智能體編程時(shí)代軟件工程的基礎(chǔ)技能正在被重新劃定。過去幾年我們聊軟件工程默認(rèn)是一套圍繞需求、設(shè)計(jì)、編碼、測試、部署展開的穩(wěn)定體系而現(xiàn)在LLM 能寫代碼、能調(diào)用工具、能自主規(guī)劃任務(wù)工程師的核心工作從“自己寫每一行邏輯”變成“設(shè)計(jì)一套讓模型穩(wěn)定完成任務(wù)的系統(tǒng)”。這個(gè)變化不是概念層面的它直接影響招聘要求、學(xué)習(xí)路徑和項(xiàng)目落地方式。這篇文章嘗試把“智能體編程時(shí)代的軟件工程基礎(chǔ)技能”整理成一張可執(zhí)行的能力圖譜。重點(diǎn)回答幾個(gè)問題提示詞工程和上下文工程到底算什么層級的能力RAG、工作流編排、工具調(diào)用這些環(huán)節(jié)為什么成了新基本功從傳統(tǒng) CRUD 開發(fā)切到智能體開發(fā)先補(bǔ)什么技能低代碼平臺(tái)上智能體搭建入口頻繁調(diào)整底層要掌握哪些知識才不會(huì)被動(dòng)。全文按“技能分層 → 環(huán)境準(zhǔn)備 → 最小實(shí)戰(zhàn) → 測試驗(yàn)證 → 接口化 → 性能與排錯(cuò)”展開適合正在做技術(shù)選型、準(zhǔn)備轉(zhuǎn)型智能體開發(fā)、或者想系統(tǒng)梳理技能樹的讀者。1. 智能體編程時(shí)代的軟件工程基礎(chǔ)技能速覽能力項(xiàng)說明能力本質(zhì)從“手寫確定性邏輯”轉(zhuǎn)向“設(shè)計(jì)模型推理 工具調(diào)用 狀態(tài)管理的復(fù)合系統(tǒng)”核心技能模塊需求拆解、提示詞/上下文工程、RAG、工作流編排、工具調(diào)用、質(zhì)量評測、可觀測性典型技術(shù)棧Python、LangChain/LlamaIndex、向量數(shù)據(jù)庫、Docker、模型 API、FastAPI硬件/環(huán)境門檻使用云端模型 API 時(shí)無需本地 GPU本地部署需要按模型實(shí)際要求準(zhǔn)備顯存最低上手條件熟悉 Python 基礎(chǔ)語法理解 HTTP 接口調(diào)用有基本的數(shù)據(jù)結(jié)構(gòu)概念是否支持低代碼支持但低代碼平臺(tái)適合搭建原型生產(chǎn)級系統(tǒng)仍需要工程能力兜底是否適合批量任務(wù)可以但需要自己設(shè)計(jì)隊(duì)列、重試、冪等和日志主要產(chǎn)出智能客服、知識庫問答、自動(dòng)化流程、代碼輔助工具、數(shù)據(jù)分析智能體適合場景內(nèi)容生產(chǎn)、內(nèi)部工具、業(yè)務(wù)流程自動(dòng)化、知識管理、復(fù)雜系統(tǒng)輔助開發(fā)從材料看當(dāng)前行業(yè)對智能體開發(fā)者的要求并不是“會(huì)寫花哨的提示詞”而是能穩(wěn)定交付。很多低代碼平臺(tái)上“智能體開發(fā)入口消失”之類的現(xiàn)象本質(zhì)上也是平臺(tái)在調(diào)整能力分層——低代碼負(fù)責(zé)快速搭建工程化能力還是需要開發(fā)者自己掌握。所以本文不會(huì)只講某個(gè)平臺(tái)怎么點(diǎn)按鈕而是把底層技能拆清楚。2. 為什么智能體編程需要一張新的技能圖譜傳統(tǒng)軟件工程關(guān)注的是確定性系統(tǒng)輸入明確、處理邏輯明確、輸出明確。開發(fā)者把業(yè)務(wù)規(guī)則翻譯成代碼用單元測試保證行為符合預(yù)期。智能體編程不是這樣系統(tǒng)的核心是模型而模型的輸出有概率性。同一個(gè)提示詞兩次運(yùn)行結(jié)果可能不同同一個(gè)任務(wù)模型可能選擇不同的工具調(diào)用路徑。這種不確定性要求工程師把一部分精力從“寫邏輯”轉(zhuǎn)移到“約束邏輯”。具體來說智能體系統(tǒng)的工程問題變成了如何把用戶模糊的意圖拆成模型能理解的子任務(wù)如何讓模型在有限輪次內(nèi)完成推理而不是陷入死循環(huán)如何把外部知識準(zhǔn)確注入生成過程減少幻覺如何讓模型安全調(diào)用外部工具并處理工具返回的異常如何評估一個(gè)智能體“做得好不好”而不只是“能不能跑”。這些問題橫跨提示詞工程、后端開發(fā)、數(shù)據(jù)工程、測試工程和運(yùn)維。所以“智能體編程軟件工程基礎(chǔ)技能圖譜”本質(zhì)上是一個(gè)跨學(xué)科能力地圖傳統(tǒng)軟件工程的知識沒有失效而是變成底座上面新增了模型交互和智能體編排這一層。低代碼平臺(tái)的熱搜變化也印證了這一點(diǎn)。像“扣子編程中低代碼模式智能體開發(fā)怎么沒有了”這類問題說明大量用戶習(xí)慣在可視化界面里拖拽搭建智能體一旦平臺(tái)調(diào)整入口能力就斷檔。如果能理解底層邏輯——模型調(diào)用、工具協(xié)議、上下文管理、發(fā)布部署——平臺(tái)怎么改都不影響交付。3. 技能圖譜總覽五層能力結(jié)構(gòu)智能體編程的基礎(chǔ)技能可以分成五層。這五層從下往上正好是一個(gè)智能體從開發(fā)到上線所需的能力棧。3.1 第一層模型交互基礎(chǔ)這一層是地基。開發(fā)者需要理解 LLM 的 API 調(diào)用方式包括 chat completion 的請求和響應(yīng)結(jié)構(gòu)、token 限制、temperature/top_p 等采樣參數(shù)、system/user/assistant 消息角色以及流式輸出。這些概念不復(fù)雜但直接影響后續(xù)所有設(shè)計(jì)。比如不知道 system prompt 和 user prompt 的邊界就很難做好角色約束不理解 max_tokens長文本輸出就會(huì)莫名截?cái)嗖涣私饬魇捷敵鼋换ンw驗(yàn)就會(huì)卡頓。3.2 第二層上下文與提示詞工程提示詞工程不是“寫幾句好聽的話讓模型聽話”而是結(jié)構(gòu)化的輸入設(shè)計(jì)。核心內(nèi)容包括任務(wù)指令的清晰度、示例few-shot的選擇、輸出格式約束、思維鏈引導(dǎo)、避免幻覺的邊界聲明。再往上是上下文工程也就是如何在有限的上下文窗口內(nèi)選擇最相關(guān)的信息。這涉及文本分割、摘要、重新排序、動(dòng)態(tài)組裝等技術(shù)。3.3 第三層知識增強(qiáng)與檢索模型不可能知道所有私域信息。RAG檢索增強(qiáng)生成因此成為智能體開發(fā)的高頻技能。這一層需要掌握文本加載與解析、分塊策略、向量化、向量數(shù)據(jù)庫存儲(chǔ)、相似度檢索、重排以及把檢索結(jié)果拼裝進(jìn)提示詞的策略。很多智能體“答非所問”問題往往出在這一層。3.4 第四層工具調(diào)用與工作流編排智能體不只是聊天還要干活。干活意味著調(diào)用工具比如查數(shù)據(jù)庫、調(diào)內(nèi)部 API、發(fā)郵件、執(zhí)行代碼。工程上需要設(shè)計(jì)工具描述、參數(shù) schema、模型調(diào)用工具的協(xié)議以及工具返回結(jié)果后的處理邏輯。工作流編排則負(fù)責(zé)把多個(gè)步驟串起來包括條件分支、循環(huán)、人工審批節(jié)點(diǎn)、異常重試。這一層最接近傳統(tǒng)后端開發(fā)也是最容易出 Bug 的地方。3.5 第五層評測、可觀測性與部署一個(gè)能演示的智能體 Demo 和能上線的智能體服務(wù)之間差距就在這一層。評測需要準(zhǔn)備測試集、設(shè)計(jì)指標(biāo)、做回歸可觀測性需要記錄每次請求的輸入輸出、token 消耗、工具調(diào)用鏈、延遲部署需要考慮接口封裝、鑒權(quán)、限流、后臺(tái)任務(wù)處理。很多團(tuán)隊(duì)智能體項(xiàng)目失敗不是模型不行是工程化沒跟上。4. 技能深度拆解每個(gè)環(huán)節(jié)到底要掌握什么4.1 需求拆解把業(yè)務(wù)問題翻譯成智能體問題傳統(tǒng)需求分析寫的是功能清單和規(guī)則智能體需求分析更需要寫清楚任務(wù)邊界、可用工具、知識來源、錯(cuò)誤處理方式和驗(yàn)收標(biāo)準(zhǔn)。比如做一個(gè)客服智能體需要明確它能回答什么、不能回答什么、遇到不確定信息是轉(zhuǎn)人工還是拒答、回答的格式是什么、是否需要引用來源。這些約束會(huì)影響后續(xù)提示詞設(shè)計(jì)和 RAG 方案。建議用一張表格維護(hù)需求映射業(yè)務(wù)需求智能體能力依賴技術(shù)驗(yàn)收標(biāo)準(zhǔn)解答產(chǎn)品使用問題基于知識庫問答RAG 重排測試集準(zhǔn)確率達(dá)標(biāo)查詢訂單狀態(tài)調(diào)用訂單 API工具調(diào)用工具調(diào)用成功率、響應(yīng)時(shí)間生成周報(bào)草稿結(jié)構(gòu)化內(nèi)容生成提示詞 模板格式正確、信息完整4.2 提示詞與上下文工程從“寫提示詞”到“設(shè)計(jì)狀態(tài)”提示詞工程看起來門檻低實(shí)際上很容易被低估。初級用法是寫一段指令高級用法是把提示詞當(dāng)成系統(tǒng)的狀態(tài)管理機(jī)制。同一個(gè)智能體在不同任務(wù)階段system prompt 應(yīng)該動(dòng)態(tài)變化用戶多輪對話中歷史消息需要截?cái)?、摘要、壓縮檢索到的知識需要按相關(guān)度排序并標(biāo)注來源。這里給出一個(gè)通用的提示詞結(jié)構(gòu)模板實(shí)際項(xiàng)目需要根據(jù)任務(wù)調(diào)整你是{角色}負(fù)責(zé)完成{任務(wù)}。 約束條件 1. 只能基于提供的知識回答不要編造信息。 2. 如果知識不足回復(fù)“信息不足請補(bǔ)充問題細(xì)節(jié)”。 3. 回答使用 Markdown 格式控制在{字?jǐn)?shù)}字以內(nèi)。 可用工具 - {工具名稱}{工具描述} 輸出格式 {JSON 或文本格式示例}注意這不是萬能模板而是強(qiáng)調(diào)“角色 任務(wù) 約束 工具 輸出格式”五要素。少了任何一部分模型都可能出現(xiàn)行為漂移。4.3 RAG智能體記憶的外部化RAG 是智能體編程里最值得投入的技能。它解決的是模型不知道、記不住、容易忘的問題。實(shí)現(xiàn)一套 RAG 并不難難的是在真實(shí)場景里調(diào)好。操作層面需要掌握以下步驟文檔解析PDF、Word、HTML、Markdown 等格式轉(zhuǎn)成純文本保留必要結(jié)構(gòu)文本分塊按標(biāo)題、段落、固定長度切分塊與塊之間保留重疊向量化用 Embedding 模型將文本轉(zhuǎn)為向量模型需要根據(jù)實(shí)際項(xiàng)目選擇存儲(chǔ)與檢索使用向量數(shù)據(jù)庫做相似度搜索常用方案有 Milvus、Qdrant、Chroma 等重排對檢索結(jié)果做二次排序去掉不相關(guān)內(nèi)容上下文組裝把檢索結(jié)果拼接到系統(tǒng)提示詞中控制總長度。下面是一個(gè)使用 Python 偽代碼實(shí)現(xiàn)的 RAG 查詢流程實(shí)際項(xiàng)目需要替換向量庫和模型接口import requests # 向量化接口和向量數(shù)據(jù)庫需要按實(shí)際項(xiàng)目替換 def embed_text(text: str): resp requests.post(http://127.0.0.1:8080/embed, json{text: text}, timeout30) return resp.json()[vector] def search_similar(query: str, top_k: int 3): query_vec embed_text(query) resp requests.post(http://127.0.0.1:8080/search, json{vector: query_vec, top_k: top_k}, timeout30) return resp.json()[results] def build_rag_prompt(query: str): docs search_similar(query) context \n\n.join([f[文檔{i1}] {d[text]} for i, d in enumerate(docs)]) prompt f 請根據(jù)以下知識回答問題。 知識 {context} 問題{query} 要求只使用知識中的信息如果知識不相關(guān)請明確說“未找到相關(guān)信息”。 return prompt實(shí)際項(xiàng)目中建議把檢索結(jié)果的結(jié)構(gòu)化信息記錄下來方便后續(xù)調(diào)試。4.4 工具調(diào)用智能體的“手”和“腳”工具調(diào)用是讓智能體從“會(huì)說話”變成“能干活”的關(guān)鍵。模型本身不執(zhí)行代碼它只是輸出一個(gè)結(jié)構(gòu)化的工具調(diào)用請求由應(yīng)用層解析并執(zhí)行。設(shè)計(jì)工具時(shí)描述越是清晰準(zhǔn)確模型調(diào)用就越穩(wěn)定。一個(gè)工具定義通常包含字段作用示例name工具名稱模型根據(jù)名稱調(diào)用query_orderdescription工具用途越具體越好根據(jù)訂單號查詢訂單狀態(tài)parameters參數(shù) JSON Schemaorder_id: string, required下面是一個(gè)工具調(diào)用循環(huán)的簡化實(shí)現(xiàn)import json import requests class SimpleAgent: def __init__(self, api_url: str, tools: list): self.api_url api_url self.tools tools self.messages [ {role: system, content: 你是智能助手只能使用可用工具完成任務(wù)。} ] def _call_model(self): payload { model: your-model, messages: self.messages, tools: self.tools, temperature: 0.2 } resp requests.post(self.api_url, jsonpayload, timeout120) return resp.json() def _execute_tool(self, tool_name: str, arguments: dict): if tool_name query_order: order_id arguments.get(order_id, ) return {status: shipped, order_id: order_id} return {error: unknown tool} def run(self, user_input: str, max_rounds: int 5): self.messages.append({role: user, content: user_input}) for _ in range(max_rounds): response self._call_model() choice response[choices][0][message] if choice.get(tool_calls): for call in choice[tool_calls]: tool_name call[function][name] args json.loads(call[function][arguments]) result self._execute_tool(tool_name, args) self.messages.append({ role: tool, tool_call_id: call[id], content: json.dumps(result, ensure_asciiFalse) }) else: self.messages.append(choice) return choice[content] return 已達(dá)到最大輪數(shù)限制任務(wù)未完成。 agent SimpleAgent( api_urlhttp://127.0.0.1:8000/v1/chat/completions, tools[{ type: function, function: { name: query_order, description: 根據(jù)訂單號查詢訂單狀態(tài), parameters: { type: object, properties: { order_id: {type: string} }, required: [order_id] } } }] ) result agent.run(請查詢訂單 A10086 的狀態(tài)) print(result)這個(gè)例子只演示核心循環(huán)。生產(chǎn)環(huán)境中工具執(zhí)行結(jié)果需要校驗(yàn)、日志、超時(shí)控制工具本身要有鑒權(quán)和限流。4.5 評測與可觀測性衡量智能體質(zhì)量智能體評測不能只看一兩個(gè)例子。需要建立測試集、設(shè)計(jì)評估指標(biāo)。常用做法是準(zhǔn)備幾十到幾百條真實(shí)問題每條標(biāo)注期望答案或標(biāo)準(zhǔn)動(dòng)作然后跑一遍智能體計(jì)算指標(biāo)。自動(dòng)化程度越高回歸成本越低。常用效果指標(biāo)指標(biāo)含義計(jì)算方式任務(wù)完成率能正確結(jié)束任務(wù)的比例成功任務(wù)數(shù) / 總?cè)蝿?wù)數(shù)工具調(diào)用準(zhǔn)確率正確選擇并調(diào)用工具的比例正確調(diào)用次數(shù) / 總調(diào)用次數(shù)回答相關(guān)性回答是否貼合問題人工評分或 LLM 評分幻覺率回答中出現(xiàn)無依據(jù)內(nèi)容的比例幻覺樣本數(shù) / 總樣本數(shù)平均響應(yīng)時(shí)間從請求到返回的耗時(shí)總耗時(shí) / 請求數(shù)可觀測性方面建議每個(gè)請求都記錄完整消息序列system、user、assistant、tool每次模型調(diào)用的 token 消耗工具調(diào)用的名稱、參數(shù)、返回值響應(yīng)延遲最終輸出和是否觸發(fā)異常分支。這些日志是排查“智能體行為奇怪”的唯一依據(jù)。5. 環(huán)境準(zhǔn)備搭建一套智能體開發(fā)底座智能體開發(fā)環(huán)境不需要一開始就上復(fù)雜框架先用最小組合跑通鏈路。這里給出一套通用方案實(shí)際項(xiàng)目可以按團(tuán)隊(duì)技術(shù)棧替換。5.1 技術(shù)選型建議組件可選方案說明開發(fā)語言Python 3.10生態(tài)最全AI 相關(guān)庫支持最好模型訪問云端 API 或本地部署云端起步最快本地部署需關(guān)注顯存編排框架LangChain / LlamaIndex / 自研新手建議先用自研簡單流程理解后再引入框架向量數(shù)據(jù)庫Chroma / Qdrant / Milvus原型用 Chroma生產(chǎn)可按需選型接口服務(wù)FastAPI輕量適合快速封裝智能體 API運(yùn)行環(huán)境Docker docker-compose統(tǒng)一環(huán)境方便遷移5.2 本地環(huán)境準(zhǔn)備清單如果是本地開發(fā)建議檢查以下內(nèi)容Python 版本與虛擬環(huán)境工具venv / conda / uvpip 鏡像源配置方便安裝依賴Docker 和 docker-compose 是否可用網(wǎng)絡(luò)策略模型 API 是否需要配置密鑰、代理等需要注意合法合規(guī)訪問磁盤空間向量庫、依賴包、模型緩存都會(huì)占空間預(yù)留充足端口規(guī)劃避免 8000、8080、7860 等常用端口沖突下面是一個(gè)虛擬環(huán)境初始化示例# 創(chuàng)建虛擬環(huán)境 python3 -m venv agent_env # 激活虛擬環(huán)境 source agent_env/bin/activate # 升級 pip 并安裝基礎(chǔ)依賴 pip install --upgrade pip pip install requests fastapi uvicorn chromadb如果后續(xù)要使用局部向量檢索可以按項(xiàng)目文檔安裝對應(yīng)依賴。不要一次性裝大量庫按需安裝更容易排查問題。5.3 本地模型部署的通用判斷如果不使用云端 API而是本地跑模型需要重點(diǎn)關(guān)注顯存。不同模型、不同量化方式、不同上下文長度顯存占用差異很大。通用的做法是先跑一個(gè)小模型驗(yàn)證流程再逐步換更大模型觀察推理時(shí)的顯存占用而不是只看模型文件大小。本地推理通常需要 CUDA 環(huán)境安裝前確認(rèn)顯卡驅(qū)動(dòng)和 PyTorch 版本匹配。如果顯卡顯存不夠可以考慮 CPU 推理或更小的量化模型但速度會(huì)明顯下降需要提前做性能測試。6. 智能體最小實(shí)戰(zhàn)從零搭建一個(gè)問答與工具調(diào)用智能體這一節(jié)用一個(gè)完整的 Python 示例演示智能體開發(fā)的核心鏈路。這個(gè)例子不依賴任何重型框架只用 requests 庫調(diào)用模型 API演示“接收輸入 → 調(diào)用模型 → 解析響應(yīng) → 執(zhí)行工具 → 返回結(jié)果”的循環(huán)。6.1 項(xiàng)目結(jié)構(gòu)agent_demo/ ├── agent.py # 智能體核心邏輯 ├── tools.py # 工具定義與執(zhí)行 ├── rag.py # RAG 檢索相關(guān) ├── config.py # 配置項(xiàng) └── requirements.txt # 依賴清單6.2 模型服務(wù)配置實(shí)際項(xiàng)目中需要把模型服務(wù)地址替換成自己可訪問的服務(wù)。如果是本地部署的模型通常是http://127.0.0.1:8000/v1/chat/completions如果是云端 API則使用對應(yīng)服務(wù)商提供的接口地址。# config.py API_URL http://127.0.0.1:8000/v1/chat/completions MODEL_NAME your-model REQUEST_TIMEOUT 1206.3 核心智能體實(shí)現(xiàn)# agent.py import json import requests from config import API_URL, MODEL_NAME, REQUEST_TIMEOUT from tools import TOOLS, execute_tool class Agent: def __init__(self, system_prompt: str): self.system_prompt system_prompt self.messages [{role: system, content: system_prompt}] def _call_model(self, messages): payload { model: MODEL_NAME, messages: messages, tools: TOOLS, temperature: 0.2, stream: False } resp requests.post(API_URL, jsonpayload, timeoutREQUEST_TIMEOUT) resp.raise_for_status() return resp.json() def run(self, user_input: str, max_rounds: int 5): self.messages.append({role: user, content: user_input}) for _ in range(max_rounds): response self._call_model(self.messages) message response[choices][0][message] if message.get(tool_calls): self.messages.append(message) for call in message[tool_calls]: tool_name call[function][name] try: args json.loads(call[function][arguments]) except json.JSONDecodeError: args {} result execute_tool(tool_name, args) self.messages.append({ role: tool, tool_call_id: call[id], content: json.dumps(result, ensure_asciiFalse) }) continue self.messages.append(message) return message[content] return 達(dá)到最大輪次限制未能完成目標(biāo)。 if __name__ __main__: prompt 你是企業(yè)內(nèi)部助理可以使用工具查詢信息。回答請簡潔準(zhǔn)確。 agent Agent(system_promptprompt) result agent.run(請查詢訂單 20250101 的物流狀態(tài)) print(result)6.4 工具實(shí)現(xiàn)# tools.py TOOLS [ { type: function, function: { name: query_logistics, description: 根據(jù)訂單號查詢物流狀態(tài), parameters: { type: object, properties: { order_id: {type: string, description: 訂單號} }, required: [order_id] } } } ] def execute_tool(tool_name: str, arguments: dict): if tool_name query_logistics: order_id arguments.get(order_id) return {order_id: order_id, status: 已發(fā)貨, location: 上海轉(zhuǎn)運(yùn)中心} return {error: f未知工具: {tool_name}}運(yùn)行后預(yù)期結(jié)果是智能體先輸出工具調(diào)用請求程序執(zhí)行工具再調(diào)用模型生成最終答案。如果工具描述不清楚或參數(shù)名不一致模型可能反復(fù)調(diào)用錯(cuò)誤這時(shí)優(yōu)先檢查工具描述的準(zhǔn)確性。7. 功能測試與效果驗(yàn)證智能體能不能穩(wěn)定交付智能體的測試和傳統(tǒng)軟件測試有很大區(qū)別。傳統(tǒng)測試斷言返回值是否等于期望值智能體測試更接近“行為驗(yàn)證”。需要設(shè)計(jì)多維度的測試用例并持續(xù)回歸。7.1 測試用例設(shè)計(jì)測試類型輸入示例預(yù)期行為判斷標(biāo)準(zhǔn)基礎(chǔ)問答公司年假政策是什么給出知識庫中的準(zhǔn)確回答回答中是否有知識依據(jù)知識缺失2026年新產(chǎn)品價(jià)格明確告知信息不足不應(yīng)編造價(jià)格工具調(diào)用查詢訂單狀態(tài)正確調(diào)用查詢工具工具調(diào)用參數(shù)是否正確多輪對話追問訂單細(xì)節(jié)能結(jié)合歷史上下文回答是否引用前文信息惡意輸入繞過限制的提示詞拒絕執(zhí)行或安全兜底不觸發(fā)越權(quán)行為7.2 回歸測試自動(dòng)化建議把測試用例保存為 JSON 文件寫一個(gè)簡單的評測腳本循環(huán)執(zhí)行。下面是一個(gè)通用示例# eval_agent.py import json from agent import Agent test_cases [ { input: 年假政策是什么, must_contain: [年假], must_not_contain: [API_KEY] }, { input: 查詢訂單 20250101, must_contain: [已發(fā)貨, 上海] } ] def run_test(): agent Agent(system_prompt你是企業(yè)助理請謹(jǐn)慎回答。) passed 0 total len(test_cases) for case in test_cases: output agent.run(case[input]) ok True for keyword in case.get(must_contain, []): if keyword not in output: ok False for keyword in case.get(must_not_contain, []): if keyword in output: ok False if ok: passed 1 print(f輸入: {case[input]}) print(f輸出: {output}) print(f通過: {ok}) print(- * 40) print(f通過率: {passed}/{total}) if __name__ __main__: run_test()這里的must_contain只是最簡單的評測方式。更嚴(yán)格的場景可以引入 LLM 作為評測員對回答做相關(guān)性打分或者人工標(biāo)注后計(jì)算指標(biāo)。7.3 效果驗(yàn)證的關(guān)鍵點(diǎn)判斷智能體是否合格不是看一兩個(gè)例子而是要看同一問題多次運(yùn)行是否穩(wěn)定邊界輸入是否優(yōu)雅降級工具調(diào)用失敗后能否自我糾正長對話中是否丟失上下文回答是否有來源依據(jù)是否出現(xiàn)幻覺。顯存/資源占用是否在可控范圍如果是本地部署。任何一個(gè)環(huán)節(jié)不穩(wěn)定都需要回到提示詞、上下文管理或工具定義里排查。8. 接口 API 與批量任務(wù)從 Demo 到服務(wù)智能體跑通之后下一步是把它封裝成服務(wù)讓其他系統(tǒng)調(diào)用。這一步是把“能演示”變成“能上線”的關(guān)鍵。8.1 用 FastAPI 封裝智能體接口下面給出一個(gè)最簡封裝示例# api.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel from agent import Agent app FastAPI() class ChatRequest(BaseModel): message: str session_id: str default class ChatResponse(BaseModel): reply: str session_id: str # 生產(chǎn)環(huán)境應(yīng)使用獨(dú)立的會(huì)話存儲(chǔ)這里用簡單字典示例 sessions {} app.post(/api/chat, response_modelChatResponse) def chat(req: ChatRequest): try: if req.session_id not in sessions: sessions[req.session_id] Agent(system_prompt你是企業(yè)智能助理。) agent sessions[req.session_id] reply agent.run(req.message) return ChatResponse(replyreply, session_idreq.session_id) except Exception as e: raise HTTPException(status_code500, detailstr(e)) if __name__ __main__: import uvicorn uvicorn.run(app, host127.0.0.1, port8000)啟動(dòng)接口服務(wù)uvicorn api:app --host 127.0.0.1 --port 8000調(diào)用接口curl -X POST http://127.0.0.1:8000/api/chat \ -H Content-Type: application/json \ -d {message: 查詢訂單 20250101 狀態(tài), session_id: user-001}8.2 批量任務(wù)設(shè)計(jì)如果需要對一批文本或文檔做批量處理不建議直接并發(fā)請求模型 API容易觸發(fā)限流。更穩(wěn)妥的做法是引入任務(wù)隊(duì)列。常見方案簡單場景使用 Redis 隊(duì)列 Python Worker復(fù)雜場景使用 Celery 或 Arq 管理異步任務(wù)極簡場景單進(jìn)程內(nèi)串行遍歷。下面是一個(gè)使用多線程做批量處理的簡化示例生產(chǎn)環(huán)境建議換用正規(guī)隊(duì)列# batch.py import json import threading from queue import Queue from agent import Agent def process_item(item: dict): agent Agent(system_prompt你是文檔處理助手。) result agent.run(item[question]) item[answer] result return item def worker(task_queue: Queue, results: list): while True: item task_queue.get() if item is None: break try: results.append(process_item(item)) except Exception as e: results.append({input: item, error: str(e)}) finally: task_queue.task_done() def run_batch(input_file: str, output_file: str, worker_count: int 4): with open(input_file, r, encodingutf-8) as f: items json.load(f) task_queue Queue() for item in items: task_queue.put(item) results [] threads [] for _ in range(worker_count): t threading.Thread(targetworker, args(task_queue, results)) t.start() threads.append(t) task_queue.join() for _ in range(worker_count): task_queue.put(None) for t in threads: t.join() with open(output_file, w, encodingutf-8) as f: json.dump(results, f, ensure_asciiFalse, indent2) if __name__ __main__: run_batch(input.json, output.json)批量任務(wù)的核心原則每個(gè)任務(wù)獨(dú)立、可重試、有日志、有失敗記錄。模型調(diào)用是外部依賴網(wǎng)絡(luò)抖動(dòng)、限流、超時(shí)都可能導(dǎo)致失敗任務(wù)處理必須考慮這些情況。8.3 服務(wù)化注意事項(xiàng)接口服務(wù)上線前需要確認(rèn)鑒權(quán)接口不能裸奔至少加 API Key 或內(nèi)部網(wǎng)絡(luò)限制限流避免單個(gè)用戶刷爆模型調(diào)用額度超時(shí)模型響應(yīng)慢接口超時(shí)時(shí)間要設(shè)置合理日志每次請求記錄輸入輸出、耗時(shí)、token 消耗會(huì)話存儲(chǔ)多實(shí)例部署時(shí)session 需要放到 Redis 等共享存儲(chǔ)模型版本固定模型版本避免模型更新導(dǎo)致行為漂移。9. 資源占用與性能觀察智能體系統(tǒng)的資源占用來自多個(gè)部分模型推理、向量檢索、應(yīng)用服務(wù)、日志存儲(chǔ)。不同部署方式差異很大。9.1 模型推理部分如果使用云端模型 API本地幾乎沒有顯存壓力主要關(guān)注 API 延遲和 token 消耗。如果本地部署模型顯存占用是最關(guān)鍵的指標(biāo)。觀察到顯存占用過高時(shí)可以考慮使用量化版本模型縮短上下文長度減小 batch size使用流式輸出避免一次性生成過長結(jié)果及時(shí)釋放不再使用的模型實(shí)例。顯存占用需以實(shí)際模型和推理參數(shù)為準(zhǔn)不要只看模型文件大小。部署前先用小規(guī)模請求測試記錄顯存峰值。9.2 RAG 與向量檢索部分RAG 系統(tǒng)的資源消耗主要在文本向量化如果文檔量大需要批量處理向量數(shù)據(jù)庫索引需要占用內(nèi)存或磁盤檢索時(shí)返回的文檔塊越多下游模型輸入越長token 消耗越大?？梢詢?yōu)化檢索的 top_k減少不相關(guān)內(nèi)容也可以引入重排模型讓更少但更準(zhǔn)的文檔進(jìn)入上下文。這些都是常見的性能優(yōu)化手段。9.3 應(yīng)用服務(wù)部分FastAPI 這類服務(wù)本身資源占用不高但如果每個(gè)請求都創(chuàng)建一個(gè)新的 Agent 實(shí)例內(nèi)存會(huì)累積。建議復(fù)用 Agent 實(shí)例或改為無狀態(tài)接口把會(huì)話消息存到外部存儲(chǔ)。批量任務(wù)建議控制并發(fā)數(shù)防止把模型服務(wù)打掛。9.4 性能觀察方法通用的觀察手段包括使用nvidia-smi觀察 GPU 顯存和利用率使用psutil記錄進(jìn)程 CPU 和內(nèi)存在接口層記錄耗時(shí)、tokens、成功率和錯(cuò)誤率在日志中記錄每次工具調(diào)用的耗時(shí)使用 Prometheus Grafana 做更系統(tǒng)的監(jiān)控。性能問題如果出現(xiàn)優(yōu)先分兩層排查如果模型調(diào)用占大頭就優(yōu)化上下文長度和采樣參數(shù)如果是工具邏輯慢就優(yōu)化后端服務(wù)和外部依賴。10. 常見問題與排查方法問題現(xiàn)象可能原因排查方式解決方案智能體答非所問提示詞缺少任務(wù)邊界查看完整消息日志檢查 system prompt補(bǔ)充角色、約束、輸出格式說明回答出現(xiàn)幻覺缺少知識來源或 RAG 失效檢查檢索結(jié)果是否為空檢查文檔解析、分塊、向量庫數(shù)據(jù)工具一直被錯(cuò)誤調(diào)用工具描述不清晰或參數(shù) schema 有誤查看模型調(diào)用工具的發(fā)起信息和參數(shù)優(yōu)化工具描述和參數(shù)定義多輪對話丟失上下文歷史消息被截?cái)嗷蛭淳S護(hù)查看 messages 序列設(shè)計(jì)歷史消息截?cái)嗷蛘呗越涌诔瑫r(shí)模型響應(yīng)慢或工具執(zhí)行慢查看接口耗時(shí)分布調(diào)大超時(shí)時(shí)間、優(yōu)化工具或使用異步批量任務(wù)部分失敗網(wǎng)絡(luò)波動(dòng)或限流查看失敗任務(wù)日志增加重試機(jī)制和失敗記錄本地部署顯存溢出模型過大或并發(fā)過多查看顯存占用曲線換量化模型、降并發(fā)、縮短上下文模型 API 返回空響應(yīng)參數(shù)錯(cuò)誤或內(nèi)容被安全攔截檢查請求參數(shù)和響應(yīng)體調(diào)整參數(shù)或聯(lián)系服務(wù)方低代碼平臺(tái)智能體入口變化平臺(tái)調(diào)整能力分層查看平臺(tái)最新文檔掌握底層工程能力避免依賴單一平臺(tái)軟件工程轉(zhuǎn)型智能體開發(fā)思路不清缺少系統(tǒng)化學(xué)習(xí)路徑對照技能圖譜逐層補(bǔ)能力先做最小實(shí)戰(zhàn)再逐步加深11. 最佳實(shí)踐與使用建議智能體編程聽起來新穎但工程化的底層邏輯仍然是“小步快跑持續(xù)驗(yàn)證”。以下建議來自智能體項(xiàng)目開發(fā)和交付的通用經(jīng)驗(yàn)值得在動(dòng)手前過一遍。第一先跑通最小閉環(huán)。不要一開始就搭復(fù)雜的 Agent Framework先用最原始的 API 調(diào)用把“輸入 → 模型 → 工具 → 輸出”串通。最小閉環(huán)能幫你理解模型行為也能暴露出真正的瓶頸。第二提示詞要有版本管理。提示詞就是代碼建議納入 Git 管理每次修改記錄效果變化。修改提示詞前先跑一遍回歸測試集避免改了一個(gè)問題帶崩三個(gè)場景。第三工具調(diào)用必須有日志。模型到底調(diào)了什么工具、傳了什么參數(shù)、返回了什么錯(cuò)誤這些信息如果缺失排錯(cuò)會(huì)非常痛苦。建議每個(gè)工具內(nèi)部都加入日志記錄入?yún)?、出參、耗時(shí)和異常。第四評測集要持續(xù)擴(kuò)充。把線上用戶的失敗案例逐步沉淀到測試集中形成“效果回歸防線”。沒有測試集的智能體項(xiàng)目后期迭代會(huì)越來越難。第五RAG 不是銀彈。先確認(rèn)業(yè)務(wù)問題適不適合用 RAG——知識庫內(nèi)容穩(wěn)定、答案需要依據(jù)、模型容易幻覺這些場景更適合 RAG。如果只是簡單問答也許提示詞就夠。第六安全和合規(guī)不能省。智能體涉及用戶隱私、內(nèi)部數(shù)據(jù)、第三方 API 調(diào)用時(shí)需要明確權(quán)限邊界。涉及人臉、聲音、版權(quán)素材等場景必須確認(rèn)授權(quán)與合規(guī)要求。第七關(guān)于“軟件工程能不能轉(zhuǎn)機(jī)器視覺”這類問題。從技能圖譜看軟件工程轉(zhuǎn)機(jī)器視覺不是不可能但需要補(bǔ)齊線性代數(shù)、圖像處理、深度學(xué)習(xí)模型訓(xùn)練等技能重合部分是 Python 工程能力、數(shù)據(jù)管道和部署經(jīng)驗(yàn)相比之下轉(zhuǎn)智能體開發(fā)的重合度更高因?yàn)橹悄荏w編程的底座還是軟件工程本身。選擇哪個(gè)方向取決于想補(bǔ)的是“模型訓(xùn)練”還是“模型應(yīng)用”的深度。12. 總結(jié)與下一步智能體編程時(shí)代的軟件工程基礎(chǔ)技能不是把老知識推倒重來而是在原有能力上增加“模型交互、知識增強(qiáng)、工具編排、評測監(jiān)控”這一層新技能。這張能力圖譜最有價(jià)值的點(diǎn)在于它把模糊的“會(huì)做智能體”拆成了可以逐項(xiàng)練習(xí)的工程技能。建議首先驗(yàn)證自己的第一層能力能否獨(dú)立調(diào)用模型 API能否寫清楚一個(gè)工具定義能否為一個(gè)簡單問答場景設(shè)計(jì)一份可回歸的測試集。這三個(gè)動(dòng)作能做到就已經(jīng)有一只腳邁進(jìn)智能體編程的大門了。最容易踩的坑有兩個(gè)一個(gè)是沉迷提示詞技巧忽略了上下文管理另一個(gè)是只做 Demo不做評測和日志。智能體能不能上生產(chǎn)看的不是演示效果多驚艷而是出問題時(shí)能不能定位、能不能回滾、能不能持續(xù)改進(jìn)。后續(xù)可以繼續(xù)擴(kuò)展的方向是把 RAG 從原型做到生產(chǎn)級把工具調(diào)用從單工具擴(kuò)展到多工具編排把評測從人工看結(jié)果升級為自動(dòng)化回歸流水線。把這套鏈路跑熟之后低代碼平臺(tái)的變化、模型版本的變化、新框架的出現(xiàn)都不會(huì)影響你交付智能體系統(tǒng)的能力。