Files

2026-06-08 14:14:38 +03:00

16 KiB

Raw Blame History

Спецификация: Сервис LLM-перевода табличных данных

Дата: 2026-05-18 (актуализация: 2026-06-07)
Назначение: Передача сторонней команде для оценки трудозатрат
Фокус: только требования к конечному результату, без технологий
Статус: Implemented ✅ (~153 файла, ~36 091 строка кода)

1. Фронтенд (Web-интерфейс)

1.1 Управление задачами перевода (Jobs)

Список всех задач перевода с фильтрацией по датасорсу, целевой таблице, статусу.
Создание новой задачи перевода:
- Выбор Superset-датасорса (источник данных).
- Выбор колонки для перевода (одна, обязательная).
- Выбор колонок контекста (ноль или более) — их значения передаются LLM для повышения качества.
- Выбор ключевых колонок (одна или более, composite key) — по ним данные будут сопоставляться при вставке в целевую таблицу.
- Указание целевой таблицы и целевой колонки.
- Выбор одного или нескольких языков перевода.
- Редактирование системного промпта (шаблон сообщения LLM).
- Выбор LLM-провайдера и модели.
- Прикрепление одного или нескольких справочников терминов.
- Указание стратегии UPSERT (skip_existing / overwrite / insert).
Редактирование, копирование, удаление задачи.

1.2 Превью (Quality Gate)

Запуск превью на ограниченной выборке строк (1–100, по умолчанию 10).
Отображение source-строк, контекста, обнаруженного языка оригинала и перевода на каждый целевой язык — рядом, в табличном виде.
Approve / Edit / Reject для каждой строки превью.
Повторный запуск превью с изменёнными настройками (промпт, язык, провайдер).
Подтверждение превью (accept) — открывает возможность полного прогона.
Предупреждение о стоимости перед запуском полного прогона (оценка токенов и цены).

1.3 Выполнение (Run)

Запуск полного прогона (только после accepted превью).
Живой индикатор прогресса: сколько строк обработано, успешно, с ошибками, процент выполнения.
Возможность отмены прогона.
Построчный просмотр результатов после завершения:
- Исходный текст, контекст, перевод по каждому языку.
- Статус каждой строки (OK / ошибка / пропущена).
- Сгенерированный SQL (для аудита).
- Статус вставки в Superset.
Повтор проблемных batch-ей (retry failed).
Inline-редактирование любой переведённой строки в результатах.
Bulk Find & Replace по результатам прогона (с превью замен).

1.4 Очередь и планировщик

Возможность настроить расписание для задачи:
- Одноразовый запуск в будущем.
- Интервальный (каждые N минут/часов/дней).
- Cron-выражение с выбором часового пояса.
Scheduled-прогон создаёт новый Run и выполняет полный цикл.
Для scheduled-прогонов: new-key-only (только новые строки, которых нет в последнем успешном прогоне).
Если последний успешный прогон старше 90 дней — fallback на полный прогон.
Защита от overlap: если предыдущий scheduled-прогон ещё выполняется — пропуск или очередь (1 в очереди).
После N последовательных ошибок (по умолч. 3) — автоотключение расписания и уведомление.

1.5 История и аудит

Список всех прогонов с деталями: датасорс, целевая таблица, кол-во строк, статус, кто запустил.
Детальный просмотр прогона: configuration snapshot, промпт, результаты по строкам, сгенерированный SQL, Superset execution reference.
Фильтрация по датасорсу, целевой таблице, дате, статусу.

1.6 Справочники терминов (Dictionaries)

Создание справочника.
Добавление пар «термин оригинала → перевод» с указанием языка оригинала и языка перевода.
Импорт из CSV/TSV с превью, разрешением конфликтов (overwrite / keep / skip).
Inline-редактирование, удаление записей.
Прикрепление справочника к задаче перевода.
Приоритет справочников (низкий номер = выше приоритет).

1.7 Коррекция и обратная связь

Из любого завершённого прогона: клик на ячейку перевода → inline-редактирование.
После редактирования: кнопка «Отправить в справочник».
Popup с предзаполненными: исходный термин, старый перевод, новый перевод, язык оригинала (из строки), язык перевода (из колонки), context_data (из строк, автоматически), usage notes (вручную).
Выбор целевого справочника (фильтр по языковой паре).
Bulk-режим: массовое редактирование и отправка нескольких терминов за раз.
Конфликт при повторной отправке: overwrite / keep existing / cancel.

2. Оркестратор (Run Lifecycle)

2.1 Жизненный цикл прогона

