LangChain从零到实战：核心组件、LCEL与Agent编排指南

提到 LangChain，不少同学的第一反应是：“又一个大模型套壳框架？”。但如果你真的用一段时间就会发现，它更像是一个“乐高积木箱”，专门用来把大模型、提示词、外部数据和各类工具拼装成真正可用的应用。这半年来我从只会调 API 的“调用工”，到能独立搭建带记忆、能联网查资料、会调用工具的多智能体 Demo，全靠一点点啃 LangChain 的源码和官方文档。这系列笔记的第一篇，我想认认真真聊聊“从零认识 LangChain”——它到底是什么、核心组件有哪些、第一次写代码该走哪条路，以及网上那些“LangChain vs Dify vs CrewAI”的争论到底该怎么看。这篇不堆概念，只看实际能落地的部分，适合刚入门、想搞清 LangChain 定位的同学慢慢看。

1. 项目概述：LangChain 到底是什么

1.1 大模型时代的“胶水层”与编排器

LangChain 这个词拆开看是 Lang + Chain，官方定位是“使用大语言模型构建应用的框架”。我最初的理解是，它把大模型（LLM）包装成可以随意组合的单元，让你用一组“链”把提示词、模型、外部数据、工具串起来。但用得深了以后，我更愿意把它称作“LLM 应用开发的编排与胶水层”：大模型是发动机，LangChain 是变速箱和仪表盘——它定义了各类组件之间如何协作、如何流转数据、如何被复用，让你不太需要关心底层是 OpenAI 还是本地开源模型。

这背后对应的是一个很实际的痛点：单个 LLM 调用其实是“无状态、纯文本到纯文本”的映射，但现实应用需要复杂流程，比如先查数据库、再拼提示词、再调模型、最后格式化输出；或者多轮对话时需要记住上下文；或者需要决策走哪条分支。用原生代码来做，每个项目都要写一套重复逻辑，维护成本极高。LangChain 的价值就在这里：它把“链式调用+状态管理+工具调用”这些高频模式抽象成通用组件，替你把脏活累活扛了，开发者的精力只需投入到真正的业务逻辑上。

这个定位对初学者特别重要。因为当你看到网上各种“LangChain 死了”“LangChain 太抽象”的吐槽时，如果先清楚它本质是胶水层和编排器，就能明白——吐槽者多半是在批评它的 API 演进速度和学习曲线，而不是质疑“应用构建需要编排抽象”这件事本身。这也是我写下整个系列笔记的出发点：先理解它是什么、解决什么问题，再去学怎么用，才能不被版本变化的噪声带偏。

1.2 它能解决什么问题，适合哪些人学习

从实际应用场景来说，LangChain 最容易帮上忙的是三类事情：一是做知识库问答（RAG），把文档切块、向量化、检索，再配合大模型出具回答；二是做带工具的智能体，比如让模型决定“要不要查天气/要不要调计算器/要不要访问内网文档”，从而完成单次 LLM 调用做不到的复合任务；三是做业务流的可视化编排，把多个模型调用组合成一条流水线，支持分支、合并、并行。

我的感受是，如果你只是想快速调一下大模型的 API 做个小工具，直接用 OpenAI SDK 就够了，LangChain 属于“锦上添花”；但如果你要构建一个稍具规模的应用，比如包含数据流转、多轮对话、工具调用、日志追踪的完整服务，那 LangChain 的抽象便能让代码结构清晰不少。它最适合的人群有三类：正在做 LLM 应用落地的后端开发者、想系统学习智能体编排的 AI 应用工程师，以及准备用 Agent 类框架做产品原型的技术决策者。这篇文章虽然是“从零认识”, 但我会尽量带实操视角，即便完全没接触过 LangChain 也能跟着步骤走。

2. 核心组件与设计思路拆解

2.1 六大核心抽象：Model、Prompt、Chain、Memory、Agent、Indexes

LangChain 最迷人的地方在于：它用非常少的几个抽象就覆盖了 LLM 应用背后几乎所有的高频模式。我总结下来，核心组件可以分成六类：模型（Model）、提示词（Prompt）模板、链（Chain）、记忆（Memory）、智能体（Agent）以及索引/向量库（Indexes）。

