mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-07-09 13:22:10 +02:00
277 lines
No EOL
14 KiB
Markdown
277 lines
No EOL
14 KiB
Markdown
# Спецификация определения шаблона потока
|
||
|
||
## Обзор
|
||
|
||
Шаблон потока определяет полный шаблон структуры потока данных в системе TrustGraph. При инстанцировании он создает взаимосвязанную сеть процессоров, которые обрабатывают прием данных, обработку, хранение и запросы как единую систему.
|
||
|
||
## Структура
|
||
|
||
Определение шаблона потока состоит из пяти основных разделов:
|
||
|
||
### 1. Раздел классов
|
||
Определяет общие сервисные процессоры, которые инстанцируются один раз для каждого шаблона потока. Эти процессоры обрабатывают запросы от всех экземпляров потока этого класса.
|
||
|
||
```json
|
||
"class": {
|
||
"service-name:{class}": {
|
||
"request": "queue-pattern:{class}",
|
||
"response": "queue-pattern:{class}",
|
||
"settings": {
|
||
"setting-name": "fixed-value",
|
||
"parameterized-setting": "{parameter-name}"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**Характеристики:**
|
||
Общие для всех экземпляров потока одного класса.
|
||
Обычно это дорогие или безсостояниевые сервисы (LLM, модели эмбеддингов).
|
||
Используйте переменную шаблона `{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}`.
|
||
|
||
### Раздел "Интерфейсы"
|
||
Определяет точки входа и контракты взаимодействия для потока. Они формируют API для внешних систем и взаимодействия между внутренними компонентами.
|
||
|
||
Интерфейсы могут иметь две формы:
|
||
|
||
**Модель "Отправь и забудь"** (одна очередь):
|
||
```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}`
|
||
|
||
## Архитектура потока данных
|
||
|
||
Шаблон потока данных создает унифицированный поток, где:
|
||
|
||
1. **Конвейер обработки документов**: Поток от получения данных до преобразования и хранения
|
||
2. **Сервисы запросов**: Интегрированные процессоры, которые запрашивают одни и те же хранилища данных и сервисы
|
||
3. **Общие сервисы**: Централизованные процессоры, которые могут использоваться всеми потоками
|
||
4. **Модули записи данных**: Сохраняют обработанные данные в соответствующие хранилища
|
||
|
||
Все процессоры (как `{id}`, так и `{class}`) работают вместе как единый граф потока данных, а не как отдельные системы.
|
||
|
||
## Пример инстанцирования потока
|
||
|
||
Дано:
|
||
Идентификатор экземпляра потока: `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. **Унифицированная архитектура**: Запросы и обработка являются частью одного потока данных |