从零入门LangChain大模型实战：小白也能轻松搭建Agent（含环境配置与核心代码解析）

Source

本文专为会一点Python、调过几次大模型API但未系统搭建过Agent的读者设计。以工程顺序讲解LangChain框架：从接入模型、跑起Agent，逐步补充记忆、防护、检索、观测等功能，最后深入图编排和长任务套件。内容分四段读，涵盖LangChain核心概念、环境准备、基础调用、结构化输出及工具集成等关键知识点，助你独立完成工具循环+规矩齐全的应用。

一、LangChain 概述

  1. 1 构建agent出现的问题

第一次调大模型 API 的体验通常很好。十行代码，拿到回答，感觉这事没什么难的。

from openai import OpenAI

client = OpenAI()
resp = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "推荐三本讲分布式系统的书"}],
)
print(resp.choices[0].message.content)

问题出现在把它变成产品的时候。常见有五个坎：

  1. 换模型。 老板说 OpenAI 太贵，换成 DeepSeek；过两周又说某个任务用 Claude 更好。每家 SDK 的类名、参数名、返回结构都不一样，代码里开始长出 if provider == "openai"，越写越长。

  2. 提示词。 一开始拼字符串还行；等到有五个变量、要塞对话历史、还要按语言切换措辞，f-string 就成了灾难。更麻烦的是它散落在各个函数里，谁改了什么没人知道。

  3. 输出。 模型返回自由文本，你要的是能存进数据库的字段。于是写正则、写 json.loads、写各种兜底；模型偶尔多说一句「好的，以下是结果」就把解析打挂。

  4. 流程。 用户提问 → 查知识库 → 判断够不够 → 不够再查或换问法 → 最后生成答案。用裸 SDK 写，胶水代码会比业务代码多。

  5. 排查。 线上答得不对，你想知道完整提示词、检索命中了哪几段、这次花了多少 token。print 打到第三层就乱了。

这五个坎不是模型能力问题，是工程问题。LangChain 解决的就是这一层。

图片

  1. 2 LangChain 是什么

一句话：它是夹在你的应用和大模型之间的一层标准抽象，加一套把这些抽象拼起来的编排协议。

图片

具体做三件事：

  1. 统一接口。 不管底下是 OpenAI、Anthropic、Google，还是本地 Ollama，上层都是 model.invoke(messages)。换模型改一行配置。

  2. 封装重复劳动。 函数签名怎么转成模型能懂的 schema、怎么接调用请求、怎么把结果塞回对话——这些每个项目都要写一遍，LangChain 写好了。

  3. 提供可组合的积木。 提示词模板、模型、输出解析器、检索器都遵循 Runnable 协议，可以用 | 串起来，也可以并行、分支、重试。

  4. 3 它不负责什么

边界先划清，后面几部分才不会搅在一起：

  1. 不是模型。 一行推理代码都没有；能力上限由你选的模型决定，框架只负责接进来。

  2. 不是向量数据库。 切分、Embedding、检索的接口它定义了；真正存数据的是 Chroma、pgvector、Milvus 这些。

  3. 不管复杂流程的状态。 循环、条件回退、执行到一半等人审批、进程重启后接着跑——交给 LangGraph（本系列第二部分）。

  4. 不管长任务的自主规划。 Agent 自己拆几十步任务、开子代理、中间结果写文件——交给 DeepAgents（第三部分）。

  5. 不管调试和评测。 那是 LangSmith 做的事，后面会讲到。

图片

什么时候不必用 LangChain：单次调用做个文本改写；对延迟极度敏感、不愿多一层封装；团队已有成熟自研抽象。这几种情况直接用官方 SDK 更清爽，硬套框架反而多一层要维护的东西。

  1. 4 核心概念

后面各篇会逐个展开，这里先了解：

  1. Chat Model：模型的统一封装。输入消息列表，输出 AIMessage。

  2. Message：对话的基本单位，分 System、Human、AI、Tool 四类。

  3. Prompt Template：把提示词里的变量抽出来，管理占位符和对话历史。不单独成篇，入门示例和后面实战里按需用。

  4. Output Parser / 结构化输出：把自由文本变成可用的数据结构。

  5. Tool：给模型的可调用函数。你写 Python 函数，框架转成模型认识的 schema。

二、环境准备

  1. 1 虚拟环境选哪个

市面上三个选择各有适用面：

  1. conda：除了 Python 包，还能管解释器版本和 CUDA、编译器这类非 Python 依赖。以后要跑本地模型、装 PyTorch，选它省事。

  2. uv：只管 Python 生态，速度比 pip 快一个量级。纯应用层项目用它很舒服。

  3. venv：标准库自带，最轻，基于当前解释器建环境，适合临时试代码。

