LangChain

LangChain 快速入门

一句话卖点:从「调 API」到「建 Agent」的桥梁 —— 用 LangChain 把 LLM 变成能干活的应用。

这是什么?适合谁?

LangChain 是 Harrison Chase 于 2022 年 10 月开源(2024-2026 持续演进)的AI 应用开发框架,主仓库 langchain-ai/langchain,GitHub 142K+ stars。它不是一个模型,而是帮你把 LLM 和外部工具、数据库、API 连接起来、让 AI 能「干活」的完整工具链。

LangChain 不是一个产品而是一个家族:

• LangChain:核心框架,LCEL 表达式语言、Prompt、Chain、Memory、Retriever;
• LangGraph:Agent 工作流编排框架,基于状态机的多 Agent 协作(2024 年推出);
• LangSmith:调试 / 追踪 / 评估 / 监控平台,生产环境必备;
• LangServe:把 Chain 部署成 REST API 的工具。

简单区分:

• 如果你只想要一个聊天机器人 → 直接用 ChatGPT;
• 如果你想让 AI 读你的数据库、搜你的文档、调你的 API、做多步操作 → LangChain 就是帮你串联这些的工具箱。

适合谁?一是后端工程师,需要把 LLM 集成到现有系统中;二是AI 产品经理 / 创业者,想快速搭建 AI Agent 原型;三是企业架构师,需要可观测、可调试、可部署的生产级 AI 管道;四是Agent 研究者,LangGraph + LangSmith 是研究 Agent 行为 / 评估 / 多代理协作的最佳实验场。

不适合:只想简单对话(用 ChatGPT 网页)、需要极致性能(LangChain 的抽象层有 5-15% 开销,极致场景考虑 vLLM 直连)、纯前端 / 无后端(需要后端部署)。

准备工作

1. 环境:Python 3.10+,或 TypeScript/JavaScript(JS 版本功能略少但还在追赶);
2. 安装:pip install langchain langchain-core langchain-openai(Python)或 npm install langchain @langchain/core (JS);
3. API Key:至少一个 LLM 提供商(OpenAI、DeepSeek、Anthropic、Google、阿里通义、智谱、月之暗面);
4. 可选:LangSmith 账号(免费层每月 5K traces)用于调试追踪;
5. 前置知识:Python 基础、LLM 基本概念(prompt / token / temperature / context window)。

3 步快速上手

第 1 步:安装并配置

pip install langchain langchain-openai langchain-community
export OPENAI_API_KEY="sk-xxx"

# 或用 DeepSeek(国内友好)
export OPENAI_API_KEY="sk-xxx"
export OPENAI_BASE_URL="https://api.deepseek.com"

第 2 步:运行第一个 Chain (LCEL)

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一个 Python 编程专家"),
    ("user", "用 Python 写一个 {algorithm} 的代码示例,加注释")
])
parser = StrOutputParser()

# LCEL 表达式:用 | 串联组件
chain = prompt | llm | parser

result = chain.invoke({"algorithm": "快速排序"})
print(result)

第 3 步:创建第一个 Agent(带工具调用)

from langchain_openai import ChatOpenAI
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain_core.prompts import ChatPromptTemplate
from langchain.tools import tool

@tool
def get_weather(city: str) -> str:
    """获取指定城市的当前天气"""
    return f"{city}:晴天,25°C"

@tool
def add(a: int, b: int) -> int:
    """计算两个数的和"""
    return a + b

llm = ChatOpenAI(model="gpt-4o-mini")
tools = [get_weather, add]

prompt = ChatPromptTemplate.from_messages([
    ("system", "你可以使用工具回答问题。如果信息已足够,直接回答。"),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])

agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, max_iterations=5)

result = executor.invoke({"input": "北京今天天气怎么样?另外,123 加 456 等于多少?"})
print(result["output"])

初级用法

