---
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-сессии. |