Qwen API Key — учётные данные для вызова моделей Tongyi Qianwen. Это не просто строка-пароль: от типа и принадлежности ключа зависит, пройдёт ли запрос аутентификацию, на какой аккаунт попадёт стоимость и насколько быстро удастся найти причину сбоя. Ключ Qwen дополнительно привязан к двум сущностям — региону и бизнес-пространству; именно здесь часто кроется причина «ключ вроде верный, а возвращается 401».
Статья последовательно разбирает путь «понять принадлежность — создать — настроить права — сохранить в переменных — устранить ошибку — выполнить ротацию» для официального пути Alibaba Cloud Model Studio и для ZSQH AI Gateway.
Примечание: Qwen, Tongyi Qianwen, Alibaba Cloud, Bailian (Model Studio) и DashScope — товарные знаки или названия продуктов Alibaba Group и связанных компаний. Статья носит технический характер и не подразумевает аффилированности, агентских отношений или авторизации со стороны Alibaba Group. Порядок создания, правила прав и биллинга определяются официальной документацией и консолью Alibaba Cloud Model Studio.
1. Сначала поймите три уровня принадлежности ключа
В Bailian ключ одновременно принадлежит трём измерениям:
- аккаунту: это может быть основной аккаунт Alibaba Cloud или пользователь RAM;
- региону: Пекин, Сингапур, Вирджиния (США), Гонконг и другие регионы независимы;
- бизнес-пространству: пространство по умолчанию или дочернее, которое определяет доступные ключу модели.
Несовпадение любого из трёх измерений проявляется как сбой аутентификации или нехватка прав. Особенно важен регион: у каждого региона свой домен, API Key и список моделей, ключ нельзя использовать в другом регионе. Ключ, созданный в Пекине, при запросе к сингапурскому адресу обычно вернёт 401 и invalid_api_key, хотя сам ключ не утратил силу.
2. Создание API Key в Alibaba Cloud Model Studio
Официальный путь подходит командам, которые используют только Qwen и хотят первыми получать новые модели и возможности. Основные шаги:
- Войдите в консоль Alibaba Cloud Model Studio и выберите правильный регион в правом верхнем углу.
- Перейдите на страницу API Key и нажмите «Создать API Key».
- Выберите аккаунт-владелец: по умолчанию основной аккаунт Alibaba Cloud, можно указать пользователя RAM.
- Выберите бизнес-пространство: пространство по умолчанию подходит для быстрого старта; для изоляции моделей или затрат выберите дочернее.
- Настройте права: рекомендуется сначала «Все»; при необходимости ужесточения выберите «Пользовательские», задайте белый список IP и доступные модели.
- Сразу после создания скопируйте полный ключ и выданный на странице API Host, сохраните в менеджере паролей или серверной системе управления секретами.
- Проверьте минимальным запросом, что аутентификация, регион и имя модели верны, и только затем записывайте в рабочую конфигурацию.
Две детали легко упустить. Во-первых, для создания ключа нужны права супер-администратора или администратора бизнес-пространства; обычный участник может не видеть кнопку создания. Во-вторых, открытый ключ обычно показывается полностью только один раз при создании; после закрытия окна его нельзя увидеть снова. Если не сохранили — придётся сбросить или создать новый. Долгосрочный ключ не истекает автоматически, но «не истекает» не означает «не нужно ротировать».
3. Бизнес-пространство, RAM и границы прав
Бизнес-пространство — основа модели прав Bailian. Ключ пространства по умолчанию может вызывать стандартные модели этого пространства; ключ дочернего пространства — только модели, разрешённые в этом пространстве. Если вы развернули дообученную модель, используйте ключ того пространства, где она находится, иначе возникнет ситуация «модель есть, но доступа нет».
Правила для пользователей RAM требуют особого внимания:
- ключ может принадлежать пользователю RAM, формат аккаунта обычно
username@<AccountAlias>.onaliyun.com; - если удалить пользователя или роль в консоли RAM, все его ключи немедленно перестанут действовать без возможности восстановления;
- если исключить пользователя RAM из бизнес-пространства, ключ перестанет работать; после повторного добавления действие возобновится.
Пользовательские права подходят для продакшена: белый список IP ограничивает источник, а область моделей — доступные модели. Белый список поддерживает IPv4 и IPv6, но IPv6 сейчас доступен только в Пекине, а в регионе США поддерживается только IPv4; предельное число записей определяется консолью. Ключи тарифных пакетов (например, начинающиеся с sk-sp-) и универсальные API Key — две разные системы; не используйте ключ пакета с универсальным Base URL.
4. Поместите ключ в переменные окружения
Самая опасная практика — записывать ключ в исходники, фронтенд-бандл, вывод Notebook или переписку. В Bailian принято имя переменной DASHSCOPE_API_KEY; код ссылается только на имя:
# Локальный файл .env, добавьте его в .gitignore
DASHSCOPE_API_KEY=your_key_here
# Временное действие в текущем терминале
export DASHSCOPE_API_KEY="your_key_here"
# Минимальная проверка: ключ, регион и имя модели совпадают
curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"qwen3.8-max","messages":[{"role":"user","content":"ping"}]}'
В продакшене как минимум: не коммитьте .env в Git; используйте Secret Manager, KMS или контейнерные Secret; в CI/CD применяйте отдельные переменные; маскируйте заголовок Authorization в журналах; фронтенд никогда не хранит серверный ключ. Учтите, что названия моделей и цены в примере меняются с версиями; актуальные названия и биллинг — в списке моделей консоли и на странице цены на модели.
5. Официальный ключ или ключ шлюза
Если команда использует только Qwen, официальный ключ — самый прямой вариант. Если одновременно используются Qwen, DeepSeek, GLM, Kimi и другие модели либо нужны единые квоты, счета и документы, можно создать ключ в ZSQH AI Gateway. Это не взаимоисключающие варианты, а два способа управления.
| Критерий | Официальный ключ Alibaba Cloud Model Studio | Ключ ZSQH AI Gateway |
|---|---|---|
| Точка создания | Консоль Model Studio | Консоль шлюза |
| Область применения | Qwen и сторонние модели в регионе Bailian | Модели, подключённые к шлюзу |
| Платёжный аккаунт | Аккаунт Alibaba Cloud | Аккаунт шлюза |
| Base URL | dashscope.aliyuncs.com и другие адреса Bailian |
https://ai.zhongshangqihang.com/v1 |
| Подходящий сценарий | Только Qwen, нужны новейшие модели | Несколько моделей и единый счёт |
Системы аутентификации разных ключей несовместимы: официальный ключ — с официальным Base URL, ключ шлюза — с адресом шлюза. Самое частое проявление смешивания — 401, затем запрос уходит в неверный регион или сервис.
6. Разбор 401: сначала регион, затем заголовки
При 401 не спешите переустанавливать SDK. Проверяйте по порядку:
- Заголовок
Authorization: Bearer <key>и ровно один пробел послеBearer. - Ключ скопирован полностью, без перевода строки, кавычек и пробелов по краям.
- Регион создания ключа совпадает с регионом Base URL.
- Бизнес-пространство совпадает; домен пространства принимает только его собственные ключи.
- Ключ не отключён, не удалён и не сброшен; создатель RAM не исключён из пространства и не удалён.
- Ключ пакета с префиксом
sk-sp-не используется с универсальным интерфейсом. - У аккаунта нет задолженности. Задолженность обычно возвращает 400 и
Arrearage, а не 401, но тоже выглядит как «не работает».
Если всё в порядке, зафиксируйте Request ID из ответа и проверьте журнал вызовов или мониторинг модели в консоли. Request ID — самая полезная информация для тикета, гораздо полезнее слов «выдаёт ошибку».
7. Ротация, отзыв и аудит
Один ключ на всё удобен на коротком горизонте, но плохо разбирается на длинном. Делите как минимум по средам и сервисам: тест, продакшен и CI — отдельные ключи; каждый бэкенд-сервис — свой; имя ключа включает среду и сервис, например prod-customer-service. Добавьте лимиты и оповещения о расходе, чтобы аномальные вызовы обнаруживались до сжигания значительной квоты.
При ротации не удаляйте старый ключ сразу. Правильный порядок: создать новый ключ → перевести небольшую часть трафика → убедиться, что права на модели, квоты и счета в норме → отозвать старый. Так при проблеме с новой конфигурацией останется быстрый откат. При увольнении, передаче подрядчику или появлении ключа в журналах и публичном репозитории немедленно отзывайте и пересоздавайте ключ, проверяя счета и журналы на аномалии.
8. Часто задаваемые вопросы
1. Где создать ключ Qwen API?
Войдите в консоль Alibaba Cloud Model Studio, выберите регион и создайте ключ на странице API Key. При использовании ZSQH AI Gateway ключ создаётся в консоли шлюза; ключи несовместимы.
2. Почему действующий ключ возвращает 401?
Самая частая причина — несовпадение региона, затем неполное копирование ключа, неверный формат заголовка, несовпадение бизнес-пространства или удаление создателя RAM. Сначала сверьте регион ключа и Base URL, затем проверьте заголовки.
3. Можно ли использовать один ключ в нескольких проектах?
Технически можно, но не рекомендуется. Общий ключ не позволяет различить источник вызовов, одна утечка затрагивает весь бизнес, а счета трудно разделить. Как минимум делите по средам и ключевым сервисам.
4. Что делать при утечке ключа?
Немедленно отключите или удалите ключ в консоли, создайте новый и обновите серверную конфигурацию; проверьте счета и журналы на аномальный расход; при необходимости обратитесь в поддержку. Не ограничивайтесь правкой кода без отзыва старого ключа.
5. Можно ли смешивать официальный ключ и ключ шлюза?
Нет. У них разные системы аутентификации, Base URL и платёжные аккаунты. Смешивание обычно даёт 401 и может отправить запрос на неверный адрес сервиса.