模型是最底层的引擎，LangChain 通过统一接口兼容 OpenAI、Anthropic、百度文心、本地 Ollama 等，好处是你写业务代码时可以少关注具体模型厂商的 SDK 差异。提示词模板解决的是“动态拼字符串”的痛点，它定义了一个带变量的模板，运行时再填充具体内容，避免在业务代码里手动拼接 Prompts。链则是串联模型和提示词的最小执行单元，比如经典的“提示词 + 模型 + 输出解析”就是一个最简链。这也是后来 LangChain 力推 LCEL（LangChain Expression Language）的原因：用|符号像 Unix 管道一样把组件串起来，直观且天然支持流转和并行。

记忆模块用于多轮对话场景，存储历史消息并在下一步生成时注入上下文。智能体则让模型具备“决策能力”——它根据用户问题判断该调用哪个工具，拿到工具返回值后再决定下一步动作。索引/向量库是 RAG 的基础，负责文档加载、切分、向量化并存入向量数据库（如 Chroma、FAISS、Pinecone），检索时把最相关的片段取出来作为上下文。

这六大抽象并不是割裂的，它们会在一个应用中协同出现：索引提供外部知识，提示词把它组织成模型能理解的语言，模型生成结果，链控制流程流转，记忆保留上下文，智能体决定是否调用额外工具。把这套骨架先记住，后面学任何模块都会觉得有地图可循。

2.2 设计逻辑：为什么是“链”，而不是普通函数封装

如果只是“按顺序调用”几个函数，那不叫框架，写个 Python 脚本也能做。LangChain 之所以把“链”作为一等公民，是因为 LLM 应用的执行流往往不是纯线性的：有时需要并行处理多个独立任务，有时需要根据中间结果动态跳转，有时还要嵌入重试、回退、流式输出等逻辑。如果这些都用普通函数硬编码，业务代码很快就会被各种控制流淹没。

链的设计其实借鉴了 Unix 哲学中的“管道”：每个组件实现统一的输入输出协议，上一个组件的输出自动成为下一个组件的输入，组件的组合方式因此变得非常灵活。LangChain 的 Runnable 协议（包含invoke、stream、batch等方法）就是这一思想的现代实现，它让“链”可以像乐高积木一样被自由拼装、嵌套与并行化。

这背后的另一个考量是稳定性与可观测性。把各个步骤抽象成链以后，你可以在每个环节插入日志、追踪 token 消耗、设置超时与重试，这对生产级应用非常重要。我自己踩过不少“全链路一个函数”的坑——上线前跑得通，一旦某段 API 超时或返回非预期格式，排查起来非常痛苦。使用链模式之后，日志能清楚标出是哪一步“断了”，定位问题的时间能少一半。

2.3 从旧版到 LCEL：现代 LangChain 的核心变化

LangChain 过去两年的版本演进堪称剧烈，如果你翻到两年前的教程，会看到大量LLMChain(prompt=..., llm=...)的用法；而现在官方推荐的是 LCEL 写法：直接prompt | llm | output_parser串成一条可执行链。这个变化很关键，因为旧版把“链”搞成了一系列难以组合的类，而新版用统一的 Runnable 协议，让组合、流式、异步都变成内建能力。

举个例子，在旧版里你想让模型流式输出文本，通常得特意去调用llm.stream()，但同一个链换到另一个模型厂商，流式支持还得单独适配。LCEL 出现以后，任何 Runnable 都天然支持.stream()、.invoke()、.batch()，不用关心内部实现细节。对于初学者，我强烈建议直接学新版 LCEL，因为这是 LangChain 所有新功能和教程的基础，未来生态也会围绕它扩展。

那旧版代码还有必要了解吗？说实话，偶尔用到老项目维护时还是需要的。但如果你是新项目，直接跳过旧 API，能在长期上省掉非常多的“改接口”痛苦。我的建议是：遇到教程里还在教LLMChain的，谨慎参考；优先看官方文档中带“Runnable”或“LCEL”字样的章节。

3. 从零开始的实操入门

3.1 环境准备与依赖安装

