1586 字

8 分钟

Runnable绑定、配置与监听

2026-04-27

LangChain

/

Runnable

/

LCEL

/

Config

/

LangSmith

Runnable绑定、配置与监听#

本篇承接 02_LangChain底层原理中的 Runnable 协议与 LCEL 管道。它不再讨论”链能不能跑”，而是集中回答另外三个工程化问题：参数如何预绑定、运行时配置如何传递、生命周期如何监听。

1 Runnable配置层概览#

1.1 Prompt变量、Runnable kwargs 与 RunnableConfig#

LangChain 里最容易混淆的，是这三层东西看起来都像”参数”，但作用完全不同：

层次	作用对象	影响什么	典型例子
Prompt 变量	Prompt 模板	模型看到的内容	`{question}`、`{context}`
Runnable kwargs	底层 Runnable	模型 / 工具怎么执行	`temperature=0`、`stop=["\n\n"]`
RunnableConfig	运行时配置层	tracing、回调、并发、上下文元信息	`tags`、`metadata`、`session_id`

如果不先把这三层分清，后面看 bind()、with_config()、listeners 就会一直混。

1.2 配置层的工程价值#

原型代码通常只关心：

1
chain = prompt | model | parser
2
result = chain.invoke({"topic": "RAG"})

但生产代码很快就会关心：

给模型统一绑定 stop、temperature
给链路打 tags 和 metadata
控制 batch() 的 max_concurrency
在运行前后挂监听器
给不同会话传不同 configurable 参数

核心理解
LCEL 不只是数据流的组合语法，它还有一层完整的运行时配置能力。bind()、with_config() 和 listeners 就是这层能力的核心入口。

2 `bind()`#

2.1 作用#

bind() 的作用是：给底层 Runnable 提前绑定调用参数，并返回一条新的 Runnable。

最常见的绑定对象是模型：

temperature
stop
tools
tool_choice

1
# pip install langchain langchain-openai
2

3
from langchain_openai import ChatOpenAI
4
from langchain_core.output_parsers import StrOutputParser
5

6
model = ChatOpenAI(model="gpt-4o-mini")
7

8
chain = (
9
    model.bind(stop=["\n\n"])
10
    | StrOutputParser()
11
)
12

13
result = chain.invoke("请连续输出 1 到 10，每个数字后面加一句解释。")
14
print(result)

2.2 典型场景#

bind() 最适合做”组件级默认执行策略”：

1
qa_model = ChatOpenAI(model="gpt-4o-mini").bind(temperature=0)
2
creative_model = ChatOpenAI(model="gpt-4o-mini").bind(temperature=0.9)

这里的价值在于：

不是每次调用都重新传参数
不是把参数散落在多个调用点
而是把”这个 Runnable 以后就按这种方式执行”固化下来

2.3 与 Prompt 变量的区分#

1
from langchain_core.prompts import ChatPromptTemplate
2
from langchain_core.output_parsers import StrOutputParser
3
from langchain_openai import ChatOpenAI
4

5
prompt = ChatPromptTemplate.from_template("请解释 {concept}")
6
model = ChatOpenAI(model="gpt-4o-mini").bind(temperature=0)
7

8
chain = prompt | model | StrOutputParser()

这里：

{concept} 是业务输入，进入 Prompt
temperature=0 是执行参数，进入 Runnable kwargs

经验法则
需要让模型”读到”的内容，放进 Prompt；需要让底层 Runnable”按某种方式执行”的参数，优先考虑 bind()。

3 `with_config()` 与 RunnableConfig#

3.1 常用字段#

with_config() 绑定的是 RunnableConfig，而不是模型 kwargs。常用字段包括：

run_name
tags
metadata
callbacks
max_concurrency
configurable

1
# pip install langchain langchain-openai
2

3
from langchain_openai import ChatOpenAI
4
from langchain_core.prompts import ChatPromptTemplate
5
from langchain_core.output_parsers import StrOutputParser
6

