Python
22 读懂 LangChain:语法桥
综合演练:拿真实书稿逐段精读,检验全部技能
- Python
- LangChain
- 进阶
目标:把 13–21 章攒下的九块积木全部用上,逐行读懂真实 LangChain 书稿里的 RAG 链与 Agent 代码——读完这一章,你就从「学过 Python」正式跨到「能自己开读 LangChain」。 与 LangChain 的关系:本章就是那座桥。所有摘编代码都来自仓库里的
../langchain-book-python/(下文简称「原书」),逐行标注用到了第几章的什么知识;读通本章,那本书可以整本开读。
1. 开场:恭喜,你已经站在桥上了
13 章开头我们说过:入门课毕业和读懂真实项目之间,隔着一层「惯用法」的雾。这层雾由九种语法织成——注解、lambda、装饰器、类、生成器、import、异常、with、pydantic。13–21 章把这九块积木一块块递给了你,但一直是分开学的。
真实代码不会这么客气。原书第 08 章的一条 RAG 链,短短二十几行里九块积木同时上场。本章做三件事:
- 技能地图:九块积木各用一句话回收,对着 LangChain 形态再认一遍脸;
- 十大惯用法速查 + 两段逐行精读(RAG 链、Agent):拿原书真实代码从头读到尾,每行标注知识点;
- 自测清单 + 开读路线:确认无死角后,给出那本书的推荐阅读顺序。
这一章没有新语法。它是毕业考试,也是登机牌。
2. 技能地图:13–21 章一行回收
| 章 | 一句话核心 | 在 LangChain 里的典型形态 |
|---|---|---|
| 13 类型注解实战 | 签名上的说明书:x: str、-> bool、Annotated[str, "描述"],运行时不拦错,但 IDE、pydantic、@tool 都读它 | 工具签名 base: Annotated[str, "基准货币代码,如 USD"](原书 12 章) |
| 14 函数进阶 | 函数是对象:可存、可传、可被包一层再返回;lambda 和装饰器都从这一条推出来 | 链里的 lambda input: input["question"]、工具定义 @tool(原书 8/12 章) |
| 15 面向对象进阶 | 类是模板、实例是产品;继承让组件共享接口,所以组件才能互相替换 | 每个组件都是类实例:ChatOpenAI()、InMemoryVectorStore(embeddings)(原书 1/8 章) |
| 16 迭代器与生成器 | for 的本质是不断 next();生成器边产边给,不占整块内存 | for chunk in chain.stream(...)(原书 1/10 章) |
| 17 模块、包与工程化 | import 按「包.模块」路径找名字;第三方库装进虚拟环境;密钥进 .env | from langchain_core.prompts import ChatPromptTemplate(原书 8 章) |
| 18 异常、调试与测试 | traceback 从下往上读;except 在边界兜住可预期的错,别让请求整体崩掉 | 分类链 except Exception: return "一般问题"(原书 12 章) |
| 19 文件与上下文管理器 | with = 进门领资源、出门自动还,哪怕中途抛错也还得掉 | with requests.post(...) as response: 读流式响应(原书 10 章) |
| 20 异步编程入门 | async/await:单线程在「等 I/O」时不闲着,切去干别的 | async for message, metadata in agent.astream(...)(原书 10 章) |
| 21 pydantic 数据建模 | 继承 BaseModel 得到带校验的数据类,一键生成 JSON Schema | 工具参数 schema、with_structured_output(原书 11 章) |
哪一行看着眼生,就点回哪一章补;全都眼熟,直接过关。
3. 十大惯用法速查
以下十条覆盖原书代码里出镜率最高的写法。每条都从原书对应章节逐字核对后摘编(个别为排版压缩了行数,写法与参数未改),注明出自原书第几章。
① @tool 装饰器(出自原书 12 章)
@tool
def calculator(expression: Annotated[str, "要计算的四则运算表达式"]) -> str:
"""计算四则运算表达式,如 17 * 7.24"""
用到:14 章装饰器、13 章注解。一句话:函数一行不改,@tool 把它包成工具对象——函数名变工具名、docstring 变工具说明、签名注解变参数 schema,全部自动提取。
② .pipe() 方法链(出自原书 1 章)
simple_chain = chat_model.pipe(output_parser)
用到:14 章(组件当值传)、15 章(方法调用)。一句话:把两个 Runnable(可运行组件)焊成一条 RunnableSequence,上游输出接下游输入;返回的新链仍是 Runnable,可以继续 pipe。
③ 链里的 lambda(出自原书 8 章)
retrieval_chain = RunnableSequence(
lambda input: input["question"],
retriever,
convert_docs_to_string,
)
用到:14 章 lambda、07 章字典取值。一句话:链的每一环必须是 Runnable,普通函数会被自动包装成 RunnableLambda——这里专职「从输入字典里抽出 question 字段」。
④ pydantic 模型作 schema(出自原书 11 章)
class GetCurrentWeather(BaseModel):
location: str = Field(description="The city and state, e.g. San Francisco, CA")
unit: Literal["celsius", "fahrenheit"] = Field(description="The unit of temperature")
用到:21 章 pydantic、13 章注解。一句话:用一个类声明「工具该收什么参数」,框架自动转成 JSON Schema 附给模型;Literal 限定取值枚举。
⑤ 类型注解签名(出自原书 5 章)
def code_file_filter(file_path: str) -> bool:
"""只加载代码文件,排除文档与配置"""
return not file_path.endswith((".md", ".json"))
用到:13 章类型注解。一句话:注解是写给读代码的人和工具看的说明书——不改变运行结果,但 IDE 能据此查错补全;放进 @tool 签名里还会升级成参数 schema。
⑥ for chunk in chain.stream()(出自原书 1 章)
stream = simple_chain.stream([HumanMessage("Tell me a joke")])
for chunk in stream:
print(chunk)
用到:16 章生成器、05 章 for 循环。一句话:stream 返回生成器,模型每吐一段(chunk)就能被循环体消费一段,用户不必等全文生成完。
⑦ with 管理资源(出自原书 10 章,参数有精简)
with requests.post(url, json=payload, stream=True) as response:
for chunk in response.iter_content(chunk_size=None, decode_unicode=True):
print(chunk, end="", flush=True)
用到:19 章上下文管理器、16 章迭代。一句话:HTTP 连接是典型的「借了要还」的资源,with 保证循环结束(哪怕中途抛错)也自动关闭连接。
⑧ try/except 容错(出自原书 12 章,逐字一致)
def classify(question):
try:
return classify_chain.invoke({"input": question}).type
except Exception:
return "一般问题"
用到:18 章异常处理。一句话:LLM 的输出不可能 100% 可解析,生产代码在边界处兜底——解析失败就返回安全的默认值,不让整个请求崩掉。
⑨ from langchain_x import Y 第三方导入(出自原书 8 章)
from langchain_classic.document_loaders import TextLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
用到:17 章包与模块、01 章安装。一句话:langchain 按职责拆成多个包(core / openai / text-splitters / classic…),import 路径就是「从哪个包的哪个模块拿哪些名字」;读代码先扫 import 段,就知道用了谁家的组件。
⑩ config={"configurable": {...}} 配置字典(出自原书 9 章)
thread_config = {"configurable": {"thread_id": "1"}}
res1 = agent.invoke({"messages": [{"role": "user", "content": "hi, 我叫小明"}]}, thread_config)
用到:07 章嵌套字典。一句话:invoke 的第二个参数是运行配置,嵌套字典里的 thread_id 是会话标识——同一个 thread_id 的多次调用共享一份记忆。
4. 完整精读演练:一条 RAG 链的解剖
下面这段摘自原书 08-RAG完整实现.md 的完整可运行代码(8.8 节):输入一本小说和一个问题,输出基于原文的回答。省略 import(见上节⑨)与 TEMPLATE 模板文本,右侧标注用到了本课程第几章的什么知识。
# ── 加载与切分 ─────────────────────────────────────────────
loader = TextLoader("data/qiu.txt", encoding="utf-8") # ← 17章·第三方类 19章·显式编码
docs = loader.load() # ← 15章·实例方法
splitter = RecursiveCharacterTextSplitter(
chunk_size=500, chunk_overlap=100 # ← 08章·关键字参数
)
split_docs = splitter.split_documents(docs) # ← 16章·产新列表,不动原数据
# ── 向量化与检索 ───────────────────────────────────────────
embeddings = OpenAIEmbeddings()
vectorstore = InMemoryVectorStore(embeddings) # ← 09章·实例当参数传
vectorstore.add_documents(split_docs)
retriever = vectorstore.as_retriever(search_kwargs={"k": 2}) # ← 07章·嵌套字典字面量
# ── 检索结果转纯文本 ───────────────────────────────────────
def convert_docs_to_string(documents): # ← 08章·自定义函数
return "\n".join(document.page_content for document in documents) # ← 14章·生成器表达式 15章·属性访问
# ── 组装整条链 ─────────────────────────────────────────────
retrieval_chain = RunnableSequence( # ← 14章·组件当值传递
lambda input: input["question"], # ← 14章·lambda 07章·字典取值
retriever,
convert_docs_to_string, # ← 14章·函数名不加括号=传函数本身
)
prompt = ChatPromptTemplate.from_template(TEMPLATE) # ← 15章·类方法当工厂
model = ChatOpenAI()
rag_chain = RunnableSequence(
{ # ← 07章·字典的值可以是任何对象
"context": retrieval_chain,
"question": lambda input: input["question"],
},
prompt,
model,
StrOutputParser(), # ← 15章·实例直接占一个"格子"
)
answer = rag_chain.invoke({"question": "谁提出了宏原子的假设?"}) # ← 07章·字典作输入
print(answer)
上面是原书原样引用(含它的
OpenAIEmbeddings()与ChatOpenAI())。你自己写的时候按本课程换成 GLM:embeddings那行换成OpenAIEmbeddings(base_url=os.environ["GLM_BASE_URL"], api_key=os.environ["GLM_API_KEY"], model=os.environ["EMBEDDING_ID"], check_embedding_ctx_length=False),model那行换成带base_url/api_key/model三参数的ChatOpenAI。语法结构与逐行注解完全不变——这正说明换模型只是换构造参数,链本身不动。完整写法见向量存储与配置。
逐段展开(编号对应上方注释圈号所在的小节):
- 加载与切分:
TextLoader(...)构造加载器实例(17 章的第三方类),.load()调它的方法(15 章),返回Document对象列表;encoding="utf-8"是关键字参数(08 章),显式指定编码避免中文乱码(19 章的老朋友)。切分器同理:构造时传chunk_size=500, chunk_overlap=100(每块约 500 字、相邻块重叠 100 字),split_documents返回切好的新列表(16 章:产新不改性)。 - 向量化与检索:
InMemoryVectorStore(embeddings)把 embedding 模型实例当参数传进去(09 章:对象装对象),add_documents逐块向量化入库;as_retriever(search_kwargs={"k": 2})一行里出现了方法链(15 章)和嵌套字典字面量(07 章)——每次检索取相似度最高的 2 块。 - 转纯文本:retriever 返回的是
Document列表,塞不进 prompt,所以自定义函数抽page_content拼接。"\n".join(生成器表达式)一行两个进阶点:生成器表达式惰性取值(14/16 章)、document.page_content是属性访问而非字典取键(15 章)。 - 组链:
RunnableSequence按位置接收一串组件,传的都是对象本身,没有括号调用(14 章的核心:函数/对象是值)。两个易错点——lambda input: input["question"]定义时不执行、链跑起来才执行;第一个位置参数是普通字典字面量,invoke 时每个键是一条并行分支,输出组装成{"context": ..., "question": ...}交给 prompt 填模板。 - 调用:整条链的输入就是一个字典(07 章),输出是
StrOutputParser()从AIMessage里抽出的纯字符串。
数据流图——同一份代码,换成「每个环节的值长什么样」的视角:
data/qiu.txt(一个 txt 文件)
│ TextLoader(...).load() ← 加载
▼
[Document] × 1(整本一个;page_content = 全文)
│ RecursiveCharacterTextSplitter.split_documents() ← 切分
▼
[Document] × N(每块约 500 字,相邻块重叠 100 字)
│ OpenAIEmbeddings 逐块向量化 + add_documents 入库
▼
InMemoryVectorStore(N 个向量,与 N 个块一一对应)
│ retriever.invoke(question):按相似度取 top-2
▼
[Document] × 2(检索结果,仍是 Document 对象)
│ convert_docs_to_string:抽 page_content,"\n".join 拼接
▼
context: str(一段原文纯文本)──────┐
├─► {"context": ..., "question": ...}
question: str(用户原话,透传)────┘ │
▼
ChatPromptTemplate 填充 {context}/{question}
▼
ChatOpenAI ──► AIMessage(模型原始回复对象)
▼
StrOutputParser ──► str(最终纯文本回答)
读链代码的通用套路:先找 invoke 看输入是什么类型,再顺着 pipe 方向追问「每一步把什么变成什么」。类型对得上,链就读懂了。
5. 读懂 Agent 代码:create_agent + @tool
第二段精读摘自原书 12-Agent系统.md:一个能「查汇率 + 算乘法」的 agent。
@tool # ← 14章·装饰器:函数外包一层再顶原名
def get_exchange_rate(
base: Annotated[str, "基准货币代码,如 USD"], # ← 13章·注解 + Annotated 附加说明
target: Annotated[str, "目标货币代码,如 CNY"],
) -> str: # ← 13章·返回值注解
"""查询两种货币之间的当前汇率""" # ← 17章·docstring,被 @tool 提取当工具说明
table = {"USD:CNY": 7.24, "USD:EUR": 0.92} # ← 07章·字典
rate = table.get(f"{base}:{target}") # ← 07章·get 安全取值 + f-string 拼接
if rate is not None: # ← 04章·条件 02章·is 判 None
return f"1 {base} = {rate} {target}"
return f"没有 {base} 到 {target} 的汇率数据"
agent = create_agent( # ← 08章·函数封装复杂度
model="openai:gpt-5.5",
system_prompt="你是一个乐于助人的助手",
tools=[get_exchange_rate, calculator], # ← 14章·函数对象存列表,注意没有括号
)
result = agent.invoke({
"messages": [{"role": "user", "content": "我有 17 美元,现在相当于多少人民币?"}], # ← 07章·嵌套字典
})
print(result["messages"][-1].content) # ← 06章·[-1] 取末位 15章·属性链
# 17 美元约等于 123.08 元人民币。
要点三条:
@tool之下的函数体就是普通 Python——字典、.get、f-string、条件返回,全部是 01–12 章的内容。装饰器只「没收」了签名和 docstring 去生成工具说明书(名字、描述、参数 schema),执行时跑的还是你写的这几行。tools=[get_exchange_rate, calculator]列表里存的是函数对象(14 章:没有括号就是传本身)。链和 agent 的区别在此:链的步骤由代码写死,agent 把工具集交给模型,由它临场决定调用哪个、传什么参数。result["messages"][-1].content三连:字典取键、列表负索引取最后一条、属性访问取正文——一行的功底全在 06/07/15 章。
一句话总结:Agent = 循环 + 工具调用。create_agent 内部自动跑「调模型 → 解析 tool_calls → 执行工具 → 结果回传 → 再调模型」,直到模型给出不含工具调用的最终回复。循环的执行模型、ReAct 历史机制、recursion_limit 防 token 失控,留给原书第 12 章展开。
6. 自测清单:能独立读懂以下写法吗
对照打勾,全部通过就可以出发了:
-
chain = prompt.pipe(model).pipe(parser)—— 能说出每一步的输入/输出类型,以及为什么接得上(14 章) -
lambda input: input["question"]—— 能说出这个 lambda 定义时干不干活、什么时候才真正执行(14 章) -
@tool装饰过的函数 —— 能说出函数名、docstring、参数注解分别被提取成了工具的什么(14 章) -
class Query(BaseModel): question: str = Field(description="...")—— 能说出这个类在运行时提供什么能力、Field的描述给谁看(21 章) -
def code_file_filter(file_path: str) -> bool—— 能说出注解写给谁看、不写会少什么(13 章) -
for chunk in chain.stream(msg)—— 能说出stream返回的对象是什么、chunk 从哪里来(16 章) -
with requests.post(...) as response:—— 能说出进入和退出 with 块时各自动发生了什么(19 章) -
except Exception: return "一般问题"—— 能说出这里兜的是什么错、为什么不让它冒出去(18 章) -
config = {"configurable": {"thread_id": "1"}}—— 能说出这个嵌套字典控制着什么、换一个值会怎样(07 章 + 原书 9 章) - 整条
rag_chain—— 能脱稿对着 4 节的数据流图,讲出每一站的类型变化
7. 开读路线:那本书该按什么顺序读
原书推荐按「先跑通、再深入」的顺序,每本的前置依赖一句话说明:
| 顺序 | 读什么 | 前置依赖一句话 |
|---|---|---|
| 0 | README | 只需会装包配 Key(17 章的 .env 用法直接照抄) |
| 1 | 01 认识 LangChain 与 LCEL | 13–17 章足够;pipe、invoke、stream 全是本章速查条目 |
| 2 | 03 输出解析器 | 引出 pydantic 输出,正好复习 21 章 |
| 3 | 05 文档加载器 | 只需 import 和类实例化,检索侧开工 |
| 4 | 06 文本切分 | 承接 05,全是参数调优 |
| 5 | 07 向量存储与检索优化 | 承接 06,FAISS 落盘会用到 19 章的文件思想 |
| 6 | 08 RAG 完整实现 | 里程碑:跑通本章精读的这条链,RAG 就通了 |
| 7 | 09 Memory 记忆系统 | 自定义中间件要继承类、覆写方法(15 章) |
| 8 | 11 Function Calling | pydantic schema 是主角,21 章必须熟 |
| 9 | 12 Agent 系统 | @tool 装饰器与 Annotated 注解(13/14 章) |
| 10 | 13 引导式交互实战 | 综合收尾,前面通了这本就是复习 |
02(Prompt 模板)、04(RAG 原理)偏理论,随时插读补课;10(流式部署)需要 20 章的 async 基础,放最后。
另有一条并行路线:本仓库 docs/ 目录是一套基于 LangChain 1.x 重写的使用文档(17 节正课 + FAQ + 术语表),章节结构与原书相近、API 全部更新(create_agent、middleware、checkpointer)。建议:拿原书建立体系,拿 1.x 文档对齐当前版本,两套互为对照。
卡住时的三步法(按顺序做,九成卡点在前两步就解掉):
- 看类型注解说明书:先读函数签名和 docstring(13 章:注解就是官方说明书),确认自己传的参数类型对不对;
- print 中间结果:把链拆开,对可疑的那一步单独
.invoke,然后print(type(x), x)看值的真实类型(18 章的调试直觉); - 查语法手册:确认是 Python 语法问题,去 最新Python语法手册 搜对应节;确认是 API 问题,回原书 00 术语表 或对应章节。
8. 收尾:过桥
四个半月前你从「Python 是什么」出发,现在你能对着一条二十行的 RAG 链说出每一行的来历,能看懂 agent 为什么「函数存进列表却不调用」。这不是背语法背出来的,是九块积木一块块亲手搭出来的。
桥那头的书不厚,但每一页你都已经认识上面的字了。去吧:langchain-book-python/README.md——从今天起,你读的是工程,不再是教材。(1.x 重写版从 docs/README.md 进,两者并行不悖。)