LangChain 速成课的坑我替你先踩了一轮。最近半年找我咨询 LLM 应用怎么落地的朋友越来越多十个里有八个会问同一句话LangChain 到底是套壳还是真有必要我的回答通常是——它确实是套壳但套得好不好直接决定你后续能不能把一个原型快速变成一个能维护的产品。用 Python 去构建 OpenAI LLM 驱动应用LangChain 是目前我实测下来最顺手的那套“脚手架”。这篇是系列的第一部分目标非常具体带你从零搭好环境完成第一个真正可运行的 LangChain 应用并拆清楚 Prompt Template、LLM、Output Parser 这三块核心模块是怎么串起来的。适合两类人看一类是刚接触大模型开发的 Python 开发者另一类是已经在裸调 API、但被代码越写越乱逼疯的初级工程师。看完你至少能回答三个问题——LangChain 的 Chain 到底链了什么、为什么推荐用 LCEL 管道写法、以及报错之后怎么快速定位。1. 先想清楚再动手LangChain 和 OpenAI 在这个项目里各自扮演什么角色1.1 LangChain 不是魔法它是一套“积木 说明书”很多人第一次看 LangChain 的文档会觉得头晕因为概念名词太多了Chain、Agent、Memory、Retriever、Tool、Callback……好像每个都很重要每个又都不知道什么时候用。我的理解方式很简单LangChain 就是一套乐高积木把大模型应用开发里那些“反复出现的标准动作”封装成了一个个带标准接口的零件。什么叫标准动作举例来说调用一个 LLM 时你需要准备提示词、拼接上下文、调用接口、解析返回结果、处理异常。裸写 OpenAI SDK 时这套逻辑你得自己组织但 LangChain 把它拆成了几个独立组件让它们各司其职PromptTemplate 负责拼提示词ChatOpenAI 负责模型调用OutputParser 负责把模型回答转成结构化数据。然后 LangChain 提供了一种统一语法把这些组件粘合成一条链。所以不要指望 LangChain 能提升模型本身的智商它不会让你的 GPT-4o 变聪明。它的价值在于三点第一组件可以单独测试、单独换掉今天用这家模型明天换那家模型改动成本极低第二团队协作时大家有统一的抽象层代码评审能聊到具体点上去第三官方维护了大量周边集成向量库、网页检索、外部工具都是插上去就能用。1.2 这个速成项目到底要做什么为了不让你陷入“学了一堆概念却不知道用来干嘛”的状态我们把整个系列的第一部分收敛成一个很小的目标做一个命令行问答程序。它接收用户输入的问题从 OpenAI 的 chat 模型拿回答并把回答以干净的、格式可控的方式打印出来。这个程序会有三个逐步升级的版本。第一个是最小 Demo只验证 API 连通性第二个引入提示词模板让程序能切换不同角色来回答问题第三个加入输出解析器让程序可以输出 JSON 结构化数据。三个版本对应 LangChain 三个最核心的抽象LLM 封装、PromptTemplate、OutputParser。等你把这三块吃透再往后学 Agent、Memory、RAG就是顺水推舟的事。顺带说下技术选型。语言用 Python 3.10 以上框架用 LangChain 0.2.x 或 0.3.x 系列写这篇时 0.3 已经比较稳定模型接口统一走 langchain-openai 这个专用包。为什么不直接用 langchain 老包里那个OpenAI类因为新版 LangChain 做了包拆分模型提供商相关的内容都独立出去了老写法在新版本里会被标记为 deprecated与其之后迁移不如一开始就用新结构。1.3 版本和依赖选择一个表格说清楚装依赖之前先把版本坑点讲明白这能省掉不少排查时间。LangChain 生态现在的版本节奏非常快小版本升级偶尔会改接口。我的建议是项目里锁定主版本不要追最新。下面是推荐的依赖清单和用途。依赖包版本建议用途langchain0.2.x / 0.3.x核心抽象PromptTemplate、Chain 的基础langchain-openai0.1.x / 0.2.x提供 ChatOpenAI、OpenAIEmbeddings 等封装python-dotenv1.x从 .env 文件读取密钥pydantic2.x定义结构化输出模型openai1.xlangchain-openai 的底层依赖会被自动安装我踩过的坑是直接pip install langchain后忘了装langchain-openai结果导入from langchain_openai import ChatOpenAI直接 ModuleNotFoundError。这个包不会跟随核心库自动安装必须手动装。另外强烈建议在虚拟环境里做。Python 项目最痛苦的事情之一就是全局环境里依赖互相打架llama 项目要的 numpy 版本和 LangChain 要的冲突起来能折腾一下午。用python -m venv .venv建环境激活后所有依赖都装在里面删掉重来也毫无心理负担。2. 半小时搭好环境从零初始化一个 LangChain 项目2.1 动手第一件事把密钥管好环境准备阶段很多人只关注代码能不能跑忽略了一件事API 密钥怎么安全地传给程序。我看到过无数人把密钥直接写死在.py文件里然后一不小心把代码传到公共仓库几分钟后密钥就被爬虫拿走刷爆账单。正确做法是用环境变量或者用 .env 文件配合 python-dotenv 加载。创建一个新目录作为项目根目录。按下面的结构组织langchain-quickstart/ ├── .env ├── .gitignore ├── requirements.txt └── main.py.env文件内容如下OPENAI_API_KEYsk-你的密钥.gitignore里一定要加上.env防止密钥被版本管理工具纳入跟踪.env .venv/ __pycache__/然后在终端里执行安装命令。我实测下来这套组合是稳定的python -m venv .venv source .venv/bin/activate pip install langchain langchain-openai python-dotenv这里解释一下为什么用 .env 而不是直接在当前 shell 里 export。.env 的好处是密钥跟着项目走换台机器还原环境时只要自己手动填密钥不需要在命令行历史里暴露。配合 .gitignore 使用后代码和数据天然隔离这是基础设施级的卫生习惯值得从第一行代码开始养。2.2 第一个可运行 Demo让模型开口说话环境搭好后先写一个最小版本验证整条链路通了没有。这个过程强烈不建议跳过因为后面所有调试都建立在这个“能通”的基础上。新建main.py写入以下代码import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI load_dotenv() llm ChatOpenAI( modelgpt-4o-mini, temperature0.7, api_keyos.getenv(OPENAI_API_KEY), ) response llm.invoke(用一句话介绍 LangChain) print(response.content)跑一下python main.py。如果一切正常你会看到模型输出的中文介绍。就这么简单你已经完成了第一次 LangChain 调用。这里有个细节值得展开llm.invoke()是 ChatOpenAI 这个封装对象的核心入口。LangChain 0.2 之后统一了调用方式——所有组件都有invoke方法输入和输出都是标准类型。刚才这段代码里invoke 接受的是一个普通字符串返回的是AIMessage对象我们取它的.content拿到最终文本。这个设计贯穿 LangChain 的方方面面后面学的每个组件都有 invoke理解这一个方法就是理解了所有组件的通讯协议。另外temperature 这个参数很值得说。它控制模型输出的随机性范围是 0 到 2。0 会让模型尽可能选择概率最高的词回答稳定但偏死板适合事实罗列0.7 到 1 比较适合生成、头脑风暴类场景回答不那么套路1.5 以上基本是放飞自我同一个问题两次回答能差异巨大。新手的常见错误是问事实性问题也把 temperature 设得很高导致模型一本正经地胡编这一点在多轮对话和知识问答里尤其致命。2.3 模型选型参考便宜和聪明之间怎么选在 Demo 里我用了gpt-4o-mini没有用旗舰型号。原因很直接这个速成项目要验证的是 LangChain 的工程链路不是模型能力的极限。模型再聪明如果不解决“提示词怎么管理、输出怎么解析、代码怎么组织”这些问题一样做不出产品。以下是几个常见模型的实践对比帮你在不同场景下做选择。模型速度成本典型场景gpt-4o中等较高复杂推理、代码生成、需要高准确率的场景gpt-4o-mini快很低日常问答、文本分类、提取、原型验证gpt-3.5-turbo快很低对能力要求不高的场景但综合质量弱于 4o 系列个人经验第一阶段练习用gpt-4o-mini是最优解。理由很简单你会在调试提示词的过程中反复调用接口如果每次都走 gpt-4o单轮调试成本是 mini 的十几倍一天调下来账单有点难看。等提示词方案定稿了再根据任务难度切到更强的模型也不迟。成本意识从练习阶段就开始养成后面做真实项目时会非常感谢自己。还有一个细节是该在什么时候知道自己选的模型名字拼错了。OpenAI 的模型名会周期性调整旧名字可能下线新名字可能加后缀。如果你运行时报类似Model not found的错第一反应不要怀疑 LangChain先去查一下当前可用的模型 ID 列表。很多时候问题不在代码而在产品线的版本迭代。3. 核心环节用 PromptTemplate 和解析器把程序变“聪明”3.1 裸调用与链式调用体验 LangChain 的核心思维第一个 Demo 能跑但它没有任何工程性可言。现在我们要做一个升级给程序加入切换角色的能力。比如用户输入一个问题程序可以选择让“资深律师”或者“搞笑段子手”来回答这个角色设定放在提示词里。如果继续裸写提示词代码会变成这样role 资深律师 prompt f你现在是一个{role}请回答以下问题{question}看起来似乎没什么问题f-string 拼起来挺方便。但是当项目变大你会发现提示词的修改会散落在代码各处每条提示词可能还带着不同的 few-shot 示例、输出格式约束、历史对话拼接逻辑。这个阶段用 f-string 还能忍受等提示词变长、需要版本管理时就会非常痛苦。LangChain 给的方案是 PromptTemplate把提示词写成模板变量部分用占位符申明同一个模板可以在程序不同位置反复实例化。下面的代码把模板和模型串成一条链这是 LangChain 最精髓的写法之一from langchain_core.prompts import ChatPromptTemplate from langchain_openai import ChatOpenAI llm ChatOpenAI(modelgpt-4o-mini, temperature0.7) template ChatPromptTemplate.from_template( 你现在是一个{role}请用专业且简洁的方式回答下面的问题{question} ) chain template | llm question 如果我的合同里没有约定违约金还能索赔吗 response chain.invoke({role: 资深律师, question: question}) print(response.content)注意template | llm这个管道符语法。这可不是 Python 的位或运算而是 LangChain 在语言层面实现的一种组合方式官方叫 LCELLangChain Expression Language。管道左边的输出会自动转化为右边的输入chain.invoke()只需要传一个字典模板里的变量就会自动被填充。这条 chain 的输入是字典中间经过模板变成提示词再经模型变成 AIMessage结构非常清晰。这里想强调一个很容易被忽略的细节ChatPromptTemplate.from_template创建的模板把变量声明和使用分离了。你可以把模板存成单独的文件甚至从配置文件里加载。等到项目里出现五六个提示词模板时统一管理比散落各处好得多。3.2 多变量模板提示词工程的最小实践单元当模板只有一个变量时效果还不明显。一旦加上系统指令、内容片段、格式要求PromptTemplate 的优势就体现出来了。看这个升级版template ChatPromptTemplate.from_messages([ (system, 你是一位严谨的{profession}只根据给定内容回答问题不要编造。 ), (human, 资料{context}\n\n问题{question}), ]) chain template | llm response chain.invoke({ profession: 财务分析师, context: 公司今年营收同比上涨 10%但利润下降 5%, question: 利润下降的可能原因有哪些 }) print(response.content)from_messages是一种更接近 Chat API 原生结构的模板方式它区分了系统消息和人类消息。这背后对应着 OpenAI 模型训练时遵循的角色体系系统消息设定整体行为和边界人类消息是用户实际输入。把角色设定放进 system 消息而不是和用户问题拼在一起是提示词工程里一个很便宜但收益明显的习惯。这个案例也展示了模板组合能力的重要性。真实场景里的提示词几乎永远是多段拼装既有上下文资料又有用户问题还可能带输出格式说明。如果用裸 f-string变量一多拼接顺序就容易错。模板方式让变量顺序由占位符位置决定填错值的概率大幅下降并且变量多了以后代码可读性依然在线。3.3 输出解析器让模型输出的不是文案而是数据链式调用的第三个关键组件是输出解析器。为什么要用它因为模型返回的是自然语言文本但对一个程序来说我们往往希望拿到结构化数据——比如一个 JSON 对象包含标题、评分、摘要。如果直接拿自然语言去解析模型每句话的表达方式都可能不同程序会处理得想骂人。LangChain 提供了一套输出解析器把模型输出从“人话”转成“程序好处理的结构”。最简单的StrOutputParser直接取字符串内容适合纯问答场景。复杂一点的是PydanticOutputParser它能定义一个数据模型让模型严格按照模型的字段格式输出 JSON再自动校验转换。下面这个例子定义了一个电影点评的返回结构from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser from langchain_core.output_parsers import PydanticOutputParser from pydantic import BaseModel, Field class MovieReview(BaseModel): title: str Field(description电影名称) rating: float Field(description评分1到10分) summary: str Field(description不超过30字的一句话总结) parser PydanticOutputParser(pydantic_objectMovieReview) template ChatPromptTemplate.from_messages([ (system, 你是一个影评助手。请严格按照要求输出 JSON。\n{format_instructions}), (human, 请评价电影{movie_name}), ]) chain template | llm | parser result chain.invoke({ movie_name: 星际穿越, format_instructions: parser.get_format_instructions(), }) print(result.title) print(result.rating) print(result.summary)这段代码里有个关键点parser.get_format_instructions()会在运行时生成一段描述告诉模型“输出的 JSON 必须有哪些字段、每个字段什么类型”。它是运行时有用的保证了模型的输出的格式期望和 Pydantic 模型定义一致。所以模板里把format_instructions作为一个模板变量传进去是一种非常标准也偏高效的做法。真实的执行链路是这样的用户请求 → PromptTemplate 渲染提示词 → ChatOpenAI 调用模型 → 原始文本 → Pydantic 解析器 → MovieReview 对象我测试过多次只要提示词里带了format_instructions模型输出几乎都能被正确解析。但偶尔模型会多输出一段解释性文字比如在 JSON 前后加 代码块或者夹带 Markdown 标记这会导致解析器抛错。应对方案有两个一是保持模型版本稳定不要频繁换二是在解析错误时增加重试机制把错误信息重新反馈给模型让它修正。后者在实际项目里是最稳的兜底手段。看到这里你其实已经掌握了 LangChain 三条链路的拼装方式模板、模型、解析器。它们之间的关系完全符合 LCEL 管道语法任何一个组件都可以被替换。这也是 LangChain 最核心的编程模型。4. 实战踩坑实录那些文档里不会告诉你的问题4.1 密钥和环境类报错按图索骥搞定它我带着这个速成课的内容教过几批同学发现报错集中在几个固定模式上。把这些经验整理成一张速查表遇到问题可以对照着排查。错误现象原因处理方式OpenAIError: The api_key client option must be set代码里没有正确传递 api_key或者 .env 没加载检查load_dotenv()位置确认 .env 文件在项目根目录ModuleNotFoundError: langchain_openai漏装 langchain-openai 包pip install langchain-openaiAuthenticationError: 401API 密钥无效或被拒绝检查密钥前后是否有多余空格、是否已过期NotFoundError: 404模型名不存在或不可用查一下当前可用的模型列表替换模型名BadRequestError: 400请求参数格式不符合要求留意 max_tokens、temperature 等参数范围某些模型不支持超过上限一个容易被忽视的坑.env文件里的密钥如果带了引号dotenv 会把引号当作用户名的一部分解析进去导致认证一直失败。以前我就遇到过.env 里写了OPENAI_API_KEYsk-xxx结果程序里读出来的值变成了sk-xxx包括引号反复排查了快半小时才发现。建议 .env 里的值一律不加引号。还有一件事如果你是在 Jupyter Notebook 里跑这种代码load_dotenv()之后改动了 .env 文件需要重启 Kernel 才能生效。因为 python-dotenv 只会在调用时读一次文件变化不会自动感知。这个坑在新手里特别常见代码看起来没错但就是读到旧值很浪费情绪。4.2 调用超时和重试策略别让偶发故障搞崩心态LLM API 和本地函数最大的区别是网络不确定性强。即使代码完全正确也可能遇到请求超时或者限流。默认情况下 ChatOpenAI 的超时时间是 60 秒但如果网络状况不好或者是排队高峰期一次请求超过 60 秒直接抛异常。处理方式是在初始化模型时显式设置超时和最大重试次数llm ChatOpenAI( modelgpt-4o-mini, temperature0.7, timeout60, max_retries3, )max_retries的作用是当请求遇到临时性错误时自动重试这个参数在 API 偶发抖动时很有用。但要注意不是所有异常都适合重试。401 是认证问题重试多少次都一样400 是请求错误重试也不会变成功。一般只有超时、限流这类瞬时错误才值得重试。盲目重试不仅浪费等待时间还可能叠加触发限流。另外同步调用和异步调用的超时感受完全不同。上面写的都是同步调用一次请求阻塞整个程序。如果你在做 Web 服务建议学一下ainvoke()异步方法配合asyncio并发处理多个请求吞吐量会有质变。这个内容我会放到系列后面的部分细讲现在先知道有这个方向就行。4.3 结构化输出不稳定兜底方案要留一手本章节最推荐的实操经验是这个依赖 Pydantic 解析器时永远不可能做到 100% 一次解析成功。模型毕竟是概率输出就算指令写得再明确偶尔也会多给你几个字。典型的失败案例是模型在 JSON 前加了“好的这是你要的结果”这种自然语言前缀或者把 JSON 用 Markdown 代码块包起来。应对思路分三层。第一层提示词里明确说“只输出 JSON不要额外解释”这能减少大部分问题。第二层捕获OutputParserException异常拿到原始文本做轻量清洗比如提取 JSON 子串。第三层把解析失败的信息和原始输出一起回传给模型让模型自行纠正from langchain.output_parsers import OutputParserException try: result chain.invoke({movie_name: 星际穿越}) except OutputParserException as e: print(解析失败原始输出是, e.llm_output)这里e.llm_output是一个非常实用的属性它会保存模型实际的原始输出。拿到它以后你就能看到模型到底多输出了哪些内容然后针对性地调整提示词。很多同学在解析失败时只知道报错信息里有“Failed to parse”却看不到原始输出这正是因为没有访问llm_output。记得把它打印出来它会帮你省掉大量猜测。4.4 上下文和成本控制新手最容易忽视的隐性坑最后一个坑来自成本比代码报错更隐蔽。调用大模型是有计费的而计费的单位是 token不是请求次数。提示词越长、回答越多token 消耗越大。第一次写 PromptTemplate 的开发者很容易把大段资料全塞进模板里每次调用都带着几千 token 的“随身行李”费用会按你的使用量线性增长。我养成了一个习惯每次写模板时评估两个数字——输入 token 的大致范围和输出 token 的限制。输出限制可以通过max_tokens参数控制比如设置 512模型就不会无止境地往下写。计算公式很简单费用 输入 token 数 × 单价 输出 token 数 × 单价。不同模型价格差异大具体单价以官方价格页为准但思维习惯要提前建立你是每分每秒都在烧钱让模型替你干活提示词越精炼成本越低。控制上下文长度还涉及模型本身的窗口限制。模型能接收的输入 token 是有限的超过上限会直接报错。如果你的输入资料特别长常见方案是切分、摘要或只取关键段落这属于 RAG 的范畴留到系列后面展开。现在只要记住提示词不是越长越好够用就行这是 LLM 应用成本控制的基本原则。5. 复盘与下一步这套东西到底还能长成什么样5.1 当前 Demo 的局限以及最值得立刻改进的三个方向做完上面的内容你已经拥有一个能跑、能切换角色、能输出结构化结果的命令行程序。但实事求是地讲距离一个“产品”还差着老远。它没有记忆每一次 invoke 都是独立的模型不记得你上一轮说过什么它没有检索能力所有知识都靠模型自身训练数据你没法让它查询私有文档它没有并发处理能力同步方式在高流量场景下撑不住。这三个限制恰好对应 LangChain 后续的三个核心主题Memory多轮对话记忆、RAG检索增强生成、异步与流式输出。它们是 LangChain 真正发挥价值的领域。现在带着这三个明确的改进方向去学后续内容效率会远高于漫无目的地读文档。就我个人的实操经验来说建议你下一步优先学 RAG。原因很实在RAG 能解决大模型幻觉问题让你自己的知识库能被模型引用这个能力在真实项目里的需求度极高而且 LangChain 对向量数据库的支持已经非常成熟。你只需要学会文本切分、向量化、相似度检索三个环就能搭一个简单的“文档问答机器人”。5.2 在 LangChain 体系里Agent 是下一个真正的量变点如果你的学习路线走到一定程度一定会接触到 Agent。Agent 和 Chain 的区别可以这样理解Chain 是固定流水线每一步做什么是提前写好的Agent 是一个会自己规划步骤的调度器它拥有工具列表能根据用户的提问自主决定调用哪个工具、按什么顺序调用甚至能在失败后换一条路重试。这个机制特别适合做数据查询类的应用。举例来说你可以给 Agent 挂上一个 SQL 工具和 Excel 工具用户问“这个月各区域业绩平均增长多少”Agent 会自己决定先查数据库再算平均然后把结果整理成报告。这是光靠 Chain 做不到的因为链里的步骤必须人工预判。但 Agent 也带来新的复杂度最大的问题是不可控。模型自行选择工具时可能选错或者陷入工具调用循环。在实际项目里我建议从“半自动”方案开始Chain 负责主流程Agent 只在某个特定分支里介入而不是一出场就让 Agent 接管所有流程。先把确定性高的部分用代码写死让模型只做决策的部分这样最终效果会更稳定一些。5.3 给初学者的路径建议按这个顺序往下走每次带新人我都会给出一个明确的路线图。学 LangChain 最大的风险不是学不完而是东学一块西学一块知识碎片化。按下面顺序走基础最扎实吃透 PromptTemplate 和 OutputParser 的组合使用独立写过三种不同类型的数据结构。掌握 LCEL 管道语法理解 invoke、batch、stream 三种调用方式的区别。用 langchain 接入至少一个本地向量库跑通一个最小 RAG 流程。学习 ConversationBufferMemory 和它的变体实现多轮记忆。再玩 Agent给 Agent 挂上两个自定义工具跑一个搜索或计算类任务。最后才是异步、流式、回调等进阶特性它们解决性能和质量问题。每一步都要有一个能跑的最小项目。不要光学概念概念背得再熟三天不敲代码就会忘掉。我个人学 LangChain 时最重要的心得是代码是一行一行敲进去的不是你“看懂”的。照着文档敲一遍再自己改一组件变量再故意制造一个报错然后解决掉这个流程走完才是真的掌握。这条速成课的路线我会按系列继续往下写。第一部分到这里你已经能搭出一个像样的 LLM 应用骨架了。如果环境搭建或第一个 Demo 跑的时候卡住了优先检查版本和密钥这两项80% 的问题都出在那里。把它跑通下一步我们再聊怎么让你的应用记住对话、翻出文档里的答案以及在你自己的产品里真正用起来。
