1. 引言

在使用 LangChain 调用大语言模型时，config 参数是一个容易被忽视但非常重要的配置入口。它允许我们在不修改模型定义的前提下，动态控制单次调用的行为，例如请求超时、重试次数、回调函数、标签等。本文将从基础用法到进阶技巧，系统梳理 config 参数的使用方法。

2. 什么是 config 参数

在 LangChain 中，config 参数通常指调用链（Chain）或模型（Model）时传入的运行时配置对象。它独立于模型本身的参数（如 temperature、max_tokens），用于控制调用过程中的非模型行为。

from langchain_openai import ChatOpenAI

model = ChatOpenAI(model="gpt-4o")

# 调用时传入 config
response = model.invoke("你好", config={"timeout": 30})

3. config 的常见配置项

3.1 超时控制

通过 timeout 设置单次请求的最大等待时间，避免模型响应过慢导致程序阻塞。

response = model.invoke("请介绍一下你自己", config={"timeout": 60})

3.2 重试机制

max_retries 控制请求失败后的重试次数，适用于网络抖动或临时限流场景。

response = model.invoke("生成一段代码", config={"max_retries": 3})

3.3 回调函数

callbacks 允许在调用过程中挂载自定义回调，用于日志记录、监控或流式输出。

from langchain_core.callbacks import StdOutCallbackHandler

handler = StdOutCallbackHandler()
response = model.invoke("讲个笑话", config={"callbacks": [handler]})

3.4 标签与元数据

tags 和 metadata 用于给调用打标签，方便在追踪系统中筛选和定位。

response = model.invoke(
    "总结这段文字",
    config={
        "tags": ["summary", "production"],
        "metadata": {"user_id": "u_12345", "request_id": "req_001"}
    }
)

3.5 常用参数速查表

参数	类型	作用	示例
timeout	float	单次请求超时时间（秒）	config={"timeout": 30}
max_retries	int	请求失败后的最大重试次数	config={"max_retries": 3}
callbacks	list[BaseCallbackHandler]	挂载回调，用于日志、监控、流式输出	config={"callbacks": [handler]}
tags	list[str]	为调用打标签，便于追踪筛选	config={"tags": ["summary"]}
metadata	dict	附加元数据，用于请求追踪与定位	config={"metadata": {"user_id": "u_1"}}
recursion_limit	int	限制链式调用的最大递归深度	config={"recursion_limit": 10}
configurable	dict	运行时动态覆盖链内组件的配置	config={"configurable": {"model": "gpt-4o"}}

说明：recursion_limit 常用于防止 LCEL 链出现无限递归；configurable 则配合 RunnableConfig 实现链内参数的运行时动态切换。

4. 在 Chain 中使用 config

当使用 LCEL（LangChain Expression Language）构建链时，config 参数同样适用，并且可以贯穿整个链的调用过程。

from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_template("请用{language}写一段问候语")
chain = prompt | model

response = chain.invoke(
    {"language": "中文"},
    config={"tags": ["greeting"], "timeout": 30}
)

5. 使用 RunnableConfig 类型

LangChain 提供了 RunnableConfig 类型，用于类型提示和结构化配置，推荐在正式项目中使用。

from langchain_core.runnables import RunnableConfig

config = RunnableConfig(
    timeout=30,
    max_retries=2,
    tags=["api", "v1"],
    metadata={"env": "production"}
)

response = model.invoke("你好", config=config)

6. 流式调用中的 config

在流式输出场景下，config 同样可以传入，用于控制流式请求的行为。

async for chunk in model.astream("写一首诗", config={"timeout": 30}):
    print(chunk.content, end="")

7. 常见问题与注意事项

• config 参数与模型参数（如 temperature）是相互独立的，前者控制调用行为，后者控制生成行为。
• 不同模型提供商对 config 的支持程度可能不同，部分配置项（如 timeout）在异步调用中表现更稳定。
• 在链式调用中，config 会传递给链中的每个组件，但也可以通过 configurable 字段实现更细粒度的控制。

8. 总结

config 参数是 LangChain 调用模型中一个灵活且强大的配置入口。合理使用超时、重试、回调和标签等配置，可以显著提升应用的健壮性和可观测性。建议在实际项目中结合 RunnableConfig 类型，让配置更加清晰和可维护。