trustgraph/docs/tech-specs/flow-configurable-parameters.zh-cn.md

layout	title	parent
default	Flow Blueprint Configurable Parameters Technical Specification	Chinese (Beta)

Flow Blueprint Configurable Parameters Technical Specification

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

Overview

本规范描述了 TrustGraph 中可配置参数在流程蓝图中的实现方式。参数允许用户在流程启动时自定义处理器参数，通过提供用于替换流程蓝图定义中参数占位符的值来实现。

<<<<<<< HEAD 参数通过处理器参数中的模板变量替换来实现，类似于 {id} 和 {class} 变量的工作方式，但使用用户提供的值。

该集成支持四种主要用例：

1. 模型选择: 允许用户选择不同的 LLM 模型（例如，gemma3:8b、gpt-4、claude-3）用于处理器。 ======= 参数通过处理器参数中的模板变量替换来工作，类似于 {id} 和 {class} 变量的工作方式，但使用用户提供的值。

该集成支持四种主要用例：

1. 模型选择: 允许用户选择不同的 LLM 模型 (例如，gemma3:8b, gpt-4, claude-3) 用于处理器。

82edf2d (New md files from RunPod)

2. 资源配置: 调整处理器参数，例如块大小、批处理大小和并发限制。
3. 行为调整: 通过参数修改处理器行为，例如温度、最大 token 数或检索阈值。
4. 环境特定参数: 配置每个部署的环境端点、API 密钥或区域特定 URL。

目标

动态处理器配置: 通过参数替换启用处理器参数的运行时配置。 参数验证: 在流程启动时提供参数的类型检查和验证。 <<<<<<< HEAD 默认值: 提供合理的默认值，同时允许高级用户进行覆盖。

默认值: 支持合理的默认值，同时允许高级用户进行覆盖。

82edf2d (New md files from RunPod) 模板替换: Seamlessly 替换处理器参数中的参数占位符。 UI 集成: 通过 API 和 UI 接口提供参数输入。 类型安全: 确保参数类型与预期的处理器参数类型匹配。 文档: 在流程蓝图定义中提供自文档化的参数模式。 向后兼容性: 保持与不使用参数的现有流程蓝图的兼容性。

背景

<<<<<<< HEAD TrustGraph 中的流程蓝图现在支持处理器参数，这些参数可以包含固定值或参数占位符。这为运行时自定义提供了机会。

TrustGraph 中的流程蓝图现在支持处理器参数，这些参数可以包含固定值或参数占位符。 这为运行时自定义提供了机会。

82edf2d (New md files from RunPod)

当前处理器参数支持： 固定值："model": "gemma3:12b" 参数占位符："model": "gemma3:{model-size}"

本规范定义了参数的： <<<<<<< HEAD 在流程蓝图定义中的声明方式 流程启动时的验证方式 在处理器参数中的替换方式 通过 API 和 UI 的暴露方式

在流程蓝图定义中的声明 在流程启动时的验证 在处理器参数中的替换 通过 API 和 UI 的暴露

82edf2d (New md files from RunPod)

通过利用参数化的处理器参数，TrustGraph 可以： 通过使用参数进行变体，减少流程蓝图的重复。 允许用户在不修改定义的情况下调整处理器行为。 通过参数值支持环境特定的配置。 通过参数模式验证确保类型安全。

技术设计

架构

可配置参数系统需要以下技术组件：

1. 参数模式定义 基于 JSON Schema 的参数定义，位于流程蓝图元数据中。 类型定义，包括字符串、数字、布尔值、枚举和对象类型。 验证规则，包括最小值/最大值、模式和必填字段。

   模块：trustgraph-flow/trustgraph/flow/definition.py

2. 参数解析引擎 对模式进行运行时参数验证。 为未指定的参数应用默认值。 将参数注入到流程执行上下文。 如有必要进行类型转换和转换。

   模块：trustgraph-flow/trustgraph/flow/parameter_resolver.py

3. 参数存储集成 从模式/配置存储中检索参数定义。 缓存常用的参数定义。 <<<<<<< HEAD 对其进行验证，以确保其与中心存储的模式一致。 ======= 对其进行集中存储的模式验证。

