LangChain零基础入门：大模型应用开发实操指南

weixin_33895516

457人浏览 · 2026-07-12 12:25:26

weixin_33895516 · 2026-07-12 12:25:26 发布

1. 项目概述：这不是又一本“Hello World”式教程，而是一张能带你真正上路的LangChain实操地图

你点开这篇内容，大概率正站在一个有点兴奋又有点懵的路口：听说LangChain是当前最火的大模型应用开发框架，能快速把LLM变成你手里的“智能工具箱”，可一打开官方文档，满屏的Chain、Agent、Tool、Memory、Retriever……像闯进了一家没贴标签的零件仓库。别急，我带团队用LangChain落地过7个真实业务系统——从内部知识库问答机器人，到自动写周报+分析销售数据的AI助理，再到嵌入CRM的客户意图识别模块——踩过的坑比读过的文档还厚。这篇《LangChain入门：给零基础新手的趣味指南》，不是照着API手册念经，而是把我们从“第一次跑通hello world”到“上线后稳定扛住日均3000次调用”的全过程，掰开揉碎，用厨房里切菜、搭乐高、修水管这些你能立刻脑补出画面的生活逻辑，讲清楚LangChain到底在解决什么问题、为什么非得这么设计、哪些地方新手最容易卡死、以及卡死之后怎么三步内定位到根因。核心关键词就三个： LangChain、大模型应用开发、零基础入门 。它适合两类人：一类是完全没碰过Python或AI的职场人，比如市场专员想自己搭个竞品动态追踪Bot；另一类是会写代码但没接触过大模型生态的开发者，比如Java后端工程师想快速验证一个AI客服原型。你不需要提前装好CUDA驱动，也不用背诵Transformer公式——只要你会用手机APP，就能理解LangChain里“链（Chain）”的本质，就是把几个现成的“智能积木块”按顺序咔嗒扣紧，让它们自动传递信息、接力干活。接下来的内容，每一行都来自我们真实项目里的调试日志、会议白板草图和凌晨两点改完最后一行代码时的截图。现在，咱们直接动手。

2. 核心设计思路拆解：为什么LangChain不叫“LangSDK”或“LLM-Kit”，而偏偏叫“Chain”？

2.1 “链”不是比喻，是解决现实工程问题的刚性结构

很多人初学LangChain，第一反应是：“哦，就是把Prompt拼在一起？” 这是个危险的误解。我带的第一个实习生，花了三天时间手动拼接几十个Prompt模板，最后发现：当用户问“把上周三的销售数据和竞品A的财报摘要对比一下”，系统要么只返回销售数据，要么只返回财报，就是没法把两份结果“放一起对比”。问题出在哪？不是模型能力不够，而是缺乏一个 状态流转与上下文管理的骨架 。LangChain的“Chain”，本质是一个 有状态的函数管道（Stateful Function Pipeline） 。它强制规定：前一个环节的输出，必须以明确的数据结构（通常是字典）传给下一个环节；每个环节可以读取全局状态（比如整个对话历史），也能修改局部状态（比如临时存个API返回的JSON）。这就像老式自来水管道——水龙头（用户输入）一拧开，水流（数据）必须经过阀门（PromptTemplate）、加压泵（LLM调用）、过滤网（OutputParser）、储水罐（Memory），最后从花洒（最终响应）喷出来。中间任何一个接口没对齐（比如阀门出口尺寸和泵入口不匹配），整条线就断了。LangChain用 RunnableSequence 、 RunnableParallel 这些类，把这种物理世界的“接口标准”翻译成了代码契约。我们做内部知识库项目时，曾把RAG流程硬编码成函数调用链，结果当需要加入“用户偏好记忆”功能时，不得不重写全部67行逻辑；而换成LangChain的 ConversationalRetrievalChain 后，只加了3行配置： memory=ConversationBufferMemory(...) ，就自动把历史问答塞进了每次检索的上下文。这就是“链式结构”带来的可扩展性红利——它不承诺你写出多炫的算法，但保证你在加新功能时，不用推倒重来。

2.2 四大核心组件不是并列关系，而是分层协作的“作战梯队”

LangChain文档里常把Model、Prompt、Output Parser、Retriever并列为四大组件，但这容易让人误以为它们是平级的“零件”。实际在我们所有落地项目中，它们构成的是 三层纵深防御体系 ：

