一、为什么一定要学 LangChain？

1. LLM 裸调用只能做“问答玩具”——记不住、算不了、连不上网。
2. LangChain 提供“胶水层”：提示词模板、记忆、工具、代理、索引、链式编排，把大模型变成“有手有脚有记忆”的智能体。
3. 社区最活跃、文档最全、岗位 JD 里出现频率最高——早学早溢价 。

---

二、LangChain 全景速览

LangChain 1.x
├─ Models（大脑）
│  ├─ LLM：单轮文本补全
│  ├─ Chat Model：多轮角色对话
│  └─ Embeddings：向量化
├─ Prompts（提示词工程）
│  ├─ Template：动态变量
│  ├─ FewShot：动态示例
│  └─ OutputParser：结构化输出
├─ Memory（记忆）
│  ├─ Buffer：全量存
│  ├─ Window：最近 k 轮
│  ├─ Summary：滚动摘要
│  └─ Entity：抽实体长期记
├─ Indexes（外挂知识库）
│  ├─ Loader：500+ 文件格式
│  ├─ Splitter：语义分块
│  ├─ Embedding：向量
│  ├─ VectorStore：FAISS/PG/GCS
│  └─ Retriever：召回+重排
├─ Chains（工作流）
│  ├─ LLMChain：单步
│  ├─ SequentialChain：顺序
│  ├─ RouterChain：分支
│  └─ RetrievalQA：知识库问答
├─ Agents（自主智能体）
│  ├─ ReAct：推理+行动
│  ├─ OpenAI Functions：函数调用
│  └─ Plan-and-execute：先计划再干活
└─ Callbacks（可观测）
   ├─ 日志、耗时、Token
   └─ LangSmith：一键追踪

---

三、从零开始：5 分钟安装 + 第一个 Chain

# 1. 创环境
conda create -n lc python=3.11 -y && conda activate lc

# 2. 装核心+常用扩展
pip install langchain==1.0.0 openai python-dotenv

# 3. 最小 LLMChain（翻译+摘要）
from langchain.chat_models import ChatOpenAI
from langchain.prompts import ChatPromptTemplate
from langchain.chains import LLMChain

llm = ChatOpenAI(model="gpt-4o", temperature=0)
prompt = ChatPromptTemplate.from_messages([
    ("system", "你是翻译助手，把用户输入译成英文并给一句 20 字摘要"),
    ("user", "{text}")
])
chain = LLMChain(llm=llm, prompt=prompt)
print(chain.run("LangChain 让大模型长出手脚"))

输出：

LangChain enables LLMs to interact with the world.
Summary: A framework empowering LLMs with tools and memory.

✅ 至此，你已经完成第一个 Chain。

---

四、核心组件深度拆解 + 实战案例

每个案例<=30 行代码，可复制到 Jupyter 直接跑。

1. Prompts：动态 Few-Shot + 输出解析器

场景：电商客服，根据用户情绪自动选择“退货”或“补偿”模板，并返回 JSON 结构化动作。

from langchain.prompts import PromptTemplate
from langchain.output_parsers import PydanticOutputParser
from pydantic import BaseModel, Field

class Action(BaseModel):
    action: str = Field(description="退货|补偿|转人工")
    reason: str = Field(description="决策理由")

parser = PydanticOutputParser(pydantic_object=Action)

prompt = PromptTemplate(
    template="根据评价判断动作。\n{format_instructions}\n评价：{review}",
    input_variables=["review"],
    partial_variables={"format_instructions": parser.get_format_instructions()}
)

chain = prompt | llm | parser
print(chain.invoke({"review": "发货太慢，等了一周！但质量还行"}))

输出：

Action(action='补偿', reason='物流延迟影响体验，商品本身无问题')

---

2. Memory：三种记忆模式对比

记忆类型	优点	缺点	适用
Buffer	完整上下文	Token 爆炸	短对话
Window	固定轮数	早期信息丢失	通用
Summary	省 Token	摘要失真	长对话

代码：同一段聊天，三种 memory 效果对比

from langchain.memory import (
    ConversationBufferMemory,
    ConversationBufferWindowMemory,
    ConversationSummaryMemory
)

def chat_with(memory):
    chain = ConversationChain(llm=llm, memory=memory, verbose=True)
    chain.predict(input="我叫 Bob，喜欢徒步")
    chain.predict(input="帮我起个户外公众号名字？")
    chain.predict(input="刚才我叫啥？")   # 考记忆
    return memory.load_memory_variables({})

# 运行后可见 Buffer 能答出 Bob，Window(k=1) 会忘，Summary 能提取实体。

---

3. Indexes：30 行构建“ChatPDF”

from langchain.document_loaders import PyPDFLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain.vectorstores import FAISS
from langchain.embeddings import OpenAIEmbeddings
from langchain.chains import RetrievalQA

# 1. 加载+分块
docs = PyPDFLoader("2026-AGI-Report.pdf").load()
texts = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=200).split_documents(docs)

# 2. 向量库
db = FAISS.from_documents(texts, OpenAIEmbeddings())

# 3. 问答链
qa = RetrievalQA.from_chain_type(llm=llm, retriever=db.as_retriever())
print(qa.run("AGI 报告里对 Agent 的安全建议？"))

✅ 本地只依赖 CPU 也能毫秒级召回。

---

4. Agents：ReAct 模式拆解

ReAct = Reason + Act，循环如下：
LLM ⟹ 动作 ⟹ 工具 ⟹ 结果 ⟹ LLM …直到给出答案。

