【LangChain】ainvoke() 方法的 config 参数可配置的设置项

本文基于 LangChain 0.3.x，详细介绍 LangChain 中 模型调用时使用的ainvoke() 方法的 config 参数（类型为 RunnableConfig），列出可配置的设置项、其作用和使用场景，并提供一个独立示例，展示如何通过 config 设置超时和回调来优化人工智能主题的问答工作流，示例突出 config 在异步调用中的灵活性。（ LangChain RunnableConfig 文档)

---

ainvoke() 方法的 config 参数概览

ainvoke() 是 LangChain 中 Runnable 类的异步调用方法，用于异步执行链、模型或工具的逻辑。它接受一个可选的 config 参数，类型为 RunnableConfig，用于配置运行时行为。RunnableConfig 是一个字典或 TypedDict，允许开发者设置超时、并发、回调、元数据等，以控制执行流程和调试。

方法签名：

async def ainvoke(
    self,
    input: Input,
    config: Optional[RunnableConfig] = None,
    **kwargs: Any
) -> Output

• 参数：
  • input（Input）：输入数据，类型取决于具体 Runnable。
  • config（Optional[RunnableConfig]）：运行时配置，默认为 None。
  • **kwargs：其他参数，传递给底层实现。
• 返回值：Output，异步返回的输出，类型取决于 Runnable。

RunnableConfig 的作用：

• 提供运行时控制，如超时、最大并发、回调等。
• 支持调试，通过元数据和标签跟踪执行。
• 允许动态调整行为，适用于复杂工作流。

适用场景：

• 设置超时，防止长时间运行的任务阻塞。
• 添加回调，记录执行日志或监控性能。
• 配置并发，优化多任务处理。
• 传递元数据，跟踪任务来源或上下文。

---

RunnableConfig 可设置项

以下是 RunnableConfig 支持的主要设置项，基于 LangChain 0.3.x 的源码（langchain_core/runnables/config.py）和文档。RunnableConfig 是一个 TypedDict，定义如下：

class RunnableConfig(TypedDict, total=False):
    tags: List[str]
    metadata: Dict[str, Any]
    callbacks: Optional[Callbacks]
    run_name: Optional[str]
    max_concurrency: Optional[int]
    recursion_limit: Optional[int]
    configurable: Optional[Dict[str, Any]]

1. tags

• 类型：List[str]
• 作用：为运行添加标签，用于过滤或分组。
• 使用场景：
  • 区分不同类型的任务（如 "query"、"moderation"）。
  • 在回调中根据标签执行特定逻辑。
• 示例：

  config = {"tags": ["ai_query", "test"]}
  

2. metadata

• 类型：Dict[str, Any]
• 作用：附加元数据，记录任务上下文或标识。
• 使用场景：
  • 跟踪用户 ID、会话 ID 或任务来源。
  • 在日志或监控中记录额外信息。
• 示例：

  config = {"metadata": {"user_id": "123", "session_id": "abc"}}
  

3. callbacks

• 类型：Optional[Callbacks]（List[BaseCallbackHandler] 或 BaseCallbackManager）
• 作用：定义回调函数，监控运行事件（如开始、结束、错误）。
• 支持的回调：
  • langchain_core.callbacks.StdOutCallbackHandler：打印标准输出。
  • langchain_core.callbacks.FileCallbackHandler：记录到文件。
  • 自定义回调：继承 BaseCallbackHandler。
• 使用场景：
  • 记录执行时间或日志。
  • 集成监控工具（如 LangSmith）。
• 示例：

  from langchain_core.callbacks import StdOutCallbackHandler
  config = {"callbacks": [StdOutCallbackHandler()]}
  

4. run_name

• 类型：Optional[str]
• 作用：指定运行的名称，便于跟踪。
• 使用场景：
  • 在复杂工作流中标识特定任务。
  • 在回调或日志中显示任务名称。
• 示例：

  config = {"run_name": "AI_Query"}
  

5. max_concurrency

• 类型：Optional[int]
• 作用：限制并发调用数量，防止资源过载。
• 使用场景：
  • 在高负载场景下控制 API 调用。
  • 优化多线程或异步任务。
• 示例：

  config = {"max_concurrency": 5}
  

6. recursion_limit

