> ## Documentation Index > Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt > Use this file to discover all available pages before exploring further. # bge-reranker-v2-m3 Переранжирование текста > bge-reranker-v2-m3 — это многоязычная модель переранжирования, которая оценивает полученные кандидаты относительно вашего запроса и переупорядочивает их — самое дешевое осмысленное улучшение качества поиска для RAG. Доступно в APIYI по адресу /v1/rerank, $0.01 за 1M tokens. `bge-reranker-v2-m3` — это open-source многоязычная reranking-модель от BAAI. Она решает самый распространенный сбой в системах retrieval: **vector search вернул нужные документы, но наверху оказались не те, которые действительно отвечают на вопрос.** APIYI предоставляет стандартный `/v1/rerank`-шлюз — один token, тот же ключ, что и у любой другой модели. **Имя модели**: `bge-reranker-v2-m3` (с учетом регистра). **Шлюз**: `POST /v1/rerank`. Доступно в группах `default` и `svip`. Все числа на этой странице получены по результатам тестирования APIYI 2026-07-30 (UTC+8), 60+ тестовых случаев. ## Что это такое и когда это использовать Реранжировщик — это **кросс-энкодер**: он конкатенирует ваш запрос с каждым документом-кандидатом, пропускает пару через модель и напрямую выдаёт оценку релевантности. Это принципиально отличается от embedding-модели: | | Эмбеддинг (векторный поиск) | Реранжирование | | ----------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | | Как вычисляется | Запрос и документ кодируются **раздельно**, а затем сравниваются по расстоянию | Запрос и документ проходят через модель **вместе** | | Можно ли предварительно проиндексировать? | ✅ Векторы документов вычисляются офлайн и хранятся в векторной БД | ❌ Для вычислений нужен запрос — предварительно посчитать ничего нельзя | | Скорость | Быстро; миллисекунды на миллионах документов | Медленно; масштабируется от числа кандидатов | | Точность | Средняя | Высокая | | Роль | **Recall**: извлекать десятки документов из миллионов | **Precision**: выбирать несколько лучших из десятков | Поэтому он не заменяет векторный поиск — это второй этап, который следует за ним. Реранжировщик **не может построить индекс и не может выполнять извлечение**. У него нет векторного выхода, и он не может обрабатывать документы без запроса. Если вам нужно «поместить мои документы в векторную БД», вам нужны [text embeddings](/ru/api-capabilities/text-embedding), а не эта модель. ### Сравнение на конкретном примере Те же 10 документов-кандидатов, тот же запрос («Мои API-запросы продолжают возвращать 429 — как это исправить?»), меняется только метод ранжирования: | Метод ранжирования | nDCG\@3 | P\@3 | Что попало в топ-3 | | ---------------------------------------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------- | | Только векторное сходство (`text-embedding-3-small`) | 0.53 | 0.33 | Прямой ответ, **глоссарий кодов состояния 4xx**, **уведомление о техобслуживании дата-центра** | | Плюс `bge-reranker-v2-m3` | **1.00** | **1.00** | Прямой ответ, прямой ответ, объяснение exponential backoff | Векторный поиск поднял в топ-3 глоссарий HTTP-4xx и уведомление о техобслуживании с упоминанием «April 29». Оба материала тематически близки и разделяют лексику с запросом — но ни один не отвечает на него. Реранжировщик опустил оба вниз. В этом и состоит вся ценность: **он отделяет «на ту же тему» от «действительно отвечает на вопрос».** ## Информация о модели | Property | Value | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Название модели** | `bge-reranker-v2-m3` (чувствительно к регистру; при неверном названии возвращается 503) | | **Архитектура** | Cross-encoder, backbone XLM-RoBERTa-large, дообучена на bge-m3 | | **Параметры** | \~568M (0.6B) | | **Лимит контекстного окна** | **8192 token, на пару запрос-документ** (измерено: при превышении возвращается 400, без тихого усечения) | | **Языки** | Проверен правильный порядок для китайского, английского, японского, корейского, русского, французского и арабского; кросс-лингвальный retrieval работает | | **Эндпоинт** | `POST /v1/rerank` | | **Группы** | `default`, `svip` | | **Источник** | Huawei Cloud ModelArts (официальный passthrough) | | **Лицензия** | Apache 2.0 | ## Тарификация | Элемент | Цена | | ------- | ---------------------------------------- | | Вход | \$0.01 / 1M tokens | | Выход | Нет (эта модель не выдаёт output tokens) | **Достаточно дёшево, чтобы не обращать внимания.** Реранжирование 100 кандидатов (\~2,700 tokens) стоит примерно \$0.000027. Миллион таких вызовов обойдётся в \$27. Реранжирование почти никогда не становится узким местом по стоимости в системе RAG — **ограничение здесь — задержка, а не деньги**. Подбирайте размер набора кандидатов с учётом задержки, а не затрат. **Семантика использования** (измеренная): * `prompt_tokens` = запрос (учитывается один раз) плюс каждый кандидатный документ. На практике строго линейно: `≈ 26.9 × doc count + 7` (ошибка аппроксимации \< 0.31%), так что вы можете предсказывать это на стороне клиента * `total_tokens` больше, и разрыв растет с ростом числа кандидатов — это согласуется с тем, что запрос учитывается один раз для каждой пары запрос-документ * `input_tokens` / `output_tokens` на этом канале **всегда 0** — не используйте их * `top_n` и `return_documents` **не меняют использование** — каждый кандидат оценивается в любом случае В этот раз **не удалось подтвердить по записям тарификации, следуют ли начисления `prompt_tokens` или `total_tokens`** (test token не может прочитать эндпоинт баланса аккаунта). При 100 кандидатах эти два варианта отличаются примерно на 45%. Для задач, чувствительных к стоимости, считайте счёт из консоли источником истины, а не вычисляйте затраты по полям `usage`. ## Минимальный вызов ```bash cURL theme={null} curl https://api.apiyi.com/v1/rerank \ -H "Authorization: Bearer $APIYI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "bge-reranker-v2-m3", "query": "What are the must-see attractions in Hangzhou?", "documents": [ "West Lake is Hangzhou'\''s most famous attraction, known for Broken Bridge and Leifeng Pagoda.", "The Bund in Shanghai sits along the Huangpu River and is the city'\''s signature landmark.", "Lingyin Temple, in Hangzhou'\''s West Lake district, is a well-known Buddhist temple." ], "top_n": 2 }' ``` ```python Python theme={null} import os, requests resp = requests.post( "https://api.apiyi.com/v1/rerank", headers={"Authorization": f"Bearer {os.environ['APIYI_API_KEY']}"}, json={ "model": "bge-reranker-v2-m3", "query": "What are the must-see attractions in Hangzhou?", "documents": [ "West Lake is Hangzhou's most famous attraction, known for Broken Bridge and Leifeng Pagoda.", "The Bund in Shanghai sits along the Huangpu River and is the city's signature landmark.", "Lingyin Temple, in Hangzhou's West Lake district, is a well-known Buddhist temple.", ], "top_n": 2, }, timeout=60, ).json() for r in resp["results"]: print(f"{r['relevance_score']:.4f} {r['document']['text']}") ``` ```javascript Node.js theme={null} const resp = await fetch('https://api.apiyi.com/v1/rerank', { method: 'POST', headers: { Authorization: `Bearer ${process.env.APIYI_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ model: 'bge-reranker-v2-m3', query: 'What are the must-see attractions in Hangzhou?', documents: [ "West Lake is Hangzhou's most famous attraction, known for Broken Bridge and Leifeng Pagoda.", "The Bund in Shanghai sits along the Huangpu River and is the city's signature landmark.", "Lingyin Temple, in Hangzhou's West Lake district, is a well-known Buddhist temple.", ], top_n: 2, }), }); const data = await resp.json(); data.results.forEach((r) => console.log(r.relevance_score, r.document.text)); ``` Ответ: ```json theme={null} { "results": [ { "document": { "text": "West Lake is Hangzhou's most famous attraction..." }, "index": 0, "relevance_score": 0.97265625 }, { "document": { "text": "Lingyin Temple, in Hangzhou's West Lake district..." }, "index": 2, "relevance_score": 0.1181640625 } ], "usage": { "prompt_tokens": 70, "total_tokens": 91 } } ``` **`index` — это поле, которое имеет значение.** Это **исходная позиция** документа в массиве `documents`, который вы отправили. Используйте ее, чтобы найти свой объект документа (ID, URL, метаданные) — не пытайтесь сопоставлять по возвращенному `text`. ## Параметры запроса | Параметр | Тип | Обязательный | Примечания | | ------------------ | --------- | ------------ | ---------------------------------------------------------------------------------------------------------- | | `model` | string | ✓ | Всегда `bge-reranker-v2-m3`, **с учетом регистра** | | `query` | string | ✓ | Поисковый запрос. Пустая строка возвращает 400 | | `documents` | string\[] | ✓ | Кандидаты. **Только массив обычных строк.** Пустой массив возвращает 400 | | `top_n` | int | | Возвращает top N. Если параметр опущен / `0` / отрицательный, возвращается все. Не влияет на использование | | `return_documents` | bool | | ⚠️ **Не влияет на этот канал** — см. известные проблемы ниже | ## Матрица измеренных возможностей | Возможность | Результат | | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | Китайский семантический ранжирование | ✅ nDCG\@3 = 1.00 | | Устойчивость к ловушкам по ключевым словам | ✅ Top-2 корректен, но отвлекающий вариант все еще может получить очень высокий балл (см. ниже) | | Межъязыковой режим (ZH ↔ EN) | ✅ Порядок корректен, но абсолютные оценки падают на 1–2 порядка | | Многоязычный режим (JA / KO / RU / FR / AR) | ✅ Все пять вариантов отсортированы правильно | | **Понимание отрицания** | ❌ **Явная слабость**, nDCG\@3 = 0.47 (см. ниже) | | Детерминизм | ✅ Повторение запроса 10× дает бит-в-бит идентичный результат; при перемешивании кандидатов дрейф составляет лишь 3.7e-4 | | Согласованность для дублирующихся документов | ✅ Идентичные документы получают бит-в-бит идентичные оценки | | Максимум кандидатов на запрос | ✅ 2000 работает на практике; **держите значение ≤ 100** | | Максимальная длина документа | 8192 tokens на пару; при превышении возвращается 400 (без тихой усечки) | | **Квота upstream** | ⚠️ TPM 20,000 / RPM 120, примерно 4–5 параллельных слотов; около 15 поисков/мин при 100 кандидатах (см. ниже) | | `return_documents: false` | ❌ Параметр игнорируется | ## Три вещи, которые вы должны знать Инстинктивно хочется «просто отфильтровать на 0.5». **Измеренные данные показывают, что это ломает работу:** | Случай | Диапазон оценок для действительно релевантных документов | | ---------------------------------------------------------------------------- | -------------------------------------------------------- | | Китайский запрос × китайские документы | 0.289 – 1.000 (медиана 0.948) | | Одноязычные, не китайские (JA/KO/RU/FR/AR) | **0.005 – 0.998** (медиана 0.241) | | **Кросс-лингвальный (ZH ↔ EN)** | **0.0038 – 0.205** | | Нерелевантный отвлекающий документ с сильным пересечением по ключевым словам | достигал пика на **0.945** | Порог 0.5 **отбрасывал бы каждый правильный кросс-лингвальный результат** и большинство результатов, занявших второе место на не китайских языках, при этом **допуская** документ о ценах на выращивание яблок для запроса «Apple Inc. выручка за FY2024». **Что делать вместо этого**: рассматривайте это как ключ сортировки, а не как confidence. Если вам нужно фильтровать, используйте относительный порог (`score >= top1_score × 0.3`) или просто берите Top-N и калибруйте на своих размеченных данных. Запрос: «Какие достопримечательности стоит посетить зимой?» Два кандидата прямо говорят об обратном: | Ранг | Оценка | Документ | Действительно релевантно? | | ---- | ------ | -------------------------------------------------------------- | ------------------------- | | #1 | 0.811 | Harbin Ice and Snow World… лучшая зимняя достопримечательность | ✅ | | #2 | 0.769 | Beidaihe… **не подходит для зимнего туризма** | ❌ | | #3 | 0.531 | Qinghai Lake… **не рекомендуется зимой** | ❌ | | #4 | 0.375 | Wusong Island… обязательное место для посещения зимой | ✅ | | #5 | 0.289 | Sanya… популярное зимнее направление для отдыха | ✅ | Модель сопоставила тему «зима + достопримечательности + путешествия» и **не обработала отрицание**. nDCG\@3 составил всего 0.47. **Как смягчить**: для запросов с отрицанием, исключением или условиями («без глютена», «везде, кроме Beijing», «не применяется к несовершеннолетним») добавляйте LLM-проверку после reranking — не отдавайте Top-N напрямую пользователям. Одна и та же совпадающая фраза, дополненная разным количеством нерелевантного заполнителя: | Общая длина | Оценка, совпадение в **начале** | Оценка, совпадение в **конце** | | ----------- | ------------------------------- | ------------------------------ | | 528 chars | 0.933 | 0.720 | | 1028 chars | 0.931 | 0.500 | | 4028 chars | 0.907 | 0.351 | | 8028 chars | 0.828 | 0.181 | И **длина тоже завышает оценки для нерелевантных документов**: один и тот же не совпадающий документ получил 0.029 в коротком варианте и 0.121 в дополненном — в 4 раза выше. **Как смягчить**: разбивайте длинные документы на фрагменты по 200–500 символов перед reranking и берите самый высокооцененный фрагмент как оценку документа. Chunking — самый эффективный шаг предварительной обработки для этой модели. Полный метод настройки — chunking, пороги, подбор recall — описан в [RAG tuning in practice](/ru/api-capabilities/rerank/rag-best-practices). ## Известные проблемы **`return_documents` не имеет эффекта** (измерено 2026-07-30). Независимо от того, передаете ли вы `true`, `false` или вообще опускаете его, `document.text` возвращается в ответе как есть. Для нагрузок, чувствительных к пропускной способности (большие наборы кандидатов с длинными документами), ответ получается намного больше ожидаемого — сопоставляйте результаты обратно по `index` самостоятельно, вместо того чтобы полагаться на этот флаг. **Неверное имя модели возвращает 503, а не 404.** Сообщение выглядит так: `Current group default has no available channels for model xxx`. Имя **чувствительно к регистру** — `BGE-Reranker-v2-M3` считается несуществующей моделью. Если при интеграции вы получаете 503, проверьте написание, прежде чем предполагать сбой канала. **Внешняя квота — самое жесткое ограничение этой модели: планируйте свои tokenы до интеграции.** Внешний сервис (Huawei Cloud MaaS) разрешает для этой модели **TPM 20,000 / RPM 120**. У модели эмбеддингов BGE-M3 на той же платформе — 1,200,000 TPM — **в 60 раз больше**. Тестирование разделило два **независимых** механизма: | Механизм | Измеренное поведение | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Около 4–5 параллельных занятых слотов** | 10 параллельных запросов → 4 успешны; 20 параллельных запросов → 5 успешны (tokenы составляют лишь 3–4% от TPM); **20 последовательных запросов → 20/20 успешны** | | **Окно TPM 20,000 со скользящим обновлением** | Срабатывает даже при **нулевой параллельности**: при последовательной отправке запросов по 1.3K tokenов 8-й возвращает 429 при накопленных 16,093 tokenах, 9 подряд завершаются ошибкой, затем окно сдвигается и система восстанавливается | Запросы сверх лимита слотов **отклоняются сразу, а не ставятся в очередь**, и обе ошибки возвращают одинаковое сообщение `upstream load saturated` — по ответу их нельзя различить, поэтому вам нужно закладывать это в расчет нагрузки. **Рекомендация**: ограничьте параллельные запросы до 4, добавьте экспоненциальный backoff и рассчитайте пропускную способность по таблице ниже. ### Сколько поисков в минуту Если использовать измеренное `≈26.9 tokens/document` при TPM 20,000: | Кандидатов на запрос | tokenов на вызов | Теоретический предел | | -------------------- | ---------------- | -------------------- | | 50 | 673 | \~29 / мин | | 100 | 1,325 | **\~15 / мин** | | 200 | 2,629 | \~7 / мин | Это также объясняет, почему один запрос не может содержать слишком много кандидатов: 1000 кандидатов — это 26,867 tokenов, то есть **один запрос потребляет 134% всего минутного бюджета**, поэтому он гарантированно получит 429. При 2000 кандидатов это уже 269%. **Расширение квоты уже в процессе.** TPM 20,000 выше — это начальное выделение у внешнего сервиса, и APIYI уже подал заявку на его увеличение. Если ваша нагрузка превышает то, что позволяет таблица, **свяжитесь со службой поддержки APIYI, чтобы пересмотреть квоту внешнего сервиса**, вместо того чтобы уменьшать архитектуру под текущее значение. **`/v1/rerank` — единственно допустимый путь.** Запрос `/rerank` или `/v2/rerank` (значение по умолчанию в Cohere v2 SDK) возвращает **HTTP 200 с HTML главной страницы сайта**, а не JSON 404 — клиенты видят лишь непонятную ошибку разбора. Если интеграция сообщает о «неподдающемся разбору ответе», сначала проверьте `/v1`. ## Часто задаваемые вопросы Только векторный поиск: это работает, но точность Top-N заметно хуже (измеренный nDCG\@3 падает с 1.00 до 0.53). Реранжирование само по себе: **нет.** У него нет векторного вывода, и ему нужен набор кандидатов. Оценивать миллионы документов по одному ни практично, ни экономически оправданно. Стандартная схема двухэтапная: сначала отобрать 50–100 с помощью векторов/BM25 → затем реранжировать до 3–5 → передать LLM. Измеренная задержка примерно линейно зависит от числа кандидатов (короткие документы): 10 ≈ 2 с, 100 ≈ 4 с, 500 ≈ 15 с, 1000 ≈ 33 с. **50–100 — это оптимальный диапазон.** Ниже 20 у реранжировщика остается не так много ошибок в порядке, которые нужно исправлять. Выше 200 задержка уже начинает мешать интерактивности, а хвост списка кандидатов все равно редко содержит ответ. Бюджет тоже важен: 100 кандидатов — это \~1,325 token, поэтому TPM 20,000 позволяет только \~15 поисков в минуту. Удвойте число кандидатов — и вы вдвое снизите пропускную способность: **число кандидатов — это не только решение по качеству, но и решение по емкости**. **`cohere` SDK v2 не работает как есть**: он нацелен на `/v2/rerank`, который возвращает HTML главной страницы вместо JSON, поэтому SDK выдает ошибку разбора. Названия параметров (`query` / `documents` / `top_n` / `return_documents`) действительно соответствуют Cohere Rerank v1, но `documents` **принимает только массив строк** (`[{"text": "..."}]` возвращает 400), а в ответе нет полей `id` / `meta`. **Проще всего обернуть HTTP-вызов самостоятельно** — [Практическая настройка RAG](/ru/api-capabilities/rerank/rag-best-practices) содержит готовые адаптеры для LangChain и LlamaIndex. Проверенные рабочие клиенты: обычный `requests` POST ✅ и запасной вариант через SDK `openai` `client.post("/rerank", ...)` ✅. Да, и это очень стабильно. **Повторение идентичного запроса 10 раз дает побитово идентичный результат** (нулевой дрейф). Дрейф порядка \~3.7e-4 появляется только когда вы **перемешиваете порядок кандидатов** (дрожание батчинга bf16), и порядок не меняется. Привязывайте кэш к `normalised query + ordered hash of document contents`. Поскольку порядок вносит этот небольшой дрейф, **не рассматривайте `relevance_score` как ключ идемпотентности.** Вы получите 400 с `This model's maximum context length is 8192 tokens`. Он **не обрезает данные молча.** Лимит применяется к каждой паре запрос-документ, а не к запросу целиком — один запрос с 400 documents × 1000 characters (330K tokens total) возвращается нормально. ## Связанная документация * [Песочница Rerank API](/ru/api-capabilities/rerank/rerank-api) * [Практическая настройка RAG](/ru/api-capabilities/rerank/rag-best-practices) * [Текстовые embeddings](/ru/api-capabilities/text-embedding) * [Тарификация моделей](/en/models)