Создание: формируется snapshot конфигурации задачи + snapshot прикреплённых справочников.
Планирование: определяются целевые языки, размер batch-ей (динамически, по token budget), порядок обработки.
Выполнение:
- Выборка source-строк: для scheduled new-key-only — только новые ключи; для manual — все строки.
- Разбивка на batch-и.
- Для каждого batch: a. Запрос к LLM с промптом, контекстом, отфильтрованными записями справочников. b. Парсинг структурированного JSON-ответа. c. Валидация: все ли строки batch переведены, нет ли дубликатов. d. Если ошибка — запись в TranslationBatch как failed.
- После всех batch-ей: финализация (статус, error_message если все строки упали).
Вставка (Insert phase):
- Генерация UPSERT SQL под диалект БД (определяется динамически из Superset connection).
- Отправка SQL через Superset SQL Lab API.
- Polling статуса выполнения.
- Запись результата (query reference, статус, ошибка).
Завершение: запись метрик, отправка уведомления (опционально), авто-dismiss через N секунд на UI.

2.2 Snapshot isolation

Все прогоны используют snapshot конфигурации и справочников, взятый на момент старта.
Изменения конфигурации во время выполнения прогона НЕ влияют на текущий прогон.

2.3 Retry

Возможность повторно запустить только failed batch-и (не трогая успешные).
При перезапуске можно сменить LLM-провайдера.

2.4 Data retention

90 дней — полная детализация (source-строки, переводы, SQL).
После 90 дней — агрегация: только метаданные прогона и агрегированные метрики.
Перед прунингом — сохранение cumulative snapshot метрик.

3. Перевод (LLM)

3.1 Multi-language

Задача поддерживает N целевых языков (массив, а не один язык).
LLM получает исходный текст один раз на batch и возвращает переводы для ВСЕХ целевых языков в одном JSON-ответе.
Не нужно N отдельных LLM-вызовов.

3.2 Автоопределение языка оригинала

LLM определяет язык каждой строки автоматически.
Возвращает BCP-47 tag (например, "fr", "de", "und" для неопределённого).
Пользователь НЕ указывает язык оригинала вручную.

3.3 Reference copy

Если язык оригинала включён в список целевых языков — «переводом» для него будет исходный текст (verification copy).

3.4 Dictionary injection

Перед каждым LLM-запросом выполняется per-batch фильтрация справочника:
- Отбираются только те записи, чей source_term встречается (case-insensitive substring match) хотя бы в одной строке batch-а.
- Учитывается языковая пара (source_language записи === detected_language строки, target_language записи === языка промпта).
Отфильтрованные записи вставляются в промпт как authoritative glossary.
Записи с совпадающим контекстом (context_data) помечаются priority.

3.4 Превью

Quality gate, а не построчное утверждение.
Принятие превью = одобрение настроек (промпт, языки, справочники), после чего полный прогон обрабатывает ВСЕ строки.
Редактуры на уровне превью переносятся в полный прогон для тех же строк (carry-forward).
Rejected строки превью исключаются из полного прогона (только если были в sample).

4. Справочники (Dictionaries)

4.1 Структура

Справочник содержит пары «термин оригинала → перевод».
Каждая запись имеет:
- source_term — термин на языке оригинала.
- target_translation — корректный перевод.
- source_language (BCP-47) — язык термина.
- target_language (BCP-47) — язык перевода.
- context_data (JSON, опционально) — значения контекстных колонок из строки, где был найден термин.
- usage_notes (текст, опционально) — заметки по использованию.
- has_context (boolean) — есть ли контекстные данные.

4.2 Привязка к задаче

К задаче можно привязать несколько справочников.
Порядок приоритета: чем меньше номер, тем выше приоритет.
При конфликте (один source_term в нескольких справочниках) побеждает высший приоритет.

4.3 Per-batch фильтрация

В каждый LLM-запрос включаются ТОЛЬКО те записи справочника, чей source_term:
- Встречается хотя бы в одной строке batch-а (substring match).
- source_language совпадает с detected_language строки.
- target_language совпадает с языком текущего промпта.
Размер справочника не ограничен (фильтрация не даёт промпту расти бесконечно).

4.4 Контекстная приоритизация

Если context_data записи совпадает с контекстом строки batch-а (Jaccard similarity > 50%) — запись помечается как priority_context.
Priority-записи перечисляются первыми с пометкой # PRIORITY.
Это soft signal для LLM, не хард-фильтр.

4.5 Коррекция через результаты прогонов

Из любого завершённого прогона можно отправить исправление в справочник.
context_data заполняется автоматически из строки, где был найден термин.
Пользователь может отредактировать context_data, добавить usage_notes, убрать контекст.
Если context_data превышает 500 токенов — обрезается с пометкой.

5. Обработка ошибок (Edge Cases)

NULL в колонке перевода → пропуск строки с логированием.
NULL в ключевой колонке → reject строки (не может быть вставлена).
LLM вернул неожиданный формат → запрос структурированного JSON, валидация, failed batch.
Все строки batch упали → run.error_message с деталями.
Редактирование задачи во время выполнения прогона → не влияет на текущий прогон (snapshot isolation).
Удаление справочника, привязанного к активной задаче → запрет, предупреждение.
Scheduled прогон при недоступном датасорсе → запись ошибки, попытка следующего триггера.
Неподдерживаемый диалект БД → блокировка выполнения с сообщением.
Вставка через Superset SQL Lab вернула ошибку → insert_status = failed, error_message заполнен.

16 KiB Raw Blame History Unescape Escape