【LangChain】langchain_core.runnables.RunnableConfig() 类：控制 Runnable 执行行为的配置对象

于 2025-05-14 18:26:43 发布
阅读量670 收藏 7
点赞数 20
分类专栏： LangChain 文章标签： langchain RunnableConfig 配置 Runnable
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/u013172930/article/details/147960435
版权

在 LangChain 中，RunnableConfig 是一个核心配置对象，用于控制和自定义 LangChain 中 Runnable 对象的执行行为。Runnable 是 LangChain 的基础构建块，涵盖了链（Chains）、代理（Agents）、工具（Tools）等组件。RunnableConfig 允许开发者在运行时动态传递配置参数，例如回调（Callbacks）、最大迭代次数、超时时间、元数据等，以实现更灵活和可控的执行流程。

以下是对 RunnableConfig 的详细介绍，涵盖其定义、作用、主要字段、实现方式、应用场景、代码示例、优化建议以及与生态系统的结合。

1. 什么是 RunnableConfig？

RunnableConfig 是一个 Python 字典或 Pydantic 模型，用于在调用 Runnable 对象（如链、代理、工具）时传递运行时配置。它提供了以下功能：

  • 动态配置：在运行时指定回调、超时、元数据等，而无需修改组件定义。
  • 统一接口：为所有 Runnable 提供一致的配置方式。
  • 灵活控制：支持调试、监控、错误处理和上下文传递。

RunnableConfig 的典型用途包括：

  • 指定回调以记录执行过程。
  • 设置最大迭代次数或超时以控制代理行为。
  • 传递元数据以跟踪请求或上下文。
  • 配置线程或异步执行选项。

2. RunnableConfig 的主要字段

RunnableConfig 是一个灵活的配置对象，常用字段包括以下内容（基于 LangChain 文档和实现）：

字段类型描述示例值
callbacksList[BaseCallbackHandler] 或 CallbackManager指定执行过程中使用的回调处理器，用于记录事件（如开始、结束、错误）。[StdOutCallbackHandler()]
max_iterationsint限制代理或循环的最大迭代次数，防止无限循环。5
max_execution_timefloat设置执行的最大时间（秒），超时后抛出错误。30.0
metadataDict[str, Any]传递附加元数据，用于跟踪或上下文管理。{"request_id": "123"}
tagsList[str]为运行添加标签，用于过滤或分类。["experiment", "test"]
run_namestr指定运行的名称，便于调试和日志记录。"MyChainRun"
configurableDict[str, Any]动态配置字段，用于特定组件的自定义参数。{"temperature": 0.7}
recursion_limitint限制递归调用深度，防止栈溢出。10
timeoutfloat请求超时时间（秒），常用于网络调用。10.0

注意：

  • 并非所有字段都适用于每个 Runnable，具体支持取决于组件实现。
  • RunnableConfig 通常作为可选参数传递给 invoke、ainvoke、batch 等方法。

3. RunnableConfig 的工作原理

RunnableConfig 的工作流程如下：

  1. 配置传递：
    • 开发者在调用 Runnable 的方法（如 invoke）时传递 RunnableConfig。
    • 示例：chain.invoke(input, config={"callbacks": [handler]})。
  2. 组件解析：
    • Runnable 对象（链、代理等）解析 RunnableConfig，提取所需字段。
    • 例如，代理读取 max_iterations，回调管理器读取 callbacks。
  3. 执行控制：
    • 配置参数控制执行行为，如触发回调、检查超时或限制迭代。
  4. 事件分发：
    • 回调处理器接收执行过程中的事件（如 on_chain_start、on_tool_end）。
  5. 结果返回：
    • 配置不影响输出内容，但可能影响执行路径（如提前终止）。

RunnableConfig 的核心优势是其统一性和模块化，允许开发者在不修改核心逻辑的情况下动态调整行为。

4. LangChain 中使用 RunnableConfig 的方式

以下是 RunnableConfig 的主要使用方式，结合代码示例说明：

(1) 配置回调（Callbacks）

  • 功能：通过 callbacks 字段指定回调处理器，记录执行过程。
  • 适用场景：调试、日志记录、性能监控。
  • 示例：
    from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.callbacks import StdOutCallbackHandler
