langchain

LangChain 专家技能

LangChain 是一个采用 MIT 许可、用于构建由大模型驱动的应用的 Python 框架。自 v1.0（2025 年 10 月）起，它提供分层架构：通过 LCEL（LangChain Expression Language）进行高层链组合，通过 create_agent 创建 Agent（底层运行于 LangGraph 运行时），并借助 LangSmith 实现生产环境可观测性。它拥有 1000 多项集成和 10 万多个 GitHub 星标，是应用最广泛的大模型编排框架。

v1.0 的关键变化： 所有新的 LangChain Agent 都运行于 LangGraph 运行时。AgentExecutor 将进入维护模式，直至 2026 年 12 月。创建新 Agent 时请使用 create_agent。需要完全控制状态机时，直接使用 LangGraph。

⚠️ 关键：不要在新代码中使用 AgentExecutor。 它将进入维护模式，直至 2026 年 12 月。请改用 create_agent(model, tools, prompt)——它开箱即用地生成具有流式处理、持久化和可观测性的 LangGraph 状态机。

核心原则

使用 LangChain 构建时，每项决策都应遵循这些原则。继续阅读参考指南之前，请先了解这些原则。

1. LCEL 是组合的基本构件。 管道运算符（|）可串联 Runnables。每个组件——提示词、模型、解析器、检索器——都实现 Runnable 接口。所有内容都通过 LCEL 构建。
2. Agent 运行于 LangGraph 之上。 自 v1.0 起，create_agent 会在底层生成 LangGraph 状态机。无需编写图代码，即可获得流式处理、持久化和可观测性。需要分支、循环或人在回路中时，直接使用 LangGraph。
3. RAG 是一条链，而非一个框架。 retriever | prompt | model | parser 是规范的 RAG 模式。文档加载器、分割器和向量存储都是可互换的组件。
4. LangSmith 提供生产环境可观测性。 启动时启用追踪。89% 的生产团队使用可观测性——没有它，调试 Agent 行为只能靠猜。
5. 生态系统是竞争优势。 1000 多项集成意味着模型提供商、向量存储和工具只需一行代码即可替换。面向接口构建，而非面向实现。

从这里开始

你已有……	从这里开始
什么都没有——空白项目	安装 LangChain，构建一个基本的 LCEL 链
要查询的文档	构建 RAG 链（加载、分割、嵌入、检索、生成）
实现 Agent 行为的需求	使用 create_agent 和工具
现有的 AgentExecutor 代码	迁移到 create_agent——参见 references/agent-patterns.md
生产环境部署	添加 LangSmith 追踪和 LangServe 部署
正在比较框架	参见 Framework Routing Guide

流水线模式

模式	适用场景	要运行的阶段	跳过
快速	单条链、探索	prompt → model → parser	检索、Agent、生产加固
RAG	文档问答	load → split → embed → retrieve → generate	Agent 编排、部署
Agent	使用工具的 Agent	create_agent + tools + LangGraph 运行时	简单链即可满足需求时
生产	面向用户发布	RAG/Agent + LangSmith + LangServe	无

快速参考

任务	方法	参考
基本链	prompt | model | parser	references/lcel-reference.md
RAG 流水线	retriever | prompt | model | parser	references/rag-strategies.md
创建 Agent	create_agent(model, tools, prompt)	references/agent-patterns.md
工具定义	@tool 装饰器	references/agent-patterns.md
多 Agent	LangGraph supervisor 模式	references/agent-patterns.md
可观测性	设置 LANGCHAIN_TRACING_V2=true	references/production-deployment.md
部署	LangServe 或 LangSmith Deployment	references/production-deployment.md
向量存储	一行替换（Chroma、Pinecone、pgvector）	references/integration-ecosystem.md

何时使用此技能

在以下任何情况下，都应加载此技能：

• 为由大模型驱动的应用构建 LCEL 链
• 在企业或个人数据上实现 RAG 流水线
• 创建能够调用工具并进行多步推理的 Agent
• 将大模型应用部署到生产环境并进行可观测性监控
• 比较 LangChain 与 LlamaIndex、Haystack 或原始 API 调用