第一层：决策中枢（Agent + Tool）
负责判断“该干什么”。比如用户说“查下北京今天天气，再告诉我附近有没有川菜馆”，Agent不是自己去查天气，而是先调用 WeatherTool ，拿到结果后再调用 RestaurantSearchTool 。我们做过压力测试：当Tool数量超过12个时，纯Prompt驱动的Agent会频繁选错工具（错误率37%），而接入 SelfAskWithSearch 这类结构化Agent后，错误率降到5%以下。关键在于，Agent把“思考过程”显式化为步骤，而不是让LLM在黑盒里瞎猜。
第二层：信息枢纽（Retriever + Memory）
解决“从哪找数据”和“记得住什么”。Retriever不是简单的向量搜索，它必须和Embedding模型、向量库、元数据过滤器深度耦合。我们在金融合规项目中，要求检索结果必须标注“来源文档页码+条款编号”，这就迫使Retriever返回的不再是模糊的相似度分数，而是带结构化元数据的Document对象。Memory更微妙—— ConversationBufferWindowMemory 只记最近5轮，适合客服场景；而 EntityMemory 会自动提取对话中的人名、地名、事件，构建知识图谱节点，这是我们做高管访谈纪要生成的核心。
第三层：执行单元（Model + Prompt + OutputParser）
真正“干活”的肌肉。这里新手最大误区是过度优化Prompt。我们实测过：在相同模型（gpt-3.5-turbo）下，把Prompt从120字精简到80字，响应速度提升18%，但准确率反而下降2.3%。因为LLM需要足够的“思维引导词”来对齐任务。OutputParser才是隐藏王牌—— PydanticOutputParser 能把LLM胡写的JSON强行解析成Pydantic模型，哪怕它漏了字段、多了逗号，我们用它把销售日报里“Q3营收：¥12,345,678”这种带千分位符的字符串，稳稳转成float类型，避免后续计算报错。

提示：别一上来就研究Agent。我们90%的初期项目，用 LLMChain （Model+Prompt+Parser）+ RetrievalQA （Retriever+Memory）组合就能覆盖需求。Agent是“特种部队”，Chain是“常规步兵”，先练好基本功再上战场。

2.3 为什么放弃“手写HTTP请求”，选择LangChain封装？

有人质疑：“我直接用OpenAI SDK发POST请求，不比LangChain少写代码？” 这话在单次调用时成立，但当业务复杂度上升，代价立刻显现。我们有个电商项目，需要实现“根据用户历史订单，推荐3款相似商品，并生成个性化推荐理由”。手写方案要处理：

请求头认证（API Key轮换）
重试逻辑（网络抖动时自动重试3次）
流式响应解析（SSE格式转换）
Token计数与截断（防止超长输入）
错误分类（429限流？401密钥失效？500服务端崩？）

而LangChain一行代码搞定： llm = ChatOpenAI(model_name="gpt-3.5-turbo", temperature=0.3, streaming=True, max_retries=3) 。它背后封装了 tenacity 重试库、 httpx 异步客户端、 tiktoken 分词器。更关键的是 可观测性 ——我们线上监控系统能直接抓取LangChain的 on_llm_start 、 on_chain_end 等回调事件，实时看到每个Chain的耗时、Token消耗、错误类型。手写HTTP请求？你得自己埋点、自己解析日志、自己画监控图表。LangChain不是帮你少写几行代码，而是帮你省下搭建运维体系的200小时。

3. 零基础实操全流程：从安装第一个包到跑通带记忆的问答机器人

3.1 环境准备：避开Python版本和依赖地狱的3个致命陷阱

新手第一步常栽在环境上。我们统计过，72%的“pip install langchain失败”案例，根源不在LangChain本身。以下是血泪经验：

