2.5 Runnable 配置透传与上下文管理（with_config、configurable 动态配置，1.2.7 版本特性）

2.5 Runnable 配置透传与上下文管理（with_config、configurable 动态配置，1.2.7 版本特性）

2.5.1 引言

LangChain 1.2.7 版本对 Runnable 协议的配置体系进行了核心强化，正式确立了 with_config 配置绑定与 configurable 动态注入的双核心机制，构建起「静态绑定-动态适配-全链路透传」的完整上下文管理能力。这两项特性精准解决了传统配置方案中「复用性差、动态调整繁琐、复杂链路配置割裂」的痛点，尤其适用于生产环境中的多环境部署、多用户隔离、全链路监控等核心场景。

与旧版本相比，1.2.7 版本的配置体系实现了三大突破：一是配置合并逻辑的标准化，明确了多层配置的优先级规则；二是全链路透传的自动化，无需手动在组件间传递配置；三是动态配置的灵活化，支持在实例化、执行阶段按需注入参数。本节将从核心概念、API 细节、分层实战到最佳实践，系统拆解这两项特性的使用逻辑与生产级应用方案。

2.5.2 核心概念与 API 规范（1.2.7 版本）

<2.5.2.1> with_config：配置静态绑定与复用

with_config 是 Runnable 实例的核心方法，用于将 RunnableConfig 配置与当前实例进行静态绑定，返回一个全新的 Runnable 实例（原实例保持不变）。绑定后的配置会对该实例的所有执行方法（invoke、batch、stream 等）生效，且支持多层叠加与灵活覆盖。

官方 API 定义（LangChain 1.2.7 源码）

def with_config(
    self,
    config: RunnableConfig,
    **kwargs: Any
) -> Runnable[Input, Output]:
    """
    为 Runnable 实例绑定配置，返回新实例（原实例不可变）
    :param config: 基础配置字典，支持 tags、metadata、callbacks、configurable 等键
    :param kwargs: 额外配置参数，会覆盖 config 中同名键（优先级：kwargs > config）
    :return: 绑定配置后的新 Runnable 实例
    """

核心特性（1.2.7 版本强化点）

1. 不可变性设计 ：每次调用 with_config 均生成新实例，原实例配置不受影响，支持多配置并行复用；

2. 智能配置合并：tags 会自动合并为列表（去重），metadata 会递归合并，callbacks 会追加而非覆盖；

3. 全方法兼容：绑定的配置对 invoke/ainvoke、batch/abatch、stream/astream 六大核心方法完全生效；

4. 链式叠加支持 ：可连续调用 with_config，配置按调用顺序逐层合并（后续配置覆盖前序冲突项）。

<2.5.2.2> configurable：动态配置注入与多场景适配

configurable 是 langchain_core.runnables 模块提供的装饰器，用于为自定义 Runnable 类或函数标记「动态配置字段」。通过该装饰器，字段可在实例化、执行阶段动态注入，无需硬编码，且支持与 with_config 协同实现「基础配置+场景配置」的组合模式。

官方 API 定义（LangChain 1.2.7 源码简化）

def configurable(
    *configurable_fields: str,
    **default_values: Any
) -> Callable:
    """
    为 Runnable 类/函数添加动态配置字段
    :param configurable_fields: 动态字段名列表（需与类初始化参数或函数参数一致）
    :param default_values: 字段默认值（可选），格式为 {字段名: 默认值}
    :return: 装饰后的 Runnable 类/函数
    """

核心特性（1.2.7 版本核心优势）

1. 动态注入能力 ：标记的字段可在实例化（__init__）或执行（通过 with_config）时动态传递；

2. 全链路透传 ：动态字段会被纳入 RunnableConfig 的 configurable 键中，自动透传到链路所有组件；

3. 默认值兜底：支持为动态字段设置默认值，未传递时使用默认值，平衡灵活性与稳定性；

4. 类型兼容性 ：支持与 with_config 绑定的静态配置合并，动态字段优先级高于默认值。

2.5.3 分层实战案例（独立可运行）

以下案例基于 LangChain 1.2.7 版本，延续前文环境准备（已初始化 llm = ChatOpenAI(model="gpt-3.5-turbo")），从基础到生产级逐步演示特性用法。

