trustgraph/docs/tech-specs/flow-class-definition.zh-cn.md

layout	title	parent
default	流程蓝图定义规范	Chinese (Beta)

<<<<<<< HEAD

流程蓝图定义规范

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.

概述

流程蓝图在 TrustGraph 系统中定义了一个完整的数据流模式模板。当实例化时，它会创建一个相互连接的处理单元网络，该网络处理数据摄取、处理、存储和查询，作为一个统一的系统。

结构

流程蓝图定义由五个主要部分组成：

1. 类部分

定义共享服务处理器，这些处理器每个流程蓝图实例化一次。这些处理器处理来自此类的所有流程实例的请求。

流工作蓝图定义规范

概述

一个流工作蓝图定义了 TrustGraph 系统中完整的数据流模式模板。当实例化时，它会创建一个相互连接的处理单元网络，该网络处理数据摄取、处理、存储和查询，作为一个统一的系统。

结构

一个流工作蓝图定义由五个主要部分组成：

1. 类部分

定义共享服务处理器，这些处理器每个流工作蓝图实例化一次。这些处理器处理来自此类的所有流实例的请求。

82edf2d (New md files from RunPod)

"class": {
  "service-name:{class}": {
    "request": "queue-pattern:{class}",
    "response": "queue-pattern:{class}",
    "settings": {
      "setting-name": "fixed-value",
      "parameterized-setting": "{parameter-name}"
    }
  }
}

<<<<<<< HEAD 特性：

特点：

82edf2d (New md files from RunPod) 在同一类别的所有流程实例中共享。 通常是昂贵或无状态的服务（例如：大型语言模型、嵌入模型）。 使用 {class} 模板变量进行队列命名。 设置可以是固定值，也可以使用 {parameter-name} 语法进行参数化。 示例：embeddings:{class}, text-completion:{class}, graph-rag:{class}

2. 流程部分

定义与流程相关的处理器，这些处理器为每个独立的流程实例进行实例化。 每个流程都拥有自己的一组隔离的处理器。

"flow": {
  "processor-name:{id}": {
    "input": "queue-pattern:{id}",
    "output": "queue-pattern:{id}",
    "settings": {
      "setting-name": "fixed-value",
      "parameterized-setting": "{parameter-name}"
    }
  }
}

特性： 每个流程只有一个实例。 处理流程特定的数据和状态。 使用 {id} 模板变量进行队列命名。 设置可以是固定值，也可以使用 {parameter-name} 语法进行参数化。 示例：chunker:{id}, pdf-decoder:{id}, kg-extract-relationships:{id}

3. 接口部分

定义流程的入口点和交互协议。 这些构成了外部系统和内部组件通信的 API 表面。

<<<<<<< HEAD 接口可以有两种形式：

即发即弃模式（单个队列）：

接口可以采用两种形式：

发布-订阅模式（单个队列）：

82edf2d (New md files from RunPod)

"interfaces": {
  "document-load": "persistent://tg/flow/document-load:{id}",
  "triples-store": "persistent://tg/flow/triples-store:{id}"
}

请求/响应模式 (包含请求/响应字段的对象):

"interfaces": {
  "embeddings": {
    "request": "non-persistent://tg/request/embeddings:{class}",
    "response": "non-persistent://tg/response/embeddings:{class}"
  }
}

接口类型： 入口点： 外部系统注入数据的入口点 (document-load, agent) 服务接口： 服务请求/响应模式 (embeddings, text-completion) 数据接口： 触发/完成式数据流连接点 (triples-store, entity-contexts-load)

4. 参数部分

将流程特定的参数名称映射到集中存储的参数定义：

"parameters": {
  "model": "llm-model",
  "temp": "temperature",
  "chunk": "chunk-size"
}

特性： 键是处理器设置中使用的参数名称（例如，{model}） 值引用存储在 schema/config 中的参数定义 允许在流程之间重用常见的参数定义 减少参数模式的重复

5. 元数据

关于流程蓝图的附加信息：

"description": "Human-readable description",
"tags": ["capability-1", "capability-2"]

模板变量

系统变量

{id}

被替换为唯一的流程实例标识符 为每个流程创建隔离的资源 示例：flow-123, customer-A-flow

{class}

被替换为流程蓝图名称 为相同类别的流程创建共享资源 示例：standard-rag, enterprise-rag

参数变量

{parameter-name}

在流程启动时定义的自定义参数 参数名称与流程的 parameters 部分中的键匹配 用于在处理器设置中自定义行为 示例：{model}, {temp}, {chunk} 被替换为启动流程时提供的值 验证通过与集中存储的参数定义进行比较

