На большинстве платформ ключ Embedding API ничем не отличается от ключа чат-модели: это лишь удостоверение личности, а реальные права определяются настройками аккаунта и параметрами модели в запросе. Но векторизация часто работает в фоне и обрабатывает большие массивы документов, поэтому утечка или неверная настройка ключа обходится дорого и трудно диагностируется.

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

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

1. Сначала выясните: нужен ли Embedding отдельный ключ

Большинство OpenAI-совместимых платформ используют единую авторизацию: один и тот же ключ вызывает и /v1/chat/completions, и /v1/embeddings. Доступность зависит от баланса, прав на модель и политики платформы, а не от типа ключа.

Некоторые платформы тарифицируют или авторизуют векторный сервис отдельно. Перед созданием ключа проверьте в консоли три вещи:

  • покрывает ли текущий тариф или баланс embedding-модель;
  • есть ли у ключа белый список моделей или ограничение по проекту;
  • общий ли лимит у embedding и чата.

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

2. Регистрация и вход в консоль

На примере ZSQH AI Gateway:

  1. Откройте https://ai.zhongshangqihang.com, зарегистрируйтесь по электронной почте и подтвердите адрес.
  2. Войдите в консоль и найдите страницу «API-ключи».
  3. На странице «Кошелёк» или «Пополнение» проверьте баланс; для тестов достаточно небольшой суммы.
  4. Откройте «Журнал использования» и убедитесь, что видны модель, токены и расходы.

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

3. Что указывать при создании ключа

При нажатии «Создать ключ» обычно появляются поля:

  1. Название. Укажите назначение и среду, например rag-prod-backend или embedding-batch-dev. Не используйте имена вроде «тест1».
  2. Лимит. Сначала поставьте низкое значение и повысьте его, когда увидите реальный расход батч-задач.
  3. Срок действия. Для временных скриптов — 7 или 30 дней; у производственного ключа тоже должен быть фиксированный цикл ротации.
  4. Область модели или проекта. Если платформа поддерживает, отметьте только embedding-модели и нужные проекты.
  5. Сохранить и скопировать. Полный ключ обычно показывается один раз; не сохранили — придётся удалять и создавать заново.

Ключи часто начинаются с sk-, но префикс не является доказательством подлинности. При копировании следите, чтобы не попали пробелы или перевод строки в начале и конце, — это одна из частых причин 401.

4. Как проектировать права и лимиты

Векторизация — это «много чтения, мало записи, пакетные запуски и частые повторы». Цель разделения прав — не защита от внешней атаки, а недопущение ситуации, когда один ключ влияет на все среды.

Сценарий Имя ключа Лимит Где хранить Ротация
Локальная разработка emb-dev-имя Минимальный Локальный .env 30 дней
Тестовая среда emb-staging Низкий Секреты CI/CD 60 дней
Производственные батчи emb-prod-batch По бюджету Сервис управления секретами 90 дней
Производственные запросы emb-prod-query По бюджету Сервис управления секретами 90 дней

Несколько принципов:

  • Разделяйте разработку и производство. Утечка тестового ключа не должна влиять на производственный счёт.
  • Разделяйте батчи и запросы. Батч-задачи часто повторяются; отдельный лимит помогает локализовать аномальный расход.
  • Минимальные права. Если можно включить только embedding, не включайте чат-модели; если можно ограничить проект, не выдавайте права уровня аккаунта.
  • Не вставляйте ключ во фронтенд. Ключ в браузере, приложении или мини-программе обязательно будет извлечён; запросы векторизации должны идти через ваш backend.
  • Не используйте общий личный ключ. При увольнении сотрудника или потере устройства общий ключ нельзя отключить отдельно.

5. Хранение ключа в переменных окружения

Не прописывайте ключ прямо в коде. В Python его можно читать так:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.embeddings.create(
    model="text-embedding-3-small",
    input=["Первый фрагмент текста", "Второй фрагмент текста"],
)
print(len(resp.data[0].embedding))

При локальном использовании .env добавьте файл в .gitignore и коммитьте только .env.example. В производстве используйте секреты контейнера, облачный менеджер секретов или Vault; не записывайте ключ в Dockerfile, слои образа, артефакты фронтенд-сборки или журналы CI.

