RAG Reranker

RAG Reranker — это сервис для интеллектуального ранжирования документов по релевантности к поисковому запросу. Он использует семантические эмбеддинги для определения степени схожести между запросом и документами, что позволяет находить наиболее релевантные результаты даже при отсутствии точных совпадений слов.

Принцип работы

Reranker преобразует текстовые данные в векторные представления (эмбеддинги) и вычисляет косинусную схожесть между векторами запроса и документов. Чем выше схожесть, тем более релевантен документ запросу.

Основные возможности:

Семантический поиск — находит документы по смыслу, а не только по ключевым словам
Кеширование эмбеддингов — экономия до 90% затрат при повторных запросах
Две модели — выбор между скоростью (small) и точностью (large)
Работа с таблицами — интеллектуальная обработка структурированных данных

Эндпоинт

POST https://chat.jarv.tech/api/v1/rerank

Параметры запроса

Параметр	Тип	По умолчанию	Описание
`query`	`string`	обязательный	Поисковый запрос для ранжирования документов
`content`	`string \| array`	обязательный	Текст или массив документов для ранжирования
`model`	`string`	`"small"`	Модель эмбеддингов: `"small"` (1536 измерений) или `"large"` (3072 измерения)
`similarity_threshold`	`float`	`0.0`	Минимальный порог схожести (от 0.0 до 1.0)
`top_k`	`integer`	`10`	Количество топ результатов для возврата
`caching`	`boolean`	`true`	Использовать кеширование эмбеддингов
`column_to_embed`	`string`	`null`	Колонка для создания эмбеддингов (только для табличных данных)
`column_id`	`string`	`null`	Колонка с идентификаторами (только для табличных данных)

Работа с текстом

При передаче простого текста, Reranker автоматически разбивает его на чанки (фрагменты) размером 1000 символов с перекрытием 200 символов. Это позволяет эффективно обрабатывать длинные документы.

Пример: Поиск в тексте

curl -X POST https://chat.jarv.tech/api/v1/rerank \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "машинное обучение и нейронные сети",
    "content": "Искусственный интеллект включает в себя множество подходов... Глубокое обучение использует многослойные нейронные сети... Классические алгоритмы машинного обучения включают деревья решений...",
    "model": "small",
    "top_k": 3
  }'

Пример: Поиск в массиве документов

curl -X POST https://chat.jarv.tech/api/v1/rerank \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "преимущества облачных технологий",
    "content": [
      {
        "id": "doc_1",
        "data": "Облачные вычисления предоставляют масштабируемую инфраструктуру...",
        "metadata": {"category": "cloud", "date": "2024-01-15"}
      },
      {
        "id": "doc_2",
        "data": "Локальные серверы требуют больших капитальных вложений...",
        "metadata": {"category": "on-premise", "date": "2024-01-10"}
      },
      {
        "id": "doc_3",
        "data": "Гибридная архитектура сочетает преимущества облака и локальной инфраструктуры...",
        "metadata": {"category": "hybrid", "date": "2024-01-20"}
      }
    ],
    "similarity_threshold": 0.3,
    "top_k": 2
  }'

Работа с таблицами

Reranker поддерживает интеллектуальную обработку табличных данных с гибкими настройками того, какие колонки использовать для поиска и идентификации.

Важно: Табличные данные должны быть переданы как массив объектов (строк таблицы), где каждый объект представляет одну строку с ключами-названиями колонок.

Сценарии использования таблиц

1. Поиск по конкретной колонке

Используйте column_to_embed для указания колонки, по которой нужно искать, и column_id для идентификации строк.

Пример: База знаний компании

У вас есть таблица с вопросами и ответами. Нужно найти релевантные ответы по запросу пользователя.

