mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 08:26:21 +02:00
314 lines
16 KiB
Markdown
314 lines
16 KiB
Markdown
|
---
|
|||
|
|
layout: default
|
|||
|
|
title: "Спецификация определения шаблона потока"
|
|||
|
|
parent: "Russian (Beta)"
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# Спецификация определения шаблона потока
|
|||
|
|
|
|||
|
|
> **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. Раздел классов
|
|||
|
|
Определяет общие сервисные процессоры, которые инстанцируются один раз для каждого шаблона потока. Эти процессоры обрабатывают запросы от всех экземпляров потока этого класса.
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
"class": {
|
|||
|
|
"service-name:{class}": {
|
|||
|
|
"request": "queue-pattern:{class}",
|
|||
|
|
"response": "queue-pattern:{class}",
|
|||
|
|
"settings": {
|
|||
|
|
"setting-name": "fixed-value",
|
|||
|
|
"parameterized-setting": "{parameter-name}"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**Характеристики:**
|
|||
|
|
<<<<<<< HEAD
|
|||
|
|
Общие для всех экземпляров потока одного класса.
|
|||
|
|
Обычно это дорогие или безсостояниевые сервисы (LLM, модели эмбеддингов).
|
|||
|
|
Используйте переменную шаблона `{class}` для именования очереди.
|
|||
|
|
Настройки могут быть фиксированными значениями или параметризованы с использованием синтаксиса `{parameter-name}`.
|
|||
|
|
=======
|
|||
|
|
Распространяются на все экземпляры потока одного и того же класса.
|
|||
|
|
Обычно это дорогие или не имеющие состояния сервисы (LLM, модели эмбеддингов).
|
|||
|
|
Используйте переменную шаблона `{class}` для именования очереди.
|
|||
|
|
Параметры могут быть фиксированными значениями или параметризованы с использованием синтаксиса `{parameter-name}`.
|
|||
|
|
>>>>>>> 82edf2d (New md files from RunPod)
|
|||
|
|
Примеры: `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
|
|||
|
|
<<<<<<< HEAD
|
|||
|
|
Обеспечивает повторное использование общих определений параметров в различных потоках.
|
|||
|
|
=======
|
|||
|
|
Позволяет повторно использовать общие определения параметров в различных потоках.
|
|||
|
|
>>>>>>> 82edf2d (New md files from RunPod)
|
|||
|
|
Уменьшает дублирование схем параметров.
|
|||
|
|
|
|||
|
|
### 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`: Сервисы "отправь и забудь"
|
|||
|
|
<<<<<<< HEAD
|
|||
|
|
`request`: Запрос в сервисах "запрос/ответ"
|
|||
|
|
`response`: Ответ в сервисах "запрос/ответ"
|
|||
|
|
=======
|
|||
|
|
`request`: Запрос в сервисах "запрос-ответ"
|
|||
|
|
`response`: Ответ в сервисах "запрос-ответ"
|
|||
|
|
>>>>>>> 82edf2d (New md files from RunPod)
|
|||
|
|
**тема**: Конкретное имя очереди/темы с переменными шаблона
|
|||
|
|
|
|||
|
|
### Постоянные очереди
|
|||
|
|
Шаблон: `persistent://tg/flow/<topic>:{id}`
|
|||
|
|
Используется для сервисов "отправь и забудь" и потоков данных с гарантированной доставкой
|
|||
|
|
<<<<<<< HEAD
|
|||
|
|
Данные сохраняются в хранилище Pulsar после перезагрузок
|
|||
|
|
=======
|
|||
|
|
Данные сохраняются в хранилище Pulsar при перезапусках
|
|||
|
|
>>>>>>> 82edf2d (New md files from RunPod)
|
|||
|
|
Пример: `persistent://tg/flow/chunk-load:{id}`
|
|||
|
|
|
|||
|
|
### Непостоянные очереди
|
|||
|
|
Шаблон: `non-persistent://tg/request/<topic>:{class}` или `non-persistent://tg/response/<topic>:{class}`
|
|||
|
|
<<<<<<< HEAD
|
|||
|
|
Используется для шаблонов обмена сообщениями "запрос/ответ"
|
|||
|
|
=======
|
|||
|
|
Используется для шаблонов обмена сообщениями "запрос-ответ"
|
|||
|
|
>>>>>>> 82edf2d (New md files from RunPod)
|
|||
|
|
Непостоянные, не сохраняются на диск Pulsar
|
|||
|
|
Меньшая задержка, подходит для коммуникации в стиле RPC
|
|||
|
|
Пример: `non-persistent://tg/request/embeddings:{class}`
|
|||
|
|
|
|||
|
|
## Архитектура потока данных
|
|||
|
|
|
|||
|
|
Шаблон потока данных создает унифицированный поток, где:
|
|||
|
|
|
|||
|
|
1. **Конвейер обработки документов**: Поток от получения данных до преобразования и хранения
|
|||
|
|
2. **Сервисы запросов**: Интегрированные процессоры, которые запрашивают одни и те же хранилища данных и сервисы
|
|||
|
|
3. **Общие сервисы**: Централизованные процессоры, которые могут использоваться всеми потоками
|
|||
|
|
4. **Модули записи данных**: Сохраняют обработанные данные в соответствующие хранилища
|
|||
|
|
|
|||
|
|
Все процессоры (как `{id}`, так и `{class}`) работают вместе как единый граф потока данных, а не как отдельные системы.
|
|||
|
|
|
|||
|
|
<<<<<<< HEAD
|
|||
|
|
## Пример инстанцирования потока
|
|||
|
|
=======
|
|||
|
|
## Пример инстанциирования потока
|
|||
|
|
>>>>>>> 82edf2d (New md files from RunPod)
|
|||
|
|
|
|||
|
|
Дано:
|
|||
|
|
Идентификатор экземпляра потока: `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. **Унифицированная архитектура**: Запросы и обработка являются частью одного потока данных
|