LangChain 本身是纯 Python 包，三个都能跑通。下面用 conda 演示，因为后面篇目会接本地模型。

conda create --name langchain1.2 python=3.13
conda activate langchain1.2
python -V

装包显式带版本号，这个习惯值得坚持。LangChain 1.x 迭代不慢，不锁版本过两个月回来看示例可能就跑不了了。

pip install langchain==1.2.12 langchain-openai

国内网络慢的话加个镜像：

pip install langchain==1.2.12 -i https://pypi.tuna.tsinghua.edu.cn/simple

验证一下：

import langchain
print(langchain.__version__)
  1. 2 API Key 怎么放

别写在代码里。项目根目录建 .env，同时把它加进 .gitignore：

OPENAI_API_KEY=sk-xxxxxxxx
OPENAI_BASE_URL=https://api.openai.com/v1

OPENAI_BASE_URL 这行在用第三方代理或兼容接口的服务商时会用到，直连官方可以删掉。

代码里读进来：

from dotenv import load_dotenv

load_dotenv()

python-dotenv 需要单独装。load_dotenv() 会把 .env 里的键值塞进环境变量，后面 init_chat_model 自己会去环境变量里找，不用手动传。

  1. 3 装哪个包

LangChain 1.x 把包拆得比较细，第一次看容易懵。搞清这四个就够了：

  1. langchain-core：地基，定义 Runnable、BaseMessage、BaseChatModel 这些抽象，几乎不带第三方依赖。你很少直接装它，但很多导入来自这里。

  2. langchain：上层封装，init_chat_model、create_agent 都在这。依赖 core，装它 core 会一起来。

  3. 集成包（langchain-openai、langchain-anthropic、langchain-ollama 等）：按需装，用哪家装哪家，不会因为要用 OpenAI 就被迫装一堆 Anthropic 依赖。

  4. langchain-community：社区维护的集成，量大但质量参差，用之前看一眼源码。另有一个 langchain-classic 是 0.x 遗留 API，新项目不用管。

图片

三、第一次调用

这一节跑三段代码：直接调模型、把提示词抽成模板、用 | 把两者接起来。三段合起来就是 LangChain 最基础的用法骨架。

  1. 1 一行接入模型
from langchain.chat_models import init_chat_model

model = init_chat_model("openai:gpt-5.5")

resp = model.invoke("用一句话解释什么是向量数据库")
print(resp.content)

init_chat_model 的字符串格式是 供应商:模型名。换成 anthropic:claude-sonnet-4-6 或 ollama:qwen3，只要装了对应集成包、配了对应的 key，其他代码一个字都不用改。这就是统一接口的实际手感。

invoke 的返回值是 AIMessage，有三个字段我们现在就认识下：

print(resp.content)             # 文本内容
print(resp.usage_metadata)      # token 用量
print(resp.response_metadata)   # 模型名、停止原因等

usage_metadata 会告诉你输入输出各花了多少 token。做成本估算的时候，这个字段是唯一可信的来源，别自己数字符。

传字符串是简写。完整写法是消息列表，用来给模型设定角色：

from langchain_core.messages import SystemMessage, HumanMessage

resp = model.invoke([
    SystemMessage("你是一个数据库领域的技术顾问，回答简洁，不说客套话。"),
    HumanMessage("向量数据库和传统数据库的核心区别是什么？"),
])
  1. 2 把提示词抽出来

上面的提示词是硬编码的。真实场景里它有变量，而且经常改。

from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_messages([
    ("system", "你是{role}，用{style}的风格回答，不要客套。"),
    ("human", "{question}"),
])

messages = prompt.invoke({
    "role": "数据库领域的技术顾问",
    "style": "简洁直接",
    "question": "向量数据库和传统数据库的核心区别是什么？",
})

prompt.invoke() 出来的是渲染好的消息列表，可以直接喂给模型。看着像是给 f-string 换了个写法，但模板是个对象，能单独测试、单独存成文件、单独做版本管理。提示词一多，这个差别就显出来了。

  1. 3 用管道符串起来

现在把两步接上：

chain = prompt | model

resp = chain.invoke({
    "role": "数据库领域的技术顾问",
    "style": "简洁直接",
    "question": "向量数据库和传统数据库的核心区别是什么？",
})
print(resp.content)

| 能这么用，是因为 prompt 和 model 都实现了 Runnable 协议：都有 invoke、batch、stream 这几个方法，都是输入进去输出出来。串起来得到的还是一个 Runnable，所以可以继续往后接。

接一个只取文本的解析器：

from langchain_core.output_parsers import StrOutputParser

chain = prompt | model | StrOutputParser()
print(chain.invoke({...}))   # 直接得到 str，不用再 .content

