LangChain
05 · LCEL 与 Runnable
组链、invoke/batch/stream、fallback
- LangChain
- Python
本节速览
这一节的每一块内容,分别是干什么的:
| 内容 | 是干什么的 |
|---|---|
| 统一接口(Runnable) | 所有组件同一套 invoke / batch / stream,可随意替换组合 |
| pipe 组链 | 把组件像管道一样串成 chain |
| RunnablePassthrough.assign | 透传输入的同时往下游追加字段 |
| 重试与 fallback | 失败自动重试、自动切换备用链 |
| Callbacks 与 Tracing | 观测链上每一次调用的输入输出 |
LCEL(LangChain Expression Language)是 LangChain 的编排方式。核心是 Runnable 抽象类:模型、prompt 模板、输出解析器、整条 chain 都实现了它。一条 chain 本身也是 Runnable,可以作为另一条 chain 的组成部分任意嵌套。
统一接口
没有它会怎样——prompt 有 prompt 的用法、模型有模型的用法、parser 有 parser 的用法,拼一条链要给每个组件写专门的胶水代码,换个组件胶水重写。
有了它——所有组件都实现 Runnable,invoke / batch / stream 三板斧通用,组件随换随拼。
所有 Runnable 共享同一组调用方法:
| 方法 | 行为 |
|---|---|
invoke(input) | 单次调用,传入一个输入 |
batch([input1, input2]) | 批量调用,自动并行执行以降低总延迟 |
stream(input) | 流式返回生成器,每个 chunk 到达即可消费 |
三种方式用同一条链,不需要为批量或流式重写代码:
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
from langchain_core.output_parsers import StrOutputParser # 提取纯文本
load_dotenv()
llm = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
)
chain = llm.pipe(StrOutputParser())
# batch:两个问题并行执行,返回一组结果
print(chain.batch(["讲个笑话", "讲个谜语"]))
# ['为什么科学家不信原子?……', '什么东西越洗越脏?……']
# stream:逐段产出,到一段处理一段,用户不用等完整回复
for chunk in chain.stream("用一百字解释什么是递归"):
print(chunk, end="", flush=True)
pipe 组链
没有它会怎样——手动接力:messages = prompt.format(...)、resp = llm.invoke(messages)、text = parser.parse(resp),中间变量一大堆,少传一步就 AttributeError。
有了它——prompt.pipe(llm).pipe(parser),一条链一个对象,invoke 一次到底。
.pipe() 把上游输出接给下游输入,等价写法是 | 运算符:
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
from langchain_core.output_parsers import StrOutputParser # 提取纯文本
load_dotenv()
llm = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
)
chain = llm.pipe(StrOutputParser())
# 等价写法:llm | StrOutputParser()
chain.invoke("讲一个笑话")
要点:
pipe返回RunnableSequence,它同样实现 invoke / batch / stream,调用方式与单模块一致。- 上游输出类型必须匹配下游输入类型,数据沿 pipe 方向流动。
- LCEL 的目标是「从原型到生产」不改代码:链内可并行的步骤自动并行,内置重试与 fallback,支持 LangSmith 追踪。
字典自动转 RunnableMap
没有它会怎样——链要同时准备 context 和 question 两个输入,得手写函数分别取值再组装,每加一个字段改一次组装函数。
有了它——传个 dict 进去,键就是下游输入名,自动并行分发,加字段只加一行。
RunnableSequence 的第一步如果是普通字典字面量,会自动转成 RunnableMap:字典的每个键是一个 Runnable,invoke 时各分支并行执行,输出按键名组装成新字典。RAG 链里同时取「检索结果」和「原始问题」就靠它:
from langchain_core.output_parsers import StrOutputParser # 提取纯文本
from langchain_core.prompts import ChatPromptTemplate # 带角色的消息模板
from langchain_core.runnables import RunnableLambda, RunnableSequence # 函数转 Runnable、顺序串联
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
load_dotenv()
model = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
)
prompt = ChatPromptTemplate.from_messages([
{"role": "system", "content": "仅依据下面的资料回答问题,资料里没有就回答「资料里没有」。\n资料:{context}"},
{"role": "human", "content": "{question}"},
])
# 检索子链:演示用 lambda 模拟产出原文;真实项目接 vectorstore.as_retriever()
retrieval_chain = RunnableLambda(lambda question: "……检索到的原文……")
rag_chain = RunnableSequence(
{
"context": retrieval_chain, # 子链,产出检索到的原文
"question": lambda input: input["question"], # 透传原问题
},
prompt, # 收到 {"context": ..., "question": ...}
model,
StrOutputParser(),
)
print(rag_chain.invoke({"question": "秋天的后园里长着什么树"}))
普通函数放进 chain 会自动包装为 RunnableLambda,不需要手动转换。
RunnablePassthrough.assign
没有它会怎样——RAG 的 prompt 同时要 {context} 和 {question},但链入口只有 question;直接接检索器,原问题到下一步就丢了,{question} 渲染成空。
有了它——assign 把检索结果追加在原输入旁边一起透传,两个字段都在。
在原输入字典上追加字段,不丢弃已有字段:
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
from langchain_core.output_parsers import StrOutputParser # 提取纯文本
from langchain_core.prompts import ChatPromptTemplate # 带角色的消息模板
from langchain_core.runnables import RunnablePassthrough # 透传输入并追加字段
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
load_dotenv()
model = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
)
# 改写链:结合对话记录,把带代词的追问改写成信息完整的独立问题(工程完整版见第 18 章)
rephrase_chain = ChatPromptTemplate.from_messages([
{"role": "system", "content": "结合下面的对话记录,把用户的后续问题改写为一个信息完整的独立问题,"
"让没看过对话的人也能理解。只输出改写后的问题。\n对话记录:\n{history}"},
{"role": "human", "content": "{question}"},
]).pipe(model).pipe(StrOutputParser())
chain_step = RunnablePassthrough.assign(standalone_question=rephrase_chain)
# 输入 {"question": ..., "history": ...}
# 输出 {"question": ..., "history": ..., "standalone_question": ...}
result = chain_step.invoke({
"question": "他提出了什么假设?",
"history": "用户:介绍下丁仪\n助手:丁仪是《球状闪电》中的物理学家,沉迷于球状闪电的研究。",
})
print(result["standalone_question"])
# 丁仪在《球状闪电》中提出了什么假设?
容错:重试与 fallback
没有它会怎样——API 偶发 429 / 超时,一次失败整条链直接抛异常,用户看到 500;高峰期错误率肉眼可见。
有了它——with_retry 自动重试瞬时错误,with_fallbacks 主模型挂了自动切备用,用户无感。
模型自带出错自动重试,由构造参数 max_retries 控制(默认 2,只重试网络错误、429 限流、5xx)。重试解决不了的问题(Key 无效、服务整体故障)交给 fallback:主对象失败时依次尝试备选。
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
load_dotenv()
fake_llm = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key="invalid-key", # 故意的错误 Key,必定 401
model=os.environ["GLM_MODEL_ID"],
max_retries=0, # 不重试,立刻失败好演示 fallback
)
real_llm = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
)
llm_with_fallback = fake_llm.with_fallbacks(fallbacks=[real_llm])
llm_with_fallback.invoke("你好") # fake 失败后自动切到 real,返回正常结果
fallbacks是列表,按顺序逐个尝试,全部失败才抛错。- 任何 Runnable 都能挂 fallback:给 chain 中某个易错环节单独挂,或给整条 chain 挂。
- 典型用法:一条复杂但高质量的 chain,挂一条简单 chain 兜底,极端情况下保证至少有输出。
with_fallbacks返回的对象同样是 Runnable,可以继续 pipe。
bind 是另一个通用能力:预置调用参数并返回新 Runnable,之后这条链的每次调用都自动带上这些参数,bind_tools(见 Function Calling)就基于它:
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
from langchain_core.output_parsers import StrOutputParser # 提取纯文本
load_dotenv()
model = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
)
# 预置 stop:这条链的输出一到句号就截断
short_chain = model.bind(stop=["。"]).pipe(StrOutputParser())
short_chain.invoke("写一段自我介绍")
# 你好
Callbacks 与 Tracing:观测调用链
没有它会怎样——想知道哪步慢、哪步输入不对,只能在每层手插 print,发版还得记得删;线上出了问题两眼一抹黑。
有了它——回调挂在链上,每步的输入、输出、耗时自动上报,业务代码零改动。
每个 Runnable 的调用过程都会经过回调系统(callbacks),这是 LangChain 记录调用链路的基础设施,调试、评估、观测都建立在它上面。日常按代价从低到高用三档。
第一档,全局调试日志。打印每个组件的输入输出,本地排查最快的手段:
from langchain_core.globals import set_debug # 开全局调试日志
set_debug(True) # 日志量很大,调试完移除
第二档,LangSmith 追踪。环境变量开启(见配置),每次调用的输入、输出、耗时自动上报,chain 与 agent 都覆盖。排查 agent 的多轮工具调用,比翻命令行日志高效。
第三档,自定义回调处理器。invoke / stream 的 config 参数传 callbacks,挂自己的 BaseCallbackHandler,在 on_llm_start、on_chain_end 等钩子里接日志、指标或告警:
import os # 读取环境变量
from dotenv import load_dotenv # 从 .env 读环境变量
from langchain_core.callbacks import BaseCallbackHandler # 回调基类
from langchain_core.output_parsers import StrOutputParser # 提取纯文本
from langchain_core.prompts import ChatPromptTemplate # 带角色的消息模板
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
load_dotenv()
model = ChatOpenAI(
base_url=os.environ["GLM_BASE_URL"],
api_key=os.environ["GLM_API_KEY"],
model=os.environ["GLM_MODEL_ID"],
)
class MyHandler(BaseCallbackHandler):
def on_llm_start(self, serialized, prompts, **kwargs):
print("LLM 开始,收到:", prompts) # 模型调用前的完整输入,排查 prompt 问题用
def on_llm_end(self, response, **kwargs):
print("LLM 结束,生成", len(response.generations), "条回复") # 拿用量、算指标在这里接
my_handler = MyHandler()
chain = ChatPromptTemplate.from_messages([
{"role": "human", "content": "{question}"},
]).pipe(model).pipe(StrOutputParser())
result = chain.invoke(
{"question": "用一句话解释什么是递归"},
config={"callbacks": [my_handler]},
)
# LLM 开始,收到: [HumanMessage(content='用一句话解释什么是递归', ...)]
# LLM 结束,生成 1 条回复
print(result)
上一节:Models 与 Messages · 下一节:Prompt 模板