# 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), только той же роли или без роли. В промпт попадает блок `` внутри самой задачи с часами, видом часов, проектом и сходством. Промпт требует: часы «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. Коды работ вместо свободных названий: тогда аналоги и калибровка опираются на одно и то же понятие задачи.