如果你想学 LangChain但只是打算照抄别人的代码这篇文章可能不太适合你。如果你想搞明白 LangChain 的 Model、Chain、Agent 到底是什么、为什么要这样设计、如何从零动手搭一个能查天气、能算数、能回答问题的 AI 智能应用那么这篇文章值得你从头读到尾。我见过不少初学者卡在两个地方第一环境装好了模型也调通了但一接触 Agent 就懵不知道为什么一句话就能让模型自己去调用工具第二照着网上的旧教程写代码发现 API 已经变了报错信息也看不懂最后只能放弃。LangChain 本身的学习难度并不高真正难的是它的版本迭代比较快而且官方对“标准写法”的定义也在不断调整。如果你不理解核心设计只盯着 API 用法很容易一直处于“在追新版本”的状态。这篇文章会给你一条相对完整的路线从最基础的“调用一个模型”开始到用 Prompt 模板封装提示词再到搭建一个能调用外部工具的 Agent最后输出一个完整可运行的项目并附上常见报错排查表。读完以后你可以自己判断什么时候用 Chain 就够什么时候必须上 Agent什么时候应该去学 LangGraph。1. 这篇文章真正要解决的问题先说结论LangChain 不是大模型本身也不是深度学习框架而是“大模型应用开发框架”。它的核心价值是把调用模型、写提示词、接外部工具、管理对话记忆这些事情从零散的裸代码封装成一套可以复用、可以组合的组件。很多人学 LangChain 失败不是因为智商而是因为选题。一上来就学 Agent 高级编排前置概念还没搞懂或者反过来只学会了最基础的model.invoke()以为这就是全部后面不知道往哪走。这篇文章用一条主线把问题串起来先理解概念再跑通代码最后搞清楚每种写法适合什么场景。读完这篇文章你会获得三个可以复用的能力能独立配置 Python 环境跑通 LangChain 的模型调用。能理解 Chain 和 Agent 的边界知道什么场景该用哪一种。能照着一个完整的示例搭出带工具调用的 Agent 应用并且具备最基本的报错排查能力。文章里所有代码都遵循一个原则能用最小代码跑通就不引入多余依赖。你不需要先成为 Prompt 工程专家也不需要精通大模型原理只要会基础的 Python 语法就可以跟上。2. LangChain 核心概念Model、Chain、Agent 到底是什么2.1 用一句话理解 LangChain如果没有 LangChain你要开发一个 AI 对话功能通常要做的事情包括请求模型服务商接口、拼接 Prompt、处理返回结果、记录对话历史、接入业务 API、处理错误重试。这些工作每家团队都要重复做一遍而且写法五花八门。LangChain 做的事情就是把上述通用能力抽象成组件。你只需要选择模型、定义 Prompt、写清工具剩下的组装交给框架。类比一下PyTorch 是深度学习的训练框架vLLM 是大模型的推理加速引擎LangChain 是大模型应用的“编排层”。三者不属于同一个层面并不存在“哪个更好”的问题。2.2 ModelAI 应用的“大脑”Model 指的就是大语言模型本身常见的有 OpenAI 的 GPT 系列、DeepSeek、通义千问、智谱 GLM 等。LangChain 通过统一的接口封装不同模型服务商让你在切换模型时只需要改配置不需要改业务逻辑。这里有个零基础读者最容易误解的地方LangChain 不等于某个模型它不会自带模型能力它只是帮你把模型“接进”应用里。你依然需要申请模型服务的 API Key并按服务商的规则使用。2.3 Prompt告诉模型怎么干活Prompt 是你写给模型的指令。同样是“帮我写个 Python 脚本”不同 Prompt 模板得到的回答质量可能差很远。LangChain 里用 PromptTemplate 管理 Prompt可以把动态参数插入模板。实际项目中Prompt 不是一次写好的而是要像代码一样持续迭代。2.4 Chain把多步操作串成流水线Chain 可以理解成“流水线”。从用户输入开始经过 Prompt 拼接、模型调用、结果解析、再加工最终输出。LangChain 的 LCEL 表达式用|符号把多个步骤串起来语法上接近 Unix 管道命令学习成本很低。Chain 适合“流程固定”的场景。比如一个翻译接口输入、模板、模型、输出链路确定不需要模型去思考“下一步该做什么”。这种情况下用 Chain 就够了没必要上 Agent。2.5 Agent让模型自己决定下一步做什么Agent 和 Chain 最大的区别是“决策权”。Chain 的流程是开发者写死的先做什么后做什么由代码决定Agent 的流程由模型自己决定模型根据用户问题判断需不需要调用工具、调用哪个工具、解析工具结果后继续回答。一个 Agent 有三个核心组成部分组成部分通俗理解在 LangChain 中的角色LLM大脑负责理解、判断、决策Tool手脚Agent 能调用的外部能力如查天气、查数据库Prompt工作手册约束 Agent 行为例如“必须用工具回答问题”2.6 LangChain 和 LangGraph 是什么关系这是新手最容易搞混的问题。简单说LangChain 提供组件LangGraph 提供“图执行引擎”。如果你只是在搭固定流程用 LangChain 足够如果你的 Agent 需要循环、条件分支、人工审核节点、多角色协作LangGraph 更合适。这种设计不是重复造轮子。LangChain 更偏“声明式”适合把步骤固定下来的过程LangGraph 更偏“命令式”可以把 Agent 每一步的执行状态落到图结构里方便追踪、打断和恢复。对比项LangChainLangGraph定位组件库 可组合调用有状态执行图适合场景固定链路、快速原型分支、循环、人工介入的复杂 Agent可控性链路上限比较明显每个步骤可控、可追踪学习曲线偏易偏陡3. 环境准备与前置条件3.1 需要准备什么在开始写代码之前先把环境准备好。你需要以下几样东西Python 3.10 或更高版本建议使用较新的稳定版。pip 包管理工具一般安装 Python 时自带。一个模型服务商的 API Key。一个能正常访问模型服务接口的网络环境。这里解释一下为什么需要 API KeyLangChain 本身是开源的但底层调用的模型服务不是免费的绝大多数服务商需要注册账号并创建 Key。文章中的代码使用 OpenAI 兼容接口的写法也就是说只要你的模型服务商支持 OpenAI 兼容格式都可以套用。3.2 创建项目与虚拟环境建议每个项目都建独立虚拟环境避免依赖冲突。打开终端执行mkdir langchain-demo cd langchain-demo python -m venv .venv source .venv/bin/activateWindows 命令行下激活命令是.venv\Scripts\activate。激活成功后命令行前面会出现(.venv)前缀。3.3 安装依赖pip install langchain langchain-openai langgraph python-dotenv这里简单说明每个包的作用langchain核心框架。langchain-openaiOpenAI 兼容接口的适配器。langgraphLangChain 官方推荐的 Agent 执行引擎本文的 Agent 示例会用到它。python-dotenv读取.env配置文件。版本方面请以官方最新发布版本为准本文代码基于目前主流的 API 编写重点演示的是设计思路。3.4 配置环境变量在项目根目录创建.env文件# 文件路径.env LLM_API_KEY你的API_Key LLM_MODELdeepseek-chat LLM_BASE_URLhttps://api.deepseek.com/v1注意不同服务商的base_url和模型名不一样请以服务商文档为准。.env文件不要提交到 Git建议加入.gitignore。# 文件路径.gitignore .env .venv/ __pycache__/4. 第一步用 LangChain 调用 Model4.1 编写最小调用代码在项目目录创建main.py# 文件路径main.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI # 加载 .env 中的环境变量 load_dotenv() llm ChatOpenAI( modelos.getenv(LLM_MODEL), api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL), temperature0.3, ) response llm.invoke(用一句话解释什么是大语言模型) print(response.content)这段代码做的事情很简单创建模型客户端调用invoke方法传入文本拿到模型回复后打印。需要注意这里的ChatOpenAI不是只能接 OpenAI凡是支持 OpenAI 兼容协议的服务商都可以通过base_url接入。4.2 运行与验证执行python main.py如果一切正常终端会输出一句中文回答例如“大语言模型是通过海量文本训练出来、能理解和生成自然语言的人工智能模型”。如果报错优先检查三件事环境变量是否加载成功、模型名是否正确、网络是否能访问服务商接口。4.3 使用 Prompt 模板直接调用模型相当于裸奔实际项目中很少这么写。更标准的做法是用ChatPromptTemplate管理指令把系统角色和用户输入分开# 文件路径prompt_demo.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate load_dotenv() llm ChatOpenAI( modelos.getenv(LLM_MODEL), api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL), ) prompt ChatPromptTemplate.from_messages([ (system, 你是{domain}领域的资深专家回答必须具体、可执行不要空话。), (human, 请给出3条关于「{question}」的建议。), ]) chain prompt | llm result chain.invoke({ domain: Python 后端开发, question: 如何优化接口性能, }) print(result.content)这里最值得注意的写法是prompt | llm这是 LCELLangChain Expression Language的管道语法表示把 Prompt 的输出传给模型作为输入。把两个组件串成一个chain之后调用chain.invoke()就能一次性完成“填充模板 调用模型”。运行方式和之前一样执行python prompt_demo.py。你可以尝试修改domain和question观察输出变化这是体验 LangChain 组合能力最快的方式。5. 第二步从 Chain 到 Agent 的升级5.1 为什么需要 Agent假设用户问“北京今天天气怎么样顺便算一下 12*3456 等于多少”。如果只用 Chain你需要在代码里把各种可能性提前写死非常痛苦但如果用 Agent模型会自动拆解任务决定调用天气工具和计算工具。这就是 Agent 的核心价值把“流程怎么走”的决策权交给模型开发者只需要负责准备好工具。5.2 Function Calling 机制你可能好奇模型是怎么知道“去调用工具”的这依赖模型服务商提供的 Function Calling 能力。当你把工具函数声明传给模型后模型会根据用户问题输出一个结构化的指令比如“调用函数 get_weather参数是北京”。LangChain 负责解析这个指令、执行对应函数、把结果回传给模型模型再基于工具结果生成最终回答。所以有个前提需要注意Agent 是否能正常工作和模型本身支不支持工具调用强相关。如果模型不支持 Function Calling这个方案就走不通。5.3 编写一个最简单的工具函数先写一个查询天气的工具。工具函数看起来和普通 Python 函数没有区别但有两个要求必须有类型注解必须有清晰的 docstring因为模型要靠这些描述理解工具的用途。# 文件路径tool_weather.py def get_weather(city: str) - str: 查询指定城市当前天气。参数 city 是城市名称例如“北京”。 weather_map { 北京: 晴气温 5-15℃, 上海: 多云气温 10-18℃, 广州: 小雨气温 15-22℃, 深圳: 阴气温 14-21℃, } return weather_map.get(city, f暂无 {city} 的天气数据请确认城市名称)说明一下这里的天气数据是模拟的真实项目中应该替换为天气 API 的调用逻辑。用模拟数据的好处是你不需要申请额外的 API Key 就能先把 Agent 流程跑通。5.4 Agent 完整示例接下来把工具接入 Agent# 文件路径agent_demo.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langgraph.prebuilt import create_react_agent from tool_weather import get_weather load_dotenv() llm ChatOpenAI( modelos.getenv(LLM_MODEL), api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL), temperature0, ) tools [get_weather] agent create_react_agent(llm, tools) result agent.invoke({ messages: [ {role: user, content: 北京今天天气怎么样} ] }) print(result[messages][-1].content)这里使用create_react_agent创建 Agent它来自 LangGraph 的预置模块。ReAct 是“Reasoning and Acting”的缩写核心思路是让模型在“思考、行动、观察”之间循环先决定要做什么再调用工具然后观察结果最后给出回答。从代码量来看Agent 和普通模型调用差不多区别就在tools参数。你可以继续添加工具函数让 Agent 具备更多能力。6. 完整实战搭建一个多工具 AI 助手6.1 需求设计现在我们把前面的内容整合成一个稍完整的小项目命令行 AI 助手支持查询天气、安全四则运算、以及简单的数学表达式计算。用户输入一句话Agent 自己决定要不要调用工具。6.2 实现安全计算工具很多人写计算工具时第一反应是用eval()但eval()在线上有严重安全风险。这里用一个基于ast模块的安全实现只允许白名单运算符# 文件路径tool_calculator.py import ast import operator def safe_calculate(expression: str) - str: 安全计算数学表达式支持四则运算和括号。例如 12 * 34 56。 allowed_operators { ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul, ast.Div: operator.truediv, ast.USub: operator.neg, ast.Pow: operator.pow, } def eval_node(node): if isinstance(node, ast.Expression): return eval_node(node.body) if isinstance(node, ast.Constant): if isinstance(node.value, (int, float)): return node.value raise ValueError(只支持数字) if isinstance(node, ast.BinOp): left eval_node(node.left) right eval_node(node.right) op allowed_operators.get(type(node.op)) if op is None: raise ValueError(不支持的运算符) return op(left, right) if isinstance(node, ast.UnaryOp): operand eval_node(node.operand) op allowed_operators.get(type(node.op)) if op is None: raise ValueError(不支持的运算符) return op(operand) raise ValueError(不支持的表达式) try: tree ast.parse(expression, modeeval) result eval_node(tree.body) return str(result) except Exception as e: return f表达式错误: {e}这个实现允许数字和四则运算但禁止了函数调用、属性访问、列表表达式等危险语法比直接使用eval安全得多。在真实项目里计算类工具一定要做类似的限制。6.3 组装 Agent 完整代码# 文件路径assistant.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langgraph.prebuilt import create_react_agent from tool_weather import get_weather from tool_calculator import safe_calculate load_dotenv() llm ChatOpenAI( modelos.getenv(LLM_MODEL), api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL), temperature0, ) tools [get_weather, safe_calculate] agent create_react_agent(llm, tools) while True: user_input input(请输入你的问题输入 exit 退出) if user_input.lower() exit: break result agent.invoke({ messages: [ {role: user, content: user_input} ] }) print(助手回答:, result[messages][-1].content) print(- * 50)代码逻辑很简单循环读取用户输入交给 Agent 处理打印最终回答。create_react_agent内部已经处理了“思考、调用工具、观察结果”的循环不需要你手工编排。6.4 运行与验证执行python assistant.py尝试输入下面几个句子北京今天天气怎么样 帮我算一下 12 * 34 56 等于多少 上海天气如何预期效果是Agent 识别出天气相关问题后调用get_weather识别出计算问题后调用safe_calculate。如果你开启调试模式甚至能看到它先选择了哪个工具、拿到了什么结果再生成最终回答。需要提醒的是如果模型不支持工具调用或者工具描述不够清晰Agent 可能给出一个纯文本回答而不真的调用工具。这不是代码的问题而是模型能力和工具定义的问题可以通过调整工具描述来改善。6.5 如何判断成功判断 Agent 是否成功的标准不只是“最终回答是否正确”还包括模型是否做出了正确的工具选择、工具调用次数是否合理、失败时是否如实告诉用户。一个成熟的 Agent 应用需要你不断观察它的中间执行过程而不只是看结果。7. 常见问题与排查思路实际开发中LangChain 的报错类型不算多但新手容易因为“看不懂报错”而卡住。下面把我认为最常见的几类问题列成一张排查表问题现象可能原因排查方式解决方案报错提示 API key 无效或鉴权失败.env没写对、Key 过期、环境变量没加载打印os.getenv(LLM_API_KEY)确认值重新配置.env确认 Key 在服务商后台有效请求卡住最终 timeout 或连接失败网络到模型服务不通或base_url配置错误先用curl或浏览器访问base_url测试连通性检查网络环境确认服务商接口地址是否正确提示模型名不存在或 not supported模型名拼写错误或服务商没有该模型对照服务商文档核对模型列表换成服务商支持的正确模型名报上下文窗口溢出超过最大 token单次请求内容太长或历史消息累积过多查看请求包含的消息总长度精简 Prompt、清理历史消息、分段处理模型服务返回过载at capacity服务端资源紧张或触发限流观察是否持续出现记录状态码替换模型、增加重试退避、错峰调用Agent 没有调用工具直接强行回答模型不支持工具调用或工具描述太模糊打开调试模式查看中间步骤确认模型支持 Function Calling并优化工具描述使用带思维链的模型时报错要求回传推理内容厂商要求把思维链内容随请求回传查看服务商工具调用兼容文档按服务商模式配置或升级模型适配层排查问题时有一个通用思路不要盯着最后一行报错要看完整的堆栈信息。LangChain 的报错通常会把底层 HTTP 状态码和模型服务商的信息都打出来先分清是“环境问题、网络问题、模型问题”还是“代码问题”。8. 最佳实践与工程建议8.1 配置安全管理API Key 属于敏感信息绝对不要硬编码在代码里也不要提交到 Git 仓库。建议使用环境变量或配置中心管理。团队协作时.env.example可以作为模板提交到仓库但.env必须忽略。如果密钥泄露立即到服务商后台吊销并重新生成。8.2 工具函数设计原则工具是 Agent 能力的边界。工具函数应该满足三个原则职责单一。一个工具只做一件事不要写一个“万能工具”。描述清晰。docstring 要说明功能、参数含义和适用场景。输入校验。不要信任模型生成的参数函数内部要做异常处理。记住模型是靠工具描述决定“什么时候用、怎么用”的。描述写得越清楚Agent 的调用准确率越高。8.3 什么时候用 Chain什么时候用 Agent我的建议是流程固定、不需要决策的场景用 Chain比如翻译、摘要、数据提取流程不确定、需要调用多个外部资源、需要根据中间结果调整下一步的场景用 Agent。如果只是做一个简单的问答接口没必要引入 Agent。Agent 的“灵活性”是用“不可预测性”换来的它可能多调用一次工具也可能选错工具。生产环境一定要有超时控制、重试机制和人工审核节点。8.4 对话记忆怎么加本文的 Agent 示例没有历史记忆每次提问都是独立请求。真实项目里用户希望 AI 记得上一轮说过什么。LangChain 和 LangGraph 都提供了记忆方案核心思路是把对话历史存入一个可持久化的存储中每次请求时带上最近几轮消息。建议从LangGraph的 checkpointer 机制入手它能把 Agent 的每一步执行状态持久化支持断点续跑和人工干预生产环境比手动拼接历史消息更可靠。8.5 想清楚框架分层前面提到过LangChain、vLLM、PyTorch 是不同层次的东西。PyTorch 负责模型训练vLLM 负责推理加速LangChain 负责应用编排。这三个没有可比性学习路线也不冲突。如果你要做的只是调用现成大模型开发应用LangChain 就够了如果你要训练模型才需要学 PyTorch如果你要优化推理性能才需要了解 vLLM。8.6 安全边界Agent 的能力越强风险越大。生产环境中要警惕以下情况不要让 Agent 直接执行操作系统命令或访问数据库删除接口。给 Agent 的工具配置权限时遵循最小权限原则只开放当前任务需要的能力。任何涉及用户数据或资金的操作都要经过人工确认。记录 Agent 的工具调用日志方便事后审计。安全不是上线前补上的功能而是在设计工具时就要考虑好的约束。9. 总结与后续学习方向这篇文章做的事是帮零基础读者把 LangChain 的学习路线梳理清楚先理解 Model、Prompt、Chain、Agent 这些核心概念再通过实际的代码把模型调用、Prompt 模板、工具调用、Agent 组装全部跑通。最后那份排查表建议你在遇到报错时先对照检查能省下不少搜资料的时间。如果你今天只记住一句话那就是LangChain 不是模型而是把模型、工具、流程组织起来的工程框架。从 Model 到 Chain 再到 Agent本质上都在回答同一个问题——如何让大模型在真实业务里稳定地完成工作。下一步可以继续学这几个方向一是把 Agent 的对话记忆接上做成真正可聊天的应用二是学习 RAG检索增强生成让 AI 能回答私有知识库的问题三是深入了解 LangGraph把 Agent 从“能跑”推进到“可控、可追踪、可上线”。每一条路都够你研究很久但基础打好之后这些方向都会顺畅很多。