301 lines
10 KiB
Markdown
301 lines
10 KiB
Markdown
# Модуль rag
|
||
|
||
## 1. Функции модуля
|
||
- Единое ядро RAG для индексации и retrieval по документации и коду проекта.
|
||
- Поддержка двух семейств индексации: `DOCS` и `CODE`, с разными слоями и разными pipeline.
|
||
- Хранение `rag_session`, index-jobs, многослойных документов, cache-слоев и retrieval-запросов.
|
||
- Поддержка индексации snapshot и changes с переиспользованием cache по `blob_sha`.
|
||
- Предоставление контекста для agent/chat, где `DOCS` используется по умолчанию, а `CODE` включается для явных вопросов по реализации.
|
||
|
||
## 2. Диаграмма классов и взаимосвязей
|
||
```mermaid
|
||
classDiagram
|
||
class RagService
|
||
class RagRepository
|
||
class RagSchemaRepository
|
||
class RagDocumentUpserter
|
||
class DocsIndexingPipeline
|
||
class CodeIndexingPipeline
|
||
class RagQueryRouter
|
||
class GigaChatEmbedder
|
||
|
||
RagService --> RagRepository
|
||
RagService --> DocsIndexingPipeline
|
||
RagService --> CodeIndexingPipeline
|
||
RagService --> RagQueryRouter
|
||
RagService --> GigaChatEmbedder
|
||
RagRepository --> RagSchemaRepository
|
||
RagService --> RagDocumentUpserter
|
||
```
|
||
|
||
## 3. Описание классов
|
||
- `RagService`: основной application-service модуля.
|
||
Методы: `index_snapshot` — индексирует полный набор файлов; `index_changes` — применяет инкрементальные изменения; `retrieve` — возвращает релевантный контекст из `DOCS` или `CODE`.
|
||
- `RagRepository`: фасад persistence-слоя RAG.
|
||
Методы: `ensure_tables` — создает/обновляет схему; `upsert_session/get_session/session_exists` — операции по `rag_session`; `create_job/update_job/get_job` — операции по index jobs; `replace_documents/apply_document_changes` — операции по документам; `get_cached_documents/cache_documents` — работа с cache; `retrieve/fallback_chunks` — retrieval.
|
||
- `RagSchemaRepository`: управление схемой БД для RAG.
|
||
Методы: `ensure_tables` — создает таблицы и индексы; `_ensure_columns` — добавляет новые поля; `_ensure_indexes` — поддерживает индексы для retrieval и фильтрации.
|
||
- `RagDocumentUpserter`: батчевый writer многослойных `RagDocument`.
|
||
Методы: `replace` — полностью заменяет документы сессии; `apply_changes` — применяет upsert/delete по измененным путям.
|
||
- `DocsIndexingPipeline`: pipeline индексации документации.
|
||
Методы: `supports` — определяет, относится ли файл к docs; `index_file` — строит документы слоев `D1-D4` для одного файла.
|
||
- `CodeIndexingPipeline`: pipeline индексации Python-кода.
|
||
Методы: `supports` — определяет, относится ли файл к code; `index_file` — строит документы слоев `C0-C3` для одного файла.
|
||
- `RagQueryRouter`: выбирает retrieval mode и активные слои.
|
||
Методы: `resolve_mode` — определяет `docs` или `code`; `layers_for_mode` — возвращает набор слоев для retrieval.
|
||
- `GigaChatEmbedder`: адаптер embeddings-модели.
|
||
Методы: `embed` — возвращает embeddings для списка текстов.
|
||
|
||
## 4. Сиквенс-диаграммы API и выполнения
|
||
|
||
### Индексация snapshot через текущий `rag_session` facade
|
||
Назначение: создать/обновить `rag_session` и построить многослойный индекс по переданным файлам проекта.
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Router as RagModule.APIRouter
|
||
participant Sessions as RagSessionStore
|
||
participant Indexing as IndexingOrchestrator
|
||
participant Rag as RagService
|
||
participant Docs as DocsIndexingPipeline
|
||
participant Code as CodeIndexingPipeline
|
||
participant Repo as RagRepository
|
||
|
||
Router->>Sessions: create(project_id)
|
||
Sessions-->>Router: rag_session_id
|
||
Router->>Indexing: enqueue_snapshot(rag_session_id, files)
|
||
Indexing->>Rag: index_snapshot(rag_session_id, files)
|
||
loop for each file
|
||
Rag->>Docs: supports/index_file
|
||
Rag->>Code: supports/index_file
|
||
Rag->>Repo: cache_documents(...)
|
||
end
|
||
Rag->>Repo: replace_documents(...)
|
||
Indexing-->>Router: index_job_id,status
|
||
```
|
||
|
||
### Retrieval для agent/chat
|
||
Назначение: вернуть релевантный контекст из нужного семейства слоев.
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Agent as GraphAgentRuntime
|
||
participant Rag as RagService
|
||
participant Router as RagQueryRouter
|
||
participant Repo as RagRepository
|
||
|
||
Agent->>Rag: retrieve(rag_session_id, query)
|
||
Rag->>Router: resolve_mode(query)
|
||
Router-->>Rag: docs|code + layers
|
||
Rag->>Repo: retrieve(query_embedding, query_text, layers)
|
||
Repo-->>Rag: ranked items
|
||
Rag-->>Agent: items
|
||
```
|
||
|
||
## 5. Слои, фиксируемые в RAG
|
||
|
||
### 5.1. Слои DOCS
|
||
|
||
#### `D1_MODULE_CATALOG`
|
||
Назначение: каталог модулей документации и граф связей между ними.
|
||
|
||
Основные атрибуты:
|
||
- `module_id`
|
||
- `type`
|
||
- `domain`
|
||
- `title`
|
||
- `status`
|
||
- `version`
|
||
- `tags`
|
||
- `owners`
|
||
- `links`
|
||
- `calls_api`
|
||
- `called_by`
|
||
- `uses_logic`
|
||
- `used_by`
|
||
- `reads_db`
|
||
- `writes_db`
|
||
- `integrates_with`
|
||
- `emits_events`
|
||
- `consumes_events`
|
||
- `source_path`
|
||
- `summary_text`
|
||
|
||
#### `D2_FACT_INDEX`
|
||
Назначение: атомарные факты `subject-predicate-object` с evidence.
|
||
|
||
Основные атрибуты:
|
||
- `fact_id`
|
||
- `subject_id`
|
||
- `predicate`
|
||
- `object`
|
||
- `object_ref`
|
||
- `source_path`
|
||
- `anchor`
|
||
- `line_start`
|
||
- `line_end`
|
||
- `confidence`
|
||
- `tags`
|
||
|
||
#### `D3_SECTION_INDEX`
|
||
Назначение: семантические секции документации, нарезанные по заголовкам.
|
||
|
||
Основные атрибуты:
|
||
- `chunk_id`
|
||
- `module_id`
|
||
- `section_path`
|
||
- `section_title`
|
||
- `content`
|
||
- `source_path`
|
||
- `order`
|
||
- `tags`
|
||
- `domain`
|
||
- `type`
|
||
- `embedding`
|
||
|
||
#### `D4_POLICY_INDEX`
|
||
Назначение: глобальные правила и конвенции проекта.
|
||
|
||
Основные атрибуты:
|
||
- `policy_id`
|
||
- `applies_to`
|
||
- `rules`
|
||
- `default_behaviors`
|
||
- `source_path`
|
||
|
||
### 5.2. Слои CODE
|
||
|
||
#### `C0_SOURCE_CHUNKS`
|
||
Назначение: сырой код как источник истины для цитирования и evidence.
|
||
|
||
Основные атрибуты:
|
||
- `lang`
|
||
- `repo_id`
|
||
- `commit_sha`
|
||
- `path`
|
||
- `span`
|
||
- `title`
|
||
- `text`
|
||
- `module_or_unit`
|
||
- `chunk_type`
|
||
- `symbol_id`
|
||
- `hash`
|
||
|
||
#### `C1_SYMBOL_CATALOG`
|
||
Назначение: каталог символов кода и их деклараций.
|
||
|
||
Основные атрибуты:
|
||
- `lang`
|
||
- `repo_id`
|
||
- `commit_sha`
|
||
- `symbol_id`
|
||
- `qname`
|
||
- `kind`
|
||
- `decl.path`
|
||
- `decl.start_line`
|
||
- `decl.end_line`
|
||
- `text`
|
||
- `visibility`
|
||
- `signature`
|
||
- `decorators_or_annotations`
|
||
- `docstring_or_javadoc`
|
||
- `parent_symbol_id`
|
||
- `package_or_module`
|
||
- `is_entry_candidate`
|
||
- `lang_payload`
|
||
|
||
#### `C2_DEPENDENCY_GRAPH`
|
||
Назначение: связи между сущностями кода.
|
||
|
||
Основные атрибуты:
|
||
- `lang`
|
||
- `repo_id`
|
||
- `commit_sha`
|
||
- `edge_id`
|
||
- `edge_type`
|
||
- `src_symbol_id`
|
||
- `dst_symbol_id`
|
||
- `dst_ref`
|
||
- `evidence.path`
|
||
- `evidence.start_line`
|
||
- `evidence.end_line`
|
||
- `text`
|
||
- `resolution`
|
||
- `callsite_kind`
|
||
- `lang_payload`
|
||
|
||
#### `C3_ENTRYPOINTS`
|
||
Назначение: точки входа приложения и их обработчики.
|
||
|
||
Основные атрибуты:
|
||
- `lang`
|
||
- `repo_id`
|
||
- `commit_sha`
|
||
- `entry_id`
|
||
- `entry_type`
|
||
- `framework`
|
||
- `route_or_command`
|
||
- `handler_symbol_id`
|
||
- `evidence.path`
|
||
- `evidence.start_line`
|
||
- `evidence.end_line`
|
||
- `text`
|
||
- `http.methods`
|
||
- `http.auth`
|
||
- `request_model`
|
||
- `response_model`
|
||
- `cli.args_schema`
|
||
- `task.queue`
|
||
- `task.cron`
|
||
- `tags`
|
||
- `lang_payload`
|
||
|
||
#### `C4_PUBLIC_API`
|
||
Назначение: публичная поверхность API/экспортируемых символов.
|
||
|
||
Основные атрибуты:
|
||
- `api_id`
|
||
- `symbol_id`
|
||
- `stability`
|
||
- `source_of_truth`
|
||
- `versioning_tags`
|
||
- `lang_payload`
|
||
|
||
#### `C5_BEHAVIOR_SUMMARIES`
|
||
Назначение: поведенческие summary с обязательными evidence links.
|
||
|
||
Основные атрибуты:
|
||
- `target_type`
|
||
- `target_id`
|
||
- `text`
|
||
- `claims`
|
||
- `evidence_links`
|
||
- `confidence`
|
||
- `generated_by`
|
||
- `generated_at`
|
||
|
||
#### `C6_RUNTIME_TRACES`
|
||
Назначение: runtime/trace слой для связи кода и реального исполнения.
|
||
|
||
Основные атрибуты:
|
||
- `env`
|
||
- `trace_id`
|
||
- `span_id`
|
||
- `symbol_id`
|
||
- `entry_id`
|
||
- `text`
|
||
- `timings`
|
||
- `service`
|
||
- `host`
|
||
- `labels`
|
||
|
||
## 6. Правила retrieval
|
||
- По умолчанию retrieval идет в `DOCS`.
|
||
- `CODE` используется только для явных вопросов по реализации, устройству кода, endpoint'ам, handler'ам и документации “из кода”.
|
||
- Для `DOCS` приоритет слоев: `D1 -> D2 -> D3 -> D4`.
|
||
- Для `CODE` приоритет слоев: `C3 -> C1 -> C2 -> C0`.
|
||
|
||
## 7. Текущий статус реализации
|
||
- В первой итерации реализованы `DOCS D1-D4`.
|
||
- В первой итерации реализованы `CODE C0-C3`.
|
||
- `C4-C6` зафиксированы в контракте и зарезервированы под следующие этапы.
|
||
- Текущие `rag_session` и `rag_repo` работают как facade/adapter поверх нового пакета `rag`.
|