GLM API Key — это учётные данные для вызова моделей GLM от Zhipu. На вид это просто строка символов, но она определяет три вещи: пройдёт ли запрос аутентификацию, на какой счёт будут отнесены расходы и насколько велик риск при утечке. Многие сбои подключения связаны не с моделью или сетью, а с неверным типом ключа, неправильным хранением или отсутствием ротации.
Статья разбирает порядок «выбор типа — создание — хранение — ротация — диагностика», два пути получения ключа — официальную платформу и ZSQH AI Gateway — и даёт чек-лист безопасной настройки, который можно применить сразу.
Примечание: Zhipu, GLM и BigModel — товарные знаки их правообладателей. Статья носит технический характер; мы не аффилированы с Zhipu, не являемся её агентом и не действуем по её поручению. Порядок создания ключей, требования аутентификации и правила тарификации определяются документацией Zhipu Open Platform.
1. Сначала определите, какой тип ключа вам нужен
Платформа Zhipu раздельно управляет ключами личных тарифов, командных тарифов и стандартного API моделей. Они не взаимозаменяемы. Если не определить назначение до создания, легко получить ситуацию «ключ действителен, но вызов не проходит».
- Ключ стандартного API моделей — для серверных сервисов, скриптов, агентов и пакетных задач; оплата по фактическому объёму вызовов. Большинство технических подключений относится к этой категории.
- Ключ Coding Plan — для инструментов программирования вроде Claude Code; он использует права тарифного плана и не предназначен для вызова обычных бизнес-интерфейсов.
- Командные и корпоративные ключи — для совместной работы и централизованного управления; права и принадлежность счетов отличаются от личных ключей.
Если отправить ключ Coding Plan в стандартный API, типичный результат — сбой аутентификации или сообщение об отсутствии у тарифа прав на эту модель. При такой ошибке сначала проверьте тип продукта ключа, затем — полностью ли он скопирован.
2. Создание ключа на платформе Zhipu
Официальный путь подходит командам, которые используют только GLM и хотят первыми получать новые модели и функции. Основные шаги:
- Откройте платформу Zhipu Open Platform, зарегистрируйтесь и войдите.
- Перейдите на страницу API Keys в консоли и убедитесь, что находитесь в нужном проекте или пространстве.
- Нажмите создание ключа и назовите его по схеме «окружение — сервис», например
prod-customer-service. - Скопируйте ключ целиком и сразу сохраните в менеджере паролей или серверной системе управления секретами.
- На странице финансов проверьте баланс или состояние ресурсного пакета, чтобы ключ не оказался создан при нулевом доступном лимите.
- Проверьте ключ минимальным запросом и только после этого вносите его в рабочую конфигурацию.
Учтите два момента: обычно ключ полностью показывается только при создании, и после закрытия страницы посмотреть его снова может быть нельзя; требования верификации личности и компании меняются вместе с продуктом и политикой — ориентируйтесь на подсказки страницы и документацию.
3. Создание ключа через шлюз
Если команда использует несколько моделей одновременно либо хочет единые квоты, единый счёт и единые счета-фактуры, можно зарегистрироваться в ZSQH AI Gateway. В разделе API-ключей создайте ключ, задайте лимит расходов и срок действия, затем на странице цены на модели уточните доступные модели линейки GLM и способ тарификации.
Ключ шлюза действует только с Base URL ZSQH и не подходит для официального адреса Zhipu; обратное тоже верно — официальный ключ нельзя напрямую использовать в шлюзе. Раздельные имена и раздельное хранение двух наборов ключей — самый простой способ избежать путаницы.
4. Хранение ключа в переменных окружения
Самый опасный вариант — записать ключ в исходный код, фронтенд-бандл или переписку. Используйте переменные окружения или сервис управления секретами, чтобы код ссылался только на имя переменной.
# .env хранится только локально и добавлен в .gitignore
GLM_API_KEY=your_key_here
GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("GLM_API_KEY"),
base_url=os.getenv("GLM_BASE_URL"),
)
Минимальные требования при внедрении: .env не попадает в Git; в продакшене используются Secret Manager, KMS облачного провайдера или секреты платформы оркестрации контейнеров; CI/CD применяет отдельные зашифрованные переменные; в логах заголовок Authorization маскируется; серверный ключ никогда не появляется во фронтенд-коде.
5. Изоляция прав, ротация и аудит
Один ключ на всё удобен на коротком горизонте, но плохо диагностируется на длинном. Рекомендуется разделение по схеме ниже.
| Практика | Какую проблему решает | Как внедрить |
|---|---|---|
| Разделение теста и продакшена | Тестовый трафик загрязняет счета, риск случайного удаления данных | Два ключа и две квоты |
| Отдельный ключ на сервис | Нельзя определить источник вызовов | Именование по сервису или репозиторию |
| Лимит расходов | Аномальные вызовы быстро сжигают бюджет | Настроить лимиты и оповещения в консоли |
| Регулярная ротация | Долгосрочный риск утечки | Ротация раз в квартал, при передаче дел — немедленный отзыв |
| Хранение журнала вызовов | Разбор инцидентов и споров | Время, модель, расход; без ключа в открытом виде |
При ротации не удаляйте старый ключ сразу. Сначала создайте новый, постепенно переведите на него трафик, убедитесь, что квоты, права на модели и счета в порядке, и только затем отзовите старый. Так при проблеме с новой конфигурацией останется быстрый путь отката.
6. Ошибка 401 и другие частые ответы
HTTP 401 означает лишь «аутентификация не пройдена»; конкретная причина видна по бизнес-коду в теле ответа. В официальных кодах Zhipu 1000 означает непройденную проверку подлинности, 1001 — отсутствие данных аутентификации в заголовке запроса, 1003 — истёкший токен, 1005 — включённую двухфакторную аутентификацию аккаунта. Проверяйте по порядку:
- Убедитесь, что заголовок имеет вид
Authorization: Bearer <key>, без лишних пробелов и кавычек. - Убедитесь, что скопирован полный ключ, а не его название или маска.
- Убедитесь, что тип ключа соответствует интерфейсу: стандартный API и ключи тарифов нельзя смешивать.
- Убедитесь, что Base URL соответствует владельцу ключа: официальный ключ — официальный адрес, ключ шлюза — адрес шлюза.
- Проверьте состояние аккаунта: задолженность возвращает 1113, ограничение частоты — 1302 или 1305.
Кроме того, 1211 означает, что модель не существует, — обычно из-за опечатки в имени или неактивированной модели; 1261 означает слишком длинный ввод, нужен сжатый контекст или разбиение на части. Если писать бизнес-код в лог, диагностика ускоряется заметно.
7. Чек-лист перед запуском
- Ключ существует только на сервере или в сервисе управления секретами.
- Тест, продакшен и CI используют разные ключи.
- У каждого ключа есть лимит расходов и ответственный.
- Настроены оповещения о низком балансе и резком росте потребления.
- Проведена тренировка отзыва и замены ключа.
- В логах нет полных ключей, номеров телефонов и других чувствительных данных.
- При увольнении или передаче дел сотрудника соответствующие ключи отозваны.
8. Частые вопросы (FAQ)
1. Где создать ключ GLM API?
После входа на Zhipu Open Platform — на странице API Keys в консоли. При использовании ZSQH AI Gateway ключ создаётся в разделе API-ключей консоли шлюза; два набора ключей не взаимозаменяемы.
2. Можно ли разместить ключ во фронтенде или мини-приложении?
Нет. Код фронтенда доступен пользователю, поэтому любой ключ, записанный во фронтенд, следует считать скомпрометированным. Правильный вариант: фронтенд обращается к вашему бэкенду, а бэкенд хранит ключ и проксирует вызовы модели.
3. Можно ли использовать один ключ в нескольких проектах?
Технически можно, но не рекомендуется. Общий ключ не позволяет разделить источники вызовов, одна утечка затрагивает весь бизнес, а счета трудно распределить. Как минимум разделите ключи по сервисам и окружениям.
4. Что делать при утечке ключа?
Немедленно отзовите или удалите ключ в консоли, создайте новый и обновите серверную конфигурацию. Одновременно проверьте счета и журналы вызовов на аномальное потребление; при необходимости сообщите в поддержку платформы.
5. Можно ли смешивать официальный ключ и ключ шлюза?
Нет. У них разные системы аутентификации, Base URL и счета. Самое частое проявление смешивания — 401, реже — запрос уходит на неверный адрес сервиса.