陷阱1：Python版本错配
LangChain v0.1.x要求Python ≥3.8.1，但很多Mac用户用系统自带的Python 3.9，却没注意到Apple Silicon芯片（M1/M2）需要arm64架构的包。直接 pip install langchain 会报 ERROR: No matching distribution found for langchain 。解决方案：用 pyenv 安装纯净Python：
```
# 先卸载brew装的python（它常混用x86/arm64）
brew uninstall python
# 安装pyenv管理多版本
brew install pyenv
# 安装arm64专用Python（以3.11为例）
pyenv install 3.11.8
pyenv global 3.11.8
# 验证架构
python -c "import platform; print(platform.machine())"  # 应输出 arm64
```
陷阱2：向量库依赖冲突
LangChain默认用 chromadb 做向量存储，但它依赖 numpy 和 protobuf ，而这两个库在Windows上极易和 tensorflow 等包冲突。我们的标准做法是： 永远用conda创建隔离环境 。
```
conda create -n langchain-env python=3.11
conda activate langchain-env
# 安装langchain前，先装好底层依赖
conda install numpy protobuf -c conda-forge
pip install langchain langchain-community langchain-openai
```

陷阱3：API密钥管理不当
别把OpenAI密钥写死在代码里！我们见过实习生把密钥提交到GitHub，导致$2000账单。正确姿势是用 .env 文件：

# 创建 .env 文件（注意：.gitignore 必须包含 .env）
echo "OPENAI_API_KEY=sk-xxx" > .env
echo "LANGCHAIN_TRACING_V2=true" >> .env
echo "LANGCHAIN_API_KEY=lsk-xxx" >> .env  # LangSmith监控密钥

然后在代码里：

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
import os
from dotenv import load_dotenv
load_dotenv()  # 自动读取 .env

llm = ChatOpenAI(
    model_name="gpt-3.5-turbo",
    temperature=0.3,
    # 密钥自动从环境变量读取，无需写死
)

注意： LANGCHAIN_TRACING_V2=true 开启LangSmith监控，这是LangChain官方的可视化调试平台。它能让你看到每个Chain的输入/输出、耗时、Token数，比print调试高效10倍。免费版够个人项目用。

3.2 第一个Chain：用5行代码实现“智能回声壁”，理解数据流本质

别急着搞RAG或Agent，先做一个最简Chain，亲手感受“链”的脉搏。目标：用户输入一句话，模型返回“你说的是：[原句]，对吗？”。这不是废话，它在训练你对 Runnable 接口的肌肉记忆。

# step1.py
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langchain_core.runnables import RunnablePassthrough

# 构建Prompt模板：注意{input}是占位符
prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一个严谨的复述助手，必须一字不差重复用户的话"),
    ("human", "{input}")
])

# 初始化大模型（自动读取OPENAI_API_KEY环境变量）
llm = ChatOpenAI(model_name="gpt-3.5-turbo", temperature=0)

# 创建Chain：Prompt -> LLM -> 输出解析（这里用默认解析器）
chain = prompt | llm

# 执行！输入是字典，key必须和Prompt里的占位符一致
result = chain.invoke({"input": "今天北京天气真好"})
print(result.content)  # 输出：你说的是：今天北京天气真好，对吗？

关键原理拆解 ：

| 符号是LangChain的“管道操作符”，等价于 RunnableSequence([prompt, llm]) 。它强制数据以 dict 形式流动， prompt 接收 {"input": "..."} ，返回 ChatPromptValue 对象； llm 接收该对象，返回 AIMessage 对象。
invoke() 是同步调用， stream() 是流式调用（适合Web界面实时显示）。
为什么不用 llm.invoke(prompt.format(input="...")) ？因为那样就绕过了Chain的状态管理，后续加Memory、Retriever时会崩溃。

实操心得 ：

如果报错 No module named 'langchain_openai' ，说明你装的是旧版LangChain（<0.1）。新版已拆包，必须单独 pip install langchain-openai 。
如果响应慢，检查是否开了 streaming=True （流式模式在小文本上反而更慢）。
把 temperature=0 改成 0.7 ，再运行一次，观察输出变化——这就是控制“创造性”的旋钮，温度越高，LLM越敢自由发挥。

3.3 进阶实战：搭建带记忆的问答机器人，3步搞定对话历史管理

现在升级到真实场景：让用户连续提问，机器人能记住上下文。比如：
用户：“苹果公司CEO是谁？”
机器人：“蒂姆·库克。”
用户：“他年薪多少？”
机器人：“蒂姆·库克2023年总薪酬为6500万美元。”

