很多初学者第一次接触 LangChain 时最困惑的问题不是“怎么安装”而是“我明明已经能调用大模型 API 了为什么还要用一个框架”如果只是发一段 Prompt、拿一段回复原生的 OpenAI SDK 或者 Requests 就足够了。但一旦你想做的是“根据用户问题自动选择工具”“让模型记住多轮对话”“从文档里检索资料后再回答”这类真正的智能应用代码复杂度会迅速失控。这篇文章会从零开始把 LangChain 中最重要的两个概念拆开讲清楚Model和Agent。我们会先理解 LangChain 的设计思路再完成一个可运行的 AI 问答应用最后实现一个能调用工具的 Agent 并解决实际任务。全文包含完整代码、环境配置、运行结果和常见问题排查适合零基础入门也适合想系统梳理 LangChain 知识体系的开发者收藏备用。1. 为什么零基础入门先要理解 LangChain、Model、Agent1.1 大模型应用开发的现实问题假设你现在想做一个智能助手功能是帮用户查时间、做算术、写周报。用原始 API 写的话你要做的事包括设计提示词并且在不同场景下拼接不同的提示词判断用户意图然后自己写 if-else 决定调用哪个函数把函数返回结果拼回对话上下文再请求一次模型处理多轮对话里的历史记录避免上下文越攒越长兼容不同模型服务商换一个模型就要改一遍调用代码。这些工作本身并不复杂但非常零散。LangChain 的价值在于它把这些高频操作提炼成标准组件并且提供了组合这些组件的“语法”。你可以把一次 AI 任务理解成一条流水线输入 - 提示词 - 模型 - 输出解析 - 工具调用 - 返回结果。LangChain 负责把流水线上的每个环节串起来。1.2 LangChain 的定位组件库 编排框架LangChain 并不是一个类似 PyTorch 的深度学习框架也不是一个类似 vLLM 的推理服务。它们解决的是完全不同的层级问题名称定位解决什么问题PyTorch深度学习框架训练和运行神经网络模型vLLM高性能推理服务把训练好的模型高效部署成 API 服务LangChainLLM 应用编排框架用标准组件把模型、提示词、工具、记忆、检索组合成应用所以面试题或者项目文档里如果出现“LangChain、vLLM 跟 PyTorch 框架一个类型吗”答案是否定的。LangChain 更接近“胶水层”它不负责模型推理而是负责让开发者用统一的方式调用各种模型、管理提示词、串联业务逻辑。LangChain 的核心模块包括Model I/O负责模型调用、提示词管理、输出解析Retrieval负责文档加载、切分、向量化、检索常与 RAG 结合Memory负责多轮对话历史存储Agent负责让模型自主决策并调用工具Chain / LangGraph负责把上面所有组件编排成完整流程。1.3 Model 与 Agent 到底有什么区别这是很多人混淆的地方。Model模型是智能应用的大脑。它接收一段文本输入返回一段文本输出。它的能力边界是“理解和生成语言”但它本身不能执行操作。你让它“查询当前时间”如果 Prompt 里没有时间信息它只能凭训练数据猜一个或者明确告诉你不知道。Agent智能体是基于模型构建的决策和执行系统。Agent 的职责是理解用户目标判断需要哪些工具调用工具获取结果把工具结果交给模型继续推理输出最终答案。可以这样理解Model 是“会说的人”Agent 是“会做事的人”。Agent 内部的推理和表达仍然依赖 Model但 Agent 额外拥有工具使用权和决策循环。所以本文的实战会分两条线第一条线是直接用 Model 做问答第二条线是用 Agent 让模型调用工具完成任务。2. 环境准备与版本说明2.1 Python 环境准备LangChain 是一个 Python 库所以首先需要准备 Python 环境。建议使用 Python 3.10 或 3.11过旧的版本可能导致依赖兼容问题。为了不污染系统环境推荐创建独立虚拟环境。在终端中执行python -m venv .venv激活虚拟环境Windows.venv\Scripts\activateLinux / macOSsource .venv/bin/activate激活后终端提示符前面会出现(.venv)说明当前已经进入虚拟环境。2.2 安装 LangChain 相关依赖LangChain 生态发展很快一个容易踩坑的点是不要只安装langchain一个包。现在的官方推荐是“按需安装”langchain核心框架langchain-openaiOpenAI 以及 OpenAI 兼容接口的模型封装langchain-community社区贡献的集成组件langchain-core核心抽象通常会被自动安装python-dotenv读取.env环境变量文件。安装命令pip install langchain langchain-openai langchain-community python-dotenv如果你的项目需要固定依赖版本建议生成requirements.txt文件。下面是一个参考langchain0.3,1.1 langchain-core0.3 langchain-openai0.2 langchain-community0.3 python-dotenv1.0强调一点LangChain 在 0.3 和 1.x 之间有一些接口调整。本文示例以 0.3 之后到 1.x 初期仍然稳定的 API 为主如果你安装的是更高版本遇到导入路径变化时以官方迁移文档为准。2.3 准备模型服务与密钥LangChain 可以对接很多模型服务包括 OpenAI、DeepSeek、通义千问、本地部署的 vLLM、Ollama 等。本文以“OpenAI 兼容接口”为例这也是目前兼容性最好的方式。你需要准备以下信息一个可用的大模型 API Key模型名称例如gpt-4o-mini、deepseek-chat等如果是兼容接口还需要 API Base URL。不要把密钥直接写在代码里更不要提交到 Git 仓库。推荐使用.env文件保存OPENAI_API_KEY你的密钥 OPENAI_BASE_URLhttps://api.openai.com/v1如果你的模型服务商提供的是兼容 OpenAI 的 Base URL可以替换OPENAI_BASE_URL。本文示例代码会先读取.env再通过环境变量传给 LangChain。2.4 项目目录结构设计下面是一个简单但清晰的项目结构langchain-demo/ ├── .env ├── requirements.txt ├── chat_model.py # Model 基础调用示例 ├── prompt_template.py # 提示词模板示例 ├── chain_demo.py # 第一条链示例 ├── agent_demo.py # Agent 实战示例 └── app.py # 问答应用入口实际开发中推荐按功能拆分成models/、tools/、agents/、chains/等目录。前期练习阶段先保持单文件风格更容易理解。3. 第一个关键步骤用 ChatModel 完成模型调用3.1 ChatModel 基础用法LangChain 里最常用的模型接口是ChatOpenAI它对应的是聊天模型。与文本补全模型不同聊天模型的输入输出都是消息对象便于保留多轮对话结构。先来看一个最基础的调用示例。新建chat_model.pyimport os from dotenv import load_dotenv from langchain_openai import ChatOpenAI load_dotenv() llm ChatOpenAI( modelgpt-4o-mini, temperature0, ) response llm.invoke(用一句话简介 LangChain) print(response)运行python chat_model.py输出结果会是一个AIMessage对象而不是普通字符串contentLangChain 是一个用于构建大语言模型应用的开源框架通过将模型、提示词和工具编排成工作流让开发者更高效地开发智能应用。 ...这里有两个关键点temperature0表示输出更确定适合代码生成、分类、提取类任务如果做创意写作可以调大到 0.7 或更高。invoke是 LangChain 统一的同步调用方法返回的是结构化消息对象。如果直接打印整个对象会包含content、response_metadata等字段。如果只想拿文本可以访问response.contentprint(response.content)如果你的模型服务商使用兼容 OpenAI 的接口可以加两个参数llm ChatOpenAI( modeldeepseek-chat, api_keyos.getenv(DEEPSEEK_API_KEY), base_urlos.getenv(DEEPSEEK_BASE_URL), )模型名称必须以你实际使用的服务商为准不同平台模型名称不同即使底层模型相同暴露出来的名字也可能不一样。3.2 PromptTemplate把提示词变成模板直接在代码里拼字符串非常痛苦尤其当提示词长达几十行时。LangChain 提供了PromptTemplate支持变量插值和消息模板。新建prompt_template.pyfrom langchain_core.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_messages([ (system, 你是一名资深 Python 技术博主擅长用通俗易懂的语言解释技术概念。), (human, 请帮我解释一下 {concept}要求结合例子说明。), ]) messages prompt.invoke({concept: LangChain Agent}) print(messages)ChatPromptTemplate.from_messages接收一个消息列表每条消息由角色和内容组成。角色可以是system系统指令设定 AI 的角色和行为规范human用户输入aiAI 的历史回复invoke时传入一个字典把{concept}替换成实际内容。这样做的最大好处是提示词和代码逻辑解耦。后续要调整提示词只需要改动模板不需要动 Python 代码。3.3 用 StrOutputParser 串联成第一条链Model 返回的是AIMessage但很多业务接口希望直接拿到字符串。LangChain 提供了输出解析器StrOutputParser可以把消息对象中的content提取出来。LangChain 从 0.2 开始主推LCELLangChain Expression Language用|符号把组件串联起来写法非常直观from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser from langchain_openai import ChatOpenAI llm ChatOpenAI(modelgpt-4o-mini, temperature0) prompt ChatPromptTemplate.from_template( 用一句话解释 {concept}并给出一个实际应用场景。 ) chain prompt | llm | StrOutputParser() result chain.invoke({concept: LangChain Memory}) print(result)这里的chain就是一条完整的处理链路用户输入 - 填充 Prompt - 调用模型 - 解析输出 - 字符串结果|符号并不是 Python 自带的语法而是 LangChain 对__or__运算符的重写。它让代码读起来像管道也方便在不同组件之间自由组合。这是 LangChain 最核心的编程模型一切皆组件一切皆可链。4. 实战一从零搭建 AI 智能问答应用4.1 创建项目结构与配置文件在项目根目录创建.env文件OPENAI_API_KEY你的密钥 OPENAI_BASE_URLhttps://api.openai.com/v1创建requirements.txtlangchain0.3,1.1 langchain-openai0.2 langchain-community0.3 python-dotenv1.0安装依赖pip install -r requirements.txt4.2 编写最小问答脚本新建app.pyimport os from dotenv import load_dotenv from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser from langchain_openai import ChatOpenAI load_dotenv() # 1. 初始化模型 llm ChatOpenAI( modelos.getenv(OPENAI_MODEL, gpt-4o-mini), temperature0.3, ) # 2. 构建提示词模板 prompt ChatPromptTemplate.from_messages([ (system, 你是一个乐于助人的 AI 助手。回答尽量简洁、准确、有条理。), (human, {question}), ]) # 3. 串联成链 chain prompt | llm | StrOutputParser() # 4. 接收用户输入并回答 if __name__ __main__: while True: question input(请输入问题输入 exit 退出).strip() if question.lower() exit: break if not question: continue answer chain.invoke({question: question}) print(AI:, answer) print(- * 50)4.3 流式输出改造上面代码是一次性返回完整答案如果问题复杂用户等待时间会很长。你可以把chain.invoke改成chain.stream实现打字机效果if __name__ __main__: while True: question input(请输入问题输入 exit 退出).strip() if question.lower() exit: break if not question: continue print(AI: , end, flushTrue) for chunk in chain.stream({question: question}): print(chunk, end, flushTrue) print(\n - * 50)4.4 运行验证与输出说明运行python app.py示例交互请输入问题输入 exit 退出LangChain 中的 Agent 是什么 AI: Agent 是 LangChain 中能够根据用户目标自主选择并调用工具的智能体它通过大模型进行推理决策再借助外部工具完成实际操作。 -------------------------------------------------- 请输入问题输入 exit 退出exit到这里你已经完成了第一个基于 LangChain 的 AI 问答应用。虽然功能简单但已经覆盖了 LangChain 最核心的 Component Chain 模式。5. 深入 Agent从“会聊天”到“会办事”5.1 模型单独工作时的边界现在我们对模型提一个问题请计算 12345 乘以 6789 等于多少大模型很可能给出一个接近但不完全正确的答案。原因是语言模型本身不擅长精确计算它是通过“预测下一个 token”来生成文本的而不是像计算器那样真的做四则运算。再比如现在是几点钟如果模型没有联网能力也没有接收系统时间它就无法回答当前时间。这些场景都说明模型单独工作时有明确边界。Agent 解决的就是这个边界问题——当模型发现自己能力不足时可以调用外部工具来获得准确结果。5.2 Agent 的执行机制ReAct 循环LangChain Agent 的经典机制是ReAct即 Reasoning Acting。整个执行过程可以理解成循环思考Thought模型分析用户问题决定下一步要做什么行动Action模型选择一个工具并生成调用参数观察Observation系统执行工具把结果返回给模型继续循环模型根据观察结果继续思考直到认为可以输出最终答案回答Final Answer模型生成最终回复。这个过程可以用下面这个流程描述用户输入 - 模型推理 - 需要工具 - 是调用工具 - 返回观察结果 - 回到模型推理 - 否生成最终答案 - 输出结果Agent 最大的价值是“把决策权交给模型”。你不需要提前写好if-else判断用户意图模型会在每次调用时自主决定。5.3 用 tool 自定义工具LangChain 提供一个tool装饰器可以把普通函数快速包装成可供 Agent 调用的工具。工具需要满足两个条件有清晰的函数名有描述性的 docstring模型会根据 docstring 判断什么时候调用这个工具。新建agent_demo.pyimport os from datetime import datetime from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import create_tool_calling_agent, AgentExecutor from langchain.tools import tool from langchain_core.prompts import ChatPromptTemplate load_dotenv() tool def multiply(a: int, b: int) - int: 计算两个整数的乘积适合做精确乘法运算。 return a * b tool def get_current_time() - str: 获取当前的日期和时间。当用户询问“现在几点”“今天日期”时使用。 return datetime.now().strftime(%Y-%m-%d %H:%M:%S)重点说明函数名multiply会成为工具名函数签名a: int, b: int会告诉模型需要传入的参数类型docstring 是模型判断调用时机的重要依据如果 docstring 写得太模糊模型可能不知道在什么时候用这个工具。5.4 使用 create_tool_calling_agent 构建 Agent继续在agent_demo.py中添加代码# 初始化模型注意工具调用需要模型支持 function calling llm ChatOpenAI(modelgpt-4o-mini, temperature0) tools [multiply, get_current_time] prompt ChatPromptTemplate.from_messages([ (system, 你是一个可靠的 AI 助手可以调用工具解决用户问题。), (placeholder, {chat_history}), (human, {input}), (placeholder, {agent_scratchpad}), ]) # 构建 Agent agent create_tool_calling_agent(llm, tools, prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue) result agent_executor.invoke({ input: 请帮我计算 12345 乘以 6789然后告诉我当前时间。 }) print(\n最终答案:, result[output])代码里几个关键点create_tool_calling_agent是专门给支持“工具调用”的模型使用的创建函数tools列表决定 Agent 能使用哪些工具agent_scratchpad是 Agent 的“草稿板”用来记录已经产生的思考和观察结果AgentExecutor负责真正执行循环verboseTrue会在控制台输出完整的运行过程。5.5 运行 Agent 并观察思考过程运行代码python agent_demo.py如果一切正常你会看到类似下面的日志 Entering new AgentExecutor chain... Invoking: multiply with {a: 12345, b: 6789} 83774205 Invoking: get_current_time with {} 2025-XX-XX 14:30:22 Finished chain. 最终答案: 12345 乘以 6789 的结果是 83774205。当前的日期和时间是 2025-XX-XX 14:30:22。观察输出可以看到Agent 确实没有自己做乘法而是调用了multiply工具得到 83774205调用了get_current_time工具拿到当前时间把两个结果组织成自然语言回答。这就是 Agent 与普通 Model 调用的本质区别。模型还是那个模型但因为有了工具使用权它在面对事实性、实时性、精确性任务时可以借助外部工具拿到准确结果。6. LangGraph 与 LangChainAgent 编排的下一站6.1 LangGraph 与 LangChain 的关系如果你搜索 LangChain 进阶内容会发现一个高频词LangGraph。简单理解LangChain是组件库解决“用什么组件”的问题LangGraph是状态化编排框架解决“流程如何流转、状态如何保存”的问题。LangGraph 建立在 LangChain 组件之上但它用“图”来描述 Agent 流程。节点代表一步操作边代表状态转移全局状态会随着流程推进不断更新。相比AgentExecutorLangGraph 提供了更精细的控制能力。6.2 为什么多 Agent 场景推荐 LangGraphAgentExecutor适合快速实现单 Agent 的简单循环。但在生产级项目中你可能会遇到这些需求一个 Agent 负责理解用户意图另一个 Agent 负责搜索数据第三个 Agent 负责生成报告某个节点执行失败时希望回到上一步重新尝试需要人工审核后再继续执行需要控制每个节点的最大执行次数和时间。这些需求用线性 Chain 和自带的 AgentExecutor 很难优雅实现。LangGraph 把流程建模成状态图每个节点更新全局状态执行器按照图结构遍历节点因此天然支持分支、循环、回退、持久化。6.3 从 Chain 到 Graph 的迁移思路对于初学者不需要立刻把所有项目都改成 LangGraph。推荐的学习路径是先用 Chain 完成简单问答再用 AgentExecutor 完成单工具、多工具调用当流程中出现明显分支、循环、人工确认需求时再引入 LangGraph。理解这个演进关系可以避免“一上来就上重器”的误区。我们后面部署到生产环境时也需要先评估复杂度而不是默认选择所有运行模式。7. 常见问题与排查思路7.1 高频报错对照表问题现象常见原因解决思路提示找不到langchain_openai模块未安装langchain-openai包执行pip install langchain-openai调用模型返回 401 或 AuthenticationErrorAPI Key 错误、未设置环境变量检查.env文件确认load_dotenv()已调用404 或 Model Not Found模型名称在当前服务商不存在到服务商控制台确认模型 ID区分gpt-4o-mini、deepseek-chat等selected model is at capacity服务商模型实例容量不足或限流稍后重试或切换到同能力其他模型或检查账号额度context window 超出限制输入输出超过模型上下文长度精简历史记录使用摘要压缩或换更长上下文的模型多轮对话报 reasoning_content 相关错误思考模式开启时上一轮的推理字段未按接口要求回传使用官方 SDK 自动维护上下文或按文档回传reasoning_content或关闭思考模式网络超时或连接失败服务器网络策略限制或 Base URL 配置错误检查 Base URL 是否以/v1结尾确认服务商域名可访问7.2 模型调用与鉴权类问题遇到鉴权类错误时先按下面顺序排查确认.env文件是否存在并且位置在项目根目录确认代码里调用了load_dotenv()临时打印环境变量是否存在注意不要打印完整密钥建议只打印前几位确认模型名称和服务商平台一致如果使用了兼容接口确认 Base URL 格式正确例如是否缺少/v1路径。下面这段代码可以帮助你快速检查环境变量import os from dotenv import load_dotenv load_dotenv() api_key os.getenv(OPENAI_API_KEY) print(Key 是否存在:, bool(api_key))7.3 Agent 不调用工具或调用失败怎么排查如果 Agent 运行了但完全没有调用工具或者调用时参数错误可以按下面步骤排查确认模型支持工具调用create_tool_calling_agent要求模型支持 function calling部分本地模型或旧模型不支持可选择create_react_agent或换模型检查工具 docstring工具描述越清晰模型越容易判断何时使用检查工具参数类型如果函数签名要求int模型传入字符串时可能报错打开 verbose 日志把AgentExecutor的verboseTrue开启观察模型每一步的思考和行动简化问题先让 Agent 只做“计算 12 乘 13”确认基本链路通后再增加多工具场景。8. 最佳实践与工程建议8.1 密钥与配置管理生产环境中密钥管理是第一优先级。任何时候都不要把 API Key 写在代码里也不要提交到 Git 仓库。建议做法本地开发使用.env文件并加入.gitignore服务器部署使用环境变量或密钥管理系统不同环境开发、测试、生产使用不同的 Key避免一个 Key 泄露影响所有环境对 Key 设置额度上限和调用权限遵循最小权限原则。一个典型的.gitignore片段.env .venv/ __pycache__/8.2 提示词与工具设计提示词和工具描述的质量直接影响 Agent 的准确性。在工程实践中有几点很实用系统提示词要明确角色、任务边界、输出格式工具不要设计得太“大”一个工具只做一件事docstring 里写清楚“什么时候用、参数是什么、返回值是什么”工具名称使用动词名词结构例如get_current_time比time_tool更清晰如果 Agent 决策经常出错优先改进提示词和工具描述而不是急着换模型。8.3 错误处理、重试与降级大模型 API 并不是 100% 稳定生产应用必须考虑容错。建议至少处理以下几种情况网络超时设置合理的超时时间并增加重试机制限流捕捉限流异常做指数退避重试模型不可用准备一个备用模型例如主模型失败时切换到其他模型输出格式不符合要求增加输出校验解析失败时让模型重新生成或返回兜底文案。可以用下面的思路封装一个带重试的调用逻辑import time from tenacity import retry, stop_after_attempt, wait_exponential retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, max10)) def call_with_retry(chain, params): return chain.invoke(params)tenacity是一个通用的 Python 重试库实际项目中可以直接引入。8.4 成本、性能与可观测性大模型应用的成本并不低。上线前要关注模型选择简单任务不要用大参数模型gpt-4o-mini级别的模型足够处理大部分问答任务上下文压缩多轮对话历史不要无限追加可以做滑动窗口或摘要缓存相同问题在短期内可以复用答案减少重复调用并发控制不要无限制并发请求模型接口避免触发限流日志记录每次调用的模型、输入长度、输出长度、耗时和错误信息方便成本核算和问题定位。8.5 安全合规与生产发布生产环境发布 AI 应用时要注意安全的边界对用户输入做必要的过滤防止提示词注入攻击对 Agent 工具权限做最小化设计不要让 Agent 能直接删除数据库或执行高危命令输出内容要做合规校验尤其涉及用户数据和敏感信息时涉及修改、删除、写入外部系统的操作必须显式授权、人工确认、操作前备份不要在日志中记录完整密钥、用户敏感信息发布前先在测试环境完成全链路验证再灰度发布到生产环境。安全原则可以总结成一句话Agent 的能力越强权限边界越要收紧。9. 总结与下一步学习路线如果用一句话概括这篇文章的内容Model 让 AI 拥有“语言能力”Agent 让 AI 拥有“执行能力”LangChain 是连接两者的高效工具链。你掌握了哪些能力可以对照检查理解了 LangChain 的模块定位能说清 Chain、Agent、LangGraph 的区别能创建虚拟环境、安装 LangChain 依赖、配置模型 API Key能用 ChatModel、PromptTemplate、StrOutputParser 搭建第一条链能实现一个简单的 AI 问答应用并支持流式输出能用tool自定义工具用create_tool_calling_agent构建 Agent遇到鉴权失败、模型不可用、工具不调用等问题时有清晰的排查思路。下一步建议按这个顺序继续深入给问答应用增加“记忆”能力让 Agent 记住多轮对话学习 RAG把本地文档切片、向量化、检索后交给模型回答尝试 LangGraph实现带分支和人工确认的复杂流程把本地脚本包装成工具让 Agent 能操作真实业务系统。最后一个建议不要重复造轮子但也别盲目追新。先把你手头的场景用最小代码跑通再逐步替换成更复杂的组件。多写几遍多踩几次环境配置相关的坑LangChain 的脉络就会越来越清楚。如果这篇文章对你有帮助可以收藏备用后续我会继续更新记忆、RAG 和 LangGraph 的实战内容。