curl -X POST https://chat.jarv.tech/api/v1/rerank \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "как оформить отпуск",
    "content": [
      {
        "question_id": "Q001",
        "question": "Как оформить ежегодный отпуск?",
        "answer": "Для оформления отпуска необходимо подать заявление за 14 дней...",
        "category": "HR",
        "updated": "2024-12-01"
      },
      {
        "question_id": "Q002",
        "question": "Какие документы нужны для больничного?",
        "answer": "Больничный лист оформляется в медицинском учреждении...",
        "category": "HR",
        "updated": "2024-11-15"
      },
      {
        "question_id": "Q003",
        "question": "Как получить справку о доходах?",
        "answer": "Справка 2-НДФЛ выдается бухгалтерией по запросу...",
        "category": "Finance",
        "updated": "2024-12-10"
      }
    ],
    "column_to_embed": "answer",
    "column_id": "question_id",
    "model": "large",
    "top_k": 2
  }'

Ответ:

{
  "query": "как оформить отпуск",
  "results": [
    {
      "rank": 1,
      "id": "Q001",
      "data": "Для оформления отпуска необходимо подать заявление за 14 дней...",
      "metadata": {
        "question": "Как оформить ежегодный отпуск?",
        "category": "HR",
        "updated": "2024-12-01"
      },
      "similarity_score": 0.8234,
      "similarity_percentage": "82.3%"
    },
    {
      "rank": 2,
      "id": "Q002",
      "data": "Больничный лист оформляется в медицинском учреждении...",
      "metadata": {
        "question": "Какие документы нужны для больничного?",
        "category": "HR",
        "updated": "2024-11-15"
      },
      "similarity_score": 0.4567,
      "similarity_percentage": "45.7%"
    }
  ],
  "total_documents": 3,
  "filtered_documents": 2,
  "returned_documents": 2,
  ...
}

2. Поиск по всем колонкам кроме ID

Если указан только column_id, система объединит все остальные колонки для поиска.

Пример: Каталог товаров

Поиск товаров по всем характеристикам одновременно.

curl -X POST https://chat.jarv.tech/api/v1/rerank \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "игровой ноутбук с подсветкой клавиатуры",
    "content": [
      {
        "sku": "NB-001",
        "brand": "TechPro",
        "model": "Gaming X15",
        "description": "Мощный игровой ноутбук с RGB подсветкой клавиатуры",
        "specs": "Intel i7, RTX 4070, 32GB RAM",
        "price": 150000
      },
      {
        "sku": "NB-002",
        "brand": "WorkStation",
        "model": "Pro 14",
        "description": "Ультрабук для работы с долгим временем автономной работы",
        "specs": "Intel i5, Iris Xe, 16GB RAM",
        "price": 80000
      },
      {
        "sku": "NB-003",
        "brand": "GameMax",
        "model": "Predator 17",
        "description": "Топовый геймерский ноутбук с механической клавиатурой",
        "specs": "Intel i9, RTX 4090, 64GB RAM",
        "price": 250000
      }
    ],
    "column_id": "sku",
    "similarity_threshold": 0.4
  }'

3. Автоматическая обработка всей строки

Если не указаны ни column_to_embed, ни column_id, вся строка преобразуется в текст для поиска.

Пример: Логи событий

Поиск по всему содержимому строк лога.

curl -X POST https://chat.jarv.tech/api/v1/rerank \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "ошибка авторизации пользователя",
    "content": [
      {
        "timestamp": "2024-12-20 10:15:23",
        "level": "ERROR",
        "service": "auth-service",
        "message": "Failed to authenticate user: invalid credentials",
        "user_id": "usr_123"
      },
      {
        "timestamp": "2024-12-20 10:16:45",
        "level": "INFO",
        "service": "payment-service",
        "message": "Payment processed successfully",
        "user_id": "usr_456"
      },
      {
        "timestamp": "2024-12-20 10:17:12",
        "level": "WARN",
        "service": "auth-service",
        "message": "Multiple failed login attempts detected",
        "user_id": "usr_789"
      }
    ],
    "top_k": 2
  }'

Структура ответа

