ййй
This commit is contained in:
@@ -0,0 +1,222 @@
|
||||
---
|
||||
|
||||
## 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`, `RepoWebhookService`.
|
||||
- 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}`, `/internal/rag-repo/webhook`.
|
||||
- Key data flows: snapshot indexing, incremental reindex, retrieval из `rag_chunks`, webhook-нормализация коммитов.
|
||||
- Source of truth: код `src/app/modules/rag/*`.
|
||||
|
||||
## Назначение
|
||||
|
||||
Пакет `rag` отвечает за полный цикл подготовки retrieval-контекста для проекта: принимает снапшоты и изменения файлов, преобразует их в набор атомарных `RagDocument`, векторизует, сохраняет в БД и предоставляет доступ к индексированным данным другим частям системы.
|
||||
|
||||
## Контекст
|
||||
|
||||
Модуль используется как инфраструктурный слой для agent/runtime и смежных интеграций. На вход он принимает либо список файлов проекта, либо webhook репозитория. На выходе формирует устойчивый индекс, ассоциированный с `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 репозитории. Отдельно `RagRepoModule` принимает repository webhooks и прокидывает нормализованный commit context в story storage и cache writer.
|
||||
|
||||
## Основные модули
|
||||
|
||||
|
||||
| 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` |
|
||||
| `RepoWebhookService` | нормализация webhook payload и выделение story id | story writer, cache writer | `src/app/modules/rag/webhook_service.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 | публичный и internal 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` |
|
||||
| Story context repository | outbound | запись webhook-коммитов для story | Python interface | `logic-rag-indexing` |
|
||||
|
||||
|
||||
## Основные потоки
|
||||
|
||||
### 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.
|
||||
- Deprecated endpoint `/internal/rag/retrieve` не используется для рабочего retrieval.
|
||||
- Реальное 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 не содержат собственной бизнес-авторизации внутри модуля и полагаются на внешний слой приложения.
|
||||
- Webhook provider определяется по headers/payload без явной проверки подписи в самом `RepoWebhookService`.
|
||||
|
||||
### Reliability
|
||||
|
||||
- Проектный `asyncio.Lock` предотвращает параллельную индексацию одной `rag_session`.
|
||||
- `RetryExecutor` повторяет временные сбои индексации.
|
||||
|
||||
### Observability
|
||||
|
||||
- Logs: `RagService` пишет предупреждения по cache hit/miss и skipped files.
|
||||
- Metrics: явные метрики не выделены.
|
||||
- Traces: явная трассировка не реализована.
|
||||
- Audit: job status и webhook commit binding сохраняются в БД.
|
||||
|
||||
### 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`
|
||||
- `src/app/modules/rag/webhook_service.py`
|
||||
|
||||
### Symbols
|
||||
|
||||
- `RagModule`
|
||||
- `RagRepoModule`
|
||||
- `RagService`
|
||||
- `IndexingOrchestrator`
|
||||
- `RagRepository`
|
||||
- `RepoWebhookService`
|
||||
|
||||
## Связанные документы
|
||||
|
||||
- `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` на основе текущей реализации. |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user