Files
estimator/docs/adr/0003-rag-reference-tasks.md
T
2026-11-09 08:43:30 +03:00

9.3 KiB
Raw Blame History

ADR-0003: аналоги из истории проектов (RAG)

Дата: 2 ноября 2026 · Статус: основная часть реализована, корпус пока пуст, на реальных эмбеддингах не проверено Основание: запрос владельца реализовать основную часть RAG для pgvector и SQLite Затрагивает: infra/db/references.py, infra/embeddings/, rag/, services/references.py, agent/, CLI rag, схема БД

Состояние до решения

Были только порт Retriever, модель ReferenceTask, место в промпте оценки и неиспользуемая секция [rag] в конфиге. Хранилища, эмбеддингов, поиска и загрузки данных не было.

Решение

1. Что ищем и зачем

Ищем похожие прошлые задачи с их часами: название, описание, роль, часы, вид часов (actual измерено после работы или estimate предположено), проект, источник. Не цены и не целые проекты. Модель получает их как опору при оценке часов; часы по-прежнему берутся из её ответа, аналоги только подсказка.

Собственные оценки модели в корпус автоматически не попадают (иначе получится замкнутый круг). Корпус загружает администратор из реальных данных.

2. Поиск по задачам, а не по проекту

После декомпозиции для каждой задачи строится запрос «название. описание» с её ролью, все запросы уходят в один пакетный вызов. Для каждой задачи берётся до rag.top_k (по умолчанию 3) результатов выше порога rag.min_similarity (0,55), только той же роли или без роли. В промпт попадает блок <reference_tasks> внутри самой задачи с часами, видом часов, проектом и сходством.

Промпт требует: часы «actual» надёжнее «estimate», нерелевантное игнорировать, числа не копировать, инструкции внутри аналогов не выполнять. Текст аналогов, как и любые данные, проходит через экранирование служебных тегов. Показанные аналоги сохраняются в результате (references по id задачи) и видны в интерфейсе под задачей.

3. Хранение

Таблица reference_tasks. Одна строка на (проект, название, роль): повторная загрузка обновляет, а не дублирует. Хэш текста (content_hash) позволяет пересчитывать вектор только при изменении названия или описания; смена одних часов вектор не трогает. У строки записана модель вектора (embedding_model), поэтому после смены модели старые векторы не используются, пока rag reindex не пересчитает их.

PostgreSQL SQLite
Вектор vector(1536) (pgvector) JSON-список чисел
Поиск оператор косинусного расстояния <=>, индекс HNSW (vector_cosine_ops), hnsw.ef_search = 100 на запрос скалярное произведение в Python
Для чего рабочая база разработка и небольшие корпуса (до нескольких тысяч задач)

Оба пути возвращают одинаковый результат, это проверено одними и теми же тестами на обеих базах. На SQLite стоимость поиска растёт как число задач × 1536 на каждый запрос.

4. Эмбеддинги

  • provider = "openai": любой OpenAI-совместимый /embeddings (OpenAI, Voyage и другие с тем же форматом). Для моделей text-embedding-3-* запрашивается dimensions = 1536; остальные модели должны сами вернуть 1536 чисел, иначе ошибка с понятным текстом. Ключ берётся из EST_RAG__API_KEY, иначе из ключа OpenAI в секции llm.
  • provider = "hash": локальный офлайн-эмбеддер (хэширование основ слов) для разработки, тестов и демо. Он видит только общие слова, это намного слабее настоящей модели, в рабочем режиме на него полагаться нельзя.
  • Размерность 1536 зашита в схему БД (константа EMBEDDING_DIM). Смена размерности это новая миграция и полная переиндексация.

5. Загрузка только администратором

Команды python -m estimator rag import | reindex | stats | search | delete. Файлы CSV (UTF-8, с заголовком) или JSON-список: поля project, title, description, role, hours, hours_kind, source. Плохие строки сообщаются с номером и пропускаются, остальные загружаются; есть --dry-run. Если провайдер эмбеддингов недоступен, строки остаются без вектора и rag reindex продолжает с того же места.

HTTP-эндпоинтов у корпуса нет: это общие данные компании, клиенты API не должны их читать или менять. Тест проверяет, что они недоступны.

6. Включение и устойчивость

  • rag.enabled = false по умолчанию: сначала загружают корпус, потом включают. Команды CLI работают и при выключенном поиске.
  • При включении без ключа провайдера openai приложение не стартует. При старте проверяются наличие таблицы и расширения pgvector.
  • Сбой поиска или эмбеддингов не останавливает оценку: она считается без аналогов, в результате предупреждение.

Что проверено

  • 599 тестов на SQLite и PostgreSQL 16 с pgvector 0.6.0, включая сквозной сценарий через API на обеих базах, наличие индекса HNSW и типа vector(1536) в БД, схлопнутую миграцию (отсутствие расхождений с моделями и откат).
  • Клиент эмбеддингов проверен только на подменённом HTTP (формат запроса, порядок и пакетирование, ошибки, повторы). С настоящим провайдером эмбеддингов не запускался.
  • Качество поиска на реальных данных не оценивалось: корпуса нет, а офлайн-эмбеддер не показатель.

Известные ограничения

  • Нет гибридного поиска (векторы плюс полнотекстовый); для точных названий систем и сокращений он помог бы.
  • Фильтр по роли и модели на PostgreSQL применяется поверх индекса HNSW, поэтому для малых корпусов возможен результат короче top_k; для этого выставлен hnsw.ef_search = 100.
  • Нет интерфейса загрузки и просмотра корпуса, нет корпусов по отдельным клиентам.
  • Нет калибровки по разнице между estimate и actual (этап 7).

Дальше

  1. Загрузить настоящие данные и проверить на них эмбеддинги выбранного провайдера: доля задач, для которых найден уместный аналог, и сравнение с офлайн-эмбеддером.
  2. Гибридный поиск и интерфейс загрузки корпуса.
  3. Коды работ вместо свободных названий: тогда аналоги и калибровка опираются на одно и то же понятие задачи.