企业官网建设流程全解析

如果你想学 LangChain，但只是打算照抄别人的代码，这篇文章可能不太适合你。如果你想搞明白 LangChain 的 Model、Chain、Agent 到底是什么、为什么要这样设计、如何从零动手搭一个能查天气、能算数、能回答问题的 AI 智能应用，那么这篇文章值得你从头读到尾。

我见过不少初学者卡在两个地方：第一，环境装好了，模型也调通了，但一接触 Agent 就懵，不知道为什么一句话就能让模型自己去调用工具；第二，照着网上的旧教程写代码，发现 API 已经变了，报错信息也看不懂，最后只能放弃。LangChain 本身的学习难度并不高，真正难的是它的版本迭代比较快，而且官方对“标准写法”的定义也在不断调整。如果你不理解核心设计，只盯着 API 用法，很容易一直处于“在追新版本”的状态。

这篇文章会给你一条相对完整的路线：从最基础的“调用一个模型”开始，到用 Prompt 模板封装提示词，再到搭建一个能调用外部工具的 Agent，最后输出一个完整可运行的项目，并附上常见报错排查表。读完以后，你可以自己判断：什么时候用 Chain 就够，什么时候必须上 Agent，什么时候应该去学 LangGraph。

1. 这篇文章真正要解决的问题

先说结论：LangChain 不是大模型本身，也不是深度学习框架，而是“大模型应用开发框架”。它的核心价值，是把调用模型、写提示词、接外部工具、管理对话记忆这些事情，从零散的裸代码封装成一套可以复用、可以组合的组件。

很多人学 LangChain 失败，不是因为智商，而是因为选题。一上来就学 Agent 高级编排，前置概念还没搞懂；或者反过来，只学会了最基础的model.invoke()，以为这就是全部，后面不知道往哪走。这篇文章用一条主线把问题串起来：先理解概念，再跑通代码，最后搞清楚每种写法适合什么场景。

读完这篇文章，你会获得三个可以复用的能力：

1. 能独立配置 Python 环境，跑通 LangChain 的模型调用。
2. 能理解 Chain 和 Agent 的边界，知道什么场景该用哪一种。
3. 能照着一个完整的示例，搭出带工具调用的 Agent 应用，并且具备最基本的报错排查能力。

文章里所有代码都遵循一个原则：能用最小代码跑通，就不引入多余依赖。你不需要先成为 Prompt 工程专家，也不需要精通大模型原理，只要会基础的 Python 语法，就可以跟上。

2. LangChain 核心概念：Model、Chain、Agent 到底是什么

2.1 用一句话理解 LangChain

如果没有 LangChain，你要开发一个 AI 对话功能，通常要做的事情包括：请求模型服务商接口、拼接 Prompt、处理返回结果、记录对话历史、接入业务 API、处理错误重试。这些工作每家团队都要重复做一遍，而且写法五花八门。

LangChain 做的事情，就是把上述通用能力抽象成组件。你只需要选择模型、定义 Prompt、写清工具，剩下的组装交给框架。类比一下：PyTorch 是深度学习的训练框架，vLLM 是大模型的推理加速引擎，LangChain 是大模型应用的“编排层”。三者不属于同一个层面，并不存在“哪个更好”的问题。

2.2 Model：AI 应用的“大脑”

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 有三个核心组成部分：

2.6 LangChain 和 LangGraph 是什么关系

这是新手最容易搞混的问题。简单说：LangChain 提供组件，LangGraph 提供“图执行引擎”。如果你只是在搭固定流程，用 LangChain 足够；如果你的 Agent 需要循环、条件分支、人工审核节点、多角色协作，LangGraph 更合适。

这种设计不是重复造轮子。LangChain 更偏“声明式”，适合把步骤固定下来的过程；LangGraph 更偏“命令式”，可以把 Agent 每一步的执行状态落到图结构里，方便追踪、打断和恢复。

3. 环境准备与前置条件

3.1 需要准备什么

在开始写代码之前，先把环境准备好。你需要以下几样东西：

1. Python 3.10 或更高版本，建议使用较新的稳定版。
2. pip 包管理工具，一般安装 Python 时自带。
3. 一个模型服务商的 API Key。
4. 一个能正常访问模型服务接口的网络环境。