不管是什么阶段的 LangChain 学习，第一步都离不开环境搭建。我个人习惯用 Python 3.10+ 版本，跑 LangChain 生态最省心；推荐新建一个虚拟环境，避免和系统 Python 打架。核心依赖就两个：langchain和对应模型的适配包，比如langchain-openai或langchain-anthropic。如果你只想先跑通最小 Demo，装这两个就够了。

python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install langchain langchain-openai

这里有个细节很多人会忽略：LangChain 本身是“内核”，而不同模型厂商的适配包是独立的。这意味着以后新增模型厂商时不必把整个框架重装一遍，只需要单独装对应适配包即可。比如你用本地 Ollama，就多装一个langchain-ollama；用智谱就装langchain-zhipuai。这种“内核与集成分离”的架构，既是 LangChain 生态迅速扩大的原因，也是初学者容易困惑的地方——看到教程里装了一堆包时，先分清哪些是框架、哪些是模型适配包，会清晰很多。

3.2 使用 LCEL 构建第一条链

安装完成后，进入第一个 Demo：用 LCEL 构建一条“翻译小助手”链。这个过程会涉及三个核心组件：提示词模板、ChatModel 和字符串输出解析器。我用的是langchain-openai中的ChatOpenAI，如果你没有 OpenAI 密钥，可以换成任何你手头可用的模型，但 API 调用参数要以适配包为准。

from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser # 1. 定义提示词模板 prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个专业翻译，请把用户输入翻译成英文。"), ("user", "{input}") ]) # 2. 初始化模型，这里建议把 temperature 调低一点，翻译任务需要确定性 model = ChatOpenAI(model="gpt-4o-mini", temperature=0.2) # 3. 用一个最简输出解析器，保证拿到的是纯字符串 output_parser = StrOutputParser() # 4. 用 LCEL 管道符串联起来 chain = prompt | model | output_parser # 5. 调用链 result = chain.invoke({"input": "我爱编程，尤其是写能自动处理麻烦事的代码。"}) print(result)

跑完的预期结果大致是 “I love programming, especially writing code that automates tedious things.”。注意chain.invoke传入的是一个字典，它对应提示词模板里定义的{input}变量，这个机制就是前面提到的“模板运行时填充”的体现。

这条链虽然只有短短几行，但背后已经包含了“格式化提示词→调用模型→解析输出”的完整流程。如果你对运行过程好奇，可以在链的中间加入.with_config({"run_name": "translation_chain"})，LangChain 会自动记录每个步骤的输入输出，在 LangSmith 之类的调试工具里一目了然。初学者先不要管太多高级特性，先把这条最小链跑通，再逐步增加模块，你会更容易理解每一步在业务中的价值。

3.3 用结构化输出连接真实程序

字符串输出对展示来说足够，但要对接真实业务系统，通常需要模型返回结构化数据（如 JSON）。LangChain 提供了with_structured_output()方法，配合 Pydantic 类可以非常方便地拿到校验过的结构化结果。这一步对“从零认识”阶段的同学可能稍显进阶，但我还是建议尽早接触，因为它能立刻让 LangChain 从“玩具”变成“生产工具”。

from typing import Literal from langchain_core.pydantic_v1 import BaseModel, Field class TranslationResult(BaseModel): translated_text: str = Field(description="翻译后的文本") tone: Literal["formal", "casual"] = Field(description="语气风格") confidence: float = Field(description="置信度，0-1之间") structured_model = model.with_structured_output(TranslationResult) structured_chain = prompt | structured_model res = structured_chain.invoke({"input": "帮我翻译：今天天气不错，适合出门散步。"}) print(res.translated_text, res.tone, res.confidence)

这里with_structured_output做的事情是：把 Pydantic 类的 schema 传给模型，让模型按 schema 生成 JSON 并自动完成类型校验。如果模型返回的格式不符合定义，框架会直接抛错，避免你在下游代码里手写一堆“字段存在性”判断。这种模式在写 API 接口、数据入库、多智能体协作等场景中特别实用。

我印象最深的是一个内部知识库问答项目：早期直接让模型吐 JSON，但模型偶尔会多出或遗漏字段，导致下游解析崩溃。换成with_structured_output后，这类问题基本消失，代码量还减少了一大截。可以说，学会结构化输出之后，你才真正体会到 LangChain “把模型变成可靠函数”的设计野心。

