---
id: logic-rag-retrieval
title: Retrieval и ранжирование RAG-документов
doc_type: logic_block
domain: rag
status: draft
owner: system-analyst
source_of_truth: code
related_docs:
  - arch-rag-package
  - entity-rag-session
related_code:
  - src/app/modules/rag/persistence/repository.py
  - src/app/modules/rag/persistence/query_repository.py
  - src/app/modules/rag/persistence/retrieval_statement_builder.py
  - src/app/modules/rag/contracts/enums.py
entities:
  - RagSession
  - RagDocument
tags:
  - rag
  - retrieval
  - ranking
  - pgvector
---
# Retrieval и ранжирование RAG-документов

## Summary
- Purpose: вернуть релевантные RAG-документы из `rag_chunks` для заданной сессии и набора фильтров.
- Trigger: вызовы runtime adapters и внутренних retrieval-компонентов.
- Inputs: `rag_session_id`, `query_embedding`, `query_text`, `layers`, path filters, preference filters, limit.
- Outputs: список rows с `path`, `content`, `layer`, `title`, `metadata`, `span_start`, `span_end`, ranking fields.
- Main entities: `RagSession`, `RagDocument`.
- Main dependencies: `RagRepository`, `RagQueryRepository`, `RetrievalStatementBuilder`, PostgreSQL/pgvector.
- Side effects: отсутствуют, retrieval только читает БД.
- Source of truth: `src/app/modules/rag/persistence/query_repository.py`, `src/app/modules/rag/persistence/retrieval_statement_builder.py`.

## Назначение

Блок retrieval выбирает из индекса наиболее полезные документы по конкретному `rag_session_id`. Он объединяет в одном SQL векторную близость, lexical match, слой документа и структурные сигналы из metadata.

## Контекст

Публичный HTTP endpoint retrieval внутри `rag` помечен как deprecated, поэтому рабочий доступ к retrieval идёт через repository/runtime adapters. Это означает, что контракт фактически определяется SQL-builder и форматом rows, возвращаемых `RagQueryRepository`.

## Технический use case

### Основной сценарий

1. Клиент runtime вызывает `RagRepository.retrieve(...)`.
2. `RagQueryRepository` строит SQL через `RetrievalStatementBuilder.build_retrieve`.
3. SQL ограничивает поиск текущей `rag_session_id`, при необходимости слоями и path-фильтрами.
4. База сортирует документы по `prefer_bonus`, `test_penalty`, `layer_rank`, `lexical_rank`, `structural_rank`, `distance`.
5. Репозиторий возвращает rows с распарсенным `metadata_json`.

### Альтернативные ветки

- Для lexical fallback по коду используется `retrieve_lexical_code`, который работает только по слою `C0_SOURCE_CHUNKS`.
- Для точного добора файлов используется `retrieve_exact_files`, который читает заданные `path` без векторного ранжирования.
- Если `query_text` не даёт terms, lexical retrieval возвращает пустой результат без выполнения SQL.

## Функциональные требования

### Preconditions
- В `rag_chunks` уже должны существовать документы нужной `rag_session_id`.
- Для vector retrieval embedding документа должен быть ненулевым и совпадать по размерности с query embedding.

### Processing rules
- Базовый фильтр retrieval всегда включает `rag_session_id = :sid`.
- При наличии `layers` запрос ограничивается указанными слоями.
- `path_prefixes` задают include-фильтр по `LIKE prefix%`.
- `exclude_path_prefixes` и `exclude_like_patterns` исключают части дерева путей до сортировки.
- `prefer_path_prefixes` и `prefer_like_patterns` формируют `prefer_bonus`, поднимая приоритет совпавших путей.
- `prefer_non_tests` создаёт `test_penalty`, если путь попадает под test-паттерны.

### Validation rules
- Path filters экранируются для корректной работы `LIKE`.
- `retrieve_exact_files` нормализует и отбрасывает пустые пути до построения SQL.
- `retrieve_lexical_code` не выполняет SQL, если query terms отсутствуют.

### Output / result rules
- Каждый row содержит контент документа и технические поля ранжирования.
- `metadata_json` всегда декодируется в словарь `metadata`.
- Limit применяется на уровне SQL и ограничивает итоговый набор строк.

### Side effects
- Побочных эффектов нет, кроме чтения из БД.

## Ограничения и условия вызова

- Retrieval работает только внутри одной `rag_session_id` и не агрегирует несколько сессий.
- Layer ranking зашит в код SQL-builder и требует явного обновления при появлении новых слоёв.
- Полноценный HTTP retrieval endpoint в модуле не публикуется.

## Нефункциональные требования

### Security
- Retrieval не выполняет маскирование содержимого документов.

### Observability
- Logs: отдельное логирование запросов retrieval не реализовано.
- Metrics: метрики по latency и quality не выделены.
- Traces: отсутствуют.
- Audit: результат зависит только от состояния `rag_chunks` и входных фильтров.

### Reliability
- Пустой или некорректный lexical search безопасно возвращает пустой набор.
- `retrieve_exact_files` работает без embeddings и может использоваться как fallback.

### Performance
- Основной ranking выполняется в одном SQL-запросе.
- Для vector retrieval используются поля `embedding` и индексы по session/layer/path.

## Связанные API / UI / integration points

- Runtime retrieval adapters в `src/app/modules/agent/runtime/steps/retrieval/adapter.py`
- Explain retrieval gateway в `src/app/modules/agent/runtime/steps/explain/layered_gateway.py`
- HTTP retrieval endpoint отсутствует

## Связанные сущности

- `RagSession`
- `RagDocument`

## Связанный код

### Files
- `src/app/modules/rag/persistence/repository.py`
- `src/app/modules/rag/persistence/query_repository.py`
- `src/app/modules/rag/persistence/retrieval_statement_builder.py`
- `src/app/modules/rag/contracts/enums.py`

### Symbols
- `RagRepository.retrieve`
- `RagRepository.retrieve_lexical_code`
- `RagRepository.retrieve_exact_files`
- `RagQueryRepository.retrieve`
- `RetrievalStatementBuilder.build_retrieve`
- `RetrievalStatementBuilder.build_lexical_code`

## Связанные документы

- `arch-rag-package`
- `entity-rag-session`

## История изменений

| Date | Source | Changes |
|------|--------|---------|
| 2026-03-13 | code | Описан фактический retrieval contract и ranking SQL для пакета `rag`. |