Ключ Rerank API выглядит как обычный ключ для чат-модели, но риск у него выше: в каждом запросе передаются поисковый запрос и текст нескольких документов-кандидатов, а оплата зависит от объёма вызовов. Если ключ утечёт, посторонний сможет израсходовать ваш баланс, а в счёте появятся незнакомые запросы.
Ниже два пути получения ключа — официальная платформа поставщика и локальный AI-шлюз, — а также настройка прав и лимитов, переменные окружения, разбор 401 и порядок ротации. Доступные модели и цены — на странице тарифов.
Примечание: Cohere, Jina AI, Alibaba Cloud, SiliconFlow, Volcano Engine и другие названия принадлежат их правообладателям и упомянуты только для технического описания. ZSQH AI Gateway не связан с этими компаниями; интерфейсы и модели — по описанию на сайте.
1. Чем ключ Rerank отличается от ключа чата
Ключ чата вызывает генеративную модель: на входе сообщения, на выходе текст. Ключ Rerank вызывает модель переранжирования: на входе запрос и набор кандидатов, на выходе оценки релевантности и порядок документов.
Отличия в трёх моментах:
- Более чувствительные данные: кандидаты часто берутся из внутренней базы знаний и могут содержать договоры, регламенты и сведения о клиентах.
- Другая тарификация: обычно считаются токены запроса и документов, а длинные тексты и большие наборы увеличивают расход.
- Более узкие права: многие платформы позволяют ограничить ключ только моделями rerank, снижая риск ошибочного использования.
Поэтому не смешивайте ключ rerank и ключ чата и не выдавайте один ключ нескольким проектам. Гранулярность ключа должна быть «среда + проект».
2. Путь A: официальная платформа поставщика
Cohere, Jina AI, Alibaba Cloud Bailian, SiliconFlow, Volcano Engine и другие платформы предоставляют сервис переранжирования. Входы и поля различаются, но порядок действий похож:
- Выберите платформу: уточните поддерживаемые языки, максимальную длину документа, поддержку китайского и то, покидают ли данные страну.
- Зарегистрируйте аккаунт: локальные платформы часто требуют телефон или корпоративную верификацию, зарубежные — email и способ оплаты.
- Активируйте сервис: найдите в консоли Rerank или сервис переранжирования и убедитесь, что нужная модель доступна.
- Создайте ключ: откройте страницу API Keys и создайте секрет с именем по схеме «проект-среда», например
rag-prod. - Задайте ограничения: лимит, срок действия и, если возможно, только модели rerank.
- Сразу проверьте: после копирования выполните минимальный запрос и убедитесь, что аутентификация, имя модели и структура ответа корректны.
Заголовки аутентификации у платформ различаются. Cohere и Jina обычно используют Authorization: Bearer <key>, часть локальных платформ — собственную подпись. Не пишите заголовки по памяти, сверяйтесь с текущей официальной документацией.
3. Путь B: через ZSQH AI Gateway
Если у команды нет зарубежного способа оплаты или нужно объединить счета по нескольким моделям, можно использовать шлюз:
- Откройте ZSQH AI Gateway и пройдите регистрацию.
- В консоли перейдите на страницу «API-ключи» и создайте ключ.
- Укажите название, выберите проект или группу, задайте лимит и срок действия.
- Пополните кошелёк и убедитесь, что баланса достаточно для тестов.
- Скопируйте ключ в менеджер паролей, не оставляйте его в переписке.
Шлюз предоставляет переранжирование как POST /v1/rerank и совместим с /rerank; Base URL — https://ai.zhongshangqihang.com/v1. Важно: Rerank не входит в спецификацию OpenAI Chat Completions, это отдельная конечная точка, и методы SDK для чата к ней напрямую не применимы.
| Параметр | Официальная платформа | ZSQH AI Gateway |
|---|---|---|
| Регистрация и оплата | Зарубежные платформы обычно требуют иностранную карту, локальные — верификацию | Локальная регистрация и пополнение, способы — по странице расчётов |
| Сеть | Зарубежные точки могут быть нестабильны | Прямое подключение из Китая, меньше сетевой диагностики |
| Покрытие моделей | Только модели этого поставщика | Единый вход к нескольким upstream, по списку моделей |
| Счёт | Отдельная сверка по каждому поставщику | Объединённый счёт по моделям, удобно для отчётности |
| Путь данных | Запрос идёт напрямую к поставщику | Передача через шлюз, проверьте условия обработки данных |
| Кому подходит | Один поставщик и поддержка производителя | Несколько моделей, локальная команда, единая эксплуатация |
Пути могут сосуществовать. Частая практика — держать официальный аккаунт как резерв, а локальную команду и тестовую среду вести через шлюз. Перед выбором уточните сторону договора, тип счёта и условия обработки данных.
4. Четыре настройки безопасности при создании ключа
Получить ключ — только начало. Настройки при создании определяют границы ущерба в случае проблемы.
Первое: разделяйте по средам. Для разработки, тестов и продакшена используйте разные ключи, а в имени указывайте проект и дату. Так при разборе счёта сразу виден источник, а при утечке достаточно отозвать один ключ.
Второе: задайте лимит. Установите дневной или месячный лимит на каждый ключ и хотя бы один порог оповещения. Расход Rerank напрямую зависит от числа и длины документов, и один цикл в скрипте может за короткое время создать множество запросов.
Третье: задайте срок действия. Тестовым ключам — короткий срок, продакшен-ключам — ротация по регламенту команды. Для временных ключей подрядчикам или партнёрам автоматическое истечение надёжнее ручного отзыва.
Четвёртое: минимальные права. Если платформа поддерживает ограничение моделей, белый список IP или группы проектов, откройте только модели rerank и необходимые адреса. Не выдавайте ключу доступ ко всем моделям ради удобства.
5. Переменные окружения и чтение в коде
Ключ должен храниться только в серверных переменных окружения или менеджере секретов, не в репозитории и не во фронтенд-сборке. Минимальная конфигурация:
RERANK_API_KEY=sk-ваш-ключ
RERANK_BASE_URL=https://ai.zhongshangqihang.com/v1
Добавьте .env в .gitignore, а при развёртывании передавайте значения через панель переменных окружения платформы. Пример чтения на Python:
import os
import requests
api_key = os.environ["RERANK_API_KEY"]
base_url = os.environ.get("RERANK_BASE_URL", "https://ai.zhongshangqihang.com/v1")
resp = requests.post(
f"{base_url}/rerank",
headers={"Authorization": f"Bearer {api_key}"},
json={
"model": "имя-вашей-модели-rerank",
"query": "Какова длительность пробного периода?",
"documents": ["Пробный период составляет 14 дней.", "Поддерживается оплата по счёту."],
"top_n": 2,
},
timeout=20,
)
resp.raise_for_status()
print(resp.json()["results"])
Имя модели смотрите на странице тарифов. Если команда использует менеджер секретов, храните ключ в зашифрованном виде и внедряйте во время выполнения, не печатайте его в логах. При диагностике можно выводить request ID и код состояния, но не полный заголовок Authorization.
6. Разбор 401: сначала аутентификация, потом права
401 означает, что личность не распознана; 403 — что личность распознана, но прав недостаточно. Многие шлюзы приводят оба случая к одной структуре ошибки, поэтому смотрите тело ответа и код ошибки, а не только HTTP-статус.
| Симптом | Частая причина | Что делать |
|---|---|---|
| 401 (ошибка аутентификации) | Ключ с опечаткой, лишние пробелы, обрезан при копировании | Скопируйте заново, проверьте отсутствие перевода строки |
| 401 invalid token | Ключ удалён, истёк или принадлежит другому проекту | Проверьте статус в консоли и создайте новый |
| 401 при верном ключе | Ошибка в имени заголовка или Base URL указывает на другой сервис | Сверьте Authorization и путь с документацией |
| 403 Forbidden | У ключа нет прав на модель или аккаунт заблокирован | Проверьте область моделей и статус аккаунта |
| 404 Not Found | Неверное имя модели или путь | Сверьте /v1/rerank и список моделей |
| 429 Too Many Requests | Слишком высокий параллелизм или достигнут лимит | Повтор с экспоненциальной задержкой, проверка лимитов |
Порядок диагностики стоит зафиксировать: сначала URL и заголовки, затем статус ключа, затем имя модели, в конце — баланс и ограничения скорости. Оформите эти четыре шага как чек-лист — это быстрее, чем каждый раз действовать наугад.
7. Ротация и обработка утечки
Ротация ключей нужна не только после инцидента. Меняйте ключи по регулярному графику, а также сразу при увольнении сотрудника, случайном коммите в репозиторий или появлении полного ключа в логах.
- Создайте в консоли новый ключ с датой ротации в имени.
- Сначала пропишите новый ключ в тестовой среде и выполните минимальный запрос.
- Обновите переменные продакшена и перезапустите сервис, наблюдая за ошибками и объёмом вызовов.
- Убедившись, что у старого ключа нет трафика, отключите или удалите его.
- Просмотрите журналы последних вызовов, проверьте отсутствие посторонних источников и аномальных пиков.
- Зафиксируйте дату ротации и внесите следующую в календарь команды.
Если есть подозрение на утечку, сначала отключите старый ключ, затем проверьте счёт и журналы; не удаляйте логи первыми — доказательства помогают оценить масштаб. После ротации проверьте историю репозитория, переменные CI и переписку, чтобы не осталось других копий.
8. Частые вопросы
Может ли ключ Rerank вызывать чат-модели?
Зависит от платформы. Даже если технически возможно, делать так не стоит. Ключ переранжирования должен использоваться только для конечной точки rerank, чтобы один ключ не нёс сразу два типа расходов.
Можно ли хранить ключ во фронтенде или мини-приложении?
Нет. Код фронтенда и сетевые запросы видны пользователю, поэтому ключ фактически становится публичным. Правильный вариант — фронтенд обращается к вашему бэкенду, а ключ хранится и используется на сервере.
Чем 401 отличается от 403?
401 — ошибка аутентификации: ключ недействителен, истёк или заголовок неверен. 403 — недостаточно прав: ключ может быть валиден, но не иметь доступа к модели или проекту. Сначала смотрите code и message в теле ошибки.
Можно ли использовать один ключ в нескольких проектах?
Технически обычно можно, но с точки зрения эксплуатации не рекомендуется. Общий ключ не позволяет разделить счёт, а при утечке пострадает больше систем. Как минимум разделяйте ключи по среде и проекту.
Как часто ротировать ключ?
По регламенту безопасности команды. Частая практика — регулярная ротация, а также немедленная при смене персонала, подозрении на утечку и случайном коммите. Единого норматива нет; главное — чтобы процедура была выполнимой.
