戰(zhàn)：從模型封裝到文檔問(wèn)答+工具調(diào)用全流程)
從大模型 API 到真正能用的應(yīng)用中間缺的并不是模型調(diào)用代碼而是一層工程化封裝、一套可控的流程編排以及一個(gè)能理解“什么時(shí)候調(diào)用什么”的智能體框架。很多人學(xué) LangChain 容易陷入兩種極端一種是只看了官方文檔的 Prompt 和 ChatModel 示例覺(jué)得自己會(huì)了但一問(wèn)到怎么接 RAG、怎么做 Agent、怎么防止模型亂調(diào)用工具就答不上來(lái)另一種是直接去啃 Agent、記憶、路由、多工具編排這些高階概念結(jié)果被各種抽象類(lèi)搞暈兩三天就放棄了。這篇文章的價(jià)值在于用一條清晰的路線(xiàn)帶著你從零開(kāi)始跑通 LangChain把 Model 構(gòu)建、Prompt 工程、Chain 編排、Tool 注冊(cè)、Agent 開(kāi)發(fā)這套核心鏈路完整走一遍。最終落地一個(gè)“文檔問(wèn)答 工具調(diào)用”的智能 Agent 小項(xiàng)目。你會(huì)清楚地知道每一層解決了什么問(wèn)題以及實(shí)際工程里哪些坑是必須提前避開(kāi)的。1. 這篇文章真正要解決的問(wèn)題先做一個(gè)判斷LangChain 真正降低的并不是“調(diào)用模型”的成本。如果只是調(diào) OpenAI、文心、通義或者本地部署的 DeepSeek 接口一次 HTTP 請(qǐng)求就夠了根本不需要框架。LangChain 解決的是三個(gè)更深層的問(wèn)題第一模型切換成本。你今天用 GPT 類(lèi)模型明天想換國(guó)產(chǎn)模型或者私有化部署模型如果代碼散落各處你就要改很多調(diào)用邏輯。LangChain 用統(tǒng)一的 Model 接口屏蔽了不同廠(chǎng)商的 API 差異換模型只是改配置不動(dòng)業(yè)務(wù)代碼。第二應(yīng)用組裝效率。一個(gè)真實(shí)的大模型應(yīng)用不只是“問(wèn)一句、答一句”而是需要提示詞模板、歷史記憶、外部知識(shí)檢索、結(jié)果格式化、異常重試、多步工具調(diào)用。這些環(huán)節(jié)如果全部手寫(xiě)工作量非常大且容易出錯(cuò)。LangChain 提供了標(biāo)準(zhǔn)化組件組裝起來(lái)像搭積木。第三從“對(duì)話(huà)”走向“動(dòng)作”。這是智能 Agent 出現(xiàn)的根本原因——讓大模型不只是生成文本而是根據(jù)用戶(hù)意圖調(diào)用搜索、數(shù)據(jù)庫(kù)、API、內(nèi)部系統(tǒng)等工具自己去規(guī)劃步驟并執(zhí)行。沒(méi)有 Agent 的時(shí)候這些邏輯要靠開(kāi)發(fā)者在代碼里寫(xiě)死有了 Agent模型在一定規(guī)則約束下自己決策應(yīng)用的智能化水平上了一個(gè)臺(tái)階。所以這篇文章適合這些讀者有 Python 基礎(chǔ)想系統(tǒng)學(xué)習(xí) LangChain但被官方概念繞暈的開(kāi)發(fā)者做過(guò)模型 API 調(diào)用但不知道如何設(shè)計(jì) Prompt、如何實(shí)現(xiàn) RAG 和 Agent 的工程師正在為公司評(píng)估大模型應(yīng)用技術(shù)選型需要快速驗(yàn)證 LangChain 和 LangGraph 差別的技術(shù)負(fù)責(zé)人。讀完這篇文章你應(yīng)該能獨(dú)立完成一個(gè)面向?qū)嶋H業(yè)務(wù)場(chǎng)景的 LangChain 智能 Agent 項(xiàng)目骨架并且知道每一步的原理和常見(jiàn)坑在哪里。2. 核心概念Model、Prompt、Chain、Agent 之間的關(guān)系學(xué)習(xí) LangChain 最忌諱的就是一上來(lái)背概念。這里先用一個(gè)貼近業(yè)務(wù)的場(chǎng)景把核心概念串一遍。假設(shè)你要做一個(gè)“企業(yè)知識(shí)庫(kù)助手”員工可以問(wèn)“今年的報(bào)銷(xiāo)流程是什么”。一個(gè)最簡(jiǎn)單的流程是用戶(hù)提問(wèn) - 組裝提示詞 - 調(diào)用大模型 - 返回答案在 LangChain 里這個(gè)流程由三個(gè)核心概念承載Model對(duì)底層大模型的統(tǒng)一封裝。無(wú)論是 GPT、Claude 還是國(guó)內(nèi)大模型 API都通過(guò)它來(lái)調(diào)用。PromptTemplate提示詞模板。把用戶(hù)問(wèn)題動(dòng)態(tài)插入到固定的指令上下文中保證模型每次都按照你設(shè)計(jì)的格式和規(guī)則回答。Chain把“提示詞模板 模型”等組件串聯(lián)成一個(gè)可執(zhí)行的工作流。簡(jiǎn)單鏈很好懂復(fù)雜鏈則是“路由 多步執(zhí)行 條件判斷”的組合。再往上一層是 Agent。它比 Chain 多了一個(gè)關(guān)鍵能力模型可以決定“接下來(lái)調(diào)用哪個(gè)工具”。用生活例子解釋Chain 像一個(gè)固定流程的作業(yè)流水線(xiàn)每個(gè)工位做什么是設(shè)定好的Agent 則像一個(gè)有決策權(quán)的工頭收到任務(wù)后先判斷“這個(gè)活需要誰(shuí)來(lái)干”然后調(diào)用對(duì)應(yīng)工人的能力如果干完發(fā)現(xiàn)還需要另一道工序它會(huì)繼續(xù)安排。在代碼層面Agent 由三部分組成模型負(fù)責(zé)理解用戶(hù)意圖、規(guī)劃步驟、決定工具調(diào)用。工具Tool一個(gè)帶描述的函數(shù)告訴模型“你能用什么能力”。比如搜索工具、數(shù)據(jù)庫(kù)查詢(xún)工具、計(jì)算器工具。執(zhí)行器AgentExecutor負(fù)責(zé)讓模型和工具反復(fù)交互直到得到最終答案。LangChain 提供一個(gè)核心機(jī)制模型在對(duì)話(huà)中輸出一個(gè)特殊的工具調(diào)用結(jié)果AgentExecutor 捕獲后執(zhí)行對(duì)應(yīng)函數(shù)把結(jié)果回傳給模型模型再基于新信息繼續(xù)推理。這個(gè)循環(huán)會(huì)一直持續(xù)到模型覺(jué)得“我該回答用戶(hù)了”。理清這層關(guān)系后后面的代碼就好理解了。所有復(fù)雜的 LangChain 應(yīng)用本質(zhì)都是在這套“模型 工具 循環(huán)”上疊加記憶、檢索、人機(jī)審核等機(jī)制。3. 環(huán)境準(zhǔn)備與前置條件開(kāi)始寫(xiě)代碼之前先把環(huán)境準(zhǔn)備好。本文不綁定某一個(gè)具體的大模型廠(chǎng)商以“通過(guò) OpenAI 兼容接口接入大模型”的方式演示這樣無(wú)論你使用的是官方 API、國(guó)內(nèi)廠(chǎng)商的 OpenAI 兼容網(wǎng)關(guān)還是本地 Ollama 部署的模型都能復(fù)用同一套代碼。3.1 環(huán)境清單環(huán)境項(xiàng)說(shuō)明Python3.9 及以上版本推薦 3.10/3.11操作系統(tǒng)Windows / macOS / Linux 均可本文示例在 macOS 下運(yùn)行LangChain本文使用 LangChain 0.x 系列寫(xiě)法對(duì) 0.1/0.2/0.3 均兼容大模型 API需要一個(gè) API Key或者本地已啟動(dòng)的 Ollama 服務(wù)包管理工具pip 即可也可以使用 poetry/uv版本說(shuō)明LangChain 更新速度非常快不同小版本的 API 可能會(huì)有調(diào)整。文中的代碼在 0.2.x 和 0.3.x 上均驗(yàn)證過(guò)通用寫(xiě)法。如果遇到 API 不存在的問(wèn)題優(yōu)先查看官方遷移文檔不要盲目照抄舊版示例。3.2 安裝依賴(lài)建議先創(chuàng)建虛擬環(huán)境避免污染全局 Python 環(huán)境python -m venv .venv source .venv/bin/activate # Windows 下使用 .venv\Scripts\activate然后安裝核心依賴(lài)pip install langchain langchain-community langchain-openai langchain-core python-dotenv如果后面要跑 RAG 示例還需要安裝向量庫(kù)和文檔加載相關(guān)包pip install faiss-cpu pypdf chromadb安裝完成后在項(xiàng)目根目錄創(chuàng)建.env文件寫(xiě)入你的模型配置OPENAI_API_KEYyour-api-key-here OPENAI_API_BASEhttps://your-endpoint.example.com/v1 OPENAI_MODEL_NAMEgpt-4o-mini如果你使用的是本地 Ollama 部署的模型則配置如下OPENAI_API_KEYollama OPENAI_API_BASEhttp://localhost:11434/v1 OPENAI_MODEL_NAMEqwen2.5:7b這里的核心思路是LangChain 的ChatOpenAI類(lèi)支持任意 OpenAI 兼容接口。很多國(guó)產(chǎn)模型框架都會(huì)提供/v1的 OpenAI 兼容端點(diǎn)通過(guò)這種方式接入代碼完全不用改。4. 大模型 Model 構(gòu)建從 LLM 到 ChatModel 的演進(jìn)4.1 為什么現(xiàn)在推薦 ChatModel 而不是 LLM早期 LangChain 里大量使用OpenAI(text-davinci-003)這種文本補(bǔ)全模型現(xiàn)在已經(jīng)基本退出主流。原因有兩個(gè)第一當(dāng)前大模型基本都是對(duì)話(huà)式模型以“消息序列”作為輸入而不是單條字符串。對(duì)話(huà)模型對(duì)指令遵循能力更強(qiáng)也更適合多輪對(duì)話(huà)和工具調(diào)用。第二LangChain 在后續(xù)版本里將LLM抽象和ChatModel抽象做了明確分層。ChatModel輸入輸出的不再是字符串而是消息對(duì)象——SystemMessage、HumanMessage、AIMessage。這個(gè)設(shè)計(jì)讓模型能夠區(qū)分“系統(tǒng)指令”和“用戶(hù)輸入”為 Prompt 工程提供了結(jié)構(gòu)化基礎(chǔ)。4.2 最小可用模型封裝直接用配置初始化一個(gè) ChatModel# model_demo.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI load_dotenv() llm ChatOpenAI( modelos.getenv(OPENAI_MODEL_NAME, gpt-4o-mini), temperature0.3, timeout60, max_retries2, ) resp llm.invoke(用一句話(huà)解釋什么是大模型) print(resp)運(yùn)行方式python model_demo.py從代碼可以看到llm.invoke()返回的是一個(gè)AIMessage對(duì)象而不只是字符串。你如果只想要文本內(nèi)容可以取resp.content。這里有一個(gè)實(shí)用的建議不要把模型名寫(xiě)死在代碼里。模型名、API Base、Key 全部放到環(huán)境變量或配置中心管理。這樣從測(cè)試環(huán)境切到生產(chǎn)環(huán)境、從官方 API 切到私有化部署都不需要改代碼。4.3 多輪對(duì)話(huà)與消息結(jié)構(gòu)在實(shí)際項(xiàng)目中直接invoke(問(wèn)題)是不夠的。真實(shí)對(duì)話(huà)需要區(qū)分系統(tǒng)指令、歷史消息、當(dāng)前問(wèn)題。用消息列表顯式構(gòu)建from langchain_core.messages import SystemMessage, HumanMessage messages [ SystemMessage(content你是一個(gè)嚴(yán)謹(jǐn)?shù)腏ava工程師回答技術(shù)問(wèn)題時(shí)要給出代碼示例。), HumanMessage(content什么是Spring循環(huán)依賴(lài)), ] resp llm.invoke(messages) print(resp.content)為什么要強(qiáng)調(diào)這一點(diǎn)因?yàn)樵?Chain 和 Agent 中LangChain 內(nèi)部所有對(duì)話(huà)都是基于消息列表在傳遞。如果你理解了這個(gè)數(shù)據(jù)結(jié)構(gòu)后面看 Agent 生成的日志、調(diào)試多輪對(duì)話(huà)問(wèn)題時(shí)會(huì)輕松很多。5. Prompt 工程與 Chain 編排讓模型輸出穩(wěn)定模型接好了下一個(gè)問(wèn)題是怎么讓模型的輸出穩(wěn)定、可控、符合業(yè)務(wù)格式。直接問(wèn)模型“幫我寫(xiě)一篇文章”和“你是資深Java架構(gòu)師請(qǐng)用三段式結(jié)構(gòu)寫(xiě)一篇關(guān)于Spring Cloud的架構(gòu)分析文章要求包含核心組件對(duì)比表”效果完全不同。這個(gè)差異就是 Prompt 工程。5.1 PromptTemplate 動(dòng)態(tài)參數(shù)from langchain_core.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_messages([ (system, 你是一位{role}回答問(wèn)題時(shí)必須{rule}。), (user, {question}), ]) chain prompt | llm result chain.invoke({ role: 資深數(shù)據(jù)庫(kù)運(yùn)維工程師, rule: 先給結(jié)論再給操作步驟并說(shuō)明風(fēng)險(xiǎn), question: MySQL 查詢(xún)特別慢怎么排查, }) print(result.content)這里的|操作符是 LangChain 的一個(gè)重要特性使用管道符把組件串成鏈。prompt | llm的含義是“先把輸入按模板轉(zhuǎn)成消息再把消息交給模型”。這種方式可讀性很強(qiáng)一個(gè)完整的鏈路就是多個(gè)組件用管道連接。5.2 輸出解析器從文本到結(jié)構(gòu)化數(shù)據(jù)讓模型輸出 JSON 是常見(jiàn)需求但直接生成 JSON 經(jīng)常出現(xiàn)多余解釋、格式不完整等問(wèn)題。LangChain 提供了輸出解析器讓模型按照指定結(jié)構(gòu)輸出并自動(dòng)修復(fù)。from langchain_core.output_parsers import StrOutputParser, JsonOutputParser from pydantic import BaseModel, Field class BugReport(BaseModel): component: str Field(description出現(xiàn)問(wèn)題的系統(tǒng)模塊) level: str Field(description嚴(yán)重級(jí)別critical/major/minor) suggestion: str Field(description修復(fù)建議) parser JsonOutputParser(pydantic_objectBugReport) prompt ChatPromptTemplate.from_messages([ (system, 根據(jù)用戶(hù)描述提取Bug信息嚴(yán)格按JSON格式輸出不要輸出其他內(nèi)容。\n{format_instructions}), (user, {description}), ]) chain prompt | llm | parser result chain.invoke({ description: 用戶(hù)登錄時(shí)驗(yàn)證碼一直提示過(guò)期檢查發(fā)現(xiàn)是Redis緩存時(shí)間設(shè)置錯(cuò)誤, format_instructions: parser.get_format_instructions(), }) print(result)運(yùn)行輸出是一個(gè)字典結(jié)構(gòu){ component: 用戶(hù)登錄, level: major, suggestion: 檢查Redis中驗(yàn)證碼緩存的過(guò)期時(shí)間確認(rèn)時(shí)間單位是否正確 }這里的實(shí)用價(jià)值在于結(jié)構(gòu)化輸出是 Agent 的基石。當(dāng)模型要調(diào)用工具時(shí)它輸出的必須是嚴(yán)格結(jié)構(gòu)化的工具調(diào)用參數(shù)而不是一句話(huà)描述“我想調(diào)用查詢(xún)函數(shù)”。理解了JsonOutputParser的用法你就能理解 Agent 內(nèi)部是怎么約束模型輸出的。6. Tool 與 Agent 核心機(jī)制從生成文本到執(zhí)行動(dòng)作現(xiàn)在進(jìn)入本文的核心章節(jié)智能 Agent 開(kāi)發(fā)。6.1 工具的本質(zhì)在 Agent 框架里一個(gè)“工具”就是一個(gè)函數(shù)加一段描述。模型看到“可以用什么工具”但不會(huì)看到函數(shù)的實(shí)現(xiàn)細(xì)節(jié)。關(guān)鍵在于描述要清楚因?yàn)槟Ｐ驼强棵枋鰜?lái)判斷“這個(gè)任務(wù)該用哪個(gè)工具”。# agent_demo.py from langchain_core.tools import tool tool def get_user_balance(user_id: str) - str: 查詢(xún)用戶(hù)賬戶(hù)余額。入?yún)ser_id為用戶(hù)的唯一標(biāo)識(shí)。 Args: user_id: 用戶(hù)ID字符串例如U12345 # 實(shí)際項(xiàng)目中這里會(huì)查數(shù)據(jù)庫(kù)或調(diào)用內(nèi)部服務(wù) data { U12345: 1000.50, U99999: 0, } balance data.get(user_id, -1) return f用戶(hù){user_id}的賬戶(hù)余額是{balance}元 tool def send_warning_message(user_id: str) - str: 當(dāng)用戶(hù)余額異?；虻陀陂撝禃r(shí)向用戶(hù)發(fā)送風(fēng)險(xiǎn)預(yù)警消息。 return f已向用戶(hù){user_id}發(fā)送余額預(yù)警這里容易踩坑的地方是工具描述不寫(xiě)清楚模型就不知道該不該調(diào)用、怎么調(diào)用。get_user_balance的 docstring 里既說(shuō)明了“做什么”又說(shuō)明了“參數(shù)是什么”還給了示例值這就是典型的“機(jī)器可讀”描述寫(xiě)法。6.2 創(chuàng)建第一個(gè)工具調(diào)用 Agentfrom langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate from langchain_openai import ChatOpenAI llm ChatOpenAI( modelos.getenv(OPENAI_MODEL_NAME), temperature0, ) tools [get_user_balance, send_warning_message] prompt ChatPromptTemplate.from_messages([ (system, 你是一個(gè)銀行客服助手。查詢(xún)余額前先確認(rèn)用戶(hù)ID有效如果余額為0或異常請(qǐng)調(diào)用預(yù)警工具。), (placeholder, {chat_history}), (human, {input}), (placeholder, {agent_scratchpad}), ]) agent create_tool_calling_agent(llm, tools, prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue) result agent_executor.invoke({ input: 幫我查一下用戶(hù)U12345的余額 }) print(result[output])create_tool_calling_agent的作用是讓模型在需要時(shí)輸出tool_calls指令A(yù)gentExecutor 自動(dòng)執(zhí)行對(duì)應(yīng)工具并把返回結(jié)果再次喂給模型。agent_scratchpad是 LangChain 用來(lái)存放“模型已執(zhí)行過(guò)的推理過(guò)程與工具返回結(jié)果”的占位區(qū)域這是 Agent 循環(huán)可以持續(xù)推理的關(guān)鍵。6.3 Agent 與 Chain 的選擇判斷很多初學(xué)者問(wèn)我什么時(shí)候用 Chain什么時(shí)候用 Agent簡(jiǎn)單判斷標(biāo)準(zhǔn)如果執(zhí)行流程是確定的用 Chain如果執(zhí)行流程要看用戶(hù)輸入和中間結(jié)果而變化用 Agent。比如報(bào)銷(xiāo)審批流程步驟固定提交 - 校驗(yàn)金額 - 領(lǐng)導(dǎo)審批 - 財(cái)務(wù)打款。這種用 Chain 更像狀態(tài)機(jī)安全可控。而“幫我分析這份文檔然后生成摘要再比較其中的數(shù)據(jù)最后生成周報(bào)”這種不固定順序的任務(wù)一個(gè) Agent 要靈活得多。但要警惕Agent 的自由度也意味著不確定性。在生產(chǎn)環(huán)境使用 Agent一定要加白名單、工具權(quán)限控制、調(diào)用審計(jì)并在關(guān)鍵節(jié)點(diǎn)引入人工確認(rèn)。這一點(diǎn)在后面最佳實(shí)踐里還會(huì)細(xì)說(shuō)。7. 項(xiàng)目實(shí)戰(zhàn)構(gòu)建一個(gè)“文檔問(wèn)答 工具調(diào)用”的智能 Agent前面的例子都偏演示這一節(jié)把能力整合起來(lái)做一個(gè)真實(shí)感的項(xiàng)目企業(yè)內(nèi)部知識(shí)庫(kù)問(wèn)答 Agent。這個(gè)項(xiàng)目需要兩個(gè)核心能力從 PDF/文本中加載知識(shí)切分后存入向量庫(kù)實(shí)現(xiàn) RAG 檢索增強(qiáng)問(wèn)答在回答業(yè)務(wù)問(wèn)題時(shí)如果需要訪(fǎng)問(wèn)實(shí)時(shí)數(shù)據(jù)比如查詢(xún)工單狀態(tài)模型會(huì)自動(dòng)調(diào)用工具。7.1 項(xiàng)目結(jié)構(gòu)knowledge_agent/ ├── .env ├── requirements.txt ├── knowledge/ # 存放知識(shí)文檔 │ └── handbook.pdf ├── vector_store/ # 向量庫(kù)索引保存目錄 ├── ingest.py # 文檔導(dǎo)入腳本 ├── agent.py # Agent 主程序 └── tools.py # 自定義工具7.2 文檔導(dǎo)入與向量化# ingest.py from langchain_community.document_loaders import PyPDFLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings from langchain_community.vectorstores import FAISS loader PyPDFLoader(knowledge/handbook.pdf) documents loader.load() text_splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap100, separators[\n\n, \n, 。, , , ], ) docs text_splitter.split_documents(documents) embeddings OpenAIEmbeddings() vector_store FAISS.from_documents(docs, embeddings) vector_store.save_local(vector_store/handbook_index) print(f文檔已切分為 {len(docs)} 個(gè)片段并寫(xiě)入向量庫(kù))切分參數(shù)是 RAG 效果的關(guān)鍵。chunk_size太大模型一次接收的上下文過(guò)多檢索相關(guān)性下降chunk_size太小單個(gè)片段信息不完整。chunk_overlap用于保留上下文銜接避免一句話(huà)被攔腰切斷。7.3 自定義查詢(xún)工具實(shí)際業(yè)務(wù)里知識(shí)庫(kù)文檔里的信息可能是靜態(tài)的比如制度、手冊(cè)但工單狀態(tài)、庫(kù)存數(shù)量是動(dòng)態(tài)的需要通過(guò)工具查詢(xún)。# tools.py from langchain_core.tools import tool tool def query_order_status(order_id: str) - str: 根據(jù)訂單號(hào)查詢(xún)訂單當(dāng)前處理狀態(tài)。用于回答物流、訂單進(jìn)度類(lèi)問(wèn)題。 fake_db { SO20241001: 已發(fā)貨預(yù)計(jì)3天內(nèi)送達(dá), SO20241002: 正在倉(cāng)庫(kù)揀貨, } return fake_db.get(order_id, 未查詢(xún)到該訂單請(qǐng)確認(rèn)訂單號(hào)是否正確)7.4 Agent 主程序RAG 檢索器作為工具LangChain Agent 不僅可以把普通函數(shù)當(dāng)工具還可以把檢索器包裝成工具。這讓 Agent 具備“先檢索再回答”的能力。# agent.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI, OpenAIEmbeddings from langchain_community.vectorstores import FAISS from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate from langchain.tools.retriever import create_retriever_tool from tools import query_order_status load_dotenv() # 1. 構(gòu)建檢索器 embeddings OpenAIEmbeddings() vector_store FAISS.load_local( vector_store/handbook_index, embeddings, allow_dangerous_deserializationTrue, # 僅用于本地可信索引 ) retriever vector_store.as_retriever(search_kwargs{k: 3}) retriever_tool create_retriever_tool( retriever, nameknowledge_base_search, description搜索企業(yè)知識(shí)庫(kù)查找流程規(guī)范、制度政策、產(chǎn)品使用說(shuō)明等信息。當(dāng)用戶(hù)問(wèn)題涉及公司制度或產(chǎn)品操作時(shí)必須先調(diào)用該工具。, ) # 2. 模型和工具 llm ChatOpenAI( modelos.getenv(OPENAI_MODEL_NAME), temperature0.2, ) tools [retriever_tool, query_order_status] # 3. 提示詞 prompt ChatPromptTemplate.from_messages([ (system, ( 你是企業(yè)內(nèi)部智能助理?；卮鹨骪n 1. 涉及制度、規(guī)范類(lèi)問(wèn)題必須調(diào)用知識(shí)庫(kù)工具基于檢索結(jié)果回答。\n 2. 涉及訂單、物流問(wèn)題必須調(diào)用訂單查詢(xún)工具。\n 3. 如果工具沒(méi)有返回有效信息明確告知用戶(hù)需要補(bǔ)充信息不要編造答案。 )), (placeholder, {chat_history}), (human, {input}), (placeholder, {agent_scratchpad}), ]) # 4. 創(chuàng)建并執(zhí)行 Agent agent create_tool_calling_agent(llm, tools, prompt) agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, max_iterations5, early_stopping_methodforce, ) if __name__ __main__: while True: user_input input(\n請(qǐng)輸入你的問(wèn)題輸入exit退出) if user_input.lower() exit: break response agent_executor.invoke({input: user_input}) print(\n回答:, response[output])這里有幾個(gè)工程細(xì)節(jié)要重點(diǎn)說(shuō)明allow_dangerous_deserializationTrue只有在加載本地可信索引時(shí)才允許絕不要用在不可信的共享索引文件上。這是安全邊界問(wèn)題。search_kwargs{k: 3}控制檢索返回的片段數(shù)量。片段數(shù)越多模型參考信息越多但也更容易被無(wú)關(guān)信息干擾。max_iterations5限制 Agent 的最大推理輪數(shù)防止模型在工具調(diào)用中陷入死循環(huán)。檢索器描述中明確寫(xiě)了“當(dāng)用戶(hù)問(wèn)題涉及公司制度或產(chǎn)品操作時(shí)必須先調(diào)用該工具”。這種“觸發(fā)條件”描述是讓 Agent 正確決策的關(guān)鍵提示詞。8. 運(yùn)行結(jié)果與效果驗(yàn)證運(yùn)行 Agent 主程序python agent.py測(cè)試一制度類(lèi)問(wèn)題請(qǐng)輸入你的問(wèn)題輸入exit退出公司的年假制度是怎樣的期望的 Agent 行為模型先判斷該問(wèn)題屬于“知識(shí)庫(kù)”范疇調(diào)用knowledge_base_search工具檢索向量庫(kù)把相關(guān)文本片段帶回然后基于片段組織回答并能在回答中給出參考來(lái)源。如果verboseTrue控制臺(tái)會(huì)顯示模型選擇工具、工具返回結(jié)果的過(guò)程。這是調(diào)試 Agent 最重要的手段。測(cè)試二動(dòng)態(tài)數(shù)據(jù)問(wèn)題請(qǐng)輸入你的問(wèn)題輸入exit退出SO20241001這個(gè)訂單現(xiàn)在什么狀態(tài)期望行為模型調(diào)用query_order_status工具不再走知識(shí)庫(kù)檢索。測(cè)試三跨工具復(fù)合問(wèn)題請(qǐng)輸入你的問(wèn)題輸入exit退出用戶(hù)想了解請(qǐng)假流程同時(shí)查詢(xún)一下他的訂單SO20241002到哪里了。期望行為模型判斷這是兩個(gè)獨(dú)立任務(wù)會(huì)依次調(diào)用知識(shí)庫(kù)工具和訂單查詢(xún)工具最后把兩部分答案匯總。如果 Agent 只回答了其中一部分說(shuō)明提示詞里的工具描述還不夠清晰或者模型版本工具調(diào)用能力偏弱。8.1 如何判斷 Agent 運(yùn)行是否正常判斷成功不只看最終回答還要看推理路徑是否符合預(yù)期檢查點(diǎn)正常表現(xiàn)異常表現(xiàn)工具選擇問(wèn)題類(lèi)型與工具描述匹配制度問(wèn)題調(diào)了訂單工具參數(shù)提取訂單號(hào)準(zhǔn)確傳給了工具模型自己設(shè)計(jì)了不存在的參數(shù)工具返回返回結(jié)果出現(xiàn)在日志中工具拋出異常但 Agent 未捕獲最終回答引用了檢索結(jié)果內(nèi)容答案看起來(lái)像模型憑空編造如果回答內(nèi)容明顯不是來(lái)自檢索文檔優(yōu)先檢查是否已經(jīng)執(zhí)行了ingest.py以及檢索返回的k是否過(guò)小。9. 常見(jiàn)問(wèn)題與排查思路問(wèn)題現(xiàn)象可能原因排查方式解決方案模型報(bào)AuthenticationErrorAPI Key 錯(cuò)誤或沒(méi)有寫(xiě)入 .env檢查 .env 文件和load_dotenv()是否執(zhí)行確認(rèn) Key 格式確認(rèn)環(huán)境變量名正確模型報(bào)NotFoundError模型名不支持或 API Base 地址錯(cuò)誤查看完整報(bào)錯(cuò)中的 model 和 base_url換成模型服務(wù)商支持的模型名檢查是否缺少/v1FAISS 加載時(shí)報(bào)allow_dangerous_deserialization錯(cuò)誤新版 LangChain 安全策略要求顯式聲明閱讀報(bào)錯(cuò)提示確認(rèn)索引來(lái)自可信來(lái)源后設(shè)置參數(shù)為 TrueAgent 一直重復(fù)調(diào)用同一個(gè)工具工具返回結(jié)果沒(méi)有滿(mǎn)足模型預(yù)期或 description 不清晰打開(kāi) verbose 日志觀察工具返回內(nèi)容和模型下一步判斷優(yōu)化工具描述增加結(jié)果校驗(yàn)設(shè)置max_iterations檢索結(jié)果不相關(guān)切分粒度太大或 embedding 模型不匹配檢查 chunk_size、檢索 k 值打印檢索片段調(diào)整切分參數(shù)更換更強(qiáng)的 embedding 模型API 請(qǐng)求超時(shí)網(wǎng)絡(luò)不穩(wěn)定或模型響應(yīng)過(guò)慢查看日志中的超時(shí)時(shí)間調(diào)大timeout參數(shù)增加max_retriesLangChain 版本升級(jí)導(dǎo)致的 API 變動(dòng)是使用過(guò)程中最常見(jiàn)的坑。遇到.invoke()、create_tool_calling_agent等方法報(bào)不存在時(shí)先去查看當(dāng)前安裝版本的官方文檔再檢查遷移說(shuō)明。很多項(xiàng)目就是安裝最新版 LangChain 后跑著跑著舊版教程代碼直接崩了。方法是安裝時(shí)固定大版本pip install langchain0.2,0.410. 最佳實(shí)踐與工程建議10.1 配置管理一切皆配置模型名、API Key、數(shù)據(jù)庫(kù)連接、向量庫(kù)路徑都不要寫(xiě)死在代碼里。建議使用.env文件加配置中心結(jié)合的方式。團(tuán)隊(duì)協(xié)作時(shí).env 不進(jìn)倉(cāng)庫(kù)用.env.example提交占位。10.2 提示詞與工具描述是一等公民把 Prompt 和工具描述當(dāng)作代碼一樣管理建議單獨(dú)存放prompts/ ├── agent_system.txt └── tool_descriptions.yaml后續(xù)調(diào)優(yōu)時(shí)你會(huì)發(fā)現(xiàn)大多數(shù) Agent 問(wèn)題不是模型的錯(cuò)而是工具描述寫(xiě)得不清楚。10.3 安全邊界Agent 權(quán)限控制Agent 很強(qiáng)大但它也會(huì)執(zhí)行你給它的工具。在生產(chǎn)環(huán)境必須做到工具只暴露最小權(quán)限比如只讀接口不允許任意寫(xiě)庫(kù)對(duì) Agent 的調(diào)用做日志審計(jì)記錄每一次工具調(diào)用的參數(shù)和結(jié)果涉及資金、刪除、修改類(lèi)操作加入人工確認(rèn)環(huán)節(jié)不要讓模型直接執(zhí)行。10.4 日志與可觀測(cè)性verboseTrue只適合開(kāi)發(fā)調(diào)試。生產(chǎn)環(huán)境建議接入 LangSmith 或自建日志系統(tǒng)記錄用戶(hù)輸入和最終輸出模型每一次工具調(diào)用的請(qǐng)求參數(shù)每次調(diào)用的耗時(shí)和 token 消耗。這樣你才能知道 Agent 跑一次業(yè)務(wù)到底花了多少錢(qián)、哪個(gè)環(huán)節(jié)最慢、哪個(gè)工具被反復(fù)調(diào)用。10.5 從 LangChain 到 LangGraph如果你用 LangChain Agent 開(kāi)發(fā)到一定復(fù)雜度會(huì)遇到兩個(gè)明顯痛點(diǎn)第一狀態(tài)控制弱。AgentExecutor 的循環(huán)是框架內(nèi)置的你想在中間插入“人工審核節(jié)點(diǎn)”或者“條件分支”比較麻煩。第二保存和恢復(fù)難。線(xiàn)上 Agent 執(zhí)行到一半進(jìn)程崩潰了現(xiàn)場(chǎng)很難恢復(fù)。這時(shí)候需要關(guān)注 LangGraph。它把 Agent 的每一步定義成圖中的節(jié)點(diǎn)節(jié)點(diǎn)之間用邊連接你可以精確控制模型判斷 - 工具A - 人工確認(rèn) - 工具B - 回答還可以支持條件邊模型調(diào)用工具后根據(jù)返回結(jié)果決定走哪個(gè)分支。LangGraph 提供了更底層的編排能力適合生產(chǎn)級(jí) Agent。本文篇幅有限不展開(kāi) LangGraph 的語(yǔ)法但這是一個(gè)非常值得繼續(xù)深入的方向。對(duì)于剛?cè)腴T(mén)的人來(lái)說(shuō)現(xiàn)有 LangChain Agent 足夠跑通業(yè)務(wù)驗(yàn)證當(dāng)流程復(fù)雜度上來(lái)后再遷移到 LangGraph 也不遲。11. 總結(jié)與后續(xù)學(xué)習(xí)方向這篇文章打通了 LangChain 的完整學(xué)習(xí)路徑從 Model 的統(tǒng)一封裝到 Prompt 模板和輸出解析再到 Chain 的管道編排最后通過(guò) Tool 機(jī)制實(shí)現(xiàn)智能 Agent并落地了一個(gè)“文檔問(wèn)答 實(shí)時(shí)工具調(diào)用”的實(shí)戰(zhàn)項(xiàng)目。復(fù)盤(pán)一下你學(xué)到了四個(gè)關(guān)鍵判斷LangChain 的核心價(jià)值不是“調(diào)模型”而是“統(tǒng)一模型接口 標(biāo)準(zhǔn)化應(yīng)用組裝 支持動(dòng)作執(zhí)行”。Chain 適合固定流程Agent 適合動(dòng)態(tài)規(guī)劃。選擇之前先想清楚流程是否確定。工具描述是 Agent 效果的上限。模型能不能正確選工具取決于你怎么寫(xiě) description。生產(chǎn)環(huán)境用 Agent 必須加權(quán)限控制、日志審計(jì)和人工確認(rèn)節(jié)點(diǎn)不能裸奔。如果你按照文章示例跑通了項(xiàng)目下一步建議按這個(gè)順序深入把 RAG 的檢索效果調(diào)優(yōu)學(xué)習(xí)分塊策略、rerank 和混合檢索研究 LangGraph 的狀態(tài)圖模型把 Agent 工作流從“黑盒循環(huán)”改造成“可視化、可控狀態(tài)機(jī)”關(guān)注 Streamlit 或 FastAPI把命令行 Agent 封裝成 Web 應(yīng)用探索大模型微調(diào)Fine-tuning當(dāng) Prompt 無(wú)論如何調(diào)優(yōu)都無(wú)法滿(mǎn)足場(chǎng)景時(shí)微調(diào)是一個(gè)更底層的優(yōu)化方向。建議收藏本文作為你后續(xù) LangChain 使用的速查手冊(cè)。遇到 API 版本問(wèn)題或 Agent 行為異常時(shí)回到這份代碼和排查表比重新翻一遍文檔要快得多。 LangChain智能Agent實(shí)戰(zhàn)：從模型封裝到文檔問(wèn)答+工具調(diào)用全流程
從大模型 API 到真正能用的應(yīng)用中間缺的并不是模型調(diào)用代碼而是一層工程化封裝、一套可控的流程編排以及一個(gè)能理解“什么時(shí)候調(diào)用什么”的智能體框架。很多人學(xué) LangChain 容易陷入兩種極端一種是只看了官方文檔的 Prompt 和 ChatModel 示例覺(jué)得自己會(huì)了但一問(wèn)到怎么接 RAG、怎么做 Agent、怎么防止模型亂調(diào)用工具就答不上來(lái)另一種是直接去啃 Agent、記憶、路由、多工具編排這些高階概念結(jié)果被各種抽象類(lèi)搞暈兩三天就放棄了。這篇文章的價(jià)值在于用一條清晰的路線(xiàn)帶著你從零開(kāi)始跑通 LangChain把 Model 構(gòu)建、Prompt 工程、Chain 編排、Tool 注冊(cè)、Agent 開(kāi)發(fā)這套核心鏈路完整走一遍。最終落地一個(gè)“文檔問(wèn)答 工具調(diào)用”的智能 Agent 小項(xiàng)目。你會(huì)清楚地知道每一層解決了什么問(wèn)題以及實(shí)際工程里哪些坑是必須提前避開(kāi)的。1. 這篇文章真正要解決的問(wèn)題先做一個(gè)判斷LangChain 真正降低的并不是“調(diào)用模型”的成本。如果只是調(diào) OpenAI、文心、通義或者本地部署的 DeepSeek 接口一次 HTTP 請(qǐng)求就夠了根本不需要框架。LangChain 解決的是三個(gè)更深層的問(wèn)題第一模型切換成本。你今天用 GPT 類(lèi)模型明天想換國(guó)產(chǎn)模型或者私有化部署模型如果代碼散落各處你就要改很多調(diào)用邏輯。LangChain 用統(tǒng)一的 Model 接口屏蔽了不同廠(chǎng)商的 API 差異換模型只是改配置不動(dòng)業(yè)務(wù)代碼。第二應(yīng)用組裝效率。一個(gè)真實(shí)的大模型應(yīng)用不只是“問(wèn)一句、答一句”而是需要提示詞模板、歷史記憶、外部知識(shí)檢索、結(jié)果格式化、異常重試、多步工具調(diào)用。這些環(huán)節(jié)如果全部手寫(xiě)工作量非常大且容易出錯(cuò)。LangChain 提供了標(biāo)準(zhǔn)化組件組裝起來(lái)像搭積木。第三從“對(duì)話(huà)”走向“動(dòng)作”。這是智能 Agent 出現(xiàn)的根本原因——讓大模型不只是生成文本而是根據(jù)用戶(hù)意圖調(diào)用搜索、數(shù)據(jù)庫(kù)、API、內(nèi)部系統(tǒng)等工具自己去規(guī)劃步驟并執(zhí)行。沒(méi)有 Agent 的時(shí)候這些邏輯要靠開(kāi)發(fā)者在代碼里寫(xiě)死有了 Agent模型在一定規(guī)則約束下自己決策應(yīng)用的智能化水平上了一個(gè)臺(tái)階。所以這篇文章適合這些讀者有 Python 基礎(chǔ)想系統(tǒng)學(xué)習(xí) LangChain但被官方概念繞暈的開(kāi)發(fā)者做過(guò)模型 API 調(diào)用但不知道如何設(shè)計(jì) Prompt、如何實(shí)現(xiàn) RAG 和 Agent 的工程師正在為公司評(píng)估大模型應(yīng)用技術(shù)選型需要快速驗(yàn)證 LangChain 和 LangGraph 差別的技術(shù)負(fù)責(zé)人。讀完這篇文章你應(yīng)該能獨(dú)立完成一個(gè)面向?qū)嶋H業(yè)務(wù)場(chǎng)景的 LangChain 智能 Agent 項(xiàng)目骨架并且知道每一步的原理和常見(jiàn)坑在哪里。2. 核心概念Model、Prompt、Chain、Agent 之間的關(guān)系學(xué)習(xí) LangChain 最忌諱的就是一上來(lái)背概念。這里先用一個(gè)貼近業(yè)務(wù)的場(chǎng)景把核心概念串一遍。假設(shè)你要做一個(gè)“企業(yè)知識(shí)庫(kù)助手”員工可以問(wèn)“今年的報(bào)銷(xiāo)流程是什么”。一個(gè)最簡(jiǎn)單的流程是用戶(hù)提問(wèn) - 組裝提示詞 - 調(diào)用大模型 - 返回答案在 LangChain 里這個(gè)流程由三個(gè)核心概念承載Model對(duì)底層大模型的統(tǒng)一封裝。無(wú)論是 GPT、Claude 還是國(guó)內(nèi)大模型 API都通過(guò)它來(lái)調(diào)用。PromptTemplate提示詞模板。把用戶(hù)問(wèn)題動(dòng)態(tài)插入到固定的指令上下文中保證模型每次都按照你設(shè)計(jì)的格式和規(guī)則回答。Chain把“提示詞模板 模型”等組件串聯(lián)成一個(gè)可執(zhí)行的工作流。簡(jiǎn)單鏈很好懂復(fù)雜鏈則是“路由 多步執(zhí)行 條件判斷”的組合。再往上一層是 Agent。它比 Chain 多了一個(gè)關(guān)鍵能力模型可以決定“接下來(lái)調(diào)用哪個(gè)工具”。用生活例子解釋Chain 像一個(gè)固定流程的作業(yè)流水線(xiàn)每個(gè)工位做什么是設(shè)定好的Agent 則像一個(gè)有決策權(quán)的工頭收到任務(wù)后先判斷“這個(gè)活需要誰(shuí)來(lái)干”然后調(diào)用對(duì)應(yīng)工人的能力如果干完發(fā)現(xiàn)還需要另一道工序它會(huì)繼續(xù)安排。在代碼層面Agent 由三部分組成模型負(fù)責(zé)理解用戶(hù)意圖、規(guī)劃步驟、決定工具調(diào)用。工具Tool一個(gè)帶描述的函數(shù)告訴模型“你能用什么能力”。比如搜索工具、數(shù)據(jù)庫(kù)查詢(xún)工具、計(jì)算器工具。執(zhí)行器AgentExecutor負(fù)責(zé)讓模型和工具反復(fù)交互直到得到最終答案。LangChain 提供一個(gè)核心機(jī)制模型在對(duì)話(huà)中輸出一個(gè)特殊的工具調(diào)用結(jié)果AgentExecutor 捕獲后執(zhí)行對(duì)應(yīng)函數(shù)把結(jié)果回傳給模型模型再基于新信息繼續(xù)推理。這個(gè)循環(huán)會(huì)一直持續(xù)到模型覺(jué)得“我該回答用戶(hù)了”。理清這層關(guān)系后后面的代碼就好理解了。所有復(fù)雜的 LangChain 應(yīng)用本質(zhì)都是在這套“模型 工具 循環(huán)”上疊加記憶、檢索、人機(jī)審核等機(jī)制。3. 環(huán)境準(zhǔn)備與前置條件開(kāi)始寫(xiě)代碼之前先把環(huán)境準(zhǔn)備好。本文不綁定某一個(gè)具體的大模型廠(chǎng)商以“通過(guò) OpenAI 兼容接口接入大模型”的方式演示這樣無(wú)論你使用的是官方 API、國(guó)內(nèi)廠(chǎng)商的 OpenAI 兼容網(wǎng)關(guān)還是本地 Ollama 部署的模型都能復(fù)用同一套代碼。3.1 環(huán)境清單環(huán)境項(xiàng)說(shuō)明Python3.9 及以上版本推薦 3.10/3.11操作系統(tǒng)Windows / macOS / Linux 均可本文示例在 macOS 下運(yùn)行LangChain本文使用 LangChain 0.x 系列寫(xiě)法對(duì) 0.1/0.2/0.3 均兼容大模型 API需要一個(gè) API Key或者本地已啟動(dòng)的 Ollama 服務(wù)包管理工具pip 即可也可以使用 poetry/uv版本說(shuō)明LangChain 更新速度非常快不同小版本的 API 可能會(huì)有調(diào)整。文中的代碼在 0.2.x 和 0.3.x 上均驗(yàn)證過(guò)通用寫(xiě)法。如果遇到 API 不存在的問(wèn)題優(yōu)先查看官方遷移文檔不要盲目照抄舊版示例。3.2 安裝依賴(lài)建議先創(chuàng)建虛擬環(huán)境避免污染全局 Python 環(huán)境python -m venv .venv source .venv/bin/activate # Windows 下使用 .venv\Scripts\activate然后安裝核心依賴(lài)pip install langchain langchain-community langchain-openai langchain-core python-dotenv如果后面要跑 RAG 示例還需要安裝向量庫(kù)和文檔加載相關(guān)包pip install faiss-cpu pypdf chromadb安裝完成后在項(xiàng)目根目錄創(chuàng)建.env文件寫(xiě)入你的模型配置OPENAI_API_KEYyour-api-key-here OPENAI_API_BASEhttps://your-endpoint.example.com/v1 OPENAI_MODEL_NAMEgpt-4o-mini如果你使用的是本地 Ollama 部署的模型則配置如下OPENAI_API_KEYollama OPENAI_API_BASEhttp://localhost:11434/v1 OPENAI_MODEL_NAMEqwen2.5:7b這里的核心思路是LangChain 的ChatOpenAI類(lèi)支持任意 OpenAI 兼容接口。很多國(guó)產(chǎn)模型框架都會(huì)提供/v1的 OpenAI 兼容端點(diǎn)通過(guò)這種方式接入代碼完全不用改。4. 大模型 Model 構(gòu)建從 LLM 到 ChatModel 的演進(jìn)4.1 為什么現(xiàn)在推薦 ChatModel 而不是 LLM早期 LangChain 里大量使用OpenAI(text-davinci-003)這種文本補(bǔ)全模型現(xiàn)在已經(jīng)基本退出主流。原因有兩個(gè)第一當(dāng)前大模型基本都是對(duì)話(huà)式模型以“消息序列”作為輸入而不是單條字符串。對(duì)話(huà)模型對(duì)指令遵循能力更強(qiáng)也更適合多輪對(duì)話(huà)和工具調(diào)用。第二LangChain 在后續(xù)版本里將LLM抽象和ChatModel抽象做了明確分層。ChatModel輸入輸出的不再是字符串而是消息對(duì)象——SystemMessage、HumanMessage、AIMessage。這個(gè)設(shè)計(jì)讓模型能夠區(qū)分“系統(tǒng)指令”和“用戶(hù)輸入”為 Prompt 工程提供了結(jié)構(gòu)化基礎(chǔ)。4.2 最小可用模型封裝直接用配置初始化一個(gè) ChatModel# model_demo.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI load_dotenv() llm ChatOpenAI( modelos.getenv(OPENAI_MODEL_NAME, gpt-4o-mini), temperature0.3, timeout60, max_retries2, ) resp llm.invoke(用一句話(huà)解釋什么是大模型) print(resp)運(yùn)行方式python model_demo.py從代碼可以看到llm.invoke()返回的是一個(gè)AIMessage對(duì)象而不只是字符串。你如果只想要文本內(nèi)容可以取resp.content。這里有一個(gè)實(shí)用的建議不要把模型名寫(xiě)死在代碼里。模型名、API Base、Key 全部放到環(huán)境變量或配置中心管理。這樣從測(cè)試環(huán)境切到生產(chǎn)環(huán)境、從官方 API 切到私有化部署都不需要改代碼。4.3 多輪對(duì)話(huà)與消息結(jié)構(gòu)在實(shí)際項(xiàng)目中直接invoke(問(wèn)題)是不夠的。真實(shí)對(duì)話(huà)需要區(qū)分系統(tǒng)指令、歷史消息、當(dāng)前問(wèn)題。用消息列表顯式構(gòu)建from langchain_core.messages import SystemMessage, HumanMessage messages [ SystemMessage(content你是一個(gè)嚴(yán)謹(jǐn)?shù)腏ava工程師回答技術(shù)問(wèn)題時(shí)要給出代碼示例。), HumanMessage(content什么是Spring循環(huán)依賴(lài)), ] resp llm.invoke(messages) print(resp.content)為什么要強(qiáng)調(diào)這一點(diǎn)因?yàn)樵?Chain 和 Agent 中LangChain 內(nèi)部所有對(duì)話(huà)都是基于消息列表在傳遞。如果你理解了這個(gè)數(shù)據(jù)結(jié)構(gòu)后面看 Agent 生成的日志、調(diào)試多輪對(duì)話(huà)問(wèn)題時(shí)會(huì)輕松很多。5. Prompt 工程與 Chain 編排讓模型輸出穩(wěn)定模型接好了下一個(gè)問(wèn)題是怎么讓模型的輸出穩(wěn)定、可控、符合業(yè)務(wù)格式。直接問(wèn)模型“幫我寫(xiě)一篇文章”和“你是資深Java架構(gòu)師請(qǐng)用三段式結(jié)構(gòu)寫(xiě)一篇關(guān)于Spring Cloud的架構(gòu)分析文章要求包含核心組件對(duì)比表”效果完全不同。這個(gè)差異就是 Prompt 工程。5.1 PromptTemplate 動(dòng)態(tài)參數(shù)from langchain_core.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_messages([ (system, 你是一位{role}回答問(wèn)題時(shí)必須{rule}。), (user, {question}), ]) chain prompt | llm result chain.invoke({ role: 資深數(shù)據(jù)庫(kù)運(yùn)維工程師, rule: 先給結(jié)論再給操作步驟并說(shuō)明風(fēng)險(xiǎn), question: MySQL 查詢(xún)特別慢怎么排查, }) print(result.content)這里的|操作符是 LangChain 的一個(gè)重要特性使用管道符把組件串成鏈。prompt | llm的含義是“先把輸入按模板轉(zhuǎn)成消息再把消息交給模型”。這種方式可讀性很強(qiáng)一個(gè)完整的鏈路就是多個(gè)組件用管道連接。5.2 輸出解析器從文本到結(jié)構(gòu)化數(shù)據(jù)讓模型輸出 JSON 是常見(jiàn)需求但直接生成 JSON 經(jīng)常出現(xiàn)多余解釋、格式不完整等問(wèn)題。LangChain 提供了輸出解析器讓模型按照指定結(jié)構(gòu)輸出并自動(dòng)修復(fù)。from langchain_core.output_parsers import StrOutputParser, JsonOutputParser from pydantic import BaseModel, Field class BugReport(BaseModel): component: str Field(description出現(xiàn)問(wèn)題的系統(tǒng)模塊) level: str Field(description嚴(yán)重級(jí)別critical/major/minor) suggestion: str Field(description修復(fù)建議) parser JsonOutputParser(pydantic_objectBugReport) prompt ChatPromptTemplate.from_messages([ (system, 根據(jù)用戶(hù)描述提取Bug信息嚴(yán)格按JSON格式輸出不要輸出其他內(nèi)容。\n{format_instructions}), (user, {description}), ]) chain prompt | llm | parser result chain.invoke({ description: 用戶(hù)登錄時(shí)驗(yàn)證碼一直提示過(guò)期檢查發(fā)現(xiàn)是Redis緩存時(shí)間設(shè)置錯(cuò)誤, format_instructions: parser.get_format_instructions(), }) print(result)運(yùn)行輸出是一個(gè)字典結(jié)構(gòu){ component: 用戶(hù)登錄, level: major, suggestion: 檢查Redis中驗(yàn)證碼緩存的過(guò)期時(shí)間確認(rèn)時(shí)間單位是否正確 }這里的實(shí)用價(jià)值在于結(jié)構(gòu)化輸出是 Agent 的基石。當(dāng)模型要調(diào)用工具時(shí)它輸出的必須是嚴(yán)格結(jié)構(gòu)化的工具調(diào)用參數(shù)而不是一句話(huà)描述“我想調(diào)用查詢(xún)函數(shù)”。理解了JsonOutputParser的用法你就能理解 Agent 內(nèi)部是怎么約束模型輸出的。6. Tool 與 Agent 核心機(jī)制從生成文本到執(zhí)行動(dòng)作現(xiàn)在進(jìn)入本文的核心章節(jié)智能 Agent 開(kāi)發(fā)。6.1 工具的本質(zhì)在 Agent 框架里一個(gè)“工具”就是一個(gè)函數(shù)加一段描述。模型看到“可以用什么工具”但不會(huì)看到函數(shù)的實(shí)現(xiàn)細(xì)節(jié)。關(guān)鍵在于描述要清楚因?yàn)槟Ｐ驼强棵枋鰜?lái)判斷“這個(gè)任務(wù)該用哪個(gè)工具”。# agent_demo.py from langchain_core.tools import tool tool def get_user_balance(user_id: str) - str: 查詢(xún)用戶(hù)賬戶(hù)余額。入?yún)ser_id為用戶(hù)的唯一標(biāo)識(shí)。 Args: user_id: 用戶(hù)ID字符串例如U12345 # 實(shí)際項(xiàng)目中這里會(huì)查數(shù)據(jù)庫(kù)或調(diào)用內(nèi)部服務(wù) data { U12345: 1000.50, U99999: 0, } balance data.get(user_id, -1) return f用戶(hù){user_id}的賬戶(hù)余額是{balance}元 tool def send_warning_message(user_id: str) - str: 當(dāng)用戶(hù)余額異?；虻陀陂撝禃r(shí)向用戶(hù)發(fā)送風(fēng)險(xiǎn)預(yù)警消息。 return f已向用戶(hù){user_id}發(fā)送余額預(yù)警這里容易踩坑的地方是工具描述不寫(xiě)清楚模型就不知道該不該調(diào)用、怎么調(diào)用。get_user_balance的 docstring 里既說(shuō)明了“做什么”又說(shuō)明了“參數(shù)是什么”還給了示例值這就是典型的“機(jī)器可讀”描述寫(xiě)法。6.2 創(chuàng)建第一個(gè)工具調(diào)用 Agentfrom langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate from langchain_openai import ChatOpenAI llm ChatOpenAI( modelos.getenv(OPENAI_MODEL_NAME), temperature0, ) tools [get_user_balance, send_warning_message] prompt ChatPromptTemplate.from_messages([ (system, 你是一個(gè)銀行客服助手。查詢(xún)余額前先確認(rèn)用戶(hù)ID有效如果余額為0或異常請(qǐng)調(diào)用預(yù)警工具。), (placeholder, {chat_history}), (human, {input}), (placeholder, {agent_scratchpad}), ]) agent create_tool_calling_agent(llm, tools, prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue) result agent_executor.invoke({ input: 幫我查一下用戶(hù)U12345的余額 }) print(result[output])create_tool_calling_agent的作用是讓模型在需要時(shí)輸出tool_calls指令A(yù)gentExecutor 自動(dòng)執(zhí)行對(duì)應(yīng)工具并把返回結(jié)果再次喂給模型。agent_scratchpad是 LangChain 用來(lái)存放“模型已執(zhí)行過(guò)的推理過(guò)程與工具返回結(jié)果”的占位區(qū)域這是 Agent 循環(huán)可以持續(xù)推理的關(guān)鍵。6.3 Agent 與 Chain 的選擇判斷很多初學(xué)者問(wèn)我什么時(shí)候用 Chain什么時(shí)候用 Agent簡(jiǎn)單判斷標(biāo)準(zhǔn)如果執(zhí)行流程是確定的用 Chain如果執(zhí)行流程要看用戶(hù)輸入和中間結(jié)果而變化用 Agent。比如報(bào)銷(xiāo)審批流程步驟固定提交 - 校驗(yàn)金額 - 領(lǐng)導(dǎo)審批 - 財(cái)務(wù)打款。這種用 Chain 更像狀態(tài)機(jī)安全可控。而“幫我分析這份文檔然后生成摘要再比較其中的數(shù)據(jù)最后生成周報(bào)”這種不固定順序的任務(wù)一個(gè) Agent 要靈活得多。但要警惕Agent 的自由度也意味著不確定性。在生產(chǎn)環(huán)境使用 Agent一定要加白名單、工具權(quán)限控制、調(diào)用審計(jì)并在關(guān)鍵節(jié)點(diǎn)引入人工確認(rèn)。這一點(diǎn)在后面最佳實(shí)踐里還會(huì)細(xì)說(shuō)。7. 項(xiàng)目實(shí)戰(zhàn)構(gòu)建一個(gè)“文檔問(wèn)答 工具調(diào)用”的智能 Agent前面的例子都偏演示這一節(jié)把能力整合起來(lái)做一個(gè)真實(shí)感的項(xiàng)目企業(yè)內(nèi)部知識(shí)庫(kù)問(wèn)答 Agent。這個(gè)項(xiàng)目需要兩個(gè)核心能力從 PDF/文本中加載知識(shí)切分后存入向量庫(kù)實(shí)現(xiàn) RAG 檢索增強(qiáng)問(wèn)答在回答業(yè)務(wù)問(wèn)題時(shí)如果需要訪(fǎng)問(wèn)實(shí)時(shí)數(shù)據(jù)比如查詢(xún)工單狀態(tài)模型會(huì)自動(dòng)調(diào)用工具。7.1 項(xiàng)目結(jié)構(gòu)knowledge_agent/ ├── .env ├── requirements.txt ├── knowledge/ # 存放知識(shí)文檔 │ └── handbook.pdf ├── vector_store/ # 向量庫(kù)索引保存目錄 ├── ingest.py # 文檔導(dǎo)入腳本 ├── agent.py # Agent 主程序 └── tools.py # 自定義工具7.2 文檔導(dǎo)入與向量化# ingest.py from langchain_community.document_loaders import PyPDFLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings from langchain_community.vectorstores import FAISS loader PyPDFLoader(knowledge/handbook.pdf) documents loader.load() text_splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap100, separators[\n\n, \n, 。, , , ], ) docs text_splitter.split_documents(documents) embeddings OpenAIEmbeddings() vector_store FAISS.from_documents(docs, embeddings) vector_store.save_local(vector_store/handbook_index) print(f文檔已切分為 {len(docs)} 個(gè)片段并寫(xiě)入向量庫(kù))切分參數(shù)是 RAG 效果的關(guān)鍵。chunk_size太大模型一次接收的上下文過(guò)多檢索相關(guān)性下降chunk_size太小單個(gè)片段信息不完整。chunk_overlap用于保留上下文銜接避免一句話(huà)被攔腰切斷。7.3 自定義查詢(xún)工具實(shí)際業(yè)務(wù)里知識(shí)庫(kù)文檔里的信息可能是靜態(tài)的比如制度、手冊(cè)但工單狀態(tài)、庫(kù)存數(shù)量是動(dòng)態(tài)的需要通過(guò)工具查詢(xún)。# tools.py from langchain_core.tools import tool tool def query_order_status(order_id: str) - str: 根據(jù)訂單號(hào)查詢(xún)訂單當(dāng)前處理狀態(tài)。用于回答物流、訂單進(jìn)度類(lèi)問(wèn)題。 fake_db { SO20241001: 已發(fā)貨預(yù)計(jì)3天內(nèi)送達(dá), SO20241002: 正在倉(cāng)庫(kù)揀貨, } return fake_db.get(order_id, 未查詢(xún)到該訂單請(qǐng)確認(rèn)訂單號(hào)是否正確)7.4 Agent 主程序RAG 檢索器作為工具LangChain Agent 不僅可以把普通函數(shù)當(dāng)工具還可以把檢索器包裝成工具。這讓 Agent 具備“先檢索再回答”的能力。# agent.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI, OpenAIEmbeddings from langchain_community.vectorstores import FAISS from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate from langchain.tools.retriever import create_retriever_tool from tools import query_order_status load_dotenv() # 1. 構(gòu)建檢索器 embeddings OpenAIEmbeddings() vector_store FAISS.load_local( vector_store/handbook_index, embeddings, allow_dangerous_deserializationTrue, # 僅用于本地可信索引 ) retriever vector_store.as_retriever(search_kwargs{k: 3}) retriever_tool create_retriever_tool( retriever, nameknowledge_base_search, description搜索企業(yè)知識(shí)庫(kù)查找流程規(guī)范、制度政策、產(chǎn)品使用說(shuō)明等信息。當(dāng)用戶(hù)問(wèn)題涉及公司制度或產(chǎn)品操作時(shí)必須先調(diào)用該工具。, ) # 2. 模型和工具 llm ChatOpenAI( modelos.getenv(OPENAI_MODEL_NAME), temperature0.2, ) tools [retriever_tool, query_order_status] # 3. 提示詞 prompt ChatPromptTemplate.from_messages([ (system, ( 你是企業(yè)內(nèi)部智能助理?；卮鹨骪n 1. 涉及制度、規(guī)范類(lèi)問(wèn)題必須調(diào)用知識(shí)庫(kù)工具基于檢索結(jié)果回答。\n 2. 涉及訂單、物流問(wèn)題必須調(diào)用訂單查詢(xún)工具。\n 3. 如果工具沒(méi)有返回有效信息明確告知用戶(hù)需要補(bǔ)充信息不要編造答案。 )), (placeholder, {chat_history}), (human, {input}), (placeholder, {agent_scratchpad}), ]) # 4. 創(chuàng)建并執(zhí)行 Agent agent create_tool_calling_agent(llm, tools, prompt) agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, max_iterations5, early_stopping_methodforce, ) if __name__ __main__: while True: user_input input(\n請(qǐng)輸入你的問(wèn)題輸入exit退出) if user_input.lower() exit: break response agent_executor.invoke({input: user_input}) print(\n回答:, response[output])這里有幾個(gè)工程細(xì)節(jié)要重點(diǎn)說(shuō)明allow_dangerous_deserializationTrue只有在加載本地可信索引時(shí)才允許絕不要用在不可信的共享索引文件上。這是安全邊界問(wèn)題。search_kwargs{k: 3}控制檢索返回的片段數(shù)量。片段數(shù)越多模型參考信息越多但也更容易被無(wú)關(guān)信息干擾。max_iterations5限制 Agent 的最大推理輪數(shù)防止模型在工具調(diào)用中陷入死循環(huán)。檢索器描述中明確寫(xiě)了“當(dāng)用戶(hù)問(wèn)題涉及公司制度或產(chǎn)品操作時(shí)必須先調(diào)用該工具”。這種“觸發(fā)條件”描述是讓 Agent 正確決策的關(guān)鍵提示詞。8. 運(yùn)行結(jié)果與效果驗(yàn)證運(yùn)行 Agent 主程序python agent.py測(cè)試一制度類(lèi)問(wèn)題請(qǐng)輸入你的問(wèn)題輸入exit退出公司的年假制度是怎樣的期望的 Agent 行為模型先判斷該問(wèn)題屬于“知識(shí)庫(kù)”范疇調(diào)用knowledge_base_search工具檢索向量庫(kù)把相關(guān)文本片段帶回然后基于片段組織回答并能在回答中給出參考來(lái)源。如果verboseTrue控制臺(tái)會(huì)顯示模型選擇工具、工具返回結(jié)果的過(guò)程。這是調(diào)試 Agent 最重要的手段。測(cè)試二動(dòng)態(tài)數(shù)據(jù)問(wèn)題請(qǐng)輸入你的問(wèn)題輸入exit退出SO20241001這個(gè)訂單現(xiàn)在什么狀態(tài)期望行為模型調(diào)用query_order_status工具不再走知識(shí)庫(kù)檢索。測(cè)試三跨工具復(fù)合問(wèn)題請(qǐng)輸入你的問(wèn)題輸入exit退出用戶(hù)想了解請(qǐng)假流程同時(shí)查詢(xún)一下他的訂單SO20241002到哪里了。期望行為模型判斷這是兩個(gè)獨(dú)立任務(wù)會(huì)依次調(diào)用知識(shí)庫(kù)工具和訂單查詢(xún)工具最后把兩部分答案匯總。如果 Agent 只回答了其中一部分說(shuō)明提示詞里的工具描述還不夠清晰或者模型版本工具調(diào)用能力偏弱。8.1 如何判斷 Agent 運(yùn)行是否正常判斷成功不只看最終回答還要看推理路徑是否符合預(yù)期檢查點(diǎn)正常表現(xiàn)異常表現(xiàn)工具選擇問(wèn)題類(lèi)型與工具描述匹配制度問(wèn)題調(diào)了訂單工具參數(shù)提取訂單號(hào)準(zhǔn)確傳給了工具模型自己設(shè)計(jì)了不存在的參數(shù)工具返回返回結(jié)果出現(xiàn)在日志中工具拋出異常但 Agent 未捕獲最終回答引用了檢索結(jié)果內(nèi)容答案看起來(lái)像模型憑空編造如果回答內(nèi)容明顯不是來(lái)自檢索文檔優(yōu)先檢查是否已經(jīng)執(zhí)行了ingest.py以及檢索返回的k是否過(guò)小。9. 常見(jiàn)問(wèn)題與排查思路問(wèn)題現(xiàn)象可能原因排查方式解決方案模型報(bào)AuthenticationErrorAPI Key 錯(cuò)誤或沒(méi)有寫(xiě)入 .env檢查 .env 文件和load_dotenv()是否執(zhí)行確認(rèn) Key 格式確認(rèn)環(huán)境變量名正確模型報(bào)NotFoundError模型名不支持或 API Base 地址錯(cuò)誤查看完整報(bào)錯(cuò)中的 model 和 base_url換成模型服務(wù)商支持的模型名檢查是否缺少/v1FAISS 加載時(shí)報(bào)allow_dangerous_deserialization錯(cuò)誤新版 LangChain 安全策略要求顯式聲明閱讀報(bào)錯(cuò)提示確認(rèn)索引來(lái)自可信來(lái)源后設(shè)置參數(shù)為 TrueAgent 一直重復(fù)調(diào)用同一個(gè)工具工具返回結(jié)果沒(méi)有滿(mǎn)足模型預(yù)期或 description 不清晰打開(kāi) verbose 日志觀察工具返回內(nèi)容和模型下一步判斷優(yōu)化工具描述增加結(jié)果校驗(yàn)設(shè)置max_iterations檢索結(jié)果不相關(guān)切分粒度太大或 embedding 模型不匹配檢查 chunk_size、檢索 k 值打印檢索片段調(diào)整切分參數(shù)更換更強(qiáng)的 embedding 模型API 請(qǐng)求超時(shí)網(wǎng)絡(luò)不穩(wěn)定或模型響應(yīng)過(guò)慢查看日志中的超時(shí)時(shí)間調(diào)大timeout參數(shù)增加max_retriesLangChain 版本升級(jí)導(dǎo)致的 API 變動(dòng)是使用過(guò)程中最常見(jiàn)的坑。遇到.invoke()、create_tool_calling_agent等方法報(bào)不存在時(shí)先去查看當(dāng)前安裝版本的官方文檔再檢查遷移說(shuō)明。很多項(xiàng)目就是安裝最新版 LangChain 后跑著跑著舊版教程代碼直接崩了。方法是安裝時(shí)固定大版本pip install langchain0.2,0.410. 最佳實(shí)踐與工程建議10.1 配置管理一切皆配置模型名、API Key、數(shù)據(jù)庫(kù)連接、向量庫(kù)路徑都不要寫(xiě)死在代碼里。建議使用.env文件加配置中心結(jié)合的方式。團(tuán)隊(duì)協(xié)作時(shí).env 不進(jìn)倉(cāng)庫(kù)用.env.example提交占位。10.2 提示詞與工具描述是一等公民把 Prompt 和工具描述當(dāng)作代碼一樣管理建議單獨(dú)存放prompts/ ├── agent_system.txt └── tool_descriptions.yaml后續(xù)調(diào)優(yōu)時(shí)你會(huì)發(fā)現(xiàn)大多數(shù) Agent 問(wèn)題不是模型的錯(cuò)而是工具描述寫(xiě)得不清楚。10.3 安全邊界Agent 權(quán)限控制Agent 很強(qiáng)大但它也會(huì)執(zhí)行你給它的工具。在生產(chǎn)環(huán)境必須做到工具只暴露最小權(quán)限比如只讀接口不允許任意寫(xiě)庫(kù)對(duì) Agent 的調(diào)用做日志審計(jì)記錄每一次工具調(diào)用的參數(shù)和結(jié)果涉及資金、刪除、修改類(lèi)操作加入人工確認(rèn)環(huán)節(jié)不要讓模型直接執(zhí)行。10.4 日志與可觀測(cè)性verboseTrue只適合開(kāi)發(fā)調(diào)試。生產(chǎn)環(huán)境建議接入 LangSmith 或自建日志系統(tǒng)記錄用戶(hù)輸入和最終輸出模型每一次工具調(diào)用的請(qǐng)求參數(shù)每次調(diào)用的耗時(shí)和 token 消耗。這樣你才能知道 Agent 跑一次業(yè)務(wù)到底花了多少錢(qián)、哪個(gè)環(huán)節(jié)最慢、哪個(gè)工具被反復(fù)調(diào)用。10.5 從 LangChain 到 LangGraph如果你用 LangChain Agent 開(kāi)發(fā)到一定復(fù)雜度會(huì)遇到兩個(gè)明顯痛點(diǎn)第一狀態(tài)控制弱。AgentExecutor 的循環(huán)是框架內(nèi)置的你想在中間插入“人工審核節(jié)點(diǎn)”或者“條件分支”比較麻煩。第二保存和恢復(fù)難。線(xiàn)上 Agent 執(zhí)行到一半進(jìn)程崩潰了現(xiàn)場(chǎng)很難恢復(fù)。這時(shí)候需要關(guān)注 LangGraph。它把 Agent 的每一步定義成圖中的節(jié)點(diǎn)節(jié)點(diǎn)之間用邊連接你可以精確控制模型判斷 - 工具A - 人工確認(rèn) - 工具B - 回答還可以支持條件邊模型調(diào)用工具后根據(jù)返回結(jié)果決定走哪個(gè)分支。LangGraph 提供了更底層的編排能力適合生產(chǎn)級(jí) Agent。本文篇幅有限不展開(kāi) LangGraph 的語(yǔ)法但這是一個(gè)非常值得繼續(xù)深入的方向。對(duì)于剛?cè)腴T(mén)的人來(lái)說(shuō)現(xiàn)有 LangChain Agent 足夠跑通業(yè)務(wù)驗(yàn)證當(dāng)流程復(fù)雜度上來(lái)后再遷移到 LangGraph 也不遲。11. 總結(jié)與后續(xù)學(xué)習(xí)方向這篇文章打通了 LangChain 的完整學(xué)習(xí)路徑從 Model 的統(tǒng)一封裝到 Prompt 模板和輸出解析再到 Chain 的管道編排最后通過(guò) Tool 機(jī)制實(shí)現(xiàn)智能 Agent并落地了一個(gè)“文檔問(wèn)答 實(shí)時(shí)工具調(diào)用”的實(shí)戰(zhàn)項(xiàng)目。復(fù)盤(pán)一下你學(xué)到了四個(gè)關(guān)鍵判斷LangChain 的核心價(jià)值不是“調(diào)模型”而是“統(tǒng)一模型接口 標(biāo)準(zhǔn)化應(yīng)用組裝 支持動(dòng)作執(zhí)行”。Chain 適合固定流程Agent 適合動(dòng)態(tài)規(guī)劃。選擇之前先想清楚流程是否確定。工具描述是 Agent 效果的上限。模型能不能正確選工具取決于你怎么寫(xiě) description。生產(chǎn)環(huán)境用 Agent 必須加權(quán)限控制、日志審計(jì)和人工確認(rèn)節(jié)點(diǎn)不能裸奔。如果你按照文章示例跑通了項(xiàng)目下一步建議按這個(gè)順序深入把 RAG 的檢索效果調(diào)優(yōu)學(xué)習(xí)分塊策略、rerank 和混合檢索研究 LangGraph 的狀態(tài)圖模型把 Agent 工作流從“黑盒循環(huán)”改造成“可視化、可控狀態(tài)機(jī)”關(guān)注 Streamlit 或 FastAPI把命令行 Agent 封裝成 Web 應(yīng)用探索大模型微調(diào)Fine-tuning當(dāng) Prompt 無(wú)論如何調(diào)優(yōu)都無(wú)法滿(mǎn)足場(chǎng)景時(shí)微調(diào)是一個(gè)更底層的優(yōu)化方向。建議收藏本文作為你后續(xù) LangChain 使用的速查手冊(cè)。遇到 API 版本問(wèn)題或 Agent 行為異常時(shí)回到這份代碼和排查表比重新翻一遍文檔要快得多。