配置管理与 Configurable

📚 学习目标

学完这篇文章后，你将能够：

理解 RunnableConfig 对象的作用
在节点中访问运行时配置
实现可配置的 Agent（如动态切换模型、Prompt）

前置知识

在开始学习之前，建议先阅读：

01-visualization

你需要了解：

环境变量的基本概念

1️⃣ 什么是 RunnableConfig？

在调用 invoke, stream, batch 时，LangGraph 允许传入第二个参数：RunnableConfig。

import { RunnableConfig } from '@langchain/core/runnables';

await app.invoke(inputs, {
  configurable: {
    model: "gpt-4",
    temperature: 0.5
  },
  recursionLimit: 50,
  runName: "MyAgentRun"
});

这些配置不仅控制运行时的行为（如递归限制），还可以透传给图中的每个节点。

如果你把它当成一个“运行时上下文对象”会更好理解：

configurable：你自定义的运行参数（用户ID、模型名、feature flag...）
tags/metadata：可观测性与追踪用（打标签、记录额外信息）
recursionLimit：防止循环失控

2️⃣ RunnableConfig 里常用的字段

下面是一个“面向教学”的简化心智模型（不同版本字段可能略有差异）：

export type ExampleRunnableConfig = {
  configurable?: Record<string, unknown>;
  tags?: string[];
  metadata?: Record<string, unknown>;
  recursionLimit?: number;
  runName?: string;
};

3️⃣ 节点内访问配置

节点函数的第二个参数就是 config。

const myNode = async (state: State, config: RunnableConfig) => {
  // 1. 获取配置
  const modelName = config.configurable?.model || "gpt-3.5-turbo";
  
  // 2. 使用配置
  const model = new ChatOpenAI({ model: modelName });
  const response = await model.invoke(state.messages);
  
  return { messages: [response] };
};

为什么这很有用？

多租户支持：不同用户使用不同的 prompt 或模型。
A/B 测试：运行时动态决定使用哪个策略。
安全性：动态传入 User ID 或 API Token。

[!NOTE] 不要把明文 API Key 放进 configurable。更稳妥的方式是传 keyId / tenantId，在节点里再去你的密钥系统取真实 key。

4️⃣ 预置配置项

LangGraph 有一些内置的配置键：

recursionLimit: 最大递归深度（默认 25）。防止死循环。
thread_id: 用于 Checkpoint 持久化（区分不同会话）。
runName: 在 LangSmith 追踪中显示的名称。

// 防止死循环的保护机制
try {
  await app.invoke(inputs, { recursionLimit: 5 });
} catch (e) {
  console.log("达到递归限制！");
}

5️⃣ 配置继承：子图/节点如何拿到同一套参数

当你把一个“编译后的 subgraph”当作节点接入父图时，运行时配置通常会沿调用链传递下去。

💡 练习题

编码题：修改你的 ReAct Agent，使其接受一个 systemPrompt 配置参数。在运行时动态传入不同的角色设定（如“你是一个海盗” vs “你是一个医生”）。
场景题：如果在 configurable 中传入了一个敏感的 API Key，它会被 LangSmith 记录吗？如何避免？（提示：LangSmith 有脱敏机制，但最好不要明文传递敏感信息在 configurable 中，而是传递 Key 的引用或 ID）

📚 参考资源

官方文档

LangGraph JS

✅ 总结

本章要点：

configurable 字段是运行时动态传参的主要通道。
节点函数的签名是 (state, config) => ...。
合理使用配置可以让你的 Graph 更加通用和灵活。

下一步：如果运行出错了怎么办？继续学习：错误处理。

登录以继续阅读

解锁完整文档、代码示例及更多高级功能。

立即登录

配置管理与 Configurable

登录以继续阅读

On this page