• PromptTemplate 模板:from_template("写一首关于{topic}的{style}诗"),可变量插值;
• 不同 OutputParser:StrOutputParser(纯文本)、JsonOutputParser(结构化 JSON,推荐用于 Agent 输入)、PydanticOutputParser(强类型);
• Memory:ConversationBufferMemory(全量历史)、ConversationSummaryMemory(摘要历史,token 省)、ConversationBufferWindowMemory(最近 K 轮);
• Retrieval (RAG):from langchain_community.document_loaders import PyPDFLoader;loader = PyPDFLoader("...");docs = loader.load() 然后切分嵌入;
• Vector Store 集成:Chroma(本地)、Pinecone(云)、Weaviate(本地+云)、FAISS(Meta 出的本地)、pgvector(PG 扩展);
• Streaming 输出:chain.stream({"topic": "AI"}) 一边推理一边输出,体感更好;
• Batch 批处理:chain.batch([{"topic": "AI"}, {"topic": "Web3"}]) 批量调用,效率高;
• 异步调用:await chain.ainvoke({"topic": "AI"}),FastAPI 等异步框架友好。

高级玩法

• LangGraph 多 Agent 协作:用状态机编排多个 Agent,一个 Planner、一个 Executor、一个 Reviewer 组成复杂流程;
• RAG Fusion:对原始 query 改写 / 扩展成多个,然后并行检索 → 合并 → 重排,显著提升召回率;
• Self-RAG / CRAG:让 LLM 自我评估检索结果质量,自动触发重新检索或修正;
• Multi-Vector Retriever:同一文档存多种粒度的向量(段落级 + 句子级),问答时精确到句子;
• Hybrid Search (BM25 + 向量):用 EnsembleRetriever 组合稀疏(BM25)和稠密(向量)检索,长尾词效果提升显著;
• Function Calling / Tool Use:用 @tool 装饰器或 StructuredTool 定义工具,支持 OpenAI / Anthropic / Google 多种 function calling 协议;
• 流式 + 工具并行:Agent 多工具调用时用 stream_log 看每步推理,前端可展示思考过程;
• LangSmith 集成:在生产环境追踪每条 LLM 调用,看 latency、token、错误率,用 LANGCHAIN_TRACING_V2=true 一行启用;
• 生产化部署:LangServe 把 Chain 包装成 FastAPI,挂 Nginx + 鉴权 + 限流就能上线;
• 结构化输出:用 with_structured_output(Pydantic) 让 LLM 直接返回 Pydantic 对象,免去 JSON parsing 错误;
• Human-in-the-Loop:用 LangGraph 的 interrupt_before / interrupt_after 让关键决策暂停,等人工审核;
• LangSmith Hub:团队共享 Prompt、Chain、Evaluation Sets,版本化管理。

小技巧

1. 固定版本:LangChain 主版本变化快,锁定 pip install langchain==0.3.x langchain-core==0.3.x langchain-openai==0.2.x,否则一个月后代码就跑不了;
2. LCEL 优先 over 旧 Chains:2024 年后的所有新项目应该用 LCEL(prompt | llm | parser),不要用 LLMChain、SequentialChain 这些旧 API,即将废弃;
3. Prompt 集中管理:把 prompt 放 .py 文件或 LangSmith Hub,不要散落在代码里,迭代效率天差地别;
4. Tool 描述要清晰:LLM 是否调用工具取决于 docstring,"""获取北京今天的天气,返回字符串""" 比 """天气查询""" 触发率高得多;
5. max_iterations 必须设:Agent 必须限制最大迭代次数(建议 5-10),否则会无限循环;
6. 异步 + 流式 + 批处理组合:FastAPI + ainvoke + astream 是生产环境的最佳实践组合;
7. LangSmith 永远开:调试期间开 LangSmith,每个 Chain 的输入输出都看清楚,定位问题比 print 快 10 倍;
8. Vector Store 选型:小项目 Chroma / FAISS(本地、零依赖),中等 Pinecone / Weaviate(云托管或自部署),大数据 Qdrant / Milvus(亿级向量);
9. 缓存省钱:set_llm_cache(InMemoryCache()) 或 SQLiteCache,相同 prompt 不重复调 API;
10. Token 经济:用 tiktoken 预算 token,设置 max_tokens,LangSmith 看实际消耗。

常见踩坑

踩坑 1:版本不兼容 — ImportError / AttributeError

