ййй
This commit is contained in:
@@ -0,0 +1,150 @@
|
||||
---
|
||||
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`. |
|
||||
Reference in New Issue
Block a user