from langchain_core.runnables import RunnableConfig

# 初始化模型和链
llm = ChatOpenAI(api_key="your-openai-key")
prompt = ChatPromptTemplate.from_template("解释{topic}")
chain = prompt | llm

# 配置回调
config = RunnableConfig(callbacks=[StdOutCallbackHandler()])

# 调用链
result = chain.invoke({"topic": "量子计算"}, config=config)
print(result.content)
  • 输出：
    [chain/start] [1:chain:RunnableSequence] Entering Chain run with input: {'topic': '量子计算'}
[llm/start] [1:chain:RunnableSequence > 2:llm:ChatOpenAI] Entering LLM run with input: ...
[llm/end] [1:chain:RunnableSequence > 2:llm:ChatOpenAI] Exiting LLM run with output: ...
[chain/end] [1:chain:RunnableSequence] Exiting Chain run with output: ...
量子计算是一种基于量子力学原理的计算范式...
  • 说明：
    • StdOutCallbackHandler 打印执行日志，展示链和模型的开始/结束事件。
    • 可替换为自定义回调或 LangSmith 集成。

(2) 控制代理迭代

  • 功能：通过 max_iterations 限制代理的推理循环。
  • 适用场景：防止代理陷入无限循环，优化性能。
  • 示例：
    from langchain_openai import ChatOpenAI
from langchain.agents import initialize_agent, AgentType
from langchain_core.tools import Tool
from langchain_core.runnables import RunnableConfig

# 定义工具
def calculator(expression: str) -> str:
    return str(eval(expression))

tools = [Tool(name="Calculator", func=calculator, description="执行数学计算")]

# 初始化代理
llm = ChatOpenAI(api_key="your-openai-key")
agent = initialize_agent(tools, llm, agent_type=AgentType.ZERO_SHOT_REACT_DESCRIPTION, verbose=True)

# 配置最大迭代次数
config = RunnableConfig(max_iterations=3)

# 调用代理
result = agent.invoke("计算 2 + 2", config=config)
print(result["output"])
  • 输出：
    [AgentExecutor] 正在执行...
[Action] 使用 Calculator 工具计算 2 + 2
[Tool Output] 4
[Final Answer] 4
  • 说明：
    • max_iterations=3 限制代理最多执行 3 次工具调用。
    • 如果任务未完成，代理会提前终止并返回部分结果。

(3) 设置超时

  • 功能：通过 max_execution_time 或 timeout 限制执行时间。
  • 适用场景：避免长时间运行，优化实时应用。
  • 示例：
    from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnableConfig

llm = ChatOpenAI(api_key="your-openai-key")
prompt = ChatPromptTemplate.from_template("生成一篇关于{topic}的500字文章")
chain = prompt | llm

# 配置超时（10秒）
config = RunnableConfig(max_execution_time=10.0)

try:
    result = chain.invoke({"topic": "量子计算"}, config=config)
    print(result.content)
except TimeoutError:
    print("执行超时")
  • 说明：
    • max_execution_time=10.0 限制链执行不超过 10 秒。
    • 超时抛出 TimeoutError，需捕获处理。

(4) 传递元数据

  • 功能：通过 metadata 字段传递上下文或跟踪信息。
  • 适用场景：请求跟踪、用户标识、实验管理。
  • 示例：
    from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnableConfig
from langchain_core.callbacks import BaseCallbackHandler

# 自定义回调记录元数据
class MetadataCallback(BaseCallbackHandler):
    def on_chain_start(self, serialized, inputs, **kwargs):
        print(f"元数据：{kwargs.get('metadata', {})}")

llm = ChatOpenAI(api_key="your-openai-key")
prompt = ChatPromptTemplate.from_template("解释{topic}")
chain = prompt | llm

# 配置元数据
config = RunnableConfig(
    callbacks=[MetadataCallback()],
    metadata={"request_id": "123", "user_id": "user001"}
)

result = chain.invoke({"topic": "量子计算"}, config=config)
print(result.content)
  • 输出：
    元数据：{'request_id': '123', 'user_id': 'user001'}
量子计算是一种基于量子力学原理的计算范式...
  • 说明：
    • metadata 字段可用于日志记录或与外部系统集成。
    • 回调处理器可访问元数据，增强可追溯性。

