diff --git a/next.config.js b/next.config.js index 7da9ccca2..5ea5ce148 100644 --- a/next.config.js +++ b/next.config.js @@ -6,7 +6,7 @@ const withNextra = require('nextra')({ module.exports = withNextra({ i18n: { - locales: ['en', 'zh', 'jp', 'pt', 'tr', 'es', 'it', 'fr', 'kr', 'ca', 'fi', 'ru','de', 'ar'], + locales: ['en', 'zh', 'tw', 'jp', 'pt', 'tr', 'es', 'it', 'fr', 'kr', 'ca', 'fi', 'ru','de', 'ar'], defaultLocale: 'en', }, webpack(config) { diff --git a/pages/_meta.tw.json b/pages/_meta.tw.json new file mode 100644 index 000000000..b1fb1e242 --- /dev/null +++ b/pages/_meta.tw.json @@ -0,0 +1,55 @@ +{ + "index": "提示詞工程", + "introduction": "簡介", + "techniques": "提示詞技巧", + "agents": "AI Agents", + "guides": "指南", + "applications": "應用", + "prompts": "Prompt Hub", + "models": "模型", + "risks": "風險與誤用", + "research": "LLM 研究", + "papers": "論文", + "tools": "工具", + "notebooks": "Notebooks", + "datasets": "資料集", + "readings": "延伸閱讀", + "courses": { + "title": "🎓 課程", + "type": "menu", + "items": { + "intro-prompt-engineering": { + "title": "提示詞工程入門", + "href": "https://dair-ai.thinkific.com/courses/introduction-prompt-engineering" + }, + "advanced-prompt-engineering": { + "title": "進階提示詞工程", + "href": "https://dair-ai.thinkific.com/courses/advanced-prompt-engineering" + }, + "intro-ai-agents": { + "title": "AI Agents 入門", + "href": "https://dair-ai.thinkific.com/courses/introduction-ai-agents" + }, + "agents-with-n8n": { + "title": "用 n8n 建構 AI Agents", + "href": "https://dair-ai.thinkific.com/courses/agents-with-n8n" + }, + "rag-systems": { + "title": "建構 RAG 系統", + "href": "https://dair-ai.thinkific.com/courses/introduction-rag" + }, + "advanced-agents": { + "title": "建構進階 AI Agents", + "href": "https://dair-ai.thinkific.com/courses/advanced-ai-agents" + }, + "all-courses": { + "title": "查看全部 →", + "href": "https://dair-ai.thinkific.com/pages/courses" + } + } + }, + "about": { + "title": "關於", + "type": "page" + } +} diff --git a/pages/about.tw.mdx b/pages/about.tw.mdx new file mode 100644 index 000000000..f844481fe --- /dev/null +++ b/pages/about.tw.mdx @@ -0,0 +1,17 @@ +# 關於 + +Prompt Engineering Guide 是由 [DAIR.AI](https://github.com/dair-ai) 發起的專案，目標是協助研究人員與實務工作者深入理解提示詞工程、脈絡工程、RAG 與 AI Agents 等主題。 + +DAIR.AI 致力於讓更多人能接近並運用 AI 研究、教育與技術。使命是啟發並幫助下一代 AI 創新者與創作者。 + +## 贊助 + +我們樂於與有意共同行動的夥伴合作，透過贊助持續維護與擴充本指南的內容。若有贊助意願，歡迎透過電子郵件 [hello@dair.ai](mailto:hello@dair.ai) 與我們聯絡。 + +## 貢獻 + +非常歡迎社群參與貢獻內容與修正。頁面上會顯示可用的編輯按鈕，方便協作。 + +授權相關資訊請見：[這裡](https://github.com/dair-ai/Prompt-Engineering-Guide#license)。 + +本指南的許多想法來自多個開放資源的啟發，例如 [OpenAI Cookbook](https://github.com/openai/openai-cookbook)、[Pretrain, Prompt, Predict](http://pretrain.nlpedia.ai/)、[Learn Prompting](https://learnprompting.org/) 等等。 diff --git a/pages/agents.tw.mdx b/pages/agents.tw.mdx new file mode 100644 index 000000000..63f5c6817 --- /dev/null +++ b/pages/agents.tw.mdx @@ -0,0 +1,12 @@ +# Agents 代理系統 + +import { Callout } from 'nextra/components' +import ContentFileNames from 'components/ContentFileNames' + +在本節中，會先從整體角度介紹以大型語言模型（LLM）為核心的代理系統（agents），說明常見的設計模式、實作要點、使用技巧，以及典型的應用情境與案例。 + + +本節內容整理自我們的新課程「[Building Effective AI Agents with n8n](https://dair-ai.thinkific.com/courses/agents-with-n8n)」，課程中提供更完整的說明、可下載的範本、提示詞範例，以及設計與實作代理系統的進階技巧。 + + + diff --git a/pages/agents/_meta.tw.json b/pages/agents/_meta.tw.json new file mode 100644 index 000000000..704e70526 --- /dev/null +++ b/pages/agents/_meta.tw.json @@ -0,0 +1,9 @@ +{ + "introduction": "AI Agents 入門", + "components": "Agent 的核心組成", + "ai-workflows-vs-ai-agents": "AI Workflows vs. AI Agents", + "context-engineering": "脈絡工程（Context Engineering）", + "context-engineering-deep-dive": "脈絡工程深入實戰：打造 Deep Research Agent", + "function-calling": "函式呼叫", + "deep-agents": "Deep Agents" +} diff --git a/pages/agents/ai-workflows-vs-ai-agents.tw.mdx b/pages/agents/ai-workflows-vs-ai-agents.tw.mdx new file mode 100644 index 000000000..6fbd201a6 --- /dev/null +++ b/pages/agents/ai-workflows-vs-ai-agents.tw.mdx @@ -0,0 +1,229 @@ +# AI Workflows vs. AI Agents + +import { Callout } from 'nextra/components' + +![AI Workflows vs. AI Agents](../../img/agents/task-planner-agent.png) + +代理式系統（agentic systems）代表了一種新的典範：如何把大型語言模型（Large Language Models, LLMs）與工具協作編排，用來完成更複雜的任務。本篇會說明 **AI workflows** 與 **AI Agents** 的核心差異，協助在 AI 應用中判斷何時該採用哪一種做法。 + + +本篇內容整理自我們的新課程 ["Building Effective AI Agents with n8n"](https://dair-ai.thinkific.com/courses/agents-with-n8n)，課程中提供更完整的洞見、可下載範本、提示詞、以及設計與實作代理式系統的進階技巧。 + + +## 什麼是代理式系統？ + +代理式系統大致可以分成兩種類型： + +### 1. AI Workflows（AI 工作流程） + +**AI workflows** 指的是：用 **事先定義好的程式路徑（predefined code paths）** 來編排 LLM 與工具的系統。整體流程會依照結構化的步驟順序執行，並具有明確的控制流（control flow）。 + +**主要特徵：** + +AI workflows 的典型特性包括： + +- 事先定義好的步驟與執行路徑 +- 可預測性高、控管容易 +- 任務邊界清楚 +- 編排邏輯明確（由程式掌握） + +**適用情境：** + +建議在這些情境優先使用 AI workflows： + +- 任務定義清楚、需求明確 +- 需要可預測性與一致性 +- 需要明確掌握執行流程 +- 正式環境（production）中可靠性至關重要 + +### 2. AI Agents + +**AI agents** 指的是：讓 LLM **動態主導自己的流程** 與工具使用方式，並在完成任務的過程中維持一定程度的自主控制（autonomous control）。 + +**主要特徵：** + +AI agents 的典型特性包括： + +- 動態決策 +- 自主選擇與使用工具 +- 具備推理與反思能力 +- 自主規劃並執行任務 + +**適用情境：** + +建議在這些情境優先使用 AI agents： + +- 任務較開放、執行路徑會隨情境改變 +- 情境複雜，事前難以明確定義步驟數量與分支 +- 需要自適應推理（adaptive reasoning） +- 彈性的重要性高於可預測性 + +## 常見的 AI 工作流程模式 + +### Pattern 1: Prompt Chaining + + + +Prompt chaining 指的是：把複雜任務拆成一連串依序執行的 LLM 呼叫，並讓每一步的輸出作為下一步的輸入。 + +**範例：文件產生工作流程** + +![Prompt Chaining](../../img/agents/prompt-chaining.png) + +這個 workflow 示範了用 prompt chaining 來產生文件的模式：當收到 chat 訊息後，系統先用 GPT-4.1-mini 產生初稿大綱，再把大綱拿去和預先定義的標準比對。接著透過人工的 "Set Grade" 步驟評估品質，再由條件式的 "If" 節點根據分數決定下一步。如果大綱符合檢核標準，就用 GPT-4o 擴寫各段落，並進一步精修與潤飾最終文件；若未符合檢核標準，workflow 會分支到 "Edit Fields" 讓人為調整後再繼續，確保多階段產出流程中能持續做品質控管。 + +**Prompt Chaining 使用情境：** +- 內容產生管線 +- 多階段文件處理 +- 逐步驗證（sequential validation）流程 + +### Pattern 2: Routing + +Routing 會先對請求做分類，並根據分類結果把不同的請求導向專門的 LLM chain 或 agent。 + +**範例：客服路由器** + +![Routing](../../img/agents/routing.png) + +這個 workflow 示範了在客服系統中如何做智慧分流：當收到 chat 訊息後，先由 Query Classifier 使用 GPT-4.1-mini 搭配 Structured Output Parser 來判斷請求類型。接著 "Route by Type" switch 會把問題導向三條專門的 LLM chain：General LLM Chain 用於一般問題、Refund LLM Chain 用於付款／退款相關、Support LLM Chain 用於技術支援。這樣既能維持統一的回覆系統，也能針對不同問題提供更適切的處理方式，進而提升客服效率與準確性。 + +**Routing 使用情境：** +- 客服系統 +- 跨領域問答 +- 請求優先排序與委派 +- 透過路由到合適模型來提升資源使用效率 + +**優點：** +- 更有效率地使用資源 +- 針對不同問題類型提供專門處理 +- 透過選擇性使用模型來控制成本 + +### Pattern 3: Parallelization + +Parallelization 會同時執行多個互相獨立的 LLM 操作，以提升效率。 + +**範例：內容安全管線** + +![Parallelization](../../img/agents/parallelization.png) + +**Parallelization 使用情境：** +- 內容審查系統 +- 多準則評估 +- 併行資料處理 +- 獨立驗證任務 + +**優勢：** +- 降低延遲 +- 更有效率地使用資源 +- 提升吞吐量 + +## AI Agents：自主任務執行 + +AI agents 結合 LLM 與自主決策能力，讓系統能透過推理、反思，以及動態工具使用來完成複雜任務。 + +**範例：任務規劃 Agent** + +**情境**：使用者詢問「明天下午 2 點加一場和 John 的會議」 + + +![Task Planning Agent](../../img/agents/task-planner-agent.png) + +這個 workflow 示範了一個自主的 Task Planner agent，展現具備動態決策能力的 agent 行為：當收到 chat 訊息後，系統會把請求導向 Task Planner agent；這個 agent 可存取三個關鍵元件：用於理解與規劃的 Chat Model（Reasoning LLM）、用於跨互動維持脈絡的 Memory 系統，以及 Tool 集合。agent 會從多個工具中自主挑選，例如 add_update_tasks（把任務新增或更新到 Google Sheets）以及 search_task（讀取與搜尋既有任務）。與事先寫死流程的 workflow 不同，agent 會根據使用者請求自行決定要用哪些工具、何時使用、以及使用順序，展現出 AI agents 相較於傳統 AI workflows 的彈性與自主性。 + + +**重點洞見**：agent 會根據請求脈絡決定要用哪些工具、以及使用順序──不是照著預先定義的規則。 + + +**AI Agent 使用情境：** + +- 深度研究系統 +- Agentic RAG 系統 +- 程式撰寫 agents +- 資料分析與處理 +- 內容產生與編修 +- 客服支援與協助 +- 互動式聊天機器人與虛擬助理 + + +**核心元件：** + +以下整理建構 AI Agents 的幾個核心元件： + +1. **Tool Access**：與外部系統整合（Google Sheets、search APIs、資料庫） +2. **Memory**：跨互動保留脈絡，維持連續性 +3. **Reasoning Engine**：用於工具選擇與任務規劃的決策邏輯 +4. **Autonomy**：不仰賴預先定義的控制流，自主完成執行 + +### Agents 與 Workflows 的差異 + +| 面向 | AI Workflows | AI Agents | +|--------|-------------|-----------| +| **控制流程** | 事先定義、明確 | 動態、自主 | +| **決策方式** | 以程式邏輯寫死 | 由 LLM 推理驅動 | +| **工具使用** | 由程式編排 | 由 agent 自行選擇 | +| **適應性** | 路徑固定 | 執行彈性 | +| **複雜度** | 較低、較可預測 | 較高、能力更強 | +| **適用情境** | 任務定義清楚 | 問題開放、探索性高 | + + +## 設計考量 + +### 如何在 Workflows 與 Agents 之間做選擇 + +**以下情況適合使用 AI Workflows：** +- 任務需求清楚且穩定 +- 可預測性是必要條件 +- 需要明確掌握執行流程 +- 除錯與監控是優先事項 +- 成本控管至關重要 + +**以下情況適合使用 AI Agents：** +- 任務開放或具探索性 +- 彈性比可預測性更重要 +- 問題空間複雜且變因很多 +- 類人推理有助於解題 +- 需要隨情境變化做調整 + +### 混合式作法 + +許多正式環境系統會同時結合兩種作法： +- **用 workflows 提供結構**：把可靠、定義清楚的元件放在 workflow +- **用 agents 提供彈性**：在需要自適應決策的地方使用 agents +- **範例**：先用 workflow 把請求路由到不同專門 agents，再由各 agent 處理開放式子任務 + +未來文章會提供一個具體範例。 + +## 最佳實務 + +### 適用於 AI Workflows + +1. **清楚定義步驟**：把 workflow 中每個階段寫清楚 +2. **錯誤處理**：為失敗情況準備 fallback path +3. **驗證關卡**：在關鍵步驟之間加入檢查 +4. **效能監控**：追蹤每一步的延遲與成功率 + +### 適用於 AI Agents + +1. **工具設計**：提供目的明確、文件清楚的工具 +2. **記憶管理**：實作有效的脈絡保留策略 +3. **防護欄**：對 agent 行為與工具使用範圍設下邊界 +4. **可觀測性**：記錄 agent 的推理與決策過程 +5. **迭代測試**：在多元情境下持續評估 agent 表現 + +未來文章會更深入討論這些主題。 + +## 結論 + +理解 AI workflows 與 AI agents 的差異，是建構有效代理式系統的關鍵。workflows 適合任務定義清楚的場景，能提供控制性與可預測性；agents 則適合複雜且開放式的問題，提供更高的彈性與自主性。 + +選擇 workflows、agents，或兩者混合，取決於具體 use case、效能需求，以及對自主決策的容忍度。只要讓系統設計與任務特性對齊，就能建構更有效率、更可靠的 AI 應用。 + + +本篇內容整理自我們的新課程 ["Building Effective AI Agents with n8n"](https://dair-ai.thinkific.com/courses/agents-with-n8n)，課程中提供更完整的洞見、可下載範本、提示詞、以及設計與實作代理式系統的進階技巧。 + + +## Additional Resources + +- [Anthropic: Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) +- [Prompt Engineering Guide](https://www.promptingguide.ai/) +- [Building Effective AI Agents with n8n](https://dair-ai.thinkific.com/courses/agents-with-n8n) diff --git a/pages/agents/components.tw.mdx b/pages/agents/components.tw.mdx new file mode 100644 index 000000000..d96371670 --- /dev/null +++ b/pages/agents/components.tw.mdx @@ -0,0 +1,55 @@ +# Agent 的核心組成 + +import { Callout } from 'nextra/components' + +要讓 AI Agent 能夠處理真正複雜的任務，通常至少需要三種能力：**規劃（planning）**、**工具使用（tool utilization）**、以及 **記憶管理（memory systems）**。以下分別說明這三個面向如何彼此配合，構成一個實用的代理系統。 + +![Agent Components](../../img/agents/agent-components.png) + +## 規劃：Agent 的「大腦」 + +一個有效的 Agent 核心是它的規劃能力，而這通常是由大型語言模型（LLM）所驅動。現代 LLM 可以在規劃上提供多種關鍵能力，例如： + +- 透過鏈式思考（chain-of-thought）進行任務分解 +- 針對過往動作與資訊進行自我反思（self-reflection） +- 根據新資訊調整策略、持續學習 +- 檢查目前進度，評估是否需要調整方向 + +雖然現階段的規劃能力還不完美，但如果沒有足夠好的 planning，Agent 就很難穩定地自動完成複雜任務，也會失去引入 Agent 的意義。 + + +若想系統化學習如何設計與實作 AI Agents，可以參考我們的課程。[立即加入！](https://dair-ai.thinkific.com/courses/introduction-ai-agents) +結帳時輸入 PROMPTING20 可享 8 折優惠。 + + +## 工具使用：延伸 Agent 的能力邊界 + +第二個關鍵組成，是 Agent 與外部工具互動的能力。設計良好的 Agent 不只需要「能接上工具」，還要**知道何時、如何使用哪些工具**。常見的工具類型包括： + +- 程式碼直譯器與執行環境 +- 網路搜尋與爬蟲工具 +- 數學計算或符號推理工具 +- 影像產生或辨識系統 + +這些工具讓 Agent 能把規劃步驟真正落實成具體行動，從抽象策略走向實際結果。 +LLM 是否能正確選擇工具、合理安排使用時機，往往決定了 Agent 在複雜任務中的上限。 + +## 記憶系統：保留與運用資訊 + +第三個不可或缺的元件是記憶管理，大致可以分成兩類： + +1. **短期（工作）記憶** + - 作為目前對話與任務的上下文緩衝區 + - 支援 in-context learning + - 對多數短期任務已經足夠 + - 幫助在多輪互動中保持連貫性 + +2. **長期記憶** + - 通常透過向量資料庫等外部系統實作 + - 能快速檢索過去的重要資訊 + - 對未來任務與長期關係管理特別有價值 + - 目前在實務上仍相對少見，但被廣泛認為會是未來的重要方向 + +良好的記憶系統讓 Agent 能把從工具或環境中取得的資訊儲存下來，重複利用，逐步累積經驗，而不是每次都從頭開始。 + +總結來說，**規劃能力、工具使用與記憶管理的協同運作**，構成了有效 AI Agent 的基礎。即使每個部分目前都有各自的限制，理解並善用這三大支柱，仍是設計與實作 Agent 架構時最重要的起點。隨著技術演進，可能會出現更多類型的記憶與推理模組，但這三個面向很可能會持續扮演核心角色。 diff --git a/pages/agents/context-engineering-deep-dive.tw.mdx b/pages/agents/context-engineering-deep-dive.tw.mdx new file mode 100644 index 000000000..25093bfd8 --- /dev/null +++ b/pages/agents/context-engineering-deep-dive.tw.mdx @@ -0,0 +1,273 @@ +# 脈絡工程深入實戰：打造 Deep Research Agent + +import { Callout } from 'nextra/components' + +[脈絡工程](https://www.promptingguide.ai/guides/context-engineering-guide) 要做好，其實需要大量迭代與細緻的設計決策。本節會以一個簡化版本的「深度研究代理（deep research agent）」為例，深入說明在實務上該如何調整 system prompt、工具說明與架構，來提升 Agent 的穩定性與效能。 + + +本節內容整理自課程「Building Effective AI Agents with n8n」，課程中有更完整的架構拆解、可下載的範本、提示詞設計與進階技巧。 + + +## 脈絡工程的現實樣貌 + +要讓 Agent 真的好用，往往得花上大量時間調整： + +- System prompt 的設計與修訂 +- 各種工具（tools）的描述與使用說明 +- Agent 與 Agent 之間的架構與溝通模式 +- 不同 Agent 之間輸入／輸出的資料格式 + +這些工作絕對不是一次性就能完成，而是一個持續迭代、對最終穩定度影響極大的過程。 + +## Agent 架構設計 + +### 初版設計遇到的問題 + +![deep-research-agent](../../img/agents/simple-dr-agent.png) + +一開始的設計是：把網頁搜尋工具直接接在 Deep Research Agent 上，讓同一個 Agent 同時負責： + +- 建立、更新與刪除任務 +- 寫入與讀取記憶 +- 執行網路搜尋 +- 產生最終報告 + +**這樣設計的後果：** + +- context 很快變得過長、難以控制 +- Agent 偶爾會忘記執行某些搜尋 +- 任務完成狀態沒有被正確更新 +- 在不同查詢下行為不穩定 + +### 改成多代理架構後的改善 + +解法是「拆解責任」：引入一個專門負責搜尋的 Worker Agent。 + +**多代理設計的好處：** + +1. **職責分離**：父層 Agent（Deep Research Agent）負責規劃與協調；搜尋 Worker Agent 專職執行網路搜尋。 +2. **可靠性提升**：每個 Agent 的職責更單純，漏掉任務或狀態更新的機率變小。 +3. **模型選擇更彈性**： + - Deep Research Agent：可以用較強的推理模型（例如 Gemini 2.5 Pro） + - Search Worker Agent：改用較輕量、便宜的模型（例如 Gemini 2.5 Flash） + +如果你使用的是 OpenAI 的模型，也可以採用類似策略，例如用 GPT-5 負責規劃與推理、用 GPT-5-mini 負責搜尋執行，以取得類似表現。 + + +**設計原則：** 把不同責任拆成不同 Agent，可以同時提升可靠性與成本效益。 + + +## System Prompt 工程 + +以下是我們在 n8n 中為 Deep Research Agent 使用的 system prompt 範例（節錄）： + +```md +You are a deep research agent who will help with planning and executing search tasks to generate a deep research report. + +## GENERAL INSTRUCTIONS + +The user will provide a query, and you will convert that query into a search plan with multiple search tasks (3 web searches). You will execute each search task and maintain the status of those searches in a spreadsheet. + +You will then generate a final deep research report for the user. + +For context, today's date is: {{ $now.format('yyyy-MM-dd') }} + +## TOOL DESCRIPTIONS + +Below are some useful instructions for how to use the available tools. +... +``` + +可以分幾個部分來看： + +### 高層角色定義 + +開頭先明確告訴模型它是什麼角色、要做什麼： + +```md +You are a deep research agent who will help with planning and executing search tasks to generate a deep research report. +``` + +### 一般流程說明（General Instructions） + +接著說清楚整體工作流程： + +```md +## GENERAL INSTRUCTIONS + +The user will provide a query, and you will convert that query into a search plan with multiple search tasks (3 web searches). You will execute each search task and maintain the status of those searches in a spreadsheet. + +You will then generate a final deep research report for the user. +``` + +### 提供必要脈絡（例如目前日期） + +對於「看最新資訊」的代理來說，目前日期很重要： + +```md +For context, today's date is: {{ $now.format('yyyy-MM-dd') }} +``` + +原因在於： + +- 大多數 LLM 的訓練資料都有時間截止點； +- 若不提供日期，Agent 在處理「最新訊息」這類查詢時容易搞混； +- 對於需要時間敏感判斷的任務（例如最近的研究、今年趨勢）尤其重要。 + +在 n8n 這類工作流程工具中，可以使用內建函式動態注入日期與時區資訊。 + +## 工具定義與使用說明 + +### 為什麼要在 prompt 裡寫工具說明？ + +工具本身的技術定義（參數、型別等）通常會寫在程式或設定中，但在 **system prompt 裡再解釋一次「何時、如何用這些工具」**，對實際行為影響往往更大。 + + +關鍵洞見：很多時候，Agent 效果最大的提升，來自於在 system prompt 裡把工具使用規則講清楚，而不是只定義好工具參數。 + + +### 工具說明範例 + +```md +## TOOL DESCRIPTIONS + +Below are some useful instructions for how to use the available tools. + +Deleting tasks: Use the delete_task tool to clear up all the tasks before starting the search plan. + +Planning tasks: You will create a plan with the search tasks (3 web searches) and add them to the Google Sheet using the append_update_task tool. Make sure to keep the status of each task updated after completing each search. Each task begins with a todo status and will be updated to a "done" status once the search worker returns information regarding the search task. + +Executing tasks: Use the Search Worker Agent tool to execute the search plan. The input to the agent are the actual search queries, word for word. + +Use the tools in the order that makes the most sense to you but be efficient. +``` + +一開始如果沒有明確規定任務狀態值，Agent 可能會自己發明： + +- 有時寫 `pending`、有時 `to-do` +- 有時 `completed`，有時 `done` 或 `finished` + +因此我們會在 prompt 裡明確限制可以使用的狀態值，避免後續流程出現不可預期狀況。 + +注意最後這句： + +```md +Use the tools in the order that makes most sense to you, but be efficient. +``` + +它刻意保留了一些彈性，讓 Agent 可以根據情況調整執行策略，例如： + +- 覺得 2 次搜尋就足夠時，可以不一定強迫做到 3 次； +- 可以在發現明顯重複時合併查詢； +- 也可以根據上下文決定是否再次搜尋。 + +如果你的應用場景需要「每個任務都必須被執行」，則可以改成比較嚴格的指令： + +```md +You MUST execute a web search for each and every search task you create. +Do NOT skip any tasks, even if they seem redundant. +``` + +開發階段通常會用較彈性的版本，觀察 Agent 的決策模式； +正式上線後則可能改成更嚴謹的規則，以確保完整性與可預測性。 + +## 脈絡工程的迭代流程 + +### 改善脈絡的迭代本質 + +實際開發過程大致會經歷以下迴圈： + +1. 以基礎的 system prompt 與工具說明實作第一版； +2. 用各種不同查詢與情境測試； +3. 找出問題（例如任務被漏掉、狀態值混亂、搜尋不完整）； +4. 在 prompt 中加入更具體的規則或範例； +5. 再次測試並比較前後行為差異； +6. 持續重複上述步驟。 + +在這個過程中，良好的觀測與紀錄機制（例如把任務與狀態寫進試算表）非常重要，否則會很難釐清問題是出在模型、工具、還是脈絡設計。 + +### 還缺什麼（What's Still Missing） + +在深度研究這類多步驟 Agent 上，還可以持續探索： + +- **搜尋任務中繼資料（Search Task Metadata）：** + - 查詢擴寫（augmenting search queries） + - 搜尋類型（web search／news search／academic search／PDF search） + - 時間區間篩選（今天、上週、近一個月、近一年、全部） + - 領域焦點（科技、科學、健康等） + - 任務執行順序的優先順序 +- **加強搜尋規劃（Enhanced Search Planning）：** + - 產生搜尋任務時的更細緻規則 + - 偏好的查詢格式 + - 拆解複雜問題的指引 + - 好／壞任務拆解示例 +- **日期區間規格（Date Range Specification）：** + - 起始日期與結束日期（time-bounded searches） + - 日期參數格式 + - 由時間關鍵詞推論日期區間的邏輯（例如 today、last week、past month） + +基於這些建議，也更能體會：要讓 AI agents 做好網頁搜尋，本身就是一個需要大量脈絡工程的挑戰。 + +脈絡工程的本質是一種「**針對真實行為不斷修正的工程實務**」，而不是一份寫完就放著不動的說明文件。只要善用觀察、調整與再測試這個迴圈，就能讓你的 Deep Research Agent 逐步變得更穩定、更可靠。 + +## 進階考量 + +### 子代理溝通 + +在設計多代理系統時，需要仔細想清楚： + +**子代理需要哪些資訊？** + +- 以搜尋 Worker 為例：通常只需要「搜尋查詢字串」 +- 不需要整包上下文或任務中繼資料 +- 盡量讓輸入保持最小、最聚焦 + +**子代理應該回傳哪些資訊？** + +- 搜尋結果與關鍵發現 +- 錯誤狀態或失敗原因 +- 關於本次執行的中繼資料（例如查詢、時間、來源等） + +### 脈絡長度管理 + +當代理開始執行多個任務時，context 往往會快速膨脹： + +- 任務歷史會累積 +- 搜尋結果會佔用大量 tokens +- 對話脈絡會持續增長 + +**管理脈絡長度的常見策略：** + +- 用不同 Agent 隔離不同脈絡 +- 引入記憶管理工具 +- 把過長輸出先摘要，再加入 context +- 每次研究查詢開始前先清空任務清單 + +### 在 System Prompt 中加入錯誤處理 + +在 system prompt 中加入失敗情境的明確規則，例如： + +```text +ERROR HANDLING: +- If search_worker fails, retry once with rephrased query +- If task cannot be completed, mark status as "failed" with reason +- If critical errors occur, notify user and request guidance +- Never proceed silently when operations fail +``` + +## 結論 + +脈絡工程是打造可靠 AI agents 的關鍵實務，通常需要： + +- 花大量時間反覆迭代 prompts 與工具說明 +- 在架構上做出審慎決策（例如 Agent 的拆分與溝通模式） +- 用明確指令消除模型的猜測空間 +- 依觀察到的真實行為持續修正 +- 在彈性與控制之間取得平衡 + +這個 deep research agent 的案例示範了：只要把角色定義、工具使用規則、必要脈絡與迭代流程設計好，就能把不穩定的原型，逐步推進成更接近可上線的系統。 + + +想用更完整的範例與範本打造可上線的 AI agents？歡迎參考我們的課程。[立即加入！](https://dair-ai.thinkific.com/courses/agents-with-n8n) +結帳時輸入優惠碼 PROMPTING20，可額外享有 8 折優惠。 + diff --git a/pages/agents/context-engineering.tw.mdx b/pages/agents/context-engineering.tw.mdx new file mode 100644 index 000000000..0e4113ade --- /dev/null +++ b/pages/agents/context-engineering.tw.mdx @@ -0,0 +1,226 @@ +# 為什麼需要脈絡工程（Context Engineering）？ + +import { Callout } from 'nextra/components' + +[脈絡工程](https://www.promptingguide.ai/guides/context-engineering-guide) 是打造穩定且可預期的 AI Agents 時，最關鍵也最容易被低估的一個實務。這篇小節會透過一個「深度研究代理（deep research agent）」的案例，說明脈絡工程在實作上的重要性與典型做法。 + +簡單說，脈絡工程就是：**刻意設計與調整促使 Agent 產生特定行為的 prompts、指令與限制條件**，讓系統更可靠地達成預期結果。 + + +本節內容整理自課程「Building Effective AI Agents with n8n」，課程會更完整地介紹架構設計、可下載範本與提示詞實作技巧。 + + +## 什麼是脈絡工程？ + +[脈絡工程](https://www.promptingguide.ai/guides/context-engineering-guide) 可以被視為一個持續迭代的過程，用來設計、測試與最佳化提供給 Agent 的所有「上下文資訊」。相較於只針對單次 LLM 呼叫寫一段 prompt，在 Agent 場景下，我們還需要一起考量： + +- **System prompt**：定義 Agent 的角色與能力邊界 +- **任務約束（task constraints）**：明確規定哪些行為是「必須」或「禁止」 +- **工具說明**：描述每個工具是做什麼的、什麼時候該用、怎麼用 +- **記憶管理**：在多步驟流程中如何維持狀態與歷史脈絡 +- **錯誤處理模式**：遇到錯誤時應該如何回報與恢復 + +## 案例：深度研究 Agent + +以下以一個會「搜尋網路並產生研究報告」的簡化代理系統為例，說明脈絡工程在實務上要處理什麼問題。 + +![Agent Workflow](../../img/agents/simple-dr-agent.png) + +### 脈絡工程的挑戰 + +#### 挑戰一：任務沒有被完整執行 + +在最初版本的實作中，我們發現： +協調者（orchestrator）Agent 會規劃出 3 個搜尋任務，但實際只幫其中 2 個跑搜尋，剩下 1 個被「悄悄略過」，也沒有任何說明。 + +**原因**：system prompt 裡沒有明確規定「每個任務一定要有交代」，Agent 便自行判斷哪些搜尋「似乎不重要」，導致行為不一致。 + +**改進方向**大致有兩種： + +1. **較彈性**：允許 Agent 不執行所有搜尋，但必須對略過的任務給出理由與標註。 +2. **較嚴格**：強制規定每一個規劃出的搜尋任務都必須被執行。 + +下面是較嚴謹的 system prompt 補強範例： + +```text +You are a deep research agent responsible for executing comprehensive research tasks. + +TASK EXECUTION RULES: +- For each search task you create, you MUST either: + 1. Execute a web search and document findings, OR + 2. Explicitly state why the search is unnecessary and mark it as completed with justification + +- Do NOT skip tasks silently or make assumptions about task redundancy +- If you determine tasks overlap, consolidate them BEFORE execution +- Update task status in the spreadsheet after each action +``` + +#### 挑戰二：缺乏可觀測性（Observability） + +在沒有良好紀錄機制的情況下，很難理解 Agent 為什麼做出某些決策，也難以針對錯誤調整 prompt。 + +**解法**：為 Agent 建立一套簡單的任務追蹤系統，例如用試算表或文字檔記錄： + +- 任務 ID +- 搜尋查詢 +- 狀態（todo / in_progress / completed） +- 結果摘要 +- 時間戳記（timestamp） + +這些資訊可以幫助我們： + +- 即時觀察 Agent 的決策與行為 +- 了解整體任務執行流程 +- 找出行為模式與常見錯誤 +- 為後續調整與實驗提供依據 + +### 脈絡工程實務準則 + +根據上述案例，可以整理出幾項常用的設計原則： + +#### 1. 消除 Prompt 中的模糊空間 + +**不佳示例：** +```text +Perform research on the given topic. +``` + +**較佳寫法：** +```text +Perform research on the given topic by: +1. Breaking down the query into 3-5 specific search subtasks +2. Executing a web search for EACH subtask using the search_tool +3. Documenting findings for each search in the task tracker +4. Synthesizing all findings into a comprehensive report +``` + +#### 2. 明確寫出預期 + +不要假設 Agent「知道你要什麼」。 +盡量在指令中講清楚： + +- 哪些行為是必做、哪些是可選 +- 輸出品質標準與格式要求 +- 決策準則與優先順序 + +#### 3. 建立可觀測性 + +在 Agent 系統裡加入 Debug 友善的設計： + +- 記錄每次決策與推理摘要 +- 把狀態變化寫到外部儲存（例如試算表或資料庫） +- 紀錄工具呼叫與結果 +- 捕捉錯誤與邊界情況，當作後續調整的素材 + + +每一次「奇怪的行為」或錯誤案例，都是改進脈絡工程的線索。 + + +#### 4. 依實際行為迭代 + +脈絡工程本質上是一個閉環： + +1. 先用初版 context 上線 +2. 觀察實際行為與產出 +3. 找出與預期不符的地方 +4. 調整 system prompt、約束條件與工具說明 +5. 再次測試與驗證 +6. 重複上述步驟 + +#### 5. 在「彈性」與「約束」間找到平衡 + +過度嚴格的規則會讓 Agent 缺乏彈性、難以處理邊界情況； +過度寬鬆又會讓行為變得不可預測。 + +實務上可以先從較彈性版本開始，觀察 Agent 行為，再逐步加入必要的約束條件。 + +## 進階脈絡工程技巧概覽 + +這裡列出幾個進階議題，細節可參考脈絡工程專章： + +### 分層脈絡架構 + +將 context 拆成 System / Task / Tool / Memory 等層級分別設計。 + +### 動態調整脈絡 + +根據任務複雜度、資源狀況、歷史錯誤紀錄來動態增減指令與輔助資訊。 + +### 脈絡檢驗（Context Validation） + +評估是確保脈絡工程技巧能如預期運作的關鍵。在上線前，請驗證脈絡設計： + +- **完整性**：是否涵蓋所有重要情境？ +- **清楚度**：是否沒有歧義？ +- **一致性**：不同部分是否彼此一致？ +- **可測試性**：是否能驗證其行為？ + +## 常見脈絡工程地雷 + +### 1. 約束過頭 + +**問題：** 規則太多、太死，導致 Agent 無法處理邊界情況。 + +**範例：** +```text +NEVER skip a search task. +ALWAYS perform exactly 3 searches. +NEVER combine similar queries. +``` + +**較佳做法：** +```text +Aim to perform searches for all planned tasks. If you determine that tasks are redundant, consolidate them before execution and document your reasoning. +``` + +### 2. 指令過於籠統 + +**問題：** 指令含糊會導致行為不可預測。 + +**範例：** +```text +Do some research and create a report. +``` + +**較佳做法：** +```text +Execute research by: +1. Analyzing the user query to identify key information needs +2. Creating 3-5 specific search tasks covering different aspects +3. Executing searches using the search_tool for each task +4. Synthesizing findings into a structured report with sections for: + - Executive summary + - Key findings per search task + - Conclusions and insights +``` + +### 3. 未定義錯誤處理 + +**問題：** 沒有告訴 Agent 出錯時要怎麼做，就很難期待它在錯誤情況下能保持穩定。 +**解法：** 在某些情況下，為 AI Agent 加上錯誤處理指令會有幫助，例如： + +```text +ERROR HANDLING: +- If a search fails, retry once with a rephrased query +- If retry fails, document the failure and continue with remaining tasks +- If more than 50% of searches fail, alert the user and request guidance +- Never stop execution completely without user notification +``` + +## 如何衡量脈絡工程是否有效？ + +可以追蹤以下幾個指標來評估： + +1. **任務完成率**：有多少任務被完整、正確地完成 +2. **行為一致性**：在相似輸入下行為是否穩定 +3. **錯誤比例**：失敗與非預期行為出現的頻率 +4. **使用者滿意度**：輸出是否實際有用 +5. **除錯成本**：定位與修正問題需要花多少時間 + +脈絡工程不應被視為一次性工作，而是一個持續迭代的工程實務。 +透過系統化觀察、分析失敗案例、調整指令與限制，再搭配嚴謹測試，就能逐步打造出穩定、可預測且真正有用的 Agent 系統。 + + +若想進一步學習如何將這些原則落實到生產環境中的代理系統，歡迎參考我們的課程。[立即加入！](https://dair-ai.thinkific.com/courses/agents-with-n8n) +結帳時輸入 PROMPTING20 可享 8 折優惠。 + diff --git a/pages/agents/deep-agents.tw.mdx b/pages/agents/deep-agents.tw.mdx new file mode 100644 index 000000000..cb95a01fc --- /dev/null +++ b/pages/agents/deep-agents.tw.mdx @@ -0,0 +1,121 @@ +# Deep Agents + +import { Callout } from 'nextra/components' + +現在多數所謂的「Agent」，其實都還很淺（shallow）。 + +一旦面對真正長鏈、多步驟的問題（例如深度研究、具結構的代理寫碼流程），就很容易當機。 + +這件事正在快速改變。 + +我們正逐漸進入 **Deep Agents** 的時代：這類系統會更有策略地規劃、記憶與委派子任務，目標是處理非常複雜的問題。 + +包括 [DAIR.AI Academy's](https://dair-ai.thinkific.com/)、[LangChain](https://docs.langchain.com/labs/deep-agents/overview)、[Claude Code](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk)，以及像 [Philipp Schmid](https://www.philschmid.de/agents-2.0-deep-agents) 等開發者，都在持續整理與實驗這個概念。 + +下圖是我們為 [DAIR.AI Academy's](https://dair-ai.thinkific.com/) 學員設計的深度 Agent，用來支援課程相關的客服與問答： + +![deep-agent](../../img/agents/customer-support-deep-agent.png) + + +本篇內容延伸自課程「Building Effective AI Agents with n8n」，課程中會更全面介紹 Deep Agents 的設計原則、樣板與提示詞實作細節。 + + +以下是我自己整理、並綜合他人觀點後歸納出的 Deep Agents 核心概念。 + +## 規劃（Planning） + +![cs-planning](../../img/agents/cs-planning.png) + +Deep Agent 不再只是在單一 context window 裡「臨場發揮」，而是維護一份**可更新、可重試、可恢復**的結構化任務規劃。你可以把它想成一份持續變動的待辦清單，引導 Agent 朝長期目標前進。 + +只要試著在 Claude Code 或類似工具裡開啟「先規劃再執行」的模式，就能感受到差異：在長任務上效果好非常多。 + +我們也曾示範過如何透過延長「腦力激盪時間」來提升結果品質，這其實就是在強化規劃、專家脈絡與人類在環（human-in-the-loop）合作。對於像科學發現這類長期、開放式問題，規劃能力會更加關鍵。 + +## Orchestrator 與 Sub-agent 架構 + +![cs-subagents](../../img/agents/cs-subagents.png) + +只靠一個超長 context 的大 Agent 已經不太夠用。 +雖然也有人主張應該避免多代理、改用單一巨型系統（例如這篇 [Don't build multi-agents](https://cognition.ai/blog/dont-build-multi-agents)），但我對這種做法持保留態度。 + +在實務上，「**協調者（orchestrator）＋多個專精子 Agent**」是一種非常強大的架構： + +- 協調者負責理解任務、規劃步驟與委派 +- 子 Agent 則聚焦於各自領域（搜尋、寫碼、知識庫檢索、分析、驗證、撰寫…） +- 每個子 Agent 擁有乾淨、聚焦的脈絡，有利於管理 context 與行為一致性 + +Claude Code 將這種作法在寫碼場景裡發揚光大；實務上也證明，透過職責分離來管理 context，是目前最有效率的方式之一。 + +我也曾經在 X 上分享過幾篇關於 orchestrator + sub-agents 架構的實作筆記與心得：[筆記一](https://x.com/omarsar0/status/1960877597191245974)、[筆記二](https://x.com/omarsar0/status/1971975884077965783)。 + +## Context Retrieval 與 Agentic Search + +![persistent-storage](../../img/agents/cs-persistent-storage.png) + +Deep Agents 不會只靠對話歷史撐全場。 +它們會把中間產物存放在外部記憶中（檔案、筆記、向量資料庫或其他形式），需要時再有選擇地取用，避免把所有細節都塞進同一個 context。 + +近期像 [ReasoningBank](https://arxiv.org/abs/2509.25140) 與 [Agentic Context Engineering](https://arxiv.org/abs/2510.04618) 之類的研究，都在探討如何設計更好的「推理記憶」與檢索策略。 + +在 orchestrator＋sub-agents 架構下，常見的做法是採用混合記憶： + +- 結合 traditional semantic search 與 agentic search +- 允許 Agent 自己選擇要用哪種檢索策略 + +## 脈絡工程（Context Engineering） + +對這類系統來說，「說不清楚要做什麼」幾乎是最糟糕的情況。 +Prompt 工程依然重要，但我們更希望用 **context engineering（脈絡工程）** 來強調對整體上下文與流程的設計。 + +好的脈絡工程會明確定義： + +- 什麼時候要進行規劃、什麼時候直接執行 +- 什麼情況要交給哪一個 sub-agent +- 檔案與中間產物應如何命名與整理 +- 要如何與人類協同（例如何時詢問使用者確認） + +其中也包含： + +- 結構化輸出（structured outputs）的設計 +- system prompt 的最佳化與壓縮 +- 對 context 效果的評估與修改 +- 工具定義與使用說明的持續調整（可參考 [Writing Tools for Agents](https://www.anthropic.com/engineering/writing-tools-for-agents)） + +更多內容可以參考我們在指南中的脈絡工程專章：[Context Engineering Deep Dive](https://www.promptingguide.ai/guides/context-engineering-guide)。 + +## 驗證（Verification） + +![verification agent](../../img/agents/cs-verification-agent.png) + +在 Deep Agents 中，「驗證」跟脈絡工程一樣重要，但往往被談得比較少。 +驗證的核心是：**檢查輸出是否可信**，可以由 LLM 擔任評審（LLM-as-a-Judge），也可以交給人類，或兩者搭配。 + +現代 LLM 在許多工（特別是數學與寫碼）上表現已經非常強，但仍然存在： + +- 幻覺（hallucination） +- 迎合型回應（sycophancy） +- prompt injection +- 以及其他安全與穩定性問題 + +匯入驗證步驟可以讓 Agent 更接近「可上線使用」的水準，而不只是 demo。 +你可以透過系統化評估流程（eval pipelines）來建立專門的 verifier Agent。 + +## 結語 + +Deep Agents 代表的是一種**建構 AI 系統方式的質變**： +從單一模型一次性輸出，走向有規劃、有記憶、有分工與驗證的多階段流程。 + +這類 Agent 也很可能會成為「個人化、主動型代理」的基礎積木： +未來的代理不只是回應指令，而是能在背景中主動幫你完成一連串任務。 + +如果你想實際動手打造這樣的 Deep Agent，可以參考我們在 DAIR.AI Academy 的課程： +https://dair-ai.thinkific.com/courses/agents-with-n8n + +文中圖例則出自課程的期末專案：學生需要設計並實作一個具 Agentic RAG 能力的系統。 + + +本篇內容延伸自課程「Building Effective AI Agents with n8n」，課程中有更多圖示、範例、提示詞樣板與實作技巧，幫助你一步步建構自己的 Deep Agents。 + + +*撰寫：Elvis Saravia（Prompt Engineering Guide 作者、DAIR.AI Academy 共同創辦人）* diff --git a/pages/agents/function-calling.tw.mdx b/pages/agents/function-calling.tw.mdx new file mode 100644 index 000000000..e9549410c --- /dev/null +++ b/pages/agents/function-calling.tw.mdx @@ -0,0 +1,223 @@ +# AI Agents 的函式呼叫（Function Calling） + +import { Callout } from 'nextra/components' + +函式呼叫（也稱為 tool calling）是現代以 LLM 為核心的代理系統的關鍵能力之一。理解函式呼叫在背後如何運作，是打造有效的 AI Agents、並在出問題時進行除錯的基礎。 + +## 主題 + +- [什麼是函式呼叫？](#什麼是函式呼叫) +- [函式呼叫如何驅動 AI Agents](#函式呼叫如何驅動-ai-agents) +- [工具定義的角色](#工具定義的角色) +- [Agent 迴圈：行動與觀察](#agent-迴圈行動與觀察) +- [函式呼叫除錯](#函式呼叫除錯) +- [工具定義的最佳實務](#工具定義的最佳實務) + +## 什麼是函式呼叫？ + +本質上，函式呼叫讓 LLM 可以與外部工具、API 與知識庫互動。當 LLM 接到需要超出訓練資料範圍的資訊或動作時，它可以決定呼叫外部函式來取得資訊或執行動作。 + +例如，如果你問 AI Agent：「巴黎現在的天氣如何？」LLM 單靠自己無法正確回答，因為它沒有即時天氣資料。但透過函式呼叫，LLM 會判斷需要呼叫天氣 API，產生帶有正確參數（此例為城市「巴黎」）的函式呼叫，再用回傳資料產生回應。 + +這項能力讓原本只是文字產生器的 LLM，變成能與真實世界互動的強大代理。 + +## 函式呼叫如何驅動 AI Agents + +![Function Calling Flow](../../img/agents/function-calling-flow.png) + +以 LLM 為核心的代理系統，通常仰賴兩個能力來解決複雜任務：工具呼叫與推理。這讓 Agents 可以整合外部工具、連接 MCP（Model Context Protocol）伺服器，並存取知識庫。 + +函式呼叫流程如下： + +1. **使用者提問**：使用者向 Agent 提出需求（例如「巴黎現在的天氣如何？」） + +2. **脈絡組裝**：system 訊息、工具定義、使用者訊息被組合成送給模型的完整脈絡 + +3. **工具決策**：LLM 分析脈絡並判斷是否需要呼叫工具；若需要，會輸出結構化回應，指示要呼叫哪個工具與使用的參數 + +4. **工具執行**：開發者的程式收到工具呼叫需求後，執行實際函式（例如呼叫天氣 API） + +5. **觀察**：工具回傳結果，成為代理術語中的 observation + +6. **回應產生**：觀察結果與先前所有訊息一起回傳給模型，讓它產生最終回應 + +這裡的關鍵在於：模型始終保有完整脈絡，清楚知道對話中發生過的一切。這種脈絡意識讓 Agent 能做出更好的後續決策，並正確將工具結果整合進最後的回應。 + +## 工具定義的角色 + +工具定義可以說是函式呼叫最關鍵的元件。它們是 LLM 唯一知道有哪些工具、何時該使用的資訊來源。 + +一個工具定義通常包含： + +- **名稱**：函式的清楚識別名稱 +- **描述**：說明工具做什麼、什麼情境該用 +- **參數**：函式可接受的輸入內容，包括型別與說明 + +以下是天氣工具定義範例： + +```python +tools = [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location. Use this when the user asks about weather conditions in a specific city or region.", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"], + "description": "The temperature unit to use" + } + }, + "required": ["location"] + } + } + } +] +``` + +描述欄位特別重要。它不只告訴模型工具的用途，也會告訴模型什麼時候該用。當你提供多個工具時，清楚而具體的描述會變得更關鍵，才能幫模型做出正確的工具選擇。 + + +工具定義會在每次 LLM 呼叫時成為脈絡的一部分，因此會佔用 token，並影響成本與延遲。工具定義要簡潔，但也要足夠具體。 + + +## Agent 迴圈：行動與觀察 + +理解 Agent 迴圈是除錯與最佳化代理系統的基礎。迴圈由以下步驟反覆組成： + +1. **行動**：Agent 決定採取行動（呼叫工具） +2. **環境回應**：外部工具或 API 回傳結果 +3. **觀察**：Agent 接收並處理結果 +4. **決策**：Agent 判斷是否需要下一次行動，或直接回應使用者 + +來看一個具體例子。當你對 Agent 說「OpenAI 最新消息」，流程可能會是： + +``` +使用者：「OpenAI 最新消息」 + +Agent 想：我需要 OpenAI 的最新資訊。 + 我應該使用 web_search 工具。 + +行動：web_search(query="OpenAI latest news announcements") + +觀察：[近期 OpenAI 文章的搜尋結果...] + +Agent 想：我已經有回答所需的資訊。 + 我來整理給使用者。 + +回應：「以下是 OpenAI 的最新更新...」 +``` + +觀察就是環境（例如搜尋引擎或 API）在 Agent 執行行動後回傳的內容。這份觀察會變成下一輪的脈絡，讓 Agent 建立在既有結果上再做決策。 + +在更複雜的情境裡，Agent 可能需要多次呼叫工具才能回答問題。每一次呼叫都會累積脈絡，讓 Agent 根據已掌握的資訊決定下一步該做什麼。 + +## 函式呼叫除錯 + +在打造 AI Agents 時，一定會遇到「行為不如預期」的情況：可能選錯工具、參數給錯，或該呼叫卻沒呼叫。此時理解函式呼叫的內部運作就非常關鍵。 + +在像 n8n 這類工作流程自動化工具中，你可以開啟「Return Intermediate Steps」，來查看背後發生的細節，包括： + +- **哪些工具被呼叫**：工具呼叫的順序 +- **傳入的參數**：每個工具實際收到的參數 +- **回傳的觀察**：每個工具回傳了什麼 +- **Token 使用量**：每一步消耗的 token 數量 + +以下是一個研究查詢的中繼步驟範例： + +```json +{ + "intermediateSteps": [ + { + "action": { + "tool": "web_search", + "toolInput": { + "query": "OpenAI latest announcements 2025" + } + }, + "observation": "1. OpenAI announces new reasoning model... 2. GPT-5 rumors surface..." + }, + { + "action": { + "tool": "update_task_status", + "toolInput": { + "taskId": "search_1", + "status": "completed" + } + }, + "observation": "Task updated successfully" + } + ] +} +``` + +這種視覺化對除錯很關鍵。如果 Agent 產出錯誤結果，可以逐步檢查每一步，找出問題發生的位置。常見問題包括： + +- **工具選擇錯誤**：模型選了不該用的工具 +- **參數錯誤**：參數不完整或內容不正確 +- **脈絡不足**：工具定義提供的指引不夠 +- **觀察處理錯誤**：模型誤解了工具回傳內容 + + +有些平台因抽象層的關係，可能不會完整暴露 prompt 脈絡。除錯時，盡量靠近原始 API 呼叫，才能清楚知道模型實際收到的脈絡。 + + +## 工具定義的最佳實務 + +以下是打造代理系統時最實用的工具定義建議： + +**描述要具體** + +不要寫「搜尋網路」，可以改成：「搜尋網路上的最新資訊。當使用者詢問近期事件、新聞或訓練後可能變動的資料時使用。」 + +**在 system prompt 補上使用情境** + +工具定義裡雖然有描述，但在 system prompt 中再補上何時、如何使用工具的明確指引，會讓 LLM 做出更好的判斷，特別是工具數量較多時。 + +``` +You have access to the following tools: +- web_search: Use this for any questions about current events or recent information +- calculator: Use this for mathematical calculations +- knowledge_base: Use this to search internal documentation + +Always prefer the knowledge_base for company-specific questions before using web_search. +``` + +**明確定義參數限制** + +盡可能使用 enum 約束參數值，並在描述中給範例，幫助模型更清楚理解可用的值。 + +```python +"unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"], + "description": "Temperature unit. Use 'celsius' for most countries, 'fahrenheit' for US." +} +``` + +**妥善處理工具失敗情況** + +工具應該回傳清楚的錯誤訊息，協助 Agent 復原或改用替代方案。 + +```python +def search_database(query: str) -> str: + results = db.search(query) + if not results: + return "No results found for this query. Try broadening your search terms or using alternative keywords." + return format_results(results) +``` + + +本內容整理自我們的課程 ["Building Effective AI Agents with n8n"](https://dair-ai.thinkific.com/courses/agents-with-n8n)，課程中提供實戰操作代理系統與除錯的完整經驗。 + +使用優惠碼 PROMPTING20 可再折 20%。 + + +函式呼叫是連結 LLM 推理與真實世界行動的橋梁。透過理解工具定義如何影響模型決策、Agent 迴圈如何處理行動與觀察，以及整體流程的除錯方式，你就能打造出更穩健的 AI Agents，並有效運用外部工具解決複雜問題。 diff --git a/pages/agents/introduction.tw.mdx b/pages/agents/introduction.tw.mdx new file mode 100644 index 000000000..29311c599 --- /dev/null +++ b/pages/agents/introduction.tw.mdx @@ -0,0 +1,57 @@ +# AI Agents 入門 + +import { Callout } from 'nextra/components' + +AI Agent 正在改變處理複雜任務的方式，善用大型語言模型（LLM）的力量，代為完成工作並產生令人驚豔的成果。本篇會帶你快速認識 AI Agents 的基本概念、核心能力、常見設計模式與應用場景。 + +## 什麼是 Agent？ + +![Agent Components](../../img/agents/agent-components.png) + +在這裡，Agent 指的是一種由 LLM 驅動、能主動採取行動並自主解決複雜任務的系統。相比只做單次文字輸出的一般 LLM，AI Agent 具備更多額外能力，包括： + +* **規劃與反思：** Agent 能分析問題、拆解步驟，並依照新增的資訊動態調整策略。 +* **使用工具：** 能呼叫外部工具與資源，例如資料庫、API、各種軟體服務，來蒐集資訊或執行動作。 +* **記憶：** 能儲存與提取過往資訊，累積經驗，做出更符合情境的決策。 + +這篇文章就聚焦在這種 AI Agent 的概念，以及它在人工智慧發展中的重要性。 + +## 為什麼要打造 Agent？ + +大型語言模型在「單一步驟、定義清楚」的任務上表現很好，例如翻譯、撰寫電子郵件等。但只要任務變得複雜、牽涉多個步驟、需要規劃與推理，就會開始碰到瓶頸。這些情境往往還需要查詢外部資料，而不是只靠模型內建知識。 + +比方說，要規劃一套行銷策略，可能涉及： + +* 研究競品與市場趨勢 +* 分析不同通路的成效 +* 讀取公司內部歷史資料 + +這些都仰賴最新、真實世界的資訊與公司內部資料，一個單純的 LLM 很難在沒有外部工具的情況下完成。 + +AI Agent 透過結合 LLM、記憶模組、規劃能力與工具使用，補上了這塊缺口。 + +善用這些能力，Agent 可以處理各種複雜任務，例如： + +* 擬定完整行銷策略 +* 規劃活動與專案排程 +* 提供具上下文的客戶支援 + + +想學習如何實作 AI Agents？歡迎參考我們的新課程。 [立刻報名！](https://dair-ai.thinkific.com/courses/introduction-ai-agents) +結帳時輸入折扣碼 PROMPTING20 可再享 8 折優惠。 + + +## AI Agents 的常見應用 + +以下是幾個實務上常見的 Agent 應用場景（非完整清單）： + +* **推薦系統：** 提供個人化產品、服務或內容建議。 +* **客服系統：** 處理詢問、協助排除問題、提供即時說明。 +* **研究與調查：** 協助在法律、金融、健康等不同領域做深入研究。 +* **電商應用：** 協助線上購物情境、訂單處理與個人化推薦。 +* **訂位與預約：** 幫忙規劃旅遊、活動與各式預約流程。 +* **報表與分析：** 消化大量資料並產出統整報告。 +* **財務分析：** 分析市場趨勢、閱讀財務資料，並產出分析結果。 + +隨著工具生態與模型能力持續演進，這類 Agent 型應用的範圍也只會持續擴大。 + diff --git a/pages/applications.tw.mdx b/pages/applications.tw.mdx new file mode 100644 index 000000000..400fa08f2 --- /dev/null +++ b/pages/applications.tw.mdx @@ -0,0 +1,8 @@ +# 提示詞應用 + +import { Callout } from 'nextra-theme-docs' +import ContentFileNames from 'components/ContentFileNames' + +在本章節中，將介紹幾種進階又有趣的方式，示範如何運用提示詞工程，讓大型語言模型（LLM）完成各種實用且更複雜的任務。 + + diff --git a/pages/applications/_meta.tw.json b/pages/applications/_meta.tw.json new file mode 100644 index 000000000..06560ab99 --- /dev/null +++ b/pages/applications/_meta.tw.json @@ -0,0 +1,11 @@ +{ + "finetuning-gpt4o": "使用 GPT-4o 進行微調（Fine-Tuning）", + "function_calling": "使用 LLM 進行 Function Calling", + "context-caching": "使用 Gemini 1.5 Flash 的 Context Caching", + "generating": "產生資料", + "synthetic_rag": "為 RAG 產生合成資料集", + "generating_textbooks": "應對合成資料集的多樣性問題", + "coding": "產生程式碼", + "workplace_casestudy": "應屆畢業生職務分類案例研究", + "pf": "提示詞函式" +} diff --git a/pages/applications/coding.tw.mdx b/pages/applications/coding.tw.mdx new file mode 100644 index 000000000..9487bf6bd --- /dev/null +++ b/pages/applications/coding.tw.mdx @@ -0,0 +1,196 @@ +# 產生程式碼 + +import { Callout, FileTree } from 'nextra-theme-docs' +import {Screenshot} from 'components/screenshot' +import CODE1 from '../../img/code-generation/chat-mode.png' + + + 本章節正在準備中。 + + +像 ChatGPT 這種大型語言模型在程式碼產生方面非常有效。在本節中，我們將介紹許多如何使用 ChatGPT 進行程式碼產生的範例。 + +以下所有範例都使用 OpenAI 的 Playground（聊天模式）和`gpt-3.5-turbo`模型。 + +與 OpenAI 的所有聊天模型一樣，您可以使用`系統訊息`來定義回應的行為和格式。我們將使用以下系統訊息作為提示詞範例： + +``` +您是一位有用的程式碼助手，可以教初級開發人員如何編寫程式碼。您選擇的語言是Python。不解釋程式碼，只產生程式碼區塊本身。 +``` + +## 基本範例 + +`使用者訊息`將是提示詞本身，其中包含了您希望模型產生的特定程式碼的指令。以下是程式碼產生的第一個基本提示詞快照。請注意，最終程式碼是由`助手`產生的。 + + + +如果您想自己試試，這是一些提示詞： + +``` +寫一段程式碼詢問使用者他們的名字並說Hello +``` + +## 將註解轉換成程式碼 + +您也可以使用這些大型語言模型的程式碼產生能力將註解轉換成程式碼。讓我們看另一個將指令作為註解區塊傳遞的範例： + +*提示詞：* +``` +""" +1. 建立一個電影名稱列表 +2. 建立這些電影的評分列表 +3. 將它們組合並建立一個包含10部電影及其評分的json物件 +""" +``` + +*輸出：* +```python +movies = ["The Shawshank Redemption", "The Godfather", "The Dark Knight", "Schindler's List", "Pulp Fiction", "The Lord of the Rings: The Return of the King", "Forrest Gump", "Star Wars: Episode V - The Empire Strikes Back", "Inception", "The Silence of the Lambs"] + +ratings = [9.3, 9.2, 9.0, 8.9, 8.9, 8.9, 8.8, 8.7, 8.7, 8.6] + +movie_ratings = {} + +for i in range(len(movies)): + movie_ratings[movies[i]] = ratings[i] + +json_object = json.dumps(movie_ratings, indent=4) + +print(json_object) +``` + +產生的程式碼看起來像是可以正常執行的程式碼。然而，輸出的程式碼不包含重要的`import`語句，即：`import json`。當這些模型產生可執行的程式碼時，您必須注意這樣的小細節，並始終確保測試您的程式碼。 + +## 完成函式或下一行 + +這些大型語言模型也被整合到像是 GitHub Copilot 等工具中，這使得它們對開發人員非常有用。其中一個有用的功能是模型能夠完成函式。 + +*提示詞：* +```python +# 將兩個數字相乘並加 75 的函式 + +def multiply( +``` + +*輸出：* +```python +a, b): + result = a * b + result += 75 + return result +``` + +## MySQL 查詢語句產生 + +除了上面的基本程式碼產生範例外，您還可以使用該模型產生其他有用的程式碼，例如建立和測試 MySQL 查詢。 + +假設您有一個資料集，其中包含一些資訊，您可以將其作為提示詞的一部分，然後指示它產生特定查詢。例如： + +``` +""" +Table departments, columns = [DepartmentId, DepartmentName] +Table students, columns = [DepartmentId, StudentId, StudentName] +Create a MySQL query for all students in the Computer Science department +""" +``` + +*輸出：* +```mysql +SELECT students.StudentId, students.StudentName +FROM students +INNER JOIN departments +ON students.DepartmentId = departments.DepartmentId +WHERE departments.DepartmentName = 'Computer Science'; +``` + +模型產生了一個查詢語句！然而，我們沒有對應的資料庫來測試產生的查詢語句是否正確。如果要測試，則需要建立這個資料庫。幸運的是，您可以使用 ChatGPT 為您產生此內容。例如使用上述提示詞的修改版本，其指令略有不同，以產生資料庫結構： + +```mysql +Table departments, columns = [DepartmentId, DepartmentName] +Table students, columns = [DepartmentId, StudentId, StudentName] +Create a valid database schema with the above tables and columns +``` + +模型產生了以下的資料表建立語句： + +```mysql +CREATE TABLE departments ( + DepartmentId INT PRIMARY KEY, + DepartmentName VARCHAR(50) +); + +CREATE TABLE students ( + DepartmentId INT, + StudentId INT PRIMARY KEY, + StudentName VARCHAR(50), + FOREIGN KEY (DepartmentId) REFERENCES departments(DepartmentId) +); +``` + +您也可以建立一個臨時的資料庫，使用類似[sqliteonline.com](https://sqliteonline.com/)。 + +您還需要虛擬資料來測試產生的查詢是否有效。讓我們也使用 ChatGPT！提示詞語句類似下例： + +```mysql +CREATE TABLE departments ( + DepartmentId INT PRIMARY KEY, + DepartmentName VARCHAR(50) +); + +CREATE TABLE students ( + DepartmentId INT, + StudentId INT PRIMARY KEY, + StudentName VARCHAR(50), + FOREIGN KEY (DepartmentId) REFERENCES departments(DepartmentId) +); + +給定上面的資料表結構，產生有效的插入語句，每個表包含4行： +``` + +帶有插入語句的輸出： + +```mysql +INSERT INTO departments (DepartmentId, DepartmentName) +VALUES (1, 'Computer Science'), (2, 'Mathematics'), (3, 'Physics'), (4, 'Biology'); + +INSERT INTO students (DepartmentId, StudentId, StudentName) +VALUES (1, 101, 'John Doe'), (1, 102, 'Jane Doe'), (2, 201, 'Alice Smith'), (2, 202, 'Bob Johnson'); +``` + +現在您已經有了資料庫和虛擬資料，可以測試原始查詢了。根據虛擬資料，結果應該是兩行，分別包含`Jane Doe`和`John Doe`。 + +## 解釋程式碼 +如果您正在學習使用某種語言程式設計，用提示詞請模型解釋某些程式碼位可能會很有用。讓我們重用上面產生的查詢，並要求模型對其進行解釋。 + +如果您使用的是與之前相同的`系統訊息`，請注意如何指導模型。例如，如果我們使用以下範例，模型會抱怨它是 Python 中的程式碼助手，但它仍然提供瞭解釋。有時，模型拒絕產生您指示的內容，因為它用來遵循系統訊息。 + +*提示詞：* + +```mysql +SELECT students.StudentId, students.StudentName +FROM students +INNER JOIN departments +ON students.DepartmentId = departments.DepartmentId +WHERE departments.DepartmentName = 'Computer Science'; + +解釋上面的SQL語句。 +``` + +*輸出：* + +``` +對不起，作為一個Python程式碼助手，我不能產生SQL語句。但是，我能解釋您提供的SQL語句的含義。 + +這個SQL語句從`students`表選擇了`StudentId`和`StudentName`欄位，其中`departments`表中的`DepartmentName`欄位等於'Computer Science'。為了實現這一效果，語句使用一個內部連接關鍵字在`DepartmentId`欄位和`students`和`departments`表。 + +簡單來說，語句選擇了電腦科學系註冊的學生的姓名和ID。 +``` + +## 編輯程式碼 +範例即將推出！ + +## 除錯程式碼 +範例即將推出！ + +## 最佳實踐 +即將推出！ diff --git a/pages/applications/context-caching.tw.mdx b/pages/applications/context-caching.tw.mdx new file mode 100644 index 000000000..586856b60 --- /dev/null +++ b/pages/applications/context-caching.tw.mdx @@ -0,0 +1,58 @@ +# 使用 Gemini 1.5 Flash 的 Context Caching + +import {Cards, Card, Callout} from 'nextra-theme-docs' +import {CodeIcon} from 'components/icons' + +Google 最近在 Gemini API 中推出了一項新功能：[context-caching](https://ai.google.dev/gemini-api/docs/caching?lang=python)，目前可搭配 Gemini 1.5 Pro 與 Gemini 1.5 Flash 使用。本指南示範如何在 Gemini 1.5 Flash 上運用 context caching。 + +