Add RAG basic implementation
This commit is contained in:
@@ -9,3 +9,6 @@ Market figures in (3) are starting priors from public, mostly marketing, sources
|
||||
5. [estimator-architecture-review-v2-response.md](estimator-architecture-review-v2-response.md): разбор этого ревью: что принимаем, что корректируем, что откладываем, порядок работ и два открытых вопроса
|
||||
6. [adr/0001-reserve-policy-and-engagement.md](adr/0001-reserve-policy-and-engagement.md): решение по резерву, наценке, модели оплаты (фикс или T&M) и снимку вводных, с числами и чувствительностью
|
||||
7. [adr/0002-vat-layer.md](adr/0002-vat-layer.md): НДС как слой показа поверх цен без НДС, ставки по умолчанию для РФ и ЕС, приведение ориентиров рынка, что проверено и что открыто
|
||||
8. [adr/0003-rag-reference-tasks.md](adr/0003-rag-reference-tasks.md): аналоги из истории проектов (RAG): поиск по задачам, pgvector и SQLite, эмбеддинги, загрузка через CLI, проверено и не проверено
|
||||
9. [deployment.md](deployment.md): развёртывание в Docker: порядок запуска и миграции, обновление, резервные копии, администрирование, обратный прокси, что проверено и что нет
|
||||
|
||||
|
||||
@@ -111,7 +111,7 @@
|
||||
## Последствия
|
||||
|
||||
- **Ломающее изменение API:** поля `price.cost` и `price.cost_confident` заменены на `cost_expected`, `cost_with_reserve`, `reserve_cost` и другие; добавлены `engagement`, `result.quote`, `price.inputs`. Старых развёртываний нет, поэтому миграция данных не писалась: результаты, сохранённые прежней версией, новый код не прочитает.
|
||||
- **Миграция `0002_engagement`** добавляет колонку `estimate_versions.engagement` (по умолчанию `fixed_price`).
|
||||
- **Миграция `0002_engagement`** добавляет колонку `estimate_versions.engagement` (по умолчанию `fixed_price`). Позже, до первой установки, миграция схлопнута в `0001_initial` (см. раздел 13.9 архитектуры).
|
||||
- В каждой версии теперь хранится снимок вводных, версия растёт на несколько килобайт JSON.
|
||||
- Интерфейс: поле «Как продаём» в форме, переключатель модели на странице оценки, ставки клиента в таблице по ролям, модель рядом с суммой в истории.
|
||||
|
||||
|
||||
@@ -55,7 +55,7 @@
|
||||
|
||||
## Последствия
|
||||
|
||||
- Миграция `0003_vat_rate` добавляет колонку `estimate_versions.vat_rate` (по умолчанию 0).
|
||||
- Миграция `0003_vat_rate` добавляет колонку `estimate_versions.vat_rate` (по умолчанию 0). Позже, до первой установки, миграция схлопнута в `0001_initial` (см. раздел 13.9 архитектуры).
|
||||
- В ответе API: `vat_rate` у оценки, `quote.vat_rate`, `quote.amount_gross`, `quote.cap_gross`; в бенчмарке `includes_vat`, `vat_rate`; в сверке `normalized_from_gross`.
|
||||
- В справочнике рынка у ориентиров `includes_vat = false` с пометкой: источники не уточняют, считаем без НДС. **Это допущение нужно проверить**, пока оно не подтверждено.
|
||||
- В интерфейсе: поле «НДС» в форме, строка «К оплате с НДС», переключатель ставки на странице оценки, пояснение в карточке сверки.
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
# 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. Коды работ вместо свободных названий: тогда аналоги и калибровка опираются на одно и то же понятие задачи.
|
||||
@@ -0,0 +1,92 @@
|
||||
# Развёртывание в Docker
|
||||
|
||||
**Дата:** 2 ноября 2026 · **Статус:** файлы написаны и проверены имитацией; сборка образа и `docker compose up` в среде разработки не запускались (там нет Docker)
|
||||
|
||||
## Что входит
|
||||
|
||||
| Файл | Назначение |
|
||||
|---|---|
|
||||
| `Dockerfile` | Образ сервиса: двухэтапная сборка на `python:3.12-slim`, запуск не от root (пользователь `app`, uid 10001), проверка здоровья `/health` |
|
||||
| `docker/entrypoint.sh` | Точка входа: `serve` (по умолчанию), `migrate`, любая другая команда передаётся в `python -m estimator` |
|
||||
| `docker-compose.yml` | Три сервиса: `db` (PostgreSQL 16 с pgvector), `migrate` (разовое задание), `app` (сервис) |
|
||||
| `.dockerignore` | Не пускает в образ `.env`, тесты, документацию, `.git` |
|
||||
| `.env.example` | Шаблон `.env`: настройки сервиса, переменные compose, веб-интерфейс, обратный прокси |
|
||||
|
||||
## Порядок запуска и миграции
|
||||
|
||||
```
|
||||
db становится healthy ─► migrate применяет схему и завершается успешно ─► app запускается
|
||||
```
|
||||
|
||||
- `migrate` ждёт базу (`wait-db`, до 60 секунд), выполняет `alembic upgrade head` и выходит. `app` стартует только при коде возврата 0 (`service_completed_successfully`): **если миграция не прошла, сервис не запускается**.
|
||||
- Миграции вынесены в отдельное задание, а не в запуск самого сервиса: при нескольких копиях сервиса они не будут применяться одновременно.
|
||||
- Миграция повторяема: повторный запуск ничего не меняет. Она создаёт расширение `vector` (поэтому образ базы `pgvector/pgvector:pg16`, а пользователь базы должен быть суперпользователем, как в compose).
|
||||
- Для одного контейнера без compose есть `MIGRATE_ON_START=true`: тогда `serve` сначала ждёт базу и применяет миграции, при сбое любого шага сервис не стартует.
|
||||
- Проверка готовности базы в compose идёт по TCP (`pg_isready -h 127.0.0.1`): временный сервер первого запуска слушает только сокет, и проверка по сокету могла бы объявить базу готовой раньше времени.
|
||||
|
||||
## Запуск
|
||||
|
||||
```bash
|
||||
cp .env.example .env # POSTGRES_PASSWORD, ключ(и) LLM, EST_API__KEYS
|
||||
docker compose up -d --build
|
||||
docker compose logs -f migrate app
|
||||
curl http://localhost:8000/health
|
||||
```
|
||||
|
||||
`POSTGRES_PASSWORD` обязателен: без него compose отказывается стартовать. Пароль должен состоять из букв и цифр, он входит в строку подключения.
|
||||
|
||||
## Обновление
|
||||
|
||||
```bash
|
||||
git pull && docker compose up -d --build # migrate выполнится перед запуском новой версии сервиса
|
||||
```
|
||||
|
||||
Откат схемы не автоматический: перед обновлением делайте копию базы.
|
||||
|
||||
## Резервная копия и восстановление
|
||||
|
||||
```bash
|
||||
docker compose exec db pg_dump -U estimator -Fc estimator > estimator.dump
|
||||
docker compose exec -T db pg_restore -U estimator -d estimator --clean < estimator.dump
|
||||
```
|
||||
|
||||
## Администрирование
|
||||
|
||||
```bash
|
||||
# пароль для пользователя веб-интерфейса (запрашивается дважды, не короче 12 символов)
|
||||
docker compose run --rm app hash-password
|
||||
|
||||
# загрузка корпуса аналогов (файл монтируется в контейнер)
|
||||
docker compose run --rm -v "$PWD/refs.csv:/data/refs.csv:ro" app rag import /data/refs.csv --project "Проект"
|
||||
docker compose run --rm app rag stats
|
||||
```
|
||||
|
||||
Хэш пароля содержит знаки `$`. В `.env` значение `EST_WEB__USERS` берите в одинарные кавычки, иначе compose попытается их раскрыть.
|
||||
|
||||
## За обратным прокси и HTTPS
|
||||
|
||||
- Включите `EST_API__PROXY_HEADERS=true` и укажите адреса прокси в `EST_API__FORWARDED_ALLOW_IPS` (никогда `*`, если порт доступен напрямую): иначе ограничитель попыток входа видит адрес прокси вместо адреса клиента.
|
||||
- В образе по умолчанию `EST_ENV=prod`, то есть `config/prod.toml` с `cookie_secure = true`: сессионная cookie отправляется только по HTTPS (на `localhost` современные браузеры это допускают). Для обычного http на другом адресе задайте `EST_WEB__COOKIE_SECURE=false`.
|
||||
- Сервис сам HTTPS не терминирует.
|
||||
|
||||
## Что сделано для безопасности
|
||||
|
||||
Запуск не от root, `cap_drop: ALL`, `no-new-privileges`, база не публикуется на хост, секреты не попадают в образ (`.env` исключён из контекста сборки, в `Dockerfile` нет ключей), пароль базы обязателен, пакеты ставятся только из собранных колёс. Конфигурация и промпты лежат в образе (`/app/config`, `/app/prompts`); чтобы их заменить, смонтируйте свои каталоги поверх.
|
||||
|
||||
## Что проверено и что нет
|
||||
|
||||
Проверено:
|
||||
- колесо собирается и содержит шаблоны, статику и `htmx.min.js`; в зависимостях объявлен `pgvector` (его не хватало, он нужен схеме; теперь тест сверяет все импортируемые пакеты с `pyproject.toml`);
|
||||
- в чистом виртуальном окружении, установленном из колёс (без каталога проекта), команда `migrate` применяет схему на PostgreSQL 16 с pgvector (таблицы, расширение, индекс HNSW), повторный запуск ничего не меняет;
|
||||
- `serve` с `MIGRATE_ON_START=true` на пустой базе применяет миграции и только потом поднимает сервис, который отвечает на запросы;
|
||||
- недоступная база или сломанная миграция останавливают запуск, порт не слушается;
|
||||
- `wait-db` ждёт появления базы и возвращается, когда она создана;
|
||||
- тесты в репозитории проверяют порядок вызовов точки входа (заглушкой вместо `python`), структуру compose (порядок запуска, один образ, обязательный пароль, база не опубликована) и свойства `Dockerfile` (не root, что копируется, нет секретов, `.dockerignore` не исключает нужное).
|
||||
|
||||
Не проверено (в среде нет Docker): `docker build`, `docker compose up`, размер образа, проверка здоровья внутри контейнера, поведение образа `pgvector/pgvector:pg16` на первом запуске (предполагается, что расширение в нём есть, а пользователь по умолчанию суперпользователь). Первый запуск стоит пройти вручную и посмотреть `docker compose logs migrate`.
|
||||
|
||||
## Ограничения
|
||||
|
||||
- Фоновые расчёты идут внутри процесса: запускайте одну копию `app`.
|
||||
- Нет автоматических резервных копий и срока хранения старых оценок, нет ограничения частоты запросов к API.
|
||||
- Образ не подписывается и не сканируется на уязвимости; версии зависимостей не закреплены (задаются нижними границами в `pyproject.toml`).
|
||||
@@ -541,7 +541,7 @@ if __name__ == "__main__":
|
||||
| 3. `market/repository`, справочник, `market/check` | готово (плюс эндпоинты `/api/market/*` и авторизация по ключу) |
|
||||
| 4. LLM-клиент (OpenAI, Anthropic) и конвейер агента | готово на фейковых и мокнутых ответах, на реальных провайдерах не проверено |
|
||||
| 5. БД, миграции, `estimate_service`, REST оценок | готово, проверено на SQLite и PostgreSQL 16 |
|
||||
| 6. RAG | не начато |
|
||||
| 6. RAG | основная часть готова (ADR-0003), корпус пуст, на реальных эмбеддингах не проверено |
|
||||
| 7. Калибровка | не начато |
|
||||
| 8. MCP-обёртка | не начато |
|
||||
| 9. ETL рыночных данных | не начато |
|
||||
@@ -679,3 +679,33 @@ if __name__ == "__main__":
|
||||
|
||||
Проверено: тесты на SQLite и PostgreSQL 16, включая миграцию `0003`. Открыто: режим налогообложения продавца (ОСНО или УСН), НДС в источниках ориентиров, предупреждение о падении наценки при фиксированной сумме с НДС.
|
||||
|
||||
### 13.9. Мелкие долги, RAG, схлопнутые миграции
|
||||
|
||||
Обновлено: 2 ноября 2026. RAG подробно в [ADR-0003](adr/0003-rag-reference-tasks.md).
|
||||
|
||||
| Что | Решение |
|
||||
|---|---|
|
||||
| Миграции | Схлопнуты в одну `0001_initial` (ревизии `0002_engagement`, `0003_vat_rate` и упоминания о них в ADR-0001 и ADR-0002 исторические). Пока нигде нет установленной базы, схему можно править в этом файле; после первой установки только новые ревизии |
|
||||
| Автор версий | У оценки `created_by` (кто начал), у каждой версии свой `created_by` (кто сделал). Для ключа API это имя клиента, для интерфейса имя человека (токены UI теперь на пользователя, а не на рабочее пространство). Изоляция данных по-прежнему идёт по клиенту |
|
||||
| «Предварительная оценка» | `result.preliminary` и причины, если оценка опирается на допущения по неуточнённым вопросам; в интерфейсе плашка и пометка в истории. Ручная правка и смена модели оплаты статус не меняют |
|
||||
| Роли | В справочник рынка добавлены ставки `frontend` и `designer`. **Это допущения без источника** (frontend равен backend, designer условный), помечены в файле и ждут реальных значений |
|
||||
| RAG | Таблица `reference_tasks` (pgvector и HNSW на PostgreSQL, JSON и Python на SQLite), эмбеддинги OpenAI-совместимые или офлайн `hash`, поиск аналогов по каждой задаче, загрузка через CLI `rag`, аналоги видны в интерфейсе и сохраняются в результате |
|
||||
| Конфигурация | `[rag]`: `enabled=false` по умолчанию, `provider`, `model`, `base_url`, `top_k`, `min_similarity`, `batch_size`; `agent.reference_k` удалён (заменён на `rag.top_k`) |
|
||||
|
||||
Проверено: 599 тестов на SQLite и PostgreSQL 16 с pgvector 0.6.0, прогон настоящего htmx в jsdom.
|
||||
|
||||
### 13.10. Docker и запуск
|
||||
|
||||
Обновлено: 2 ноября 2026. Подробности в [deployment.md](deployment.md).
|
||||
|
||||
| Что | Решение |
|
||||
|---|---|
|
||||
| Образ | Двухэтапная сборка на `python:3.12-slim`, запуск не от root, `config/`, `prompts/`, `migrations/` и `alembic.ini` лежат в `/app` (сервис читает их относительно рабочего каталога) |
|
||||
| Миграции | Отдельное разовое задание `migrate` в compose; сервис стартует только после его успешного завершения. Для одного контейнера есть `MIGRATE_ON_START=true` |
|
||||
| База | `pgvector/pgvector:pg16`, готовность проверяется по TCP |
|
||||
| Новые команды | `python -m estimator wait-db [--timeout N]`; настройки `[api] proxy_headers` и `forwarded_allow_ips` |
|
||||
| `.env` | Читаются только ключи с префиксом `EST_`: переменные compose в том же файле сервису не мешают, а опечатка с префиксом по-прежнему вызывает ошибку |
|
||||
| Зависимости | Добавлен пропущенный `pgvector`; тест сверяет все импортируемые пакеты с `pyproject.toml` |
|
||||
|
||||
Образ в среде разработки не собирался (нет Docker); проверка выполнена имитацией на PostgreSQL 16 с pgvector и тестами структуры файлов.
|
||||
|
||||
|
||||
@@ -408,3 +408,10 @@ HTMX хорошо подходит для форм, таблиц, статусо
|
||||
- На карточке цены селектор ставки: смена создаёт новую версию без нового расчёта.
|
||||
- Карточка сверки с рынком пишет, что сравнивается цена с резервом без НДС, и помечает ориентиры, приведённые из цен с НДС.
|
||||
|
||||
### 13.6. Автор, предварительная оценка, аналоги (2.11.2026)
|
||||
|
||||
- В строке состояния оценки указаны автор оценки и автор каждой версии; в истории колонка «Автор» (кто начал оценку).
|
||||
- Оценка, построенная на допущениях по неуточнённым вопросам, получает жёлтую плашку «Предварительная оценка» с перечнем допущений, а в истории пометку «предварительная».
|
||||
- Под задачей в раскрывающемся блоке «Аналоги из истории»: похожие прошлые задачи с часами, видом (факт или оценка), проектом и сходством. Блок виден только при включённом RAG ([ADR-0003](adr/0003-rag-reference-tasks.md)). Тексты аналогов экранируются.
|
||||
- Токены, которыми интерфейс обращается к API внутри процесса, теперь выдаются на каждого пользователя, чтобы в журнале версий был виден человек.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user