D04-L3-LangChain入门

LangChain 入门：一文理解 LCEL，跑通你的第一个可运行链

适合人群：已能调用大模型 API、想系统学习 LangChain 的开发者

📌 引言：为什么值得学 LangChain？

自己用 SDK 调大模型很简单，但一旦任务变复杂——要做提示词模板、要接多个工具、要控制流程、要加记忆——代码就会失控。LangChain 是生态最全的 LLM 应用框架：模型接入、提示词管理、输出解析、记忆、工具、Agent、可观测，都有现成组件。

不过 LangChain 的版本迭代很快、旧教程遍地都是，很多初学者被过时的写法带偏。这篇文章只讲当前主流推荐的写法：LCEL（LangChain Expression Language），并给出可运行的完整示例。

一、LangChain 的核心抽象

用一句话建立心智模型：LangChain = 一堆组件 + 一种把它们串起来的语法（LCEL）。

抽象作用类比
ChatPromptTemplate管理提示词模板（system/human 消息）预制的"话术模板"
ChatModel封装大模型调用（OpenAI/通义/文心…）“大脑”
OutputParser解析模型输出（纯文本/JSON/结构化）“翻译官”
Runnable可执行单元，一切组件的统一接口乐高积木
LCEL 管道|把 Runnable 串成链积木的拼接槽

核心洞察：在 LangChain 里，几乎一切都是 Runnable——模型是、解析器是、模板是、整条链也是。它们都能被|拼接，这是 LCEL 的基础。

二、LCEL 是什么？为什么推荐它？

LCEL 是 LangChain 提供的声明式管道语法，本质就是 Python 的|运算符重载：

chain=prompt|model|parser
  • prompt输入用户的原始问题，输出标准消息；
  • model接收消息，输出模型响应；
  • parser把响应转成干净文本。

数据像流水线一样从左到右流动，每一步的输入是上一步的输出。对比旧写法（LLMChain(prompt=..., llm=...)），LCEL 的优势：

  1. 写法直观：流水线一目了然，新人很快就能读懂；
  2. 原生并行/流式/异步：.batch()、.stream()、.ainvoke()开箱即用；
  3. 易组合：链本身也是 Runnable，可以被更大的链嵌套；
  4. 官方主推：新功能都优先在 LCEL 上实现，旧 API 在逐步淘汰。

三、快速上手：跑通第一个 LCEL 链

3.1 准备工作

pipinstalllangchain langchain-openai

并设置环境变量OPENAI_API_KEY。

3.2 示例一：最简问答链（三个组件拼一条链）

fromlangchain_core.promptsimportChatPromptTemplatefromlangchain_openaiimportChatOpenAIfromlangchain_core.output_parsersimportStrOutputParser# 1) 提示词模板：声明 system 与 human 两段消息，用 {变量} 占位prompt=ChatPromptTemplate.from_messages([("system","你是一位严谨的{role}，请用简洁的中文回答，不要编造事实。"),("human","{question}"),])# 2) 模型：指定模型与采样参数model=ChatOpenAI(model="gpt-4o-mini",temperature=0)# 3) 输出解析器：把模型响应转成纯字符串parser=StrOutputParser()# 4) LCEL 管道：拼成一条链chain=prompt|model|parser# 5) 调用：传入模板中的所有变量answer=chain.invoke({"role":"技术顾问","question":"什么是向量数据库？它和普通数据库有什么区别？",})print(answer)

运行后会输出一段中文回答。整个链条只有 4 行核心代码，且chain.invoke({...})传入的字典恰好填满模板变量——这就是 LCEL 的"约定优于配置"。

3.3 示例二：并行分发 + 汇总（感受 LCEL 的组合能力）

业务里常需要"先并行收集多个角度的答案，再汇总"。LCEL 用RunnableParallel一行搞定：

fromlangchain_core.runnablesimportRunnableParallel# 三个并行分支：各自独立的提示词 + 模型 + 解析器branch_a=ChatPromptTemplate.from_template("从【优点】角度评价：{topic}")|model|parser branch_b=ChatPromptTemplate.from_template("从【风险】角度评价：{topic}")|model|parser branch_c=ChatPromptTemplate.from_template("用一句话总结：{topic}")|model|parser# 并行执行三分支，结果以字典形式汇总parallel=RunnableParallel(优点=branch_a,风险=branch_b,总结=branch_c)# 再拼一个汇总链final=parallel|ChatPromptTemplate.from_template("请综合以下三个视角输出完整结论：\n{优点}\n{风险}\n{总结}")|model|parser result=final.invoke({"topic":"把 AI Agent 引入客服系统"})print(result)