• 类型：Optional[int]
• 作用：限制递归深度，防止无限循环（如在代理中）。
• 使用场景：
  • 控制复杂链或代理的迭代次数。
  • 避免栈溢出。
• 示例：

  config = {"recursion_limit": 10}
  

7. configurable

• 类型：Optional[Dict[str, Any]]
• 作用：存储动态配置，传递给特定组件。
• 使用场景：
  • 传递自定义参数（如模型温度、超时）。
  • 支持运行时调整组件行为。
• 示例：

  config = {"configurable": {"timeout": 30, "temperature": 0.9}}
  

其他运行时设置

虽然 RunnableConfig 本身不直接定义以下设置，但 config 可以间接影响底层组件的行为（如通过 configurable 或回调）：

• Timeout：通过 configurable 设置 HTTP 请求超时。

  config = {"configurable": {"timeout": 30}}
  

• API Key：通过 configurable 动态传递密钥（特定于某些链）。

  config = {"configurable": {"api_key": "your-api-key"}}
  

注意：

• 不同 Runnable 子类可能支持额外的 config 设置，需查阅具体文档。
• config 的优先级：运行时 config > 组件初始化配置 > 全局配置（如 langchain.globals）。

---

使用方式

以下是使用 ainvoke() 方法和 config 参数的通用步骤。

1. 安装依赖

pip install --upgrade langchain langchain-openai

2. 设置 OpenAI API 密钥

export OPENAI_API_KEY="your-api-key"

或在代码中：

import os
os.environ["OPENAI_API_KEY"] = "your-api-key"

3. 配置链和 config

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.callbacks import StdOutCallbackHandler
llm = ChatOpenAI(model="gpt-3.5-turbo")
prompt = ChatPromptTemplate.from_template("回答: {input}")
chain = prompt | llm
config = {
    "tags": ["ai_query"],
    "metadata": {"user_id": "123"},
    "callbacks": [StdOutCallbackHandler()],
    "run_name": "AI_Query",
    "configurable": {"timeout": 30}
}

4. 异步调用

import asyncio
result = await chain.ainvoke({"input": "什么是 AI？"}, config=config)
print(result.content)

---

使用 ainvoke() 和 config 的示例

以下是一个独立示例，展示如何使用 ainvoke() 方法的 config 参数配置超时和回调，优化人工智能主题的问答工作流。config 设置包括 callbacks（记录日志）、configurable（超时）和 metadata（用户追踪）。

准备环境：

• 获取 OpenAI API 密钥：OpenAI Platform。
• 设置环境变量：

  export OPENAI_API_KEY="your-api-key"
  

• 安装依赖：

  pip install --upgrade langchain langchain-openai
  

代码：

import asyncio
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnableLambda
from langchain_core.output_parsers import StrOutputParser
from langchain_core.callbacks import StdOutCallbackHandler

# 初始化 ChatOpenAI
llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0.7)

# 定义提示模板
prompt = ChatPromptTemplate.from_template(
    "你是一个人工智能专家，回答问题：{input}\n回答："
)

# 定义输出解析器
parser = StrOutputParser()

# 创建工作流
chain = (
    RunnableLambda(lambda x: x.strip()) | prompt | llm | parser
)

# 定义 config
config = {
    "tags": ["ai_query", "test"],
    "metadata": {"user_id": "123", "session_id": "abc"},
    "callbacks": [StdOutCallbackHandler()],
    "run_name": "AI_Query",
    "configurable": {"timeout": 30}
}

# 测试 ainvoke 和 config 设置
async def main():
    print("测试 ainvoke 和 config 设置：")
    try:
        question = "人工智能是什么？"
        result = await chain.ainvoke(question, config=config)
        print(f"\n输入问题: {question}")
        print(f"回答: {result}")
    except Exception as e:
        print(f"错误: {e}")

# 运行异步主函数
if __name__ == "__main__":
    asyncio.run(main())

输出示例（实际输出取决于模型和网络）：

测试 ainvoke 和 config 设置：
[StdOutCallbackHandler] Started run AI_Query
[StdOutCallbackHandler] Processing prompt...
[StdOutCallbackHandler] Completed run AI_Query

输入问题: 人工智能是什么？
回答: 人工智能（AI）是计算机科学的一个分支，旨在模拟人类智能，如学习、推理和问题解决。

代码说明

1. LLM 初始化：
   • 使用 ChatOpenAI 调用 gpt-3.5-turbo，设置 temperature=0.7。