<2.5.3.1> 基础案例：with_config 静态配置绑定与复用

场景：为 LLM 实例绑定生产环境通用配置（日志回调、环境标签、服务元数据），复用给多个业务场景。

from langchain_core.callbacks import ConsoleCallbackHandler
from langchain_core.runnables import RunnableConfig

# 1. 定义生产环境基础配置
prod_base_config: RunnableConfig = {
    "tags": ["prod-env", "llm-service"],  # 环境标签（用于日志筛选）
    "metadata": {
        "service_name": "user-query-processing",
        "version": "v1.0.0",
        "cluster": "prod-1"
    },  # 服务元数据（用于链路追踪）
    "callbacks": [ConsoleCallbackHandler()]  # 日志回调（打印执行流程）
}

# 2. 绑定基础配置，生成新实例（原 llm 实例不变）
llm_prod = llm.with_config(prod_base_config)

# 3. 叠加业务场景配置（链式调用 with_config）
# 场景1：用户问答业务（新增业务标签）
llm_qa = llm_prod.with_config({"tags": ["business:qa"], "metadata": {"timeout": 30}})
# 场景2：内容生成业务（调整模型参数）
llm_generate = llm_prod.with_config({"tags": ["business:generate"], "temperature": 0.8})

# 4. 执行验证（配置自动生效）
print("=== 业务场景1：用户问答 ===")
result_qa = llm_qa.invoke("解释 LangChain with_config 的核心价值")
print("输出片段：", result_qa.content[:80] + "...")

print("\n=== 业务场景2：内容生成 ===")
result_generate = llm_generate.invoke("生成3条AI工具推广短文案")
print("输出片段：", result_generate.content[:80] + "...")

案例说明：

• 基础配置 prod_base_config 绑定后，所有衍生实例均继承日志回调与服务元数据；

• 链式调用 with_config 时，tags 自动合并（prod-env + business:qa），metadata 递归合并，temperature 覆盖基础配置；

• 不同业务场景通过独立实例隔离配置，避免相互影响，同时复用基础配置减少冗余。

<2.5.3.2> 进阶案例：configurable 动态字段注入

场景：自定义工具类，动态注入「超时时间」「重试次数」「接口地址」，适配不同第三方服务调用场景。

from langchain_core.runnables import Runnable, configurable
from langchain_core.exceptions import LangChainException
import time
from typing import Optional

# 1. 用 configurable 装饰器标记动态字段
@configurable(
    "timeout",  # 动态字段1：超时时间（秒）
    "retry_count",  # 动态字段2：重试次数
    "api_url",  # 动态字段3：接口地址
    timeout=5,  # 默认值：超时5秒
    retry_count=2,  # 默认值：重试2次
    api_url="https://api.default.com"  # 默认值：默认接口地址
)
class ThirdPartyAPIRunnable(Runnable):
    def invoke(
        self,
        input: dict,
        config: Optional[RunnableConfig] = None,
        **kwargs: Any
    ) -> dict:
        """模拟第三方API调用，支持动态配置超时、重试、接口地址"""
        retry = 0
        while retry <= self.retry_count:
            try:
                print(f"[API调用] 地址：{self.api_url}，输入：{input}，超时：{self.timeout}s")
                # 模拟API调用耗时（1秒）
                time.sleep(1)
                # 模拟失败场景（输入含"失败"且未到最大重试次数）
                if "失败" in str(input) and retry < self.retry_count:
                    raise ConnectionError("模拟接口连接失败")
                return {"status": "success", "data": f"响应：{input}"}
            except Exception as e:
                retry += 1
                if retry > self.retry_count:
                    raise LangChainException(
                        f"API调用失败（重试{self.retry_count}次）：{str(e)}"
                    ) from e
                print(f"[重试] 第{retry}次重试...")

# 2. 实例化：注入动态字段（覆盖默认值）
api_runnable = ThirdPartyAPIRunnable(
    timeout=10,  # 超时10秒
    retry_count=3,  # 重试3次
    api_url="https://api.business.com/user"  # 业务接口地址
)

# 3. 执行时动态调整配置（通过 with_config）
# 临时调整接口地址和超时时间，适配特殊场景
api_runnable_temp = api_runnable.with_config({
    "configurable": {
        "api_url": "https://api.temp.com/urgent",
        "timeout": 15
    }
})

