跳转到主要内容

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 模板