{
  "query": "поисковый запрос",
  "results": [
    {
      "rank": 1,
      "id": "идентификатор документа",
      "data": "текст документа или чанка",
      "metadata": {
        // дополнительные данные документа
      },
      "similarity_score": 0.8567,
      "similarity_percentage": "85.7%"
    }
  ],
  "total_documents": 10,        // Всего документов обработано
  "filtered_documents": 5,      // Прошли порог схожести
  "returned_documents": 3,      // Возвращено (top_k)
  "model_info": {
    "model": "large",
    "embedding_model": "text-embedding-3-large",
    "dimensions": 3072
  },
  "cache_info": {
    "from_cache": true,         // Использован кеш
    "cache_hit": true,
    "tokens_used": 0,          // 0 при использовании кеша
    "cached_tokens": 1500      // Сохранено токенов
  },
  "usage": {
    "query_tokens": 15,
    "document_tokens": 1500,
    "total_tokens": 1515,
    "cost_rub": 1.18           // Стоимость запроса
  },
  "parameters": {
    "similarity_threshold": 0.3,
    "top_k": 10,
    "model": "large",
    "column_to_embed": null,
    "column_id": null
  },
  "processing_time_seconds": 0.234
}

Как работает кеширование

Кеширование — это ключевая функция для оптимизации затрат при работе с Reranker. Система автоматически сохраняет векторные представления (эмбеддинги) документов и переиспользует их при повторных запросах.

⚠️ Важно: Автоматический сброс кеша

Кеш автоматически сбрасывается в двух случаях:

Через 12 часа — все записи старше суток удаляются автоматически
При изменении документа — даже минимальное изменение в тексте, порядке документов или структуре приводит к созданию нового кеша

Принцип работы кеша

Ключевые особенности:

Уникальный ключ кеша — формируется на основе API-ключа, модели и "отпечатка" контента
Время жизни — 12 часа (автоматическая очистка устаревших записей)
Привязка к API-ключу — каждый пользователь имеет изолированный кеш
Экономия — при попадании в кеш оплачиваются только токены запроса

Как формируется "отпечаток" контента

Система создает уникальную подпись для каждого набора документов, чтобы определить, изменились ли данные:

Тип контента	Метод создания подписи	Пример
Текст	Первые 200 и последние 200 символов	Для текста "Искусственный интеллект... [много текста]... революционная технология" подпись будет включать начало и конец
Массив документов	Первые 2 и последние 2 документа (id + первые 100 символов data)	Учитываются структура и содержимое крайних элементов массива
Таблица (DataFrame)	Размерность таблицы + первые 2 и последние 2 строки	Для таблицы 100x5 создается подпись вида "df_100x5_[данные строк]"

📌 Что приводит к сбросу кеша:

Изменение текста — добавление/удаление даже одного символа
Изменение порядка — перестановка документов в массиве
Изменение структуры — добавление/удаление полей в документах
Изменение id или data — любые правки в ключевых полях
Истечение 12 часов — автоматическая очистка по времени

Совет: Если документы обновляются редко, старайтесь сохранять их структуру и порядок неизменными для максимальной эффективности кеша.

Когда кеш эффективен

✅ Идеальные сценарии для кеширования:

FAQ системы — база вопросов и ответов обновляется редко
Каталоги товаров — изменения происходят не чаще раза в день
Документация — статичный контент с редкими обновлениями
Исторические данные — логи, архивы, отчеты за прошлые периоды

❌ Когда отключить кеширование:

Реалтайм данные — биржевые котировки, новостные ленты
Часто меняющийся контент — чаты, комментарии, активные форумы
Персонализированные данные — уникальный контент для каждого пользователя

Пример экономии с кешированием

Рассмотрим реальный пример использования кеша для FAQ-системы:

Помните: Кеш действует только 12 часа. После этого при первом запросе эмбеддинги будут пересчитаны заново.

# День 1, 10:00 - Первый запрос (создание кеша)
{
  "query": "как оформить отпуск",
  "content": [...100 документов FAQ...],
  "model": "large",
  "caching": true
}
# Результат: cost_rub: 39.00 (полная стоимость)

