智能體實(shí)戰(zhàn)：從對(duì)話到行動(dòng)的FunctionGemma方案)
把大模型真正用起來(lái)之后我發(fā)現(xiàn)一個(gè)很明顯的分水嶺會(huì)聊天的模型很多會(huì)干活的模型很少。大部分時(shí)候我們打開(kāi)一個(gè)助手問(wèn)它“明天天氣怎么樣”它只會(huì)生成一段“天氣可能不太好建議帶傘”的漂亮話而不是真的去查接口、拉數(shù)據(jù)、設(shè)置提醒。這個(gè)差距就是從“對(duì)話”到“行動(dòng)”的距離。FunctionGemma 就是我在做端側(cè)智能體時(shí)重點(diǎn)嘗試的一套方案它把函數(shù)調(diào)用能力直接內(nèi)建到輕量級(jí)模型里讓模型不僅能理解意圖還能輸出結(jié)構(gòu)化的函數(shù)調(diào)用指令然后由本機(jī)執(zhí)行器完成實(shí)際操作。這篇文章我會(huì)從模型原理、端側(cè)部署、代碼實(shí)現(xiàn)和調(diào)優(yōu)經(jīng)驗(yàn)四個(gè)方面把完整鏈路拆開(kāi)聊清楚。文章面向的讀者是正在做端側(cè) AI 應(yīng)用、智能體框架或者本地助手的開(kāi)發(fā)者。哪怕你還沒(méi)系統(tǒng)接觸過(guò)函數(shù)調(diào)用只要有一點(diǎn)大模型推理的基礎(chǔ)跟著后面的代碼走一遍也能在本地搭出一個(gè)能查時(shí)間、記備忘錄、發(fā)通知的小智能體。我會(huì)盡量說(shuō)人話把那些文檔里不會(huì)寫(xiě)的坑也一并擺出來(lái)。1. 端側(cè)智能體到底難在哪為什么“會(huì)聊天”不等于“會(huì)行動(dòng)”1.1 對(duì)話模型的天然邊界先看一個(gè)最典型的場(chǎng)景。你問(wèn)一個(gè)純對(duì)話模型“幫我把明天上午十點(diǎn)的會(huì)議改成十一點(diǎn)?！彼鼤?huì)怎么回大概率是“好的建議您前往日歷應(yīng)用手動(dòng)修改。”這句回答看似禮貌實(shí)際上什么都沒(méi)做。原因很簡(jiǎn)單普通語(yǔ)言模型的能力邊界在“生成文本”它沒(méi)有一個(gè)可以去操作日歷的“手”。LLM 本質(zhì)上是在給定上文的前提下預(yù)測(cè)下一個(gè) token。它知道日歷是什么甚至知道很多改日程的步驟但它沒(méi)有權(quán)限、沒(méi)有接口、也沒(méi)有執(zhí)行環(huán)境。想讓它真正干活就必須在模型外面接一層“工具層”。這一步在云端相對(duì)容易畢竟服務(wù)器可以隨便調(diào)接口、跑代碼。但到了手機(jī)、路由器、車(chē)載終端、嵌入式設(shè)備上問(wèn)題立刻變復(fù)雜算力有限、內(nèi)存吃緊、網(wǎng)絡(luò)不穩(wěn)定、隱私要求高。你不能指望設(shè)備端拖一個(gè)幾百億參數(shù)的模型再依賴云端反饋。端側(cè)智能體真正需要的是一個(gè)小、快、準(zhǔn)的本地“行動(dòng)派”模型而不是一個(gè)只會(huì)嘴上說(shuō)說(shuō)的“評(píng)論員”。1.2 函數(shù)調(diào)用把“意圖”變成“指令”函數(shù)調(diào)用function calling是當(dāng)前把大模型變成行動(dòng)體的最主流方案。核心思路很簡(jiǎn)單模型不直接執(zhí)行動(dòng)作而是輸出一個(gè)結(jié)構(gòu)化指令比如create_event(title項(xiàng)目評(píng)審, time2025-06-10 10:00)真正的執(zhí)行交給本地代碼。這樣做有四個(gè)好處可解釋模型只負(fù)責(zé)“決定做什么”每一步動(dòng)作都是明確的函數(shù)名和參數(shù)。可控制執(zhí)行前可以做權(quán)限校驗(yàn)、參數(shù)校驗(yàn)不讓模型亂來(lái)?？苫貪L如果某次調(diào)用產(chǎn)生了壞結(jié)果很容易定位到是哪個(gè)函數(shù)、什么參數(shù)出問(wèn)題。可擴(kuò)展新增能力只需要注冊(cè)一個(gè)新函數(shù)不需要重新訓(xùn)練模型。還是用改日程舉例用戶說(shuō)“把明天的會(huì)改到十一點(diǎn)”模型并不直接操作日歷數(shù)據(jù)庫(kù)它輸出reschedule_event(event_idevent_123, new_time11:00)。本機(jī)代碼拿到這個(gè)指令后再調(diào)用系統(tǒng)日歷 API 完成修改。這樣一來(lái)模型依然是模型動(dòng)作卻真正發(fā)生了。1.3 FunctionGemma 解決的三個(gè)核心問(wèn)題FunctionGemma 是一類(lèi)面向端側(cè)場(chǎng)景的輕量級(jí)工具調(diào)用模型方案。我不把它理解成某個(gè)單獨(dú)模型而是一條“訓(xùn)練策略 推理協(xié)議 端側(cè)執(zhí)行框架”的組合。它重點(diǎn)解決三個(gè)問(wèn)題。第一是輕量化。參數(shù)規(guī)模壓縮到端側(cè)能扛住的范圍同時(shí)通過(guò)定向訓(xùn)練把“工具調(diào)用”這個(gè)能力突出強(qiáng)化而不是像通用模型那樣什么都會(huì)一點(diǎn)、什么都不精。第二是結(jié)構(gòu)化輸出穩(wěn)定。純對(duì)話模型輸出 JSON 經(jīng)常缺括號(hào)、多字、字段名漂移。FunctionGemma 在訓(xùn)練階段使用了大量工具調(diào)用樣本并配合特殊 token 標(biāo)記函數(shù)調(diào)用段讓輸出格式的穩(wěn)定性比通用模型高一個(gè)量級(jí)。第三是多輪工具狀態(tài)感知。真實(shí)智能體不可能只調(diào)用一次函數(shù)。用戶查完天氣可能接著問(wèn)“那明天呢”這時(shí)候模型必須能結(jié)合上一次工具返回結(jié)果繼續(xù)推理。FunctionGemma 的訓(xùn)練數(shù)據(jù)里包含了多輪工具結(jié)果回填樣本所以它知道什么時(shí)候該繼續(xù)調(diào)、什么時(shí)候該給最終答復(fù)。2. FunctionGemma 是怎么設(shè)計(jì)出來(lái)的原理與運(yùn)行機(jī)制2.1 模型架構(gòu)與訓(xùn)練對(duì)象不去糾結(jié)底層實(shí)現(xiàn)細(xì)節(jié)從功能視角看FunctionGemma 的底座是一個(gè)標(biāo)準(zhǔn)的 Decoder-Only 輕量語(yǔ)言模型參數(shù)檔位從 1B 到 4B 不等。它要做的事情是在常規(guī)對(duì)話能力之上額外學(xué)會(huì)一種“工具調(diào)用方言”。訓(xùn)練數(shù)據(jù)混合了三類(lèi)多輪對(duì)話數(shù)據(jù)保證模型仍然能正常聊天、總結(jié)、問(wèn)答。函數(shù)調(diào)用數(shù)據(jù)用戶在某一輪提出請(qǐng)求模型在回復(fù)中插入一個(gè)特殊標(biāo)記比如function_call后面跟著 JSON 形式的函數(shù)名和參數(shù)。工具結(jié)果回填數(shù)據(jù)上一輪調(diào)用了函數(shù)這一輪的輸入是function_result模型需要基于這個(gè)結(jié)果生成最終回復(fù)或者繼續(xù)發(fā)起下一個(gè)函數(shù)調(diào)用。為什么要把函數(shù)調(diào)用訓(xùn)練成一種“方言”而不是靠提示詞現(xiàn)場(chǎng)學(xué)會(huì)因?yàn)槎藗?cè)模型參數(shù)少泛化能力有限。如果你只是臨時(shí)在系統(tǒng)提示詞里貼幾個(gè)函數(shù)定義小模型很容易學(xué)會(huì)“讀題”卻很難學(xué)會(huì)“寫(xiě)標(biāo)準(zhǔn)格式”。只有把大量同類(lèi)樣本灌進(jìn)訓(xùn)練過(guò)程模型才會(huì)把“看到用戶請(qǐng)求→判斷可調(diào)函數(shù)→輸出 JSON 指令”這一鏈路變成一種條件反射。2.2 函數(shù)描述注入與結(jié)構(gòu)化輸出你可能會(huì)好奇模型怎么知道有哪些函數(shù)可以調(diào)答案跟提示工程有關(guān)。推理時(shí)我們會(huì)把當(dāng)前可用的函數(shù)列表轉(zhuǎn)成 JSON Schema 格式拼到系統(tǒng)提示詞里。一個(gè)典型的函數(shù)聲明長(zhǎng)這樣{ name: create_memo, description: 創(chuàng)建一條本地備忘錄適合記錄臨時(shí)想法和待辦事項(xiàng), parameters: { type: object, properties: { title: { type: string, description: 備忘錄標(biāo)題盡量簡(jiǎn)潔 }, content: { type: string, description: 備忘錄正文內(nèi)容 } }, required: [title, content] } }這段描述不是給機(jī)器看的機(jī)器其實(shí)不“理解”自然語(yǔ)言的全部含義它是給模型的注意力機(jī)制做引導(dǎo)的。描述寫(xiě)得越具體模型越容易在需要的時(shí)候選擇這個(gè)函數(shù)而不是搞混參數(shù)。結(jié)構(gòu)化輸出則通過(guò)兩重機(jī)制保證。第一重是訓(xùn)練記憶模型見(jiàn)多了function_call的格式自然會(huì)模仿。第二重是推理后處理如果模型輸出的 JSON 不夠規(guī)整代碼層可以做一次容錯(cuò)解析比如提取方括號(hào)里的文本、修復(fù)缺失的尾括號(hào)、把單引號(hào)轉(zhuǎn)成雙引號(hào)。這兩重機(jī)制缺一不可。2.3 一次完整調(diào)用鏈路的六個(gè)階段端側(cè)智能體不是把函數(shù)定義拼進(jìn)去就算完真正跑起來(lái)之后每一步都是一段可復(fù)用的邏輯。我把完整鏈路拆成六個(gè)階段構(gòu)造請(qǐng)求把系統(tǒng)提示詞、函數(shù)聲明、對(duì)話歷史、當(dāng)前問(wèn)題拼成一個(gè) prompt。模型推理由 FunctionGemma 生成結(jié)果結(jié)果可能是一次文本回復(fù)也可能是一次函數(shù)調(diào)用。解析輸出識(shí)別function_call標(biāo)記嘗試提取 JSON判斷格式是否合法。校驗(yàn)指令檢查函數(shù)名是否白名單、參數(shù)是否匹配 schema、必填字段是否齊全。執(zhí)行函數(shù)調(diào)用本地函數(shù)拿到返回值轉(zhuǎn)成字符串或 JSON。回填結(jié)果把工具返回值以tool角色追加到對(duì)話里再送進(jìn)模型做下一輪推理直到模型給出最終回復(fù)。這個(gè)循環(huán)不是無(wú)限的。我會(huì)在工程實(shí)現(xiàn)里設(shè)置一個(gè)最大輪次比如 4 到 6 次。一旦超過(guò)就返回“我還沒(méi)能完成這個(gè)任務(wù)請(qǐng)換個(gè)說(shuō)法再試一次”。這樣做是為了防止模型因?yàn)槟硞€(gè)函數(shù)始終報(bào)錯(cuò)而無(wú)限重試?yán)速M(fèi)端側(cè)電力。3. 實(shí)操用 FunctionGemma 在本地搭一個(gè)可行動(dòng)的智能體3.1 準(zhǔn)備運(yùn)行環(huán)境與模型文件動(dòng)手之前先把環(huán)境準(zhǔn)備好。我默認(rèn)你手頭有一臺(tái)普通開(kāi)發(fā)機(jī)CPU 能跑、內(nèi)存 8G 以上就可以。如果你是做部署到手機(jī)或嵌入式設(shè)備步驟類(lèi)似只是需要先把模型量化成更小的文件。建議的準(zhǔn)備項(xiàng)Python 3.10裝好 json、re、datetime 等標(biāo)準(zhǔn)庫(kù)以及一個(gè)支持端側(cè)模型推理的引擎接口。從模型倉(cāng)庫(kù)拿一個(gè)量化好的 FunctionGemma 權(quán)重文件優(yōu)先選 int4 或 int8 的 GGUF 格式體積小、CPU 也能跑。把權(quán)重文件放到固定目錄比如models/functiongemma-2b-int4.gguf。初始化推理引擎時(shí)重點(diǎn)設(shè)置兩個(gè)參數(shù)上下文長(zhǎng)度和線程數(shù)。上下文長(zhǎng)度建議先給 2048太小容易截?cái)喽噍喒ぞ呓Y(jié)果太大內(nèi)存占用會(huì)直線上升。線程數(shù)設(shè)成 CPU 核心數(shù)的一半左右避免推理時(shí)整個(gè)設(shè)備卡死。3.2 定義本地工具集第一步先把“智能體能做什么”定下來(lái)。做端側(cè)智能體最忌諱一上來(lái)就想做全知全能先選三五個(gè)高頻、確定、可驗(yàn)證的工具。我在這里定義一組很實(shí)用的工具獲取當(dāng)前時(shí)間、創(chuàng)建本地備忘錄、發(fā)送系統(tǒng)通知。代碼很簡(jiǎn)單import json from datetime import datetime def get_local_time() - str: 獲取當(dāng)前本地時(shí)間 return datetime.now().isoformat() def create_memo(title: str, content: str) - bool: 把備忘錄寫(xiě)入本地文件 memo {title: title, content: content, created_at: datetime.now().isoformat()} with open(memos.json, a, encodingutf-8) as f: f.write(json.dumps(memo, ensure_asciiFalse) \n) return True def send_notification(title: str, message: str) - bool: 發(fā)送一條本地系統(tǒng)通知 # 這里對(duì)接平臺(tái)通知接口演示時(shí)先返回 True print(f[通知] {title}: {message}) return True TOOL_REGISTRY { get_local_time: get_local_time, create_memo: create_memo, send_notification: send_notification, }注意一個(gè)工程細(xì)節(jié)TOOL_REGISTRY的 key 必須和函數(shù)聲明里的name完全一致執(zhí)行層只認(rèn)這個(gè)注冊(cè)表不認(rèn)模型輸出里的名字。這樣做的好處是即使模型偶爾輸出一個(gè)不存在的函數(shù)名執(zhí)行層也能立刻攔截而不是傻乎乎地報(bào)錯(cuò)。3.3 構(gòu)造函數(shù)聲明與系統(tǒng)提示詞函數(shù)聲明列表作為模型可參考的“工具手冊(cè)”。前面已經(jīng)展示了單個(gè)函數(shù)的 JSON Schema實(shí)際使用時(shí)會(huì)拼成一個(gè)數(shù)組。系統(tǒng)提示詞我通常這樣寫(xiě)SYSTEM_PROMPT 你是一個(gè)運(yùn)行在本地設(shè)備上的智能助手。 你可以使用以下工具完成用戶請(qǐng)求但不要虛構(gòu)不存在的函數(shù)。 當(dāng)用戶請(qǐng)求需要調(diào)用工具時(shí)請(qǐng)嚴(yán)格按照下面的格式輸出 function_call{name: 函數(shù)名, arguments: {參數(shù)名: 參數(shù)值}}/function_call 如果用戶請(qǐng)求不需要工具直接使用自然語(yǔ)言回復(fù)。 FUNCTION_DEFS [ { name: get_local_time, description: 獲取當(dāng)前本地日期和時(shí)間。當(dāng)用戶問(wèn)現(xiàn)在幾點(diǎn)、今天日期時(shí)使用。, parameters: { type: object, properties: {}, required: [] } }, { name: create_memo, description: 把一段文字記錄成本地備忘錄。適用于用戶說(shuō)記一下添加到待辦寫(xiě)個(gè)備忘。, parameters: { type: object, properties: { title: {type: string, description: 簡(jiǎn)短標(biāo)題}, content: {type: string, description: 完整內(nèi)容} }, required: [title, content] } }, { name: send_notification, description: 發(fā)送本地系統(tǒng)通知。適用于用戶要求提醒、通知。, parameters: { type: object, properties: { title: {type: string, description: 通知標(biāo)題}, message: {type: string, description: 通知內(nèi)容} }, required: [title, message] } } ]為什么要單獨(dú)加一句“不要虛構(gòu)不存在的函數(shù)”因?yàn)樾∧Ｐ驮陂_(kāi)放環(huán)境下容易把用戶提到的任何動(dòng)詞都當(dāng)成函數(shù)名。比如用戶說(shuō)“幫我發(fā)個(gè)郵件”模型如果看到?jīng)]有郵件函數(shù)可能會(huì)編一個(gè)send_email出來(lái)。把約束寫(xiě)進(jìn)系統(tǒng)提示詞能顯著減少這類(lèi)幻覺(jué)。3.4 核心推理與執(zhí)行循環(huán)代碼下面這段循環(huán)是整個(gè)智能體的心臟。它負(fù)責(zé)把對(duì)話狀態(tài)、函數(shù)聲明、模型輸出和本地工具串起來(lái)。def build_prompt(messages, function_defs): 把消息列表和函數(shù)聲明拼成模型輸入 system_text SYSTEM_PROMPT \n可用工具:\n json.dumps(function_defs, ensure_asciiFalse) prompt system_text \n for msg in messages: role msg[role] content msg[content] if role user: prompt f\n用戶: {content}\n elif role tool: prompt f\nfunction_result{content}/function_result\n else: prompt f\n系統(tǒng): {content}\n return prompt def parse_function_call(raw_text): 從模型輸出中提取函數(shù)調(diào)用 JSON match re.search(rfunction_call(.*?)/function_call, raw_text, re.DOTALL) if not match: return None try: return json.loads(match.group(1)) except json.JSONDecodeError: return None def execute_function(func_name, func_args): 執(zhí)行本地工具返回 JSON 字符串 if func_name not in TOOL_REGISTRY: return json.dumps({error: f未知函數(shù): {func_name}}) try: result TOOL_REGISTRY[func_name](**func_args) return json.dumps({result: result}, ensure_asciiFalse) except Exception as e: return json.dumps({error: str(e)}) def run_agent(user_question, max_steps4): messages [{role: user, content: user_question}] for _ in range(max_steps): prompt build_prompt(messages, FUNCTION_DEFS) raw_output engine.generate(prompt) action parse_function_call(raw_output) if action is None: # 沒(méi)有函數(shù)調(diào)用視為最終回復(fù) return raw_output func_name action.get(name) func_args action.get(arguments, {}) tool_result execute_function(func_name, func_args) messages.append({role: tool, content: tool_result}) # 繼續(xù)循環(huán)讓模型基于工具結(jié)果生成下一個(gè)動(dòng)作或最終回復(fù) return 已超過(guò)最大工具調(diào)用次數(shù)任務(wù)中斷注意上面代碼里的engine.generate是一個(gè)抽象接口。不同推理引擎的調(diào)用方式不一樣但是整體邏輯完全一致。我建議你先把這段循環(huán)寫(xiě)穩(wěn)再替換成具體的引擎。我見(jiàn)過(guò)太多人一上來(lái)就去調(diào)某個(gè)推理框架的 API反而忽略了智能體本身的調(diào)度邏輯。3.5 部署到低算力設(shè)備的注意點(diǎn)如果目標(biāo)設(shè)備不是 PC而是手機(jī)、開(kāi)發(fā)板這類(lèi)低算力環(huán)境有幾個(gè)點(diǎn)要提前處理。第一量化精度要夠。4bit 量化通常是性價(jià)比最高的選擇模型大小能壓到原來(lái)的三分之一甚至四分之一。但量化后可能會(huì)損失少量工具調(diào)用準(zhǔn)確率所以我建議準(zhǔn)備兩套模型開(kāi)發(fā)調(diào)試用高精度版正式部署用 int4 版。如果在正式版上發(fā)現(xiàn)某個(gè)函數(shù)頻繁選錯(cuò)優(yōu)先回查 schema 描述是否清晰而不是急著換回高精度模型。第二控制上下文長(zhǎng)度。端側(cè)設(shè)備的內(nèi)存是硬約束一次推理能塞進(jìn)去的 token 有限。多輪對(duì)話時(shí)不要無(wú)限追加歷史只保留最近兩到三輪。工具結(jié)果如果很長(zhǎng)先讓模型自己寫(xiě)一個(gè)摘要再拼回上下文而不是把全套 JSON 塞進(jìn)去。第三做好功耗控制。函數(shù)調(diào)用循環(huán)如果設(shè)計(jì)成無(wú)限重試設(shè)備會(huì)長(zhǎng)時(shí)間保持高負(fù)載。我剛才在代碼里加了max_steps限制實(shí)際項(xiàng)目里我還會(huì)再加一條單次任務(wù)總耗時(shí)超過(guò) 10 秒就主動(dòng)結(jié)束并返回到主界面。端側(cè)智能體不能像云端服務(wù)那樣無(wú)限“思考”。4. 調(diào)優(yōu)與避坑把準(zhǔn)確率從“碰運(yùn)氣”抬到“能交付”4.1 函數(shù) Schema 設(shè)計(jì)原則函數(shù)聲明看起來(lái)簡(jiǎn)單真正決定模型能不能調(diào)對(duì)。我總結(jié)了幾條實(shí)用原則。函數(shù)名要?jiǎng)釉~開(kāi)頭像是get_local_time、create_memo不要用time、memo、notification這類(lèi)名詞否則模型區(qū)分不了“查時(shí)間”和“設(shè)置時(shí)間”。描述里要寫(xiě)清楚觸發(fā)條件。不要只寫(xiě)“獲取時(shí)間”要寫(xiě)“用戶問(wèn)現(xiàn)在幾點(diǎn)、當(dāng)前日期時(shí)使用”。端側(cè)模型參數(shù)小對(duì)隱式語(yǔ)義的把握弱描述越直白選擇準(zhǔn)確率越高。參數(shù)必填項(xiàng)越少越好。能用默認(rèn)值就用默認(rèn)值。比如create_memo如果允許省略標(biāo)題就可以把title設(shè)為非必填模型出錯(cuò)的可能性會(huì)降低一個(gè)檔次。一次暴露的函數(shù)數(shù)量要控制。測(cè)試時(shí)我遇到過(guò)模型在 30 個(gè)函數(shù)里反復(fù)猶豫的情況最后把函數(shù)按場(chǎng)景拆成多組根據(jù)用戶第一輪問(wèn)題動(dòng)態(tài)選擇暴露哪一組準(zhǔn)確率立刻上來(lái)。如果設(shè)備只做備忘助手那就別把“控制燈泡”的函數(shù)也塞進(jìn)去。4.2 采樣參數(shù)怎么調(diào)函數(shù)調(diào)用不是創(chuàng)作不需要模型“自由發(fā)揮”。采樣參數(shù)應(yīng)該往確定性方向調(diào)。溫度調(diào)低是首選。0.2 以下通常比較穩(wěn)0.0 則完全貪心。我建議從 0.1 起步如果發(fā)現(xiàn)模型經(jīng)常輸出重復(fù)內(nèi)容再嘗試小幅提高。top_p保持 0.9 到 0.95主要用來(lái)過(guò)濾尾部低概率 token。top_k設(shè)成 20 到 50 之間防止模型在函數(shù)名這種關(guān)鍵位置突然發(fā)散。如果你的推理引擎支持約束解碼一定要用起來(lái)。約束解碼可以限制模型只能按照預(yù)定義的 JSON Schema 生成 token把格式錯(cuò)誤直接扼殺在生成階段。這是當(dāng)前提升函數(shù)調(diào)用成功率最有效的工程手段比任何提示詞技巧都管用。不支持也沒(méi)關(guān)系代碼層做一套健壯的 JSON 解析兜底。4.3 多輪狀態(tài)與上下文裁剪真正跑起來(lái)之后最容易被忽略的是多輪上下文。用戶說(shuō)“現(xiàn)在幾點(diǎn)了”模型調(diào)了get_local_time返回2025-06-10T09:30:00。用戶接著問(wèn)“那一個(gè)小時(shí)后呢”這時(shí)候模型必須能看到剛才的函數(shù)結(jié)果才能計(jì)算10:30。實(shí)現(xiàn)上要記住兩點(diǎn)。第一工具結(jié)果一旦被模型消費(fèi)就不再需要保留原始 JSON?？梢栽诘诙喭评砬鞍呀Y(jié)果壓縮成一句話比如“當(dāng)前時(shí)間是 2025-06-10 09:30:00”然后繼續(xù)拼進(jìn)上下文。這樣既保留了信息又不占 token。第二不要讓工具結(jié)果“污染”新一輪對(duì)話的角色。工具結(jié)果必須以獨(dú)立的tool角色放入消息列表不能拼在 user 消息里。否則模型容易把工具結(jié)果誤當(dāng)成用戶新指令導(dǎo)致角色混亂。我遇到過(guò)好幾次模型在工具返回后突然說(shuō)“好的我會(huì)記住”就是角色沒(méi)分清楚。4.4 安全邊界設(shè)計(jì)讓模型調(diào)用本地函數(shù)等于給外部文本輸入開(kāi)了個(gè)執(zhí)行口子安全必須前置。最基礎(chǔ)的做法是白名單機(jī)制。TOOL_REGISTRY就是白名單所有執(zhí)行入口只能從這里查函數(shù)。永遠(yuǎn)不要讓模型直接執(zhí)行任意 Python 代碼哪怕它“發(fā)誓”只是做個(gè)加法。其次要做參數(shù)校驗(yàn)。函數(shù)名合法不代表參數(shù)合法。create_memo的content如果允許任意字符串那模型可能把用戶輸入的惡意內(nèi)容寫(xiě)進(jìn)文件。文件路徑類(lèi)參數(shù)更要小心絕對(duì)不能讓模型傳一個(gè)../../etc/passwd進(jìn)來(lái)。我會(huì)在每個(gè)函數(shù)內(nèi)部再做一輪自己的校驗(yàn)不依賴模型輸出的正確性。最后是敏感操作二次確認(rèn)。刪除文件、發(fā)送不可撤回的通知、修改系統(tǒng)配置這類(lèi)操作不能模型一說(shuō)就執(zhí)行。要先把待執(zhí)行動(dòng)作展示給用戶確認(rèn)用戶點(diǎn)擊確認(rèn)后再真正調(diào)用。端側(cè)智能體追求效率但安全底線一點(diǎn)不能松。5. 常見(jiàn)問(wèn)題排查實(shí)錄5.1 高頻報(bào)錯(cuò)與對(duì)應(yīng)解法我在做 FunctionGemma 落地時(shí)遇到過(guò)不少問(wèn)題這里整理成一張速查表?，F(xiàn)象可能原因解決思路模型輸出普通文本而不是函數(shù)調(diào)用系統(tǒng)提示詞沒(méi)有說(shuō)清輸出格式或函數(shù)聲明沒(méi)拼進(jìn)去檢查 build_prompt確認(rèn) FUNCTION_DEFS 已拼到系統(tǒng)提示詞中把觸發(fā)條件寫(xiě)得更直白函數(shù)名拼錯(cuò)、多字少字模型對(duì)函數(shù)名的記憶不穩(wěn)定尤其函數(shù)名過(guò)長(zhǎng)函數(shù)名控制在 2-4 個(gè)詞動(dòng)詞開(kāi)頭在提示詞里重復(fù)一遍可用函數(shù)名參數(shù)類(lèi)型錯(cuò)誤比如把數(shù)字寫(xiě)成字符串函數(shù) schema 里沒(méi)有寫(xiě)清楚類(lèi)型檢查函數(shù)定義中的parameters必要時(shí)在描述里補(bǔ)類(lèi)型示例同一函數(shù)被無(wú)限重復(fù)調(diào)用工具結(jié)果沒(méi)有正確回填模型看不到結(jié)果就只能重試檢查messages.append是否正確工具角色是否被截?cái)喙ぞ呓Y(jié)果存在但最終回復(fù)卻沒(méi)有參考它上下文被裁剪或者工具結(jié)果寫(xiě)在了不顯眼的位置增加上下文長(zhǎng)度把最近的工具結(jié)果放在 prompt 最后面推理速度很慢上下文太長(zhǎng)、線程數(shù)太少、模型未量化裁剪歷史調(diào)整線程數(shù)換 int4 量化版本JSON 解析經(jīng)常失敗模型生成時(shí)沒(méi)有約束解碼輸出多余字符優(yōu)化提示詞或者在解析層使用更寬容的 JSON 提取正則表格里面的問(wèn)題我全都真實(shí)踩過(guò)尤其是“工具結(jié)果沒(méi)回填導(dǎo)致重試”那個(gè)月幾乎天天碰到。后來(lái)我加了一行日志專(zhuān)門(mén)打印每次循環(huán)后的完整 prompt問(wèn)題立刻暴露出來(lái)上下文被裁剪時(shí)把工具結(jié)果裁掉了。從那以后我再也沒(méi)讓上下文長(zhǎng)度超過(guò)設(shè)定值。5.2 我的排查順序遇到問(wèn)題不要急著調(diào)模型先按這個(gè)順序排查能省很多時(shí)間。第一步看輸入是不是 prompt 拼接錯(cuò)了。先把每次發(fā)給引擎的完整文本打出來(lái)確認(rèn)函數(shù)聲明、歷史消息、工具結(jié)果都在并且順序合理。這一步能解決一半問(wèn)題。第二步看輸出模型到底生成了什么。把原始 token 序列或原始文本保存下來(lái)不要只看解析后的結(jié)果。很多時(shí)候模型生成的是正確的function_call但你的正則沒(méi)匹配到。第三步看執(zhí)行工具本身有沒(méi)有報(bào)錯(cuò)。給每個(gè)工具寫(xiě)一個(gè)獨(dú)立的單元測(cè)試確認(rèn)get_local_time()確實(shí)返回時(shí)間、create_memo()確實(shí)寫(xiě)入了文件。工具有問(wèn)題再智能的模型也白搭。第四步才回頭調(diào)模型。這時(shí)候再考慮改溫度、改 schema、加少樣本示例。順序反了會(huì)很痛苦我見(jiàn)過(guò)有人花一周時(shí)間調(diào)提示詞最后發(fā)現(xiàn)是個(gè)底層 JSON 解析 bug 導(dǎo)致的。6. 我的幾點(diǎn)實(shí)操體會(huì)做端側(cè)智能體越久越覺(jué)得“從對(duì)話邁向行動(dòng)”這個(gè)說(shuō)法不是一句口號(hào)而是整個(gè)范式轉(zhuǎn)換的本質(zhì)。純對(duì)話模型是知識(shí)引擎重心在“答得好不好”函數(shù)調(diào)用模型是行動(dòng)引擎重心在“做得對(duì)不對(duì)”。FunctionGemma 這類(lèi)方案的真正價(jià)值是把模型體積、工具調(diào)用能力、端側(cè)資源約束放到同一個(gè)天平上做出一個(gè)工程上可用的折中。我自己的體會(huì)有三點(diǎn)值得分享。第一永遠(yuǎn)不要追求全知全能。端側(cè)智能體最適合的場(chǎng)景一定是邊界清晰的垂直場(chǎng)景。我就讓它管備忘錄、查時(shí)間、發(fā)通知三個(gè)函數(shù)用得非常穩(wěn)定。一旦加了太多工具準(zhǔn)確率下降的速度會(huì)超出你的預(yù)期。第二把模型看作“意圖理解器”把本機(jī)代碼看作“安全執(zhí)行器”。模型負(fù)責(zé)判斷用戶想干什么剩下的事情全部由你寫(xiě)的代碼負(fù)責(zé)。這條路比讓模型直接生成代碼安全得多也更容易排查問(wèn)題。第三每一輪工具調(diào)用都要有日志和可復(fù)現(xiàn)性。我在完成函數(shù)調(diào)用后都會(huì)把當(dāng)時(shí)的 prompt、模型輸出、工具結(jié)果完整存一份標(biāo)記為 trace。后續(xù)優(yōu)化模型或調(diào) schema 時(shí)直接回放這些 trace能快速驗(yàn)證改動(dòng)是否有效。這個(gè)習(xí)慣幫我省下了大量回歸測(cè)試的時(shí)間。最后再分享一個(gè)小技巧。剛開(kāi)始調(diào)通智能體時(shí)可以故意在用戶請(qǐng)求里塞一些模棱兩可的話比如“隨便記一下”“提醒我明天”觀察模型是調(diào)用工具還是亂猜。只要把這類(lèi)邊界情況覆蓋到端側(cè)智能體才算真正從“能跑”進(jìn)化到“能用”。 端側(cè)智能體實(shí)戰(zhàn)：從對(duì)話到行動(dòng)的FunctionGemma方案
把大模型真正用起來(lái)之后我發(fā)現(xiàn)一個(gè)很明顯的分水嶺會(huì)聊天的模型很多會(huì)干活的模型很少。大部分時(shí)候我們打開(kāi)一個(gè)助手問(wèn)它“明天天氣怎么樣”它只會(huì)生成一段“天氣可能不太好建議帶傘”的漂亮話而不是真的去查接口、拉數(shù)據(jù)、設(shè)置提醒。這個(gè)差距就是從“對(duì)話”到“行動(dòng)”的距離。FunctionGemma 就是我在做端側(cè)智能體時(shí)重點(diǎn)嘗試的一套方案它把函數(shù)調(diào)用能力直接內(nèi)建到輕量級(jí)模型里讓模型不僅能理解意圖還能輸出結(jié)構(gòu)化的函數(shù)調(diào)用指令然后由本機(jī)執(zhí)行器完成實(shí)際操作。這篇文章我會(huì)從模型原理、端側(cè)部署、代碼實(shí)現(xiàn)和調(diào)優(yōu)經(jīng)驗(yàn)四個(gè)方面把完整鏈路拆開(kāi)聊清楚。文章面向的讀者是正在做端側(cè) AI 應(yīng)用、智能體框架或者本地助手的開(kāi)發(fā)者。哪怕你還沒(méi)系統(tǒng)接觸過(guò)函數(shù)調(diào)用只要有一點(diǎn)大模型推理的基礎(chǔ)跟著后面的代碼走一遍也能在本地搭出一個(gè)能查時(shí)間、記備忘錄、發(fā)通知的小智能體。我會(huì)盡量說(shuō)人話把那些文檔里不會(huì)寫(xiě)的坑也一并擺出來(lái)。1. 端側(cè)智能體到底難在哪為什么“會(huì)聊天”不等于“會(huì)行動(dòng)”1.1 對(duì)話模型的天然邊界先看一個(gè)最典型的場(chǎng)景。你問(wèn)一個(gè)純對(duì)話模型“幫我把明天上午十點(diǎn)的會(huì)議改成十一點(diǎn)?！彼鼤?huì)怎么回大概率是“好的建議您前往日歷應(yīng)用手動(dòng)修改。”這句回答看似禮貌實(shí)際上什么都沒(méi)做。原因很簡(jiǎn)單普通語(yǔ)言模型的能力邊界在“生成文本”它沒(méi)有一個(gè)可以去操作日歷的“手”。LLM 本質(zhì)上是在給定上文的前提下預(yù)測(cè)下一個(gè) token。它知道日歷是什么甚至知道很多改日程的步驟但它沒(méi)有權(quán)限、沒(méi)有接口、也沒(méi)有執(zhí)行環(huán)境。想讓它真正干活就必須在模型外面接一層“工具層”。這一步在云端相對(duì)容易畢竟服務(wù)器可以隨便調(diào)接口、跑代碼。但到了手機(jī)、路由器、車(chē)載終端、嵌入式設(shè)備上問(wèn)題立刻變復(fù)雜算力有限、內(nèi)存吃緊、網(wǎng)絡(luò)不穩(wěn)定、隱私要求高。你不能指望設(shè)備端拖一個(gè)幾百億參數(shù)的模型再依賴云端反饋。端側(cè)智能體真正需要的是一個(gè)小、快、準(zhǔn)的本地“行動(dòng)派”模型而不是一個(gè)只會(huì)嘴上說(shuō)說(shuō)的“評(píng)論員”。1.2 函數(shù)調(diào)用把“意圖”變成“指令”函數(shù)調(diào)用function calling是當(dāng)前把大模型變成行動(dòng)體的最主流方案。核心思路很簡(jiǎn)單模型不直接執(zhí)行動(dòng)作而是輸出一個(gè)結(jié)構(gòu)化指令比如create_event(title項(xiàng)目評(píng)審, time2025-06-10 10:00)真正的執(zhí)行交給本地代碼。這樣做有四個(gè)好處可解釋模型只負(fù)責(zé)“決定做什么”每一步動(dòng)作都是明確的函數(shù)名和參數(shù)。可控制執(zhí)行前可以做權(quán)限校驗(yàn)、參數(shù)校驗(yàn)不讓模型亂來(lái)?？苫貪L如果某次調(diào)用產(chǎn)生了壞結(jié)果很容易定位到是哪個(gè)函數(shù)、什么參數(shù)出問(wèn)題。可擴(kuò)展新增能力只需要注冊(cè)一個(gè)新函數(shù)不需要重新訓(xùn)練模型。還是用改日程舉例用戶說(shuō)“把明天的會(huì)改到十一點(diǎn)”模型并不直接操作日歷數(shù)據(jù)庫(kù)它輸出reschedule_event(event_idevent_123, new_time11:00)。本機(jī)代碼拿到這個(gè)指令后再調(diào)用系統(tǒng)日歷 API 完成修改。這樣一來(lái)模型依然是模型動(dòng)作卻真正發(fā)生了。1.3 FunctionGemma 解決的三個(gè)核心問(wèn)題FunctionGemma 是一類(lèi)面向端側(cè)場(chǎng)景的輕量級(jí)工具調(diào)用模型方案。我不把它理解成某個(gè)單獨(dú)模型而是一條“訓(xùn)練策略 推理協(xié)議 端側(cè)執(zhí)行框架”的組合。它重點(diǎn)解決三個(gè)問(wèn)題。第一是輕量化。參數(shù)規(guī)模壓縮到端側(cè)能扛住的范圍同時(shí)通過(guò)定向訓(xùn)練把“工具調(diào)用”這個(gè)能力突出強(qiáng)化而不是像通用模型那樣什么都會(huì)一點(diǎn)、什么都不精。第二是結(jié)構(gòu)化輸出穩(wěn)定。純對(duì)話模型輸出 JSON 經(jīng)常缺括號(hào)、多字、字段名漂移。FunctionGemma 在訓(xùn)練階段使用了大量工具調(diào)用樣本并配合特殊 token 標(biāo)記函數(shù)調(diào)用段讓輸出格式的穩(wěn)定性比通用模型高一個(gè)量級(jí)。第三是多輪工具狀態(tài)感知。真實(shí)智能體不可能只調(diào)用一次函數(shù)。用戶查完天氣可能接著問(wèn)“那明天呢”這時(shí)候模型必須能結(jié)合上一次工具返回結(jié)果繼續(xù)推理。FunctionGemma 的訓(xùn)練數(shù)據(jù)里包含了多輪工具結(jié)果回填樣本所以它知道什么時(shí)候該繼續(xù)調(diào)、什么時(shí)候該給最終答復(fù)。2. FunctionGemma 是怎么設(shè)計(jì)出來(lái)的原理與運(yùn)行機(jī)制2.1 模型架構(gòu)與訓(xùn)練對(duì)象不去糾結(jié)底層實(shí)現(xiàn)細(xì)節(jié)從功能視角看FunctionGemma 的底座是一個(gè)標(biāo)準(zhǔn)的 Decoder-Only 輕量語(yǔ)言模型參數(shù)檔位從 1B 到 4B 不等。它要做的事情是在常規(guī)對(duì)話能力之上額外學(xué)會(huì)一種“工具調(diào)用方言”。訓(xùn)練數(shù)據(jù)混合了三類(lèi)多輪對(duì)話數(shù)據(jù)保證模型仍然能正常聊天、總結(jié)、問(wèn)答。函數(shù)調(diào)用數(shù)據(jù)用戶在某一輪提出請(qǐng)求模型在回復(fù)中插入一個(gè)特殊標(biāo)記比如function_call后面跟著 JSON 形式的函數(shù)名和參數(shù)。工具結(jié)果回填數(shù)據(jù)上一輪調(diào)用了函數(shù)這一輪的輸入是function_result模型需要基于這個(gè)結(jié)果生成最終回復(fù)或者繼續(xù)發(fā)起下一個(gè)函數(shù)調(diào)用。為什么要把函數(shù)調(diào)用訓(xùn)練成一種“方言”而不是靠提示詞現(xiàn)場(chǎng)學(xué)會(huì)因?yàn)槎藗?cè)模型參數(shù)少泛化能力有限。如果你只是臨時(shí)在系統(tǒng)提示詞里貼幾個(gè)函數(shù)定義小模型很容易學(xué)會(huì)“讀題”卻很難學(xué)會(huì)“寫(xiě)標(biāo)準(zhǔn)格式”。只有把大量同類(lèi)樣本灌進(jìn)訓(xùn)練過(guò)程模型才會(huì)把“看到用戶請(qǐng)求→判斷可調(diào)函數(shù)→輸出 JSON 指令”這一鏈路變成一種條件反射。2.2 函數(shù)描述注入與結(jié)構(gòu)化輸出你可能會(huì)好奇模型怎么知道有哪些函數(shù)可以調(diào)答案跟提示工程有關(guān)。推理時(shí)我們會(huì)把當(dāng)前可用的函數(shù)列表轉(zhuǎn)成 JSON Schema 格式拼到系統(tǒng)提示詞里。一個(gè)典型的函數(shù)聲明長(zhǎng)這樣{ name: create_memo, description: 創(chuàng)建一條本地備忘錄適合記錄臨時(shí)想法和待辦事項(xiàng), parameters: { type: object, properties: { title: { type: string, description: 備忘錄標(biāo)題盡量簡(jiǎn)潔 }, content: { type: string, description: 備忘錄正文內(nèi)容 } }, required: [title, content] } }這段描述不是給機(jī)器看的機(jī)器其實(shí)不“理解”自然語(yǔ)言的全部含義它是給模型的注意力機(jī)制做引導(dǎo)的。描述寫(xiě)得越具體模型越容易在需要的時(shí)候選擇這個(gè)函數(shù)而不是搞混參數(shù)。結(jié)構(gòu)化輸出則通過(guò)兩重機(jī)制保證。第一重是訓(xùn)練記憶模型見(jiàn)多了function_call的格式自然會(huì)模仿。第二重是推理后處理如果模型輸出的 JSON 不夠規(guī)整代碼層可以做一次容錯(cuò)解析比如提取方括號(hào)里的文本、修復(fù)缺失的尾括號(hào)、把單引號(hào)轉(zhuǎn)成雙引號(hào)。這兩重機(jī)制缺一不可。2.3 一次完整調(diào)用鏈路的六個(gè)階段端側(cè)智能體不是把函數(shù)定義拼進(jìn)去就算完真正跑起來(lái)之后每一步都是一段可復(fù)用的邏輯。我把完整鏈路拆成六個(gè)階段構(gòu)造請(qǐng)求把系統(tǒng)提示詞、函數(shù)聲明、對(duì)話歷史、當(dāng)前問(wèn)題拼成一個(gè) prompt。模型推理由 FunctionGemma 生成結(jié)果結(jié)果可能是一次文本回復(fù)也可能是一次函數(shù)調(diào)用。解析輸出識(shí)別function_call標(biāo)記嘗試提取 JSON判斷格式是否合法。校驗(yàn)指令檢查函數(shù)名是否白名單、參數(shù)是否匹配 schema、必填字段是否齊全。執(zhí)行函數(shù)調(diào)用本地函數(shù)拿到返回值轉(zhuǎn)成字符串或 JSON。回填結(jié)果把工具返回值以tool角色追加到對(duì)話里再送進(jìn)模型做下一輪推理直到模型給出最終回復(fù)。這個(gè)循環(huán)不是無(wú)限的。我會(huì)在工程實(shí)現(xiàn)里設(shè)置一個(gè)最大輪次比如 4 到 6 次。一旦超過(guò)就返回“我還沒(méi)能完成這個(gè)任務(wù)請(qǐng)換個(gè)說(shuō)法再試一次”。這樣做是為了防止模型因?yàn)槟硞€(gè)函數(shù)始終報(bào)錯(cuò)而無(wú)限重試?yán)速M(fèi)端側(cè)電力。3. 實(shí)操用 FunctionGemma 在本地搭一個(gè)可行動(dòng)的智能體3.1 準(zhǔn)備運(yùn)行環(huán)境與模型文件動(dòng)手之前先把環(huán)境準(zhǔn)備好。我默認(rèn)你手頭有一臺(tái)普通開(kāi)發(fā)機(jī)CPU 能跑、內(nèi)存 8G 以上就可以。如果你是做部署到手機(jī)或嵌入式設(shè)備步驟類(lèi)似只是需要先把模型量化成更小的文件。建議的準(zhǔn)備項(xiàng)Python 3.10裝好 json、re、datetime 等標(biāo)準(zhǔn)庫(kù)以及一個(gè)支持端側(cè)模型推理的引擎接口。從模型倉(cāng)庫(kù)拿一個(gè)量化好的 FunctionGemma 權(quán)重文件優(yōu)先選 int4 或 int8 的 GGUF 格式體積小、CPU 也能跑。把權(quán)重文件放到固定目錄比如models/functiongemma-2b-int4.gguf。初始化推理引擎時(shí)重點(diǎn)設(shè)置兩個(gè)參數(shù)上下文長(zhǎng)度和線程數(shù)。上下文長(zhǎng)度建議先給 2048太小容易截?cái)喽噍喒ぞ呓Y(jié)果太大內(nèi)存占用會(huì)直線上升。線程數(shù)設(shè)成 CPU 核心數(shù)的一半左右避免推理時(shí)整個(gè)設(shè)備卡死。3.2 定義本地工具集第一步先把“智能體能做什么”定下來(lái)。做端側(cè)智能體最忌諱一上來(lái)就想做全知全能先選三五個(gè)高頻、確定、可驗(yàn)證的工具。我在這里定義一組很實(shí)用的工具獲取當(dāng)前時(shí)間、創(chuàng)建本地備忘錄、發(fā)送系統(tǒng)通知。代碼很簡(jiǎn)單import json from datetime import datetime def get_local_time() - str: 獲取當(dāng)前本地時(shí)間 return datetime.now().isoformat() def create_memo(title: str, content: str) - bool: 把備忘錄寫(xiě)入本地文件 memo {title: title, content: content, created_at: datetime.now().isoformat()} with open(memos.json, a, encodingutf-8) as f: f.write(json.dumps(memo, ensure_asciiFalse) \n) return True def send_notification(title: str, message: str) - bool: 發(fā)送一條本地系統(tǒng)通知 # 這里對(duì)接平臺(tái)通知接口演示時(shí)先返回 True print(f[通知] {title}: {message}) return True TOOL_REGISTRY { get_local_time: get_local_time, create_memo: create_memo, send_notification: send_notification, }注意一個(gè)工程細(xì)節(jié)TOOL_REGISTRY的 key 必須和函數(shù)聲明里的name完全一致執(zhí)行層只認(rèn)這個(gè)注冊(cè)表不認(rèn)模型輸出里的名字。這樣做的好處是即使模型偶爾輸出一個(gè)不存在的函數(shù)名執(zhí)行層也能立刻攔截而不是傻乎乎地報(bào)錯(cuò)。3.3 構(gòu)造函數(shù)聲明與系統(tǒng)提示詞函數(shù)聲明列表作為模型可參考的“工具手冊(cè)”。前面已經(jīng)展示了單個(gè)函數(shù)的 JSON Schema實(shí)際使用時(shí)會(huì)拼成一個(gè)數(shù)組。系統(tǒng)提示詞我通常這樣寫(xiě)SYSTEM_PROMPT 你是一個(gè)運(yùn)行在本地設(shè)備上的智能助手。 你可以使用以下工具完成用戶請(qǐng)求但不要虛構(gòu)不存在的函數(shù)。 當(dāng)用戶請(qǐng)求需要調(diào)用工具時(shí)請(qǐng)嚴(yán)格按照下面的格式輸出 function_call{name: 函數(shù)名, arguments: {參數(shù)名: 參數(shù)值}}/function_call 如果用戶請(qǐng)求不需要工具直接使用自然語(yǔ)言回復(fù)。 FUNCTION_DEFS [ { name: get_local_time, description: 獲取當(dāng)前本地日期和時(shí)間。當(dāng)用戶問(wèn)現(xiàn)在幾點(diǎn)、今天日期時(shí)使用。, parameters: { type: object, properties: {}, required: [] } }, { name: create_memo, description: 把一段文字記錄成本地備忘錄。適用于用戶說(shuō)記一下添加到待辦寫(xiě)個(gè)備忘。, parameters: { type: object, properties: { title: {type: string, description: 簡(jiǎn)短標(biāo)題}, content: {type: string, description: 完整內(nèi)容} }, required: [title, content] } }, { name: send_notification, description: 發(fā)送本地系統(tǒng)通知。適用于用戶要求提醒、通知。, parameters: { type: object, properties: { title: {type: string, description: 通知標(biāo)題}, message: {type: string, description: 通知內(nèi)容} }, required: [title, message] } } ]為什么要單獨(dú)加一句“不要虛構(gòu)不存在的函數(shù)”因?yàn)樾∧Ｐ驮陂_(kāi)放環(huán)境下容易把用戶提到的任何動(dòng)詞都當(dāng)成函數(shù)名。比如用戶說(shuō)“幫我發(fā)個(gè)郵件”模型如果看到?jīng)]有郵件函數(shù)可能會(huì)編一個(gè)send_email出來(lái)。把約束寫(xiě)進(jìn)系統(tǒng)提示詞能顯著減少這類(lèi)幻覺(jué)。3.4 核心推理與執(zhí)行循環(huán)代碼下面這段循環(huán)是整個(gè)智能體的心臟。它負(fù)責(zé)把對(duì)話狀態(tài)、函數(shù)聲明、模型輸出和本地工具串起來(lái)。def build_prompt(messages, function_defs): 把消息列表和函數(shù)聲明拼成模型輸入 system_text SYSTEM_PROMPT \n可用工具:\n json.dumps(function_defs, ensure_asciiFalse) prompt system_text \n for msg in messages: role msg[role] content msg[content] if role user: prompt f\n用戶: {content}\n elif role tool: prompt f\nfunction_result{content}/function_result\n else: prompt f\n系統(tǒng): {content}\n return prompt def parse_function_call(raw_text): 從模型輸出中提取函數(shù)調(diào)用 JSON match re.search(rfunction_call(.*?)/function_call, raw_text, re.DOTALL) if not match: return None try: return json.loads(match.group(1)) except json.JSONDecodeError: return None def execute_function(func_name, func_args): 執(zhí)行本地工具返回 JSON 字符串 if func_name not in TOOL_REGISTRY: return json.dumps({error: f未知函數(shù): {func_name}}) try: result TOOL_REGISTRY[func_name](**func_args) return json.dumps({result: result}, ensure_asciiFalse) except Exception as e: return json.dumps({error: str(e)}) def run_agent(user_question, max_steps4): messages [{role: user, content: user_question}] for _ in range(max_steps): prompt build_prompt(messages, FUNCTION_DEFS) raw_output engine.generate(prompt) action parse_function_call(raw_output) if action is None: # 沒(méi)有函數(shù)調(diào)用視為最終回復(fù) return raw_output func_name action.get(name) func_args action.get(arguments, {}) tool_result execute_function(func_name, func_args) messages.append({role: tool, content: tool_result}) # 繼續(xù)循環(huán)讓模型基于工具結(jié)果生成下一個(gè)動(dòng)作或最終回復(fù) return 已超過(guò)最大工具調(diào)用次數(shù)任務(wù)中斷注意上面代碼里的engine.generate是一個(gè)抽象接口。不同推理引擎的調(diào)用方式不一樣但是整體邏輯完全一致。我建議你先把這段循環(huán)寫(xiě)穩(wěn)再替換成具體的引擎。我見(jiàn)過(guò)太多人一上來(lái)就去調(diào)某個(gè)推理框架的 API反而忽略了智能體本身的調(diào)度邏輯。3.5 部署到低算力設(shè)備的注意點(diǎn)如果目標(biāo)設(shè)備不是 PC而是手機(jī)、開(kāi)發(fā)板這類(lèi)低算力環(huán)境有幾個(gè)點(diǎn)要提前處理。第一量化精度要夠。4bit 量化通常是性價(jià)比最高的選擇模型大小能壓到原來(lái)的三分之一甚至四分之一。但量化后可能會(huì)損失少量工具調(diào)用準(zhǔn)確率所以我建議準(zhǔn)備兩套模型開(kāi)發(fā)調(diào)試用高精度版正式部署用 int4 版。如果在正式版上發(fā)現(xiàn)某個(gè)函數(shù)頻繁選錯(cuò)優(yōu)先回查 schema 描述是否清晰而不是急著換回高精度模型。第二控制上下文長(zhǎng)度。端側(cè)設(shè)備的內(nèi)存是硬約束一次推理能塞進(jìn)去的 token 有限。多輪對(duì)話時(shí)不要無(wú)限追加歷史只保留最近兩到三輪。工具結(jié)果如果很長(zhǎng)先讓模型自己寫(xiě)一個(gè)摘要再拼回上下文而不是把全套 JSON 塞進(jìn)去。第三做好功耗控制。函數(shù)調(diào)用循環(huán)如果設(shè)計(jì)成無(wú)限重試設(shè)備會(huì)長(zhǎng)時(shí)間保持高負(fù)載。我剛才在代碼里加了max_steps限制實(shí)際項(xiàng)目里我還會(huì)再加一條單次任務(wù)總耗時(shí)超過(guò) 10 秒就主動(dòng)結(jié)束并返回到主界面。端側(cè)智能體不能像云端服務(wù)那樣無(wú)限“思考”。4. 調(diào)優(yōu)與避坑把準(zhǔn)確率從“碰運(yùn)氣”抬到“能交付”4.1 函數(shù) Schema 設(shè)計(jì)原則函數(shù)聲明看起來(lái)簡(jiǎn)單真正決定模型能不能調(diào)對(duì)。我總結(jié)了幾條實(shí)用原則。函數(shù)名要?jiǎng)釉~開(kāi)頭像是get_local_time、create_memo不要用time、memo、notification這類(lèi)名詞否則模型區(qū)分不了“查時(shí)間”和“設(shè)置時(shí)間”。描述里要寫(xiě)清楚觸發(fā)條件。不要只寫(xiě)“獲取時(shí)間”要寫(xiě)“用戶問(wèn)現(xiàn)在幾點(diǎn)、當(dāng)前日期時(shí)使用”。端側(cè)模型參數(shù)小對(duì)隱式語(yǔ)義的把握弱描述越直白選擇準(zhǔn)確率越高。參數(shù)必填項(xiàng)越少越好。能用默認(rèn)值就用默認(rèn)值。比如create_memo如果允許省略標(biāo)題就可以把title設(shè)為非必填模型出錯(cuò)的可能性會(huì)降低一個(gè)檔次。一次暴露的函數(shù)數(shù)量要控制。測(cè)試時(shí)我遇到過(guò)模型在 30 個(gè)函數(shù)里反復(fù)猶豫的情況最后把函數(shù)按場(chǎng)景拆成多組根據(jù)用戶第一輪問(wèn)題動(dòng)態(tài)選擇暴露哪一組準(zhǔn)確率立刻上來(lái)。如果設(shè)備只做備忘助手那就別把“控制燈泡”的函數(shù)也塞進(jìn)去。4.2 采樣參數(shù)怎么調(diào)函數(shù)調(diào)用不是創(chuàng)作不需要模型“自由發(fā)揮”。采樣參數(shù)應(yīng)該往確定性方向調(diào)。溫度調(diào)低是首選。0.2 以下通常比較穩(wěn)0.0 則完全貪心。我建議從 0.1 起步如果發(fā)現(xiàn)模型經(jīng)常輸出重復(fù)內(nèi)容再嘗試小幅提高。top_p保持 0.9 到 0.95主要用來(lái)過(guò)濾尾部低概率 token。top_k設(shè)成 20 到 50 之間防止模型在函數(shù)名這種關(guān)鍵位置突然發(fā)散。如果你的推理引擎支持約束解碼一定要用起來(lái)。約束解碼可以限制模型只能按照預(yù)定義的 JSON Schema 生成 token把格式錯(cuò)誤直接扼殺在生成階段。這是當(dāng)前提升函數(shù)調(diào)用成功率最有效的工程手段比任何提示詞技巧都管用。不支持也沒(méi)關(guān)系代碼層做一套健壯的 JSON 解析兜底。4.3 多輪狀態(tài)與上下文裁剪真正跑起來(lái)之后最容易被忽略的是多輪上下文。用戶說(shuō)“現(xiàn)在幾點(diǎn)了”模型調(diào)了get_local_time返回2025-06-10T09:30:00。用戶接著問(wèn)“那一個(gè)小時(shí)后呢”這時(shí)候模型必須能看到剛才的函數(shù)結(jié)果才能計(jì)算10:30。實(shí)現(xiàn)上要記住兩點(diǎn)。第一工具結(jié)果一旦被模型消費(fèi)就不再需要保留原始 JSON?？梢栽诘诙喭评砬鞍呀Y(jié)果壓縮成一句話比如“當(dāng)前時(shí)間是 2025-06-10 09:30:00”然后繼續(xù)拼進(jìn)上下文。這樣既保留了信息又不占 token。第二不要讓工具結(jié)果“污染”新一輪對(duì)話的角色。工具結(jié)果必須以獨(dú)立的tool角色放入消息列表不能拼在 user 消息里。否則模型容易把工具結(jié)果誤當(dāng)成用戶新指令導(dǎo)致角色混亂。我遇到過(guò)好幾次模型在工具返回后突然說(shuō)“好的我會(huì)記住”就是角色沒(méi)分清楚。4.4 安全邊界設(shè)計(jì)讓模型調(diào)用本地函數(shù)等于給外部文本輸入開(kāi)了個(gè)執(zhí)行口子安全必須前置。最基礎(chǔ)的做法是白名單機(jī)制。TOOL_REGISTRY就是白名單所有執(zhí)行入口只能從這里查函數(shù)。永遠(yuǎn)不要讓模型直接執(zhí)行任意 Python 代碼哪怕它“發(fā)誓”只是做個(gè)加法。其次要做參數(shù)校驗(yàn)。函數(shù)名合法不代表參數(shù)合法。create_memo的content如果允許任意字符串那模型可能把用戶輸入的惡意內(nèi)容寫(xiě)進(jìn)文件。文件路徑類(lèi)參數(shù)更要小心絕對(duì)不能讓模型傳一個(gè)../../etc/passwd進(jìn)來(lái)。我會(huì)在每個(gè)函數(shù)內(nèi)部再做一輪自己的校驗(yàn)不依賴模型輸出的正確性。最后是敏感操作二次確認(rèn)。刪除文件、發(fā)送不可撤回的通知、修改系統(tǒng)配置這類(lèi)操作不能模型一說(shuō)就執(zhí)行。要先把待執(zhí)行動(dòng)作展示給用戶確認(rèn)用戶點(diǎn)擊確認(rèn)后再真正調(diào)用。端側(cè)智能體追求效率但安全底線一點(diǎn)不能松。5. 常見(jiàn)問(wèn)題排查實(shí)錄5.1 高頻報(bào)錯(cuò)與對(duì)應(yīng)解法我在做 FunctionGemma 落地時(shí)遇到過(guò)不少問(wèn)題這里整理成一張速查表?，F(xiàn)象可能原因解決思路模型輸出普通文本而不是函數(shù)調(diào)用系統(tǒng)提示詞沒(méi)有說(shuō)清輸出格式或函數(shù)聲明沒(méi)拼進(jìn)去檢查 build_prompt確認(rèn) FUNCTION_DEFS 已拼到系統(tǒng)提示詞中把觸發(fā)條件寫(xiě)得更直白函數(shù)名拼錯(cuò)、多字少字模型對(duì)函數(shù)名的記憶不穩(wěn)定尤其函數(shù)名過(guò)長(zhǎng)函數(shù)名控制在 2-4 個(gè)詞動(dòng)詞開(kāi)頭在提示詞里重復(fù)一遍可用函數(shù)名參數(shù)類(lèi)型錯(cuò)誤比如把數(shù)字寫(xiě)成字符串函數(shù) schema 里沒(méi)有寫(xiě)清楚類(lèi)型檢查函數(shù)定義中的parameters必要時(shí)在描述里補(bǔ)類(lèi)型示例同一函數(shù)被無(wú)限重復(fù)調(diào)用工具結(jié)果沒(méi)有正確回填模型看不到結(jié)果就只能重試檢查messages.append是否正確工具角色是否被截?cái)喙ぞ呓Y(jié)果存在但最終回復(fù)卻沒(méi)有參考它上下文被裁剪或者工具結(jié)果寫(xiě)在了不顯眼的位置增加上下文長(zhǎng)度把最近的工具結(jié)果放在 prompt 最后面推理速度很慢上下文太長(zhǎng)、線程數(shù)太少、模型未量化裁剪歷史調(diào)整線程數(shù)換 int4 量化版本JSON 解析經(jīng)常失敗模型生成時(shí)沒(méi)有約束解碼輸出多余字符優(yōu)化提示詞或者在解析層使用更寬容的 JSON 提取正則表格里面的問(wèn)題我全都真實(shí)踩過(guò)尤其是“工具結(jié)果沒(méi)回填導(dǎo)致重試”那個(gè)月幾乎天天碰到。后來(lái)我加了一行日志專(zhuān)門(mén)打印每次循環(huán)后的完整 prompt問(wèn)題立刻暴露出來(lái)上下文被裁剪時(shí)把工具結(jié)果裁掉了。從那以后我再也沒(méi)讓上下文長(zhǎng)度超過(guò)設(shè)定值。5.2 我的排查順序遇到問(wèn)題不要急著調(diào)模型先按這個(gè)順序排查能省很多時(shí)間。第一步看輸入是不是 prompt 拼接錯(cuò)了。先把每次發(fā)給引擎的完整文本打出來(lái)確認(rèn)函數(shù)聲明、歷史消息、工具結(jié)果都在并且順序合理。這一步能解決一半問(wèn)題。第二步看輸出模型到底生成了什么。把原始 token 序列或原始文本保存下來(lái)不要只看解析后的結(jié)果。很多時(shí)候模型生成的是正確的function_call但你的正則沒(méi)匹配到。第三步看執(zhí)行工具本身有沒(méi)有報(bào)錯(cuò)。給每個(gè)工具寫(xiě)一個(gè)獨(dú)立的單元測(cè)試確認(rèn)get_local_time()確實(shí)返回時(shí)間、create_memo()確實(shí)寫(xiě)入了文件。工具有問(wèn)題再智能的模型也白搭。第四步才回頭調(diào)模型。這時(shí)候再考慮改溫度、改 schema、加少樣本示例。順序反了會(huì)很痛苦我見(jiàn)過(guò)有人花一周時(shí)間調(diào)提示詞最后發(fā)現(xiàn)是個(gè)底層 JSON 解析 bug 導(dǎo)致的。6. 我的幾點(diǎn)實(shí)操體會(huì)做端側(cè)智能體越久越覺(jué)得“從對(duì)話邁向行動(dòng)”這個(gè)說(shuō)法不是一句口號(hào)而是整個(gè)范式轉(zhuǎn)換的本質(zhì)。純對(duì)話模型是知識(shí)引擎重心在“答得好不好”函數(shù)調(diào)用模型是行動(dòng)引擎重心在“做得對(duì)不對(duì)”。FunctionGemma 這類(lèi)方案的真正價(jià)值是把模型體積、工具調(diào)用能力、端側(cè)資源約束放到同一個(gè)天平上做出一個(gè)工程上可用的折中。我自己的體會(huì)有三點(diǎn)值得分享。第一永遠(yuǎn)不要追求全知全能。端側(cè)智能體最適合的場(chǎng)景一定是邊界清晰的垂直場(chǎng)景。我就讓它管備忘錄、查時(shí)間、發(fā)通知三個(gè)函數(shù)用得非常穩(wěn)定。一旦加了太多工具準(zhǔn)確率下降的速度會(huì)超出你的預(yù)期。第二把模型看作“意圖理解器”把本機(jī)代碼看作“安全執(zhí)行器”。模型負(fù)責(zé)判斷用戶想干什么剩下的事情全部由你寫(xiě)的代碼負(fù)責(zé)。這條路比讓模型直接生成代碼安全得多也更容易排查問(wèn)題。第三每一輪工具調(diào)用都要有日志和可復(fù)現(xiàn)性。我在完成函數(shù)調(diào)用后都會(huì)把當(dāng)時(shí)的 prompt、模型輸出、工具結(jié)果完整存一份標(biāo)記為 trace。后續(xù)優(yōu)化模型或調(diào) schema 時(shí)直接回放這些 trace能快速驗(yàn)證改動(dòng)是否有效。這個(gè)習(xí)慣幫我省下了大量回歸測(cè)試的時(shí)間。最后再分享一個(gè)小技巧。剛開(kāi)始調(diào)通智能體時(shí)可以故意在用戶請(qǐng)求里塞一些模棱兩可的話比如“隨便記一下”“提醒我明天”觀察模型是調(diào)用工具還是亂猜。只要把這類(lèi)邊界情況覆蓋到端側(cè)智能體才算真正從“能跑”進(jìn)化到“能用”。