这需要 Memory 组件。新手常犯的错是：以为加个 ConversationBufferMemory 就万事大吉，结果发现第二轮提问时，历史记录根本没传给LLM。真相是： Memory必须和Prompt深度绑定 。

# step2_memory.py
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_openai import ChatOpenAI
from langchain.memory import ConversationBufferMemory
from langchain.chains import LLMChain

# 关键1：Prompt必须预留历史消息占位符
prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一个知识丰富的助手，请基于历史对话和当前问题回答用户。"),
    MessagesPlaceholder(variable_name="history"),  # ← 历史消息插槽
    ("human", "{input}")  # ← 当前输入插槽
])

llm = ChatOpenAI(model_name="gpt-3.5-turbo", temperature=0)

# 关键2：Memory实例化时指定返回键（必须和Prompt占位符名一致）
memory = ConversationBufferMemory(
    memory_key="history",  # ← 和MessagesPlaceholder的variable_name一致
    return_messages=True   # ← 必须为True，否则返回字符串而非Message列表
)

# 关键3：用LLMChain包装，自动注入memory
chain = LLMChain(
    llm=llm,
    prompt=prompt,
    memory=memory,
    verbose=True  # 开启详细日志，看数据怎么流
)

# 连续调用（模拟真实对话）
response1 = chain.invoke({"input": "苹果公司CEO是谁？"})
print("Q1:", response1["input"])
print("A1:", response1["text"])

response2 = chain.invoke({"input": "他年薪多少？"})
print("Q2:", response2["input"])
print("A2:", response2["text"])
# 输出A2会包含Q1的上下文，如：“蒂姆·库克2023年总薪酬为6500万美元。”

为什么必须 return_messages=True ？
因为 MessagesPlaceholder 期望接收 [HumanMessage, AIMessage, HumanMessage...] 列表，如果 return_messages=False ，Memory返回的是字符串 "Human: ... AI: ..." ，Prompt模板无法解析，直接报错。这是90%新手卡住的第一道墙。

内存管理技巧 ：

ConversationBufferWindowMemory(k=3) 只保留最近3轮对话，防爆内存。
ConversationSummaryMemory 会把历史对话自动总结成一句，适合长对话场景。
我们在线上系统用 RedisChatMessageHistory ，把Memory存在Redis里，实现多实例共享对话状态。

3.4 终极整合：RAG问答机器人——让LLM“读懂”你的PDF文档

这才是LangChain的杀手锏。我们帮某律所做的合同审查Bot，就是靠这招把300页PDF合同秒变可问答的知识库。核心是 RetrievalQA 链，但新手常忽略三个细节：

细节1：文档切分策略决定准确率上限
别用默认 RecursiveCharacterTextSplitter 。法律合同里，“第3.2条”必须和“本条款所述义务”在同一chunk，否则检索会丢关键上下文。我们用 SemanticChunker （基于语义相似度）：
```
from langchain_experimental.text_splitter import SemanticChunker
from langchain_openai.embeddings import OpenAIEmbeddings

text_splitter = SemanticChunker(
    OpenAIEmbeddings(), 
    breakpoint_threshold_type="percentile"  # 按语义断点切分
)
```

细节2：向量库必须支持元数据过滤
用户问“关于付款方式的条款”，不能只搜“付款”，还要限定在 section="payment" 的chunk里。 ChromaDB 原生支持：

from langchain_community.vectorstores import Chroma

vectorstore = Chroma.from_documents(
    documents=chunks,
    embedding=OpenAIEmbeddings(),
    persist_directory="./chroma_db",
    collection_metadata={"hnsw:space": "cosine"}  # 指定距离算法
)
# 检索时加过滤
retriever = vectorstore.as_retriever(
    search_kwargs={"filter": {"section": "payment"}}
)

细节3：Prompt必须引导LLM引用来源
否则LLM会“幻觉”编造条款。我们用这个Prompt模板：

qa_prompt = ChatPromptTemplate.from_messages([
    ("system", """你是一个严谨的法律助手。请严格基于以下【参考资料】回答问题。
    【参考资料】：
    {context}
    
    要求：
    1. 若参考资料未提及，回答“根据提供的资料，无法确定”；
    2. 每个答案末尾必须标注“依据：[文档名]第X页”；
    3. 不要解释推理过程，直接给出结论。"""),
    ("human", "{question}")
])