Учтите: после изменения переменных окружения процесс нужно перезапустить. Частая причина ситуации «локально работает, в производстве 401» — сервис читает старые переменные или платформа развёртывания не передала их в рабочую среду.

6. Порядок разбора ошибки 401

При 401 Unauthorized проверяйте в таком порядке — обычно причина находится за несколько минут:

  1. Убедитесь, что заголовок имеет вид Authorization: Bearer sk-..., между Bearer и ключом ровно один пробел.
  2. Скопируйте ключ заново и проверьте отсутствие пробелов, переводов строки, кавычек и невидимых символов.
  3. Убедитесь, что ключ не удалён, не отключён и не истёк.
  4. Проверьте, что ключ относится к платформе, которой соответствует Base URL: не отправляйте ключ платформы A на платформу B.
  5. Убедитесь, что процесс действительно прочитал переменную окружения, а не пустую строку.
  6. Проверьте, не переписывает ли заголовок Authorization reverse proxy, шлюз или SDK.
  7. Если падают только отдельные запросы, проверьте, не был ли ключ остановлен системой безопасности после попадания во фронтенд-код.

Дополнение: 401 — это проблема идентификации, 403 чаще связан с правами или регионом, 429 — с частотой или квотой. Не приписывайте все сбои ключу.

7. Официальный ключ или ключ шлюза

Оба пути рабочие; разница — в закупке, сети и поддержке:

  • Прямой официальный доступ. Аккаунт, счета и модели администрирует вендор. Подходит командам с зарубежным платёжным каналом и возможностью самостоятельно решать сетевые и комплаенс-вопросы. Минус — модели распределены по разным платформам, ключи и сверка тоже разделены.
  • Доступ через шлюз. Один Base URL и один ключ для нескольких моделей, проще доступ и расчёты в юанях, централизованные журналы и лимиты. Цена — дополнительный слой зависимости: нужно проверить политику данных, доступность и порядок работы с инцидентами.

При выборе не смотрите только на цену. Как минимум уточните: сохраняются ли данные, есть ли счета, как сообщают о сбоях, публикуют ли заранее вывод моделей из эксплуатации и можно ли выгрузить журнал расхода. Актуальные модели и цены смотрите на странице тарифов; цены меняются, не закладывайте в бюджет цифры из старых статей.

8. Ротация и действия при утечке

Ротацию лучше сделать регулярным действием, а не реакцией на инцидент:

  1. Создайте на исходной платформе новый ключ с теми же правами.
  2. Обновите значение в переменных окружения или менеджере секретов.
  3. Перезапустите или переразверните сервис и выполните один запрос к embedding, чтобы подтвердить успех.
  4. Понаблюдайте за журналом использования 24–48 часов.
  5. Удалите старый ключ и зафиксируйте дату ротации.

При подозрении на утечку порядок обратный: сначала отключите старый ключ, затем изучите журнал использования и историю репозитория, и только потом создавайте новый. Удалить строку из кода недостаточно: ключ мог попасть в журналы CI, слои образа или сторонний кеш.

Частые вопросы

Обязательно ли отдельный ключ для Embedding?

Нет. Большинство OpenAI-совместимых платформ позволяют одним ключом вызывать и embedding, и чат. Отдельный ключ нужен, если вы хотите разделить лимиты, аудит или отключение.

Можно ли увидеть полный ключ после создания?

Обычно нет. Полное значение показывается только при создании, затем остаётся префикс или маска. Если не сохранили — удалите и создайте заново, не пытайтесь найти ключ в журналах.

Можно ли одним ключом вызывать несколько embedding-моделей?

Как правило да, модель указывается в поле model запроса. Доступные модели и размерность смотрите в документации платформы и на странице тарифов.

Локальный curl работает, а в производстве 401. Почему?

Проверьте три вещи: переданы ли переменные окружения в производственной среде, сохраняет ли reverse proxy заголовок Authorization, не используется ли в производстве другой — удалённый или просроченный — ключ. Затем проверьте, правильный ли Base URL.

Достаточно ли удалить ключ после утечки?

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

Что дальше

Если аккаунта ещё нет, начните со страницы регистрации, создайте ключ с низким лимитом и отправьте один текст в /v1/embeddings. После успешного запроса выберите рабочую модель на странице тарифов. Про сам процесс векторизации читайте в статье о подключении.

Читайте также: