167 lines
7.4 KiB
Markdown
167 lines
7.4 KiB
Markdown
---
|
||
id: api-rag-session-create
|
||
title: Создание RAG-сессии и запуск snapshot-индексации
|
||
doc_type: api_method
|
||
domain: rag
|
||
status: draft
|
||
owner: system-analyst
|
||
source_of_truth: code
|
||
related_docs:
|
||
- arch-rag-package
|
||
- logic-rag-indexing
|
||
- entity-rag-session
|
||
- entity-rag-index-job
|
||
related_code:
|
||
- src/app/modules/rag/module.py
|
||
- src/app/schemas/rag_sessions.py
|
||
- src/app/schemas/indexing.py
|
||
entities:
|
||
- RagSession
|
||
- IndexJob
|
||
tags:
|
||
- rag
|
||
- api
|
||
- session
|
||
- snapshot
|
||
---
|
||
# Создание RAG-сессии и запуск snapshot-индексации
|
||
|
||
## Summary
|
||
- Purpose: создать новую `RagSession` и асинхронно поставить полную индексацию snapshot-файлов.
|
||
- Actor: внешний клиент модуля RAG.
|
||
- Trigger: первичная загрузка файлов проекта в индекс.
|
||
- Endpoint: `POST /api/rag/sessions`
|
||
- Main entities: `RagSession`, `IndexJob`.
|
||
- Main logic: создание UUID-сессии, постановка snapshot job, возврат идентификаторов сессии и job.
|
||
- Main errors: в коде endpoint нет собственной бизнес-валидации сверх pydantic; ошибки индексации проявляются позже в job status.
|
||
- Source of truth: `src/app/modules/rag/module.py`, `src/app/schemas/rag_sessions.py`.
|
||
|
||
## Назначение
|
||
|
||
Метод открывает новую RAG-сессию и запускает первичную индексацию файлов. Он используется как основной публичный вход для нового API пакета `rag`.
|
||
|
||
## Контекст
|
||
|
||
В отличие от legacy `/api/index/snapshot`, этот endpoint всегда создаёт новый `rag_session_id`, что позволяет независимо хранить несколько снимков одного проекта.
|
||
|
||
## Технический use case
|
||
|
||
### Основной сценарий
|
||
|
||
1. Клиент передаёт `project_id` и массив `files`.
|
||
2. `RagSessionStore.create` создаёт новую запись в `rag_sessions`.
|
||
3. `IndexingOrchestrator.enqueue_snapshot` создаёт `IndexJob` и запускает фоновую обработку.
|
||
4. API сразу возвращает `rag_session_id`, `index_job_id` и стартовый статус.
|
||
|
||
### Альтернативные ветки
|
||
|
||
- Если часть файлов не подлежит индексации, они будут отфильтрованы уже внутри indexing pipeline, а не на этапе ответа API.
|
||
- Ошибки индексации не меняют синхронный ответ create endpoint, а отражаются в последующем статусе job.
|
||
|
||
## Функциональные требования
|
||
|
||
### Request validation
|
||
- `project_id` обязателен и не может быть пустым.
|
||
- `files` передаются списком объектов `FileSnapshot`.
|
||
- Для каждого файла обязательны `path`, `content`, `content_hash`.
|
||
|
||
### Processing rules
|
||
- На каждый вызов создаётся новая `RagSession`.
|
||
- Snapshot job создаётся сразу после сохранения сессии.
|
||
- Ответ не ждёт завершения индексации.
|
||
|
||
### State changes
|
||
- В `rag_sessions` появляется новая запись.
|
||
- В `rag_index_jobs` появляется новая запись в статусе `queued`.
|
||
|
||
### Side effects
|
||
- Запуск фоновой `asyncio` task.
|
||
- Последующая публикация progress events в EventBus.
|
||
|
||
## Contract
|
||
|
||
### Endpoint
|
||
- Method: `POST`
|
||
- Path: `/api/rag/sessions`
|
||
- Auth: определяется внешним слоем приложения, внутри endpoint не задана.
|
||
- Idempotent: нет.
|
||
- Timeout: короткий, так как endpoint не ждёт индексацию.
|
||
- Retry: допустим только на стороне клиента с пониманием, что будет создана новая сессия.
|
||
|
||
### Request
|
||
| Field | Type | Required | Constraints | Description |
|
||
|------|------|----------|-------------|-------------|
|
||
| `project_id` | `string` | yes | `min_length=1` | идентификатор проекта |
|
||
| `files` | `array<FileSnapshot>` | yes | может быть пустым, но схема обязана соблюдаться | snapshot файлов для первичной индексации |
|
||
| `files[].path` | `string` | yes | `min_length=1` | путь файла |
|
||
| `files[].content` | `string` | yes | без дополнительных ограничений | содержимое файла |
|
||
| `files[].content_hash` | `string` | yes | `min_length=1` | hash содержимого для cache reuse |
|
||
|
||
### Response
|
||
| Field | Type | Description |
|
||
|------|------|-------------|
|
||
| `rag_session_id` | `string` | идентификатор созданной сессии |
|
||
| `index_job_id` | `string` | идентификатор фоновой задачи индексации |
|
||
| `status` | `IndexJobStatus` | стартовый статус задачи, обычно `queued` |
|
||
|
||
### External contract refs
|
||
- OpenAPI: формируется FastAPI по `response_model=RagSessionCreateResponse`.
|
||
- Schema: `RagSessionCreateRequest`, `RagSessionCreateResponse`.
|
||
- DTO / serializer: `src/app/schemas/rag_sessions.py`, `src/app/schemas/indexing.py`.
|
||
- Additional refs: `logic-rag-indexing`.
|
||
|
||
## Errors
|
||
|
||
| error_id | http_code | when | client_behavior | retry |
|
||
|----------|-----------|------|-----------------|-------|
|
||
| `validation_error` | `422` | нарушена pydantic-схема request | исправить payload | no |
|
||
|
||
## Нефункциональные требования
|
||
|
||
### Security
|
||
- Авторизация и аутентификация находятся вне этого метода.
|
||
|
||
### Observability
|
||
- Logs: прямое логирование в endpoint отсутствует.
|
||
- Metrics: отдельные API-метрики не выделены.
|
||
- Traces: отсутствуют.
|
||
- Audit: факт вызова материализуется через `RagSession` и `IndexJob`.
|
||
|
||
### Reliability
|
||
- Даже при дальнейшей ошибке индексации клиент может получить статус через job endpoint.
|
||
- Фоновая задача создаётся немедленно после ответа.
|
||
|
||
### Performance
|
||
- Время ответа не зависит от размера snapshot, кроме времени сериализации request.
|
||
|
||
## Связанные блоки логики
|
||
- `logic-rag-indexing`
|
||
|
||
## Связанные сущности
|
||
- `RagSession`
|
||
- `IndexJob`
|
||
|
||
## Связанный код
|
||
|
||
### Files
|
||
- `src/app/modules/rag/module.py`
|
||
- `src/app/schemas/rag_sessions.py`
|
||
- `src/app/schemas/indexing.py`
|
||
|
||
### Symbols
|
||
- `RagModule.public_router.create_rag_session`
|
||
- `RagSessionStore.create`
|
||
- `IndexingOrchestrator.enqueue_snapshot`
|
||
|
||
## Связанные документы
|
||
- `arch-rag-package`
|
||
- `logic-rag-indexing`
|
||
- `entity-rag-session`
|
||
- `entity-rag-index-job`
|
||
|
||
## История изменений
|
||
|
||
| Date | Source | Changes |
|
||
|------|--------|---------|
|
||
| 2026-03-13 | code | Задокументирован публичный endpoint создания RAG-сессии. |
|