💡 三个分支会并发执行（同一批请求），比串行调用快 3 倍。RunnableParallel 的每个 key 对应一个分支，输出直接作为下游模板的变量。

四、LCEL 与旧写法对比：别再学过时代码

网上大量教程还在用这类旧写法：

# ❌ 旧写法（已不推荐）fromlangchainimportLLMChain chain=LLMChain(prompt=prompt,llm=model)
# ✅ 现代写法（LCEL）chain=prompt|model|parser

判断新旧的标准：看from langchain import还是from langchain_core import。凡是直接from langchain import ...的教程大概率过时。LangChain 现在把核心抽象拆到langchain-core，模型接入放在各家的扩展包里（如langchain-openai、langchain-community），组件更清晰、依赖更轻。

五、刚上手最容易踩的 3 个坑

5.1 坑一：invoke 参数没传全

chain.invoke({"role":"技术顾问"})# ❌ 缺少 questionchain.invoke({"role":"技术顾问","question":"..."})# ✅

模板里声明了几个变量，invoke就必须传全，否则报KeyError。排查时先看模板里的{}占位符。

5.2 坑二：把旧 API 当新 API 用

报错ModuleNotFoundError: No module named 'langchain.llms'之类，多半是教程太老。装包时优先langchain-openai而不是langchain[openai]；拿不准就看官方文档（docs.langchain.com）的示例，别照抄博客。

5.3 坑三：忽略流式与异步

LCEL 的.stream()能在首 token 到达后立刻输出，是做聊天体验的刚需；.ainvoke()/.abatch()用于异步场景。上手时顺手把invoke换成stream体验一下逐字输出，后面做产品会少走很多弯路。

六、常见报错速查表

报错信息常见原因处理办法
ModuleNotFoundError: langchain.llms教程/代码过时改用langchain_openai.ChatOpenAI
KeyError: 'question'invoke 变量没传全对照模板{}占位符补全参数
OutputParserException模型输出不符合解析格式换结构化输出或在提示词中强调格式
RateLimitError触发限流加指数退避重试、降并发
中文乱码 / 编码异常终端编码或响应解析问题统一 UTF-8，检查 print 环境
AttributeError: 'RunnableLambda' has no attribute ...自定义函数签名不符函数参数改为单个 dict 输入

记不住没关系：先看报错出处（哪个包），再查该包的官方文档，比搜博客靠谱。

七、给新手的两个练习

练习 1：角色参数化
把示例一的role分别换成"法务顾问"“健身教练”“小学老师”，各问同一个问题，观察回答风格的差异。感受 Prompt 模板里"角色设定"对输出的影响。

练习 2：扩展并行分支
给示例二的RunnableParallel增加第四个分支"从【实施成本】角度评价"，并在汇总模板中加入{成本}，跑通后你就掌握了 LCEL 并行扩展的套路。

做完这两个练习，你已经能独立拼装"多视角分析链"，这是做 Agent 前最有价值的一步热身。

八、下一步学什么？（学习路径建议）

阶段内容难度
本课LCEL 基础链、并行、输出解析入门
进阶记忆（对话历史）、检索（RAG 接入）进阶
高阶工具调用、Agent、状态图（LangGraph）高阶
工程可观测（LangSmith/Langfuse）、部署工程

学习心法：先吃透"一切皆 Runnable、管道即组合"，LangChain 的其余功能都是在这两个概念上长出来的。

✅ 总结

  • LangChain 的三大核心抽象：模板、模型、解析器，全部统一为 Runnable；
  • LCEL 用|管道把组件串成链，推荐取代旧LLMChain写法；
  • RunnableParallel一行实现并行分支，stream/batch/async开箱即用；
  • 判断教程新旧看 import 来源：langchain_core才是现代写法；
  • 上手路线：基础链 → 并行组合 → 记忆 → 检索 → Agent → 可观测。

📌 觉得有用就点赞 + 收藏 + 关注，更多 AI Agent 干货持续输出。