3.4 给链加记忆：从无状态到多轮对话

第一版链是无状态的，你问它“我爱编程”，它不会记得上一句。要实现多轮对话，就需要引入 Memory（记忆）机制。LangChain 新版推荐的做法是把聊天历史显式传入提示词模板，比如把消息数组构建成System + History + 当前输入的形式，而不是用旧版自动 Memory 类，后者内部隐式管理状态，在并发场景下容易串戏。

from langchain_core.messages import SystemMessage, HumanMessage, AIMessage history = [ SystemMessage(content="你是一个贴心的助理。"), HumanMessage(content="我叫小明。"), AIMessage(content="你好小明，很高兴认识你！"), ] # 再次调用时，直接把历史消息和当前问题拼接 messages = history + [HumanMessage(content="我叫什么名字？")] response = model.invoke(messages) print(response.content)

把“显式传历史”和“无状态链”结合起来，是我目前觉得工程上最稳妥的记忆方案——每个请求都带上完整上下文，天然适合无状态部署、水平扩展和调试。LangChain 社区也提供了很多记忆封装类，但我的体会是：小项目可以用封装类图省事，稍大一点的项目最好还是自己组装消息列表，做到“可见即可控”。

4. 工具调用与智能体初体验

4.1 给模型装“手”：定义工具与 Tool 接口

LangChain 的智能体能力，很大程度上源自“让模型调用工具”这件事。想要让模型调用工具，你首先得定义工具。LangChain 里最简洁的方式是把一个普通的 Python 函数加上@tool装饰器，让它变成模型可感知的工具。

from langchain_core.tools import tool @tool def get_weather(city: str) -> str: """查询指定城市的天气，返回温度与风力描述。""" # 正常情况下这里应接入真实天气 API if city == "北京": return "多云，20°C，微风" return f"{city}：晴，24°C，南风3级" tools = [get_weather]

对初学者来说，这里的要点有两个：一是函数的 docstring 会被当作工具描述传给模型，模型靠它判断“什么情况该调用这个工具”，所以描述要写清楚用途；二是函数签名里的参数名和类型很重要，模型会按照这些 schema 来填充参数值。我经常把这个过程类比为教实习生：你得告诉他“在什么情况下用什么工具、工具需要哪些材料、会得到什么结果”，他才能靠谱地干活。

4.2 从“工具列表”到“Agent”：理解 ReAct 循环

有了工具之后，怎么让模型自主决定是否调用？答案是通过 Agent（智能体）的 ReAct 循环。ReAct 的思路是：模型先思考（Reason），决定要调哪个工具（Action），观察工具返回值（Observation），再思考下一步，直到得出最终答案。

LangChain 中创建 Agent 的常见写法是使用create_tool_calling_agent（针对支持工具调用的模型）或create_react_agent（通用 ReAct 风格）。以最简单的 ReAct 为例，你需要准备三样东西：模型、工具列表和一个提示词模板，模板里定义好 “Question/Thought/Action/Observation” 的格式。

from langchain.agents import create_react_agent, AgentExecutor from langchain_core.prompts import PromptTemplate agent_prompt = PromptTemplate.from_template( """你可以使用工具来回答问题。 工具列表: {tools} 工具名称: {tool_names} 请按以下格式输出: Thought: 你当前的想法 Action: 要使用的工具名称，如果无需工具则写 None Action Input: 工具的输入参数 Observation: 工具返回的结果 ...（循环）... Final Answer: 最终答案 用户问题: {input} {agent_scratchpad}""" ) agent = create_react_agent(model, tools, agent_prompt) executor = AgentExecutor(agent=agent, tools=tools, verbose=True) res = executor.invoke({"input": "北京今天适合穿短袖吗？"}) print(res["output"])

agent_scratchpad是 LangChain 自动填充的中间思考记录，它会存放模型之前的 Thought/Action/Observation 历史，保证多轮推理时上下文不丢失。运行上面的代码，你会看到模型输出：Thought（思考先查天气）、Action（get_weather）、Action Input（北京）、Observation（多云 20°C）、最终判断“建议穿薄外套”。如果把verbose=True打开，运行日志会显示出完整的“思考-行动-观察-答”轨迹，这个过程很上瘾——你会觉得模型真的有在“想事情”。