2. 工作流：
   • 使用 RunnableLambda 清理输入。
   • 组合 prompt、llm 和 parser 形成 LCEL 链。
3. Config 设置：
   • tags: 标记为 "ai_query" 和 "test"。
   • metadata: 记录 user_id 和 session_id。
   • callbacks: 使用 StdOutCallbackHandler 打印日志。
   • run_name: 设置为 "AI_Query"。
   • configurable: 设置超时为 30 秒。
4. 测试：
   • 使用 ainvoke 异步调用，传入 config。
   • 显示问题和回答，展示回调日志。
5. 错误处理：
   • 使用 try-except 捕获 API 或链错误。

运行要求：

• 有效的 OpenAI API 密钥：

  export OPENAI_API_KEY="your-api-key"
  

• 安装依赖：

  pip install --upgrade langchain langchain-openai
  

• 网络连接：访问 https://api.openai.com.

---

注意事项

1. API 密钥：
   • 确保 OPENAI_API_KEY 已设置：

     echo $OPENAI_API_KEY
     

   • 或在代码中设置：

     llm = ChatOpenAI(api_key="your-api-key")
     

2. Config 优先级：
   • 运行时 config 覆盖组件初始化配置：

     config = {"configurable": {"timeout": 60}}
     result = await chain.ainvoke(input, config=config)
     

   • 全局配置（如 langchain.globals）优先级最低。
3. 回调配置：
   • 自定义回调需继承 BaseCallbackHandler：

     from langchain_core.callbacks import BaseCallbackHandler
     class CustomCallback(BaseCallbackHandler):
         def on_chain_start(self, serialized, inputs, **kwargs):
             print("链开始")
     config = {"callbacks": [CustomCallback()]}
     

   • 集成 LangSmith 追踪：

     from langchain.callbacks import LangSmithCallbackHandler
     config = {"callbacks": [LangSmithCallbackHandler()]}
     

4. 性能优化：
   • 超时设置：通过 configurable：

     config = {"configurable": {"timeout": 15}}
     

   • 并发控制：结合 max_concurrency：

     config = {"max_concurrency": 3}
     

   • 异步批量：使用 abatch：

     results = await chain.abatch([input1, input2], config=config)
     

5. 错误调试：
   • 超时错误：
     • 检查 configurable：

       print(config["configurable"])
       

     • 增加超时：

       config = {"configurable": {"timeout": 60}}
       

   • 回调失败：
     • 验证回调：

       print(config["callbacks"])
       

     • 测试单独回调：

       handler = StdOutCallbackHandler()
       handler.on_chain_start({}, {"input": "测试"})
       

   • 输入错误：
     • 检查输入格式：

       print(chain.input_schema)
       

---

常见问题

Q1：如何设置超时？
A：通过 configurable：

config = {"configurable": {"timeout": 30}}
result = await chain.ainvoke(input, config=config)

Q2：如何记录执行时间？
A：使用自定义回调：

from time import time
from langchain_core.callbacks import BaseCallbackHandler
class TimingCallback(BaseCallbackHandler):
    def on_chain_start(self, serialized, inputs, **kwargs):
        self.start = time()
    def on_chain_end(self, outputs, **kwargs):
        print(f"执行耗时: {time() - self.start:.2f} 秒")
config = {"callbacks": [TimingCallback()]}

Q3：如何与代理结合？
A：传递 config 给代理：

from langchain.agents import initialize_agent, AgentType
agent = initialize_agent(tools=[tool], llm=llm, agent=AgentType.OPENAI_FUNCTIONS)
result = await agent.ainvoke({"input": "任务"}, config=config)

Q4：如何支持开源模型？
A：使用 ChatOllama：

from langchain_ollama import ChatOllama
llm = ChatOllama(model="llama3")
chain = prompt | llm | parser
result = await chain.ainvoke(question, config=config)

---

总结

ainvoke() 方法的 config 参数（RunnableConfig）支持以下设置：

• tags: 任务标签，分组或过滤。
• metadata: 元数据，记录上下文。
• callbacks: 回调函数，监控事件。
• run_name: 运行名称，便于跟踪。
• max_concurrency: 并发限制，优化资源。
• recursion_limit: 递归深度，防止循环。
• configurable: 动态参数，如超时。