82edf2d (New md files from RunPod)

模块：trustgraph-flow/trustgraph/flow/parameter_store.py

4. 流程启动器扩展 API 扩展，用于在流程启动期间接受参数值。 <<<<<<< HEAD 参数映射解析（将流程名称映射到定义名称）。 ======= 参数映射解析 (将流程名称映射到定义名称)。

82edf2d (New md files from RunPod) 处理无效参数组合的错误。

模块：trustgraph-flow/trustgraph/flow/launcher.py

5. UI 参数表单 从流程参数元数据动态生成表单。 <<<<<<< HEAD 使用 order 字段显示参数的顺序。 使用 description 字段提供参数的描述性标签。 ======= 使用 order 字段显示参数顺序。 使用 description 字段提供描述性参数标签。

82edf2d (New md files from RunPod) 根据参数类型定义进行输入验证。 参数预设和模板。

模块：trustgraph-ui/components/flow-parameters/

数据模型

<<<<<<< HEAD

参数定义（存储在模式/配置中）

参数定义以类型为 "parameter-type" 的方式存储在模式和配置系统中。

参数定义 (存储在模式/配置中)

参数定义以类型 "parameter-type" 存储在模式和配置系统中。

82edf2d (New md files from RunPod)

{
  "llm-model": {
    "type": "string",
    "description": "LLM model to use",
    "default": "gpt-4",
    "enum": [
      {
        "id": "gpt-4",
        "description": "OpenAI GPT-4 (Most Capable)"
      },
      {
        "id": "gpt-3.5-turbo",
        "description": "OpenAI GPT-3.5 Turbo (Fast & Efficient)"
      },
      {
        "id": "claude-3",
        "description": "Anthropic Claude 3 (Thoughtful & Safe)"
      },
      {
        "id": "gemma3:8b",
        "description": "Google Gemma 3 8B (Open Source)"
      }
    ],
    "required": false
  },
  "model-size": {
    "type": "string",
    "description": "Model size variant",
    "default": "8b",
    "enum": ["2b", "8b", "12b", "70b"],
    "required": false
  },
  "temperature": {
    "type": "number",
    "description": "Model temperature for generation",
    "default": 0.7,
    "minimum": 0.0,
    "maximum": 2.0,
    "required": false
  },
  "chunk-size": {
    "type": "integer",
    "description": "Document chunk size",
    "default": 512,
    "minimum": 128,
    "maximum": 2048,
    "required": false
  }
}

带有参数引用的流程蓝图

流程蓝图定义了参数元数据，包括类型引用、描述和排序：

{
  "flow_class": "document-analysis",
  "parameters": {
    "llm-model": {
      "type": "llm-model",
      "description": "Primary LLM model for text completion",
      "order": 1
    },
    "llm-rag-model": {
      "type": "llm-model",
      "description": "LLM model for RAG operations",
      "order": 2,
      "advanced": true,
      "controlled-by": "llm-model"
    },
    "llm-temperature": {
      "type": "temperature",
      "description": "Generation temperature for creativity control",
      "order": 3,
      "advanced": true
    },
    "chunk-size": {
      "type": "chunk-size",
      "description": "Document chunk size for processing",
      "order": 4,
      "advanced": true
    },
    "chunk-overlap": {
      "type": "integer",
      "description": "Overlap between document chunks",
      "order": 5,
      "advanced": true,
      "controlled-by": "chunk-size"
    }
  },
  "class": {
    "text-completion:{class}": {
      "request": "non-persistent://tg/request/text-completion:{class}",
      "response": "non-persistent://tg/response/text-completion:{class}",
      "parameters": {
        "model": "{llm-model}",
        "temperature": "{llm-temperature}"
      }
    },
    "rag-completion:{class}": {
      "request": "non-persistent://tg/request/rag-completion:{class}",
      "response": "non-persistent://tg/response/rag-completion:{class}",
      "parameters": {
        "model": "{llm-rag-model}",
        "temperature": "{llm-temperature}"
      }
    }
  },
  "flow": {
    "chunker:{id}": {
      "input": "persistent://tg/flow/chunk:{id}",
      "output": "persistent://tg/flow/chunk-load:{id}",
      "parameters": {
        "chunk_size": "{chunk-size}",
        "chunk_overlap": "{chunk-overlap}"
      }
    }
  }
}