7
chain = (
8
    ChatPromptTemplate.from_template("请解释 {topic}")
9
    | ChatOpenAI(model="gpt-4o-mini")
10
    | StrOutputParser()
11
).with_config(
12
    run_name="explain_topic_chain",
13
    tags=["tutorial", "overview"],
14
    metadata={"module": "langchain_overview"},
15
)
16

17
result = chain.invoke({"topic": "Runnable"})

3.2 组件级默认配置与请求级动态配置#

两种传配置方式都很常见：

方式	更适合什么
`chain.with_config(...)`	提前绑定一组稳定配置，形成可复用组件
`chain.invoke(input, config=...)`	每次调用都可能变化的动态配置

1
base_chain = (
2
    ChatPromptTemplate.from_template("回答问题: {question}")
3
    | ChatOpenAI(model="gpt-4o-mini")
4
    | StrOutputParser()
5
)
6

7
prod_chain = base_chain.with_config(
8
    run_name="qa_prod_chain",
9
    tags=["prod", "qa"],
10
)
11

12
answer = prod_chain.invoke(
13
    {"question": "什么是向量数据库？"},
14
    config={"metadata": {"request_id": "req_123"}},
15
)

这里可以这样理解：

with_config() 负责组件级默认配置
invoke(..., config=...) 负责请求级动态配置

3.3 `configurable`#

configurable 是运行时可配置上下文的命名空间。在 04_Prompt编排与会话历史中，RunnableWithMessageHistory 就依赖：

1
config = {"configurable": {"session_id": "user_001"}}

它既不是 Prompt 变量，也不是模型 kwargs，而是运行时上下文。

易错避坑
session_id 应该放在 configurable 里，而不是写进 Prompt，也不是塞进 bind()。

4 并发与生命周期#

4.1 `batch()` 与 `max_concurrency`#

在 02_LangChain底层原理中我们已经看到 batch() 支持并行。真正进入工程环境后，关键不是”能不能并发”，而是”并发怎么控”。

1
# pip install langchain langchain-openai
2

3
from langchain_core.prompts import ChatPromptTemplate
4
from langchain_core.output_parsers import StrOutputParser
5
from langchain_openai import ChatOpenAI
6

7
chain = (
8
    ChatPromptTemplate.from_template("用一句话解释: {topic}")
9
    | ChatOpenAI(model="gpt-4o-mini")
10
    | StrOutputParser()
11
)
12

13
results = chain.batch(
14
    [
15
        {"topic": "RAG"},
16
        {"topic": "Agent"},
17
        {"topic": "LangGraph"},
18
        {"topic": "Runnable"},
19
    ],
20
    config={"max_concurrency": 2},
21
)

max_concurrency 本质上是吞吐与稳定性的平衡阀门：

太高：容易打爆模型服务或外部工具
太低：批处理优势不明显

4.2 `with_listeners()`#

listeners 更像局部绑定的生命周期钩子，适合给某条 Runnable 就地加上开始、结束、错误监听。

1
# pip install langchain langchain-openai
2

3
from langchain_core.prompts import ChatPromptTemplate
4
from langchain_core.output_parsers import StrOutputParser
5
from langchain_openai import ChatOpenAI
6

7
def on_start(run, config=None):
8
    print(f"[START] {run.name}")
9

10
def on_end(run, config=None):
11
    print(f"[END] {run.name}")
12

13
def on_error(run, config=None):
14
    print(f"[ERROR] {run.name}")
15

16
chain = (
17
    ChatPromptTemplate.from_template("请解释 {topic}")
18
    | ChatOpenAI(model="gpt-4o-mini")
19
    | StrOutputParser()
20
).with_listeners(
21
    on_start=on_start,
22
    on_end=on_end,
23
    on_error=on_error,
24
)
25

26
chain.invoke({"topic": "Message History"})

4.3 callbacks 与 listeners#

可以粗略理解为：

