Руководство по интеграции
### Введение в архитектуру Instructed Retriever
Классические конвейеры RAG (Retrieval-Augmented Generation) страдают от стохастического дрейфа (semantic drift): когда пользователь задает сложный или косвенный вопрос, векторный поиск возвращает документы, семантически похожие на отдельные слова запроса, но бесполезные для решения конкретной задачи. Агенты начинают галлюцинировать, основываясь на нерелевантном контексте.
**Instructed Retriever** (в стиле архитектуры Databricks) решает эту проблему путем создания «детерминистических мостов» между моделью и хранилищем. Вместо отправки сырого текстового запроса во вспомогательный векторный индекс, система переводит намерение пользователя и контекстные правила в **структурированный план поиска** (Search Plan), который выполняется детерминированно.
### 1. Архитектурные уровни
1. **Компилятор запросов (Query Compiler)**: LLM компилирует текстовый запрос в строго типизированную структуру плана поиска (JSON), содержащую реляционные фильтры (по датам, категориям, авторам), границы секционирования (partition bounds) и ключевые фразы для поиска.
2. **Планировщик выполнения (Execution Planner)**: Разбирает скомпилированный план и оптимизирует доступ к индексам. Например, если запрос касается определенного проекта за конкретную дату, планировщик сначала сужает пространство поиска с помощью точных реляционных фильтров (SQL WHERE), а векторный поиск запускает только внутри полученной выборки.
3. **Детерминированный движок (Deterministic Engine)**: Выполняет структурированные SQL-запросы или API-вызовы к СУБД. Исключает случайное попадание мусорных документов из других доменов.
4. **Гибридный синтез (Hybrid Fusion)**: Объединяет результаты точного поиска и векторного сходства по схеме Reciprocal Rank Fusion (RRF) с применением весов.
### 2. План поиска (Search Plan Schema)
Пример скомпилированного плана поиска в формате JSON:
```json
{
"target_indices": ["checkpoints", "edges_map"],
"filters": [
{"field": "project_id", "op": "==", "value": "continuity-os"},
{"field": "timestamp", "op": ">=", "value": "2026-06-01T00:00:00"}
],
"vector_query": "MirrorCore self-consistency score formula weights",
"limit": 5
}
```
### 3. Защитные барьеры (Safety Guards)
- **Фильтр релевантности (Relevance Gate)**: Каждый извлеченный фрагмент оценивается по метрике косинусного сходства или релевантности. Если ни один документ не превышает порог $0.75$, система выдает ошибку или переключается на детерминированный индекс по умолчанию, предотвращая подмешивание шума.
- **Лимит токенов контекста (Token Cap)**: Ограничение размера контекста на уровне $4096$ токенов. При превышении производится жесткое обрезание списка извлеченных документов по RRF-рангу.
### 4. Реализация на Python (псевдокод)
```python
from typing import Dict, Any, List
import numpy as np
class InstructedRetriever:
def __init__(self, db_conn, vector_client):
self.db = db_conn
self.vector = vector_client
self.min_relevance = 0.75
self.max_tokens = 4096
def compile_plan(self, query: str, context_rules: str) -> Dict[str, Any]:
"""Шаг 1: Компиляция запроса в детерминированный план поиска (имитация LLM)"""
# В реальной системе здесь происходит вызов LLM с JSON-схемой выхода
plan = {
"sql_filter": "project_id = 'continuity-os' AND timestamp >= '2026-06-01'",
"vector_search_text": query,
"limit": 5
}
return plan
def execute_retrieval(self, plan: Dict[str, Any]) -> List[Dict[str, Any]]:
"""Шаг 2: Выполнение плана с реляционной фильтрацией"""
# 1. Применяем строгий SQL-фильтр для получения разрешенных ID документов
cursor = self.db.cursor()
cursor.execute(f"SELECT doc_id FROM document_metadata WHERE {plan['sql_filter']}")
allowed_ids = [row[0] for row in cursor.fetchall()]
if not allowed_ids:
return []
# 2. Выполняем векторный поиск с жестким фильтром по allowed_ids
raw_results = self.vector.search(
query=plan["vector_search_text"],
filter_ids=allowed_ids,
limit=plan["limit"]
)
# 3. Фильтруем результаты по порогу релевантности (Relevance Gate)
valid_results = []
for res in raw_results:
if res["score"] >= self.min_relevance:
valid_results.append(res)
return valid_results
```
Классические конвейеры RAG (Retrieval-Augmented Generation) страдают от стохастического дрейфа (semantic drift): когда пользователь задает сложный или косвенный вопрос, векторный поиск возвращает документы, семантически похожие на отдельные слова запроса, но бесполезные для решения конкретной задачи. Агенты начинают галлюцинировать, основываясь на нерелевантном контексте.
**Instructed Retriever** (в стиле архитектуры Databricks) решает эту проблему путем создания «детерминистических мостов» между моделью и хранилищем. Вместо отправки сырого текстового запроса во вспомогательный векторный индекс, система переводит намерение пользователя и контекстные правила в **структурированный план поиска** (Search Plan), который выполняется детерминированно.
### 1. Архитектурные уровни
1. **Компилятор запросов (Query Compiler)**: LLM компилирует текстовый запрос в строго типизированную структуру плана поиска (JSON), содержащую реляционные фильтры (по датам, категориям, авторам), границы секционирования (partition bounds) и ключевые фразы для поиска.
2. **Планировщик выполнения (Execution Planner)**: Разбирает скомпилированный план и оптимизирует доступ к индексам. Например, если запрос касается определенного проекта за конкретную дату, планировщик сначала сужает пространство поиска с помощью точных реляционных фильтров (SQL WHERE), а векторный поиск запускает только внутри полученной выборки.
3. **Детерминированный движок (Deterministic Engine)**: Выполняет структурированные SQL-запросы или API-вызовы к СУБД. Исключает случайное попадание мусорных документов из других доменов.
4. **Гибридный синтез (Hybrid Fusion)**: Объединяет результаты точного поиска и векторного сходства по схеме Reciprocal Rank Fusion (RRF) с применением весов.
### 2. План поиска (Search Plan Schema)
Пример скомпилированного плана поиска в формате JSON:
```json
{
"target_indices": ["checkpoints", "edges_map"],
"filters": [
{"field": "project_id", "op": "==", "value": "continuity-os"},
{"field": "timestamp", "op": ">=", "value": "2026-06-01T00:00:00"}
],
"vector_query": "MirrorCore self-consistency score formula weights",
"limit": 5
}
```
### 3. Защитные барьеры (Safety Guards)
- **Фильтр релевантности (Relevance Gate)**: Каждый извлеченный фрагмент оценивается по метрике косинусного сходства или релевантности. Если ни один документ не превышает порог $0.75$, система выдает ошибку или переключается на детерминированный индекс по умолчанию, предотвращая подмешивание шума.
- **Лимит токенов контекста (Token Cap)**: Ограничение размера контекста на уровне $4096$ токенов. При превышении производится жесткое обрезание списка извлеченных документов по RRF-рангу.
### 4. Реализация на Python (псевдокод)
```python
from typing import Dict, Any, List
import numpy as np
class InstructedRetriever:
def __init__(self, db_conn, vector_client):
self.db = db_conn
self.vector = vector_client
self.min_relevance = 0.75
self.max_tokens = 4096
def compile_plan(self, query: str, context_rules: str) -> Dict[str, Any]:
"""Шаг 1: Компиляция запроса в детерминированный план поиска (имитация LLM)"""
# В реальной системе здесь происходит вызов LLM с JSON-схемой выхода
plan = {
"sql_filter": "project_id = 'continuity-os' AND timestamp >= '2026-06-01'",
"vector_search_text": query,
"limit": 5
}
return plan
def execute_retrieval(self, plan: Dict[str, Any]) -> List[Dict[str, Any]]:
"""Шаг 2: Выполнение плана с реляционной фильтрацией"""
# 1. Применяем строгий SQL-фильтр для получения разрешенных ID документов
cursor = self.db.cursor()
cursor.execute(f"SELECT doc_id FROM document_metadata WHERE {plan['sql_filter']}")
allowed_ids = [row[0] for row in cursor.fetchall()]
if not allowed_ids:
return []
# 2. Выполняем векторный поиск с жестким фильтром по allowed_ids
raw_results = self.vector.search(
query=plan["vector_search_text"],
filter_ids=allowed_ids,
limit=plan["limit"]
)
# 3. Фильтруем результаты по порогу релевантности (Relevance Gate)
valid_results = []
for res in raw_results:
if res["score"] >= self.min_relevance:
valid_results.append(res)
return valid_results
```