4.3 多工具协作与 Agent 决策的艺术

真实业务中的 Agent 通常不止一个工具。当工具多起来以后，模型的“决策质量”就成了关键。我常用的技巧是：尽量让工具职责单一、描述清晰，并在描述里加上“何时使用、何时不要使用”的边界。例如get_weather可以写成“仅当用户询问天气时使用，不要用于推荐穿搭”。

多工具协作时，LangChain 会依据模型厂商的工具调用能力来决定是并行还是串行调用。比如 OpenAI 的 function calling 支持一次请求返回多个工具调用，LangChain 会在底层解析成多个 ToolMessage 然后再次交给模型。如果你要用本地小模型，通常不支持并行工具调用，只能靠 ReAct 一步一步来。这也是框架对比中常被忽略的一点：不是所有模型都能发挥 Agent 的全部能力，选型时要考虑底层模型对工具调用的原生支持度。

我自己做过的多工具 Demo 是一个“旅行小助手”：它拥有查天气、查汇率、查新闻、生成行程清单四个工具，用户只需要用一句话描述需求，它会自动安排调用顺序。整个过程跑通后非常有成就感，而且代码复用率很高——往工具列表里再塞一个新函数，Agent 就能“解锁”一项新技能。

5. 生态比较与选型建议：LangChain、Dify、CrewAI 怎么选

5.1 三类框架的定位差异

网上高频出现的对比是“LangChain、Dify、CrewAI 哪个好”，我在实际跟项目后得出的结论是：这三个框架根本不在同一维度上，硬比“哪家强”没有意义，关键是弄清楚各自的定位。

LangChain 本质是一个开发框架/工具库，面向的是会写代码的开发者。它灵活度高，能深度定制各类链和智能体逻辑，但需要你自己处理部署、前端、数据库等周边系统。Dify 则更像一个 LLM 应用平台/产品，它提供可视化工作流编排、内置知识库管理、API 发布管理等能力，甚至面向不太写代码的运营和产品人员。CrewAI 专注于多智能体协作，强调“角色扮演式的团队”——你定义不同 Agent 的角色、目标和任务，让它们像同事一样协同完成复杂工作。从技术角度出发，三者可以结合使用：用 LangChain 写核心逻辑，用 Dify 做产品化界面，用 CrewAI 管团队分工。

5.2 按项目阶段选择：原型期、生产期、团队协作期

选型不能只看技术，还要看项目阶段和团队构成。我建议按这样来评估：

• 如果你在做一个创新原型，需要快速验证“这个 Agent 逻辑能否跑通”，LangChain 是最佳选择，因为它即插即用、组件丰富，写代码少但开放度高。
• 如果你已经确定要做成一个面向用户的产品，需要管理后台、可视化调试、数据标注、审核流等能力，Dify 这类平台能让你免掉很多基础设施工作，尤其是在非技术成员也要参与维护的场景下。
• 如果是复杂任务拆解，比如“写一份行业研究报告”需要让多个 Agent 分别做资料搜集、数据分析和文案撰写，CrewAI 的团队编排效率会更直观。
• 另外要留意成本和锁定效应。用 Dify 这类平台，很多逻辑在界面上配置，但一旦要做超出平台能力的定制，反而更麻烦。用 LangChain，代码可控性高，但迭代速度依赖你的工程能力。

结合我自己的项目经验，我现在的标准姿态是：小 Demo 和中期项目用 LangChain 快速搭骨架；做内部工具或客户产品时，后端核心逻辑可以保留 LangChain，前端管理界面考虑其他可视化层；多角色协作的复杂 Agent 系统才引入 CrewAI 做上层协调。换句话说，LangChain 是“地基”，其他框架可以理解成“装修公司”，它们并不互斥。

5.3 避免框架锁定的实用心法