完整RAG链代码：

# step3_rag.py
from langchain.chains import RetrievalQA
from langchain_community.document_loaders import PyPDFLoader
from langchain_openai import ChatOpenAI

# 加载PDF（支持多页）
loader = PyPDFLoader("contract.pdf")
docs = loader.load()

# 切分+向量化（此处简化，实际用上面的SemanticChunker）
from langchain.text_splitter import RecursiveCharacterTextSplitter
text_splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)
chunks = text_splitter.split_documents(docs)

vectorstore = Chroma.from_documents(chunks, OpenAIEmbeddings())
retriever = vectorstore.as_retriever()

# 构建RAG Chain
qa_chain = RetrievalQA.from_chain_type(
    llm=ChatOpenAI(model_name="gpt-3.5-turbo", temperature=0),
    chain_type="stuff",  # 三种模式：stuff（全塞进Prompt）、map_reduce（分段处理）、refine（迭代优化）
    retriever=retriever,
    return_source_documents=True,  # 返回参考的chunk，用于溯源
    verbose=True
)

# 提问
result = qa_chain.invoke({"query": "违约金如何计算？"})
print("答案：", result["result"])
print("来源：", result["source_documents"][0].metadata["source"])

性能实测数据 ：

300页PDF，切分成约1200个chunk，向量化耗时47秒（M2 Mac Mini）。
单次检索平均响应时间：1.2秒（含LLM生成）。
准确率：在50个测试问题中，42个完全正确，5个部分正确（需人工微调Prompt），3个因PDF扫描质量差失败。

4. 常见问题与排查技巧实录：那些让我们加班到凌晨的Bug和解法

4.1 “KeyError: 'input'”——最扎心的5分钟debug

现象：

chain.invoke({"question": "苹果CEO是谁？"})  # 报错 KeyError: 'input'

根因：
Prompt模板里写的是 {input} ，但你传的key是 question 。LangChain的 invoke() 方法不会自动映射key名，它严格按字典key匹配占位符。

排查三步法 ：

看Prompt定义 ： print(prompt.template) 或 print(prompt.messages) ，确认占位符名。
看传入字典 ： print(list(input_dict.keys())) ，确认key名是否一致。

用 RunnablePassthrough.assign() 做key映射 （高级技巧）：

from langchain_core.runnables import RunnablePassthrough

# 把question映射为input
chain = (
    {"input": RunnablePassthrough()}  # 直接透传
    | prompt 
    | llm
)
# 现在可以 chain.invoke({"question": "..."}) 了

避坑口诀 ：

占位符名即契约名，传参key必须严丝合缝；
模板写 {input} ，你就传 {"input": "..."} ；
模板写 {query} ，你就传 {"query": "..."} 。

4.2 “Context length exceeded”——Token超限的隐形杀手

现象：
LLM返回空响应，或报错 context_length_exceeded ，但你明明只输入了10个字。

真相：
LangChain在组装Prompt时，会把System Message、History、Input全拼在一起。比如：

System Message：50 tokens
History（2轮对话）：320 tokens
Input：10 tokens
模型最大上下文：4096 tokens
→ 剩余给LLM生成的空间只剩3626 tokens，看似充裕，但若你用 map_reduce 模式，LangChain会把所有检索结果塞进一次调用，瞬间爆掉。

解决方案矩阵 ：

场景	方案	实操代码
单次调用超限	缩短System Message，用 `trim` 裁剪History	`memory = ConversationBufferWindowMemory(k=2)`
RAG检索结果超限	改用 `refine` 链模式，分步处理	`chain_type="refine"`
必须塞大量文本	用 `LLMChain` + `StuffDocumentsChain` 手动控制	见LangChain文档 `StuffDocumentsChain` 章节

实测技巧 ：
我们用 tiktoken 库实时监控：

import tiktoken
enc = tiktoken.encoding_for_model("gpt-3.5-turbo")
def count_tokens(text):
    return len(enc.encode(text))
print("Prompt tokens:", count_tokens(prompt.format(input="...")))

4.3 “Retriever返回空列表”——向量搜索失灵的5个检查点

现象：
retriever.invoke("苹果CEO") 返回 [] ，但你知道文档里肯定有相关内容。