(5) 使用 LangSmith 集成

  • 功能：通过 callbacks 集成 LangSmith，记录执行轨迹。
  • 适用场景：性能分析、调试复杂工作流。
  • 示例：
    from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnableConfig
from langsmith import Client

llm = ChatOpenAI(api_key="your-openai-key")
prompt = ChatPromptTemplate.from_template("解释{topic}")
chain = prompt | llm

# 配置 LangSmith
config = RunnableConfig(callbacks=[Client(api_key="your-langsmith-key")])

result = chain.invoke({"topic": "量子计算"}, config=config)
print(result.content)
  • 说明：
    • LangSmith 记录执行轨迹，包括输入、输出、耗时等。
    • 需要 LangSmith 账户和 API 密钥。

5. RunnableConfig 的应用场景

RunnableConfig 在以下场景中广泛应用：

  1. 调试与日志记录：
    • 使用 callbacks 记录链、代理或工具的执行过程。
    • 示例：打印每一步的输入输出。
  2. 性能控制：
    • 使用 max_iterations 或 max_execution_time 限制执行。
    • 示例：防止代理无限循环。
  3. 请求跟踪：
    • 使用 metadata 传递请求 ID 或用户上下文。
    • 示例：跟踪 API 请求来源。
  4. 监控与分析：
    • 结合 LangSmith 分析性能和错误。
    • 示例：优化链的响应时间。
  5. 动态配置：
    • 使用 configurable 动态调整模型参数。
    • 示例：临时更改温度或最大 token 数。
  6. 错误处理：
    • 使用超时或回调捕获异常。
    • 示例：处理网络请求超时。

6. RunnableConfig 的优化建议

(1) 提高调试效率

  • 选择合适的回调：
    • 使用 StdOutCallbackHandler 进行快速调试。
    • 使用 LangSmith 进行生产环境监控。
  • 自定义回调：
    • 实现特定事件处理逻辑。
    class CustomCallback(BaseCallbackHandler):
    def on_chain_error(self, error, **kwargs):
        print(f"链错误：{error}")

(2) 提高性能

  • 限制迭代和时间：
    • 设置 max_iterations 和 max_execution_time。
    config = RunnableConfig(max_iterations=5, max_execution_time=30.0)
  • 缓存结果：
    • 结合 LangChain 的缓存机制。
    from langchain.globals import set_llm_cache
from langchain.cache import SQLiteCache

set_llm_cache(SQLiteCache(database_path="cache.db"))
  • 异步执行：
    • 使用 ainvoke 或 abatch 支持高并发。
    result = await chain.ainvoke(input, config=config)

(3) 错误处理

  • 超时处理：
    • 捕获超时异常并提供回退。
    try:
    result = chain.invoke(input, config={"max_execution_time": 10.0})
except TimeoutError:
    result = fallback_chain.invoke(input)
  • 回调错误：
    • 在回调中记录异常。
    class ErrorCallback(BaseCallbackHandler):
    def on_chain_error(self, error, **kwargs):
        print(f"错误：{error}")

(4) 监控与分析

  • LangSmith 集成：
    • 记录执行轨迹，分析性能瓶颈。
  • 元数据跟踪：
    • 使用 metadata 关联请求和用户。
    config = RunnableConfig(metadata={"session_id": "abc123"})

(5) 配置管理

  • 默认配置：
    • 定义全局默认配置，减少重复代码。
    default_config = RunnableConfig(
    callbacks=[StdOutCallbackHandler()],
    max_iterations=5
)
result = chain.invoke(input, config=default_config)
  • 动态配置：
    • 使用 configurable 字段支持运行时参数调整。
    config = RunnableConfig(configurable={"temperature": 0.9})