这个协议的价值在于所有零件可替换。检索器、自定义函数、另一个链，只要是 Runnable 就能接进管道。第 2 篇会拆开讲批量、重试、回退这些用法。

四、让输出变成能用的东西

模型默认给你的是一整段文本，而且要等它写完才返回。这两点都能改。下面先让返回值变成带类型的数据结构，再让它边生成边显示。

  1. 1 结构化输出

假设要从用户反馈里抽结构化信息。先用 Pydantic 描述你想要的模型：

from typing import Literal
from pydantic import BaseModel, Field

class Feedback(BaseModel):
    sentiment: Literal["正面", "负面", "中性"] = Field(description="整体情绪倾向")
    category: str = Field(description="问题所属模块，如登录、支付、性能")
    urgent: bool = Field(description="是否需要紧急处理")
    summary: str = Field(description="一句话概括，不超过 30 字")

然后一行绑定：

extractor = model.with_structured_output(Feedback)

result = extractor.invoke("付款页面点了三次都没反应，钱扣了订单没生成，急死了")
print(result.sentiment, result.category, result.urgent)
print(type(result))    # <class '__main__.Feedback'>

返回的直接是 Feedback 实例，字段类型经过校验，可以直接进数据库。没有正则，没有 json.loads，没有兜底分支。

Field 里的 description 不是注释，它会进到模型的提示里，写清楚他能明显提升抽取准确率。

  1. 2 流式输出

等模型憋完一整段再显示，用户会可能以为卡住了，交互不好。我们可以使用流式输出来逐字输出内容：

for chunk in chain.stream({"question": "..."}):
    print(chunk, end="", flush=True)

stream 和 invoke 一样是 Runnable 协议的一部分，管道里任何一段都支持。

五、给模型加工具

前面的例子模型只会说话。加上工具，它就能做事。

from langchain.agents import create_agent
from langchain_core.tools import tool

@tool
def get_order_status(order_id: str) -> str:
    """根据订单号查询订单状态。order_id 是形如 SO-12345 的字符串。"""
    fake_db = {"SO-12345": "已发货，预计明天送达", "SO-67890": "支付失败"}
    return fake_db.get(order_id, "未找到该订单")

agent = create_agent(
    model="openai:gpt-5.5",
    tools=[get_order_status],
)
system_prompt="你是电商客服助手。涉及订单状态的问题必须调用工具查询，不要凭猜测回答。",
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "帮我看下 SO-12345 到哪了"}]
})
print(result["messages"][-1].content)

@tool 装饰器做的事是把函数签名和 docstring 转成模型能理解的工具描述。所以那行 docstring 不是写给人看的，模型靠它判断什么时候该调这个工具、参数该传什么。描述含糊，模型就会乱调或者不调。

create_agent 内部是个循环：模型看到问题，决定调工具，框架执行工具把结果塞回对话，模型再看结果决定是回答还是继续调。这个循环跑几轮、什么时候停，都由模型自己判断。

图片

它返回的 result["messages"] 是完整的对话记录，把它打出来能看到整个过程：

for m in result["messages"]:
    print(type(m).__name__, ":", m.content)

你会看到 HumanMessage、AIMessage（带 tool_calls）、ToolMessage、AIMessage 这样一串。这是理解 Agent 行为最直接的办法。

顺带一提，create_agent 底层是 LangGraph 建的图，所以它天然支持 checkpointer 之类的能力。后面专门讲。

六、完整示例

把上面的零件拼成一个能跑的小工具：读入一段用户反馈，抽成结构化数据，再流式生成一句给客服看的处理建议。

from typing import Literal

from dotenv import load_dotenv
from langchain.chat_models import init_chat_model
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from pydantic import BaseModel, Field

load_dotenv()

model = init_chat_model("openai:gpt-5.5", temperature=0)

class Feedback(BaseModel):
    sentiment: Literal["正面", "负面", "中性"] = Field(description="整体情绪倾向")
    category: str = Field(description="问题所属模块，如登录、支付、性能")
    urgent: bool = Field(description="是否需要人工紧急介入")
    summary: str = Field(description="一句话概括，不超过 30 字")

extractor = model.with_structured_output(Feedback)

advice_chain = (
    ChatPromptTemplate.from_messages([
        ("system", "你是客服主管，根据工单信息给出一条处理建议，两句话以内，不要客套。"),
        ("human", "模块：{category}/n紧急：{urgent}/n概要：{summary}"),
    ])
    | model
    | StrOutputParser()
)

raw = "付款页面点了三次都没反应，钱扣了订单没生成，急死了"

ticket = extractor.invoke(raw)
print(f"[{ticket.sentiment}] {ticket.category} 紧急={ticket.urgent}")
print(f"概要：{ticket.summary}/n建议：", end="")

