Qwen API предоставляет Alibaba Cloud Model Studio (Bailian), а DashScope — её нативная система интерфейсов. Model Studio даёт и OpenAI-совместимый интерфейс, и нативный DashScope. Большинству команд проще начать с OpenAI-совместимого: существующие SDK, агентные фреймворки и инструменты обычно требуют изменить три вещи — API-ключ, Base URL и имя модели.
Настоящие ловушки не в том, «получится ли вызвать», а в регионе Base URL, действующем имени модели, разборе потокового вывода и параметрах, которые нельзя бездумно переносить из OpenAI. Ниже минимальный запрос, который проходит цепочку, затем вызов инструментов, разбор ошибок и чек-лист миграции.
Примечание: Qwen, Tongyi Qianwen, Alibaba Cloud, Model Studio (Bailian) и DashScope — товарные знаки или названия продуктов Alibaba Group и связанных компаний; статья носит технический характер и не подразумевает аффилированность, агентские или лицензионные отношения с Alibaba Group. Base URL, имена моделей, контекст и тарификация могут меняться; сверяйтесь с официальной документацией Alibaba Cloud Model Studio и страницей тарифов.
1. Подготовка
Перед началом проверьте три вещи:
- Рабочий API-ключ, соответствующий целевому региону.
- Правильный Base URL: материковый Китай, международный сайт и адрес шлюза нельзя смешивать.
- Актуальное действующее имя модели, а не пример из старой статьи.
Сначала проверьте аутентификацию и сеть через curl, затем подключайте SDK. Так при ошибке легче понять, в чём проблема: в ключе, адресе или коде.
2. Base URL: сначала регион, потом домен
Путь OpenAI-совместимого интерфейса фиксирован — /compatible-mode/v1, к нему добавляется /chat/completions. Домен зависит от региона:
| Сценарий | OpenAI-совместимый Base URL | Пояснение |
|---|---|---|
| Материковый Китай (Пекин, старый общий домен) | https://dashscope.aliyuncs.com/compatible-mode/v1 |
Совместим со старым кодом, пока работает |
| Сингапур (международный сайт) | https://dashscope-intl.aliyuncs.com/compatible-mode/v1 |
Аккаунт и ключ международного сайта |
| Вирджиния, США | https://dashscope-us.aliyuncs.com/compatible-mode/v1 |
Только IPv4, возможности по документации |
| Гонконг | https://cn-hongkong.dashscope.aliyuncs.com/compatible-mode/v1 |
Отдельный регион и ключ |
| Выделенное рабочее пространство | https://{WorkspaceId}.{region}.maas.aliyuncs.com/compatible-mode/v1 |
Рекомендуется для production: лучше пропускная способность и изоляция |
| ZSQH AI Gateway | https://ai.zhongshangqihang.com/v1 |
Единый вход к нескольким моделям |
Несколько важных моментов. Во-первых, API-ключ привязан к региону; вызов из другого региона обычно возвращает 401 и invalid_api_key — это несовпадение ключа и адреса, а не обязательно недействительный ключ. Во-вторых, аккаунты материкового Китая и международного сайта — две разные системы, ключи, счета и списки моделей не переносятся. В-третьих, домен рабочего пространства принимает только ключ этого пространства, но даёт лучшую изоляцию и пропускную способность и подходит для production; старый общий домен удобен для быстрых тестов между пространствами.
Если команда использует несколько моделей и не хочет сама поддерживать регионы, квоты и наборы ключей, создайте единый ключ в ZSQH AI Gateway и замените Base URL на адрес из последней строки таблицы.
3. Как выбрать имя модели
Список моделей Model Studio обновляется быстро. На текущей официальной странице в разделе текстовой генерации указаны, в частности, qwen3.8-max, qwen3.7-plus и qwen3.8-flash. По названию можно приблизительно понять: max — верхняя граница возможностей, plus — баланс, flash — низкая задержка и стоимость. Точное позиционирование и длина контекста — в официальной документации моделей; цены меняются, ориентируйтесь на страницу тарифов.
Не выбирайте только «самую сильную». Для поддержки, пакетной классификации и модерации контента уровень с низкой задержкой часто выгоднее; для длинных документов и сложных агентов берите старший. Имя модели храните в конфигурации, а не в коде — переключаться будет проще.
Есть две частые ловушки. Старые написания вроде qwen-max и qwen-plus могли измениться — перед подключением сверьтесь со списком моделей в консоли. Для векторных задач используйте серию embedding (например, qwen3.7-text-embedding): её тело запроса отличается от чата. Qwen-Audio не поддерживает OpenAI-совместимый протокол — для неё нужен нативный интерфейс DashScope.
4. Первый вызов через curl
Сначала задайте переменную окружения, чтобы ключ не попал в историю команд:
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": "system", "content": "Ты краткий технический ассистент."},
{"role": "user", "content": "Объясни в трёх предложениях, что такое API-шлюз."}
],
"temperature": 0.7
}'
При нормальном ответе смотрите три поля: choices[0].message.content — ответ, usage — расход, finish_reason — причина завершения. При 401 проверьте ключ и регион; при 404 и ModelNotFound — имя модели и доступность этой модели в регионе.
5. Python SDK и потоковый вывод
Нужен OpenAI SDK версии 1.0 или выше. После указания Base URL Model Studio вызов почти совпадает с OpenAI:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
stream = client.chat.completions.create(
model="qwen3.8-max",
messages=[{"role": "user", "content": "Напиши описание продукта не длиннее ста слов."}],
stream=True,
stream_options={"include_usage": True},
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
В потоковом выводе первый chunk может содержать только роль, а content будет пустым; не предполагайте текст в каждом chunk. С stream_options={"include_usage": True} расход появится в последнем chunk. При прямом HTTP ответ идёт в SSE и заканчивается data: [DONE]. Если пользователь закрыл страницу, сервер должен как можно быстрее отменить upstream-запрос, чтобы не продолжать генерацию и списание.
6. Вызов инструментов и различия параметров
Вызов инструментов использует формат OpenAI tools и tool_choice. После ответа message.tool_calls разберите function.arguments каждого вызова как JSON, выполните локальную функцию и верните результат сообщением с role: "tool". В многошаговом процессе tools нужно передавать на каждом шаге. В production проверяйте параметры, права и тайм-ауты; нельзя слепо доверять аргументам, сгенерированным моделью.
Официальная документация совместимости сейчас содержит два ограничения по инструментам: поддерживаются только частью моделей, и tools пока нельзя сочетать с stream=True. Список моделей и возможностей обновляется, поэтому перед запуском обязательно тестируйте целевую модель; если бизнесу нужен стриминг вместе с инструментами, рассмотрите нативный DashScope или сделайте вызов инструмента отдельным непотоковым шагом.
При миграции с OpenAI учитывайте различия параметров:
messages: толькоmessages[0]может иметь роль system; user и assistant обычно чередуются, последнее сообщение должно быть от user.temperature: диапазон [0, 2), официально не рекомендуется ставить 0.top_p: диапазон (0, 1.0).seed: беззнаковое 64-битное целое.stop: элементы массива не могут смешивать token ID и строки.system_fingerprint: сейчас возвращается пустая строка.- Расширенные параметры вроде
enable_search: обычно передаются черезextra_body, поддерживаются не всеми моделями. - Поля
response_format,frequency_penaltyи подобные: документация совместимости их не обеспечивает, не считайте поведение идентичным OpenAI.
7. Типичные ошибки
| Симптом | Код ошибки | Возможная причина | Что делать |
|---|---|---|---|
| 401 | InvalidApiKey / invalid_api_key |
Неверный ключ, несовпадение региона, смешение ключей тарифов | Сверить регион и тип ключа с Base URL |
| 404 | ModelNotFound / model_not_found |
Опечатка в имени, модель отсутствует в регионе, не открыта | Проверить список моделей в консоли |
| 404 | model_not_supported |
Модель не поддерживает OpenAI-совместимый режим | Перейти на нативный DashScope |
| 403 | AccessDenied / Workspace.AccessDenied |
Недостаточно прав на пространство или модель | Проверить авторизацию рабочего пространства |
| 403 | AllocationQuota.FreeTierOnly |
Бесплатная квота исчерпана | Пополнить или изменить тариф |
| 429 | Серия Throttling |
Превышены частота, токены или параллелизм | Снизить параллелизм, повторять с задержкой, запросить квоту |
| 400 | Arrearage |
Задолженность аккаунта | Пополнить и повторить |
| 400 | Range of input length... |
Вход превышает контекст | Сжать промпт или разбить на части |
| 400 | DataInspectionFailed |
Вход или выход заблокирован проверкой контента | Изменить контент и повторить |
Повторы помогают только при 429, 5xx и сетевых тайм-аутах. При 401, 403, 404 и ошибках параметров повтор не поможет, а только потратит время и квоту. При разборе сохраняйте Request ID из ответа и ищите его в журналах консоли — это быстрее догадок.
8. Чек-лист миграции с OpenAI
- Сохраните текущие промпты, параметры моделей и набор оценки.
- Создайте ключ Qwen, соответствующий целевому региону, не используйте ключи других поставщиков.
- Вынесите Base URL и имя модели в конфигурацию.
- Проверьте правила ролей
messages: первый system, последний user. - Проверьте разбор стриминга и способ учёта usage.
- Проведите регрессию вызова инструментов с реальными функциями.
- Сравните качество, задержку и расход на одном наборе примеров.
- Настройте повторы, тайм-ауты и параллелизм, наблюдайте неделю и затем переключайте всё.
- Записывайте Request ID в журналы и сохраняйте переключатель отката.
9. Частые вопросы
Qwen API совместим с OpenAI?
Большинство распространённых чат-интерфейсов совместимы, но остаются различия в привязке к региону, порядке ролей, диапазонах параметров и ограничениях вызова инструментов. Проверяйте по официальной документации совместимости, не считайте поведение всех параметров одинаковым.
Можно ли использовать один ключ в материковом Китае и на международном сайте?
Нет. Аккаунты, ключи, домены и счета двух сайтов независимы. Вызов из другого региона или с другого сайта обычно возвращает 401 и invalid_api_key.
Использовать старый домен или домен рабочего пространства?
Для быстрых тестов подойдёт старый общий домен; для production лучше выделенный домен рабочего пространства — у него лучше пропускная способность и изоляция. Главное, чтобы ключ соответствовал региону и пространству домена.
Имя модели верное, но возвращается model_not_found — почему?
Частые причины: модель не предоставляется в этом регионе, не открыта, регистр символов не совпадает или версия снята с поддержки. Ориентируйтесь на текущий список моделей в консоли.
Можно ли использовать tools вместе со stream?
Официальная документация совместимости сейчас указывает, что одновременно их использовать нельзя, а вызов инструментов поддержан лишь частью моделей. Возможности и ограничения обновляются; перед запуском тестируйте целевую модель или переходите на нативный DashScope.