callbacks：更偏平台化、统一化、可传播
listeners：更偏局部化、轻量化、就地绑定

如果你已经在 03_开发环境与LangSmith监控中以 LangSmith 为主做 tracing，callbacks 往往是主力；如果你只是想给某条链加几个前后钩子，listeners 更直接。

5 工程衔接#

5.1 生产链路示例#

1
# pip install langchain langchain-openai
2

3
from langchain_core.prompts import ChatPromptTemplate
4
from langchain_core.output_parsers import StrOutputParser
5
from langchain_openai import ChatOpenAI
6

7
prompt = ChatPromptTemplate.from_messages([
8
    ("system", "你是一位严谨的技术助手。"),
9
    ("human", "{question}"),
10
])
11

12
model = ChatOpenAI(model="gpt-4o-mini").bind(
13
    temperature=0,
14
    stop=["\n\n参考资料之外"],
15
)
16

17
chain = (
18
    prompt
19
    | model
20
    | StrOutputParser()
21
).with_config(
22
    run_name="strict_qa_chain",
23
    tags=["qa", "strict"],
24
    metadata={"owner": "langchain_notes"},
25
)
26

27
answer = chain.invoke(
28
    {"question": "什么是 Runnable？"},
29
    config={"metadata": {"request_id": "req_001"}},
30
)

这条链里：

Prompt 变量控制业务输入
bind() 控制执行参数
with_config() 控制 tracing 与元信息
invoke(..., config=...) 补充请求级上下文

5.2 与会话历史的衔接#

在 04_Prompt编排与会话历史中，RunnableWithMessageHistory 依赖 configurable.session_id。
这说明 History 不是孤立能力，而是 Runnable 配置体系的一部分。

5.3 与 RAG、LangSmith 的衔接#

RAG 链经常需要：

tags=["rag"]
metadata={"retriever": "faiss", "top_k": 4}
批量问答时限制 max_concurrency

而 LangSmith 更像一块观察面板：

LangSmith 负责”看见链路”
RunnableConfig 负责”把链路标清楚”

6 常见错误与排查#

把 tags / metadata 当作业务输入，误以为会自动进 Prompt
把模型 kwargs 写进 with_config()，而不是 bind()
所有链都共用一套巨大的默认配置，导致 tracing 难以区分
只会 invoke()，不会管理 run_name、tags、并发与监听

7 总结#

一句话总结
bind() 解决”这个 Runnable 以后按什么参数执行”，with_config() 解决”这条链路在调度与观测层面带什么元信息”，listeners 解决”运行前后如何就地挂钩子”。这三者合起来，才构成了 Runnable 的工程化配置层。

相关笔记

Runnable绑定、配置与监听

https://fuwari.vercel.app/posts/ai/llm/langchain/notes/01_langchain_overview/05_runnable绑定配置与监听/

作者

OopsYanxi

发布于

2026-04-27

许可协议

CC BY-NC-SA 4.0

Prompt编排与会话历史

LangChain 知识库索引

Runnable绑定、配置与监听#

1 Runnable配置层概览#

1.1 Prompt变量、Runnable kwargs 与 RunnableConfig#

1.2 配置层的工程价值#

2 bind()#

2.1 作用#

2.2 典型场景#

2.3 与 Prompt 变量的区分#

3 with_config() 与 RunnableConfig#

3.1 常用字段#

3.2 组件级默认配置与请求级动态配置#

3.3 configurable#

4 并发与生命周期#

4.1 batch() 与 max_concurrency#

4.2 with_listeners()#

4.3 callbacks 与 listeners#

5 工程衔接#

5.1 生产链路示例#

5.2 与会话历史的衔接#

5.3 与 RAG、LangSmith 的衔接#

6 常见错误与排查#

7 总结#

2 `bind()`#

3 `with_config()` 与 RunnableConfig#

3.3 `configurable`#

4.1 `batch()` 与 `max_concurrency`#

4.2 `with_listeners()`#