• 症状:ImportError: cannot import name 'XXX' from 'langchain' 或 AttributeError: module has no attribute
• 原因:LangChain 生态版本更新频繁(2024-2025 间 0.1→0.2→0.3 多次大改),langchain、langchain-core、langchain-openai 等包版本不匹配
• 解决:① 用 pip install langchain==0.3.x 固定版本;② 看官方 迁移指南;③ 新项目从 langchain-core 起步而非 langchain 主包

踩坑 2:Agent 陷入循环

• 症状:Agent 反复调用同一个工具,永远不退出
• 原因:prompt 没明确「何时停止」、工具返回信息不清晰、模型选了弱模型
• 解决:① 设 max_iterations=5;② prompt 里加「如果信息足够,请给出最终答案」;③ 换强模型(GPT-4o / Claude Sonnet);④ 加 early_stopping_method=“generate” 让模型自己判断

踩坑 3:Token 消耗巨大

• 症状:单个 Agent 调用消耗几万 token,账单失控
• 原因:Agent 多步推理思考→工具→观察→思考,中间 token 累积;长 context Memory 没清理;大 context Window
• 解决:① 用 LangSmith 追踪每步消耗;② Memory 用 ConversationSummaryMemory 而非 Buffer;③ 选便宜模型做 Agent 推理(DeepSeek / GPT-4o-mini);④ Cache 重复 prompt

踩坑 4:LangChain 抽象层「黑盒」感

• 症状:调试困难,不知道 Agent 内部发生了什么
• 原因:LCEL 语法糖隐藏了执行细节
• 解决:① 注册 LangSmith 账号(免费,5K traces/月);② LANGCHAIN_TRACING_V2=true;③ 用 chain.stream_log() 看每步 prompt 和 output

踩坑 5:工具调用返回格式不匹配

• 症状:ToolMessage 解析失败、Agent 报 validation error
• 原因:@tool 默认返回 str;有些工具返回 dict/list;OpenAI strict mode 要求工具 schema 严谨
• 解决:① 工具返回 str(首选);② 返回 dict 时用 parse_docstring=True 自动解析;③ OpenAI 工具加 strict=True + pydantic schema

踩坑 6:RAG 检索质量差

• 症状:检索结果和 query 无关、答案幻觉严重
• 原因:分块太大、嵌入模型选错、没 rerank、prompt 没强调「只引用文档内容」
• 解决:① chunk_size 400-1000 + overlap 50-200;② 换更强嵌入模型(text-embedding-3-large、BGE-M3);③ 加 cross-encoder rerank;④ prompt 加 system message「只回答文档中出现的内容」

踩坑 7:Streaming 中途报错

• 症状:流式输出到一半报错
• 原因:Provider 中断、网络抖动、Context 超长
• 解决:① FastAPI 加 try / except;② 重试逻辑(tenacity);③ 适当 chunk_size 控制 context;④ 监控 alert

踩坑 8:生产部署 LangServe 启动慢

• 症状:langchain serve 启动要 1-2 分钟
• 原因:LangServe 加载 Chain 时初始化模型 / Retriever
• 解决:① 初始化逻辑移到 lifespan startup;② 模型加载延后到第一次请求;③ 用 uvicorn workers 并行启动

常见问题 FAQ

Q1: LangChain 和 LlamaIndex 有什么区别?

A: 简单原则:LangChain 偏「让 LLM 干活」(Agent/工具调用),LlamaIndex 偏「让 LLM 读懂数据」(RAG/检索)。

• LangChain 擅长:多 Agent 编排、工具调用、Memory、Production 部署;
• LlamaIndex 擅长:RAG、文档加载、索引选型、检索优化。
• 两者完全可以互补:LangChain 做 Agent,内部用 LlamaIndex 做 RAG 检索;或用 LlamaIndex 做 RAG 数据管道,LangChain 做 Query 解析。2025 年后两者趋同,都向「AI 工程平台」演化。

Q2: 应该用 Python 版还是 JS 版?

A: Python 版更完整:功能多、社区大、文档全、新功能首先上 Python。JS 版适合前端 / Node.js / 全栈 TS 项目 / Deno / Cloudflare Workers。入门选 Python —— 80% 教程、Cookbook、issue 都是 Python。生产 Web 应用(Next.js / Nuxt)可以混用:Python 后端 + JS 前端 SDK。

