mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 16:36: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.
313 lines
16 KiB
Markdown
313 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. **Унифицированная архитектура**: Запросы и обработка являются частью одного потока данных
|