for chunk in advice_chain.stream(ticket.model_dump()):
    print(chunk, end="", flush=True)

四十行左右，用到了统一模型接口、提示词模板、管道组合、结构化输出、流式输出。temperature=0 是抽取类任务的常规选择，要的是稳定不是创意。

中间那句 ticket.model_dump() 是唯一的胶水代码，Pydantic 对象转成 dict 就能直接喂给下游链。前一步的输出天然对得上后一步的输入，这是用了框架之后最省事的地方。

如何学习大模型 AI ？

由于新岗位的生产效率，要优于被取代岗位的生产效率，所以实际上整个社会的生产效率是提升的。

但是具体到个人，只能说是：

“最先掌握AI的人，将会比较晚掌握AI的人有竞争优势”。

这句话，放在计算机、互联网、移动互联网的开局时期，都是一样的道理。

我在一线科技企业深耕十二载，见证过太多因技术卡位而跃迁的案例。那些率先拥抱 AI 的同事，早已在效率与薪资上形成代际优势，我意识到有很多经验和知识值得分享给大家，也可以通过我们的能力和经验解答大家在大模型的学习中的很多困惑。我们整理出这套 AI 大模型突围资料包：

  • ✅ 从零到一的 AI 学习路径图
  • ✅ 大模型调优实战手册（附医疗/金融等大厂真实案例）
  • ✅ 百度/阿里专家闭门录播课
  • ✅ 大模型当下最新行业报告
  • ✅ 真实大厂面试真题
  • ✅ 2026 最新岗位需求图谱

所有资料 ⚡️ ，朋友们如果有需要 《AI大模型入门+进阶学习资源包》，下方扫码获取~
在这里插入图片描述

① 全套AI大模型应用开发视频教程

（包含提示工程、RAG、LangChain、Agent、模型微调与部署、DeepSeek等技术点）
在这里插入图片描述

② 大模型系统化学习路线

作为学习AI大模型技术的新手，方向至关重要。 正确的学习路线可以为你节省时间，少走弯路；方向不对，努力白费。这里我给大家准备了一份最科学最系统的学习成长路线图和学习规划，带你从零基础入门到精通！
在这里插入图片描述

③ 大模型学习书籍&文档

学习AI大模型离不开书籍文档，我精选了一系列大模型技术的书籍和学习文档（电子版），它们由领域内的顶尖专家撰写，内容全面、深入、详尽，为你学习大模型提供坚实的理论基础。
在这里插入图片描述

④ AI大模型最新行业报告

2025最新行业报告，针对不同行业的现状、趋势、问题、机会等进行系统地调研和评估，以了解哪些行业更适合引入大模型的技术和应用，以及在哪些方面可以发挥大模型的优势。
在这里插入图片描述

⑤ 大模型项目实战&配套源码

学以致用，在项目实战中检验和巩固你所学到的知识，同时为你找工作就业和职业发展打下坚实的基础。
在这里插入图片描述

⑥ 大模型大厂面试真题

面试不仅是技术的较量，更需要充分的准备。在你已经掌握了大模型技术之后，就需要开始准备面试，我精心整理了一份大模型面试题库，涵盖当前面试中可能遇到的各种技术问题，让你在面试中游刃有余。

图片

以上资料如何领取？

在这里插入图片描述

为什么大家都在学大模型？

最近科技巨头英特尔宣布裁员2万人，传统岗位不断缩减，但AI相关技术岗疯狂扩招，有3-5年经验，大厂薪资就能给到50K*20薪！

图片

不出1年，“有AI项目经验”将成为投递简历的门槛。

风口之下，与其像“温水煮青蛙”一样坐等被行业淘汰，不如先人一步，掌握AI大模型原理+应用技术+项目实操经验，“顺风”翻盘！
在这里插入图片描述
在这里插入图片描述

这些资料真的有用吗？

这份资料由我和鲁为民博士(北京清华大学学士和美国加州理工学院博士)共同整理，现任上海殷泊信息科技CEO，其创立的MoPaaS云平台获Forrester全球’强劲表现者’认证，服务航天科工、国家电网等1000+企业，以第一作者在IEEE Transactions发表论文50+篇，获NASA JPL火星探测系统强化学习专利等35项中美专利。本套AI大模型课程由清华大学-加州理工双料博士、吴文俊人工智能奖得主鲁为民教授领衔研发。

资料内容涵盖了从入门到进阶的各类视频教程和实战项目，无论你是小白还是有些技术基础的技术人员，这份资料都绝对能帮助你提升薪资待遇，转行大模型岗位。
在这里插入图片描述
在这里插入图片描述

以上全套大模型资料如何领取？

在这里插入图片描述