151 lines
7.9 KiB
Markdown
151 lines
7.9 KiB
Markdown
---
|
||
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 в модуле отсутствует: `/internal/rag/retrieve` возвращает `410 deprecated`.
|
||
|
||
## Нефункциональные требования
|
||
|
||
### 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`
|
||
- Deprecated endpoint `POST /internal/rag/retrieve`
|
||
|
||
## Связанные сущности
|
||
|
||
- `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`. |
|