parameters 部分将流程特定的参数名称（键）映射到包含以下内容的参数元数据对象： type：对中心定义的参数定义的引用（例如，“llm-model”） description：用于UI显示的易于理解的描述 order：参数表单的显示顺序（较小的数字首先显示） advanced（可选）：布尔标志，指示是否为高级参数（默认：false）。如果设置为true，UI可能会默认隐藏此参数或将其放置在“高级”部分 <<<<<<< HEAD controlled-by（可选）：控制此参数在简单模式下值的另一个参数的名称。如果指定，此参数将从控制参数继承其值，除非显式覆盖

controlled-by（可选）：控制此参数在简单模式下值的另一个参数的名称。如果指定，此参数将继承其值来自控制参数，除非显式覆盖

82edf2d (New md files from RunPod)

这种方法允许： 在多个流程蓝图之间重用参数类型定义 集中管理和验证参数类型 流程特定的参数描述和排序 通过描述性的参数表单增强UI体验 流程中参数验证的一致性 轻松添加新的标准参数类型 通过基本/高级模式分离简化UI 相关设置的参数值继承

流程启动请求

流程启动API使用流程的参数名称来接受参数：

{
  "flow_class": "document-analysis",
  "flow_id": "customer-A-flow",
  "parameters": {
    "llm-model": "claude-3",
    "llm-temperature": 0.5,
    "chunk-size": 1024
  }
}

<<<<<<< HEAD 注意：在这个例子中，llm-rag-model 没有明确提供，但会从 llm-model 继承值 "claude-3"，这是因为 llm-rag-model 与 llm-model 之间存在 controlled-by 关系。 类似地，chunk-overlap 可能会继承一个基于 chunk-size 计算的值。

注意：在这个例子中，llm-rag-model 没有显式提供，但会从 llm-model 继承 "claude-3" 的值，这是因为 llm-rag-model 与 llm-model 之间存在 controlled-by 关系。 类似地，chunk-overlap 可能会继承一个基于 chunk-size 计算的值。

82edf2d (New md files from RunPod)

系统将执行以下操作：

1. 从流程蓝图定义中提取参数元数据
2. 将流程参数名称映射到其类型定义（例如，llm-model → llm-model 类型）
3. 解析受控关系（例如，llm-rag-model 从 llm-model 继承）
4. 验证用户提供的和继承的值是否符合参数类型定义
5. 在流程实例化期间，将解析的值替换到处理器参数中

实现细节

参数解析过程

当启动流程时，系统执行以下参数解析步骤：

1. 流程蓝图加载: 加载流程蓝图定义并提取参数元数据
2. 元数据提取: 提取每个参数的 type、description、order、advanced 和 controlled-by，这些信息位于流程蓝图的 parameters 部分
3. 类型定义查找: 对于流程蓝图中的每个参数： <<<<<<< HEAD 使用 type 字段从 schema/config 存储中检索参数类型定义 类型定义存储在配置系统中，类型为 "parameter-type" 每个类型定义包含参数的 schema、默认值和验证规则 ======= 使用 type 字段从模式/配置存储中检索参数类型定义 类型定义存储在配置系统中，类型为 "parameter-type" 每个类型定义包含参数的模式、默认值和验证规则

82edf2d (New md files from RunPod)

4. 默认值解析: 对于流程蓝图中定义的每个参数： 检查用户是否为该参数提供了值 如果未提供用户值，则使用参数类型定义中的 default 值 构建一个完整的参数映射，其中包含用户提供的和默认值
5. 参数继承解析（受控关系）： 对于具有 controlled-by 字段的参数，检查是否已显式提供值 如果未提供显式值，则从控制参数继承该值 如果控制参数也无值，则从类型定义中获取默认值 验证 controlled-by 关系中是否存在循环依赖
6. 验证: 验证完整的参数集（用户提供的、默认值和继承的值）是否符合类型定义
7. 存储: 将完整的解析后的参数集与流程实例一起存储，以进行审计 <<<<<<< HEAD
8. 模板替换: 使用解析后的值替换处理器参数中的参数占位符 =======
9. 模板替换: 使用解析的值替换处理器参数中的参数占位符

