型AI Agent實(shí)戰(zhàn)：從零搭建可查資料的Agent系統(tǒng))
1. 一個(gè)前端Leader的轉(zhuǎn)型焦慮與破局思路做了八年多前端帶過十幾人的團(tuán)隊(duì)從 jQuery 時(shí)代一路寫到 React Server Components我原以為自己會(huì)一直在這條路上走到黑。直到去年年底團(tuán)隊(duì)開始接一些智能化需求產(chǎn)品經(jīng)理張口閉口就是“大模型”“Agent”“RAG”我才意識(shí)到如果繼續(xù)只守著組件、狀態(tài)管理和構(gòu)建工具這一畝三分地遲早會(huì)被時(shí)代甩下車。于是從今年年初開始我給自己定了一個(gè)硬性計(jì)劃每天至少投入兩小時(shí)系統(tǒng)學(xué)習(xí) AI Agent 相關(guān)的知識(shí)并且把學(xué)習(xí)過程記錄下來這就是“DAY73”這個(gè)系列的由來。先說說這個(gè)系列到底在寫什么。它不是那種從零開始的 AI 入門教程也不是純理論的大模型原理講解而是一個(gè)有工程背景、有團(tuán)隊(duì)管理經(jīng)驗(yàn)的前端 Leader在邊工作邊轉(zhuǎn)型過程中把每天踩過的坑、跑通的代碼、想明白的架構(gòu)問題原原本本記錄下來。核心關(guān)鍵詞就三個(gè)前端轉(zhuǎn)型、AI Agent、工程化落地。適合誰來讀如果你也是前端、后端或者全棧開發(fā)者正在觀望要不要往 AI 方向靠或者已經(jīng)開始學(xué)但總覺得“學(xué)了一堆概念卻做不出東西”那這個(gè)系列應(yīng)該能幫到你。我不會(huì)跟你扯太多 Transformer 的數(shù)學(xué)推導(dǎo)而是把重點(diǎn)放在“一個(gè) Agent 系統(tǒng)到底怎么搭起來、怎么調(diào)通、怎么讓它穩(wěn)定干活”這些真正卡人的地方。DAY73 這個(gè)節(jié)點(diǎn)我已經(jīng)過了最初那種“調(diào)個(gè) API 就興奮半天”的階段開始進(jìn)入比較系統(tǒng)的工程化實(shí)踐。今天這篇我想把這段時(shí)間積累的整體思路、核心細(xì)節(jié)、實(shí)操過程和踩坑經(jīng)驗(yàn)做一次比較完整的梳理。不是流水賬而是把那些真正有價(jià)值的東西提煉出來讓你少走彎路。2. 整體設(shè)計(jì)與思路拆解為什么我不建議一上來就啃框架2.1 從“會(huì)用 API”到“會(huì)設(shè)計(jì) Agent”的分水嶺剛開始學(xué)的時(shí)候我和大多數(shù)人一樣找了個(gè)大模型的 API寫了個(gè)函數(shù)傳個(gè) prompt拿到返回就覺得“AI 不過如此”。但真正開始做一個(gè)能自主完成任務(wù)的 Agent 時(shí)問題就來了它要怎么記住上下文怎么決定下一步做什么怎么調(diào)用外部工具怎么在出錯(cuò)時(shí)自己糾正這些問題光靠一個(gè) API 調(diào)用是解決不了的。我踩過的第一個(gè)大坑就是過早地扎進(jìn)某個(gè) Agent 框架里。當(dāng)時(shí)看網(wǎng)上都在推 LangChain、AutoGPT 之類的我也跟著裝了一套結(jié)果發(fā)現(xiàn)文檔看得云里霧里一個(gè)簡(jiǎn)單的功能要套好幾層抽象出了問題根本不知道是哪一層掛了。后來我強(qiáng)迫自己退回來先用最原始的方式——直接調(diào) API、手寫循環(huán)、手動(dòng)管理狀態(tài)——把 Agent 的核心邏輯跑通一遍。這個(gè)過程雖然笨但讓我徹底搞明白了 Agent 到底是怎么回事。我的建議是先手寫再用框架。手寫一遍你會(huì)清楚地知道 Agent 的本質(zhì)就是一個(gè)“感知-決策-行動(dòng)”的循環(huán)框架只是幫你把這個(gè)循環(huán)封裝得更優(yōu)雅而已。等你手寫跑通了再去看框架的源碼會(huì)有一種“原來如此”的通透感。2.2 前端背景在 Agent 開發(fā)中的真實(shí)優(yōu)勢(shì)與短板很多人覺得前端轉(zhuǎn) AI 是跨行劣勢(shì)很大。我一開始也這么想但做了兩個(gè)多月之后我發(fā)現(xiàn)前端背景其實(shí)有幾個(gè)被低估的優(yōu)勢(shì)。第一個(gè)優(yōu)勢(shì)是對(duì)異步和狀態(tài)管理的敏感度。Agent 的執(zhí)行過程本質(zhì)上就是一連串異步操作中間還夾雜著狀態(tài)流轉(zhuǎn)。前端天天跟 Promise、async/await、狀態(tài)機(jī)打交道處理這些簡(jiǎn)直是肌肉記憶。我見過一些后端背景的朋友寫 Agent 循環(huán)時(shí)經(jīng)常在并發(fā)和狀態(tài)同步上翻車而前端出身的人反而更容易理清。第二個(gè)優(yōu)勢(shì)是對(duì)用戶體驗(yàn)的直覺。Agent 最終是要給人用的流式輸出怎么展示、工具調(diào)用過程怎么反饋、出錯(cuò)時(shí)怎么提示這些都是前端的老本行。一個(gè)功能再強(qiáng)的 Agent如果交互做得稀爛用戶也不會(huì)買賬。但短板也很明顯對(duì)模型本身的理解不夠深。前端很少接觸向量、嵌入、概率分布這些東西剛開始看 embedding、temperature、top_p 這些概念時(shí)確實(shí)有點(diǎn)吃力。我的應(yīng)對(duì)方式是不追求把數(shù)學(xué)原理搞透而是先搞清楚每個(gè)參數(shù)“調(diào)大調(diào)小分別會(huì)有什么效果”用實(shí)驗(yàn)的方式去建立直覺。比如 temperature我就固定一個(gè) prompt分別用 0.1、0.5、1.0 跑十次看輸出的差異很快就明白了。2.3 我的技術(shù)選型邏輯夠用就好別追新在選型上我給自己定了一條原則能用簡(jiǎn)單的方案解決就絕不引入復(fù)雜的依賴。具體來說模型調(diào)用直接用官方 SDK不套中間層。中間層雖然方便切換模型但也會(huì)屏蔽掉很多細(xì)節(jié)出問題時(shí)不好排查。狀態(tài)管理Agent 的對(duì)話歷史和中間狀態(tài)我用一個(gè)簡(jiǎn)單的 JSON 結(jié)構(gòu)存配合文件持久化夠用了。沒必要上數(shù)據(jù)庫。工具調(diào)用自己寫一個(gè)工具注冊(cè)表每個(gè)工具就是一個(gè)函數(shù)加一段描述模型根據(jù)描述決定調(diào)哪個(gè)。簡(jiǎn)單直接。向量檢索需要做知識(shí)庫時(shí)我用最基礎(chǔ)的嵌入加余弦相似度先跑通再說。等數(shù)據(jù)量大了再考慮專業(yè)的向量庫。這套選型看起來“土”但勝在可控。每一個(gè)環(huán)節(jié)我都能說清楚它在干什么出了問題也能快速定位。等業(yè)務(wù)真正復(fù)雜到簡(jiǎn)單方案扛不住了再升級(jí)也不遲。3. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)Agent 到底由哪些零件組成3.1 一個(gè)最小可用 Agent 的四個(gè)核心模塊把 Agent 拆開來看不管多復(fù)雜的系統(tǒng)核心都離不開這四個(gè)模塊第一模型接口層。負(fù)責(zé)和模型通信處理請(qǐng)求的組裝和響應(yīng)的解析。這一層要處理的關(guān)鍵問題包括怎么設(shè)置系統(tǒng)提示詞、怎么控制輸出格式、怎么處理流式返回、怎么應(yīng)對(duì)超時(shí)和限流。第二記憶模塊。負(fù)責(zé)管理對(duì)話歷史和長(zhǎng)期知識(shí)。短期記憶就是最近幾輪對(duì)話長(zhǎng)期記憶則是通過向量檢索從知識(shí)庫里召回的相關(guān)內(nèi)容。這里最容易踩的坑是上下文長(zhǎng)度管理——對(duì)話輪數(shù)一多token 就爆了必須有一套裁剪或摘要機(jī)制。第三工具系統(tǒng)。這是 Agent 區(qū)別于普通聊天機(jī)器人的關(guān)鍵。工具就是一組可以被模型調(diào)用的函數(shù)每個(gè)函數(shù)有明確的名稱、描述和參數(shù)定義。模型根據(jù)當(dāng)前任務(wù)決定調(diào)用哪個(gè)工具、傳什么參數(shù)。第四執(zhí)行循環(huán)。這是 Agent 的“心臟”負(fù)責(zé)把上面三個(gè)模塊串起來接收用戶輸入組裝上下文調(diào)用模型解析模型的決策執(zhí)行工具把結(jié)果喂回模型如此循環(huán)直到任務(wù)完成或達(dá)到終止條件。這四個(gè)模塊我建議你一開始就分開寫每個(gè)模塊一個(gè)文件接口定義清楚。這樣后面調(diào)試和替換都會(huì)方便很多。3.2 提示詞工程不是玄學(xué)是結(jié)構(gòu)化的溝通很多人把提示詞工程說得神乎其神其實(shí)在我看來它就是用結(jié)構(gòu)化的方式把任務(wù)說清楚。我總結(jié)了一個(gè)自己一直在用的提示詞模板分四個(gè)部分角色定義你是一個(gè) XXX 助手擅長(zhǎng) XXX。 任務(wù)描述用戶會(huì)給你 XXX你需要完成 XXX。 可用工具你可以使用以下工具XXX。 輸出要求請(qǐng)以 XXX 格式輸出注意 XXX。這個(gè)模板看起來簡(jiǎn)單但每一條都有講究。角色定義決定了模型的“人設(shè)”和知識(shí)范圍任務(wù)描述要具體到可執(zhí)行工具說明要讓模型知道每個(gè)工具能干什么、什么時(shí)候用輸出要求則約束了返回格式方便后續(xù)程序解析。我踩過的一個(gè)坑是工具描述寫得太模糊。比如我寫了一個(gè)“查詢信息”的工具描述就寫了“查詢相關(guān)信息”結(jié)果模型經(jīng)常在該用的時(shí)候不用不該用的時(shí)候亂用。后來我把描述改成“根據(jù)用戶提供的訂單號(hào)查詢?cè)撚唵蔚脑敿?xì)狀態(tài)包括發(fā)貨時(shí)間、物流信息、當(dāng)前所在位置”模型的使用準(zhǔn)確率立刻上來了。工具描述要寫到“一個(gè)完全不了解你系統(tǒng)的人看了也知道什么時(shí)候該用”的程度。3.3 上下文管理token 是稀缺資源要省著用上下文窗口是 Agent 最寶貴的資源。我見過太多人把整個(gè)對(duì)話歷史一股腦塞進(jìn)去結(jié)果沒幾輪就爆了。我的做法是分層管理系統(tǒng)提示詞固定不變永遠(yuǎn)保留。最近 N 輪對(duì)話完整保留保證短期連貫性。更早的對(duì)話用模型做一次摘要壓縮成一段話保留。知識(shí)庫召回內(nèi)容按相關(guān)度排序只取 top K 條且每條做長(zhǎng)度截?cái)唷＿@里有個(gè)經(jīng)驗(yàn)值如果模型上下文是 8K token我一般會(huì)把系統(tǒng)提示詞控制在 500 以內(nèi)最近對(duì)話控制在 2000 以內(nèi)摘要控制在 500 以內(nèi)剩下的留給知識(shí)庫召回和模型輸出。這個(gè)分配不是死的要根據(jù)實(shí)際任務(wù)調(diào)整但核心思路是給每一部分都設(shè)一個(gè)預(yù)算不能讓它無限膨脹。注意做摘要的時(shí)候不要讓模型自由發(fā)揮要給它明確的指令比如“請(qǐng)用不超過 200 字總結(jié)以下對(duì)話的關(guān)鍵信息和結(jié)論保留所有數(shù)字和專有名詞”。否則摘要會(huì)越來越模糊最后丟失關(guān)鍵信息。3.4 工具調(diào)用的參數(shù)校驗(yàn)別信模型要信代碼模型返回的工具調(diào)用參數(shù)永遠(yuǎn)不要直接信任。我吃過這個(gè)虧讓模型生成一個(gè)日期參數(shù)它有時(shí)候返回“2024-01-01”有時(shí)候返回“2024年1月1日”有時(shí)候甚至返回“明天”。如果不做校驗(yàn)后面的代碼直接崩。我的做法是在每個(gè)工具函數(shù)入口處做嚴(yán)格的參數(shù)校驗(yàn)def query_order(order_id: str, date: str): # 校驗(yàn) order_id 格式 if not re.match(r^[A-Z0-9]{10}$, order_id): return {error: 訂單號(hào)格式不正確應(yīng)為10位大寫字母或數(shù)字} # 校驗(yàn)日期格式 try: datetime.strptime(date, %Y-%m-%d) except ValueError: return {error: 日期格式不正確應(yīng)為 YYYY-MM-DD} # 通過校驗(yàn)后再執(zhí)行實(shí)際邏輯 ...校驗(yàn)失敗時(shí)不要直接拋異常而是返回一個(gè)結(jié)構(gòu)化的錯(cuò)誤信息讓模型知道哪里錯(cuò)了它下一輪就會(huì)自己糾正。這個(gè)機(jī)制我稱之為“溫和糾錯(cuò)”比直接報(bào)錯(cuò)讓整個(gè)流程中斷要優(yōu)雅得多。4. 實(shí)操過程與核心環(huán)節(jié)實(shí)現(xiàn)從零搭一個(gè)能查資料的 Agent4.1 環(huán)境準(zhǔn)備與依賴安裝這一節(jié)我以 Python 為例因?yàn)?AI 生態(tài)里 Python 的庫最全。前端朋友別慌語法看看就懂邏輯才是關(guān)鍵。首先建一個(gè)干凈的虛擬環(huán)境這是好習(xí)慣避免依賴沖突python -m venv agent-env source agent-env/bin/activate # Windows 用 agent-env\Scripts\activate然后安裝核心依賴。我盡量精簡(jiǎn)只裝必要的pip install openai requests numpyopenai是模型調(diào)用的 SDKrequests用來發(fā) HTTP 請(qǐng)求比如調(diào)外部搜索接口numpy用來做向量計(jì)算。就這三個(gè)夠跑一個(gè)基礎(chǔ) Agent 了。提示不要一上來就裝一堆框架。依賴越少出問題時(shí)排查范圍越小。等你的 Agent 真的需要復(fù)雜功能了再按需引入。4.2 模型接口封裝把通信層做扎實(shí)模型接口層是整個(gè)系統(tǒng)的地基我把它單獨(dú)寫成一個(gè)類方便統(tǒng)一管理import openai import json class LLMClient: def __init__(self, api_key, modelgpt-4): self.client openai.OpenAI(api_keyapi_key) self.model model def chat(self, messages, toolsNone, temperature0.7): params { model: self.model, messages: messages, temperature: temperature, } if tools: params[tools] tools params[tool_choice] auto try: response self.client.chat.completions.create(**params) return response.choices[0].message except Exception as e: return {error: str(e)}這個(gè)封裝做了三件事統(tǒng)一了調(diào)用入口、支持工具調(diào)用、捕獲了異常。異常捕獲很重要網(wǎng)絡(luò)請(qǐng)求隨時(shí)可能失敗不能讓一個(gè)超時(shí)把整個(gè) Agent 搞崩。關(guān)于 temperature 的設(shè)置我的經(jīng)驗(yàn)是需要精確執(zhí)行任務(wù)的場(chǎng)景用 0.1-0.3需要?jiǎng)?chuàng)意生成的場(chǎng)景用 0.7-1.0。Agent 大多數(shù)時(shí)候是在執(zhí)行任務(wù)所以我默認(rèn)用 0.3保證輸出穩(wěn)定。4.3 工具注冊(cè)與執(zhí)行讓模型知道它能干什么工具系統(tǒng)的設(shè)計(jì)我采用“注冊(cè)表”模式。每個(gè)工具是一個(gè)字典包含名稱、描述、參數(shù)定義和執(zhí)行函數(shù)class ToolRegistry: def __init__(self): self.tools {} def register(self, name, description, parameters, func): self.tools[name] { definition: { type: function, function: { name: name, description: description, parameters: parameters } }, func: func } def get_definitions(self): return [t[definition] for t in self.tools.values()] def execute(self, name, arguments): if name not in self.tools: return {error: f工具 {name} 不存在} try: args json.loads(arguments) return self.tools[name][func](**args) except Exception as e: return {error: f工具執(zhí)行失敗{str(e)}}用的時(shí)候這樣注冊(cè)registry ToolRegistry() def search_web(query: str): # 實(shí)際搜索邏輯這里用偽代碼 results do_search(query) return {results: results} registry.register( namesearch_web, description根據(jù)關(guān)鍵詞搜索網(wǎng)絡(luò)信息返回相關(guān)結(jié)果列表。當(dāng)需要獲取最新信息或不確定的事實(shí)時(shí)使用。, parameters{ type: object, properties: { query: { type: string, description: 搜索關(guān)鍵詞盡量具體 } }, required: [query] }, funcsearch_web )這里的關(guān)鍵是描述要寫得足夠清楚。模型完全靠這段描述來判斷什么時(shí)候該用這個(gè)工具。我一般會(huì)寫清楚三件事這個(gè)工具能做什么、什么時(shí)候該用、參數(shù)怎么填。4.4 執(zhí)行循環(huán)Agent 的心臟把上面幾個(gè)模塊串起來就是 Agent 的執(zhí)行循環(huán)def run_agent(user_input, max_turns10): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input} ] for turn in range(max_turns): response llm_client.chat( messagesmessages, toolsregistry.get_definitions() ) # 如果模型沒有調(diào)用工具說明它認(rèn)為可以直接回答 if not response.tool_calls: return response.content # 把模型的決策加入歷史 messages.append(response) # 執(zhí)行所有工具調(diào)用 for tool_call in response.tool_calls: result registry.execute( tool_call.function.name, tool_call.function.arguments ) messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps(result, ensure_asciiFalse) }) return 達(dá)到最大輪次限制任務(wù)未完成這個(gè)循環(huán)的邏輯很清晰調(diào)用模型 → 如果模型要調(diào)工具就執(zhí)行 → 把結(jié)果喂回去 → 再調(diào)用模型 → 直到模型給出最終答案或達(dá)到輪次上限。max_turns這個(gè)參數(shù)很重要它是防止死循環(huán)的保險(xiǎn)絲。我一般設(shè) 10復(fù)雜任務(wù)設(shè) 15。超過這個(gè)輪次還沒完成說明要么任務(wù)太復(fù)雜需要拆分要么提示詞有問題需要人工介入。4.5 記憶模塊的實(shí)現(xiàn)短期與長(zhǎng)期結(jié)合記憶模塊我分兩部分實(shí)現(xiàn)。短期記憶就是上面循環(huán)里的messages列表隨著對(duì)話自然增長(zhǎng)。長(zhǎng)期記憶則是一個(gè)簡(jiǎn)單的向量檢索import numpy as np class Memory: def __init__(self, llm_client): self.llm_client llm_client self.documents [] # 存儲(chǔ)文本 self.embeddings [] # 存儲(chǔ)向量 def add(self, text): embedding self.get_embedding(text) self.documents.append(text) self.embeddings.append(embedding) def search(self, query, top_k3): if not self.embeddings: return [] query_embedding self.get_embedding(query) # 計(jì)算余弦相似度 similarities [] for emb in self.embeddings: sim np.dot(query_embedding, emb) / ( np.linalg.norm(query_embedding) * np.linalg.norm(emb) ) similarities.append(sim) # 取 top_k indices np.argsort(similarities)[-top_k:][::-1] return [self.documents[i] for i in indices] def get_embedding(self, text): # 調(diào)用嵌入接口這里省略具體實(shí)現(xiàn) return call_embedding_api(text)這個(gè)實(shí)現(xiàn)很樸素但對(duì)小規(guī)模知識(shí)庫完全夠用。等文檔數(shù)量上千了再考慮換成專業(yè)的向量數(shù)據(jù)庫。注意余弦相似度計(jì)算前一定要做歸一化否則向量長(zhǎng)度會(huì)影響結(jié)果。我一開始忘了歸一化檢索出來的結(jié)果亂七八糟排查了半天才發(fā)現(xiàn)是這個(gè)原因。5. 常見問題與排查技巧實(shí)錄那些讓我熬夜的坑5.1 模型不調(diào)用工具怎么辦這是最常見的問題。模型明明有工具可用卻選擇直接回答或者該用 A 工具卻用了 B 工具。排查思路如下第一檢查工具描述是否清晰。這是最常見的原因。描述太模糊模型不知道什么時(shí)候該用。解決辦法是把描述寫具體最好包含使用場(chǎng)景的舉例。第二檢查系統(tǒng)提示詞是否強(qiáng)調(diào)了工具的使用。有時(shí)候需要在系統(tǒng)提示詞里明確寫“當(dāng)需要獲取實(shí)時(shí)信息時(shí)必須使用搜索工具不要憑記憶回答”。第三檢查工具數(shù)量是否過多。工具太多會(huì)讓模型選擇困難。我一般把同時(shí)可用的工具控制在 5 個(gè)以內(nèi)超過就分組根據(jù)任務(wù)類型動(dòng)態(tài)加載。第四調(diào)整tool_choice參數(shù)。如果某個(gè)任務(wù)確定必須用工具可以把它設(shè)成強(qiáng)制調(diào)用某個(gè)工具而不是auto。5.2 工具調(diào)用參數(shù)格式錯(cuò)誤模型返回的參數(shù)經(jīng)常不符合預(yù)期比如該傳字符串的傳了數(shù)字該傳數(shù)組的傳了字符串。我的應(yīng)對(duì)策略是雙重保險(xiǎn)一是在工具定義里把參數(shù)類型寫清楚type字段要準(zhǔn)確。二是在工具函數(shù)入口做校驗(yàn)和轉(zhuǎn)換能自動(dòng)轉(zhuǎn)換的就轉(zhuǎn)換不能轉(zhuǎn)換的返回明確錯(cuò)誤。def safe_int(value, default0): try: return int(value) except (ValueError, TypeError): return default這種小工具函數(shù)多寫幾個(gè)能省很多事。5.3 上下文超長(zhǎng)導(dǎo)致報(bào)錯(cuò)對(duì)話輪數(shù)一多token 必然超限。我的處理流程是每次調(diào)用模型前先估算當(dāng)前 messages 的總 token 數(shù)。如果超過預(yù)算的 80%觸發(fā)壓縮。壓縮策略保留系統(tǒng)提示詞和最近 3 輪對(duì)話中間的對(duì)話用模型做摘要。摘要后的內(nèi)容作為一條 system 消息插入。估算 token 有個(gè)粗略公式英文大約 4 個(gè)字符 1 個(gè) token中文大約 1.5 個(gè)字符 1 個(gè) token。這個(gè)不精確但用來做預(yù)警足夠了。5.4 常見問題速查表問題現(xiàn)象可能原因排查方向解決辦法模型不調(diào)用工具描述模糊/提示詞未強(qiáng)調(diào)檢查工具描述和系統(tǒng)提示詞寫具體描述明確使用場(chǎng)景參數(shù)格式錯(cuò)誤類型定義不清檢查參數(shù) schema入口做校驗(yàn)和轉(zhuǎn)換上下文超長(zhǎng)對(duì)話歷史未壓縮估算 token 數(shù)觸發(fā)摘要壓縮循環(huán)不終止工具反復(fù)返回錯(cuò)誤查看工具執(zhí)行日志修復(fù)工具設(shè)置最大輪次響應(yīng)速度慢模型選擇過大/網(wǎng)絡(luò)問題檢查模型和網(wǎng)絡(luò)換小模型或加緩存輸出格式不穩(wěn)定temperature 過高檢查溫度設(shè)置降到 0.3 以下5.5 幾個(gè)讓我印象深刻的踩坑經(jīng)歷坑一工具執(zhí)行結(jié)果太長(zhǎng)把上下文撐爆。有一次我讓 Agent 搜索資料搜索工具返回了整整一頁的原始網(wǎng)頁內(nèi)容直接塞進(jìn)上下文下一輪就超限了。后來我在工具函數(shù)里加了截?cái)噙壿嬛环祷刈钕嚓P(guān)的前 500 字問題解決?？佣Ｐ拖萑搿暗狼秆h(huán)”。工具報(bào)錯(cuò)后模型不停地道歉然后重試同一個(gè)錯(cuò)誤操作。后來我在系統(tǒng)提示詞里加了一句“如果工具連續(xù)兩次返回相同錯(cuò)誤請(qǐng)停止重試并告知用戶”才止住這個(gè)循環(huán)?？尤l(fā)調(diào)用導(dǎo)致狀態(tài)混亂。我一開始讓多個(gè)工具并行執(zhí)行結(jié)果它們同時(shí)修改同一個(gè)狀態(tài)變量數(shù)據(jù)錯(cuò)亂。后來改成串行執(zhí)行或者對(duì)共享狀態(tài)加鎖才穩(wěn)定下來。Agent 的工具執(zhí)行能串行就別并行除非你確定它們互不干擾。6. 工程化落地的一些思考6.1 日志與可觀測(cè)性Agent 的“黑匣子”Agent 最大的問題是“黑盒”——你不知道它為什么做了某個(gè)決策。所以日志系統(tǒng)必須做扎實(shí)。我記錄的內(nèi)容包括每一輪的完整 messages、模型的原始響應(yīng)、工具調(diào)用的名稱和參數(shù)、工具返回的結(jié)果、每一輪的耗時(shí)。這些日志我按會(huì)話 ID 存成 JSON 文件出問題時(shí)可以完整回放整個(gè)執(zhí)行過程。這個(gè)習(xí)慣幫我定位了無數(shù)問題強(qiáng)烈建議你也這么做。6.2 成本控制token 就是錢Agent 跑起來token 消耗是實(shí)打?qū)嵉某杀?。我的控制手段有幾個(gè)緩存相同的查詢直接返回緩存結(jié)果不重復(fù)調(diào)用模型。模型分級(jí)簡(jiǎn)單任務(wù)用小模型復(fù)雜任務(wù)才用大模型。上下文精簡(jiǎn)前面說的壓縮策略本質(zhì)上也是在省錢。設(shè)置預(yù)算上限每個(gè)會(huì)話設(shè)置最大 token 消耗超了就終止。6.3 從 Demo 到產(chǎn)品的距離跑通一個(gè) Demo 可能只需要一天但把它變成能穩(wěn)定服務(wù)的產(chǎn)品需要的工作量是 Demo 的十倍。這中間的差距主要在錯(cuò)誤處理、邊界情況、性能優(yōu)化、監(jiān)控告警、用戶體驗(yàn)。我現(xiàn)在的做法是每做一個(gè)功能先問自己三個(gè)問題出錯(cuò)了怎么辦輸入異常怎么辦用戶等太久怎么辦把這三個(gè)問題想清楚代碼的健壯性會(huì)提升一大截。7. 給同樣在轉(zhuǎn)型路上的朋友幾句實(shí)在話寫了這么多最后分享幾點(diǎn)我自己的真實(shí)體會(huì)不構(gòu)成建議就是個(gè)人經(jīng)驗(yàn)。第一別被“AI 焦慮”裹挾。網(wǎng)上天天有人喊“再不學(xué) AI 就被淘汰了”搞得人心惶惶。但冷靜下來想AI 是工具不是替代品。你原有的工程能力、架構(gòu)思維、業(yè)務(wù)理解一樣都不會(huì)白費(fèi)反而會(huì)在 AI 時(shí)代變得更值錢。轉(zhuǎn)型不是推倒重來是在原有基礎(chǔ)上加一層新能力。第二動(dòng)手比看書重要一百倍。我見過太多人收藏了一堆教程、買了一堆課結(jié)果一行代碼沒寫。AI Agent 這東西看十篇文章不如自己跑通一個(gè) Demo。哪怕是最簡(jiǎn)單的“調(diào)用模型 一個(gè)工具”跑通了你就超過了 80% 只停留在概念層面的人。第三接受“不完美”。模型會(huì)犯錯(cuò)Agent 會(huì)抽風(fēng)這是常態(tài)。不要追求一次做到完美先讓它跑起來再一點(diǎn)點(diǎn)優(yōu)化。我現(xiàn)在的 Agent 也經(jīng)常出問題但每次出問題都是一次學(xué)習(xí)機(jī)會(huì)修著修著就越來越穩(wěn)了。第四保持記錄的習(xí)慣。這個(gè) DAY 系列對(duì)我來說最大的價(jià)值不是給別人看而是逼自己每天復(fù)盤。今天學(xué)了什么、踩了什么坑、想通了什么寫下來過段時(shí)間回頭看進(jìn)步一目了然。如果你也在轉(zhuǎn)型強(qiáng)烈建議你也開一個(gè)自己的記錄系列哪怕沒人看對(duì)自己也是極好的沉淀。這個(gè)系列我還會(huì)繼續(xù)寫下去后面可能會(huì)聊聊多 Agent 協(xié)作、Agent 的評(píng)估體系、以及怎么把 Agent 集成到實(shí)際業(yè)務(wù)系統(tǒng)里。路還長(zhǎng)一起走。 前端Leader轉(zhuǎn)型AI Agent實(shí)戰(zhàn)：從零搭建可查資料的Agent系統(tǒng)
1. 一個(gè)前端Leader的轉(zhuǎn)型焦慮與破局思路做了八年多前端帶過十幾人的團(tuán)隊(duì)從 jQuery 時(shí)代一路寫到 React Server Components我原以為自己會(huì)一直在這條路上走到黑。直到去年年底團(tuán)隊(duì)開始接一些智能化需求產(chǎn)品經(jīng)理張口閉口就是“大模型”“Agent”“RAG”我才意識(shí)到如果繼續(xù)只守著組件、狀態(tài)管理和構(gòu)建工具這一畝三分地遲早會(huì)被時(shí)代甩下車。于是從今年年初開始我給自己定了一個(gè)硬性計(jì)劃每天至少投入兩小時(shí)系統(tǒng)學(xué)習(xí) AI Agent 相關(guān)的知識(shí)并且把學(xué)習(xí)過程記錄下來這就是“DAY73”這個(gè)系列的由來。先說說這個(gè)系列到底在寫什么。它不是那種從零開始的 AI 入門教程也不是純理論的大模型原理講解而是一個(gè)有工程背景、有團(tuán)隊(duì)管理經(jīng)驗(yàn)的前端 Leader在邊工作邊轉(zhuǎn)型過程中把每天踩過的坑、跑通的代碼、想明白的架構(gòu)問題原原本本記錄下來。核心關(guān)鍵詞就三個(gè)前端轉(zhuǎn)型、AI Agent、工程化落地。適合誰來讀如果你也是前端、后端或者全棧開發(fā)者正在觀望要不要往 AI 方向靠或者已經(jīng)開始學(xué)但總覺得“學(xué)了一堆概念卻做不出東西”那這個(gè)系列應(yīng)該能幫到你。我不會(huì)跟你扯太多 Transformer 的數(shù)學(xué)推導(dǎo)而是把重點(diǎn)放在“一個(gè) Agent 系統(tǒng)到底怎么搭起來、怎么調(diào)通、怎么讓它穩(wěn)定干活”這些真正卡人的地方。DAY73 這個(gè)節(jié)點(diǎn)我已經(jīng)過了最初那種“調(diào)個(gè) API 就興奮半天”的階段開始進(jìn)入比較系統(tǒng)的工程化實(shí)踐。今天這篇我想把這段時(shí)間積累的整體思路、核心細(xì)節(jié)、實(shí)操過程和踩坑經(jīng)驗(yàn)做一次比較完整的梳理。不是流水賬而是把那些真正有價(jià)值的東西提煉出來讓你少走彎路。2. 整體設(shè)計(jì)與思路拆解為什么我不建議一上來就啃框架2.1 從“會(huì)用 API”到“會(huì)設(shè)計(jì) Agent”的分水嶺剛開始學(xué)的時(shí)候我和大多數(shù)人一樣找了個(gè)大模型的 API寫了個(gè)函數(shù)傳個(gè) prompt拿到返回就覺得“AI 不過如此”。但真正開始做一個(gè)能自主完成任務(wù)的 Agent 時(shí)問題就來了它要怎么記住上下文怎么決定下一步做什么怎么調(diào)用外部工具怎么在出錯(cuò)時(shí)自己糾正這些問題光靠一個(gè) API 調(diào)用是解決不了的。我踩過的第一個(gè)大坑就是過早地扎進(jìn)某個(gè) Agent 框架里。當(dāng)時(shí)看網(wǎng)上都在推 LangChain、AutoGPT 之類的我也跟著裝了一套結(jié)果發(fā)現(xiàn)文檔看得云里霧里一個(gè)簡(jiǎn)單的功能要套好幾層抽象出了問題根本不知道是哪一層掛了。后來我強(qiáng)迫自己退回來先用最原始的方式——直接調(diào) API、手寫循環(huán)、手動(dòng)管理狀態(tài)——把 Agent 的核心邏輯跑通一遍。這個(gè)過程雖然笨但讓我徹底搞明白了 Agent 到底是怎么回事。我的建議是先手寫再用框架。手寫一遍你會(huì)清楚地知道 Agent 的本質(zhì)就是一個(gè)“感知-決策-行動(dòng)”的循環(huán)框架只是幫你把這個(gè)循環(huán)封裝得更優(yōu)雅而已。等你手寫跑通了再去看框架的源碼會(huì)有一種“原來如此”的通透感。2.2 前端背景在 Agent 開發(fā)中的真實(shí)優(yōu)勢(shì)與短板很多人覺得前端轉(zhuǎn) AI 是跨行劣勢(shì)很大。我一開始也這么想但做了兩個(gè)多月之后我發(fā)現(xiàn)前端背景其實(shí)有幾個(gè)被低估的優(yōu)勢(shì)。第一個(gè)優(yōu)勢(shì)是對(duì)異步和狀態(tài)管理的敏感度。Agent 的執(zhí)行過程本質(zhì)上就是一連串異步操作中間還夾雜著狀態(tài)流轉(zhuǎn)。前端天天跟 Promise、async/await、狀態(tài)機(jī)打交道處理這些簡(jiǎn)直是肌肉記憶。我見過一些后端背景的朋友寫 Agent 循環(huán)時(shí)經(jīng)常在并發(fā)和狀態(tài)同步上翻車而前端出身的人反而更容易理清。第二個(gè)優(yōu)勢(shì)是對(duì)用戶體驗(yàn)的直覺。Agent 最終是要給人用的流式輸出怎么展示、工具調(diào)用過程怎么反饋、出錯(cuò)時(shí)怎么提示這些都是前端的老本行。一個(gè)功能再強(qiáng)的 Agent如果交互做得稀爛用戶也不會(huì)買賬。但短板也很明顯對(duì)模型本身的理解不夠深。前端很少接觸向量、嵌入、概率分布這些東西剛開始看 embedding、temperature、top_p 這些概念時(shí)確實(shí)有點(diǎn)吃力。我的應(yīng)對(duì)方式是不追求把數(shù)學(xué)原理搞透而是先搞清楚每個(gè)參數(shù)“調(diào)大調(diào)小分別會(huì)有什么效果”用實(shí)驗(yàn)的方式去建立直覺。比如 temperature我就固定一個(gè) prompt分別用 0.1、0.5、1.0 跑十次看輸出的差異很快就明白了。2.3 我的技術(shù)選型邏輯夠用就好別追新在選型上我給自己定了一條原則能用簡(jiǎn)單的方案解決就絕不引入復(fù)雜的依賴。具體來說模型調(diào)用直接用官方 SDK不套中間層。中間層雖然方便切換模型但也會(huì)屏蔽掉很多細(xì)節(jié)出問題時(shí)不好排查。狀態(tài)管理Agent 的對(duì)話歷史和中間狀態(tài)我用一個(gè)簡(jiǎn)單的 JSON 結(jié)構(gòu)存配合文件持久化夠用了。沒必要上數(shù)據(jù)庫。工具調(diào)用自己寫一個(gè)工具注冊(cè)表每個(gè)工具就是一個(gè)函數(shù)加一段描述模型根據(jù)描述決定調(diào)哪個(gè)。簡(jiǎn)單直接。向量檢索需要做知識(shí)庫時(shí)我用最基礎(chǔ)的嵌入加余弦相似度先跑通再說。等數(shù)據(jù)量大了再考慮專業(yè)的向量庫。這套選型看起來“土”但勝在可控。每一個(gè)環(huán)節(jié)我都能說清楚它在干什么出了問題也能快速定位。等業(yè)務(wù)真正復(fù)雜到簡(jiǎn)單方案扛不住了再升級(jí)也不遲。3. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)Agent 到底由哪些零件組成3.1 一個(gè)最小可用 Agent 的四個(gè)核心模塊把 Agent 拆開來看不管多復(fù)雜的系統(tǒng)核心都離不開這四個(gè)模塊第一模型接口層。負(fù)責(zé)和模型通信處理請(qǐng)求的組裝和響應(yīng)的解析。這一層要處理的關(guān)鍵問題包括怎么設(shè)置系統(tǒng)提示詞、怎么控制輸出格式、怎么處理流式返回、怎么應(yīng)對(duì)超時(shí)和限流。第二記憶模塊。負(fù)責(zé)管理對(duì)話歷史和長(zhǎng)期知識(shí)。短期記憶就是最近幾輪對(duì)話長(zhǎng)期記憶則是通過向量檢索從知識(shí)庫里召回的相關(guān)內(nèi)容。這里最容易踩的坑是上下文長(zhǎng)度管理——對(duì)話輪數(shù)一多token 就爆了必須有一套裁剪或摘要機(jī)制。第三工具系統(tǒng)。這是 Agent 區(qū)別于普通聊天機(jī)器人的關(guān)鍵。工具就是一組可以被模型調(diào)用的函數(shù)每個(gè)函數(shù)有明確的名稱、描述和參數(shù)定義。模型根據(jù)當(dāng)前任務(wù)決定調(diào)用哪個(gè)工具、傳什么參數(shù)。第四執(zhí)行循環(huán)。這是 Agent 的“心臟”負(fù)責(zé)把上面三個(gè)模塊串起來接收用戶輸入組裝上下文調(diào)用模型解析模型的決策執(zhí)行工具把結(jié)果喂回模型如此循環(huán)直到任務(wù)完成或達(dá)到終止條件。這四個(gè)模塊我建議你一開始就分開寫每個(gè)模塊一個(gè)文件接口定義清楚。這樣后面調(diào)試和替換都會(huì)方便很多。3.2 提示詞工程不是玄學(xué)是結(jié)構(gòu)化的溝通很多人把提示詞工程說得神乎其神其實(shí)在我看來它就是用結(jié)構(gòu)化的方式把任務(wù)說清楚。我總結(jié)了一個(gè)自己一直在用的提示詞模板分四個(gè)部分角色定義你是一個(gè) XXX 助手擅長(zhǎng) XXX。 任務(wù)描述用戶會(huì)給你 XXX你需要完成 XXX。 可用工具你可以使用以下工具XXX。 輸出要求請(qǐng)以 XXX 格式輸出注意 XXX。這個(gè)模板看起來簡(jiǎn)單但每一條都有講究。角色定義決定了模型的“人設(shè)”和知識(shí)范圍任務(wù)描述要具體到可執(zhí)行工具說明要讓模型知道每個(gè)工具能干什么、什么時(shí)候用輸出要求則約束了返回格式方便后續(xù)程序解析。我踩過的一個(gè)坑是工具描述寫得太模糊。比如我寫了一個(gè)“查詢信息”的工具描述就寫了“查詢相關(guān)信息”結(jié)果模型經(jīng)常在該用的時(shí)候不用不該用的時(shí)候亂用。后來我把描述改成“根據(jù)用戶提供的訂單號(hào)查詢?cè)撚唵蔚脑敿?xì)狀態(tài)包括發(fā)貨時(shí)間、物流信息、當(dāng)前所在位置”模型的使用準(zhǔn)確率立刻上來了。工具描述要寫到“一個(gè)完全不了解你系統(tǒng)的人看了也知道什么時(shí)候該用”的程度。3.3 上下文管理token 是稀缺資源要省著用上下文窗口是 Agent 最寶貴的資源。我見過太多人把整個(gè)對(duì)話歷史一股腦塞進(jìn)去結(jié)果沒幾輪就爆了。我的做法是分層管理系統(tǒng)提示詞固定不變永遠(yuǎn)保留。最近 N 輪對(duì)話完整保留保證短期連貫性。更早的對(duì)話用模型做一次摘要壓縮成一段話保留。知識(shí)庫召回內(nèi)容按相關(guān)度排序只取 top K 條且每條做長(zhǎng)度截?cái)唷＿@里有個(gè)經(jīng)驗(yàn)值如果模型上下文是 8K token我一般會(huì)把系統(tǒng)提示詞控制在 500 以內(nèi)最近對(duì)話控制在 2000 以內(nèi)摘要控制在 500 以內(nèi)剩下的留給知識(shí)庫召回和模型輸出。這個(gè)分配不是死的要根據(jù)實(shí)際任務(wù)調(diào)整但核心思路是給每一部分都設(shè)一個(gè)預(yù)算不能讓它無限膨脹。注意做摘要的時(shí)候不要讓模型自由發(fā)揮要給它明確的指令比如“請(qǐng)用不超過 200 字總結(jié)以下對(duì)話的關(guān)鍵信息和結(jié)論保留所有數(shù)字和專有名詞”。否則摘要會(huì)越來越模糊最后丟失關(guān)鍵信息。3.4 工具調(diào)用的參數(shù)校驗(yàn)別信模型要信代碼模型返回的工具調(diào)用參數(shù)永遠(yuǎn)不要直接信任。我吃過這個(gè)虧讓模型生成一個(gè)日期參數(shù)它有時(shí)候返回“2024-01-01”有時(shí)候返回“2024年1月1日”有時(shí)候甚至返回“明天”。如果不做校驗(yàn)后面的代碼直接崩。我的做法是在每個(gè)工具函數(shù)入口處做嚴(yán)格的參數(shù)校驗(yàn)def query_order(order_id: str, date: str): # 校驗(yàn) order_id 格式 if not re.match(r^[A-Z0-9]{10}$, order_id): return {error: 訂單號(hào)格式不正確應(yīng)為10位大寫字母或數(shù)字} # 校驗(yàn)日期格式 try: datetime.strptime(date, %Y-%m-%d) except ValueError: return {error: 日期格式不正確應(yīng)為 YYYY-MM-DD} # 通過校驗(yàn)后再執(zhí)行實(shí)際邏輯 ...校驗(yàn)失敗時(shí)不要直接拋異常而是返回一個(gè)結(jié)構(gòu)化的錯(cuò)誤信息讓模型知道哪里錯(cuò)了它下一輪就會(huì)自己糾正。這個(gè)機(jī)制我稱之為“溫和糾錯(cuò)”比直接報(bào)錯(cuò)讓整個(gè)流程中斷要優(yōu)雅得多。4. 實(shí)操過程與核心環(huán)節(jié)實(shí)現(xiàn)從零搭一個(gè)能查資料的 Agent4.1 環(huán)境準(zhǔn)備與依賴安裝這一節(jié)我以 Python 為例因?yàn)?AI 生態(tài)里 Python 的庫最全。前端朋友別慌語法看看就懂邏輯才是關(guān)鍵。首先建一個(gè)干凈的虛擬環(huán)境這是好習(xí)慣避免依賴沖突python -m venv agent-env source agent-env/bin/activate # Windows 用 agent-env\Scripts\activate然后安裝核心依賴。我盡量精簡(jiǎn)只裝必要的pip install openai requests numpyopenai是模型調(diào)用的 SDKrequests用來發(fā) HTTP 請(qǐng)求比如調(diào)外部搜索接口numpy用來做向量計(jì)算。就這三個(gè)夠跑一個(gè)基礎(chǔ) Agent 了。提示不要一上來就裝一堆框架。依賴越少出問題時(shí)排查范圍越小。等你的 Agent 真的需要復(fù)雜功能了再按需引入。4.2 模型接口封裝把通信層做扎實(shí)模型接口層是整個(gè)系統(tǒng)的地基我把它單獨(dú)寫成一個(gè)類方便統(tǒng)一管理import openai import json class LLMClient: def __init__(self, api_key, modelgpt-4): self.client openai.OpenAI(api_keyapi_key) self.model model def chat(self, messages, toolsNone, temperature0.7): params { model: self.model, messages: messages, temperature: temperature, } if tools: params[tools] tools params[tool_choice] auto try: response self.client.chat.completions.create(**params) return response.choices[0].message except Exception as e: return {error: str(e)}這個(gè)封裝做了三件事統(tǒng)一了調(diào)用入口、支持工具調(diào)用、捕獲了異常。異常捕獲很重要網(wǎng)絡(luò)請(qǐng)求隨時(shí)可能失敗不能讓一個(gè)超時(shí)把整個(gè) Agent 搞崩。關(guān)于 temperature 的設(shè)置我的經(jīng)驗(yàn)是需要精確執(zhí)行任務(wù)的場(chǎng)景用 0.1-0.3需要?jiǎng)?chuàng)意生成的場(chǎng)景用 0.7-1.0。Agent 大多數(shù)時(shí)候是在執(zhí)行任務(wù)所以我默認(rèn)用 0.3保證輸出穩(wěn)定。4.3 工具注冊(cè)與執(zhí)行讓模型知道它能干什么工具系統(tǒng)的設(shè)計(jì)我采用“注冊(cè)表”模式。每個(gè)工具是一個(gè)字典包含名稱、描述、參數(shù)定義和執(zhí)行函數(shù)class ToolRegistry: def __init__(self): self.tools {} def register(self, name, description, parameters, func): self.tools[name] { definition: { type: function, function: { name: name, description: description, parameters: parameters } }, func: func } def get_definitions(self): return [t[definition] for t in self.tools.values()] def execute(self, name, arguments): if name not in self.tools: return {error: f工具 {name} 不存在} try: args json.loads(arguments) return self.tools[name][func](**args) except Exception as e: return {error: f工具執(zhí)行失敗{str(e)}}用的時(shí)候這樣注冊(cè)registry ToolRegistry() def search_web(query: str): # 實(shí)際搜索邏輯這里用偽代碼 results do_search(query) return {results: results} registry.register( namesearch_web, description根據(jù)關(guān)鍵詞搜索網(wǎng)絡(luò)信息返回相關(guān)結(jié)果列表。當(dāng)需要獲取最新信息或不確定的事實(shí)時(shí)使用。, parameters{ type: object, properties: { query: { type: string, description: 搜索關(guān)鍵詞盡量具體 } }, required: [query] }, funcsearch_web )這里的關(guān)鍵是描述要寫得足夠清楚。模型完全靠這段描述來判斷什么時(shí)候該用這個(gè)工具。我一般會(huì)寫清楚三件事這個(gè)工具能做什么、什么時(shí)候該用、參數(shù)怎么填。4.4 執(zhí)行循環(huán)Agent 的心臟把上面幾個(gè)模塊串起來就是 Agent 的執(zhí)行循環(huán)def run_agent(user_input, max_turns10): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input} ] for turn in range(max_turns): response llm_client.chat( messagesmessages, toolsregistry.get_definitions() ) # 如果模型沒有調(diào)用工具說明它認(rèn)為可以直接回答 if not response.tool_calls: return response.content # 把模型的決策加入歷史 messages.append(response) # 執(zhí)行所有工具調(diào)用 for tool_call in response.tool_calls: result registry.execute( tool_call.function.name, tool_call.function.arguments ) messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps(result, ensure_asciiFalse) }) return 達(dá)到最大輪次限制任務(wù)未完成這個(gè)循環(huán)的邏輯很清晰調(diào)用模型 → 如果模型要調(diào)工具就執(zhí)行 → 把結(jié)果喂回去 → 再調(diào)用模型 → 直到模型給出最終答案或達(dá)到輪次上限。max_turns這個(gè)參數(shù)很重要它是防止死循環(huán)的保險(xiǎn)絲。我一般設(shè) 10復(fù)雜任務(wù)設(shè) 15。超過這個(gè)輪次還沒完成說明要么任務(wù)太復(fù)雜需要拆分要么提示詞有問題需要人工介入。4.5 記憶模塊的實(shí)現(xiàn)短期與長(zhǎng)期結(jié)合記憶模塊我分兩部分實(shí)現(xiàn)。短期記憶就是上面循環(huán)里的messages列表隨著對(duì)話自然增長(zhǎng)。長(zhǎng)期記憶則是一個(gè)簡(jiǎn)單的向量檢索import numpy as np class Memory: def __init__(self, llm_client): self.llm_client llm_client self.documents [] # 存儲(chǔ)文本 self.embeddings [] # 存儲(chǔ)向量 def add(self, text): embedding self.get_embedding(text) self.documents.append(text) self.embeddings.append(embedding) def search(self, query, top_k3): if not self.embeddings: return [] query_embedding self.get_embedding(query) # 計(jì)算余弦相似度 similarities [] for emb in self.embeddings: sim np.dot(query_embedding, emb) / ( np.linalg.norm(query_embedding) * np.linalg.norm(emb) ) similarities.append(sim) # 取 top_k indices np.argsort(similarities)[-top_k:][::-1] return [self.documents[i] for i in indices] def get_embedding(self, text): # 調(diào)用嵌入接口這里省略具體實(shí)現(xiàn) return call_embedding_api(text)這個(gè)實(shí)現(xiàn)很樸素但對(duì)小規(guī)模知識(shí)庫完全夠用。等文檔數(shù)量上千了再考慮換成專業(yè)的向量數(shù)據(jù)庫。注意余弦相似度計(jì)算前一定要做歸一化否則向量長(zhǎng)度會(huì)影響結(jié)果。我一開始忘了歸一化檢索出來的結(jié)果亂七八糟排查了半天才發(fā)現(xiàn)是這個(gè)原因。5. 常見問題與排查技巧實(shí)錄那些讓我熬夜的坑5.1 模型不調(diào)用工具怎么辦這是最常見的問題。模型明明有工具可用卻選擇直接回答或者該用 A 工具卻用了 B 工具。排查思路如下第一檢查工具描述是否清晰。這是最常見的原因。描述太模糊模型不知道什么時(shí)候該用。解決辦法是把描述寫具體最好包含使用場(chǎng)景的舉例。第二檢查系統(tǒng)提示詞是否強(qiáng)調(diào)了工具的使用。有時(shí)候需要在系統(tǒng)提示詞里明確寫“當(dāng)需要獲取實(shí)時(shí)信息時(shí)必須使用搜索工具不要憑記憶回答”。第三檢查工具數(shù)量是否過多。工具太多會(huì)讓模型選擇困難。我一般把同時(shí)可用的工具控制在 5 個(gè)以內(nèi)超過就分組根據(jù)任務(wù)類型動(dòng)態(tài)加載。第四調(diào)整tool_choice參數(shù)。如果某個(gè)任務(wù)確定必須用工具可以把它設(shè)成強(qiáng)制調(diào)用某個(gè)工具而不是auto。5.2 工具調(diào)用參數(shù)格式錯(cuò)誤模型返回的參數(shù)經(jīng)常不符合預(yù)期比如該傳字符串的傳了數(shù)字該傳數(shù)組的傳了字符串。我的應(yīng)對(duì)策略是雙重保險(xiǎn)一是在工具定義里把參數(shù)類型寫清楚type字段要準(zhǔn)確。二是在工具函數(shù)入口做校驗(yàn)和轉(zhuǎn)換能自動(dòng)轉(zhuǎn)換的就轉(zhuǎn)換不能轉(zhuǎn)換的返回明確錯(cuò)誤。def safe_int(value, default0): try: return int(value) except (ValueError, TypeError): return default這種小工具函數(shù)多寫幾個(gè)能省很多事。5.3 上下文超長(zhǎng)導(dǎo)致報(bào)錯(cuò)對(duì)話輪數(shù)一多token 必然超限。我的處理流程是每次調(diào)用模型前先估算當(dāng)前 messages 的總 token 數(shù)。如果超過預(yù)算的 80%觸發(fā)壓縮。壓縮策略保留系統(tǒng)提示詞和最近 3 輪對(duì)話中間的對(duì)話用模型做摘要。摘要后的內(nèi)容作為一條 system 消息插入。估算 token 有個(gè)粗略公式英文大約 4 個(gè)字符 1 個(gè) token中文大約 1.5 個(gè)字符 1 個(gè) token。這個(gè)不精確但用來做預(yù)警足夠了。5.4 常見問題速查表問題現(xiàn)象可能原因排查方向解決辦法模型不調(diào)用工具描述模糊/提示詞未強(qiáng)調(diào)檢查工具描述和系統(tǒng)提示詞寫具體描述明確使用場(chǎng)景參數(shù)格式錯(cuò)誤類型定義不清檢查參數(shù) schema入口做校驗(yàn)和轉(zhuǎn)換上下文超長(zhǎng)對(duì)話歷史未壓縮估算 token 數(shù)觸發(fā)摘要壓縮循環(huán)不終止工具反復(fù)返回錯(cuò)誤查看工具執(zhí)行日志修復(fù)工具設(shè)置最大輪次響應(yīng)速度慢模型選擇過大/網(wǎng)絡(luò)問題檢查模型和網(wǎng)絡(luò)換小模型或加緩存輸出格式不穩(wěn)定temperature 過高檢查溫度設(shè)置降到 0.3 以下5.5 幾個(gè)讓我印象深刻的踩坑經(jīng)歷坑一工具執(zhí)行結(jié)果太長(zhǎng)把上下文撐爆。有一次我讓 Agent 搜索資料搜索工具返回了整整一頁的原始網(wǎng)頁內(nèi)容直接塞進(jìn)上下文下一輪就超限了。后來我在工具函數(shù)里加了截?cái)噙壿嬛环祷刈钕嚓P(guān)的前 500 字問題解決?？佣Ｐ拖萑搿暗狼秆h(huán)”。工具報(bào)錯(cuò)后模型不停地道歉然后重試同一個(gè)錯(cuò)誤操作。后來我在系統(tǒng)提示詞里加了一句“如果工具連續(xù)兩次返回相同錯(cuò)誤請(qǐng)停止重試并告知用戶”才止住這個(gè)循環(huán)?？尤l(fā)調(diào)用導(dǎo)致狀態(tài)混亂。我一開始讓多個(gè)工具并行執(zhí)行結(jié)果它們同時(shí)修改同一個(gè)狀態(tài)變量數(shù)據(jù)錯(cuò)亂。后來改成串行執(zhí)行或者對(duì)共享狀態(tài)加鎖才穩(wěn)定下來。Agent 的工具執(zhí)行能串行就別并行除非你確定它們互不干擾。6. 工程化落地的一些思考6.1 日志與可觀測(cè)性Agent 的“黑匣子”Agent 最大的問題是“黑盒”——你不知道它為什么做了某個(gè)決策。所以日志系統(tǒng)必須做扎實(shí)。我記錄的內(nèi)容包括每一輪的完整 messages、模型的原始響應(yīng)、工具調(diào)用的名稱和參數(shù)、工具返回的結(jié)果、每一輪的耗時(shí)。這些日志我按會(huì)話 ID 存成 JSON 文件出問題時(shí)可以完整回放整個(gè)執(zhí)行過程。這個(gè)習(xí)慣幫我定位了無數(shù)問題強(qiáng)烈建議你也這么做。6.2 成本控制token 就是錢Agent 跑起來token 消耗是實(shí)打?qū)嵉某杀?。我的控制手段有幾個(gè)緩存相同的查詢直接返回緩存結(jié)果不重復(fù)調(diào)用模型。模型分級(jí)簡(jiǎn)單任務(wù)用小模型復(fù)雜任務(wù)才用大模型。上下文精簡(jiǎn)前面說的壓縮策略本質(zhì)上也是在省錢。設(shè)置預(yù)算上限每個(gè)會(huì)話設(shè)置最大 token 消耗超了就終止。6.3 從 Demo 到產(chǎn)品的距離跑通一個(gè) Demo 可能只需要一天但把它變成能穩(wěn)定服務(wù)的產(chǎn)品需要的工作量是 Demo 的十倍。這中間的差距主要在錯(cuò)誤處理、邊界情況、性能優(yōu)化、監(jiān)控告警、用戶體驗(yàn)。我現(xiàn)在的做法是每做一個(gè)功能先問自己三個(gè)問題出錯(cuò)了怎么辦輸入異常怎么辦用戶等太久怎么辦把這三個(gè)問題想清楚代碼的健壯性會(huì)提升一大截。7. 給同樣在轉(zhuǎn)型路上的朋友幾句實(shí)在話寫了這么多最后分享幾點(diǎn)我自己的真實(shí)體會(huì)不構(gòu)成建議就是個(gè)人經(jīng)驗(yàn)。第一別被“AI 焦慮”裹挾。網(wǎng)上天天有人喊“再不學(xué) AI 就被淘汰了”搞得人心惶惶。但冷靜下來想AI 是工具不是替代品。你原有的工程能力、架構(gòu)思維、業(yè)務(wù)理解一樣都不會(huì)白費(fèi)反而會(huì)在 AI 時(shí)代變得更值錢。轉(zhuǎn)型不是推倒重來是在原有基礎(chǔ)上加一層新能力。第二動(dòng)手比看書重要一百倍。我見過太多人收藏了一堆教程、買了一堆課結(jié)果一行代碼沒寫。AI Agent 這東西看十篇文章不如自己跑通一個(gè) Demo。哪怕是最簡(jiǎn)單的“調(diào)用模型 一個(gè)工具”跑通了你就超過了 80% 只停留在概念層面的人。第三接受“不完美”。模型會(huì)犯錯(cuò)Agent 會(huì)抽風(fēng)這是常態(tài)。不要追求一次做到完美先讓它跑起來再一點(diǎn)點(diǎn)優(yōu)化。我現(xiàn)在的 Agent 也經(jīng)常出問題但每次出問題都是一次學(xué)習(xí)機(jī)會(huì)修著修著就越來越穩(wěn)了。第四保持記錄的習(xí)慣。這個(gè) DAY 系列對(duì)我來說最大的價(jià)值不是給別人看而是逼自己每天復(fù)盤。今天學(xué)了什么、踩了什么坑、想通了什么寫下來過段時(shí)間回頭看進(jìn)步一目了然。如果你也在轉(zhuǎn)型強(qiáng)烈建議你也開一個(gè)自己的記錄系列哪怕沒人看對(duì)自己也是極好的沉淀。這個(gè)系列我還會(huì)繼續(xù)寫下去后面可能會(huì)聊聊多 Agent 協(xié)作、Agent 的評(píng)估體系、以及怎么把 Agent 集成到實(shí)際業(yè)務(wù)系統(tǒng)里。路還長(zhǎng)一起走。