戰(zhàn)：從問答接口到自主智能體的完整路徑)
在實(shí)際項(xiàng)目里把一個(gè)大模型接進(jìn)業(yè)務(wù)系統(tǒng)并不難難的是讓它從一個(gè)“你問它答”的問答接口變成一個(gè)能查數(shù)據(jù)、調(diào)接口、做決策的自主智能體。阿里云 Qwen千問系列模型在當(dāng)前的模型版本中已經(jīng)支持工具調(diào)用Function Calling配合阿里云百煉平臺(tái)的托管能力和開源部署方案已經(jīng)可以搭出一條從問答到自主智能體的完整路徑。這篇文章會(huì)沿著這條路徑展開先把 Qwen 的最小問答鏈路跑通再解釋 Function Calling 為什么是智能體的核心機(jī)制然后補(bǔ)上記憶層Embedding Milvus 檢索最后給出生產(chǎn)環(huán)境的落地建議和排錯(cuò)清單。學(xué)完以后你可以在自己的項(xiàng)目里實(shí)現(xiàn)一個(gè)能查詢業(yè)務(wù)數(shù)據(jù)、調(diào)用內(nèi)部接口并且?guī)z索記憶的智能體服務(wù)。1. 先理解“問答”和“自主智能體”的邊界1.1 問答模型解決的是“生成”不是“行動(dòng)”一個(gè)尚未集成任何工具的 Qwen 問答接口本質(zhì)上完成的是“文本生成”任務(wù)。你給它一段用戶問題它根據(jù)訓(xùn)練時(shí)學(xué)習(xí)到的知識(shí)、當(dāng)前上下文和生成參數(shù)返回一段最可能的文本。這個(gè)過程的輸入輸出都是文本模型沒有權(quán)限去查數(shù)據(jù)庫、沒有能力去調(diào)用 HTTP 接口也不會(huì)主動(dòng)更新自己的知識(shí)。這也是很多項(xiàng)目把模型接上線以后發(fā)現(xiàn)它只能“聊”不能“干”的原因。在工程上純問答模型適合的場景包括客服話術(shù)生成、代碼注釋、文檔摘要、翻譯、規(guī)則問答。這些場景的共同點(diǎn)是答案要么藏在模型的參數(shù)里要么已經(jīng)出現(xiàn)在用戶提供的上下文里。一旦問題需要“實(shí)時(shí)數(shù)據(jù)”例如“查一下這個(gè)訂單現(xiàn)在到哪了”純問答模型就失效了因?yàn)樗⒉恢烙唵蜗到y(tǒng)的當(dāng)前狀態(tài)。1.2 自主智能體多了四個(gè)能力模塊從問答模型升級(jí)到自主智能體不是換一個(gè)更大的模型而是要在模型外面補(bǔ)一套決策和執(zhí)行的機(jī)制。業(yè)內(nèi)通常把智能體拆成四個(gè)部分大腦負(fù)責(zé)理解用戶意圖、拆解任務(wù)、決定下一步動(dòng)作。這里仍然是 Qwen 模型但每次請(qǐng)求的輸入不再只是用戶問題而是“系統(tǒng)提示詞 歷史對(duì)話 工具定義 當(dāng)前任務(wù)”。工具模型本身不能直接執(zhí)行動(dòng)作必須通過一段代碼或一個(gè) API 向模型暴露能力。常見的工具包括查詢訂單接口、天氣接口、數(shù)據(jù)庫查詢、文件讀寫、網(wǎng)頁檢索。記憶分為短期記憶和長期記憶。短期記憶是對(duì)話歷史長期記憶通常用向量數(shù)據(jù)庫保存業(yè)務(wù)知識(shí)通過檢索把最相關(guān)的內(nèi)容注入上下文。循環(huán)智能體不是一次請(qǐng)求就結(jié)束。模型先輸出“我準(zhǔn)備調(diào)用某個(gè)工具參數(shù)是什么”程序去執(zhí)行工具把工具結(jié)果回填給模型模型再?zèng)Q定繼續(xù)調(diào)用下一個(gè)工具還是給出最終答案。這個(gè)“計(jì)劃 - 調(diào)用 - 觀察 - 再計(jì)劃”的循環(huán)就是智能體與普通問答的本質(zhì)區(qū)別。1.3 當(dāng)前工程落地的形態(tài)人機(jī)協(xié)同為主有限自主執(zhí)行從當(dāng)前實(shí)際落地的項(xiàng)目看完整意義上的“全自主智能體”在大多數(shù)業(yè)務(wù)場景里還很少見。常見形態(tài)是“人機(jī)協(xié)同為主、有限自主執(zhí)行”系統(tǒng)允許智能體在限定范圍內(nèi)自主調(diào)用只讀查詢類工具但涉及寫操作、支付、刪除、發(fā)送消息等高風(fēng)險(xiǎn)動(dòng)作時(shí)必須回到人工確認(rèn)。這個(gè)設(shè)計(jì)不是技術(shù)做不到而是為了可控。你在實(shí)現(xiàn)智能體時(shí)建議把工具按風(fēng)險(xiǎn)分級(jí)風(fēng)險(xiǎn)級(jí)別工具示例執(zhí)行策略低風(fēng)險(xiǎn)只讀查詢訂單狀態(tài)、查天氣、檢索知識(shí)庫智能體自主執(zhí)行中風(fēng)險(xiǎn)寫操作修改草稿、發(fā)送測試消息記錄日志后執(zhí)行可回滾高風(fēng)險(xiǎn)動(dòng)作支付、刪除數(shù)據(jù)、對(duì)外發(fā)布生成待確認(rèn)動(dòng)作人工確認(rèn)后執(zhí)行2. 環(huán)境準(zhǔn)備Qwen 接入的三種方式2.1 方式一通過阿里云百煉 API 接入阿里云百煉Model Studio是 Qwen 系列模型的托管平臺(tái)。它的優(yōu)勢在于不需要自己準(zhǔn)備 GPU 服務(wù)器開通服務(wù)后拿到 API Key 就可以調(diào)用。目前百煉提供兼容 OpenAI Chat Completions 格式的接口因此主流的 Python、Java、Node.js 等語言都能快速接入。接入前需要準(zhǔn)備一個(gè)阿里云賬號(hào)并開通百煉服務(wù)。在控制臺(tái)創(chuàng)建 API Key。注意 Key 只顯示一次要立即保存。確定調(diào)用模型名。常見的有 qwen-plus、qwen-turbo以及工具調(diào)用能力更完整的 qwen-max 等。不同模型名對(duì)應(yīng)的上下文長度和費(fèi)用不同落地前要去百煉控制臺(tái)確認(rèn)最新的模型列表。注意api_key 不要硬編碼在代碼里。學(xué)習(xí)階段可以放環(huán)境變量生產(chǎn)階段必須放到密鑰管理服務(wù)或者配置中心。2.2 方式二把 Qwen 部署到自己的服務(wù)器如果業(yè)務(wù)有數(shù)據(jù)隔離要求或者調(diào)用量很大、長期使用可以考慮在自有服務(wù)器上部署 Qwen 開源模型。Qwen 提供了多個(gè)參數(shù)規(guī)模的開源版本。參數(shù)越小部署越容易但能力越弱參數(shù)越大能力越強(qiáng)對(duì) GPU 顯存要求越高。以常見情況為例模型規(guī)模顯存需求示例適用場景小參數(shù)模型消費(fèi)級(jí)顯卡或小顯存實(shí)例學(xué)習(xí)、原型驗(yàn)證、簡單問答中等規(guī)模單張企業(yè)級(jí) GPU專業(yè)問答、代碼生成大規(guī)模模型多卡部署或分布式推理復(fù)雜推理、工具調(diào)用、生產(chǎn)環(huán)境本地部署需要額外處理模型下載、推理框架、GPU 驅(qū)動(dòng)、并發(fā)排隊(duì)等問題。建議先在開發(fā)機(jī)跑通再遷移到云端 GPU 實(shí)例。OpenAI 兼容層的部署配置以官方部署文檔為準(zhǔn)不要憑記憶猜測版本參數(shù)。2.3 方式三Java 項(xiàng)目里配置阿里云 Maven 倉庫和 Spring Initializr如果項(xiàng)目是 Java 技術(shù)棧第一個(gè)遇到的問題常常不是代碼而是依賴下載。在 Maven 的 settings.xml 中配置阿里云鏡像倉庫可以顯著提升依賴?yán)∷俣萴irror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共倉庫/name urlhttps://maven.aliyun.com/repository/public/url /mirror這段配置的作用是把原本從中央倉庫拉取的依賴改從國內(nèi)鏡像拉取。需要注意的是鏡像倉庫只是下載源不改變依賴的坐標(biāo)和版本。不同團(tuán)隊(duì)還可能使用私服這時(shí)要結(jié)合私服策略調(diào)整mirrorOf避免所有倉庫都被鏡像接管。新建 Spring Boot 項(xiàng)目時(shí)也可以使用阿里云的 Spring Initializr 服務(wù)地址https://start.aliyun.com 。它提供的是經(jīng)過阿里云適配的初始化模板適合需要快速生成標(biāo)準(zhǔn)工程的情況。如果團(tuán)隊(duì)內(nèi)部有統(tǒng)一腳手架優(yōu)先使用內(nèi)部版本。2.4 三種接入方式的對(duì)比接入方式成本數(shù)據(jù)控制部署難度推薦場景百煉 API按調(diào)用量計(jì)費(fèi)數(shù)據(jù)經(jīng)云服務(wù)處理低快速原型、中小規(guī)模、開發(fā)測試自建部署硬件加運(yùn)維成本數(shù)據(jù)留在自己環(huán)境高數(shù)據(jù)隔離、大規(guī)模長期調(diào)用Java 生態(tài)集成與接入方式疊加與接入方式相關(guān)中已有 Spring Boot 體系接入方式之間不是互斥的。常見做法是開發(fā)環(huán)境用百煉 API 快速跑通生產(chǎn)環(huán)境根據(jù)數(shù)據(jù)合規(guī)和成本評(píng)估是否遷移到自建部署。遷移時(shí)代碼層盡量使用兼容接口讓切換成本降到最低。3. 跑通最小問答鏈路3.1 最小 Python 示例先跑通一個(gè)最小的問答鏈路再談智能體。這里使用 Python 的 openai SDK通過兼容模式訪問百煉import os from openai import OpenAI client OpenAI( api_keyos.getenv(DASHSCOPE_API_KEY), base_urlhttps://dashscope.aliyuncs.com/compatible-mode/v1 ) response client.chat.completions.create( modelqwen-plus, messages[ {role: system, content: 你是一名經(jīng)驗(yàn)豐富的 Java 架構(gòu)師。}, {role: user, content: 用三句話解釋什么是 Function Calling。} ], temperature0.7, max_tokens512 ) print(response.choices[0].message.content)運(yùn)行前確認(rèn)兩點(diǎn)第一環(huán)境變量 DASHSCOPE_API_KEY 已設(shè)置第二網(wǎng)絡(luò)環(huán)境能訪問 base_url。如果網(wǎng)絡(luò)策略禁用了外部域名請(qǐng)求需要先確認(rèn)百煉 endpoint 是否在訪問白名單里。3.2 關(guān)鍵參數(shù)說明參數(shù)含義常見取值調(diào)大影響調(diào)小影響temperature采樣隨機(jī)性0.0 到 1.0回答更多樣可能不穩(wěn)定回答更確定偏向保守top_p核采樣比例0.1 到 1.0候選詞更多候選詞更集中max_tokens單次最大生成 token 數(shù)128 到 4096按模型輸出更長成本更高輸出可能被截?cái)鄊essages對(duì)話消息列表按角色排列上下文更完整但可能超限上下文不足可能導(dǎo)致遺忘在函數(shù)調(diào)用場景里temperature 建議設(shè)置得低一些例如 0.2 到 0.4。工具調(diào)用要求模型輸出穩(wěn)定的 JSON 參數(shù)隨機(jī)性太大會(huì)導(dǎo)致參數(shù)格式錯(cuò)誤或參數(shù)值漂移。3.3 運(yùn)行和驗(yàn)證運(yùn)行上面的腳本正常情況下會(huì)輸出一段關(guān)于 Function Calling 的解釋。這里要驗(yàn)證的不只是“有輸出”而是輸出是否滿足要求?？梢砸来悟?yàn)證修改 system 提示詞觀察回答風(fēng)格是否變化。修改 temperature比較同一問題的穩(wěn)定性和多樣性。故意給一個(gè)超出 max_tokens 的復(fù)雜問題觀察輸出是否被截?cái)嗖⒗斫馊绾瓮ㄟ^流式輸出解決。這一步能幫你確認(rèn) API Key、網(wǎng)絡(luò)、模型名、參數(shù)四條鏈路都正常。如果其中任何一環(huán)有問題后面的智能體代碼都會(huì)失敗所以不要跳過。3.4 這一步最常見的坑第一個(gè)坑是模型名寫錯(cuò)。不同區(qū)域、不同賬號(hào)可能支持的模型名不同報(bào)錯(cuò)信息里會(huì)顯示類似 model not found 的提示。處理方式是去百煉控制臺(tái)查看支持列表不要憑記憶猜測。第二個(gè)坑是 API Key 設(shè)置錯(cuò)誤。常見現(xiàn)象是 401 或 InvalidApiKey。檢查環(huán)境變量是否真的傳入了進(jìn)程可以在腳本里打印 Key 的前幾位和后幾位用于確認(rèn)但不要完整打印。第三個(gè)坑是把 max_tokens 設(shè)太小。問答內(nèi)容稍長就會(huì)被截?cái)嗫雌饋硐瘛盎卮鸩煌暾?。?shí)際上模型輸出被強(qiáng)制停止了需要調(diào)大 max_tokens 或改用流式輸出。4. Function Calling問答升級(jí)為智能體的核心機(jī)制4.1 為什么模型本身不能直接調(diào)用工具模型是一個(gè)文本生成器它沒有權(quán)限訪問你的系統(tǒng)也不會(huì)連接外部服務(wù)。所謂 Function Calling本質(zhì)是“模型決定要調(diào)用哪個(gè)工具并生成調(diào)用參數(shù)”真正執(zhí)行工具的是你的代碼。模型輸出的不是最終答案而是一個(gè)結(jié)構(gòu)化的“調(diào)用請(qǐng)求”。因此實(shí)現(xiàn)工具調(diào)用必須有兩部分一部分是向模型聲明“你有這些工具可用每個(gè)工具的參數(shù)長什么樣”另一部分是程序端執(zhí)行工具后把結(jié)果以新的消息形式回傳給模型讓模型生成最終回答。缺了任意一部分工具調(diào)用都無法成立。4.2 工具定義的 JSON Schema向模型聲明工具時(shí)通常使用 JSON Schema 描述每個(gè)工具的名稱、描述、參數(shù)類型和必填項(xiàng)。描述寫得越清楚模型越不容易選錯(cuò)工具。下面是一個(gè)查詢訂單狀態(tài)的工具定義{ type: function, function: { name: query_order_status, description: 根據(jù)訂單號(hào)查詢訂單當(dāng)前狀態(tài)。只有用戶明確提供了訂單號(hào)時(shí)才調(diào)用。, parameters: { type: object, properties: { order_id: { type: string, description: 用戶提供的訂單號(hào)例如 OD202501010001 } }, required: [order_id] } } }注意幾個(gè)細(xì)節(jié)description 里要說明“何時(shí)調(diào)用”和“何時(shí)不調(diào)用”required 里明確必填參數(shù)參數(shù)類型盡量精確避免讓模型自行猜測。工具定義本身是 prompt 的一部分也會(huì)占用上下文 token因此不要無限制地加工具只保留當(dāng)前任務(wù)真正需要的。4.3 一個(gè)帶工具循環(huán)的智能體實(shí)現(xiàn)下面用 Python 寫一個(gè)最簡智能體循環(huán)。流程是用戶提問 - 模型判斷是否調(diào)用工具 - 程序執(zhí)行工具 - 回傳結(jié)果 - 模型生成最終回答。import json import os from openai import OpenAI client OpenAI( api_keyos.getenv(DASHSCOPE_API_KEY), base_urlhttps://dashscope.aliyuncs.com/compatible-mode/v1 ) def query_order_status(order_id: str) - str: # 實(shí)際項(xiàng)目中這里會(huì)調(diào)用內(nèi)部訂單服務(wù) return f訂單 {order_id} 的狀態(tài)是已發(fā)貨預(yù)計(jì)明天送達(dá)。 tools [ { type: function, function: { name: query_order_status, description: 根據(jù)訂單號(hào)查詢訂單當(dāng)前狀態(tài), parameters: { type: object, properties: { order_id: { type: string, description: 用戶提供的訂單號(hào) } }, required: [order_id] } } } ] def run_agent(user_message: str, max_steps: int 3) - str: messages [ {role: system, content: 你是訂單助手。用戶詢問訂單狀態(tài)時(shí)先調(diào)用工具查詢?cè)儆米匀徽Z言回復(fù)。}, {role: user, content: user_message} ] for step in range(max_steps): response client.chat.completions.create( modelqwen-plus, messagesmessages, toolstools, tool_choiceauto ) message response.choices[0].message if message.tool_calls: messages.append({ role: assistant, tool_calls: [ { id: tc.id, type: function, function: { name: tc.function.name, arguments: tc.function.arguments } } for tc in message.tool_calls ] }) for tc in message.tool_calls: args json.loads(tc.function.arguments) result query_order_status(args[order_id]) messages.append({ role: tool, tool_call_id: tc.id, content: result }) else: return message.content return 已達(dá)到最大執(zhí)行步數(shù)無法完成用戶的請(qǐng)求。 print(run_agent(幫我查一下訂單 OD202501010001 到哪了))這段代碼有四個(gè)關(guān)鍵點(diǎn)每輪請(qǐng)求都要把之前的消息完整傳給模型尤其是 tool 調(diào)用結(jié)果。模型需要看到工具返回內(nèi)容才能繼續(xù)推理。程序執(zhí)行工具后必須使用 tool 角色并帶上 tool_call_id與模型輸出的工具調(diào)用請(qǐng)求一一對(duì)應(yīng)。max_steps 是循環(huán)上限防止智能體在工具間反復(fù)橫跳消耗大量調(diào)用成本。每個(gè)工具內(nèi)部要做好異常處理。工具拋異常時(shí)要把錯(cuò)誤信息回傳給模型讓模型決定是換參數(shù)重試還是給用戶一個(gè)合理答復(fù)而不是直接讓整個(gè)程序崩潰。注意不要把工具返回結(jié)果原樣無限制地回填給模型。工具返回的可能是大段 JSON 或長文本回填前要按需裁剪字段控制上下文 token 消耗。4.4 工具調(diào)用流程里最容易出錯(cuò)的地方工具參數(shù)解析很容易踩坑。模型輸出的 arguments 是 JSON 字符串但有時(shí)包含多余空格、換行甚至缺失字段。建議使用寬松解析方式解析失敗時(shí)回退到正則提取并把整段原文記錄下來方便排查。另外一個(gè)常見問題是工具描述不明確導(dǎo)致模型在不需要工具時(shí)也調(diào)用工具。比如用戶只是閑聊“你好”模型不該去查訂單。解決方式是在工具描述里增加觸發(fā)條件并在 system 提示詞里明確“只有用戶提供訂單號(hào)時(shí)才調(diào)用查詢工具”。還需要注意 tool_choice 參數(shù)。默認(rèn) auto 讓模型自己決定是否調(diào)用工具如果業(yè)務(wù)想強(qiáng)制模型必須調(diào)用某個(gè)工具可以設(shè)為指定工具名。但強(qiáng)制調(diào)用會(huì)犧牲模型的判斷能力一般只在不需要判斷的場景使用。5. 給智能體加上記憶Qwen Embedding Milvus 檢索5.1 什么時(shí)候需要外部記憶智能體在對(duì)話中會(huì)產(chǎn)生兩類記憶需求。第一類是會(huì)話內(nèi)的短期記憶通過把歷史 messages 傳入模型來實(shí)現(xiàn)。第二類是跨會(huì)話的長期記憶比如企業(yè)知識(shí)庫、歷史工單、產(chǎn)品文檔。這些內(nèi)容不可能全部塞進(jìn)模型上下文因?yàn)?token 有限且成本高所以需要先做檢索只把最相關(guān)的片段注入提示詞。當(dāng)出現(xiàn)以下信號(hào)時(shí)就該接入外部記憶用戶問題涉及私有文檔、內(nèi)部知識(shí)模型訓(xùn)練時(shí)沒有見過。用戶問題需要綜合多份文檔才能回答。智能體每次回答前都需要相同背景材料重復(fù)寫入提示詞太浪費(fèi)。希望通過業(yè)務(wù)數(shù)據(jù)生成個(gè)性化回答而不是每次從頭問起。5.2 RAG 工作流程檢索增強(qiáng)生成Retrieval-Augmented Generation的流程分兩步。第一步是離線準(zhǔn)備把業(yè)務(wù)文檔切分成片段對(duì)每個(gè)片段生成向量寫入向量數(shù)據(jù)庫。第二步是在線檢索用戶提問時(shí)先生成問題的向量再在向量數(shù)據(jù)庫中查找最相似的片段把片段作為上下文拼到消息里最后讓模型生成回答。切分是決定效果的關(guān)鍵。切得太大會(huì)引入無關(guān)內(nèi)容切得太小會(huì)讓語義不完整。常見做法是按標(biāo)題和段落語義切分每個(gè)片段控制在幾百 token 左右同時(shí)保留來源信息方便回答時(shí)溯源。5.3 Java LangChain4j Milvus 接入示例在 Java 技術(shù)棧里可以使用 LangChain4j 簡化向量檢索的接入。LangChain4j 提供統(tǒng)一 API屏蔽了向量數(shù)據(jù)庫的差異。下面是一個(gè)示例 Maven 依賴片段dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version${langchain4j.version}/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-milvus/artifactId version${langchain4j.version}/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version${langchain4j.version}/version /dependency版本號(hào)${langchain4j.version}需要替換為你實(shí)際使用的穩(wěn)定版本并且要與 Spring Boot 版本兼容。依賴下載前確認(rèn) Maven 鏡像配置已生效。寫入和檢索的示例結(jié)構(gòu)如下EmbeddingModel embeddingModel OpenAiEmbeddingModel.builder() .baseUrl(https://dashscope.aliyuncs.com/compatible-mode/v1) .apiKey(System.getenv(DASHSCOPE_API_KEY)) .modelName(text-embedding-v3) .build(); MilvusEmbeddingStore embeddingStore MilvusEmbeddingStore.builder() .host(127.0.0.1) .port(19530) .collectionName(qwen_agent_kb) .dimension(1024) .build();先把文檔片段轉(zhuǎn)成向量并寫入再在回答時(shí)按相似度檢索。這里要注意 dimension向量維度必須與 Embedding 模型輸出的維度一致不一致時(shí)寫入會(huì)報(bào)維度錯(cuò)誤。embedding 模型名和維度參數(shù)在不同階段可能調(diào)整落地前以當(dāng)前 API 文檔為準(zhǔn)。5.4 集合設(shè)計(jì)和檢索參數(shù)字段作用推薦設(shè)置collectionName知識(shí)庫集合名按業(yè)務(wù)域命名如 order_kb、policy_kbdimension向量維度與 embedding 模型輸出一致metricType相似度算法常用 COSINE 或 IP按數(shù)據(jù)特點(diǎn)選擇id主鍵使用業(yè)務(wù)側(cè)生成的唯一 IDcontent原始文本保存原文方便回填上下文metadata元數(shù)據(jù)來源、時(shí)間、權(quán)限域便于過濾檢索時(shí)還需要設(shè)置 topK 和相似度閾值。topK 控制返回片段數(shù)量一般取 3 到 10。閾值過嚴(yán)會(huì)漏掉相關(guān)內(nèi)容過松會(huì)引入噪音。不要只看 topK建議同時(shí)輸出得分人工抽樣評(píng)估一次找到當(dāng)前文檔集的合理閾值。6. 運(yùn)行驗(yàn)證和常見問題排查6.1 一套可復(fù)用的驗(yàn)證順序智能體項(xiàng)目上線前建議按這個(gè)順序驗(yàn)證單次問答是否正常不攜帶工具時(shí)基本問答能正確返回。工具聲明是否生效輸入一個(gè)明確需要工具的提問確認(rèn)模型輸出了 tool_calls。工具執(zhí)行是否正確查看程序?qū)嶋H調(diào)用了哪個(gè)函數(shù)傳參是否合理。工具結(jié)果回填是否成功確認(rèn) tool 角色的消息帶上了正確的 tool_call_id。最終回答是否基于工具結(jié)果檢查回答內(nèi)容是否引用了工具返回的數(shù)據(jù)而不是模型自己編造。異常分支是否可控工具拋錯(cuò)、模型連續(xù)調(diào)用工具、上下文超限時(shí)程序是否能優(yōu)雅退出。6.2 問題現(xiàn)象、原因和處理表問題現(xiàn)象常見原因檢查方式處理建議模型回答完全不調(diào)用工具工具未傳入、描述不清、模型不支持打印請(qǐng)求中的 tools 字段檢查 model 名確認(rèn)傳入 tools增強(qiáng) description換支持工具調(diào)用的模型工具調(diào)用了但程序沒執(zhí)行只把工具發(fā)給模型沒有寫執(zhí)行分支檢查代碼是否解析了 message.tool_calls補(bǔ)上 for 循環(huán)執(zhí)行工具的邏輯工具結(jié)果回傳后模型仍錯(cuò)答tool_call_id 不匹配或消息順序錯(cuò)誤打印 messages 列表檢查角色確保 tool 消息緊跟對(duì)應(yīng)的 assistant tool_calls 消息上下文超限歷史消息或工具結(jié)果越來越大查看報(bào)錯(cuò)信息中的 token 數(shù)接入摘要機(jī)制裁剪歷史限制工具返回長度參數(shù)解析失敗模型輸出非法 JSON打印原始 arguments增加容錯(cuò)解析記錄原文定位模型輸出問題檢索結(jié)果與問題無關(guān)切分粒度差、embedding 不匹配、閾值不對(duì)單獨(dú)跑檢索用例檢查召回優(yōu)化切分、重選 embedding 模型、調(diào)整閾值6.3 排查鏈路遇到問題按鏈路從下往上排網(wǎng)絡(luò)和 Key先確認(rèn) base_url 可達(dá)API Key 有效。請(qǐng)求參數(shù)打印完整請(qǐng)求體逐字段確認(rèn) tools、messages、model 是否符合預(yù)期。模型返回查看原始響應(yīng)區(qū)分是沒生成 tool_calls還是生成了 Qwen Function Calling實(shí)戰(zhàn)：從問答接口到自主智能體的完整路徑
在實(shí)際項(xiàng)目里把一個(gè)大模型接進(jìn)業(yè)務(wù)系統(tǒng)并不難難的是讓它從一個(gè)“你問它答”的問答接口變成一個(gè)能查數(shù)據(jù)、調(diào)接口、做決策的自主智能體。阿里云 Qwen千問系列模型在當(dāng)前的模型版本中已經(jīng)支持工具調(diào)用Function Calling配合阿里云百煉平臺(tái)的托管能力和開源部署方案已經(jīng)可以搭出一條從問答到自主智能體的完整路徑。這篇文章會(huì)沿著這條路徑展開先把 Qwen 的最小問答鏈路跑通再解釋 Function Calling 為什么是智能體的核心機(jī)制然后補(bǔ)上記憶層Embedding Milvus 檢索最后給出生產(chǎn)環(huán)境的落地建議和排錯(cuò)清單。學(xué)完以后你可以在自己的項(xiàng)目里實(shí)現(xiàn)一個(gè)能查詢業(yè)務(wù)數(shù)據(jù)、調(diào)用內(nèi)部接口并且?guī)z索記憶的智能體服務(wù)。1. 先理解“問答”和“自主智能體”的邊界1.1 問答模型解決的是“生成”不是“行動(dòng)”一個(gè)尚未集成任何工具的 Qwen 問答接口本質(zhì)上完成的是“文本生成”任務(wù)。你給它一段用戶問題它根據(jù)訓(xùn)練時(shí)學(xué)習(xí)到的知識(shí)、當(dāng)前上下文和生成參數(shù)返回一段最可能的文本。這個(gè)過程的輸入輸出都是文本模型沒有權(quán)限去查數(shù)據(jù)庫、沒有能力去調(diào)用 HTTP 接口也不會(huì)主動(dòng)更新自己的知識(shí)。這也是很多項(xiàng)目把模型接上線以后發(fā)現(xiàn)它只能“聊”不能“干”的原因。在工程上純問答模型適合的場景包括客服話術(shù)生成、代碼注釋、文檔摘要、翻譯、規(guī)則問答。這些場景的共同點(diǎn)是答案要么藏在模型的參數(shù)里要么已經(jīng)出現(xiàn)在用戶提供的上下文里。一旦問題需要“實(shí)時(shí)數(shù)據(jù)”例如“查一下這個(gè)訂單現(xiàn)在到哪了”純問答模型就失效了因?yàn)樗⒉恢烙唵蜗到y(tǒng)的當(dāng)前狀態(tài)。1.2 自主智能體多了四個(gè)能力模塊從問答模型升級(jí)到自主智能體不是換一個(gè)更大的模型而是要在模型外面補(bǔ)一套決策和執(zhí)行的機(jī)制。業(yè)內(nèi)通常把智能體拆成四個(gè)部分大腦負(fù)責(zé)理解用戶意圖、拆解任務(wù)、決定下一步動(dòng)作。這里仍然是 Qwen 模型但每次請(qǐng)求的輸入不再只是用戶問題而是“系統(tǒng)提示詞 歷史對(duì)話 工具定義 當(dāng)前任務(wù)”。工具模型本身不能直接執(zhí)行動(dòng)作必須通過一段代碼或一個(gè) API 向模型暴露能力。常見的工具包括查詢訂單接口、天氣接口、數(shù)據(jù)庫查詢、文件讀寫、網(wǎng)頁檢索。記憶分為短期記憶和長期記憶。短期記憶是對(duì)話歷史長期記憶通常用向量數(shù)據(jù)庫保存業(yè)務(wù)知識(shí)通過檢索把最相關(guān)的內(nèi)容注入上下文。循環(huán)智能體不是一次請(qǐng)求就結(jié)束。模型先輸出“我準(zhǔn)備調(diào)用某個(gè)工具參數(shù)是什么”程序去執(zhí)行工具把工具結(jié)果回填給模型模型再?zèng)Q定繼續(xù)調(diào)用下一個(gè)工具還是給出最終答案。這個(gè)“計(jì)劃 - 調(diào)用 - 觀察 - 再計(jì)劃”的循環(huán)就是智能體與普通問答的本質(zhì)區(qū)別。1.3 當(dāng)前工程落地的形態(tài)人機(jī)協(xié)同為主有限自主執(zhí)行從當(dāng)前實(shí)際落地的項(xiàng)目看完整意義上的“全自主智能體”在大多數(shù)業(yè)務(wù)場景里還很少見。常見形態(tài)是“人機(jī)協(xié)同為主、有限自主執(zhí)行”系統(tǒng)允許智能體在限定范圍內(nèi)自主調(diào)用只讀查詢類工具但涉及寫操作、支付、刪除、發(fā)送消息等高風(fēng)險(xiǎn)動(dòng)作時(shí)必須回到人工確認(rèn)。這個(gè)設(shè)計(jì)不是技術(shù)做不到而是為了可控。你在實(shí)現(xiàn)智能體時(shí)建議把工具按風(fēng)險(xiǎn)分級(jí)風(fēng)險(xiǎn)級(jí)別工具示例執(zhí)行策略低風(fēng)險(xiǎn)只讀查詢訂單狀態(tài)、查天氣、檢索知識(shí)庫智能體自主執(zhí)行中風(fēng)險(xiǎn)寫操作修改草稿、發(fā)送測試消息記錄日志后執(zhí)行可回滾高風(fēng)險(xiǎn)動(dòng)作支付、刪除數(shù)據(jù)、對(duì)外發(fā)布生成待確認(rèn)動(dòng)作人工確認(rèn)后執(zhí)行2. 環(huán)境準(zhǔn)備Qwen 接入的三種方式2.1 方式一通過阿里云百煉 API 接入阿里云百煉Model Studio是 Qwen 系列模型的托管平臺(tái)。它的優(yōu)勢在于不需要自己準(zhǔn)備 GPU 服務(wù)器開通服務(wù)后拿到 API Key 就可以調(diào)用。目前百煉提供兼容 OpenAI Chat Completions 格式的接口因此主流的 Python、Java、Node.js 等語言都能快速接入。接入前需要準(zhǔn)備一個(gè)阿里云賬號(hào)并開通百煉服務(wù)。在控制臺(tái)創(chuàng)建 API Key。注意 Key 只顯示一次要立即保存。確定調(diào)用模型名。常見的有 qwen-plus、qwen-turbo以及工具調(diào)用能力更完整的 qwen-max 等。不同模型名對(duì)應(yīng)的上下文長度和費(fèi)用不同落地前要去百煉控制臺(tái)確認(rèn)最新的模型列表。注意api_key 不要硬編碼在代碼里。學(xué)習(xí)階段可以放環(huán)境變量生產(chǎn)階段必須放到密鑰管理服務(wù)或者配置中心。2.2 方式二把 Qwen 部署到自己的服務(wù)器如果業(yè)務(wù)有數(shù)據(jù)隔離要求或者調(diào)用量很大、長期使用可以考慮在自有服務(wù)器上部署 Qwen 開源模型。Qwen 提供了多個(gè)參數(shù)規(guī)模的開源版本。參數(shù)越小部署越容易但能力越弱參數(shù)越大能力越強(qiáng)對(duì) GPU 顯存要求越高。以常見情況為例模型規(guī)模顯存需求示例適用場景小參數(shù)模型消費(fèi)級(jí)顯卡或小顯存實(shí)例學(xué)習(xí)、原型驗(yàn)證、簡單問答中等規(guī)模單張企業(yè)級(jí) GPU專業(yè)問答、代碼生成大規(guī)模模型多卡部署或分布式推理復(fù)雜推理、工具調(diào)用、生產(chǎn)環(huán)境本地部署需要額外處理模型下載、推理框架、GPU 驅(qū)動(dòng)、并發(fā)排隊(duì)等問題。建議先在開發(fā)機(jī)跑通再遷移到云端 GPU 實(shí)例。OpenAI 兼容層的部署配置以官方部署文檔為準(zhǔn)不要憑記憶猜測版本參數(shù)。2.3 方式三Java 項(xiàng)目里配置阿里云 Maven 倉庫和 Spring Initializr如果項(xiàng)目是 Java 技術(shù)棧第一個(gè)遇到的問題常常不是代碼而是依賴下載。在 Maven 的 settings.xml 中配置阿里云鏡像倉庫可以顯著提升依賴?yán)∷俣萴irror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共倉庫/name urlhttps://maven.aliyun.com/repository/public/url /mirror這段配置的作用是把原本從中央倉庫拉取的依賴改從國內(nèi)鏡像拉取。需要注意的是鏡像倉庫只是下載源不改變依賴的坐標(biāo)和版本。不同團(tuán)隊(duì)還可能使用私服這時(shí)要結(jié)合私服策略調(diào)整mirrorOf避免所有倉庫都被鏡像接管。新建 Spring Boot 項(xiàng)目時(shí)也可以使用阿里云的 Spring Initializr 服務(wù)地址https://start.aliyun.com 。它提供的是經(jīng)過阿里云適配的初始化模板適合需要快速生成標(biāo)準(zhǔn)工程的情況。如果團(tuán)隊(duì)內(nèi)部有統(tǒng)一腳手架優(yōu)先使用內(nèi)部版本。2.4 三種接入方式的對(duì)比接入方式成本數(shù)據(jù)控制部署難度推薦場景百煉 API按調(diào)用量計(jì)費(fèi)數(shù)據(jù)經(jīng)云服務(wù)處理低快速原型、中小規(guī)模、開發(fā)測試自建部署硬件加運(yùn)維成本數(shù)據(jù)留在自己環(huán)境高數(shù)據(jù)隔離、大規(guī)模長期調(diào)用Java 生態(tài)集成與接入方式疊加與接入方式相關(guān)中已有 Spring Boot 體系接入方式之間不是互斥的。常見做法是開發(fā)環(huán)境用百煉 API 快速跑通生產(chǎn)環(huán)境根據(jù)數(shù)據(jù)合規(guī)和成本評(píng)估是否遷移到自建部署。遷移時(shí)代碼層盡量使用兼容接口讓切換成本降到最低。3. 跑通最小問答鏈路3.1 最小 Python 示例先跑通一個(gè)最小的問答鏈路再談智能體。這里使用 Python 的 openai SDK通過兼容模式訪問百煉import os from openai import OpenAI client OpenAI( api_keyos.getenv(DASHSCOPE_API_KEY), base_urlhttps://dashscope.aliyuncs.com/compatible-mode/v1 ) response client.chat.completions.create( modelqwen-plus, messages[ {role: system, content: 你是一名經(jīng)驗(yàn)豐富的 Java 架構(gòu)師。}, {role: user, content: 用三句話解釋什么是 Function Calling。} ], temperature0.7, max_tokens512 ) print(response.choices[0].message.content)運(yùn)行前確認(rèn)兩點(diǎn)第一環(huán)境變量 DASHSCOPE_API_KEY 已設(shè)置第二網(wǎng)絡(luò)環(huán)境能訪問 base_url。如果網(wǎng)絡(luò)策略禁用了外部域名請(qǐng)求需要先確認(rèn)百煉 endpoint 是否在訪問白名單里。3.2 關(guān)鍵參數(shù)說明參數(shù)含義常見取值調(diào)大影響調(diào)小影響temperature采樣隨機(jī)性0.0 到 1.0回答更多樣可能不穩(wěn)定回答更確定偏向保守top_p核采樣比例0.1 到 1.0候選詞更多候選詞更集中max_tokens單次最大生成 token 數(shù)128 到 4096按模型輸出更長成本更高輸出可能被截?cái)鄊essages對(duì)話消息列表按角色排列上下文更完整但可能超限上下文不足可能導(dǎo)致遺忘在函數(shù)調(diào)用場景里temperature 建議設(shè)置得低一些例如 0.2 到 0.4。工具調(diào)用要求模型輸出穩(wěn)定的 JSON 參數(shù)隨機(jī)性太大會(huì)導(dǎo)致參數(shù)格式錯(cuò)誤或參數(shù)值漂移。3.3 運(yùn)行和驗(yàn)證運(yùn)行上面的腳本正常情況下會(huì)輸出一段關(guān)于 Function Calling 的解釋。這里要驗(yàn)證的不只是“有輸出”而是輸出是否滿足要求?？梢砸来悟?yàn)證修改 system 提示詞觀察回答風(fēng)格是否變化。修改 temperature比較同一問題的穩(wěn)定性和多樣性。故意給一個(gè)超出 max_tokens 的復(fù)雜問題觀察輸出是否被截?cái)嗖⒗斫馊绾瓮ㄟ^流式輸出解決。這一步能幫你確認(rèn) API Key、網(wǎng)絡(luò)、模型名、參數(shù)四條鏈路都正常。如果其中任何一環(huán)有問題后面的智能體代碼都會(huì)失敗所以不要跳過。3.4 這一步最常見的坑第一個(gè)坑是模型名寫錯(cuò)。不同區(qū)域、不同賬號(hào)可能支持的模型名不同報(bào)錯(cuò)信息里會(huì)顯示類似 model not found 的提示。處理方式是去百煉控制臺(tái)查看支持列表不要憑記憶猜測。第二個(gè)坑是 API Key 設(shè)置錯(cuò)誤。常見現(xiàn)象是 401 或 InvalidApiKey。檢查環(huán)境變量是否真的傳入了進(jìn)程可以在腳本里打印 Key 的前幾位和后幾位用于確認(rèn)但不要完整打印。第三個(gè)坑是把 max_tokens 設(shè)太小。問答內(nèi)容稍長就會(huì)被截?cái)嗫雌饋硐瘛盎卮鸩煌暾?。?shí)際上模型輸出被強(qiáng)制停止了需要調(diào)大 max_tokens 或改用流式輸出。4. Function Calling問答升級(jí)為智能體的核心機(jī)制4.1 為什么模型本身不能直接調(diào)用工具模型是一個(gè)文本生成器它沒有權(quán)限訪問你的系統(tǒng)也不會(huì)連接外部服務(wù)。所謂 Function Calling本質(zhì)是“模型決定要調(diào)用哪個(gè)工具并生成調(diào)用參數(shù)”真正執(zhí)行工具的是你的代碼。模型輸出的不是最終答案而是一個(gè)結(jié)構(gòu)化的“調(diào)用請(qǐng)求”。因此實(shí)現(xiàn)工具調(diào)用必須有兩部分一部分是向模型聲明“你有這些工具可用每個(gè)工具的參數(shù)長什么樣”另一部分是程序端執(zhí)行工具后把結(jié)果以新的消息形式回傳給模型讓模型生成最終回答。缺了任意一部分工具調(diào)用都無法成立。4.2 工具定義的 JSON Schema向模型聲明工具時(shí)通常使用 JSON Schema 描述每個(gè)工具的名稱、描述、參數(shù)類型和必填項(xiàng)。描述寫得越清楚模型越不容易選錯(cuò)工具。下面是一個(gè)查詢訂單狀態(tài)的工具定義{ type: function, function: { name: query_order_status, description: 根據(jù)訂單號(hào)查詢訂單當(dāng)前狀態(tài)。只有用戶明確提供了訂單號(hào)時(shí)才調(diào)用。, parameters: { type: object, properties: { order_id: { type: string, description: 用戶提供的訂單號(hào)例如 OD202501010001 } }, required: [order_id] } } }注意幾個(gè)細(xì)節(jié)description 里要說明“何時(shí)調(diào)用”和“何時(shí)不調(diào)用”required 里明確必填參數(shù)參數(shù)類型盡量精確避免讓模型自行猜測。工具定義本身是 prompt 的一部分也會(huì)占用上下文 token因此不要無限制地加工具只保留當(dāng)前任務(wù)真正需要的。4.3 一個(gè)帶工具循環(huán)的智能體實(shí)現(xiàn)下面用 Python 寫一個(gè)最簡智能體循環(huán)。流程是用戶提問 - 模型判斷是否調(diào)用工具 - 程序執(zhí)行工具 - 回傳結(jié)果 - 模型生成最終回答。import json import os from openai import OpenAI client OpenAI( api_keyos.getenv(DASHSCOPE_API_KEY), base_urlhttps://dashscope.aliyuncs.com/compatible-mode/v1 ) def query_order_status(order_id: str) - str: # 實(shí)際項(xiàng)目中這里會(huì)調(diào)用內(nèi)部訂單服務(wù) return f訂單 {order_id} 的狀態(tài)是已發(fā)貨預(yù)計(jì)明天送達(dá)。 tools [ { type: function, function: { name: query_order_status, description: 根據(jù)訂單號(hào)查詢訂單當(dāng)前狀態(tài), parameters: { type: object, properties: { order_id: { type: string, description: 用戶提供的訂單號(hào) } }, required: [order_id] } } } ] def run_agent(user_message: str, max_steps: int 3) - str: messages [ {role: system, content: 你是訂單助手。用戶詢問訂單狀態(tài)時(shí)先調(diào)用工具查詢?cè)儆米匀徽Z言回復(fù)。}, {role: user, content: user_message} ] for step in range(max_steps): response client.chat.completions.create( modelqwen-plus, messagesmessages, toolstools, tool_choiceauto ) message response.choices[0].message if message.tool_calls: messages.append({ role: assistant, tool_calls: [ { id: tc.id, type: function, function: { name: tc.function.name, arguments: tc.function.arguments } } for tc in message.tool_calls ] }) for tc in message.tool_calls: args json.loads(tc.function.arguments) result query_order_status(args[order_id]) messages.append({ role: tool, tool_call_id: tc.id, content: result }) else: return message.content return 已達(dá)到最大執(zhí)行步數(shù)無法完成用戶的請(qǐng)求。 print(run_agent(幫我查一下訂單 OD202501010001 到哪了))這段代碼有四個(gè)關(guān)鍵點(diǎn)每輪請(qǐng)求都要把之前的消息完整傳給模型尤其是 tool 調(diào)用結(jié)果。模型需要看到工具返回內(nèi)容才能繼續(xù)推理。程序執(zhí)行工具后必須使用 tool 角色并帶上 tool_call_id與模型輸出的工具調(diào)用請(qǐng)求一一對(duì)應(yīng)。max_steps 是循環(huán)上限防止智能體在工具間反復(fù)橫跳消耗大量調(diào)用成本。每個(gè)工具內(nèi)部要做好異常處理。工具拋異常時(shí)要把錯(cuò)誤信息回傳給模型讓模型決定是換參數(shù)重試還是給用戶一個(gè)合理答復(fù)而不是直接讓整個(gè)程序崩潰。注意不要把工具返回結(jié)果原樣無限制地回填給模型。工具返回的可能是大段 JSON 或長文本回填前要按需裁剪字段控制上下文 token 消耗。4.4 工具調(diào)用流程里最容易出錯(cuò)的地方工具參數(shù)解析很容易踩坑。模型輸出的 arguments 是 JSON 字符串但有時(shí)包含多余空格、換行甚至缺失字段。建議使用寬松解析方式解析失敗時(shí)回退到正則提取并把整段原文記錄下來方便排查。另外一個(gè)常見問題是工具描述不明確導(dǎo)致模型在不需要工具時(shí)也調(diào)用工具。比如用戶只是閑聊“你好”模型不該去查訂單。解決方式是在工具描述里增加觸發(fā)條件并在 system 提示詞里明確“只有用戶提供訂單號(hào)時(shí)才調(diào)用查詢工具”。還需要注意 tool_choice 參數(shù)。默認(rèn) auto 讓模型自己決定是否調(diào)用工具如果業(yè)務(wù)想強(qiáng)制模型必須調(diào)用某個(gè)工具可以設(shè)為指定工具名。但強(qiáng)制調(diào)用會(huì)犧牲模型的判斷能力一般只在不需要判斷的場景使用。5. 給智能體加上記憶Qwen Embedding Milvus 檢索5.1 什么時(shí)候需要外部記憶智能體在對(duì)話中會(huì)產(chǎn)生兩類記憶需求。第一類是會(huì)話內(nèi)的短期記憶通過把歷史 messages 傳入模型來實(shí)現(xiàn)。第二類是跨會(huì)話的長期記憶比如企業(yè)知識(shí)庫、歷史工單、產(chǎn)品文檔。這些內(nèi)容不可能全部塞進(jìn)模型上下文因?yàn)?token 有限且成本高所以需要先做檢索只把最相關(guān)的片段注入提示詞。當(dāng)出現(xiàn)以下信號(hào)時(shí)就該接入外部記憶用戶問題涉及私有文檔、內(nèi)部知識(shí)模型訓(xùn)練時(shí)沒有見過。用戶問題需要綜合多份文檔才能回答。智能體每次回答前都需要相同背景材料重復(fù)寫入提示詞太浪費(fèi)。希望通過業(yè)務(wù)數(shù)據(jù)生成個(gè)性化回答而不是每次從頭問起。5.2 RAG 工作流程檢索增強(qiáng)生成Retrieval-Augmented Generation的流程分兩步。第一步是離線準(zhǔn)備把業(yè)務(wù)文檔切分成片段對(duì)每個(gè)片段生成向量寫入向量數(shù)據(jù)庫。第二步是在線檢索用戶提問時(shí)先生成問題的向量再在向量數(shù)據(jù)庫中查找最相似的片段把片段作為上下文拼到消息里最后讓模型生成回答。切分是決定效果的關(guān)鍵。切得太大會(huì)引入無關(guān)內(nèi)容切得太小會(huì)讓語義不完整。常見做法是按標(biāo)題和段落語義切分每個(gè)片段控制在幾百 token 左右同時(shí)保留來源信息方便回答時(shí)溯源。5.3 Java LangChain4j Milvus 接入示例在 Java 技術(shù)棧里可以使用 LangChain4j 簡化向量檢索的接入。LangChain4j 提供統(tǒng)一 API屏蔽了向量數(shù)據(jù)庫的差異。下面是一個(gè)示例 Maven 依賴片段dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version${langchain4j.version}/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-milvus/artifactId version${langchain4j.version}/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version${langchain4j.version}/version /dependency版本號(hào)${langchain4j.version}需要替換為你實(shí)際使用的穩(wěn)定版本并且要與 Spring Boot 版本兼容。依賴下載前確認(rèn) Maven 鏡像配置已生效。寫入和檢索的示例結(jié)構(gòu)如下EmbeddingModel embeddingModel OpenAiEmbeddingModel.builder() .baseUrl(https://dashscope.aliyuncs.com/compatible-mode/v1) .apiKey(System.getenv(DASHSCOPE_API_KEY)) .modelName(text-embedding-v3) .build(); MilvusEmbeddingStore embeddingStore MilvusEmbeddingStore.builder() .host(127.0.0.1) .port(19530) .collectionName(qwen_agent_kb) .dimension(1024) .build();先把文檔片段轉(zhuǎn)成向量并寫入再在回答時(shí)按相似度檢索。這里要注意 dimension向量維度必須與 Embedding 模型輸出的維度一致不一致時(shí)寫入會(huì)報(bào)維度錯(cuò)誤。embedding 模型名和維度參數(shù)在不同階段可能調(diào)整落地前以當(dāng)前 API 文檔為準(zhǔn)。5.4 集合設(shè)計(jì)和檢索參數(shù)字段作用推薦設(shè)置collectionName知識(shí)庫集合名按業(yè)務(wù)域命名如 order_kb、policy_kbdimension向量維度與 embedding 模型輸出一致metricType相似度算法常用 COSINE 或 IP按數(shù)據(jù)特點(diǎn)選擇id主鍵使用業(yè)務(wù)側(cè)生成的唯一 IDcontent原始文本保存原文方便回填上下文metadata元數(shù)據(jù)來源、時(shí)間、權(quán)限域便于過濾檢索時(shí)還需要設(shè)置 topK 和相似度閾值。topK 控制返回片段數(shù)量一般取 3 到 10。閾值過嚴(yán)會(huì)漏掉相關(guān)內(nèi)容過松會(huì)引入噪音。不要只看 topK建議同時(shí)輸出得分人工抽樣評(píng)估一次找到當(dāng)前文檔集的合理閾值。6. 運(yùn)行驗(yàn)證和常見問題排查6.1 一套可復(fù)用的驗(yàn)證順序智能體項(xiàng)目上線前建議按這個(gè)順序驗(yàn)證單次問答是否正常不攜帶工具時(shí)基本問答能正確返回。工具聲明是否生效輸入一個(gè)明確需要工具的提問確認(rèn)模型輸出了 tool_calls。工具執(zhí)行是否正確查看程序?qū)嶋H調(diào)用了哪個(gè)函數(shù)傳參是否合理。工具結(jié)果回填是否成功確認(rèn) tool 角色的消息帶上了正確的 tool_call_id。最終回答是否基于工具結(jié)果檢查回答內(nèi)容是否引用了工具返回的數(shù)據(jù)而不是模型自己編造。異常分支是否可控工具拋錯(cuò)、模型連續(xù)調(diào)用工具、上下文超限時(shí)程序是否能優(yōu)雅退出。6.2 問題現(xiàn)象、原因和處理表問題現(xiàn)象常見原因檢查方式處理建議模型回答完全不調(diào)用工具工具未傳入、描述不清、模型不支持打印請(qǐng)求中的 tools 字段檢查 model 名確認(rèn)傳入 tools增強(qiáng) description換支持工具調(diào)用的模型工具調(diào)用了但程序沒執(zhí)行只把工具發(fā)給模型沒有寫執(zhí)行分支檢查代碼是否解析了 message.tool_calls補(bǔ)上 for 循環(huán)執(zhí)行工具的邏輯工具結(jié)果回傳后模型仍錯(cuò)答tool_call_id 不匹配或消息順序錯(cuò)誤打印 messages 列表檢查角色確保 tool 消息緊跟對(duì)應(yīng)的 assistant tool_calls 消息上下文超限歷史消息或工具結(jié)果越來越大查看報(bào)錯(cuò)信息中的 token 數(shù)接入摘要機(jī)制裁剪歷史限制工具返回長度參數(shù)解析失敗模型輸出非法 JSON打印原始 arguments增加容錯(cuò)解析記錄原文定位模型輸出問題檢索結(jié)果與問題無關(guān)切分粒度差、embedding 不匹配、閾值不對(duì)單獨(dú)跑檢索用例檢查召回優(yōu)化切分、重選 embedding 模型、調(diào)整閾值6.3 排查鏈路遇到問題按鏈路從下往上排網(wǎng)絡(luò)和 Key先確認(rèn) base_url 可達(dá)API Key 有效。請(qǐng)求參數(shù)打印完整請(qǐng)求體逐字段確認(rèn) tools、messages、model 是否符合預(yù)期。模型返回查看原始響應(yīng)區(qū)分是沒生成 tool_calls還是生成了