mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 08:26:21 +02:00
8954fa3ad7
Native CLI i18n: The TrustGraph CLI has built-in translation support that dynamically loads language strings. You can test and use different languages by simply passing the --lang flag (e.g., --lang es for Spanish, --lang ru for Russian) or by configuring your environment's LANG variable. Automated Docs Translations: This PR introduces autonomously translated Markdown documentation into several target languages, including Spanish, Swahili, Portuguese, Turkish, Hindi, Hebrew, Arabic, Simplified Chinese, and Russian.
317 lines
9.3 KiB
Markdown
317 lines
9.3 KiB
Markdown
---
|
||
layout: default
|
||
title: "流程蓝图定义规范"
|
||
parent: "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)
|
||
|
||
```json
|
||
"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. 流程部分
|
||
定义与流程相关的处理器，这些处理器为每个独立的流程实例进行实例化。 每个流程都拥有自己的一组隔离的处理器。
|
||
|
||
```json
|
||
"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)
|
||
```json
|
||
"interfaces": {
|
||
"document-load": "persistent://tg/flow/document-load:{id}",
|
||
"triples-store": "persistent://tg/flow/triples-store:{id}"
|
||
}
|
||
```
|
||
|
||
**请求/响应模式** (包含请求/响应字段的对象):
|
||
```json
|
||
"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. 参数部分
|
||
将流程特定的参数名称映射到集中存储的参数定义：
|
||
|
||
```json
|
||
"parameters": {
|
||
"model": "llm-model",
|
||
"temp": "temperature",
|
||
"chunk": "chunk-size"
|
||
}
|
||
```
|
||
|
||
**特性：**
|
||
键是处理器设置中使用的参数名称（例如，`{model}`）
|
||
值引用存储在 schema/config 中的参数定义
|
||
允许在流程之间重用常见的参数定义
|
||
减少参数模式的重复
|
||
|
||
### 5. 元数据
|
||
关于流程蓝图的附加信息：
|
||
|
||
```json
|
||
"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}`
|
||
被替换为启动流程时提供的值
|
||
验证通过与集中存储的参数定义进行比较
|
||
|
||
## 处理器设置
|
||
|
||
设置在实例化时向处理器提供配置值。 它们可以是：
|
||
|
||
### 静态设置
|
||
直接值，不会改变：
|
||
```json
|
||
"settings": {
|
||
"model": "gemma3:12b",
|
||
"temperature": 0.7,
|
||
"max_retries": 3
|
||
}
|
||
```
|
||
|
||
### 参数化设置
|
||
使用在流程启动时提供的参数的值：
|
||
```json
|
||
"settings": {
|
||
"model": "{model}",
|
||
"temperature": "{temp}",
|
||
"endpoint": "https://{region}.api.example.com"
|
||
}
|
||
```
|
||
|
||
参数名称在设置中对应于流程的 `parameters` 部分中的键。
|
||
|
||
### 设置示例
|
||
|
||
**带有参数的 LLM 处理器：**
|
||
```json
|
||
// 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}"
|
||
}
|
||
}
|
||
```
|
||
|
||
**具有固定和参数化设置的分块器：**
|
||
```json
|
||
// 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. **存储写入器**: 将处理后的数据持久化到适当的存储中
|
||
=======
|
||
1. **文档处理管道**: 从摄取到转换再到存储
|
||
2. **查询服务**: 集成的处理器，查询相同的存储和服务
|
||
3. **共享服务**: 所有流程都可以使用的集中处理器
|
||
4. **存储写入器**: 将处理后的数据持久化到适当的存储
|
||
>>>>>>> 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. **统一架构**: 查询和处理是相同的数据流的一部分
|