框架选择指南

此技能属于一系列框架技能。选择合适的框架时：

场景	选择	原因
我需要组合链	LangChain	LCEL 是最简洁的管道式组合模型
我需要查询文档	LlamaIndex	数据摄取和检索是其一等原语
我需要编排 Agent	LangGraph	状态机语义、子图和人在回路
我需要将工具封装为 Agent	PydanticAI	通过依赖注入定义类型安全的 Agent
我需要搜索流水线	Haystack	其流水线模型更适用于搜索工作负载
快速构建任何类型的原型	LangChain	从零开始到链可运行，路径最快
Agent 工作流中类型化且有界的决策	System One	System One 负责问题／模型行为和校准；使用 LangChain 中间件或外层条件编排作为实现接缝，并使用 harness-engineering 确定位置并评估整体任务结果

参考文件

参考资料	何时加载	文件
LCEL 参考	使用管道运算符构建链时	references/lcel-reference.md
架构	了解软件包结构、Runnable 和 v1.0 时	references/architecture.md
RAG 策略	构建 RAG 流水线时	references/rag-strategies.md
Agent 模式	使用工具创建 Agent 或多 Agent 时	references/agent-patterns.md
Agent 中的类型化 System One 决策	确定适配器接缝、未知分支，以及模型语义与框架结果之间的交接方式	references/agent-patterns.md — 参阅“让类型化决策位于聊天模型之外”；有关位置和整体任务证据，请继续参阅 harness-engineering
生产与部署	使用 LangServe、LangSmith 和部署时	references/production-deployment.md
集成生态系统	使用模型提供商、向量存储和工具时	references/integration-ecosystem.md
常见问题与故障排除	查找常见错误和解决方法时	references/faq-and-troubleshooting.md
回调系统	实现自定义日志记录、监控和 Agent 审计时	references/callbacks.md
验证审计	验证所有 API 声明的研究结果时	references/validation-audit.md

模板文件

模板	使用时机	文件
基础链	单个提示词→模型→解析器链	templates/basic-chain.py
RAG 流水线	通过检索进行文档问答	templates/rag-pipeline.py
带工具的 Agent	使用 LangGraph 运行时的工具调用 Agent	templates/agent-with-tools.py
生产部署	使用 LangSmith 部署 LangServe	templates/production-deploy.py

脚本

脚本	用途	文件
check-setup	验证 LangChain 是否已安装	scripts/check-setup.py

故障排查指南

症状	可能原因	修复方法	参考
链没有返回任何内容	未连接输出解析器	添加 .pipe(StrOutputParser()) 或同等配置	references/lcel-reference.md
Agent 未调用工具	工具架构不匹配	检查工具是否有文档字符串和类型提示	references/agent-patterns.md
缺少 LangSmith 跟踪记录	未设置 LANGCHAIN_TRACING_V2	在执行任何链之前设置环境变量	references/production-deployment.md
弃用警告	正在使用 AgentExecutor	迁移到 create_agent（LangGraph 运行时）	references/agent-patterns.md
找不到模型	缺少集成包	安装 langchain-openai、langchain-anthropic 等	references/integration-ecosystem.md
流式传输无法正常工作	LCEL 链不支持原生流式传输	确保所有组件都实现了 stream()	references/lcel-reference.md
向量存储连接失败	凭据错误或缺少软件包	安装 langchain-community 和提供方软件包	references/integration-ecosystem.md

何时不应使用 LangChain

• 单模型、单提示词应用——直接调用 API 更简单，也更便于调试
• 需要最大程度的透明性——LangGraph（LangChain 底层使用的框架）可提供更高的可见性
• 纯多 Agent 状态机——直接使用 LangGraph 才是正确选择，而不是使用高级 API
• 不需要大模型编排的无状态微服务——LangChain 只会增加开销，没有任何益处