逐级排查清单 ：

检查文档是否成功加载 ： print(len(docs)) ，若为0，是PDF加载器问题（扫描版PDF需用 PyMuPDFLoader ）。
检查切分是否合理 ： print(chunks[0].page_content[:100]) ，确认没被切成乱码。
检查Embedding是否一致 ：向量库用 OpenAIEmbeddings() ，检索时也必须用同一个实例，不能新建。
检查相似度阈值 ： retriever = vectorstore.as_retriever(search_kwargs={"k": 5, "score_threshold": 0.5}) ，降低阈值。

终极验证 ：手动计算查询向量，看是否真无相似项：

query_embedding = OpenAIEmbeddings().embed_query("苹果CEO")
docs_with_scores = vectorstore.similarity_search_by_vector(query_embedding, k=5)
print("手动检索结果：", docs_with_scores)

血泪教训 ：
某次我们发现检索为空，最后定位到是 ChromaDB 版本升级后，默认距离算法从 l2 变成 cosine ，而我们的Embedding是用 text-embedding-ada-002 生成的，必须用 cosine 。解决方案：初始化向量库时显式指定：

vectorstore = Chroma.from_documents(
    chunks, 
    embedding, 
    collection_metadata={"hnsw:space": "cosine"}  # 强制cosine
)

4.4 “LangSmith看不到Trace”——监控失效的静默故障

现象：
开了 LANGCHAIN_TRACING_V2=true ，但LangSmith官网看不到任何trace。

根因TOP3 ：

密钥错误 ： LANGCHAIN_API_KEY 不是LangSmith的密钥（需在https://smith.langchain.com/settings里复制）。

网络拦截 ：公司防火墙屏蔽了 https://api.smith.langchain.com 。用curl测试：

curl -X POST https://api.smith.langchain.com/runs \
  -H "Content-Type: application/json" \
  -H "x-api-key: lsk-xxx" \
  -d '{"name":"test","run_type":"llm"}'

异步冲突 ：在Jupyter Notebook里， await 和 asyncio.run() 混用导致事件循环卡死。解决方案：统一用 loop.run_until_complete() 。

调试黄金命令 ：

# 查看LangChain所有环境变量
python -c "import os; [print(k,v) for k,v in os.environ.items() if 'LANGCHAIN' in k]"

# 强制刷新LangSmith缓存
export LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"

生产环境必设参数 ：

import os
os.environ["LANGCHAIN_PROJECT"] = "prod-contract-bot"  # 分项目归类
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_ENDPOINT"] = "https://api.smith.langchain.com"

5. 工具链与生态整合：LangChain不是孤岛，而是连接大模型世界的枢纽

5.1 LangChain与LangGraph：当“链”进化成“图”，应对复杂决策流

Chain 适合线性流程（A→B→C），但真实业务常是分支结构。比如客服Bot：
用户说“我要退款” → 判断订单状态 → 若已发货，走退货流程；若未发货，直接退款。

这时 LangGraph 登场。它用 StateGraph 定义节点和边，把条件判断显式化：

from langgraph.graph import StateGraph, END
from typing import TypedDict, Annotated, List

class GraphState(TypedDict):
    order_id: str
    order_status: str
    refund_method: str

def check_order_status(state: GraphState) -> GraphState:
    # 调用订单系统API
    status = get_order_status(state["order_id"])
    return {"order_status": status}

def handle_shipped(state: GraphState) -> GraphState:
    return {"refund_method": "return_and_refund"}

def handle_unshipped(state: GraphState) -> GraphState:
    return {"refund_method": "instant_refund"}

# 构建图
workflow = StateGraph(GraphState)
workflow.add_node("check_status", check_order_status)
workflow.add_node("handle_shipped", handle_shipped)
workflow.add_node("handle_unshipped", handle_unshipped)

# 设置条件边
def route_to_handler(state: GraphState) -> str:
    return "handle_shipped" if state["order_status"] == "shipped" else "handle_unshipped"

workflow.set_entry_point("check_status")
workflow.add_conditional_edges(
    "check_status",
    route_to_handler,
    {
        "handle_shipped": "handle_shipped",
        "handle_unshipped": "handle_unshipped"
    }
)
workflow.add_edge("handle_shipped", END)
workflow.add_edge("handle_unshipped", END)