# День 1, 15:00 - Запрос с тем же контентом (используется кеш)
{
  "query": "правила больничного",
  "content": [...те же 100 документов...],
  "model": "large",
  "caching": true
}
# Результат: cost_rub: 0.004 (только токены запроса)

# День 2, 11:00 - Прошло больше 12 часов (кеш истек)
{
  "query": "отпуск по уходу за ребенком",
  "content": [...те же 100 документов...],
  "model": "large",
  "caching": true
}
# Результат: cost_rub: 39.00 (кеш пересоздается)

# Изменение даже одного символа сбрасывает кеш
{
  "query": "как оформить отпуск",
  "content": [...99 старых документов + 1 обновленный...],
  "model": "large",
  "caching": true
}
# Результат: cost_rub: 39.00 (новый кеш из-за изменения)

Как проверить использование кеша

В ответе API всегда присутствует объект cache_info с детальной информацией:

Поле	Значение	Описание
`from_cache`	`true/false`	Были ли эмбеддинги документов взяты из кеша
`cache_hit`	`true/false`	Найден ли подходящий кеш для запроса
`tokens_used`	число	Количество токенов, обработанных в этом запросе (0 при кеше)
`cached_tokens`	число	Количество токенов, сохраненных в кеше
`cache_enabled`	`true/false`	Включено ли кеширование для запроса

Стратегии оптимизации кеша

1. Группировка документов

Объединяйте связанные документы в один запрос вместо множества мелких:

# ❌ Неэффективно - отдельный кеш для каждой категории
for category in ["HR", "IT", "Finance"]:
    rerank(query, documents.filter(cat=category))

# ✅ Эффективно - один кеш для всех документов
all_docs = documents.all()
results = rerank(query, all_docs)
# Фильтрация по категории после получения результатов

2. Версионирование контента

При обновлении документов добавляйте версию в metadata, а не изменяйте основной текст:

# ✅ Правильно - кеш сохраняется
{
  "id": "doc_1",
  "data": "Оригинальный текст политики отпусков",
  "metadata": {
    "version": "2.0",
    "updated": "2024-12-20",
    "changes": "Добавлен пункт о удаленной работе"
  }
}

3. Планирование обновлений

Обновляйте документы пакетно раз в сутки, чтобы максимально использовать 24-часовой кеш:

# Скрипт ежедневного обновления
async def daily_update():
    # 1. Очистить старый кеш
    await clear_rerank_cache()
    
    # 2. Загрузить обновленные документы
    documents = await load_fresh_documents()
    
    # 3. Прогреть кеш популярными запросами
    for query in POPULAR_QUERIES:
        await rerank(query, documents, caching=True)

💡 Практический совет по экономии:

При работе с большими объемами данных (например, 100 000 токенов) и модели large, один запрос без кеша стоит около 78₽. С кешированием последующие запросы будут стоить менее 1 копейки. За 12 часа при 100 запросах экономия составит более 7 700₽!

Управление кешем

Кеш позволяет значительно сократить расходы при работе с одними и теми же документами.

Получение статистики кеша

GET https://chat.jarv.tech/api/v1/rerank/cache-stats
Authorization: api-key YOUR_API_KEY

Очистка кеша

DELETE https://chat.jarv.tech/api/v1/rerank/cache
Authorization: api-key YOUR_API_KEY

Стоимость

Стоимость рассчитывается по количеству обработанных токенов. При использовании кеша оплачиваются только токены запроса.

Модель	Размерность	Стоимость за 1 млн токенов	Особенности
`small`	1536	200 ₽	Быстрая обработка, оптимальна для большинства задач
`large`	3072	780 ₽	Максимальная точность для сложных запросов

Совет по экономии: Используйте кеширование (caching: true) для документов, которые не меняются часто. Это может сократить расходы до 90% при повторных запросах.