Перейти к содержанию

ML-слой

Общая архитектура

ML Layer (backend/src/ml/)
│
├── core/                    # Базовая инфраструктура
│   ├── client.py            # OpenAI-клиент с retry и concurrency control
│   ├── memory.py            # In-memory история диалога
│   ├── progress.py          # Mixin отслеживания прогресса
│   └── rag/                 # RAG-пайплайн для ОКПД2
│       ├── hybrid_search.py # Гибридный поиск (embeddings + BM25)
│       └── bm25.py          # BM25-реализация (mmh3, tokenizers)
│
├── processors/              # Процессоры бизнес-операций
│   ├── chapters.py          # Генерация и обновление глав
│   ├── characteristics.py   # Генерация характеристик
│   └── editing.py           # Редактирование ячеек и таблиц
│
├── agents/                  # LangGraph-агенты
│   └── tz_agent.py          # Агент для работы с документом
│
├── okpd2/                   # Классификация по ОКПД2
│   └── service.py           # Сервис классификации
│
├── prompts/                 # Шаблоны промптов
│   ├── chapters/            # Промпты для генерации глав
│   ├── characteristics/     # Промпты для характеристик
│   ├── editing/             # Промпты для редактирования
│   └── extraction/          # Промпты для извлечения данных
│
└── ml_adapter.py            # Высокоуровневый фасад для domain layer

LLM-клиент (core/client.py)

Центральный компонент взаимодействия с OpenAI API.

Конфигурация:

Параметр Значение по умолчанию Описание
OPENAI_MODEL gpt-4.1 Основная модель
OPENAI_MODEL_SMALL gpt-4.1-mini Облегчённая модель
OPENAI_MODEL_TZ_AGENT gpt-5.1 Модель для чатового окна
OPENAI_MAX_CONCURRENCY 12 Максимум параллельных запросов
OPENAI_TIMEOUT 60 сек Таймаут одного запроса
Retry 5 попыток, factor=2 Экспоненциальный backoff

Методы:

Метод Назначение
call_with_schema(prompt, schema) Структурированный вывод: ответ парсится в Pydantic-модель
call_with_function(prompt, tools) Вызов функций (function calling)
call_with_web_search(query) Поиск в интернете с трейсингом через LangSmith

Fallback-стратегия: при недоступности основной модели система последовательно пробует: gpt-4.1-mini → gpt-5.1.

Процессоры

ChaptersProcessor (processors/chapters.py)

Отвечает за генерацию и обновление глав ТЗ.

Метод Описание
generate_chapter_description() Генерация содержимого главы по шаблону и контексту
generate_additional_chapters() Генерация опциональных глав (гарантии, упаковка и т.д.)
determine_affected_chapters() Определение глав, требующих пересчёта после изменений
regenerate_chapter_by_changes() Перегенерация главы с учётом внесённых изменений
search_all_normative_docs() Поиск нормативных документов (ГОСТ) с LLM-верификацией

Поиск нормативных документов:

  1. LLM генерирует список релевантных ГОСТ на основе контекста.
  2. Результаты верифицируются вторым LLM-вызовом (проверка существования, актуальности).
  3. Верифицированные документы включаются в главу.

CharacteristicsProcessor (processors/characteristics.py)

Генерация характеристик для товаров и услуг.

Метод Описание
generate_item_characteristics() Основные и дополнительные характеристики товаров
generate_service_characteristics() Характеристики услуг и работ

Процесс:

  1. Классификация товара/услуги по ОКПД2 (через Qdrant RAG).
  2. Генерация основных характеристик (LLM с учётом ОКПД2 и контекста).
  3. Генерация дополнительных характеристик (при наличии feature flag RANGE).

EditingProcessor (processors/editing.py)

Редактирование характеристик по пользовательским инструкциям.

Метод Описание
edit_cell() Редактирование одной характеристики с LLM-комментарием
edit_table() Модификация таблицы характеристик: добавление, удаление, обновление, переименование строк

Типы действий при редактировании таблицы:

Действие Описание
add Добавление новой характеристики
remove Удаление существующей характеристики
update Изменение значения характеристики
rename Переименование характеристики

RAG-пайплайн ОКПД2 (core/rag/)

Гибридный поиск для классификации товаров и услуг по ОКПД2.

Компоненты:

  1. Векторный поиск — эмбеддинги OpenAI (text-embedding-3-large), хранятся в Qdrant.
  2. BM25 — лексический поиск по терминам (mmh3 хэширование, tokenizers).
  3. Fusion — объединение результатов двух методов поиска.

Параметры:

Параметр Значение Описание
Score threshold 0.20 Минимальный порог релевантности
Prefetch multiplier 6x Множитель предварительной выборки
Коллекции okpd2 / okpd2_prod Dev / Production коллекции

TZAgent (agents/tz_agent.py)

AI-агент на базе LangGraph для интерактивной работы с документом.

Архитектура агента:

Пользовательское сообщение
        │
        ▼
┌─────────────────┐
│Intent Classifier│  ← определяет намерение пользователя
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Tool Selection  │  ← выбирает инструмент
└────────┬────────┘
         │
    ┌────┼────┬────────┬──────────┐
    ▼    ▼    ▼        ▼          ▼
chapter  char  basic   swap    text
_tool   _tool  _params _tool   response
                _tool

Доступные инструменты агента:

Инструмент Назначение
chapter_tool Добавление/изменение глав документа
char_tool Модификация характеристик
basic_params_tool Изменение базовых параметров (сроки, адреса, количество)
swap_tool Замена товара/услуги с перегенерацией характеристик

Промпты (prompts/)

Шаблонизированные промпты для всех ML-операций. Организованы по категориям:

  • chapters/ — системные промпты для генерации, обновления и анализа глав;
  • characteristics/ — промпты для генерации характеристик товаров и услуг;
  • editing/ — промпты для редактирования ячеек и таблиц;
  • extraction/ — промпты для извлечения структурированных данных из текста.

Feature flags в промптах:

Флаг Описание
RANGE Включает генерацию диапазонов значений (например, «от 2.0 до 3.2 GHz»)
GOSTS Включает поиск и добавление нормативных документов

Трейсинг и мониторинг ML

  • LangSmith — трейсинг всех LLM-вызовов через декоратор @traceable.
  • Метрики — латентность OpenAI-вызовов, количество ошибок, rate-limit hits.
  • Переменные: LANGSMITH_TRACING=true, LANGSMITH_API_KEY.