处理器设置

设置在实例化时向处理器提供配置值。 它们可以是：

静态设置

直接值，不会改变：

"settings": {
  "model": "gemma3:12b",
  "temperature": 0.7,
  "max_retries": 3
}

参数化设置

使用在流程启动时提供的参数的值：

"settings": {
  "model": "{model}",
  "temperature": "{temp}",
  "endpoint": "https://{region}.api.example.com"
}

参数名称在设置中对应于流程的 parameters 部分中的键。

设置示例

带有参数的 LLM 处理器：

// In parameters section:
"parameters": {
  "model": "llm-model",
  "temp": "temperature",
  "tokens": "max-tokens",
  "key": "openai-api-key"
}

// In processor definition:
"text-completion:{class}": {
  "request": "non-persistent://tg/request/text-completion:{class}",
  "response": "non-persistent://tg/response/text-completion:{class}",
  "settings": {
    "model": "{model}",
    "temperature": "{temp}",
    "max_tokens": "{tokens}",
    "api_key": "{key}"
  }
}

具有固定和参数化设置的分块器：

// In parameters section:
"parameters": {
  "chunk": "chunk-size"
}

// In processor definition:
"chunker:{id}": {
  "input": "persistent://tg/flow/chunk:{id}",
  "output": "persistent://tg/flow/chunk-load:{id}",
  "settings": {
    "chunk_size": "{chunk}",
    "chunk_overlap": 100,
    "encoding": "utf-8"
  }
}

队列模式 (Pulsar)

流程蓝图使用 Apache Pulsar 进行消息传递。队列名称遵循 Pulsar 格式：

<persistence>://<tenant>/<namespace>/<topic>

组件：

持久性: persistent 或 non-persistent (Pulsar 持久性模式) 租户: tg 用于 TrustGraph 提供的流程蓝图定义 命名空间: 表示消息模式 flow: 适用于“发送即忘”服务 request: 适用于请求/响应服务的请求部分 response: 适用于请求/响应服务的响应部分 主题: 具有模板变量的特定队列/主题名称

持久队列

模式: persistent://tg/flow/<topic>:{id} 用于“发送即忘”服务和持久数据流 数据在 Pulsar 存储中持久化，即使在重启后也保留 示例: persistent://tg/flow/chunk-load:{id}

非持久队列

模式: non-persistent://tg/request/<topic>:{class} 或 non-persistent://tg/response/<topic>:{class} 用于请求/响应消息模式 瞬态的，不由 Pulsar 持久化到磁盘 延迟较低，适用于 RPC 风格的通信 示例: non-persistent://tg/request/embeddings:{class}

数据流架构

流程蓝图创建统一的数据流，其中：

<<<<<<< HEAD

1. 文档处理管道: 从摄取到转换再到存储的流程
2. 查询服务: 集成的处理器，查询相同的存储和服务
3. 共享服务: 所有流程都可以使用的集中式处理器
4. 存储写入器: 将处理后的数据持久化到适当的存储中 =======
5. 文档处理管道: 从摄取到转换再到存储
6. 查询服务: 集成的处理器，查询相同的存储和服务
7. 共享服务: 所有流程都可以使用的集中处理器
8. 存储写入器: 将处理后的数据持久化到适当的存储

82edf2d (New md files from RunPod)

所有处理器（包括 {id} 和 {class}）协同工作，形成一个连贯的数据流图，而不是作为独立的系统。

流程实例化示例

假设： 流程实例 ID: customer-A-flow 流程蓝图: standard-rag 流程参数映射： "model": "llm-model" "temp": "temperature" "chunk": "chunk-size" 用户提供的参数： model: gpt-4 temp: 0.5 chunk: 512

模板扩展： persistent://tg/flow/chunk-load:{id} → persistent://tg/flow/chunk-load:customer-A-flow non-persistent://tg/request/embeddings:{class} → non-persistent://tg/request/embeddings:standard-rag "model": "{model}" → "model": "gpt-4" "temperature": "{temp}" → "temperature": "0.5" "chunk_size": "{chunk}" → "chunk_size": "512"

这会创建： 用于 customer-A-flow 的隔离文档处理管道 用于所有 standard-rag 流程的共享嵌入服务 从文档摄取到查询的完整数据流 使用提供的参数值配置的处理器

优点

1. 资源效率: 昂贵的服务在流程之间共享
2. 流程隔离: 每个流程都有自己的数据处理管道
3. 可扩展性: 可以从相同的模板实例化多个流程
4. 模块化: 共享组件和流程特定组件之间有明确的分离
5. 统一架构: 查询和处理是相同的数据流的一部分