框架迭代速度是 LangChain 被诟病最多的点，这一风险确实存在。我在文章前面也提到，LangChain 的 API 变化相当快，如果你把所有业务代码深度绑定到 LangChain 的类上，一旦升级大版本可能要重构不少代码。我的经验是：建立一个薄薄的门面层，把业务代码与框架代码隔离开来。简单来说，就是在自己的项目里写一个llm_client.py，封装所有模型调用、链构建、智能体创建逻辑，业务层只依赖这个门面暴露的几个函数。

这样做的好处是，即使以后要换掉 LangChain 或者迁移到别的框架，你只需要改门面层一个文件，而不至于把整个业务逻辑重写。我在一个客服机器人项目中实践过这种方式，后来因为模型商优惠政策变动需要更换供应商，只改了不到一百行代码就完成了切换，团队同事都直呼“这层抽象值回票价”。

6. 常见问题与排查技巧实录

6.1 运行时报错频繁的几种原因

LangChain 版本的频繁迭代，加上不同模型适配包的差异，初学者在跑代码时几乎都会遇到报错。我把最常遇到的几类问题整理成了速查表，方便你对照排查：

经验告诉我，遇到报错先看版本号。LangChain 的__version__几乎每隔几周就会变，一旦你在一个项目里锁了版本，其他项目升级时很可能“殃及池鱼”。建议在项目里用 requirements.txt 或 pyproject.toml 严格固定版本，方便复现。

6.2 如何高效阅读官方文档与源码

LangChain 官方文档的入口非常多，初学者最常用的是概念（Concepts）和教程（Tutorials）两个板块。我的经验是：先快速浏览一遍核心概念，再对照教程动手敲代码，遇到不理解的组件就去源码里搜定义。源码阅读这条路非常值，因为 LangChain 的组件大多是薄封装，源码注释也相对清晰，直接看Runnable、BasePromptTemplate、BaseChatModel这些基类的实现，会帮你省下大量试错时间。

6.3 调试利器：Verbose、LangSmith 与 tracing

调试 Agent 应用时，最痛苦的地方在于“模型心里怎么想的”你看不到。这时候首要工具就是把 AgentExecutor 或链的verbose=True打开，它会打印模型每一步的思考、行动和观察记录。另一个更强的手段是接入 LangSmith，它是 LangChain 官方可观测性平台，开启 tracing 后，你会看到一次请求内部的完整调用树，包括每次 LLM 调用的输入输出、工具响应、耗时和 token 数。

我之前排查一个“Agent 在特定问题下陷入死循环”的 bug，靠的就是 LangSmith 的 trace：模型反复调用同一个工具但忽略返回结果，原来是工具返回值里缺少明确的“终止信号”。修改工具返回内容和提示词边界后，死循环自然消失。这类问题如果没有 trace 数据，靠猜几乎不可能定位。对初学者，我建议把LANGCHAIN_TRACING_V2=true和LANGCHAIN_API_KEY配好，一开始就养成观测的习惯。

6.4 学习路径建议：不要一上来就啃 Agent

最后聊聊学习路径。我发现很多初学者犯同一个错：一上来就搞 Agent、搞 ReAct，结果被各种抽象绕晕。更稳的路径是先掌握 Prompt 模板和 Model 调用，再用 LCEL 做一条包含输出解析和记忆的链，最后才进入 Agent 和工具调用。每一步都把前面的基础吃透，再往上叠加。拿我做类比，一切复杂应用都是“提示词—链—智能体”三种层次的组合：提示词是沟通的语言，链是把语言组织成流程，智能体是让流程自动决策。把这个层级想清楚，LangChain 就会变成一张随手能画出的地图，而不是一团乱麻。

LangChain 的最佳学习方式，永远是手写代码而不是收藏教程。你可以拿它做一个小项目，比如个人知识库问答助手、邮件自动分类器或旅行规划师，从最小功能开始迭代。框架本身只是工具，它背后的设计思想才是真正能在 LLM 应用开发中持续受用的财富。这篇笔记只是系列的第一篇，后续我会继续拆解 RAG 落地的完整流程、各种记忆方案在实战中的取舍，以及自建 Agent 的踩坑复盘。如果你在跟着实操时遇到什么奇葩报错，欢迎留言探讨，我会尽量把自己验证过的解法拎出来分享。