# 4. 测试执行
print("=== 正常调用 ===")
result_normal = api_runnable_temp.invoke({"user_id": "123", "query": "获取用户信息"})
print("执行结果：", result_normal)

print("\n=== 模拟失败重试 ===")
try:
    result_fail = api_runnable_temp.invoke({"user_id": "456", "query": "失败测试"})
    print("执行结果：", result_fail)
except LangChainException as e:
    print("执行结果：", str(e))

案例说明：

• 动态字段无需在 __init__ 中定义，装饰器自动注入为实例属性，简化代码；

• 实例化时注入基础动态配置，执行时通过 with_config 的 configurable 键调整，支持场景化适配；

• 默认值兜底机制避免参数缺失，动态调整无需修改类定义，提升代码复用性与维护性。

<2.5.3.3> 生产级案例：全链路配置透传与多用户隔离

场景：构建「预处理-LLM生成-结果格式化」完整链路，实现多用户配置隔离、全链路监控、动态规则适配。

from langchain_core.runnables import RunnableSequence, RunnableLambda, configurable
from langchain_core.callbacks import BaseCallbackHandler
from typing import Dict, Any
import time

# 1. 自定义全链路监控回调（追踪用户ID、组件执行状态）
class FullLinkMonitorCallback(BaseCallbackHandler):
    def on_chain_start(self, serialized: Dict[str, Any], inputs: Dict[str, Any], **kwargs):
        config = kwargs.get("config", {})
        user_id = config.get("metadata", {}).get("user_id", "unknown")
        component = serialized.get("name", serialized.get("id", "unknown"))
        self.start_time = time.time()
        print(f"[监控] 用户{user_id} - 组件[{component}] 开始执行")

    def on_chain_end(self, outputs: Dict[str, Any], **kwargs):
        config = kwargs.get("config", {})
        user_id = config.get("metadata", {}).get("user_id", "unknown")
        duration = round(time.time() - self.start_time, 2)
        print(f"[监控] 用户{user_id} - 执行完成（耗时{duration}s）")

# 2. 动态预处理函数（通过 configurable 注入预处理规则）
@configurable("preprocess_rule", preprocess_rule="default")
def preprocess(input_text: str) -> str:
    """根据动态规则预处理输入文本"""
    if preprocess_rule == "user_vip":
        # VIP用户：保留原始文本+添加优先级标记
        return f"[VIP优先级] {input_text}"
    elif preprocess_rule == "user_common":
        # 普通用户：去除多余空格+小写转换
        return input_text.strip().lower()
    else:
        # 默认规则：仅去除空格
        return input_text.strip()

# 3. 结果格式化函数（添加用户标识与时间戳）
def format_result(result: str, config: RunnableConfig) -> Dict[str, Any]:
    """从配置中提取用户ID，注入到结果中"""
    user_id = config.get("metadata", {}).get("user_id", "unknown")
    return {
        "user_id": user_id,
        "result": result.content,
        "timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
        "rule": config.get("configurable", {}).get("preprocess_rule", "default")
    }

# 4. 构建完整链路（预处理 → LLM生成 → 结果格式化）
chain = RunnableSequence(
    # 预处理：动态规则注入
    RunnableLambda(preprocess),
    # LLM生成：复用之前的 llm_prod 实例（带生产环境配置）
    llm_prod,
    # 结果格式化：获取配置中的用户信息
    RunnableLambda(lambda result, config: format_result(result, config))
)

# 5. 为不同用户绑定专属配置（实现隔离）
# VIP用户配置：VIP预处理规则+专属标签+监控回调
user_vip_config = {
    "tags": ["prod-env", "user:vip", "business:consult"],
    "metadata": {"user_id": "vip_001", "level": "VIP"},
    "callbacks": [FullLinkMonitorCallback()],
    "configurable": {"preprocess_rule": "user_vip"}
}
chain_vip = chain.with_config(user_vip_config)

# 普通用户配置：普通预处理规则+专属标签+监控回调
user_common_config = {
    "tags": ["prod-env", "user:common", "business:consult"],
    "metadata": {"user_id": "common_002", "level": "COMMON"},
    "callbacks": [FullLinkMonitorCallback()],
    "configurable": {"preprocess_rule": "user_common"}
}
chain_common = chain.with_config(user_common_config)

