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

---
layout: default
title: "Flow Blueprint Configurable Parameters Technical Specification"
parent: "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)

```json
{
  "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
  }
}
```

#### 带有参数引用的流程蓝图

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

```json
{
  "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使用流程的参数名称来接受参数：

```json
{
  "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. **模板替换**: 使用解析后的值替换处理器参数中的参数占位符
=======
8. **模板替换**: 使用解析的值替换处理器参数中的参数占位符
>>>>>>> 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)
   示例请求：
   ```json
   {
     "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)
   这允许客户端检索在启动流程时使用的参数值。
   示例响应：
   ```json
   {
     "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. **参数解析功能**
   ```python
   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. 系统应继续支持未指定参数的流程：
=======
1. 系统应继续支持未声明任何参数的流程蓝图。
   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