82edf2d (New md files from RunPod)

9. 处理器实例化: 使用替换后的参数创建处理器

重要的实现说明： 流程服务必须将用户提供的参数与参数类型定义中的默认值合并 完整的参数集（包括应用的默认值）必须与流程一起存储，以进行可追溯性 <<<<<<< HEAD 参数解析发生在流程启动时间，而不是处理器实例化时间

参数解析发生在流程启动时，而不是在处理器实例化时

82edf2d (New md files from RunPod) 缺少没有默认值的必需参数会导致流程启动失败，并显示清晰的错误消息

具有 controlled-by 的参数继承

controlled-by 字段启用参数值继承，这对于简化用户界面同时保持灵活性非常有用：

示例场景： llm-model 参数控制主要的 LLM 模型 llm-rag-model 参数具有 "controlled-by": "llm-model" 在简单模式下，将 llm-model 设置为 "gpt-4" 会自动将 llm-rag-model 也设置为 "gpt-4" 在高级模式下，用户可以覆盖 llm-rag-model 并使用不同的值

解析规则：

1. 如果参数具有显式提供的值，则使用该值
2. 如果没有显式值且 controlled-by 已设置，则使用控制参数的值
3. 如果控制参数没有值，则回退到类型定义中的默认值
4. controlled-by 关系中的循环依赖会导致验证错误

UI 行为： 在基本/简单模式下：具有 controlled-by 的参数可能被隐藏或显示为只读，并显示继承的值 在高级模式下：显示所有参数，并且可以单独配置 当控制参数更改时，依赖参数会自动更新，除非显式覆盖

Pulsar 集成

1. 启动流程操作 Pulsar 启动流程操作需要接受一个 parameters 字段，该字段包含参数值的映射 <<<<<<< HEAD Pulsar 启动流程请求的 schema 必须更新为包含可选的 parameters 字段 ======= Pulsar 用于启动流程的请求模式必须更新为包含可选的 parameters 字段

82edf2d (New md files from RunPod) 示例请求：

{
  "flow_class": "document-analysis",
  "flow_id": "customer-A-flow",
  "parameters": {
    "model": "claude-3",
    "size": "12b",
    "temp": 0.5,
    "chunk": 1024
  }
}

2. 获取流程操作 <<<<<<< HEAD 必须更新 Pulsar 模式，以包含 parameters 字段，用于获取流程的响应。 ======= Pulsar 用于获取流程响应的 schema 必须更新，以包含 parameters 字段。

82edf2d (New md files from RunPod) 这允许客户端检索在启动流程时使用的参数值。 示例响应：

{
  "flow_id": "customer-A-flow",
  "flow_class": "document-analysis",
  "status": "running",
  "parameters": {
    "model": "claude-3",
    "size": "12b",
    "temp": 0.5,
    "chunk": 1024
  }
}

流程服务实现

流程配置服务 (trustgraph-flow/trustgraph/config/service/flow.py) 需要以下增强：

1. 参数解析功能

   async def resolve_parameters(self, flow_class, user_params):
       """
       Resolve parameters by merging user-provided values with defaults.
   
       Args:
           flow_class: The flow blueprint definition dict
           user_params: User-provided parameters dict
   
       Returns:
           Complete parameter dict with user values and defaults merged
       """
   

   此函数应该： 从流程蓝图的 parameters 部分提取参数元数据 对于每个参数，从配置存储中获取其类型定义 为任何未由用户提供的参数应用默认值 处理 controlled-by 继承关系 返回完整的参数集

2. 修改后的 handle_start_flow 方法 在加载流程蓝图后调用 resolve_parameters 使用完整的解析后的参数集进行模板替换 将完整的参数集（不仅仅是用户提供的）与流程一起存储 验证所有必需的参数是否具有值

3. 参数类型获取 参数类型定义存储在配置中，类型为 "parameter-type" 每个类型定义包含模式、默认值和验证规则 缓存常用的参数类型以减少配置查找

配置系统集成

