trustgraph/docs/tech-specs/flow-class-definition.ru.md

# Спецификация определения шаблона потока

## Обзор

Шаблон потока определяет полный шаблон структуры потока данных в системе 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. **Унифицированная архитектура**: Запросы и обработка являются частью одного потока данных