Назначение и границы
Ответ по набору документов должен объяснять происхождение утверждений и явно сообщать, когда релевантного контекста нет.
Путь от HTML-документа до векторного поиска и ответа со ссылками на фрагменты. Реальные очередь, индексатор и pgvector работают с четырьмя собственными учебными документами.
- Четыре синтетических документа и 16 chunks — демонстрационный корпус, не база реальных закупок.
- Cosine score и шаблонный ответ не являются оценкой качества промышленной модели.
- До 30 запросов в минуту на сессию и 1000 живых demo-ключей. Запросы пользователя не сохраняются.
- Worker health подтверждает соединение при старте; отдельный детектор зависшего вычисления не реализован.
Архитектура и схемы
- Seed отправляет настоящее TenderChangedV1 через NATS; индексатор извлекает HTML и формирует chunks.
- PostgreSQL VECTOR(1024) выполняет cosine search. FakeAIProvider создаёт embeddings через hashing trick.
- Повтор события использует content_hash: неизменённый документ не дублирует chunks.
- Генерация ответа — обозначенный шаблон из найденных фрагментов; внешний crawler и Ollama выключены.
Code-map: от функции к коду
Карта привязана к версии a618d1e7be8a. Она помогает проследить изменение через интерфейс, API, модуль, данные и проверку.
| Функция | Экран / API | Модуль | Данные / проверка |
|---|---|---|---|
| Начальная индексация | CLI portfolio | cli._upsert_demo_record, NatsBroker, IndexerService | sources, tenders, attachments, chunks |
| Поиск/ответ | api/v1/search, ask | SearchService, FakeAIProvider | chunks VECTOR(1024) |
| Источники | локальные HTML | web/demo | собственный корпус |
| Повтор события | api/demo/replay | NatsBroker / hash guard | общий read-only корпус |
| Сессия и лимит | cookie / middleware | portfolio, auth, rate_limit | api_keys (только хеш и счётчики) |
Как работать с картой
- Перед изменением найти функцию и пройти связи до API, состояния и хранилища.
- Проверить входы, ошибки, повторные события и зависимые сценарии.
- После изменения обновить карту и затронутые схемы вместе с кодом.
- Выполнить связанные проверки и привязать новые материалы к версии исходников.
Сценарии и API
- Найдите документ о серверах или Angular-портале.
- Задайте вопрос и откройте источники ответа.
- Введите запрос вне корпуса и проверьте отсутствие контекста.
- Повторите индексационные события: четыре документа и 16 chunks сохранятся без дублирования.
Проверка опубликованной версии
CI: CI ↗ · 84c37f0f · исторический запуск другой версии · 2026-08-27T06:43:00Z
CI: Documentation ↗ · 84c37f0f · исторический запуск другой версии · 2026-08-27T06:43:00Z
- 118 unit-тестов пройдено; 18 интеграционных/внешних проверок исключены из этого запуска.
- Search and Ask return sources; unrelated query returns no context
- Queue replay preserves 16 chunks and ready status
- Independent signed expiring HttpOnly sessions
- Подтверждённого GitHub CI для этого SHA нет; перечислены выполненные локальные проверки и сценарии опубликованной версии. Исторические CI-ссылки, если есть, отмечены отдельно.
Результаты описывают проверенные сценарии и конкретную версию. Они не являются оценкой коммерческого успеха или качества моделей на независимой выборке.
Измерения
- Сохранено 12 содержательных кадров фактического интерфейса.
- Дата, сценарий и версия указаны у каждого кадра.
- Максимум RAM контейнеров в коротком тесте: 127.04 MiB. Общие службы учитываются отдельно; магазин включает свою БД.
- Измерено 6 повторений сценария; медиана 997.0 мс, максимум 2738 мс. Время включает браузер и HTTPS; методика и ограничения приложены.
- Четыре ready-документа, 16 chunks. Повтор четырёх NATS-событий не создал дубликаты.
Запуск и эксплуатация
Live-архитектура исходного проекта предусматривает crawler и AI provider. Публичная версия запрещает live AI конфигурацией и принимает только собственный корпус.
Dockerfile.portfolio собирается вне VPS; API и worker используют один закреплённый образ и отдельные лимиты. PostgreSQL и NATS доступны только по внутренней сети, API — через localhost:18403 и Nginx.
При запуске выполнить миграции и CLI portfolio seed. Readiness API проверяет зависимости. Повтор индексации безопасен благодаря content_hash; после рестарта сверять четыре ready-документа и 16 chunks. Сессионные ApiKey удаляются по TTL каждый пять минут.
Общие правила эксплуатации: готовые файлы и закреплённые образы собираются вне VPS; секреты не входят в артефакты. Общесерверный docker prune не применяется. Логи backend ограничены ротацией, изменения log options требуют пересоздания контейнера.
Перед изменением пройти code-map от функции к экрану/API, модулю и данным. После изменения обновить карту и схемы, выполнить связанные сценарии, включая ошибку, повтор и сброс. Источник истины — конкретная версия кода, а не старая диаграмма.
Откат проверен 2026-09-07T01:04:24.534304+00:00: 20260907-verified → 20260907c → 20260907-verified. После каждого переключения подтверждены HTTPS, readiness и SHA. Это проверка конфигурации и артефактов на одном проверенном SHA; обратная миграция БД не выполнялась.
Стек
| FastAPI / Pydantic | HTTP-контракты, валидация и ответы поиска. |
|---|---|
| NATS JetStream | Доставка событий индексатору и повтор. |
| PostgreSQL / pgvector | Документы, attachments, chunks и cosine search. |
| SQLAlchemy / Python | Нормализация, извлечение, chunking и проверка content_hash. |
Материалы и исходники
История реализации: с 20 августа 2026. Публичное демо: 7 сентября 2026.