mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 08:26:21 +02:00
Feat: TrustGraph i18n & Documentation Translation Updates (#781)
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.
This commit is contained in:
Alex Jenkins
GitHub
parent
19f73e4cdc
commit
f95fd4f052
560 changed files with 236300 additions and 99 deletions
613
docs/tech-specs/flow-configurable-parameters.ru.md
Normal file
613
docs/tech-specs/flow-configurable-parameters.ru.md
Normal file
|
|
@ -0,0 +1,613 @@
|
|||
---
|
||||
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. Параметры позволяют пользователям настраивать параметры процессоров при запуске потока, предоставляя значения, которые заменяют заполнители параметров в определении шаблона потока.
|
||||
|
||||
Параметры работают путем подстановки переменных в шаблонах в параметрах процессоров, аналогично тому, как работают переменные `{id}` и `{class}`, но со значениями, предоставленными пользователем.
|
||||
|
||||
Интеграция поддерживает четыре основных сценария использования:
|
||||
|
||||
1. **Выбор модели**: Предоставление пользователям возможности выбора различных моделей LLM (например, `gemma3:8b`, `gpt-4`, `claude-3`) для процессоров.
|
||||
2. **Конфигурация ресурсов**: Настройка параметров процессоров, таких как размеры пакетов, размеры партий и лимиты параллельности.
|
||||
3. **Настройка поведения**: Изменение поведения процессоров с помощью параметров, таких как температура, максимальное количество токенов или пороги извлечения.
|
||||
4. **Параметры, специфичные для среды**: Настройка конечных точек, ключей API или URL-адресов, специфичных для региона, для каждого развертывания.
|
||||
|
||||
## Цели
|
||||
|
||||
**Динамическая конфигурация процессоров**: Обеспечение возможности динамической конфигурации параметров процессоров путем подстановки параметров.
|
||||
**Проверка параметров**: Предоставление проверки типов и валидации параметров при запуске потока.
|
||||
**Значения по умолчанию**: Поддержка разумных значений по умолчанию, позволяя при этом переопределять их для продвинутых пользователей.
|
||||
**Подстановка шаблонов**: Бесшовная замена заполнителей параметров в параметрах процессоров.
|
||||
**Интеграция с пользовательским интерфейсом**: Обеспечение ввода параметров как через API, так и через пользовательский интерфейс.
|
||||
**Безопасность типов**: Обеспечение соответствия типов параметров ожидаемым типам параметров процессора.
|
||||
**Документация**: Самодокументированные схемы параметров в определениях шаблонов потоков.
|
||||
**Обратная совместимость**: Поддержка обратной совместимости с существующими шаблонами потоков, которые не используют параметры.
|
||||
|
||||
## Предыстория
|
||||
|
||||
В шаблонах потоков в TrustGraph теперь поддерживаются параметры процессоров, которые могут содержать либо фиксированные значения, либо заполнители параметров. Это создает возможность для динамической настройки.
|
||||
|
||||
Текущие параметры процессоров поддерживают:
|
||||
Фиксированные значения: `"model": "gemma3:12b"`
|
||||
Заполнители параметров: `"model": "gemma3:{model-size}"`
|
||||
|
||||
Эта спецификация определяет, как параметры:
|
||||
Объявляются в определениях шаблонов потоков.
|
||||
Проверяются при запуске потоков.
|
||||
Подставляются в параметры процессоров.
|
||||
Предоставляются через API и пользовательский интерфейс.
|
||||
|
||||
Используя параметризованные параметры процессоров, TrustGraph может:
|
||||
Уменьшить дублирование шаблонов потоков, используя параметры для вариаций.
|
||||
Позволить пользователям настраивать поведение процессоров без изменения определений.
|
||||
Поддерживать конфигурации, специфичные для среды, с помощью значений параметров.
|
||||
Обеспечивать безопасность типов с помощью проверки схемы параметров.
|
||||
|
||||
## Технический дизайн
|
||||
|
||||
### Архитектура
|
||||
|
||||
Система конфигурируемых параметров требует следующих технических компонентов:
|
||||
|
||||
1. **Определение схемы параметров**
|
||||
Определения параметров на основе JSON-схемы в метаданных шаблона потока.
|
||||
Определения типов, включая типы string, number, boolean, enum и object.
|
||||
Правила валидации, включая минимальные/максимальные значения, шаблоны и обязательные поля.
|
||||
|
||||
Модуль: trustgraph-flow/trustgraph/flow/definition.py
|
||||
|
||||
<<<<<<< HEAD
|
||||
2. **Механизм разрешения параметров**
|
||||
Проверка параметров на соответствие схеме во время выполнения.
|
||||
Применение значений по умолчанию для не указанных параметров.
|
||||
Внедрение параметров в контекст выполнения потока.
|
||||
Преобразование типов и приведение типов при необходимости.
|
||||
=======
|
||||
2. **Движок разрешения параметров**
|
||||
Проверка параметров на соответствие схеме во время выполнения.
|
||||
Применение значений по умолчанию для не указанных параметров.
|
||||
Внедрение параметров в контекст выполнения потока.
|
||||
Приведение типов и преобразование при необходимости.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
Модуль: trustgraph-flow/trustgraph/flow/parameter_resolver.py
|
||||
|
||||
3. **Интеграция с хранилищем параметров**
|
||||
Получение определений параметров из хранилища схем/конфигураций.
|
||||
Кэширование часто используемых определений параметров.
|
||||
Проверка на соответствие централизованным схемам.
|
||||
|
||||
Модуль: trustgraph-flow/trustgraph/flow/parameter_store.py
|
||||
|
||||
4. **Расширения для запуска потоков**
|
||||
Расширения API для приема значений параметров при запуске потока.
|
||||
<<<<<<< HEAD
|
||||
Разрешение отображения (имена потоков на имена определений).
|
||||
=======
|
||||
Разрешение сопоставления параметров (имена потоков к именам определений).
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Обработка ошибок для недействительных комбинаций параметров.
|
||||
|
||||
Модуль: trustgraph-flow/trustgraph/flow/launcher.py
|
||||
|
||||
5. **Формы параметров пользовательского интерфейса**
|
||||
Динамическая генерация форм из метаданных параметров потока.
|
||||
<<<<<<< HEAD
|
||||
Отображение параметров в упорядоченном виде с использованием поля `order`.
|
||||
=======
|
||||
Отображение параметров в отсортированном порядке с использованием поля `order`.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Описательные метки параметров с использованием поля `description`.
|
||||
Проверка ввода в соответствии с определениями типов параметров.
|
||||
Предустановки и шаблоны параметров.
|
||||
|
||||
Модуль: trustgraph-ui/components/flow-parameters/
|
||||
|
||||
### Модели данных
|
||||
|
||||
#### Определения параметров (хранятся в схеме/конфигурации)
|
||||
|
||||
Определения параметров хранятся централизованно в системе схем и конфигураций с типом "parameter-type":
|
||||
|
||||
```json
|
||||
{
|
||||
"llm-model": {
|
||||
"type": "string",
|
||||
"description": "LLM model to use",
|
||||
"default": "gpt-4",
|
||||
"enum": [
|
||||
{
|
||||
"id": "gpt-4",
|
||||
"description": "OpenAI GPT-4 (Most Capable)"
|
||||
},
|
||||
{
|
||||
"id": "gpt-3.5-turbo",
|
||||
"description": "OpenAI GPT-3.5 Turbo (Fast & Efficient)"
|
||||
},
|
||||
{
|
||||
"id": "claude-3",
|
||||
"description": "Anthropic Claude 3 (Thoughtful & Safe)"
|
||||
},
|
||||
{
|
||||
"id": "gemma3:8b",
|
||||
"description": "Google Gemma 3 8B (Open Source)"
|
||||
}
|
||||
],
|
||||
"required": false
|
||||
},
|
||||
"model-size": {
|
||||
"type": "string",
|
||||
"description": "Model size variant",
|
||||
"default": "8b",
|
||||
"enum": ["2b", "8b", "12b", "70b"],
|
||||
"required": false
|
||||
},
|
||||
"temperature": {
|
||||
"type": "number",
|
||||
"description": "Model temperature for generation",
|
||||
"default": 0.7,
|
||||
"minimum": 0.0,
|
||||
"maximum": 2.0,
|
||||
"required": false
|
||||
},
|
||||
"chunk-size": {
|
||||
"type": "integer",
|
||||
"description": "Document chunk size",
|
||||
"default": 512,
|
||||
"minimum": 128,
|
||||
"maximum": 2048,
|
||||
"required": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Схема потока с ссылками на параметры
|
||||
|
||||
Схемы потока определяют метаданные параметров со ссылками на типы, описаниями и порядком:
|
||||
|
||||
```json
|
||||
{
|
||||
"flow_class": "document-analysis",
|
||||
"parameters": {
|
||||
"llm-model": {
|
||||
"type": "llm-model",
|
||||
"description": "Primary LLM model for text completion",
|
||||
"order": 1
|
||||
},
|
||||
"llm-rag-model": {
|
||||
"type": "llm-model",
|
||||
"description": "LLM model for RAG operations",
|
||||
"order": 2,
|
||||
"advanced": true,
|
||||
"controlled-by": "llm-model"
|
||||
},
|
||||
"llm-temperature": {
|
||||
"type": "temperature",
|
||||
"description": "Generation temperature for creativity control",
|
||||
"order": 3,
|
||||
"advanced": true
|
||||
},
|
||||
"chunk-size": {
|
||||
"type": "chunk-size",
|
||||
"description": "Document chunk size for processing",
|
||||
"order": 4,
|
||||
"advanced": true
|
||||
},
|
||||
"chunk-overlap": {
|
||||
"type": "integer",
|
||||
"description": "Overlap between document chunks",
|
||||
"order": 5,
|
||||
"advanced": true,
|
||||
"controlled-by": "chunk-size"
|
||||
}
|
||||
},
|
||||
"class": {
|
||||
"text-completion:{class}": {
|
||||
"request": "non-persistent://tg/request/text-completion:{class}",
|
||||
"response": "non-persistent://tg/response/text-completion:{class}",
|
||||
"parameters": {
|
||||
"model": "{llm-model}",
|
||||
"temperature": "{llm-temperature}"
|
||||
}
|
||||
},
|
||||
"rag-completion:{class}": {
|
||||
"request": "non-persistent://tg/request/rag-completion:{class}",
|
||||
"response": "non-persistent://tg/response/rag-completion:{class}",
|
||||
"parameters": {
|
||||
"model": "{llm-rag-model}",
|
||||
"temperature": "{llm-temperature}"
|
||||
}
|
||||
}
|
||||
},
|
||||
"flow": {
|
||||
"chunker:{id}": {
|
||||
"input": "persistent://tg/flow/chunk:{id}",
|
||||
"output": "persistent://tg/flow/chunk-load:{id}",
|
||||
"parameters": {
|
||||
"chunk_size": "{chunk-size}",
|
||||
"chunk_overlap": "{chunk-overlap}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Раздел `parameters` сопоставляет имена параметров, специфичные для потока (ключи), с объектами метаданных параметров, содержащими:
|
||||
<<<<<<< HEAD
|
||||
`type`: Ссылка на централизованно определенное определение параметра (например, "llm-model")
|
||||
`description`: Описание, понятное человеку, для отображения в пользовательском интерфейсе
|
||||
=======
|
||||
`type`: Ссылка на центрально определенное определение параметра (например, "llm-model")
|
||||
`description`: Описание, понятное для человека, для отображения в пользовательском интерфейсе
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
`order`: Порядок отображения параметров в формах (меньшие числа отображаются первыми)
|
||||
`advanced` (необязательно): Булевский флаг, указывающий, является ли этот параметр расширенным (по умолчанию: false). Если установлено значение true, пользовательский интерфейс может скрывать этот параметр по умолчанию или помещать его в раздел "Расширенные"
|
||||
`controlled-by` (необязательно): Имя другого параметра, который управляет значением этого параметра в простом режиме. Если указано, этот параметр наследует свое значение от управляющего параметра, если явно не переопределен
|
||||
|
||||
Этот подход позволяет:
|
||||
Повторное использование определений типов параметров в нескольких шаблонах потоков
|
||||
Централизованное управление и проверка типов параметров
|
||||
Описания и порядок параметров, специфичные для потока
|
||||
Улучшенный пользовательский интерфейс с описательными формами параметров
|
||||
Последовательная проверка параметров во всех потоках
|
||||
Легкое добавление новых стандартных типов параметров
|
||||
Упрощенный пользовательский интерфейс с разделением на режимы "базовый/расширенный"
|
||||
Наследование значений параметров для связанных настроек
|
||||
|
||||
#### Запрос запуска потока
|
||||
|
||||
API запуска потока принимает параметры, используя имена параметров, специфичные для потока:
|
||||
|
||||
```json
|
||||
{
|
||||
"flow_class": "document-analysis",
|
||||
"flow_id": "customer-A-flow",
|
||||
"parameters": {
|
||||
"llm-model": "claude-3",
|
||||
"llm-temperature": 0.5,
|
||||
"chunk-size": 1024
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
Примечание: В этом примере, `llm-rag-model` явно не указан, но он унаследует значение "claude-3" из `llm-model` из-за его `controlled-by` связи. Аналогично, `chunk-overlap` может унаследовать вычисленное значение на основе `chunk-size`.
|
||||
|
||||
Система будет:
|
||||
1. Извлекать метаданные параметров из определения схемы потока
|
||||
2. Сопоставлять имена параметров потока с их определениями типов (например, `llm-model` → `llm-model` тип)
|
||||
3. Разрешать отношения "контролируется" (например, `llm-rag-model` наследуется от `llm-model`)
|
||||
=======
|
||||
Примечание: В этом примере `llm-rag-model` явно не указано, но оно наследует значение "claude-3" из `llm-model` из-за своей `controlled-by` связи. Аналогично, `chunk-overlap` может наследовать вычисленное значение на основе `chunk-size`.
|
||||
|
||||
Система будет:
|
||||
1. Извлекать метаданные параметров из определения шаблона потока
|
||||
2. Сопоставлять имена параметров потока с их определениями типов (например, `llm-model` → тип `llm-model`)
|
||||
3. Разрешать зависимости (например, `llm-rag-model` наследует от `llm-model`)
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
4. Проверять предоставленные пользователем и унаследованные значения на соответствие определениям типов параметров
|
||||
5. Подставлять разрешенные значения в параметры процессоров во время создания экземпляра потока
|
||||
|
||||
### Детали реализации
|
||||
|
||||
#### Процесс разрешения параметров
|
||||
|
||||
При запуске потока система выполняет следующие шаги разрешения параметров:
|
||||
|
||||
<<<<<<< HEAD
|
||||
1. **Загрузка схемы потока**: Загрузить определение схемы потока и извлечь метаданные параметров
|
||||
2. **Извлечение метаданных**: Извлечь `type`, `description`, `order`, `advanced` и `controlled-by` для каждого параметра, определенного в разделе `parameters` схемы потока
|
||||
3. **Поиск определения типа**: Для каждого параметра в схеме потока:
|
||||
Получить определение типа параметра из хранилища схем/конфигураций, используя поле `type`
|
||||
Определения типов хранятся с типом "parameter-type" в системе конфигураций
|
||||
Каждое определение типа содержит схему параметра, значение по умолчанию и правила проверки
|
||||
4. **Разрешение значения по умолчанию**:
|
||||
Для каждого параметра, определенного в схеме потока:
|
||||
Проверить, предоставлено ли пользователем значение для этого параметра
|
||||
Если пользовательское значение не предоставлено, использовать значение `default` из определения типа параметра
|
||||
Создать полную карту параметров, содержащую как предоставленные пользователем, так и значения по умолчанию
|
||||
5. **Разрешение наследования параметров** (отношения "контролируется"):
|
||||
Для параметров с полем `controlled-by`, проверить, было ли предоставлено явное значение
|
||||
Если явное значение не предоставлено, унаследовать значение от контролируемого параметра
|
||||
Если контролируемый параметр также не имеет значения, использовать значение по умолчанию из определения типа
|
||||
Проверить отсутствие циклических зависимостей в отношениях `controlled-by`
|
||||
6. **Проверка**: Проверить полный набор параметров (предоставленные пользователем, значения по умолчанию и унаследованные) на соответствие определениям типов
|
||||
7. **Хранение**: Сохранить полный разрешенный набор параметров с экземпляром потока для обеспечения возможности аудита
|
||||
8. **Подстановка шаблонов**: Заменить заполнители параметров в параметрах процессоров разрешенными значениями
|
||||
9. **Создание экземпляров процессоров**: Создать процессоры с подставленными параметрами
|
||||
=======
|
||||
1. **Загрузка шаблона потока**: Загрузить определение шаблона потока и извлечь метаданные параметров
|
||||
2. **Извлечение метаданных**: Извлечь `type`, `description`, `order`, `advanced` и `controlled-by` для каждого параметра, определенного в разделе `parameters` шаблона потока
|
||||
3. **Поиск определения типа**: Для каждого параметра в шаблоне потока:
|
||||
Получить определение типа параметра из хранилища схемы/конфигурации, используя поле `type`
|
||||
Определения типов хранятся с типом "parameter-type" в системе конфигурации
|
||||
Каждое определение типа содержит схему параметра, значение по умолчанию и правила проверки
|
||||
4. **Разрешение значения по умолчанию**:
|
||||
Для каждого параметра, определенного в шаблоне потока:
|
||||
Проверить, предоставлено ли пользователем значение для этого параметра
|
||||
Если значение не предоставлено пользователем, использовать значение `default` из определения типа параметра
|
||||
Создать полную карту параметров, содержащую как предоставленные пользователем, так и значения по умолчанию
|
||||
5. **Разрешение наследования параметров** (зависимости):
|
||||
Для параметров с полем `controlled-by`, проверить, было ли предоставлено явное значение
|
||||
Если явное значение не предоставлено, унаследовать значение от управляющего параметра
|
||||
Если управляющий параметр также не имеет значения, использовать значение по умолчанию из определения типа
|
||||
Убедиться в отсутствии циклических зависимостей в отношениях `controlled-by`
|
||||
6. **Проверка**: Проверить полный набор параметров (предоставленные пользователем, значения по умолчанию и унаследованные) на соответствие определениям типов
|
||||
7. **Хранение**: Сохранить полный набор разрешенных параметров с экземпляром потока для обеспечения возможности аудита
|
||||
8. **Подстановка шаблонов**: Заменить заполнители параметров в параметрах процессоров разрешенными значениями
|
||||
9. **Создание процессоров**: Создать процессоры с подставленными параметрами
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**Важные замечания по реализации**:
|
||||
Сервис потока ДОЛЖЕН объединять параметры, предоставленные пользователем, со значениями по умолчанию из определений типов параметров
|
||||
Полный набор параметров (включая примененные значения по умолчанию) ДОЛЖЕН храниться с потоком для обеспечения отслеживаемости
|
||||
Разрешение параметров происходит при запуске потока, а не при создании экземпляра процессора
|
||||
Отсутствующие обязательные параметры без значений по умолчанию ДОЛЖНЫ приводить к сбою запуска потока с четким сообщением об ошибке
|
||||
|
||||
<<<<<<< HEAD
|
||||
#### Наследование параметров с помощью "контролируется"
|
||||
=======
|
||||
#### Наследование параметров с помощью controlled-by
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
Поле `controlled-by` обеспечивает наследование значений параметров, что особенно полезно для упрощения пользовательских интерфейсов, сохраняя при этом гибкость:
|
||||
|
||||
**Пример сценария**:
|
||||
<<<<<<< HEAD
|
||||
Параметр `llm-model` контролирует основную модель LLM
|
||||
Параметр `llm-rag-model` имеет значение `"controlled-by": "llm-model"`
|
||||
В простом режиме установка `llm-model` в "gpt-4" автоматически устанавливает `llm-rag-model` в "gpt-4"
|
||||
В расширенном режиме пользователи могут переопределить `llm-rag-model` другим значением
|
||||
|
||||
**Правила разрешения**:
|
||||
1. Если параметр имеет явно предоставленное значение, используйте это значение
|
||||
2. Если нет явного значения и `controlled-by` установлено, используйте значение контролируемого параметра
|
||||
3. Если контролируемый параметр не имеет значения, используйте значение по умолчанию из определения типа
|
||||
4. Циклические зависимости в отношениях `controlled-by` приводят к ошибке проверки
|
||||
|
||||
**Поведение пользовательского интерфейса**:
|
||||
В базовом/простом режиме: Параметры с `controlled-by` могут быть скрыты или показаны как доступные только для чтения со значением, полученным по наследству
|
||||
В расширенном режиме: Все параметры отображаются и могут быть настроены индивидуально
|
||||
При изменении контролируемого параметра зависимые параметры автоматически обновляются, если они не были явно переопределены
|
||||
=======
|
||||
Параметр `llm-model` управляет основной моделью LLM
|
||||
Параметр `llm-rag-model` имеет значение `"controlled-by": "llm-model"`
|
||||
В простом режиме установка `llm-model` в "gpt-4" автоматически устанавливает `llm-rag-model` в "gpt-4"
|
||||
В расширенном режиме пользователи могут перезаписать `llm-rag-model` другим значением
|
||||
|
||||
**Правила разрешения**:
|
||||
1. Если параметр имеет явно предоставленное значение, используйте это значение
|
||||
2. Если нет явного значения и `controlled-by` установлено, используйте значение управляющего параметра
|
||||
3. Если управляющий параметр не имеет значения, используйте значение по умолчанию из определения типа
|
||||
4. Циклические зависимости в отношениях `controlled-by` приводят к ошибке проверки
|
||||
|
||||
**Поведение пользовательского интерфейса**:
|
||||
В режимах "базовый/простой": Параметры с `controlled-by` могут быть скрыты или показаны как доступные только для чтения со унаследованным значением
|
||||
В расширенном режиме: Все параметры отображаются и могут быть настроены индивидуально
|
||||
При изменении управляющего параметра зависимые параметры автоматически обновляются, если они не перезаписаны
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
#### Интеграция с Pulsar
|
||||
|
||||
1. **Операция Start-Flow**
|
||||
<<<<<<< HEAD
|
||||
Операция start-flow в Pulsar должна принимать поле `parameters`, содержащее карту значений параметров
|
||||
Схема запроса start-flow в Pulsar должна быть обновлена для включения необязательного поля `parameters`
|
||||
=======
|
||||
Операция Pulsar start-flow должна принимать поле `parameters`, содержащее карту значений параметров
|
||||
Схема Pulsar для запроса start-flow должна быть обновлена для включения необязательного поля `parameters`
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Пример запроса:
|
||||
```json
|
||||
{
|
||||
"flow_class": "document-analysis",
|
||||
"flow_id": "customer-A-flow",
|
||||
"parameters": {
|
||||
"model": "claude-3",
|
||||
"size": "12b",
|
||||
"temp": 0.5,
|
||||
"chunk": 1024
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Операция Get-Flow**
|
||||
Схему Pulsar для ответа get-flow необходимо обновить, чтобы включить поле `parameters`.
|
||||
Это позволяет клиентам получать значения параметров, которые были использованы при запуске потока.
|
||||
Пример ответа:
|
||||
```json
|
||||
{
|
||||
"flow_id": "customer-A-flow",
|
||||
"flow_class": "document-analysis",
|
||||
"status": "running",
|
||||
"parameters": {
|
||||
"model": "claude-3",
|
||||
"size": "12b",
|
||||
"temp": 0.5,
|
||||
"chunk": 1024
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Реализация сервиса потоков
|
||||
|
||||
Сервис конфигурации потоков (`trustgraph-flow/trustgraph/config/service/flow.py`) требует следующих улучшений:
|
||||
|
||||
1. **Функция разрешения параметров**
|
||||
```python
|
||||
async def resolve_parameters(self, flow_class, user_params):
|
||||
"""
|
||||
Resolve parameters by merging user-provided values with defaults.
|
||||
|
||||
Args:
|
||||
flow_class: The flow blueprint definition dict
|
||||
user_params: User-provided parameters dict
|
||||
|
||||
Returns:
|
||||
Complete parameter dict with user values and defaults merged
|
||||
"""
|
||||
```
|
||||
|
||||
Эта функция должна:
|
||||
Извлекать метаданные параметров из раздела `parameters` схемы потока.
|
||||
Для каждого параметра получать определение его типа из хранилища конфигурации.
|
||||
<<<<<<< HEAD
|
||||
Применять значения по умолчанию для любых параметров, которые не предоставлены пользователем.
|
||||
=======
|
||||
Применять значения по умолчанию для любых параметров, не предоставленных пользователем.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Обрабатывать отношения наследования `controlled-by`.
|
||||
Возвращать полный набор параметров.
|
||||
|
||||
2. **Измененный метод `handle_start_flow`**
|
||||
Вызывать `resolve_parameters` после загрузки схемы потока.
|
||||
Использовать полный набор разрешенных параметров для подстановки в шаблоне.
|
||||
Сохранять полный набор параметров (а не только предоставленные пользователем) вместе с потоком.
|
||||
Проверять, что все необходимые параметры имеют значения.
|
||||
|
||||
3. **Получение типа параметра**
|
||||
Определения типов параметров хранятся в конфигурации с типом "parameter-type".
|
||||
Каждое определение типа содержит схему, значение по умолчанию и правила проверки.
|
||||
Кэшировать часто используемые типы параметров для уменьшения количества обращений к конфигурации.
|
||||
|
||||
#### Интеграция с системой конфигурации
|
||||
|
||||
3. **Хранение объектов потока**
|
||||
Когда поток добавляется в систему конфигурации компонентом потока в менеджере конфигурации, объект потока должен включать разрешенные значения параметров.
|
||||
Менеджер конфигурации должен хранить как исходные параметры, предоставленные пользователем, так и разрешенные значения (с применением значений по умолчанию).
|
||||
Объекты потока в системе конфигурации должны включать:
|
||||
<<<<<<< HEAD
|
||||
`parameters`: Конечные разрешенные значения параметров, используемые для потока.
|
||||
=======
|
||||
`parameters`: Окончательные разрешенные значения параметров, используемые для потока.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
#### Интеграция с CLI
|
||||
|
||||
4. **Команды CLI для библиотеки**
|
||||
Команды CLI, которые запускают потоки, должны поддерживать параметры:
|
||||
Принимать значения параметров через флаги командной строки или файлы конфигурации.
|
||||
Проверять параметры на соответствие определениям схемы потока перед отправкой.
|
||||
Поддерживать ввод файлов параметров (JSON/YAML) для сложных наборов параметров.
|
||||
|
||||
Команды CLI, которые отображают потоки, должны отображать информацию о параметрах:
|
||||
Отображать значения параметров, использованные при запуске потока.
|
||||
Отображать доступные параметры для схемы потока.
|
||||
Отображать схемы проверки параметров и значения по умолчанию.
|
||||
|
||||
#### Интеграция с базовым классом процессора
|
||||
|
||||
5. **Поддержка ParameterSpec**
|
||||
Базовые классы процессоров должны поддерживать подстановку параметров с помощью существующего механизма ParametersSpec.
|
||||
Класс ParametersSpec (расположенный в том же модуле, что и ConsumerSpec и ProducerSpec) должен быть расширен, если это необходимо, для поддержки подстановки параметров в шаблонах.
|
||||
Процессоры должны иметь возможность вызывать ParametersSpec для настройки своих параметров со значениями параметров, разрешенными во время запуска потока.
|
||||
Реализация ParametersSpec должна:
|
||||
Принимать конфигурации параметров, содержащие заполнители параметров (например, `{model}`, `{temperature}`).
|
||||
Поддерживать подстановку параметров во время выполнения при создании экземпляра процессора.
|
||||
<<<<<<< HEAD
|
||||
Проверять, соответствуют ли подставленные значения ожидаемым типам и ограничениям.
|
||||
=======
|
||||
Проверять, что подставленные значения соответствуют ожидаемым типам и ограничениям.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Предоставлять обработку ошибок для отсутствующих или недействительных ссылок на параметры.
|
||||
|
||||
#### Правила подстановки
|
||||
|
||||
Параметры используют формат `{parameter-name}` в параметрах процессора.
|
||||
Имена параметров в параметрах соответствуют ключам в разделе `parameters` схемы потока.
|
||||
Подстановка происходит наряду с заменой `{id}` и `{class}`.
|
||||
Недействительные ссылки на параметры приводят к ошибкам во время запуска.
|
||||
Проверка типов происходит на основе централизованно хранящегося определения параметра.
|
||||
**ВАЖНО**: Все значения параметров хранятся и передаются в виде строк.
|
||||
Числа преобразуются в строки (например, `0.7` становится `"0.7"`).
|
||||
Булевы значения преобразуются в строчные буквы (например, `true` становится `"true"`).
|
||||
Это требуется схемой Pulsar, которая определяет `parameters = Map(String())`.
|
||||
|
||||
Пример разрешения:
|
||||
```
|
||||
Flow parameter mapping: "model": "llm-model"
|
||||
Processor parameter: "model": "{model}"
|
||||
User provides: "model": "gemma3:8b"
|
||||
Final parameter: "model": "gemma3:8b"
|
||||
|
||||
Example with type conversion:
|
||||
Parameter type default: 0.7 (number)
|
||||
Stored in flow: "0.7" (string)
|
||||
Substituted in processor: "0.7" (string)
|
||||
```
|
||||
|
||||
## Стратегия тестирования
|
||||
|
||||
Юнит-тесты для проверки схемы параметров
|
||||
Интеграционные тесты для проверки подстановки параметров в параметры процессора
|
||||
Комплексные тесты для запуска потоков с разными значениями параметров
|
||||
UI-тесты для генерации и проверки форм параметров
|
||||
Тесты производительности для потоков со многими параметрами
|
||||
<<<<<<< HEAD
|
||||
Пограничные случаи: отсутствующие параметры, неверные типы, неопределенные ссылки на параметры
|
||||
=======
|
||||
Краевые случаи: отсутствующие параметры, неверные типы, неопределенные ссылки на параметры
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## План миграции
|
||||
|
||||
1. Система должна продолжать поддерживать шаблоны потоков без объявленных параметров.
|
||||
2. Система должна продолжать поддерживать потоки без указанных параметров:
|
||||
<<<<<<< HEAD
|
||||
Это работает для потоков без параметров и для потоков с параметрами (у которых есть значения по умолчанию).
|
||||
|
||||
(имеют значения по умолчанию).
|
||||
|
||||
## Открытые вопросы
|
||||
|
||||
В: Должны ли параметры поддерживать сложные вложенные объекты или ограничиваться простыми типами?
|
||||
О: Значения параметров будут закодированы в виде строки, поэтому, вероятно, нам стоит
|
||||
ограничиваться строками.
|
||||
|
||||
В: Должны ли быть разрешены заполнители параметров в именах очередей или только в
|
||||
параметрах?
|
||||
О: Только в параметрах, чтобы избежать странных инъекций и пограничных случаев.
|
||||
=======
|
||||
Это работает для потоков без параметров и для потоков с параметрами
|
||||
(у них есть значения по умолчанию).
|
||||
|
||||
## Открытые вопросы
|
||||
|
||||
|
||||
В: Должны ли параметры поддерживать сложные вложенные объекты или ограничиваться простыми типами?
|
||||
О: Значения параметров будут закодированы в виде строки, поэтому, вероятно, нам стоит
|
||||
придерживаться строк.
|
||||
|
||||
В: Должны ли быть разрешены заполнители параметров в именах очередей или только в
|
||||
параметрах?
|
||||
О: Только в параметрах, чтобы избежать странных внедрений и пограничных случаев.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
В: Как обрабатывать конфликты между именами параметров и системными переменными, такими как
|
||||
`id` и `class`?
|
||||
О: Недопустимо указывать id и class при запуске потока.
|
||||
|
||||
В: Должны ли мы поддерживать вычисляемые параметры (выводимые из других параметров)?
|
||||
<<<<<<< HEAD
|
||||
О: Только простая подстановка строк, чтобы избежать странных инъекций и пограничных случаев.
|
||||
=======
|
||||
О: Только простая замена строк, чтобы избежать странных внедрений и пограничных случаев.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## Ссылки
|
||||
|
||||
Спецификация JSON Schema: https://json-schema.org/
|
||||
<<<<<<< HEAD
|
||||
Спецификация определения шаблона потока: docs/tech-specs/flow-class-definition.md
|
||||
=======
|
||||
Спецификация определения схемы потока: docs/tech-specs/flow-class-definition.md
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Loading…
Add table
Add a link
Reference in a new issue