Q3: LangChain 学习曲线陡吗?

A: 入门简单:三行代码跑一个 Chain。深入难:Agent 编排、自定义工具、流式处理、Memory 策略、LangGraph 状态机,都是单独的学习曲线。建议:① 先看官方 Tutorials 做完整跑通;② 再深入单个模块(Agents / RAG / Memory);③ 实战项目驱动学习,不建议从头读完整文档。

Q4: 为什么用 LangChain 而不是直接调 API?

A: 如果你只需要「问一个问题 → 得到一个答案」,直接调 API 更简单。LangChain 的价值在于:多步推理、工具调用、RAG、Memory、流式输出、Production 化、可观测性 —— 这些直接调 API 需要写几千行代码,且维护成本高。LangChain 让你用几十行代码搞定生产级 AI 应用。

Q5: LangChain 适合生产环境吗?

A: 适合,但需要配套:① LangSmith 用于调试追踪(必须);② LangServe 用于 API 部署;③ LangGraph 用于复杂 Agent 编排;④ 自部署 LLM 或 OpenAI Tier 1+ 用于稳定性。LangChain 抽象层有 5-15% 性能开销,极高性能场景(每秒万次调用)用 LangGraph 直连或换 vLLM。

Q6: LangChain 的未来?会被替代吗?

A: 短期(2-3 年)LangChain 是事实标准。长期看,Agent 框架竞争激烈:OpenAI Swarm、Anthropic MCP、CrewAI、AutoGen(微软)、Pydantic AI 都是竞争者。LangChain 的护城河是生态最丰富、社区最大、LangSmith 数据闭环最强。建议:学 LangChain 学的是「Agent 工程化模式」,具体框架可以换,思想是通用的。

进阶学习建议

LangChain 是 2026 年 AI 工程领域生态最丰富的框架,学习投资回报率高,但内容多需要分层。建议五阶段:

• 第 1 阶段:基础 Chain (3-5 天):LCEL 语法、PromptTemplate、各种 LLM / OutputParser、基础流式输出。这一阶段完成你应该能熟练拼装 prompt + llm + parser 三件套,处理简单 LLM 调用;
• 第 2 阶段:RAG + Vector Store (1-2 周):Document Loader、Splitter、Embedding、Retriever、Vector Store 选型、加 Reranker;这一阶段你应该能搭出生产可用的问答 / 知识库系统;
• 第 3 阶段:Agent + Tool Use (1-2 周):tool 装饰器、Tool Calling、AgentExecutor、Memory、Memory 类型选型;这一阶段你应该能搭多步推理 Agent;
• 第 4 阶段:LangGraph + 多 Agent (2-4 周):状态机、节点、边、Conditional、SUB-graph、Streaming、Human-in-the-Loop;这一阶段是 LangChain 2024-2025 重点,也是最难的部分;
• 第 5 阶段:Production 化 (持续):LangSmith 调试追踪、Evaluation(对比不同 prompt / 模型)、A/B Testing、Cache、Rate Limit、可观测性、LangServe / FastAPI 部署。

学习资源:① 官方文档 python.langchain.com — 2024 年底重写后质量极高;② LangChain Academy — 免费课程;③ LangChain YouTube — 官方 channel 有大量 tutorial;④ LangSmith 模板 — 参考成熟架构;⑤ GitHub Discussions — 社区活跃,问题响应快;⑥ LangChain 实战 Cookbook — github.com/langchain-ai/langchain/tree/master/cookbook。

最佳实践:① 永远开 LangSmith —— 调试效率提升 10 倍;② 版本要锁 —— 否则一个月后跑不了;③ Prompt 集中管理 —— 团队共享;④ Memory 选 ConversationSummaryMemory —— 多数场景胜过 Buffer;⑤ Tool 描述写清楚 —— 决定 Agent 是否会调用;⑥ 生产前必 Evaluation —— 用 LangSmith 的 Dataset 跑回归;⑦ 谨慎使用 max_iterations —— 太低会截断,太高会失控。

参考链接

• LangChain 官网
• LangChain GitHub
• LangChain Python 文档
• LangSmith 平台
• LangGraph 文档
• LangChain Academy
• LangChain YouTube

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测