[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M69A1VPZFJQ1HNGTZQ5P3WSC":3,"skill-same:01M69A1VPZFJQ1HNGTZQ5P3WSC":49},{"skillNo":4,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":20,"linkOnly":21,"markdownContent":22,"markdownBody":23,"frontMatter":24,"refName":25,"commitSha":26,"skillDirectory":27,"forksCount":28,"repositoryHtmlUrl":29,"repositoryHomepageUrl":30,"ownerHtmlUrl":31,"ownerBlogUrl":32,"ownerDescription":33,"updatedAt":34,"install":35,"resources":48},"01M69A1VPZFJQ1HNGTZQ5P3WSC","local-ai-agents",null,"microsoft\u002Fai-agents-for-beginners","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M6998ZK2275KMJE6Y5SEA2X2",79567,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners\u002Fblob\u002Fmain\u002Ftranslations\u002Fzh-TW\u002F.agents\u002Fskills\u002Flocal-ai-agents\u002FSKILL.md",[],[18,19],"ai agents","local ai agents","2026-11-10 10:12:30",false,"---\nname: local-ai-agents\nlicense: MIT\n---\n# 使用 Foundry Local 和 Qwen 建立本地 AI 代理\n\n> 伴隨 [Lesson 17 – Creating Local AI Agents](..\u002F..\u002F..\u002F17-creating-local-ai-agents\u002FREADME.md) 的輔助技能。\n> 用於協助學習者打造一個能獨立在自己機器上推理、調用工具及搜尋文件的代理 — 完全無雲端推理。所有建議都基於課程內容與可執行筆記本。\n> \n> \n\n## 觸發條件\n\n當學習者希望：\n- 完全在設備端執行代理，為了隱私、成本或離線需求。\n- 使用 **Foundry Local** 本地部署模型，並透過 OpenAI 兼容端點連接。\n- 使用 **Qwen 函數呼叫** 模型來驅動可靠的本地工具調用。\n- 新增 **本地 RAG**（Chroma）或 **本地 MCP 伺服器**。\n- 設計一個 \u003Cstrong>混合\u003C\u002Fstrong> 本地\u002F雲端路由策略。\n\n## 核心心智模型\n\nSLM 以隱私、成本與離線操作換取廣度。致勝策略是：**讓 SLM 負責協調，讓工具執行繁重任務。** 模型不需要\u003Cem>了解\u003C\u002Fem>整個程式碼庫，只需知道何時呼叫 `read_file` 和 `search_docs`。這符合 SLM 的強項（例如界定決策如工具選擇），避開其弱項（廣泛知識、長距多跳推理）。\n\n\n\n\n\n\n## 為何選擇這些元件\n\n- **Foundry Local** 提供 **OpenAI 兼容 HTTP 端點**，切換到本地代理只需改變 `base_url`（並用本地占位 API 金鑰）。它也會自動選擇最佳建構版本（CPU\u002FGPU\u002FNPU）。\n- **Qwen** 模型經過函數呼叫訓練，穩定輸出格式良好的工具呼叫，使本地\u003Cem>聊天\u003C\u002Fem>模型變成本地\u003Cem>代理\u003C\u002Fem>。\n- **Chroma** 內嵌運行並將向量存放磁碟，整個 RAG 流程（嵌入 → 存儲 → 檢索 → 推理）均保持本地。\n- **MCP** 是傳輸協定，不是雲端服務：MCP 伺服器可在 `stdio` 上本地運行。\n\n## 安裝必備\n\n```bash\nfoundry model run qwen2.5-7b-instruct\nfoundry service status\n```\n\n```python\nfrom foundry_local import FoundryLocalManager\nfrom openai import OpenAI\n\nmanager = FoundryLocalManager(\"qwen2.5-7b-instruct\")\nclient = OpenAI(base_url=manager.endpoint, api_key=manager.api_key)  # local placeholder\n```\n\n8GB 記憶體為實際最低需求；GPU\u002FNPU 有助於性能但非必需。\n\n## 需重複的主要模式\n\n指引學習者閱讀筆記本\n[`17-local-agent-foundry-local.ipynb`](..\u002F..\u002F..\u002F17-creating-local-ai-agents\u002Fcode_samples\u002F17-local-agent-foundry-local.ipynb)：\n\n- \u003Cstrong>沙盒工具\u003C\u002Fstrong>：每個檔案工具均解析路徑並拒絕超出單一專案根目錄的路徑 — 即使本地，工具也只以使用者權限運行。\n- \u003Cstrong>工具呼叫迴圈\u003C\u002Fstrong>：使用 OpenAI 工具架構註冊工具，於本地執行請求工具，將結果回饋，重複直到產出最終答案。\n- **本地 RAG**：將文件添加到 Chroma 集合；`search_docs` 回傳前 k 筆區塊。\n- **本地 MCP**：透過 `stdio` 連接本地伺服器；限定作用域到專案目錄並驗證其輸出。\n\n## 混合路由（本地作為其中一個模型）\n\n| 狀態 | 模型運行位置 |\n|-----------|---------------|\n| 敏感資料 \u002F 離線 | 本地 SLM |\n| 簡單、界定明確的任務 | 本地 SLM（經濟快速） |\n| 複雜多跳推理且非敏感資料 | 雲端模型 |\n| 雲端故障 | 本地 SLM（漸進退化） |\n\n這呼應了 Lesson 16 的模型路由概念，將工作站列為其中一條路徑。優先設計可回退至本地的方案，讓代理效能降低而非直接失效。\n\n\n\n## 助理控制規則\n\n- 將所有檔案\u002F工具操作限制在沙盒化專案目錄。\n- 當學習者明確要求隱私\u002F離線目標時，不將程式碼或資料送往雲端 — 保持整個流程本地化。\n- 對 SLM 的品質設定現實預期；依賴工具與 RAG 多於模型本身的記憶知識。\n- 注意 Lesson 17 無 Foundry 回應端點，因此雲端煙霧測試不適用 — 請透過本地執行筆記本驗證。\n\n---\n\n\u003C!-- CO-OP TRANSLATOR DISCLAIMER START -->\n**免責聲明**：\n此文件已使用 AI 翻譯服務 [Co-op Translator](https:\u002F\u002Fgithub.com\u002FAzure\u002Fco-op-translator) 進行翻譯。雖然我們努力追求準確性，但請注意自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應視為權威來源。對於關鍵資訊，建議採用專業人工翻譯。我們不對因使用此翻譯所產生的任何誤解或誤譯承擔責任。\n\u003C!-- CO-OP TRANSLATOR DISCLAIMER END -->","# 使用 Foundry Local 和 Qwen 建立本地 AI 代理\n\n> 伴隨 [Lesson 17 – Creating Local AI Agents](..\u002F..\u002F..\u002F17-creating-local-ai-agents\u002FREADME.md) 的輔助技能。\n> 用於協助學習者打造一個能獨立在自己機器上推理、調用工具及搜尋文件的代理 — 完全無雲端推理。所有建議都基於課程內容與可執行筆記本。\n> \n> \n\n## 觸發條件\n\n當學習者希望：\n- 完全在設備端執行代理，為了隱私、成本或離線需求。\n- 使用 **Foundry Local** 本地部署模型，並透過 OpenAI 兼容端點連接。\n- 使用 **Qwen 函數呼叫** 模型來驅動可靠的本地工具調用。\n- 新增 **本地 RAG**（Chroma）或 **本地 MCP 伺服器**。\n- 設計一個 \u003Cstrong>混合\u003C\u002Fstrong> 本地\u002F雲端路由策略。\n\n## 核心心智模型\n\nSLM 以隱私、成本與離線操作換取廣度。致勝策略是：**讓 SLM 負責協調，讓工具執行繁重任務。** 模型不需要\u003Cem>了解\u003C\u002Fem>整個程式碼庫，只需知道何時呼叫 `read_file` 和 `search_docs`。這符合 SLM 的強項（例如界定決策如工具選擇），避開其弱項（廣泛知識、長距多跳推理）。\n\n\n\n\n\n\n## 為何選擇這些元件\n\n- **Foundry Local** 提供 **OpenAI 兼容 HTTP 端點**，切換到本地代理只需改變 `base_url`（並用本地占位 API 金鑰）。它也會自動選擇最佳建構版本（CPU\u002FGPU\u002FNPU）。\n- **Qwen** 模型經過函數呼叫訓練，穩定輸出格式良好的工具呼叫，使本地\u003Cem>聊天\u003C\u002Fem>模型變成本地\u003Cem>代理\u003C\u002Fem>。\n- **Chroma** 內嵌運行並將向量存放磁碟，整個 RAG 流程（嵌入 → 存儲 → 檢索 → 推理）均保持本地。\n- **MCP** 是傳輸協定，不是雲端服務：MCP 伺服器可在 `stdio` 上本地運行。\n\n## 安裝必備\n\n```bash\nfoundry model run qwen2.5-7b-instruct\nfoundry service status\n```\n\n```python\nfrom foundry_local import FoundryLocalManager\nfrom openai import OpenAI\n\nmanager = FoundryLocalManager(\"qwen2.5-7b-instruct\")\nclient = OpenAI(base_url=manager.endpoint, api_key=manager.api_key)  # local placeholder\n```\n\n8GB 記憶體為實際最低需求；GPU\u002FNPU 有助於性能但非必需。\n\n## 需重複的主要模式\n\n指引學習者閱讀筆記本\n[`17-local-agent-foundry-local.ipynb`](..\u002F..\u002F..\u002F17-creating-local-ai-agents\u002Fcode_samples\u002F17-local-agent-foundry-local.ipynb)：\n\n- \u003Cstrong>沙盒工具\u003C\u002Fstrong>：每個檔案工具均解析路徑並拒絕超出單一專案根目錄的路徑 — 即使本地，工具也只以使用者權限運行。\n- \u003Cstrong>工具呼叫迴圈\u003C\u002Fstrong>：使用 OpenAI 工具架構註冊工具，於本地執行請求工具，將結果回饋，重複直到產出最終答案。\n- **本地 RAG**：將文件添加到 Chroma 集合；`search_docs` 回傳前 k 筆區塊。\n- **本地 MCP**：透過 `stdio` 連接本地伺服器；限定作用域到專案目錄並驗證其輸出。\n\n## 混合路由（本地作為其中一個模型）\n\n| 狀態 | 模型運行位置 |\n|-----------|---------------|\n| 敏感資料 \u002F 離線 | 本地 SLM |\n| 簡單、界定明確的任務 | 本地 SLM（經濟快速） |\n| 複雜多跳推理且非敏感資料 | 雲端模型 |\n| 雲端故障 | 本地 SLM（漸進退化） |\n\n這呼應了 Lesson 16 的模型路由概念，將工作站列為其中一條路徑。優先設計可回退至本地的方案，讓代理效能降低而非直接失效。\n\n\n\n## 助理控制規則\n\n- 將所有檔案\u002F工具操作限制在沙盒化專案目錄。\n- 當學習者明確要求隱私\u002F離線目標時，不將程式碼或資料送往雲端 — 保持整個流程本地化。\n- 對 SLM 的品質設定現實預期；依賴工具與 RAG 多於模型本身的記憶知識。\n- 注意 Lesson 17 無 Foundry 回應端點，因此雲端煙霧測試不適用 — 請透過本地執行筆記本驗證。\n\n---\n\n\u003C!-- CO-OP TRANSLATOR DISCLAIMER START -->\n**免責聲明**：\n此文件已使用 AI 翻譯服務 [Co-op Translator](https:\u002F\u002Fgithub.com\u002FAzure\u002Fco-op-translator) 進行翻譯。雖然我們努力追求準確性，但請注意自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應視為權威來源。對於關鍵資訊，建議採用專業人工翻譯。我們不對因使用此翻譯所產生的任何誤解或誤譯承擔責任。\n\u003C!-- CO-OP TRANSLATOR DISCLAIMER END -->",{"name":5,"license":14},"main","f09e94ffe170f8af6d3db7c42987bbe4db227723","translations\u002Fzh-TW\u002F.agents\u002Fskills\u002Flocal-ai-agents",26057,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners","https:\u002F\u002Faka.ms\u002Fai-agents-beginners","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-07 12:51:12",{"source":7,"skillName":5,"commands":36,"prompt":46,"zipAvailable":47},[37,40,43],{"tool":38,"command":39},"npx","npx skills add microsoft\u002Fai-agents-for-beginners --skill local-ai-agents",{"tool":41,"command":42},"bunx","bunx skills add microsoft\u002Fai-agents-for-beginners --skill local-ai-agents",{"tool":44,"command":45},"pnpm","pnpm dlx skills add microsoft\u002Fai-agents-for-beginners --skill local-ai-agents","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners\u002Fblob\u002Fmain\u002Ftranslations\u002Fzh-TW\u002F.agents\u002Fskills\u002Flocal-ai-agents\u002FSKILL.md",true,[],[50,68,79,87,94,101],{"skillNo":51,"name":52,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":53,"categories":54,"keywords":65,"publishedAt":20},"01M69A206TRZ8KK0CW0HYJF5V5","testing-course-samples","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners\u002Fblob\u002Fmain\u002Ftranslations\u002Fzh-TW\u002F.agents\u002Fskills\u002Ftesting-course-samples\u002FSKILL.md",[55,60],{"categoryNo":56,"categoryName":57,"taxonomyType":58,"taxonomyTypeDesc":59},"01JBSEEDCAT000000000000008","测试与质量","SCENARIO","使用场景",{"categoryNo":61,"categoryName":62,"taxonomyType":63,"taxonomyTypeDesc":64},"01JBSEEDCAT000000000000039","教师与教育","PROFESSION","适用职业",[66,67],"testing","testing course samples",{"skillNo":69,"name":70,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":76,"publishedAt":20},"01M69A1XRB2SFHYRMEH0K08EKZ","microsoft-docs","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners\u002Fblob\u002Fmain\u002Ftranslations\u002Fzh-TW\u002F.agents\u002Fskills\u002Fmicrosoft-docs\u002FSKILL.md",[73],{"categoryNo":74,"categoryName":75,"taxonomyType":58,"taxonomyTypeDesc":59},"01JBSEEDCAT000000000000023","Skill与智能体开发",[77,8,78],"docs","microsoft docs",{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":20},"01M69A1S947N7MM6V9JF85S2E7","jupyter-notebook","當使用者要求建立、搭建或編輯 Jupyter 筆記本（`.ipynb`）用於實驗、探索或教學時使用；優先使用隨附範本並執行輔助腳本 `new_notebook.py` 來產生一個乾淨的起始筆記本。","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners\u002Fblob\u002Fmain\u002Ftranslations\u002Fzh-TW\u002F.agents\u002Fskills\u002Fjupyter-notebook\u002FSKILL.md",[],[86],"jupyter notebook",{"skillNo":88,"name":89,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":92,"publishedAt":20},"01M69A1Q8EXPWKZSQK69V6WF22","deploying-scalable-agents","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners\u002Fblob\u002Fmain\u002Ftranslations\u002Fzh-TW\u002F.agents\u002Fskills\u002Fdeploying-scalable-agents\u002FSKILL.md",[],[93],"deploying scalable agents",{"skillNo":95,"name":96,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":97,"categories":98,"keywords":99,"publishedAt":20},"01M69A1MHZTH3RH9N8VYSYG74X","azure-openai-to-responses","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners\u002Fblob\u002Fmain\u002Ftranslations\u002Fzh-TW\u002F.agents\u002Fskills\u002Fazure-openai-to-responses\u002FSKILL.md",[],[100],"azure openai to responses",{"skillNo":102,"name":52,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":107,"publishedAt":20},"01M69A1J59TJWN7MV1FV5TG443","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fai-agents-for-beginners\u002Fblob\u002Fmain\u002Ftranslations\u002Fzh-MO\u002F.agents\u002Fskills\u002Ftesting-course-samples\u002FSKILL.md",[105,106],{"categoryNo":56,"categoryName":57,"taxonomyType":58,"taxonomyTypeDesc":59},{"categoryNo":61,"categoryName":62,"taxonomyType":63,"taxonomyTypeDesc":64},[66,67]]