3. 流程对象存储 当流程组件在配置管理器中向配置系统添加流程时，流程对象必须包含解析后的参数值 <<<<<<< HEAD 配置管理器需要同时存储原始的用户提供的参数和解析后的值（已应用默认值） ======= 配置管理器需要存储原始的用户提供的参数以及解析后的值（已应用默认值）

82edf2d (New md files from RunPod) 配置系统中的流程对象应包含： parameters: 用于流程的最终解析后的参数值

CLI 集成

4. 库 CLI 命令 启动流程的 CLI 命令需要参数支持： 通过命令行标志或配置文件接受参数值 在提交之前，根据流程蓝图定义验证参数 支持参数文件输入（JSON/YAML），用于复杂的参数集

   显示流程的 CLI 命令需要显示参数信息： 显示启动流程时使用的参数值 显示流程蓝图的可用参数 显示参数验证模式和默认值

处理器基础类集成

5. ParameterSpec 支持 处理器基础类需要支持通过现有的 ParametersSpec 机制进行参数替换 如果需要，应增强 ParametersSpec 类（位于与 ConsumerSpec 和 ProducerSpec 相同的模块中），以支持参数模板替换 处理器应能够调用 ParametersSpec 来使用在流程启动时解析的参数值配置其参数 ParametersSpec 的实现需要： 接受包含参数占位符（例如，{model}，{temperature}）的参数配置 在实例化处理器时，支持运行时参数替换 验证替换后的值是否符合预期的类型和约束 为缺失或无效的参数引用提供错误处理

替换规则

参数使用格式 {parameter-name} 在处理器参数中 <<<<<<< HEAD 参数名称与流程的 parameters 部分中的键匹配

参数名称在参数中与流程的 parameters 部分中的键匹配

82edf2d (New md files from RunPod) 替换操作与 {id} 和 {class} 替换同时进行 无效的参数引用会导致启动时出错 基于中心存储的参数定义进行类型验证 重要提示：所有参数值都以字符串形式存储和传输 数字转换为字符串（例如，0.7 变为 "0.7"） 布尔值转换为小写字符串（例如，true 变为 "true"） 这是由 Pulsar 模式要求的，该模式定义了 parameters = Map(String())

示例解析：

Flow parameter mapping: "model": "llm-model"
Processor parameter: "model": "{model}"
User provides: "model": "gemma3:8b"
Final parameter: "model": "gemma3:8b"

Example with type conversion:
Parameter type default: 0.7 (number)
Stored in flow: "0.7" (string)
Substituted in processor: "0.7" (string)

测试策略

用于参数模式验证的单元测试 用于处理器参数中参数替换的集成测试 用于使用不同参数值启动流程的端到端测试 用于参数表单生成和验证的 UI 测试 用于具有许多参数的流程的性能测试 边界情况：缺少参数、无效类型、未定义的参数引用

迁移计划

<<<<<<< HEAD

1. 系统应继续支持未声明参数的流程蓝图。 2. 系统应继续支持未指定参数的流程： =======
2. 系统应继续支持未声明任何参数的流程蓝图。 2. 系统应继续支持未指定任何参数的流程：

82edf2d (New md files from RunPod) 这适用于没有参数的流程，以及具有参数的流程（它们具有默认值）。

(它们有默认值)。

开放问题

问：参数是否应该支持复杂的嵌套对象，还是仅限于简单类型？ 答：参数值将被字符串编码，我们可能更倾向于 使用字符串。

<<<<<<< HEAD 问：是否允许在队列名称中使用参数占位符，还是仅在

问：是否允许在队列名称中使用参数占位符，或者仅在

82edf2d (New md files from RunPod) 参数中使用？ 答：仅在参数中使用，以避免奇怪的注入和边缘情况。

问：如何处理参数名称与系统变量（如 id 和 class）之间的冲突？ 答：在启动流程时，指定 id 和 class 是无效的。

问：我们是否应该支持计算参数（从其他参数派生）？ 答：仅进行字符串替换，以避免奇怪的注入和边缘情况。

<<<<<<< HEAD

引用

=======

参考文献

82edf2d (New md files from RunPod)

JSON Schema 规范：https://json-schema.org/ 流程蓝图定义规范：docs/tech-specs/flow-class-definition.md