9.3 KiB
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).
Дальше
- Загрузить настоящие данные и проверить на них эмбеддинги выбранного провайдера: доля задач, для которых найден уместный аналог, и сравнение с офлайн-эмбеддером.
- Гибридный поиск и интерфейс загрузки корпуса.
- Коды работ вместо свободных названий: тогда аналоги и калибровка опираются на одно и то же понятие задачи.