1. 先搞清楚 LangChain 这套东西到底在解决什么问题如果你正在看这篇文章大概率是听说了 LangChain 能搞 AI 应用但被 Agent、RAG、MCP、LangGraph 这些词绕晕了不知道从哪下手。我直接说结论LangChain 的核心价值是帮你把大语言模型LLM从一个“聊天机器人”变成一个能稳定执行复杂业务流程的“自动化员工”。别被“企业级项目实战”这种词吓到。说白了就是你想让 AI 不只是回答问题而是能按你的指令去查资料、做计算、调接口、写代码、处理文件并且这些步骤能串起来、有状态、能回溯。这就是 LangChain 要干的事。Agent 是让 AI 自己决定用什么工具RAG 是让 AI 能回答它“没学过”的知识MCP 是定义工具的标准接口LangGraph 是把多个 AI 或工具调用编排成一个有状态的工作流。一周学完坦白说如果你有 Python 基础一周把核心概念和基础流程跑通完全可能。但想“吃透”取决于你用它做什么。这篇文章的目标就是帮你跳过那些概念空转直接进入“能用、能调、能排查”的实操状态把 99% 的弯路变成几条清晰的检查清单。2. 环境准备别在配置上卡一整天在写第一行 LangChain 代码之前先把环境理顺。很多“跑不起来”的问题都出在这里。2.1 基础环境与依赖首先你需要一个能运行 Python 的环境。我强烈建议使用Python 3.10 或 3.11。LangChain 社区对新版本 Python 的跟进很快但 3.10/3.11 是目前兼容性最广、最稳定的选择。用 Conda 或 venv 创建独立的虚拟环境是必须的避免包冲突。核心的安装命令很简单pip install langchain langchain-community但请注意langchain是一个“元包”它声明了很多子包作为依赖。在生产环境中更推荐根据你的需求精确安装所需的组件例如pip install langchain-core langchain-openai langchain-chroma这能更好地控制依赖版本。2.2 大模型接入钥匙在哪LangChain 本身不提供模型它是个“连接器”。你需要一个 LLM 的 API Key。对于初学者OpenAI 的 GPT 系列通过langchain-openai或 Anthropic 的 Claude通过langchain-anthropic是起点最平滑的选择因为它们的接口稳定LangChain 集成度最高。准备好你的 API Key并设置环境变量export OPENAI_API_KEYyour-key-here # 或者在代码中直接设置关键点国内用户需要注意网络连通性。确保你的运行环境能够稳定访问你选择的模型服务商 API。这是后续所有步骤的前提如果这里不通后面全是徒劳。2.3 工具与向量数据库按需选配这是最容易让人困惑的地方感觉什么都要装。其实初期你只需要关注两样一个简单的工具比如用于数学计算的langchain_experimental.utilities.PythonREPL或者搜索工具需要额外 API Key如 Tavily。先用一个工具来验证 Agent 能跑通。一个本地的向量数据库如果你要玩 RAG。学习阶段ChromaDB是最佳选择因为它无需服务器内存模式一键启动。pip install chromadb它的数据可以持久化到磁盘足够应对 demo 和小型项目。把环境清单理清楚Python 3.10虚拟环境Conda/venvlangchain-core,langchain-openai等核心包有效的 LLM API Key 及网络(可选) ChromaDB(可选) 一个示例工具包先别想着把所有热搜词对应的包都装上。从最小可运行环境开始。3. 从 LangChain 到 LangGraph核心概念落地实操现在我们来拆解这几个核心概念并用最简代码说明它们怎么用。3.1 Agent让 LLM 学会“用工具”Agent 不是魔法。它的本质是LLM 提示词决定何时用工具 工具列表 执行循环。一个最简单的 ReAct 范式 Agent 示例from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_react_agent from langchain.tools import Tool from langchain import hub # 1. 定义工具一个模拟的计算器 def calculate(expression: str) - str: 计算一个数学表达式。 try: return str(eval(expression)) except: return “计算错误” calc_tool Tool( name“Calculator”, funccalculate, description“用于计算数学表达式例如 ‘(3 5) * 2’” ) # 2. 准备 LLM 和提示词 llm ChatOpenAI(model“gpt-3.5-turbo”, temperature0) prompt hub.pull(“hwchase17/react”) # 从 LangChain Hub 拉取标准 ReAct 提示词 # 3. 创建 Agent 和执行器 agent create_react_agent(llm, tools[calc_tool], promptprompt) agent_executor AgentExecutor(agentagent, tools[calc_tool], verboseTrue) # 4. 运行 result agent_executor.invoke({“input”: “如果我有17个苹果吃了5个又买了3打我现在总共有多少个苹果”}) print(result[“output”])发生了什么LLM 看到问题意识到需要计算。它生成一个类似Action: Calculator, Action Input: (17 - 5) 3*12的思考。Agent 框架执行工具得到结果48。将结果返回给 LLMLLM 组织最终答案。关键理解AgentExecutor负责管理这个“思考-行动-观察”的循环。verboseTrue会让你看到整个过程对于调试至关重要。3.2 RAG给 LLM 装上“外部知识库”RAG 的流程比想象中直接灌文档 - 切块 - 存向量 - 问问题 - 搜相关块 - 组合答案。from langchain_openai import OpenAIEmbeddings, ChatOpenAI from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_chroma import Chroma from langchain.chains import RetrievalQA # 1. 加载并分割文档 loader TextLoader(“./my_doc.txt”) # 你的知识文档 documents loader.load() text_splitter RecursiveCharacterTextSplitter(chunk_size500, chunk_overlap50) texts text_splitter.split_documents(documents) # 2. 嵌入并存入向量库 embeddings OpenAIEmbeddings() # 需要 OPENAI_API_KEY vectorstore Chroma.from_documents(documentstexts, embeddingembeddings, persist_directory“./chroma_db”) retriever vectorstore.as_retriever() # 3. 创建问答链 llm ChatOpenAI(model“gpt-3.5-turbo”, temperature0) qa_chain RetrievalQA.from_chain_type(llmllm, chain_type“stuff”, retrieverretriever) # 4. 提问 answer qa_chain.invoke({“query”: “根据文档项目的主要目标是什么”}) print(answer[“result”])避坑点分块大小chunk_size不是越大越好。太小丢失上下文太大检索不准。从 500 开始调整。嵌入模型必须与检索时使用的模型一致。这里都用OpenAIEmbeddings。检索器retrieveras_retriever(search_kwargs{“k”: 4})可以控制返回几个相关块。chain_type“stuff”最简单把所有检索到的文本塞给 LLM。如果文本很长考虑“map_reduce”或“refine”。RAG 的效果上限一半取决于你的文档预处理分块、清洗另一半取决于检索质量。不要指望把乱七八糟的文档扔进去就能得到完美答案。3.3 MCP工具定义的“通用插座”MCPModel Context Protocol可以理解为工具定义的标准化协议。它的目的是让任何符合 MCP 标准的工具都能轻松接入 LangChain、Claude Desktop 等支持 MCP 的客户端。你暂时可以不用深入实现 MCP Server。但要知道当你看到TavilySearchResults这样的工具时它背后可能就是一个 MCP 兼容的工具。对于开发者MCP 的意义在于如果你要提供一个可被 AI 调用的服务如查询公司内部数据库按照 MCP 标准来构建就能获得最广泛的兼容性。现阶段作为 LangChain 使用者你更多是消费MCP 工具。例如通过langchain-mcp-adapters来集成 MCP 工具。3.4 LangGraph把任务流“画”出来这是 LangChain 生态中用于构建有状态、多环节、可循环工作流的库。如果说基础的AgentExecutor是一个自动的思考循环那么 LangGraph 就是让你能手动设计这个循环的蓝图支持更复杂的拓扑结构分支、并行、循环。一个超级简单的“审批流程”示例from typing import TypedDict, Annotated from langgraph.graph import StateGraph, END from langchain_openai import ChatOpenAI # 1. 定义状态State class ApprovalState(TypedDict): application: str review_comment: Annotated[str, “add”] # 这是一个“追加”字段 approved: bool # 2. 定义节点函数 def reviewer_node(state: ApprovalState): llm ChatOpenAI(model“gpt-3.5-turbo”) # 模拟审核逻辑 message llm.invoke(f“请审核以下申请给出简要意见{state[‘application’]}”) return {“review_comment”: message.content} def decision_node(state: ApprovalState): # 根据审核意见做决定这里简化逻辑 if “符合” in state[“review_comment”]: return {“approved”: True} else: return {“approved”: False} # 3. 构建图 workflow StateGraph(ApprovalState) workflow.add_node(“reviewer”, reviewer_node) workflow.add_node(“decision”, decision_node) # 4. 设置边流程走向 workflow.set_entry_point(“reviewer”) workflow.add_edge(“reviewer”, “decision”) workflow.add_edge(“decision”, END) # 5. 编译并运行 app workflow.compile() initial_state {“application”: “申请购买一台高性能服务器” “review_comment”: “” “approved”: False} result app.invoke(initial_state) print(f“审核意见{result[‘review_comment’]}\n是否批准{result[‘approved’]}”)LangGraph 的核心思想状态State一个贯穿流程的共享字典。每个节点读取和更新它。节点Node一个普通的函数处理业务逻辑。边Edge决定下一个执行哪个节点。可以是条件边add_conditional_edges。编译Compile把图结构变成一个可执行的Graph对象。什么时候用 LangGraph当你的 Agent 需要多个 LLM 调用按特定顺序协作或者流程中存在“循环”例如工具执行结果不满足要求需要重新思考时。基础的AgentExecutor已经内置了 ReAct 循环但 LangGraph 给了你完全的控制权。4. 企业级实战思维从 Demo 到可靠系统的关键跨越能跑通 Demo 只是第一步。要把这些东西用于实际项目必须转换思维。下面这些点是新手和老手的核心区别。4.1 设计模式不是所有场景都需要 Agent不要手里有把锤子看什么都像钉子。简单检索问答直接用RetrievalQA链稳定可控。固定流程的数据处理用SequentialChain或自定义Runnable序列。需要动态决策、使用多种工具用Agent。复杂、多角色、有状态的长流程用LangGraph。经验法则从最简单的链开始只有当逻辑无法用固定流程表达时才考虑引入 Agent 的“决策”能力。Agent 的不可预测性和开销更多 Token、更多调用都更高。4.2 稳定性与监控给 AI 应用装上“仪表盘”AI 应用的不稳定性主要来自 LLM 输出的随机性和工具调用的失败。结构化输出尽可能让 LLM 输出 JSON 等格式用PydanticOutputParser进行解析和校验。超时与重试为工具调用和 LLM 调用设置超时。使用tenacity库实现指数退避重试。Fallback 策略当主模型如 GPT-4调用失败或超时时自动降级到备用模型如 GPT-3.5。日志与追踪集成LangSmith。这是 LangChain 官方的监控平台。它能记录每一次链、Agent、工具的调用详情包括输入、输出、耗时、Token 用量。这是排查“为什么这次回答不对”的终极武器。在代码中加几行配置即可启用。4.3 性能与成本优化缓存对相同的输入使用InMemoryCache或SQLiteCache缓存 LLM 响应能极大节省成本和时间。批处理对于大量独立的文档处理或问答使用batch或abatch异步批处理方法。Token 管理在构建提示词时注意上下文长度。对于长文档 RAG使用能处理长上下文的模型如 GPT-4 Turbo 128K或采用Map-Reduce等链类型。向量检索优化调整retriever的search_type如mmr最大边际相关性搜索可以平衡相关性和多样性和k值。4.4 部署与集成API 服务使用FastAPI将你的 LangChain 应用包装成 HTTP API。注意处理好异步、并发和生命周期。结构化项目不要把所有代码写在一个文件里。将工具定义、链/图构建、业务逻辑分层。my_agent_project/ ├── tools/ # 自定义工具 ├── chains/ # 各种链 ├── graphs/ # LangGraph 工作流定义 ├── schemas/ # Pydantic 模型 ├── api/ # FastAPI 路由 └── config.py # 配置管理配置管理使用pydantic-settings管理 API Key、模型名称等配置通过环境变量加载。5. 高频问题与排查清单当你遇到问题时按这个顺序查。5.1 Agent 不动或乱用工具检查点1工具描述description。LLM 完全靠这个决定是否调用工具。描述必须清晰、准确包含关键词。例如一个处理 CSV 的工具描述里要有“CSV”、“文件”、“读取”、“行”、“列”等词。检查点2提示词prompt。你是否使用了合适的 Agent 类型ReAct, OpenAI Tools, etc.尝试从hub.pull拉取官方标准提示词作为基线。检查点3verboseTrue。打开详细输出看 LLM 的思考过程Thought。如果Thought里根本没提工具说明提示词或工具描述有问题。如果Action错了说明工具描述不匹配或 LLM 理解偏差。检查点4LLM 温度temperature。在 Agent 场景下通常设为0或接近0以减少随机性让决策更稳定。5.2 RAG 答案质量差检查点1检索结果。首先单独测试检索器docs retriever.get_relevant_documents(“你的问题”)。看看返回的文档块是否真的相关。如果不相关问题在前段。前段问题排查文档分块chunk_size是否合适尝试 200 500 1000 进行对比。嵌入模型是否使用了强语义理解能力的模型不同模型效果差异巨大。检索策略尝试search_type“mmr”并调整fetch_k参数。后段问题排查如果检索结果相关但最终答案不好问题在后段。提示词你的RetrievalQA是否使用了自定义提示词来指导 LLM 如何利用上下文默认提示词可能不够强。上下文长度检索到的文本总长度是否超过了 LLM 的上下文窗口考虑使用chain_type“map_reduce”。LLM 本身能力尝试换一个更强的模型如从 gpt-3.5-turbo 切换到 gpt-4。5.3 LangGraph 状态流转错误检查点1状态StateSchema。确保每个节点函数读取和写入的字段都在TypedDict中正确定义。Annotated注解如add用于指定字段的更新方式追加、替换等。检查点2边Edge逻辑。条件边add_conditional_edges的判断函数必须返回下一个节点的名称或END。用print调试这个判断函数的返回值。检查点3可视化。使用app.get_graph().draw_mermaid_png()生成流程图直观检查你的图结构是否正确。5.4 通用错误与慢速API Rate Limit/Timeout这是最常见错误。实现重试机制和降级策略。降低并发请求数。InvalidRequestError(context length)提示词上下文超长了。优化提示词减少无关信息或使用支持更长上下文的模型。速度慢首先用 LangSmith 或简单计时定位是哪个环节慢LLM 调用、工具调用、检索。LLM 慢考虑换模型或启用缓存工具慢优化工具本身检索慢考虑向量索引优化如使用 HNSW 索引。最后记住一个核心原则LangChain 是一个强大的“胶水”框架但它不解决你工具本身的质量问题也不解决你提示词设计的问题更不解决你数据质量的问题。它的价值在于把这些环节标准化、流程化、可监控化。先用手动流程验证你的想法是通的再用 LangChain 把它自动化、健壮化。这条路就走对了。 LangChain实战指南：从Agent、RAG到LangGraph构建企业级AI应用
1. 先搞清楚 LangChain 这套东西到底在解决什么问题如果你正在看这篇文章大概率是听说了 LangChain 能搞 AI 应用但被 Agent、RAG、MCP、LangGraph 这些词绕晕了不知道从哪下手。我直接说结论LangChain 的核心价值是帮你把大语言模型LLM从一个“聊天机器人”变成一个能稳定执行复杂业务流程的“自动化员工”。别被“企业级项目实战”这种词吓到。说白了就是你想让 AI 不只是回答问题而是能按你的指令去查资料、做计算、调接口、写代码、处理文件并且这些步骤能串起来、有状态、能回溯。这就是 LangChain 要干的事。Agent 是让 AI 自己决定用什么工具RAG 是让 AI 能回答它“没学过”的知识MCP 是定义工具的标准接口LangGraph 是把多个 AI 或工具调用编排成一个有状态的工作流。一周学完坦白说如果你有 Python 基础一周把核心概念和基础流程跑通完全可能。但想“吃透”取决于你用它做什么。这篇文章的目标就是帮你跳过那些概念空转直接进入“能用、能调、能排查”的实操状态把 99% 的弯路变成几条清晰的检查清单。2. 环境准备别在配置上卡一整天在写第一行 LangChain 代码之前先把环境理顺。很多“跑不起来”的问题都出在这里。2.1 基础环境与依赖首先你需要一个能运行 Python 的环境。我强烈建议使用Python 3.10 或 3.11。LangChain 社区对新版本 Python 的跟进很快但 3.10/3.11 是目前兼容性最广、最稳定的选择。用 Conda 或 venv 创建独立的虚拟环境是必须的避免包冲突。核心的安装命令很简单pip install langchain langchain-community但请注意langchain是一个“元包”它声明了很多子包作为依赖。在生产环境中更推荐根据你的需求精确安装所需的组件例如pip install langchain-core langchain-openai langchain-chroma这能更好地控制依赖版本。2.2 大模型接入钥匙在哪LangChain 本身不提供模型它是个“连接器”。你需要一个 LLM 的 API Key。对于初学者OpenAI 的 GPT 系列通过langchain-openai或 Anthropic 的 Claude通过langchain-anthropic是起点最平滑的选择因为它们的接口稳定LangChain 集成度最高。准备好你的 API Key并设置环境变量export OPENAI_API_KEYyour-key-here # 或者在代码中直接设置关键点国内用户需要注意网络连通性。确保你的运行环境能够稳定访问你选择的模型服务商 API。这是后续所有步骤的前提如果这里不通后面全是徒劳。2.3 工具与向量数据库按需选配这是最容易让人困惑的地方感觉什么都要装。其实初期你只需要关注两样一个简单的工具比如用于数学计算的langchain_experimental.utilities.PythonREPL或者搜索工具需要额外 API Key如 Tavily。先用一个工具来验证 Agent 能跑通。一个本地的向量数据库如果你要玩 RAG。学习阶段ChromaDB是最佳选择因为它无需服务器内存模式一键启动。pip install chromadb它的数据可以持久化到磁盘足够应对 demo 和小型项目。把环境清单理清楚Python 3.10虚拟环境Conda/venvlangchain-core,langchain-openai等核心包有效的 LLM API Key 及网络(可选) ChromaDB(可选) 一个示例工具包先别想着把所有热搜词对应的包都装上。从最小可运行环境开始。3. 从 LangChain 到 LangGraph核心概念落地实操现在我们来拆解这几个核心概念并用最简代码说明它们怎么用。3.1 Agent让 LLM 学会“用工具”Agent 不是魔法。它的本质是LLM 提示词决定何时用工具 工具列表 执行循环。一个最简单的 ReAct 范式 Agent 示例from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_react_agent from langchain.tools import Tool from langchain import hub # 1. 定义工具一个模拟的计算器 def calculate(expression: str) - str: 计算一个数学表达式。 try: return str(eval(expression)) except: return “计算错误” calc_tool Tool( name“Calculator”, funccalculate, description“用于计算数学表达式例如 ‘(3 5) * 2’” ) # 2. 准备 LLM 和提示词 llm ChatOpenAI(model“gpt-3.5-turbo”, temperature0) prompt hub.pull(“hwchase17/react”) # 从 LangChain Hub 拉取标准 ReAct 提示词 # 3. 创建 Agent 和执行器 agent create_react_agent(llm, tools[calc_tool], promptprompt) agent_executor AgentExecutor(agentagent, tools[calc_tool], verboseTrue) # 4. 运行 result agent_executor.invoke({“input”: “如果我有17个苹果吃了5个又买了3打我现在总共有多少个苹果”}) print(result[“output”])发生了什么LLM 看到问题意识到需要计算。它生成一个类似Action: Calculator, Action Input: (17 - 5) 3*12的思考。Agent 框架执行工具得到结果48。将结果返回给 LLMLLM 组织最终答案。关键理解AgentExecutor负责管理这个“思考-行动-观察”的循环。verboseTrue会让你看到整个过程对于调试至关重要。3.2 RAG给 LLM 装上“外部知识库”RAG 的流程比想象中直接灌文档 - 切块 - 存向量 - 问问题 - 搜相关块 - 组合答案。from langchain_openai import OpenAIEmbeddings, ChatOpenAI from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_chroma import Chroma from langchain.chains import RetrievalQA # 1. 加载并分割文档 loader TextLoader(“./my_doc.txt”) # 你的知识文档 documents loader.load() text_splitter RecursiveCharacterTextSplitter(chunk_size500, chunk_overlap50) texts text_splitter.split_documents(documents) # 2. 嵌入并存入向量库 embeddings OpenAIEmbeddings() # 需要 OPENAI_API_KEY vectorstore Chroma.from_documents(documentstexts, embeddingembeddings, persist_directory“./chroma_db”) retriever vectorstore.as_retriever() # 3. 创建问答链 llm ChatOpenAI(model“gpt-3.5-turbo”, temperature0) qa_chain RetrievalQA.from_chain_type(llmllm, chain_type“stuff”, retrieverretriever) # 4. 提问 answer qa_chain.invoke({“query”: “根据文档项目的主要目标是什么”}) print(answer[“result”])避坑点分块大小chunk_size不是越大越好。太小丢失上下文太大检索不准。从 500 开始调整。嵌入模型必须与检索时使用的模型一致。这里都用OpenAIEmbeddings。检索器retrieveras_retriever(search_kwargs{“k”: 4})可以控制返回几个相关块。chain_type“stuff”最简单把所有检索到的文本塞给 LLM。如果文本很长考虑“map_reduce”或“refine”。RAG 的效果上限一半取决于你的文档预处理分块、清洗另一半取决于检索质量。不要指望把乱七八糟的文档扔进去就能得到完美答案。3.3 MCP工具定义的“通用插座”MCPModel Context Protocol可以理解为工具定义的标准化协议。它的目的是让任何符合 MCP 标准的工具都能轻松接入 LangChain、Claude Desktop 等支持 MCP 的客户端。你暂时可以不用深入实现 MCP Server。但要知道当你看到TavilySearchResults这样的工具时它背后可能就是一个 MCP 兼容的工具。对于开发者MCP 的意义在于如果你要提供一个可被 AI 调用的服务如查询公司内部数据库按照 MCP 标准来构建就能获得最广泛的兼容性。现阶段作为 LangChain 使用者你更多是消费MCP 工具。例如通过langchain-mcp-adapters来集成 MCP 工具。3.4 LangGraph把任务流“画”出来这是 LangChain 生态中用于构建有状态、多环节、可循环工作流的库。如果说基础的AgentExecutor是一个自动的思考循环那么 LangGraph 就是让你能手动设计这个循环的蓝图支持更复杂的拓扑结构分支、并行、循环。一个超级简单的“审批流程”示例from typing import TypedDict, Annotated from langgraph.graph import StateGraph, END from langchain_openai import ChatOpenAI # 1. 定义状态State class ApprovalState(TypedDict): application: str review_comment: Annotated[str, “add”] # 这是一个“追加”字段 approved: bool # 2. 定义节点函数 def reviewer_node(state: ApprovalState): llm ChatOpenAI(model“gpt-3.5-turbo”) # 模拟审核逻辑 message llm.invoke(f“请审核以下申请给出简要意见{state[‘application’]}”) return {“review_comment”: message.content} def decision_node(state: ApprovalState): # 根据审核意见做决定这里简化逻辑 if “符合” in state[“review_comment”]: return {“approved”: True} else: return {“approved”: False} # 3. 构建图 workflow StateGraph(ApprovalState) workflow.add_node(“reviewer”, reviewer_node) workflow.add_node(“decision”, decision_node) # 4. 设置边流程走向 workflow.set_entry_point(“reviewer”) workflow.add_edge(“reviewer”, “decision”) workflow.add_edge(“decision”, END) # 5. 编译并运行 app workflow.compile() initial_state {“application”: “申请购买一台高性能服务器” “review_comment”: “” “approved”: False} result app.invoke(initial_state) print(f“审核意见{result[‘review_comment’]}\n是否批准{result[‘approved’]}”)LangGraph 的核心思想状态State一个贯穿流程的共享字典。每个节点读取和更新它。节点Node一个普通的函数处理业务逻辑。边Edge决定下一个执行哪个节点。可以是条件边add_conditional_edges。编译Compile把图结构变成一个可执行的Graph对象。什么时候用 LangGraph当你的 Agent 需要多个 LLM 调用按特定顺序协作或者流程中存在“循环”例如工具执行结果不满足要求需要重新思考时。基础的AgentExecutor已经内置了 ReAct 循环但 LangGraph 给了你完全的控制权。4. 企业级实战思维从 Demo 到可靠系统的关键跨越能跑通 Demo 只是第一步。要把这些东西用于实际项目必须转换思维。下面这些点是新手和老手的核心区别。4.1 设计模式不是所有场景都需要 Agent不要手里有把锤子看什么都像钉子。简单检索问答直接用RetrievalQA链稳定可控。固定流程的数据处理用SequentialChain或自定义Runnable序列。需要动态决策、使用多种工具用Agent。复杂、多角色、有状态的长流程用LangGraph。经验法则从最简单的链开始只有当逻辑无法用固定流程表达时才考虑引入 Agent 的“决策”能力。Agent 的不可预测性和开销更多 Token、更多调用都更高。4.2 稳定性与监控给 AI 应用装上“仪表盘”AI 应用的不稳定性主要来自 LLM 输出的随机性和工具调用的失败。结构化输出尽可能让 LLM 输出 JSON 等格式用PydanticOutputParser进行解析和校验。超时与重试为工具调用和 LLM 调用设置超时。使用tenacity库实现指数退避重试。Fallback 策略当主模型如 GPT-4调用失败或超时时自动降级到备用模型如 GPT-3.5。日志与追踪集成LangSmith。这是 LangChain 官方的监控平台。它能记录每一次链、Agent、工具的调用详情包括输入、输出、耗时、Token 用量。这是排查“为什么这次回答不对”的终极武器。在代码中加几行配置即可启用。4.3 性能与成本优化缓存对相同的输入使用InMemoryCache或SQLiteCache缓存 LLM 响应能极大节省成本和时间。批处理对于大量独立的文档处理或问答使用batch或abatch异步批处理方法。Token 管理在构建提示词时注意上下文长度。对于长文档 RAG使用能处理长上下文的模型如 GPT-4 Turbo 128K或采用Map-Reduce等链类型。向量检索优化调整retriever的search_type如mmr最大边际相关性搜索可以平衡相关性和多样性和k值。4.4 部署与集成API 服务使用FastAPI将你的 LangChain 应用包装成 HTTP API。注意处理好异步、并发和生命周期。结构化项目不要把所有代码写在一个文件里。将工具定义、链/图构建、业务逻辑分层。my_agent_project/ ├── tools/ # 自定义工具 ├── chains/ # 各种链 ├── graphs/ # LangGraph 工作流定义 ├── schemas/ # Pydantic 模型 ├── api/ # FastAPI 路由 └── config.py # 配置管理配置管理使用pydantic-settings管理 API Key、模型名称等配置通过环境变量加载。5. 高频问题与排查清单当你遇到问题时按这个顺序查。5.1 Agent 不动或乱用工具检查点1工具描述description。LLM 完全靠这个决定是否调用工具。描述必须清晰、准确包含关键词。例如一个处理 CSV 的工具描述里要有“CSV”、“文件”、“读取”、“行”、“列”等词。检查点2提示词prompt。你是否使用了合适的 Agent 类型ReAct, OpenAI Tools, etc.尝试从hub.pull拉取官方标准提示词作为基线。检查点3verboseTrue。打开详细输出看 LLM 的思考过程Thought。如果Thought里根本没提工具说明提示词或工具描述有问题。如果Action错了说明工具描述不匹配或 LLM 理解偏差。检查点4LLM 温度temperature。在 Agent 场景下通常设为0或接近0以减少随机性让决策更稳定。5.2 RAG 答案质量差检查点1检索结果。首先单独测试检索器docs retriever.get_relevant_documents(“你的问题”)。看看返回的文档块是否真的相关。如果不相关问题在前段。前段问题排查文档分块chunk_size是否合适尝试 200 500 1000 进行对比。嵌入模型是否使用了强语义理解能力的模型不同模型效果差异巨大。检索策略尝试search_type“mmr”并调整fetch_k参数。后段问题排查如果检索结果相关但最终答案不好问题在后段。提示词你的RetrievalQA是否使用了自定义提示词来指导 LLM 如何利用上下文默认提示词可能不够强。上下文长度检索到的文本总长度是否超过了 LLM 的上下文窗口考虑使用chain_type“map_reduce”。LLM 本身能力尝试换一个更强的模型如从 gpt-3.5-turbo 切换到 gpt-4。5.3 LangGraph 状态流转错误检查点1状态StateSchema。确保每个节点函数读取和写入的字段都在TypedDict中正确定义。Annotated注解如add用于指定字段的更新方式追加、替换等。检查点2边Edge逻辑。条件边add_conditional_edges的判断函数必须返回下一个节点的名称或END。用print调试这个判断函数的返回值。检查点3可视化。使用app.get_graph().draw_mermaid_png()生成流程图直观检查你的图结构是否正确。5.4 通用错误与慢速API Rate Limit/Timeout这是最常见错误。实现重试机制和降级策略。降低并发请求数。InvalidRequestError(context length)提示词上下文超长了。优化提示词减少无关信息或使用支持更长上下文的模型。速度慢首先用 LangSmith 或简单计时定位是哪个环节慢LLM 调用、工具调用、检索。LLM 慢考虑换模型或启用缓存工具慢优化工具本身检索慢考虑向量索引优化如使用 HNSW 索引。最后记住一个核心原则LangChain 是一个强大的“胶水”框架但它不解决你工具本身的质量问题也不解决你提示词设计的问题更不解决你数据质量的问题。它的价值在于把这些环节标准化、流程化、可监控化。先用手动流程验证你的想法是通的再用 LangChain 把它自动化、健壮化。这条路就走对了。