7. 注意事项

  • 字段兼容性：
    • 并非所有 Runnable 都支持所有字段（如 max_iterations 主要用于代理）。
    • 检查组件文档确认支持的配置。
  • 回调开销：
    • 过多或复杂的回调可能影响性能。
    • 使用轻量回调（如 StdOutCallbackHandler）进行调试。
  • 超时设置：
    • 超时时间需根据任务复杂度设置，过短可能导致提前终止。
    • 结合回退机制处理超时。
  • 元数据隐私：
    • 避免在 metadata 中包含敏感信息（如 API 密钥）。
    • 使用加密或匿名化处理敏感数据。
  • 异步支持：
    • 异步调用（ainvoke）需要确保回调和工具支持异步。
    class AsyncCallback(BaseCallbackHandler):
    async def on_chain_start(self, serialized, inputs, **kwargs):
        print(f"异步链开始：{inputs}")

8. 与其他模块的结合

  • 链（Chains）：
    • 配置回调和超时控制链执行。
    chain.invoke(input, config={"callbacks": [StdOutCallbackHandler()]})
  • 代理（Agents）：
    • 使用 max_iterations 和 metadata 控制代理行为。
    agent.invoke(input, config={"max_iterations": 5, "metadata": {"user_id": "001"}})
  • 工具（Tools）：
    • 工具调用可通过回调监控。
    tool.invoke(input, config={"callbacks": [ToolCallback()]})
  • 回调（Callbacks）：
    • RunnableConfig 的核心字段，驱动事件记录。
  • 缓存（Cache）：
    • 结合缓存优化性能。
    set_llm_cache(SQLiteCache(database_path="cache.db"))
  • LangSmith：
    • 通过 callbacks 集成 LangSmith，分析执行轨迹。

9. 综合示例：多功能代理

以下是一个结合多种 RunnableConfig 功能的代理示例：

from langchain_openai import ChatOpenAI
from langchain.agents import initialize_agent, AgentType
from langchain_core.tools import Tool
from langchain_community.tools import DuckDuckGoSearchRun
from langchain_core.callbacks import StdOutCallbackHandler
from langchain_core.runnables import RunnableConfig

# 定义工具
def calculator(expression: str) -> str:
    return str(eval(expression))

calc_tool = Tool(
    name="Calculator",
    func=calculator,
    description="执行数学计算，输入为数学表达（如 '2 + 2'）。"
)

search_tool = DuckDuckGoSearchRun()

# 初始化代理
llm = ChatOpenAI(api_key="your-openai-key")
agent = initialize_agent(
    tools=[calc_tool, search_tool],
    llm=llm,
    agent_type=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True
)

# 配置 RunnableConfig
config = RunnableConfig(
    callbacks=[StdOutCallbackHandler()],
    max_iterations=3,
    max_execution_time=30.0,
    metadata={"request_id": "req_001", "user_id": "user_001"},
    tags=["experiment"],
    run_name="MathAndSearchAgent"
)

# 执行任务
result = agent.invoke("计算 5 + 3 并搜索量子计算的最新进展", config=config)
print(result["output"])

输出：

[chain/start] [1:agent:MathAndSearchAgent] Entering Agent run with input: ...
[tool/start] [1:agent:MathAndSearchAgent > 2:tool:Calculator] Entering Tool run with input: 5 + 3
[tool/end] [1:agent:MathAndSearchAgent > 2:tool:Calculator] Exiting Tool run with output: 8
[tool/start] [1:agent:MathAndSearchAgent > 3:tool:DuckDuckGoSearch] Entering Tool run with input: 量子计算的最新进展
[tool/end] [1:agent:MathAndSearchAgent > 3:tool:DuckDuckGoSearch] Exiting Tool run with output: ...
[chain/end] [1:agent:MathAndSearchAgent] Exiting Agent run with output: ...
计算结果为 8，量子计算的最新进展包括...

10. 学习资源

11. 总结

  • 定义：RunnableConfig 是控制 Runnable 执行行为的配置对象，支持回调、迭代限制、超时、元数据等。
  • 主要字段：
    • callbacks：记录事件。
    • max_iterations：限制循环。
    • max_execution_time：设置超时。
    • metadata：传递上下文。
    • tags、run_name：分类和命名。
  • 工作原理：传递配置 → 解析字段 → 控制执行 → 分发事件 → 返回结果。
  • 应用场景：调试、性能控制、请求跟踪、监控、动态配置、错误处理。
  • 优化点：调试效率、性能、错误处理、监控、配置管理。
  • 注意事项：字段兼容性、回调开销、超时设置、元数据隐私、异步支持。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

彬彬侠

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值