from langchain.tools import DuckDuckGoSearchRun
from langchain.agents import create_react_agent, AgentExecutor
from langchain.prompts import PromptTemplate

# 0. 工具： DuckDuckGo 搜索
search = DuckDuckGoSearchRun()
tools = [search]

# 1. 中文 ReAct 模板
template = """尽可能回答下列问题。你有以下工具可以使用：

{tools}

工具名称: {tool_names}

请严格按照以下格式回答：

问题: 输入的问题
思考: 你应该始终思考下一步该做什么
行动: 需要使用的工具名称，必须是 [{tool_names}] 之一
行动输入: 给工具输入的内容
观察: 工具返回的结果
...（思考/行动/行动输入/观察 可以重复 N 次）
思考: 现在我知道最终答案了
最终答案: 原始问题的最终答案

开始！

问题: {input}
思考: {agent_scratchpad}"""

prompt = PromptTemplate.from_template(template)

# 2. 创建 Agent
llm = ChatOpenAI(temperature=0, model="gpt-3.5-turbo")
agent = create_react_agent(llm, tools, prompt)
agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    verbose=True,          # 关键！能看到中文思考过程
    handle_parsing_errors=True
)

# 3. 运行
if __name__ == "__main__":
    question = "今天 NVIDIA 股价实时多少？"
    agent_executor.invoke({"input": question})

运行效果（示例）：

思考: 用户想知道 NVIDIA 今天的实时股价，我需要上网搜索最新行情。
行动: duckduckgo_search
行动输入: NVIDIA 股价 今天 实时
观察: 截至 2026-01-08 14:30，NVIDIA（NVDA）报 $512.34，涨幅 +2.18%。
思考: 现在我知道最终答案了
最终答案: 截至今天下午 2 点半，NVIDIA 股价为 $512.34，上涨约 2.18%。

---

5. 结构化工具 + OpenAI Functions

当工具参数多、类型复杂时，用 Functions 模式比 ReAct 更稳。

from pydantic import BaseModel, Field

class WeatherInput(BaseModel):
    city: str = Field(description="城市拼音，如 beijing")
    unit: str = Field("celsius", description="单位")

@tool("weather", args_schema=WeatherInput, return_direct=False)
def weather(city: str, unit: str) -> str:
    """查询实时天气"""
    return f"{city} 现在 30℃（{unit}）"

agent = initialize_agent(
    tools=[weather],
    llm=llm,
    agent=AgentType.OPENAI_FUNCTIONS,
    verbose=True
)
print(agent.run("北京天气如何？"))

---

6. 持久化 + 流式 + 观测：生产三件套

# 1. 持久化：把历史存 Redis
from langchain.memory import RedisChatMessageHistory
history = RedisChatMessageHistory(session_id="user_123", url="redis://localhost:6379")
memory = ConversationBufferMemory(chat_memory=history, return_messages=True)

# 2. 流式：逐字返回前端
from langchain.callbacks.streaming_stdout import StreamingStdOutCallbackHandler
llm = ChatOpenAI(streaming=True, callbacks=[StreamingStdOutCallbackHandler()])

# 3. 观测：LangSmith 一键追踪
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_PROJECT"] = "prod_demo"

部署到 K8s 后，可在 LangSmith 面板查看每次调用的 token、耗时、工具链。

---

五、从 Demo 到生产：完整工作流 checklist

阶段	关键动作	推荐工具/配置
数据	文档清洗、分块、embedding	RecursiveCharacterTextSplitter + OpenAIEmbeddings
记忆	多用户隔离、长对话压缩	RedisChatMessageHistory + ConversationSummaryMemory
工具	自定义 API、DB、AI 模型	StructuredTool + Pydantic 参数校验
代理	选模式：ReAct / Functions / Plan-and-execute	AgentType.OPENAI_FUNCTIONS 最稳
性能	异步、并发、缓存	asyncio.gather + InMemoryCache
观测	日志、token、异常追踪	LangSmith + Prometheus
安全	内容审核、权限隔离	OpenAI Moderation API + RBAC
部署	容器、自动扩缩、灰度	Docker + K8s + Argo CD

---

六、常见踩坑与解决方案

1. Token 爆炸

   • 症状：Memory 无限追加，最终 4096 溢出。
   • 解法：用 ConversationSummaryMemory 或 VectorStoreRetrieverMemory 做滚动摘要 。

2. Agent 死循环

   • 症状：反复调用同一工具，输出“Obs: None”。
   • 解法：工具 description 加“如果 xx 为空，应立刻返回 xx”；同时设 max_iterations=5。

3. 结构化工具解析失败

   • 症状：LLM 把参数拼成字符串而非 JSON。
   • 解法：改用 OPENAI_FUNCTIONS 模式，或给 description 加“请返回合法 JSON”。

4. 向量召回不准

   • 症状：Top-k 里找不到答案。
   • 解法：
     ① 调 chunk_size=500 + chunk_overlap=100；
     ② 用 MultiQueryRetriever 生成多组向量再召回；
     ③ 上重排模型 CohereRerank。

---

七、总结

LangChain = 模型 × 提示词 × 记忆 × 工具 × 链 × 代理 的“六边形战士”。
掌握它，你就拥有了把 LLM 从“聊天玩具”变成“生产级智能体”的完整方法论：

• 用 Prompts 把需求讲清；
• 用 Indexes 让模型“多读书”；
• 用 Memory 让它“长记性”；
• 用 Tools 给它“手脚”；
• 用 Agents 让它“自己动”；
• 用 Callbacks 让一切“可观测”。
  AI大模型学习代码仓库