LangChain configurable_fields() 用法详解

configurable_fields() 是 LCEL 中实现「运行时动态配置」 的核心方法，和 bind() 是互补关系：

• bind()：写死固定参数（编译时确定）
• configurable_fields()：定义可动态修改的参数（调用时通过 config 传入）

它的核心作用：让 Runnable 组件的参数支持运行时动态切换，比如同一个链，调用时临时改 temperature、模型名、stop 词、工具等，不用重新定义链。

一、核心语法

# 1. 为组件声明可配置字段
runnable.with_configurable_fields(
    字段名1=默认值,
    字段名2=默认值,
    # 可选：配置字段说明
    config_fields={
        "字段名1": ConfigurableField(name="显示名", description="描述")
    }
)

# 2. 调用时传入配置
runnable.invoke(
    input,
    config={"configurable": {"字段名1": 新值}}
)

二、最常用场景：大模型动态配置

1. 基础用法：动态改 temperature / 模型

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

# 1. 定义基础模型
model = ChatOpenAI(model="gpt-3.5-turbo")

# 2. 声明可配置字段：temperature、model_name
configurable_model = model.with_configurable_fields(
    temperature=0.7,       # 默认值
    model_name="gpt-3.5-turbo",
    # 可选：给配置加说明
    config_fields={
        "temperature": ConfigurableField(name="温度", description="0-2随机度"),
        "model_name": ConfigurableField(name="模型名")
    }
)

# 3. 组装链
prompt = ChatPromptTemplate.from_template("{question}")
chain = prompt | configurable_model

2. 调用时动态传配置

# 调用1：使用默认配置
chain.invoke({"question": "介绍AI"})

# 调用2：动态修改 temperature（更随机）
chain.invoke(
    {"question": "介绍AI"},
    config={"configurable": {"temperature": 1.5}}
)

# 调用3：动态切换模型
chain.invoke(
    {"question": "介绍AI"},
    config={"configurable": {"model_name": "gpt-4"}}
)

三、进阶用法

1. 多个可配置字段叠加

# 同时支持：温度、最大token、停止词
configurable_model = model.with_configurable_fields(
    temperature=0.7,
    max_tokens=512,
    stop=["\n"]
)

# 调用时一次性改多个
chain.invoke(
    input,
    config={
        "configurable": {
            "temperature": 0,
            "max_tokens": 100,
            "stop": ["结束"]
        }
    }
)

2. 与 bind() 混用

• bind()：固定不变的参数
• configurable_fields()：允许动态覆盖的参数

# 先 bind 固定参数，再声明可配置字段
model = ChatOpenAI().bind(stop=["END"])
configurable_model = model.with_configurable_fields(temperature=0.7)

3. 给链整体配置（不只是模型）

from langchain_core.output_parsers import StrOutputParser

chain = (
    prompt 
    | configurable_model 
    | StrOutputParser()
).with_configurable_fields(
    # 给整个链加配置（极少用，一般给组件加）
)

四、关键规则（必看）

1. 优先级
   invoke(config) > configurable_fields 默认值 > bind() > 组件原始默认
   运行时传入的配置优先级最高。

2. 必须导入依赖

# 必须导入 ConfigurableField
from langchain_core.runnables import ConfigurableField

3. 适用所有 Runnable
   模型、提示词、解析器、RunnableLambda 都能用。

五、bind() vs configurable_fields() 对比

一句话总结：

• 固定不变 → 用 bind()
• 运行时要改 → 用 configurable_fields()

六、完整可运行示例

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import ConfigurableField

# 1. 定义可配置模型
llm = ChatOpenAI(model="gpt-3.5-turbo")
configurable_llm = llm.with_configurable_fields(
    temperature=0.7,
    max_tokens=300
)

# 2. 构建链
prompt = ChatPromptTemplate.from_messages([
    ("system", "你是专业助手"),
    ("human", "{input}")
])
chain = prompt | configurable_llm

# 3. 动态调用
response = chain.invoke(
    {"input": "什么是LCEL"},
    config={"configurable": {"temperature": 0.1, "max_tokens": 100}}
)
print(response.content)

总结

• configurable_fields()：声明组件的可动态配置参数
• 调用时用 config={"configurable": {key: value}} 传参
• 适合：动态切换模型、温度、最大token、停止词等场景
• 和 bind() 互补，共同实现 LCEL 灵活配置