app = workflow.compile()
result = app.invoke({"order_id": "ORD-12345"})

为什么不用if-else？
因为LangGraph的图结构可被LangSmith可视化，每个节点的输入/输出、耗时、错误率一目了然。我们线上系统用它监控“退款成功率”，当 handle_shipped 节点错误率突增，立刻知道是物流API不稳定，而不是LLM的问题。

5.2 LangChain与LlamaIndex：双剑合璧，各司其职

常有人问：“LangChain和LlamaIndex有什么区别？” 我们的实践结论是：

LangChain是“应用框架” ：管流程、管记忆、管工具调度、管监控。
LlamaIndex是“检索引擎” ：专精于文档理解、高级检索（HyDE、RAG-Fusion）、结构化数据接入（SQL、API）。

我们做财务分析Bot时，用LlamaIndex处理Excel：

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.readers.file import PandasCSVReader

# LlamaIndex原生支持CSV/Excel
reader = PandasCSVReader()
documents = reader.load_data("./sales_q3.csv")

index = VectorStoreIndex.from_documents(documents)
# 转成LangChain的Retriever
retriever = index.as_retriever(similarity_top_k=3)

选型决策树 ：

需要接入数据库/Excel/API？→ 优先LlamaIndex的Reader。
需要多步Agent决策？→ 用LangChain的Agent。
需要企业级权限控制？→ LlamaIndex的 AccessControlledIndex 更成熟。

5.3 LangChain与Docker：生产环境部署的3个硬性要求

本地跑通≠能上线。我们交付的每个LangChain服务，都遵循这三条铁律：

铁律1：必须用 uvicorn 替代 flask
LangChain的 streaming 响应依赖ASGI协议，Flask是WSGI，不兼容。Dockerfile必须：

FROM python:3.11-slim
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . /app
WORKDIR /app
# 关键：用uvicorn启动
CMD ["uvicorn", "app:app", "--host", "0.0.0.0:8000", "--port", "8000", "--reload"]

铁律2：向量库必须外置
ChromaDB 默认用本地文件，Docker重启就丢数据。生产必须连外部PostgreSQL：
```
import chromadb
client = chromadb.HttpClient(
    host="chroma-db-service",  # Kubernetes Service名
    port=8000
)
```

铁律3：API密钥必须用Secrets管理
Docker Compose里：

services:
  langchain-app:
    build: .
    environment:
      - OPENAI_API_KEY_FILE=/run/secrets/openai_key
    secrets:
      - openai_key
secrets:
  openai_key:
    file: ./openai.key

压测数据 ：
单个 gpt-3.5-turbo 实例，在 uvicorn --workers 4 配置下，QPS达23，P95延迟1.8秒。加Redis缓存 ChatMessageHistory 后，QPS升至41。

6. 从入门到进阶的路径规划：避开“学完就忘”的认知陷阱

6.1 新手常走的3条弯路，以及我们踩出来的正道

弯路1：死磕源码，忽略API契约
有人一上来就翻 langchain/chains/base.py ，试图理解 Runnable 的17个抽象方法。结果两周过去，连 LLMChain 都没跑通。正道是： 把LangChain当乐高说明书用，不是当发动机维修手册 。先掌握 invoke() 、 stream() 、 batch() 三个方法，90%场景够用。源码留到你遇到 CustomChain 需求时再深挖。
弯路2：过早追求“全自动”，忽视人工校验闭环
我们最早做的销售数据Bot，曾设“自动修正错误”功能——当LLM把“Q3营收”错写成“Q4”，Bot自动调用 pandas 修复。结果它把“¥12,345,678”修正成“12345678”，漏了小数点。现在所有关键输出，都加人工审核环节： LLMChain 生成 → OutputParser 结构化 → HumanInLoopChecker 弹窗确认 → FinalExporter 导出。 AI负责“快”，人负责“准” 。
弯路3：迷信“最新版”，忽略稳定性
LangChain v0.1.0发布时，我们团队全员升级，结果 ConversationSummaryMemory 的 predict_new_summary 方法签名变更，导致所有对话总结功能瘫痪2天。现在策略是： 生产环境锁死小版本号 （如 langchain==0.1.14 ），