215 lines
13 KiB
Markdown
215 lines
13 KiB
Markdown
---
|
||
|
||
## id: arch-rag-package
|
||
title: Пакет RAG
|
||
doc_type: architecture_overview
|
||
domain: rag
|
||
status: draft
|
||
owner: system-analyst
|
||
source_of_truth: code
|
||
related_docs:
|
||
- logic-rag-indexing
|
||
- logic-rag-retrieval
|
||
- entity-rag-session
|
||
- entity-rag-index-job
|
||
- api-rag-session-create
|
||
- api-rag-session-changes
|
||
- api-rag-session-job
|
||
related_code:
|
||
- src/app/modules/rag/module.py
|
||
- src/app/modules/rag/services/rag_service.py
|
||
- src/app/modules/rag/indexing_service.py
|
||
- src/app/modules/rag/persistence/repository.py
|
||
- src/app/modules/rag/persistence/schema_repository.py
|
||
entities:
|
||
- RagSession
|
||
- IndexJob
|
||
- RagDocument
|
||
tags:
|
||
- rag
|
||
- indexing
|
||
- retrieval
|
||
- architecture
|
||
|
||
# Пакет RAG
|
||
|
||
## Summary
|
||
|
||
- Scope: модуль индексации проектных файлов, хранения RAG-слоёв и выдачи retrieval-контекста.
|
||
- Purpose: построить индекс по документации и Python-коду и дать runtime доступ к релевантным фрагментам.
|
||
- Main modules: `RagModule`, `RagService`, `IndexingOrchestrator`, `RagRepository`.
|
||
- Main domains: RAG-сессии, задачи индексации, документы индекса, blob-cache, retrieval.
|
||
- Main integrations: PostgreSQL/pgvector, GigaChat embeddings, FastAPI, EventBus, story context.
|
||
- Key entrypoints: `/api/rag/sessions`, `/api/rag/sessions/{rag_session_id}/changes`, `/api/rag/sessions/{rag_session_id}/jobs/{index_job_id}`, `/api/rag/sessions/{rag_session_id}/jobs/{index_job_id}/events`.
|
||
- Key data flows: snapshot indexing, incremental reindex, retrieval из `rag_chunks`.
|
||
- Source of truth: код `src/app/modules/rag/*`.
|
||
|
||
## Назначение
|
||
|
||
Пакет `rag` отвечает за полный цикл подготовки retrieval-контекста для проекта: принимает снапшоты и изменения файлов, преобразует их в набор атомарных `RagDocument`, векторизует, сохраняет в БД и предоставляет доступ к индексированным данным другим частям системы.
|
||
|
||
## Контекст
|
||
|
||
Модуль используется как инфраструктурный слой для agent/runtime. На вход он принимает snapshot и изменения файлов проекта. На выходе формирует устойчивый индекс, ассоциированный с `rag_session_id`, и статус задач индексации, пригодный для опроса и SSE-подписки.
|
||
|
||
## Границы системы
|
||
|
||
### In scope
|
||
|
||
- Создание и хранение `RagSession`.
|
||
- Постановка и выполнение задач snapshot/change indexing.
|
||
- Индексация markdown-документации в слои `D1-D4`.
|
||
- Индексация Python-кода в слои `C0-C4`.
|
||
- Кэширование по `repo_id + blob_sha`.
|
||
- Сохранение retrieval-документов в `rag_chunks`.
|
||
- Выдача статуса задач и событий прогресса.
|
||
- Нормализация webhook Gitea/Bitbucket и связывание коммитов со story.
|
||
|
||
### Out of scope
|
||
|
||
- Финальная генерация ответа пользователю.
|
||
- Оркестрация LLM-диалога.
|
||
- Управление git-репозиторием и загрузка файлов из внешних источников.
|
||
- Политики маршрутизации intent/runtime вне собственного persistence/retrieval API.
|
||
|
||
## Архитектурная схема
|
||
|
||
`RagModule` собирает зависимости модуля и публикует HTTP endpoints. Для индексации он использует `RagSessionStore`, `IndexJobStore`, `IndexingOrchestrator` и `RagService`. `RagService` выбирает docs/code pipeline, обогащает документы метаданными файла, запрашивает embeddings и записывает результат через `RagRepository`. `RagRepository` агрегирует schema/session/job/document/cache/query репозитории.
|
||
|
||
## Основные модули
|
||
|
||
|
||
| module | responsibility | depends_on | key_code_refs |
|
||
| ---------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------- |
|
||
| `RagModule` | сборка зависимостей, публичный и internal API | `RagService`, `IndexingOrchestrator`, `RagSessionStore`, `IndexJobStore` | `src/app/modules/rag/module.py` |
|
||
| `RagService` | синхронная бизнес-логика индексации файлов и cache reuse | docs/code pipeline, embedder, `RagRepository` | `src/app/modules/rag/services/rag_service.py` |
|
||
| `IndexingOrchestrator` | асинхронный job lifecycle, retry, project lock, EventBus | `IndexJobStore`, `RagIndexer`, `EventBus`, `RetryExecutor` | `src/app/modules/rag/indexing_service.py` |
|
||
| `DocsIndexingPipeline` | построение слоёв документации `D1-D4` | classifier, chunker, document builder | `src/app/modules/rag/indexing/docs/pipeline.py` |
|
||
| `CodeIndexingPipeline` | построение слоёв кода `C0-C4` | AST parser, symbol/edge/entrypoint/role builders | `src/app/modules/rag/indexing/code/pipeline.py` |
|
||
| `RagRepository` | единая точка persistence и retrieval | schema/session/job/document/cache/query repositories | `src/app/modules/rag/persistence/repository.py` |
|
||
|
||
|
||
## Основные доменные области
|
||
|
||
- RAG session как граница индекса конкретного проекта или его временного снапшота.
|
||
- Index job как жизненный цикл асинхронной индексации и канал наблюдения за прогрессом.
|
||
- RagDocument как атом индекса, который попадает в retrieval-хранилище и в cache.
|
||
- Repo webhook context как источник commit metadata для story и cache.
|
||
|
||
## Основные интеграции
|
||
|
||
|
||
| integration | direction | purpose | protocol / transport | related_docs |
|
||
| ------------------------ | --------- | --------------------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------- |
|
||
| PostgreSQL + pgvector | outbound | хранение документов, jobs, sessions и vector search | SQLAlchemy / SQL / pgvector | `logic-rag-retrieval` |
|
||
| GigaChat embeddings | outbound | получение embedding для batch документов | HTTP client через `GigaChatClient` | `logic-rag-indexing` |
|
||
| FastAPI | inbound | публичный HTTP API модуля | HTTP | `api-rag-session-create`, `api-rag-session-changes`, `api-rag-session-job` |
|
||
| EventBus | outbound | публикация прогресса индексации и terminal events | in-process async events / SSE | `api-rag-session-job` |
|
||
|
||
|
||
## Основные потоки
|
||
|
||
### Flow 1
|
||
|
||
1. Клиент вызывает `POST /api/rag/sessions` с `project_id` и snapshot файлов.
|
||
2. `RagSessionStore` создаёт `rag_session_id`, а `IndexingOrchestrator` создаёт `IndexJob`.
|
||
3. `RagService` фильтрует файлы, переиспользует cache по `blob_sha` или строит docs/code документы заново.
|
||
4. Документы векторизуются, записываются в `rag_chunks`, а job получает финальный статус `done` или `error`.
|
||
|
||
### Flow 2
|
||
|
||
1. Клиент вызывает `POST /api/rag/sessions/{rag_session_id}/changes`.
|
||
2. `IndexingOrchestrator` сериализует обработку по `rag_session_id`.
|
||
3. `RagService` удаляет документы по `delete_paths`, пересобирает upsert-файлы и применяет изменения к индексу.
|
||
4. Клиент читает статус и события задачи через job endpoints.
|
||
|
||
## Архитектурные решения и ограничения
|
||
|
||
### Key decisions
|
||
|
||
- Snapshot и incremental indexing используют один и тот же `RagService`, различаясь только стратегией записи.
|
||
- Кэш документов привязан к `repo_id + blob_sha`, а не к `rag_session_id`, что позволяет переиспользовать embeddings между сессиями одного проекта.
|
||
- Документация и код индексируются разными pipeline, но сохраняются в общую таблицу `rag_chunks`.
|
||
- Асинхронность вынесена в `IndexingOrchestrator`, чтобы `RagService` оставался application-service без управления job lifecycle.
|
||
|
||
### Constraints
|
||
|
||
- Code indexing поддерживает только Python-файлы.
|
||
- Docs indexing ориентирован на markdown и frontmatter YAML.
|
||
- HTTP retrieval endpoint в модуле не публикуется.
|
||
- Реальное retrieval API доступно через repository/runtime adapters, а не через публичный HTTP endpoint модуля.
|
||
|
||
### Risks
|
||
|
||
- Ошибки embeddings или временные сетевые сбои переводят job в `error` только после исчерпания retry.
|
||
- Полное `replace_documents` для snapshot удаляет все документы сессии перед вставкой новых.
|
||
- Retrieval ranking завязан на SQL-эвристики по layer, lexical match и metadata, поэтому качество зависит от корректности metadata builders.
|
||
|
||
## Нефункциональные аспекты
|
||
|
||
### Security
|
||
|
||
- Публичные endpoints не содержат собственной бизнес-авторизации внутри модуля и полагаются на внешний слой приложения.
|
||
|
||
### Reliability
|
||
|
||
- Проектный `asyncio.Lock` предотвращает параллельную индексацию одной `rag_session`.
|
||
- `RetryExecutor` повторяет временные сбои индексации.
|
||
|
||
### Observability
|
||
|
||
- Logs: `RagService` пишет предупреждения по cache hit/miss и skipped files.
|
||
- Metrics: явные метрики не выделены.
|
||
- Traces: явная трассировка не реализована.
|
||
- Audit: job status сохраняется в БД.
|
||
|
||
### Performance
|
||
|
||
- Embeddings отправляются батчами с размером из `RAG_EMBED_BATCH_SIZE`.
|
||
- Cache reuse исключает повторную векторизацию неизменённых blob.
|
||
|
||
### Scalability
|
||
|
||
- Индекс хранится на уровне SQL-таблиц с векторными полями и индексами по session/layer/path.
|
||
- При росте объёма данных узким местом остаются полнотабличные delete/insert по snapshot и SQL sorting retrieval.
|
||
|
||
## Связанные сущности
|
||
|
||
- `RagSession`
|
||
- `IndexJob`
|
||
- `RagDocument`
|
||
|
||
## Связанный код
|
||
|
||
### Files
|
||
|
||
- `src/app/modules/rag/module.py`
|
||
- `src/app/modules/rag/services/rag_service.py`
|
||
- `src/app/modules/rag/indexing_service.py`
|
||
- `src/app/modules/rag/persistence/repository.py`
|
||
- `src/app/modules/rag/persistence/schema_repository.py`
|
||
|
||
### Symbols
|
||
|
||
- `RagModule`
|
||
- `RagService`
|
||
- `IndexingOrchestrator`
|
||
- `RagRepository`
|
||
|
||
## Связанные документы
|
||
|
||
- `logic-rag-indexing`
|
||
- `logic-rag-retrieval`
|
||
- `entity-rag-session`
|
||
- `entity-rag-index-job`
|
||
- `api-rag-session-create`
|
||
- `api-rag-session-changes`
|
||
- `api-rag-session-job`
|
||
|
||
## История изменений
|
||
|
||
|
||
| Date | Source | Changes |
|
||
| ---------- | ------ | ------------------------------------------------------------------- |
|
||
| 2026-03-13 | code | Создан обзор архитектуры пакета `rag` на основе текущей реализации. |
|