这里解释一下为什么需要 API Key：LangChain 本身是开源的，但底层调用的模型服务不是免费的，绝大多数服务商需要注册账号并创建 Key。文章中的代码使用 OpenAI 兼容接口的写法，也就是说，只要你的模型服务商支持 OpenAI 兼容格式，都可以套用。

3.2 创建项目与虚拟环境

建议每个项目都建独立虚拟环境，避免依赖冲突。打开终端，执行：

mkdir langchain-demo cd langchain-demo python -m venv .venv source .venv/bin/activate

Windows 命令行下激活命令是.venv\Scripts\activate。激活成功后，命令行前面会出现(.venv)前缀。

3.3 安装依赖

pip install langchain langchain-openai langgraph python-dotenv

这里简单说明每个包的作用：

• langchain：核心框架。
• langchain-openai：OpenAI 兼容接口的适配器。
• langgraph：LangChain 官方推荐的 Agent 执行引擎，本文的 Agent 示例会用到它。
• python-dotenv：读取.env配置文件。

版本方面，请以官方最新发布版本为准，本文代码基于目前主流的 API 编写，重点演示的是设计思路。

3.4 配置环境变量

在项目根目录创建.env文件：

# 文件路径：.env LLM_API_KEY=你的API_Key LLM_MODEL=deepseek-chat LLM_BASE_URL=https://api.deepseek.com/v1

注意：不同服务商的base_url和模型名不一样，请以服务商文档为准。.env文件不要提交到 Git，建议加入.gitignore。

# 文件路径：.gitignore .env .venv/ __pycache__/

4. 第一步：用 LangChain 调用 Model

4.1 编写最小调用代码

在项目目录创建main.py：

# 文件路径：main.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI # 加载 .env 中的环境变量 load_dotenv() llm = ChatOpenAI( model=os.getenv("LLM_MODEL"), api_key=os.getenv("LLM_API_KEY"), base_url=os.getenv("LLM_BASE_URL"), temperature=0.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( model=os.getenv("LLM_MODEL"), api_key=os.getenv("LLM_API_KEY"), base_url=os.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，这是 LCEL（LangChain Expression Language）的管道语法，表示把 Prompt 的输出传给模型作为输入。把两个组件串成一个chain之后，调用chain.invoke()就能一次性完成“填充模板 + 调用模型”。

运行方式和之前一样，执行python prompt_demo.py。你可以尝试修改domain和question，观察输出变化，这是体验 LangChain 组合能力最快的方式。

5. 第二步：从 Chain 到 Agent 的升级

5.1 为什么需要 Agent

假设用户问“北京今天天气怎么样，顺便算一下 12*34+56 等于多少”。如果只用 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( model=os.getenv("LLM_MODEL"), api_key=os.getenv("LLM_API_KEY"), base_url=os.getenv("LLM_BASE_URL"), temperature=0, ) 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, mode="eval") 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( model=os.getenv("LLM_MODEL"), api_key=os.getenv("LLM_API_KEY"), base_url=os.getenv("LLM_BASE_URL"), temperature=0, ) 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 的报错类型不算多，但新手容易因为“看不懂报错”而卡住。下面把我认为最常见的几类问题列成一张排查表：

排查问题时有一个通用思路：不要盯着最后一行报错，要看完整的堆栈信息。LangChain 的报错通常会把底层 HTTP 状态码和模型服务商的信息都打出来，先分清是“环境问题、网络问题、模型问题”还是“代码问题”。

8. 最佳实践与工程建议

8.1 配置安全管理

API Key 属于敏感信息，绝对不要硬编码在代码里，也不要提交到 Git 仓库。建议使用环境变量或配置中心管理。团队协作时，.env.example可以作为模板提交到仓库，但.env必须忽略。如果密钥泄露，立即到服务商后台吊销并重新生成。

8.2 工具函数设计原则

工具是 Agent 能力的边界。工具函数应该满足三个原则：

1. 职责单一。一个工具只做一件事，不要写一个“万能工具”。
2. 描述清晰。docstring 要说明功能、参数含义和适用场景。
3. 输入校验。不要信任模型生成的参数，函数内部要做异常处理。

记住，模型是靠工具描述决定“什么时候用、怎么用”的。描述写得越清楚，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 从“能跑”推进到“可控、可追踪、可上线”。每一条路都够你研究很久，但基础打好之后，这些方向都会顺畅很多。