agent/docs/documentation/rag/logic-retrieval-ranking.md

id, title, doc_type, domain, status, owner, source_of_truth, related_docs, related_code, entities, tags

id	title	doc_type	domain	status	owner	source_of_truth	related_docs	related_code	entities	tags
logic-rag-retrieval	Retrieval и ранжирование RAG-документов	logic_block	rag	draft	system-analyst	code	arch-rag-package entity-rag-session	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	RagSession RagDocument	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.