1. 為什么 LangChain 1.3 值得重新學(xué)一遍如果你最近搜過(guò) LangChain 的資料大概率會(huì)有一個(gè)感覺(jué)網(wǎng)上教程要么停留在 0.1/0.2 版本要么直接跳到 LangGraph中間斷層非常嚴(yán)重。這個(gè)斷層不是錯(cuò)覺(jué)而是 LangChain 在過(guò)去兩年里完成了一次底層重構(gòu)。0.x 時(shí)代的Chain和Agent設(shè)計(jì)到了 1.x 已經(jīng)被大幅簡(jiǎn)化以前需要十幾個(gè)依賴包才能跑通的 RAG 鏈路現(xiàn)在只需要一條pip install langchain加幾個(gè)核心模塊而 Agent 的編排邏輯則被完整移交給了 LangGraph。也就是說(shuō)你現(xiàn)在從舊教程學(xué)到的很多 API很可能在新版本里已經(jīng)廢棄了。這也是我寫這篇文章的原因。我們要聊的不是LangChain 又更新了什么小版本而是從 2025 年后 LangChain 進(jìn)入 1.x 穩(wěn)定期以來(lái)它的開(kāi)發(fā)范式到底發(fā)生了哪些變化以及作為一個(gè)普通開(kāi)發(fā)者你該怎么用最短時(shí)間把入門到代碼實(shí)戰(zhàn)這件事跑通。在動(dòng)手之前先給出我對(duì) LangChain 1.3 的核心判斷LangChain 1.x 不再是一個(gè)什么都能干的框架平臺(tái)而是一套面向大模型應(yīng)用開(kāi)發(fā)的標(biāo)準(zhǔn)組件庫(kù)。它不負(fù)責(zé) AI 推理本身也不負(fù)責(zé)模型訓(xùn)練它負(fù)責(zé)的是把模型、工具、數(shù)據(jù)、狀態(tài)流編排成一個(gè)可穩(wěn)定運(yùn)行的應(yīng)用這件事。 換句話說(shuō)LangChain 是膠水不是引擎。這篇文章會(huì)沿著一條完整的實(shí)戰(zhàn)路徑展開(kāi)先講清楚基礎(chǔ)概念和常見(jiàn)誤區(qū)然后搭建環(huán)境再用一個(gè)最小 RAG 項(xiàng)目和一個(gè) Agent 項(xiàng)目帶你體驗(yàn) LangChain 1.3 的完整開(kāi)發(fā)流程。最后給出排錯(cuò)清單和工程建議方便你直接遷移到實(shí)際項(xiàng)目中。如果你是下面這幾類讀者這篇文章最適合你只寫過(guò)幾段prompt調(diào)用想系統(tǒng)了解 LangChain 怎么組織代碼的開(kāi)發(fā)者被 LangGraph、Agent、MCP 這幾個(gè)概念繞暈想搞清它們之間關(guān)系的人從 0.x 時(shí)代的老教程入門發(fā)現(xiàn)代碼跑不起來(lái)想切換到 1.x 新寫法的開(kāi)發(fā)者。2. LangChain 基礎(chǔ)概念框架邊界與核心組件2.1 LangChain 到底解決什么問(wèn)題在沒(méi)有 LangChain 之前開(kāi)發(fā)一個(gè)大模型應(yīng)用其實(shí)也能做# 不使用框架的最小實(shí)現(xiàn) import openai client openai.OpenAI() resp client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是一個(gè)專業(yè)助手。}, {role: user, content: 請(qǐng)總結(jié)這段文本……} ] ) print(resp.choices[0].message.content)這段代碼很簡(jiǎn)單但它只解決了調(diào)用一次模型的問(wèn)題。一旦你的應(yīng)用需要連續(xù)對(duì)話、從文檔庫(kù)檢索、調(diào)用外部工具、處理中間狀態(tài)、追蹤每一次模型調(diào)用的耗時(shí)和 token 成本事情就開(kāi)始變得不可控。你需要自己管理對(duì)話歷史、自己處理向量化與存儲(chǔ)、自己寫工具循環(huán)、自己設(shè)計(jì)異常重試。LangChain 的核心價(jià)值就是把這一段自己寫邏輯變成了組裝模塊場(chǎng)景沒(méi)有 LangChain 時(shí)要做的工作使用 LangChain 后對(duì)話記憶自己維護(hù) messages 列表拼接歷史ChatMessageHistory直接管理RAG 檢索自己封裝向量化 向量庫(kù)查詢加載器、分割器、向量庫(kù)接口統(tǒng)一工具調(diào)用自己寫 while 循環(huán)讓模型反復(fù)選擇Agent 編排器自動(dòng)完成耗時(shí)追蹤手動(dòng)記錄每次 API 調(diào)用回調(diào)系統(tǒng)統(tǒng)一收集一句話概括LangChain 解決的是大模型應(yīng)用工程化的問(wèn)題而不是大模型本身的問(wèn)題。2.2 LangChain 與 LangGraph 的區(qū)別這是熱搜里出現(xiàn)頻率最高的問(wèn)題之一也是新手最容易踩坑的地方。LangChain 和 LangGraph 不是同一個(gè)層面的東西LangChain面向應(yīng)用開(kāi)發(fā)者的工具集。包括模型封裝、Prompt 模板、輸出解析器、向量存儲(chǔ)接口、文檔加載器、文本分割器等。你可以用它快速搭出 RAG、問(wèn)答、總結(jié)等應(yīng)用。LangGraph面向復(fù)雜狀態(tài)流的編排引擎。它把一次 AI 應(yīng)用執(zhí)行看作一張圖圖中的節(jié)點(diǎn)是要執(zhí)行的動(dòng)作比如調(diào)用模型、調(diào)用工具、查數(shù)據(jù)庫(kù)邊是狀態(tài)轉(zhuǎn)移。它更擅長(zhǎng)做 Agent、多步驟工作流、人機(jī)協(xié)同等需要精細(xì)控制流程的場(chǎng)景。在 LangChain 1.x 體系里兩者是配合關(guān)系LangChain 零件庫(kù)模型、工具、解析器、向量庫(kù) LangGraph 總裝線節(jié)點(diǎn)、狀態(tài)、條件分支、循環(huán)所以當(dāng)你看到LangChain 過(guò)時(shí)了嗎這個(gè)問(wèn)題時(shí)準(zhǔn)確理解是LangChain 作為框架并沒(méi)有過(guò)時(shí)過(guò)時(shí)的是 0.x 時(shí)代那種用 Chain 堆邏輯的寫法新的官方建議是復(fù)雜流程用 LangGraph 編排LangChain 負(fù)責(zé)提供底層組件。2.3 Agent 與 Skill、Tool 的關(guān)系A(chǔ)gent智能體是 LangChain 里最容易被誤解的概念。Agent 不是什么黑魔法模型而是一個(gè)由大模型驅(qū)動(dòng)決策的控制循環(huán)。它接收一個(gè)任務(wù)自己判斷我需要調(diào)用哪個(gè)工具調(diào)用之后結(jié)果滿足要求了嗎不夠就繼續(xù)調(diào)用直到任務(wù)完成。在 LangChain 1.x 的語(yǔ)境下幾個(gè)概念要分清Tool工具可以被模型調(diào)用的函數(shù)。比如查詢天氣執(zhí)行 SQL搜索網(wǎng)頁(yè)。它是對(duì)外能力的抽象。Skill技能一組相關(guān)工具和提示詞的組合。比如數(shù)據(jù)分析技能可能包含 SQL 工具、Python 執(zhí)行工具、報(bào)表生成工具。它更偏向業(yè)務(wù)粒度的復(fù)用。Agent智能體使用這些工具完成任務(wù)的決策主體。它知道自己有哪些工具可選也知道當(dāng)前任務(wù)的目標(biāo)。初學(xué)者最容易犯的錯(cuò)誤是把能調(diào)用工具等同于有智能。實(shí)際上 Agent 的能力上限由三件事決定底層模型的推理能力、工具的可靠性、以及你對(duì)狀態(tài)流的控制能力。LangChain 1.x 的 Agent 設(shè)計(jì)理念就是盡量把控制權(quán)交還給開(kāi)發(fā)者而不是讓模型自由發(fā)揮。2.4 Prompt、RAG 與 MCP 的定位這部分是 2025 年后 LangChain 生態(tài)最熱的三件事值得單獨(dú)說(shuō)明Prompt 工程最輕量級(jí)的應(yīng)用開(kāi)發(fā)方式。它不引入外部數(shù)據(jù)完全靠提示詞設(shè)計(jì)約束模型行為。適合需求簡(jiǎn)單、不涉及私有數(shù)據(jù)的場(chǎng)景。RAG檢索增強(qiáng)生成給模型外掛一個(gè)知識(shí)庫(kù)。回答問(wèn)題時(shí)先從庫(kù)里檢索相關(guān)內(nèi)容拼進(jìn)上下文再讓模型生成回答。這是目前企業(yè)落地大模型應(yīng)用最常見(jiàn)的技術(shù)路線。MCPModel Context Protocol統(tǒng)一模型如何接入外部工具和數(shù)據(jù)源的協(xié)議。它和 LangChain 的關(guān)系是互補(bǔ)而非競(jìng)爭(zhēng)LangChain 提供的是 Python 開(kāi)發(fā)框架MCP 提供的是標(biāo)準(zhǔn)化的工具接入?yún)f(xié)議。LangChain 1.x 已經(jīng)支持通過(guò) MCP 適配器連接 MCP 服務(wù)器這也是很多面試題里會(huì)問(wèn)的方向。3. 環(huán)境準(zhǔn)備與版本選型這部分我們直接進(jìn)入實(shí)操。3.1 版本選型建議寫這篇文章時(shí)LangChain 1.x 已經(jīng)進(jìn)入穩(wěn)定期。給你的選型建議是新項(xiàng)目一律使用langchain1.0的版本不要再安裝langchain-community全家桶按需安裝子包Agent 編排優(yōu)先使用langgraph而不是 0.x 時(shí)代的AgentExecutor向量庫(kù)根據(jù)項(xiàng)目實(shí)際選型本地演示可以用Chroma。注意不同子包的版本更新非常快下面的安裝命令只保證在當(dāng)前時(shí)間點(diǎn)可用。實(shí)際安裝時(shí)請(qǐng)以 PyPI 上的最新穩(wěn)定版本為準(zhǔn)不要死磕某一個(gè)固定版本號(hào)。本文重點(diǎn)演示的是 1.x 的通用開(kāi)發(fā)思路。3.2 安裝依賴推薦使用 Python 3.11 或 3.12 的虛擬環(huán)境避免系統(tǒng)級(jí)環(huán)境污染。# 創(chuàng)建并激活虛擬環(huán)境Windows/Linux/macOS 通用思路 python -m venv langchain-demo source langchain-demo/bin/activate # Windows 下使用 langchain-demo\Scripts\activate # 安裝核心依賴 pip install --upgrade pip pip install langchain pip install langchain-openai pip install langchain-community pip install langgraph # RAG 演示環(huán)境依賴 pip install chromadb pip install pypdf pip install tiktoken # 如果需要查看版本信息 pip show langchain langchain-openai langgraph依賴說(shuō)明langchain-openai官方維護(hù)的 OpenAI 模型適配包如果你用的是其他模型廠商就換成對(duì)應(yīng)的langchain-*適配包。langgraphAgent 編排和復(fù)雜流程控制必裝。chromadb本地向量數(shù)據(jù)庫(kù)適合學(xué)習(xí)和小規(guī)模原型。pypdf用來(lái)加載 PDF 文檔做 RAG 演示時(shí)需要。3.3 環(huán)境變量配置在項(xiàng)目根目錄創(chuàng)建.env文件OPENAI_API_KEYsk-你的密鑰 OPENAI_BASE_URLhttps://api.openai.com/v1如果你使用的是國(guó)內(nèi)兼容 OpenAI 接口的模型服務(wù)把OPENAI_BASE_URL改成你實(shí)際的服務(wù)地址即可。不要在生產(chǎn)代碼里硬編碼密鑰盡量通過(guò)環(huán)境變量或密鑰管理服務(wù)注入。4. 核心流程拆解一個(gè)最小 LangChain 應(yīng)用是怎么跑起來(lái)的在寫完整項(xiàng)目之前先用一個(gè)最小示例理解 LangChain 1.x 的核心開(kāi)發(fā)流程。4.1 最小調(diào)用Model 封裝LangChain 1.x 不再像 0.x 那樣要求你理解LLM和ChatModel的復(fù)雜繼承體系。你用ChatOpenAI就能完成絕大多數(shù)對(duì)話場(chǎng)景# 文件路徑: demo_01_basic.py from langchain_openai import ChatOpenAI # 創(chuàng)建模型實(shí)例 llm ChatOpenAI( modelgpt-4o-mini, temperature0.7 ) # 直接調(diào)用 resp llm.invoke(用一句話解釋什么是 LangChain) print(resp.content)關(guān)鍵點(diǎn)invoke是 1.x 的統(tǒng)一調(diào)用入口。無(wú)論是模型、鏈還是 Agent都實(shí)現(xiàn)了這個(gè)接口。ChatOpenAI返回的是一個(gè)AIMessage對(duì)象取內(nèi)容時(shí)需要.content。如果你需要多輪對(duì)話直接傳messages列表而不是自己拼接字符串。4.2 帶 Prompt 模板與輸出解析實(shí)際項(xiàng)目中很少直接裸調(diào)模型。更常見(jiàn)的寫法是Prompt 模板 模型 輸出解析器用管道符組合成一條鏈。# 文件路徑: demo_02_prompt_chain.py from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser # 1. 定義提示詞模板 prompt ChatPromptTemplate.from_messages([ (system, 你是資深 {field} 工程師回答要專業(yè)、簡(jiǎn)潔。), (human, {question}) ]) # 2. 定義模型 llm ChatOpenAI(modelgpt-4o-mini, temperature0.3) # 3. 定義輸出解析器 parser StrOutputParser() # 4. 用 | 符號(hào)組裝成鏈這是 LCEL 核心語(yǔ)法 chain prompt | llm | parser # 5. 調(diào)用 result chain.invoke({ field: Python, question: 請(qǐng)解釋 Python 的 GIL 是什么以及它對(duì)多線程的影響。 }) print(result)這個(gè)例子體現(xiàn)了 LangChain 1.x 最重要的編程范式LCELLangChain Expression Language。LCEL 的核心思想是每個(gè)組件都實(shí)現(xiàn)Runnable接口然后通過(guò)|管道符組合。左邊組件的輸出自動(dòng)變成右邊組件的輸入。它的好處是代碼可讀性高一條鏈的完整流程一眼就能看清天然支持流式輸出、異步調(diào)用、批量處理可以方便地插入回調(diào)、日志和重試邏輯。很多新手第一次看到prompt | llm | parser會(huì)覺(jué)得奇怪以為只是語(yǔ)法糖。其實(shí) LCEL 背后是一整套 Runnable 協(xié)議它是理解 LangChain 1.x 的關(guān)鍵。4.3 核心流程總結(jié)一個(gè)標(biāo)準(zhǔn) LangChain 應(yīng)用的開(kāi)發(fā)流程可以拆成五步確定輸入輸出用戶輸入什么最終想要什么格式的結(jié)果。組裝 Prompt把系統(tǒng)提示、用戶輸入、外部上下文組織成模型可理解的 messages。選擇模型根據(jù)任務(wù)類型、成本、延遲選擇模型。補(bǔ)充檢索或工具如果需要外部知識(shí)接 RAG如果需要操作外部系統(tǒng)接 Tool。編排與驗(yàn)證簡(jiǎn)單場(chǎng)景用 LCEL復(fù)雜場(chǎng)景用 LangGraph最后驗(yàn)證輸出質(zhì)量和延遲。這五步是整個(gè) LangChain 開(kāi)發(fā)的基本功。后面的實(shí)戰(zhàn)項(xiàng)目都會(huì)圍繞這個(gè)框架展開(kāi)。5. 實(shí)戰(zhàn)一基于 LangChain 1.3 搭建 RAG 問(wèn)答系統(tǒng)RAG 是 LangChain 最經(jīng)典的應(yīng)用場(chǎng)景。我們用一個(gè)本地 PDF 文檔問(wèn)答作為實(shí)戰(zhàn)項(xiàng)目它足夠小能完整展示文檔加載、切分、向量化、檢索、生成全鏈路。5.1 項(xiàng)目結(jié)構(gòu)langchain-rag-demo/ ├── .env ├── data/ │ └── langchain-intro.pdf # 你本地的知識(shí)庫(kù)文檔 ├── rag_demo.py # 主程序 └── requirements.txt在data/目錄下放任意一份 PDF 文檔即可。我這里使用一份關(guān)于 LangChain 的介紹文檔作為示例。5.2 完整實(shí)現(xiàn)# 文件路徑: rag_demo.py import os from dotenv import load_dotenv # 加載 .env 文件 load_dotenv() from langchain_openai import ChatOpenAI, OpenAIEmbeddings from langchain_community.document_loaders import PyPDFLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_chroma import Chroma from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser def build_vectorstore(): 加載文檔并構(gòu)建向量庫(kù)返回 retriever. # 1. 加載 PDF 文檔 loader PyPDFLoader(data/langchain-intro.pdf) docs loader.load() print(f加載了 {len(docs)} 頁(yè)文檔) # 2. 文本切分 text_splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap50, separators[\n\n, \n, 。, , , ., ] ) chunks text_splitter.split_documents(docs) print(f切分為 {len(chunks)} 個(gè)文本塊) # 3. 向量化并存儲(chǔ)到 Chroma embeddings OpenAIEmbeddings(modeltext-embedding-3-small) vectorstore Chroma.from_documents( documentschunks, embeddingembeddings, persist_directory./chroma_db ) # 4. 獲取檢索器返回 Top-K4 retriever vectorstore.as_retriever(search_kwargs{k: 4}) return retriever def create_rag_chain(retriever): 構(gòu)建 RAG 鏈路. # 1. 提示詞模板要求模型基于提供的上下文回答 prompt ChatPromptTemplate.from_messages([ (system, 你是一個(gè)嚴(yán)謹(jǐn)?shù)募夹g(shù)文檔助手。只能根據(jù)提供的上下文回答如果上下文中沒(méi)有相關(guān)信息就明確說(shuō)文檔中未找到相關(guān)答案不要編造。), (human, 上下文內(nèi)容\n{context}\n\n用戶問(wèn)題{question}) ]) llm ChatOpenAI(modelgpt-4o-mini, temperature0.2) parser StrOutputParser() # 2. 定義一個(gè)格式化上下文的函數(shù)把檢索結(jié)果拼成字符串 def format_docs(docs): return \n\n.join(doc.page_content for doc in docs) # 3. 使用 LCEL 組裝 RAG 鏈路 # retriever - format_docs - prompt - llm - parser chain ( { context: retriever | format_docs, question: lambda x: x[question] } | prompt | llm | parser ) return chain if __name__ __main__: # 首次運(yùn)行會(huì)構(gòu)建向量庫(kù)之后可以復(fù)用 retriever build_vectorstore() rag_chain create_rag_chain(retriever) # 測(cè)試問(wèn)答 while True: question input(請(qǐng)輸入問(wèn)題輸入 q 退出) if question.lower() q: break answer rag_chain.invoke({question: question}) print(\n回答, answer) print(- * 50)5.3 代碼邏輯說(shuō)明這段代碼里有幾個(gè)關(guān)鍵設(shè)計(jì)需要理解文本切分參數(shù)。chunk_size500表示每塊最多 500 個(gè)字符chunk_overlap50表示相鄰塊之間重疊 50 個(gè)字符。重疊的目的是避免在切分處丟失語(yǔ)義信息。中英文混排場(chǎng)景下在separators里加入中文標(biāo)點(diǎn)符號(hào)會(huì)更有效。format_docs 函數(shù)。從向量庫(kù)檢索出來(lái)的結(jié)果是一個(gè)Document列表每個(gè) Document 有page_content和metadata。這里把page_content拼接成字符串作為上下文注入 Prompt。為什么用|把它接在retriever后面因?yàn)?LCEL 支持自定義函數(shù)作為 Runnable函數(shù)接收上一個(gè)組件的輸出返回下一個(gè)組件需要的格式。檢索參數(shù)設(shè)置。search_kwargs{k: 4}表示返回最相似的 4 個(gè)文本塊。k 值太大會(huì)導(dǎo)致上下文冗長(zhǎng)、模型注意力分散k 值太小可能檢索不到關(guān)鍵信息。實(shí)際項(xiàng)目中需要根據(jù)文檔長(zhǎng)度和模型上下文窗口調(diào)試。5.4 運(yùn)行結(jié)果驗(yàn)證python rag_demo.py預(yù)期輸出效果類似加載了 10 頁(yè)文檔 切分為 28 個(gè)文本塊 請(qǐng)輸入問(wèn)題輸入 q 退出什么是 LCEL 回答根據(jù)文檔內(nèi)容LCEL 是 LangChain Expression Language 的縮寫是一種用于組合多個(gè)組件如 Prompt 模板、模型、輸出解析器的聲明式語(yǔ)法使用豎線|操作符將這些組件串聯(lián)成一個(gè)可執(zhí)行的鏈…… 請(qǐng)輸入問(wèn)題文檔里沒(méi)有提到的內(nèi)容呢 回答文檔中未找到相關(guān)答案。如何判斷系統(tǒng)是否工作正常第一次運(yùn)行會(huì)看到加載和切分日志說(shuō)明文檔讀取成功問(wèn)題能被正?；卮鹫f(shuō)明向量檢索和生成鏈路已經(jīng)打通問(wèn)一個(gè)文檔里沒(méi)有的內(nèi)容模型能拒絕回答說(shuō)明系統(tǒng)沒(méi)有被幻覺(jué)帶偏。如果回答內(nèi)容完全和文檔無(wú)關(guān)大概率是檢索失效先檢查 Chroma 目錄是否成功生成再檢查 k 值是否過(guò)小。6. 實(shí)戰(zhàn)二基于 LangGraph 構(gòu)建帶任務(wù)規(guī)劃的 Agent第二個(gè)項(xiàng)目是 Agent。網(wǎng)上關(guān)于 Agent 的討論很多但真正能幫忙跑通一個(gè)帶任務(wù)規(guī)劃的 Agent 項(xiàng)目的教程其實(shí)不多。這一節(jié)我們用 LangGraph 實(shí)現(xiàn)一個(gè)能自主規(guī)劃并調(diào)用工具完成任務(wù)的 Agent。6.1 為什么用 LangGraph 而不是舊版 AgentExecutor在 LangChain 0.x 時(shí)代initialize_agent一鍵創(chuàng)建 Agent 的方式很受歡迎但它有一個(gè)問(wèn)題Agent 的決策過(guò)程像一個(gè)黑盒你很難干預(yù)它現(xiàn)在準(zhǔn)備做什么。當(dāng)任務(wù)復(fù)雜、工具變多之后排查問(wèn)題會(huì)非常痛苦。LangGraph 的定位是可控的 Agent 運(yùn)行時(shí)。你可以明確地定義這個(gè) Agent 有哪些狀態(tài)模型在哪里做決策工具調(diào)用失敗后怎么辦什么條件下結(jié)束循環(huán)。它把不可控的循環(huán)變成了可以看到每一步的圖執(zhí)行。6.2 LangGraph 核心概念使用 LangGraph 前先建立三個(gè)基本概念State全局狀態(tài)對(duì)象。它貫穿整個(gè)圖每個(gè)節(jié)點(diǎn)都可以讀取和修改它。比如messages是常見(jiàn)的狀態(tài)字段用來(lái)保存整個(gè)對(duì)話歷史。Node圖中的節(jié)點(diǎn)就是一個(gè) Python 函數(shù)。它接收當(dāng)前狀態(tài)處理后返回新的狀態(tài)更新。Edge節(jié)點(diǎn)之間的連接。分為普通邊和條件邊。條件邊根據(jù)當(dāng)前狀態(tài)決定下一步走向哪個(gè)節(jié)點(diǎn)這是實(shí)現(xiàn)模型決策的關(guān)鍵機(jī)制。6.3 完整示例帶任務(wù)規(guī)劃的 Agent下面的示例實(shí)現(xiàn)了一個(gè)簡(jiǎn)單但完整的 Agent用戶提出任務(wù)Agent 自動(dòng)判斷是否調(diào)用工具調(diào)用工具后把結(jié)果交給模型繼續(xù)推理直到認(rèn)為任務(wù)完成。# 文件路徑: agent_demo.py import os from dotenv import load_dotenv load_dotenv() from typing import TypedDict, Annotated, Literal from langchain_openai import ChatOpenAI from langchain_core.messages import HumanMessage, AIMessage, SystemMessage from langchain_core.tools import tool from langgraph.graph import StateGraph, END from langgraph.prebuilt import ToolNode # ---------- 1. 定義工具 ---------- tool def add(a: int, b: int) - int: 計(jì)算兩個(gè)整數(shù)的和。 return a b tool def multiply(a: int, b: int) - int: 計(jì)算兩個(gè)整數(shù)的乘積。 return a * b tool def get_weather(city: str) - str: 獲取指定城市的當(dāng)前天氣概況模擬數(shù)據(jù)。 weather_map { 北京: 晴25 度, 上海: 多云27 度, 廣州: 小雨30 度, } return weather_map.get(city, 暫無(wú)該城市天氣數(shù)據(jù)) tools [add, multiply, get_weather] # ---------- 2. 定義狀態(tài) ---------- class AgentState(TypedDict): messages: Annotated[list, 對(duì)話歷史] next: str # 記錄下一步動(dòng)作類型 # ---------- 3. 定義模型節(jié)點(diǎn) ---------- llm ChatOpenAI(modelgpt-4o-mini, temperature0) # 讓模型知道可用工具 llm_with_tools llm.bind_tools(tools) def agent_node(state: AgentState): 模型決策節(jié)點(diǎn)判斷是直接回答還是調(diào)用工具. messages state[messages] # 調(diào)用模型模型可能返回 tool_calls也可能直接返回文本 response llm_with_tools.invoke(messages) return {messages: [response]} # ---------- 4. 定義條件路由 ---------- def router(state: AgentState) - Literal[tools, __end__]: 根據(jù)模型輸出判斷下一步有工具調(diào)用就去 tools 節(jié)點(diǎn)否則結(jié)束. last_message state[messages][-1] if hasattr(last_message, tool_calls) and last_message.tool_calls: return tools return __end__ # ---------- 5. 組裝圖 ---------- builder StateGraph(AgentState) # 添加節(jié)點(diǎn) builder.add_node(agent, agent_node) builder.add_node(tools, ToolNode(tools)) # 設(shè)置入口 builder.set_entry_point(agent) # agent 節(jié)點(diǎn)之后走條件路由 builder.add_conditional_edges( agent, router, { tools: tools, __end__: END } ) # 工具節(jié)點(diǎn)結(jié)束后回到 agent 繼續(xù)決策 builder.add_edge(tools, agent) # 編譯圖 graph builder.compile() # ---------- 6. 調(diào)用 Agent ---------- def run_agent(user_input: str): system_msg SystemMessage(content你是一個(gè)樂(lè)于助人的助手。如果用戶的請(qǐng)求涉及工具請(qǐng)先用工具計(jì)算再根據(jù)工具結(jié)果回答。) result graph.invoke({ messages: [system_msg, HumanMessage(contentuser_input)] }) # 返回最終回復(fù) return result[messages][-1].content if __name__ __main__: # 測(cè)試1需要拆解乘法任務(wù) print(run_agent(請(qǐng)計(jì)算 (3 5) * 2 的結(jié)果)) # 測(cè)試2查詢天氣 print(run_agent(上海今天天氣怎么樣)) # 測(cè)試3純文本對(duì)話 print(run_agent(你好請(qǐng)介紹一下你自己。))6.4 代碼邏輯與任務(wù)規(guī)劃?rùn)C(jī)制解析這段代碼雖然不長(zhǎng)但它已經(jīng)把 Agent 的任務(wù)規(guī)劃能力完整展示出來(lái)了。所謂任務(wù)規(guī)劃本質(zhì)上是模型在每一步做出下一步動(dòng)作的決策當(dāng)用戶問(wèn)請(qǐng)計(jì)算 (3 5) * 2 的結(jié)果模型首先理解這是一個(gè)算術(shù)問(wèn)題它可以調(diào)用add和multiply兩個(gè)工具第一次調(diào)用agent節(jié)點(diǎn)時(shí)模型輸出tool_calls里面包含工具名和參數(shù)但模型并不會(huì)真的執(zhí)行工具路由判斷存在tool_calls于是把控制權(quán)交給tools節(jié)點(diǎn)tools節(jié)點(diǎn)執(zhí)行真實(shí)函數(shù)把結(jié)果包裝成ToolMessage追加到messages控制權(quán)回到agent節(jié)點(diǎn)模型看到工具返回結(jié)果后繼續(xù)推理輸出最終答案這一次模型沒(méi)有tool_calls路由走向END流程結(jié)束。這就是 LangGraph 對(duì)任務(wù)規(guī)劃能力的典型實(shí)現(xiàn)用條件邊模擬循環(huán)用狀態(tài)對(duì)象保存中間結(jié)果讓模型成為每一步的決策者。6.5 運(yùn)行效果與驗(yàn)證python agent_demo.py預(yù)期輸出根據(jù)計(jì)算(3 5) * 2 的結(jié)果是 16。 上海今天多云27 度。 你好我是一個(gè)樂(lè)于助人的助手可以幫你回答問(wèn)題、執(zhí)行計(jì)算、查詢天氣等。有什么可以幫你的驗(yàn)證重點(diǎn)測(cè)試 1 能正確執(zhí)行多步工具調(diào)用后續(xù)調(diào)用沒(méi)有使用上一輪的錯(cuò)誤結(jié)果說(shuō)明狀態(tài)管理正確測(cè)試 2 能從get_weather返回的模擬數(shù)據(jù)中提取城市天氣說(shuō)明工具結(jié)果成功注入了上下文測(cè)試 3 能正常對(duì)話說(shuō)明條件路由在無(wú)工具調(diào)用場(chǎng)景下能正常結(jié)束流程。如果想看每一步的中間狀態(tài)可以給graph.invoke加上debug: True參數(shù)LangGraph 會(huì)打印每個(gè)節(jié)點(diǎn)的輸入輸出這是排查 Agent 問(wèn)題最直接的手段。7. LangChain 與 LangGraph 常見(jiàn)問(wèn)題與排查方法在實(shí)際開(kāi)發(fā)中新手最先遇到的技術(shù)問(wèn)題往往不是架構(gòu)設(shè)計(jì)而是各種看起來(lái)莫名其妙的環(huán)境和運(yùn)行問(wèn)題。下面是一份基于 LangChain 1.x 常見(jiàn)踩坑點(diǎn)整理的排查表問(wèn)題現(xiàn)象可能原因排查方式解決方案安裝時(shí)依賴沖突舊版 langchain 0.x 殘留包沖突pip listgrep langchain 查看殘留包ChatOpenAI導(dǎo)入失敗缺少langchain-openai子包查看報(bào)錯(cuò)信息中的缺失模塊pip install langchain-openai調(diào)用模型報(bào) 401/403API Key 錯(cuò)誤或環(huán)境變量未加載檢查.env文件是否被讀取打印環(huán)境變量確認(rèn).env路徑正確使用python-dotenv加載調(diào)用模型報(bào)超時(shí)網(wǎng)絡(luò)不通或代理設(shè)置異常用 curl 測(cè)試模型 API 連通性確認(rèn)接口地址正確配置合規(guī)網(wǎng)絡(luò)環(huán)境中文文檔檢索效果差文本切分時(shí)中文標(biāo)點(diǎn)被切斷打印切分后的 chunk 內(nèi)容在 separators 中加入中文標(biāo)點(diǎn)調(diào)整 chunk_sizeChroma 數(shù)據(jù)重復(fù)重復(fù)執(zhí)行腳本導(dǎo)致舊數(shù)據(jù)殘留查看chroma_db目錄內(nèi)容刪除本地chroma_db目錄后重新構(gòu)建Agent 不調(diào)用工具直接回答模型沒(méi)有正確綁定工具打印llm_with_tools綁定的工具列表確認(rèn)bind_tools已經(jīng)調(diào)用工具描述是否清晰Agent 無(wú)限循環(huán)調(diào)用工具缺少終止條件或工具返回異常設(shè)置 debug 模式觀察節(jié)點(diǎn)流轉(zhuǎn)在條件路由中增加最大步數(shù)限制或檢查工具異常處理工具參數(shù)解析錯(cuò)誤模型輸出的工具參數(shù)與函數(shù)簽名不匹配檢查工具函數(shù)簽名和 docstring給工具函數(shù)寫清晰的 docstring 和類型注解LCEL 鏈調(diào)用時(shí)報(bào)RunnableSequence錯(cuò)誤組件之間輸入輸出格式不匹配檢查管道中各組件期望的輸入格式在鏈中插入自定義函數(shù)轉(zhuǎn)換格式7.1 排查思路的通用原則先看鏈路不要只看報(bào)錯(cuò)。LangChain 報(bào)錯(cuò)信息可能很冗長(zhǎng)優(yōu)先定位是哪個(gè)組件拋出的異常?？梢杂胏hain.with_config({callbacks: [...]})添加回調(diào)打印中間變量。先跑最小示例。遇到問(wèn)題后把鏈路縮減到模型調(diào)用這一層確認(rèn)模型、密鑰、網(wǎng)絡(luò)沒(méi)有問(wèn)題再逐步加回 Prompt、檢索、工具。版本不一致是萬(wàn)惡之源。升級(jí)依賴后如果代碼跑不通先檢查是否 0.x 和 1.x 的 API 混用。比如langchain.chains.LLMChain在 1.x 中已經(jīng)不推薦直接使用新代碼應(yīng)該用 LCEL。Agent 問(wèn)題先看tool_calls再往下查。如果模型輸出里根本沒(méi)有tool_calls說(shuō)明問(wèn)題出在模型理解和工具描述上而不是后續(xù)節(jié)點(diǎn)。8. 生產(chǎn)環(huán)境中的最佳實(shí)踐與工程建議很多教程停在能跑通這一層但真實(shí)項(xiàng)目里跑通只代表開(kāi)始。這一節(jié)我們把 LangChain 應(yīng)用從 Demo 提升到工程級(jí)別聊一聊真正值得投入精力的地方。8.1 項(xiàng)目結(jié)構(gòu)設(shè)計(jì)按組件而非頁(yè)面組織代碼不要把代碼全部堆在一個(gè)文件里。一個(gè)可維護(hù)的 LangChain 項(xiàng)目建議這樣分層project/ ├── app/ │ ├── chains/ # 各業(yè)務(wù)鏈 │ │ ├── rag_chain.py │ │ └── agent_graph.py │ ├── tools/ # 自定義工具集 │ ├── prompts/ # Prompt 模板 │ ├── models/ # 模型實(shí)例配置 │ ├── services/ # 業(yè)務(wù)服務(wù)層 │ └── main.py # 入口 ├── config/ │ ├── settings.py # 配置讀取 │ └── .env ├── data/ # 文檔數(shù)據(jù) ├── tests/ # 單元測(cè)試 └── requirements.txt這樣設(shè)計(jì)的核心好處是Prompt、模型、工具都在獨(dú)立模塊中修改任何一個(gè)組件不需要牽連其他部分。8.2 配置管理不要把密鑰寫進(jìn)代碼嚴(yán)格遵守最小權(quán)限原則。生產(chǎn)環(huán)境的 API Key 應(yīng)該放在密鑰管理服務(wù)中開(kāi)發(fā)環(huán)境用.env文件但必須進(jìn).gitignore。配置項(xiàng)按環(huán)境區(qū)分可以用 pydantic-settings 或類似工具統(tǒng)一管理。# 文件路徑: config/settings.py from pydantic_settings import BaseSettings class Settings(BaseSettings): openai_api_key: str openai_base_url: str https://api.openai.com/v1 model_name: str gpt-4o-mini embedding_model: str text-embedding-3-small vectorstore_dir: str ./chroma_db chunk_size: int 500 chunk_overlap: int 50 retriever_k: int 4 class Config: env_file .env settings Settings()8.3 可觀測(cè)性記錄每次調(diào)用的全鏈路信息LangChain 提供了回調(diào)系統(tǒng)你可以監(jiān)聽(tīng)每個(gè)組件的開(kāi)始、結(jié)束和錯(cuò)誤事件。生產(chǎn)環(huán)境中建議至少記錄每次調(diào)用的耗時(shí)和 token 消耗輸入輸出摘要檢索出的文檔 ID 和相關(guān)性得分Agent 每一步的工具調(diào)用記錄。下面是一個(gè)簡(jiǎn)單的回調(diào)示例# 文件路徑: observability.py from langchain_core.callbacks import BaseCallbackHandler class LoggingCallbackHandler(BaseCallbackHandler): def on_llm_start(self, serialized, prompts, **kwargs): print(f[LLM 開(kāi)始] prompts{prompts}) def on_llm_end(self, response, **kwargs): print(f[LLM 結(jié)束] output{response.generations[0][0].text[:50]}) def on_tool_start(self, serialized, input_str, **kwargs): print(f[工具 開(kāi)始] tool{serialized.get(name)}, input{input_str}) def on_tool_end(self, output, **kwargs): print(f[工具 結(jié)束] output{output})然后在調(diào)用鏈時(shí)傳入from langchain_core.callbacks import CallbackManager callback_manager CallbackManager([LoggingCallbackHandler()]) result chain.invoke({question: ...}, config{callbacks: callback_manager})8.4 安全邊界LLM 應(yīng)用必須做的幾件事大模型應(yīng)用的安全和傳統(tǒng) Web 應(yīng)用不完全一樣除了常規(guī)的鑒權(quán)和防注入還要特別關(guān)注Prompt 注入防護(hù)。外部輸入可能包含惡意指令不要讓用戶輸入直接覆蓋系統(tǒng)提示詞。在工程上對(duì)系統(tǒng)消息和用戶消息做嚴(yán)格隔離必要時(shí)對(duì)用戶輸入做敏感詞過(guò)濾。工具權(quán)限最小化。給 Agent 綁定的工具只授予完成業(yè)務(wù)所需的最小權(quán)限。比如查詢數(shù)據(jù)庫(kù)的工具只能用只讀賬號(hào)不能給 drop 權(quán)限。輸出內(nèi)容審核。模型生成的輸出需要經(jīng)過(guò)合規(guī)過(guò)濾可以在鏈的末尾增加一個(gè)審核節(jié)點(diǎn)。調(diào)用頻率限制。防止用戶通過(guò)你的應(yīng)用大量消耗模型 token需要做配額控制。8.5 性能與成本優(yōu)化緩存對(duì)重復(fù)問(wèn)題做語(yǔ)義緩存。LangChain 內(nèi)置了InMemoryCache或RedisCache對(duì)高頻問(wèn)題非常有效。模型分級(jí)簡(jiǎn)單任務(wù)用gpt-4o-mini這類低成本模型復(fù)雜任務(wù)才上旗艦?zāi)Ｐ?。一個(gè)應(yīng)用可以同時(shí)配置多個(gè)模型實(shí)例按路由分發(fā)。檢索優(yōu)化RAG 的延遲瓶頸往往在向量檢索。如果檢索結(jié)果量大考慮使用MultiVectorRetriever或先做粗排再做精排。流式輸出使用.stream()方法而不是.invoke()可以顯著改善用戶等待體驗(yàn)。9. 總結(jié)與后續(xù)學(xué)習(xí)方向這篇文章從 LangChain 1.x 的框架定位講起梳理了 LangChain、LangGraph、Agent、Skill、MCP 這幾個(gè)關(guān)鍵概念的關(guān)系然后通過(guò)一個(gè)最小 LCEL 示例讓你理解新版本的核心編程范式接著用兩個(gè)完整項(xiàng)目分別演示了 RAG 問(wèn)答系統(tǒng)和基于 LangGraph 的 Agent 任務(wù)規(guī)劃。最后給出了排查清單和工程建議。你真正應(yīng)該帶走的不是代碼本身而是三個(gè)判斷LangChain 1.x 是穩(wěn)定期框架。過(guò)去那種兩個(gè)月不看就跟不上的情況已經(jīng)過(guò)去1.x 的核心 API 設(shè)計(jì)LCEL、invoke、組件化趨于穩(wěn)定值得投入學(xué)習(xí)。RAG 是入門 LangChain 的最短路徑。它鏈路完整、見(jiàn)效快、不需要復(fù)雜的編排知識(shí)適合作為第一個(gè)動(dòng)手項(xiàng)目。復(fù)雜 Agent 請(qǐng)直接學(xué) LangGraph。不要花時(shí)間研究 0.x 時(shí)代的 AgentExecutor 寫法那是已經(jīng)被官方邊緣化的舊模式。LangGraph 的狀態(tài)圖思維不只適用于 Agent也適用于所有需要流程控制的大模型應(yīng)用。下一步的實(shí)踐建議按順序做把上面的 RAG 項(xiàng)目換成本領(lǐng)域的技術(shù)文檔試試文檔質(zhì)量對(duì)回答效果的影響給 Agent 增加一個(gè)你工作中真正需要的工具比如查數(shù)據(jù)庫(kù)、調(diào)內(nèi)部 API在項(xiàng)目里加上回調(diào)日志和簡(jiǎn)單的 token 統(tǒng)計(jì)開(kāi)始培養(yǎng)可觀測(cè)性意識(shí)學(xué)習(xí) LangGraph 的checkpoint機(jī)制給你的 Agent 加上多輪記憶。最后補(bǔ)充一點(diǎn)網(wǎng)上關(guān)于 LangChain 過(guò)時(shí)的討論非常多但絕大多數(shù)是標(biāo)題黨?？蚣芸梢該Q代但用組件編排大模型應(yīng)用這套工程思想不會(huì)過(guò)期。真正值得你長(zhǎng)期投入的是理解模型應(yīng)用的分層架構(gòu)、接口抽象和狀態(tài)流控制——這些能力換任何框架都適用。