первый коммит
This commit is contained in:
218
app/modules/rag_session/README.md
Normal file
218
app/modules/rag_session/README.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# Модуль rag_session
|
||||
|
||||
## 1. Функции модуля
|
||||
- Создание и обслуживание сессионного RAG индекса по загруженным пользователем файлам.
|
||||
- Индексация снапшота и инкрементальных изменений.
|
||||
- Хранение чанков, retrieval контекста, трекинг статуса index jobs.
|
||||
- Публикация прогресса индексации через SSE.
|
||||
|
||||
## 2. Диаграмма классов и взаимосвязей
|
||||
```mermaid
|
||||
classDiagram
|
||||
class RagModule
|
||||
class RagService
|
||||
class RagRepository
|
||||
class RagSessionStore
|
||||
class IndexJobStore
|
||||
class IndexingOrchestrator
|
||||
class TextChunker
|
||||
class GigaChatEmbedder
|
||||
class EventBus
|
||||
|
||||
RagModule --> RagService
|
||||
RagModule --> RagRepository
|
||||
RagModule --> RagSessionStore
|
||||
RagModule --> IndexJobStore
|
||||
RagModule --> IndexingOrchestrator
|
||||
RagService --> RagRepository
|
||||
RagService --> TextChunker
|
||||
RagService --> GigaChatEmbedder
|
||||
IndexingOrchestrator --> IndexJobStore
|
||||
IndexingOrchestrator --> RagService
|
||||
IndexingOrchestrator --> EventBus
|
||||
```
|
||||
|
||||
## 3. Описание классов
|
||||
- `RagModule`: composition-root для сессионного RAG и его API.
|
||||
Методы: `__init__` — собирает сервисы индексации/retrieval; `public_router` — публикует внешние endpoint'ы; `internal_router` — публикует внутренние endpoint'ы.
|
||||
- `RagService`: доменный сервис индексации и retrieval.
|
||||
Методы: `index_snapshot` — индексирует полный набор файлов; `index_changes` — индексирует только изменения; `retrieve` — возвращает релевантные чанки по запросу.
|
||||
- `RagRepository`: слой доступа к БД для сессий, джобов и чанков.
|
||||
Методы: `ensure_tables` — создает/обновляет схему; `upsert_session/get_session/session_exists` — операции по сессиям; `create_job/update_job/get_job` — операции по задачам индексации; `replace_chunks/apply_changes/retrieve/fallback_chunks` — операции по chunk-данным.
|
||||
- `RagSessionStore`: управление жизненным циклом `rag_session`.
|
||||
Методы: `create` — создает новую сессию; `put` — upsert с внешним id; `get` — читает сессию.
|
||||
- `IndexJobStore`: управление `index_job` на уровне приложения.
|
||||
Методы: `create` — создает задачу индексации; `get` — читает задачу; `save` — обновляет статус/ошибку.
|
||||
- `IndexingOrchestrator`: асинхронный оркестратор index-jobs.
|
||||
Методы: `enqueue_snapshot` — ставит полную индексацию в очередь; `enqueue_changes` — ставит инкрементальную индексацию в очередь.
|
||||
- `TextChunker`: разбивает текст файла на чанки для embedding.
|
||||
Методы: `chunk` — возвращает список чанков заданного текста.
|
||||
- `GigaChatEmbedder`: адаптер embeddings-модели.
|
||||
Методы: `embed` — возвращает векторы для набора текстов.
|
||||
- `EventBus`: доставка событий прогресса индексации.
|
||||
Методы: `publish` — отправляет событие; `subscribe/unsubscribe` — управляет подписками SSE.
|
||||
|
||||
## 4. Сиквенс-диаграммы API
|
||||
|
||||
### POST /api/rag/sessions
|
||||
Назначение: создает новую `rag_session` и запускает фоновую индексацию полного набора файлов.
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Router as RagModule.APIRouter
|
||||
participant Sessions as RagSessionStore
|
||||
participant Indexing as IndexingOrchestrator
|
||||
|
||||
Router->>Sessions: create(project_id)
|
||||
Sessions-->>Router: rag_session_id
|
||||
Router->>Indexing: enqueue_snapshot(rag_session_id, files)
|
||||
Indexing-->>Router: index_job_id,status
|
||||
```
|
||||
|
||||
### POST /api/rag/sessions/{rag_session_id}/changes
|
||||
Назначение: ставит в очередь инкрементальную переиндексацию изменений для существующей `rag_session`.
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Router as RagModule.APIRouter
|
||||
participant Sessions as RagSessionStore
|
||||
participant Indexing as IndexingOrchestrator
|
||||
|
||||
Router->>Sessions: get(rag_session_id)
|
||||
Sessions-->>Router: session
|
||||
Router->>Indexing: enqueue_changes(rag_session_id, changed_files)
|
||||
Indexing-->>Router: index_job_id,status
|
||||
```
|
||||
|
||||
### GET /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}
|
||||
Назначение: возвращает состояние и статистику конкретной задачи индексации.
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Router as RagModule.APIRouter
|
||||
participant Jobs as IndexJobStore
|
||||
|
||||
Router->>Jobs: get(index_job_id)
|
||||
Jobs-->>Router: job_state
|
||||
```
|
||||
|
||||
### GET /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}/events
|
||||
Назначение: дает SSE-поток событий прогресса по задаче индексации.
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Router as RagModule.APIRouter
|
||||
participant Jobs as IndexJobStore
|
||||
participant Events as EventBus
|
||||
|
||||
Router->>Jobs: get(index_job_id)
|
||||
Router->>Events: subscribe(index_job_id, replay=True)
|
||||
loop until terminal
|
||||
Events-->>Router: index event
|
||||
end
|
||||
Router->>Events: unsubscribe(index_job_id)
|
||||
```
|
||||
|
||||
### POST /api/index/snapshot (legacy)
|
||||
Назначение: legacy-вход для полной индексации проекта с автоматическим созданием сессии по `project_id`.
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Router as LegacyAPIRouter
|
||||
participant Sessions as RagSessionStore
|
||||
participant Indexing as IndexingOrchestrator
|
||||
|
||||
Router->>Sessions: put(project_id, project_id)
|
||||
Router->>Indexing: enqueue_snapshot(project_id, files)
|
||||
Indexing-->>Router: index_job_id,status
|
||||
```
|
||||
|
||||
### POST /api/index/changes (legacy)
|
||||
Назначение: legacy-вход для инкрементальной индексации изменений по `project_id`.
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Router as LegacyAPIRouter
|
||||
participant Sessions as RagSessionStore
|
||||
participant Indexing as IndexingOrchestrator
|
||||
|
||||
Router->>Sessions: get(project_id)
|
||||
alt missing
|
||||
Router->>Sessions: put(project_id, project_id)
|
||||
end
|
||||
Router->>Indexing: enqueue_changes(project_id, changed_files)
|
||||
Indexing-->>Router: index_job_id,status
|
||||
```
|
||||
|
||||
### GET /api/index/jobs/{index_job_id} (legacy)
|
||||
Назначение: legacy-чтение статуса index-job по `index_job_id`.
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Router as LegacyAPIRouter
|
||||
participant Jobs as IndexJobStore
|
||||
|
||||
Router->>Jobs: get(index_job_id)
|
||||
Jobs-->>Router: job_state
|
||||
```
|
||||
|
||||
### GET /api/index/jobs/{index_job_id}/events (legacy)
|
||||
Назначение: legacy-SSE поток событий по index-job.
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Router as LegacyAPIRouter
|
||||
participant Jobs as IndexJobStore
|
||||
participant Events as EventBus
|
||||
|
||||
Router->>Jobs: get(index_job_id)
|
||||
Router->>Events: subscribe(index_job_id, replay=True)
|
||||
loop until terminal
|
||||
Events-->>Router: index event
|
||||
end
|
||||
Router->>Events: unsubscribe(index_job_id)
|
||||
```
|
||||
|
||||
### POST /internal/rag/index/snapshot
|
||||
Назначение: внутренний синхронный запуск полной индексации для сервисных сценариев.
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Router as InternalRagRouter
|
||||
participant Sessions as RagSessionStore
|
||||
participant RagService as RagService
|
||||
|
||||
Router->>Sessions: get(project_id)
|
||||
alt missing
|
||||
Router->>Sessions: put(project_id, project_id)
|
||||
end
|
||||
Router->>RagService: index_snapshot(project_id, files)
|
||||
RagService-->>Router: indexed_files,failed_files
|
||||
```
|
||||
|
||||
### POST /internal/rag/index/changes
|
||||
Назначение: внутренний синхронный запуск индексации изменений.
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Router as InternalRagRouter
|
||||
participant RagService as RagService
|
||||
|
||||
Router->>RagService: index_changes(project_id, changed_files)
|
||||
RagService-->>Router: indexed_files,failed_files
|
||||
```
|
||||
|
||||
### GET /internal/rag/index/jobs/{index_job_id}
|
||||
Назначение: внутреннее получение статуса и ошибки index-job для сервисов оркестрации.
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Router as InternalRagRouter
|
||||
participant Jobs as IndexJobStore
|
||||
|
||||
Router->>Jobs: get(index_job_id)
|
||||
Jobs-->>Router: job_state
|
||||
```
|
||||
|
||||
### POST /internal/rag/retrieve
|
||||
Назначение: внутренний retrieval релевантных чанков из `rag_session` по текстовому запросу.
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Router as InternalRagRouter
|
||||
participant RagService as RagService
|
||||
participant RagRepo as RagRepository
|
||||
|
||||
Router->>RagService: retrieve(rag_session_id, query)
|
||||
RagService->>RagRepo: retrieve/fallback_chunks
|
||||
RagRepo-->>RagService: chunks
|
||||
RagService-->>Router: items
|
||||
```
|
||||
Reference in New Issue
Block a user