# 6. 执行链路验证
print("=== VIP用户执行 ===")
result_vip = chain_vip.invoke(" 请详细介绍LangChain 1.2.7的配置透传特性 ")
print("输出结果：", result_vip)

print("\n=== 普通用户执行 ===")
result_common = chain_common.invoke(" 请简单说明configurable装饰器的用法 ")
print("输出结果：", result_common)

案例说明：

• 配置全链路自动透传：with_config 绑定的用户配置（tags、metadata、动态规则）自动传递到链路所有组件，无需手动传递；

• 多用户隔离：不同用户通过独立链路实例绑定专属配置，预处理规则、监控标签、用户标识完全隔离；

• 监控无侵入：通过回调函数从配置中提取用户信息与组件状态，实现全链路无侵入式监控；

• 动态适配：无需修改链路逻辑，仅通过配置调整预处理规则，适配不同用户需求。

2.5.4 1.2.7 版本特性关键注意事项

1. 版本兼容性约束：

   • with_config 在 1.2.0 以上版本存在，但 1.2.7 优化了配置合并逻辑（尤其是 tags 和 metadata 的合并），低版本可能出现覆盖而非合并的问题；

   • configurable 是 1.2.x 系列新增特性，1.2.0 以下版本完全不支持，需确保环境依赖 langchain-core>=1.2.7。

2. 配置优先级规则（核心）：

执行时传入的 config 参数 > 最近一次 with_config 绑定的配置 > 前序 with_config 绑定的配置 > configurable 装饰器默认值 > 组件初始化参数。

• 示例：执行 llm.with_config({"temperature": 0.5}).invoke("prompt", config={"temperature": 0.8})，最终 temperature 为 0.8。

1. 动态字段使用限制：

   • 字段名不可与 Runnable 内置参数（如 config、kwargs、input）冲突；

   • 字段值建议使用可序列化类型（str、int、bool、dict），复杂对象（如自定义类实例）可能导致配置透传失败；

   • 装饰器标记的字段必须与类/函数的参数名一致，否则会抛出 ValueError。

2. 全链路透传范围：

   • 仅对当前 Runnable 及组合的子组件（如 RunnableSequence、RunnableParallel 中的组件）生效；

   • 独立创建的 Runnable 实例需单独绑定配置，或通过全局配置（RunnableConfig 的 global 键）实现跨实例透传。

3. 性能优化建议：

   • 避免过度嵌套 with_config（建议不超过 3 层），多层合并会增加轻微性能开销；

   • 复杂回调逻辑（如数据库写入、远程日志上报）建议使用异步回调（AsyncCallbackHandler），避免阻塞执行流程；

   • 大批量执行（batch/abatch）时，动态配置字段建议使用简单类型，减少序列化开销。

2.5.5 生产环境最佳实践

1. 配置分层管理模式：

   • 基础层：绑定环境（dev/test/prod）、监控回调、通用元数据，通过 with_config 生成基础实例复用；

   • 业务层：基于基础实例，绑定业务标签、场景参数（如 temperature），生成业务专属实例；

   • 场景层：通过 with_config 动态调整 configurable 字段，适配单次执行的特殊需求（如临时调整超时时间）。

2. 多环境隔离方案：

为不同环境创建独立的配置绑定脚本，例如：

• 开发环境：宽松超时、详细日志回调、测试标签；

• 生产环境：严格超时、异步监控回调、生产标签+链路追踪元数据；

部署时仅需切换绑定的配置实例，无需修改核心业务代码。

1. 复杂链路配置技巧：

   • 全链路监控：通过 metadata 注入 request_id，结合回调函数实现跨组件链路追踪；

   • 动态参数管控：敏感参数（如 API 密钥）通过 configurable 动态注入，避免硬编码到代码或配置文件；

   • 故障隔离：为关键组件绑定独立回调，通过 tags 筛选日志，快速定位链路中的故障组件。

2. 自定义 Runnable 开发规范：

   • 所有可配置参数均通过 configurable 标记，避免硬编码；

   • 执行逻辑中优先从 config 提取参数（config.get("configurable", {}).get("field")），其次使用实例属性；

   • 回调函数中通过 config 传递上下文信息（如用户ID、请求ID），避免依赖全局变量。