Qwen API через OpenAI SDK: полное руководство по интеграции с DashScope (2026)

DashScope предоставляет доступ ко всему семейству моделей Qwen через endpoint, совместимый с протоколом OpenAI Chat Completions. Достаточно заменить три значения в существующем коде на базе OpenAI SDK — API key, base URL, имя модели — и приложение, работавшее с GPT-4o, начнёт работать с Qwen3.8-Max, Qwen3.7-Plus или любой из сторонних моделей, размещённых на DashScope (DeepSeek V4, Kimi K3, GLM-5.3). Никаких изменений формата запросов, никаких новых клиентских библиотек.

Это руководство проведёт вас от «у меня нет аккаунта Alibaba Cloud» до «я маршрутизирую Qwen, Claude и GPT через единый шлюз в production».

OpenAI-совместимость означает, что провайдер предоставляет endpoint chat-completions, чей контракт запроса и ответа достаточно близок к API OpenAI, чтобы немодифицированный вызов OpenAI SDK работал после замены трёх значений: API key, base URL, название модели. Минимальная поверхность на практике —POST /v1/chat/completions с messages, model и потоковым ответом в форме OpenAI.

Начало работы за 3 минуты

Шаг 1 — Создайте аккаунт Alibaba Cloud. Перейдите на alibabacloud.com для международного доступа или aliyun.com для материкового Китая. Активируйте Model Studio (百炼) в консоли.

Шаг 2 — Получите API-ключ. Откройте страницу API Keys в Model Studio и создайте новый ключ. Ключи привязаны к региону: ключ из Пекина работает только с пекинским endpoint, сингапурский — только с сингапурским.

Шаг 3 — Установите OpenAI SDK.

pip install --upgrade openai

Шаг 4 — Отправьте первый запрос.

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

response = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain API routing in two sentences."},
    ],
)

print(response.choices[0].message.content)

Формат ответа идентичен openai.ChatCompletion — те же поля id, choices, usage. Любой код, парсящий ответы OpenAI, работает без изменений.

Base URL по регионам

DashScope работает в нескольких регионах, у каждого свой endpoint. Alibaba Cloud мигрирует на доменные имена с привязкой к workspace для повышения стабильности.

Замените {WorkspaceId} на реальный ID из консоли Model Studio. Устаревший endpoint dashscope.aliyuncs.com продолжает работать для Пекина, но Alibaba Cloud рекомендует новый формат для всех интеграций.

Самая частая ошибка при первом подключении — использование пекинского API-ключа с сингапурским endpoint. DashScope возвращает HTTP 401 invalid_api_key, если регион ключа не совпадает с регионом endpoint.

ID моделей: актуальная линейка Qwen

DashScope организует модели по поколениям и уровням. Ниже представлены модели генерации текста, наиболее актуальные для API-разработчиков по состоянию на август 2026 года.

Уровень Max (флагманы)

Уровень Plus (баланс)

Уровень Flash / Turbo (скорость и стоимость)

Open-source модели на DashScope

Сторонние модели на DashScope

DashScope предлагает не только Qwen. Alibaba Cloud размещает модели других провайдеров на том же OpenAI-совместимом endpoint — для переключения достаточно сменить model ID.

Таким образом DashScope превращается в мультимодельный маркетплейс: один аккаунт, один API-ключ и доступ к моделям нескольких китайских AI-лабораторий.

Режим thinking (цепочка рассуждений)

Qwen3.7-Max и Qwen3.8-Max поддерживают режим thinking, при котором модель генерирует внутреннюю цепочку рассуждений перед финальным ответом. Включается через параметр extra_body в OpenAI SDK.

response = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {"role": "user", "content": "Prove that the square root of 2 is irrational."},
    ],
    extra_body={
        "enable_thinking": True,
        "thinking_budget": 10000,
    },
    stream=True,
)

При активном thinking DashScope возвращает цепочку рассуждений в отдельном поле reasoning_content каждого chunk. Тарификация учитывает как thinking-токены, так и токены финального ответа.

Для отключения передайте enable_thinking=False в extra_body.

Tool calling (вызов функций)

OpenAI-совместимый endpoint DashScope поддерживает стандартный параметр tools. Формат запросов и ответов соответствует спецификации OpenAI.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "City name"}
                },
                "required": ["location"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[{"role": "user", "content": "What is the weather in Shanghai?"}],
    tools=tools,
    tool_choice="auto",
)

Модель возвращает массив tool_calls в сообщении assistant, а вы отправляете результат функции обратно с ролью tool — идентично потоку OpenAI. Qwen3.8-Max и Qwen3.7-Max поддерживают параллельные tool calls.

Потоковая передача

Работает через стандартный stream=True. DashScope возвращает объекты chat.completion.chunk в том же формате, что и OpenAI.

stream = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[{"role": "user", "content": "Write a haiku about API routing."}],
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)

Параметр stream_options={"include_usage": True} добавляет счётчик токенов в последний chunk — удобно для отслеживания расходов.

Тарифы (регион Пекин, август 2026)

Цены указаны за миллион токенов в юанях (RMB). Модели уровня Max используют ступенчатое ценообразование в зависимости от общего количества входных токенов.

Модели с поддержкой Batch API (qwen3.8-max, qwen3-max) стоят на 50% дешевле при batch-вызовах. Кэширование контекста даёт отдельную скидку: попадание в кэш обычно тарифицируется по 10% от стандартной цены ввода.

Международные регионы (Сингапур, Вирджиния, Токио) дороже. qwen3.8-max в Сингапуре стоит ¥14.988/M вместо ¥12/M в Пекине.

Актуальные цены — на странице тарифов DashScope.

Типичные ошибки и решения

HTTP 401 invalid_api_key — API-ключ и endpoint относятся к разным регионам. Создайте ключ в том же регионе, что и ваш endpoint.

HTTP 404 на /v1/chat/completions — вероятно, используется формат нативного DashScope-протокола. Убедитесь, что base URL заканчивается на /compatible-mode/v1, а не на /api/v1.

model not found — Model ID чувствительны к регистру. Пишите qwen3.8-max, не Qwen3.8-Max. Для сторонних моделей используйте префикс провайдера: ZHIPU/GLM-5.3-Flash.

Thinking-токены тарифицируются, но рассуждения не видны — при enable_thinking=True токены рассуждений включаются в usage.completion_tokens, но сама цепочка доступна только при streaming через поле reasoning_content.

Ошибки rate limit — DashScope применяет лимиты по модели и уровню аккаунта. Конкретные значения не опубликованы для каждой модели. Повышение уровня аккаунта Alibaba Cloud увеличивает лимиты.

Чек-лист для production

1. Используйте workspace-доменные имена. Устаревший dashscope.aliyuncs.com не обеспечивает изоляцию по workspace.
2. Ротируйте API-ключи. Ключи DashScope не имеют срока действия по умолчанию. Настройте ротацию в менеджере секретов.
3. Следите за календарём вывода моделей. Alibaba Cloud регулярно выводит из эксплуатации старые версии. Расписание — на странице вывода моделей. Мы отслеживаем это в справочнике жизненного цикла моделей DashScope.
4. Включите кэширование контекста для повторяющихся prompt. При системном prompt длиннее 1 024 токенов неявное кэширование включается автоматически. Для явного кэширования смотрите документацию DashScope.
5. Оцените влияние thinking на бюджет. Thinking-токены могут увеличить количество output-токенов в 2–5 раз. Протестируйте на репрезентативной выборке.
6. Установите stream_options.include_usage для отслеживания реального потребления токенов по каждому запросу.

Маршрутизация Qwen вместе с другими провайдерами

Если приложению нужно обращаться к Qwen, Claude и GPT из единой точки, API-router принимает запросы и пересылает их нужному провайдеру. TheRouter маршрутизирует OpenAI-совместимые запросы к настроенным провайдерам, включая DashScope, и поддерживает fallback-цепочки: если DashScope недоступен или возвращает ошибку rate limit, запрос переходит к альтернативному провайдеру.

Типичная конфигурация: направьте приложение на endpoint TheRouter вместо DashScope напрямую, добавьте DashScope как provider с API-ключом и base URL, задайте fallback-цепочку — сначала Qwen3.8-Max на DashScope, при 5xx-ответах переключение на DeepSeek API. TheRouter пересылает запрос в формате OpenAI — изменения кода не нужны.

Это особенно полезно, когда DashScope используется для основного inference, но нужна защита от региональных сбоев и временных ограничений по rate limit.

Подробнее о платформе DashScope — в руководстве по Aliyun Bailian API. О моделях серии Qwen3.7 — в руководстве по серии DashScope Qwen3.7.

Часто задаваемые вопросы

Можно ли использовать Node.js OpenAI SDK с DashScope? Да. Установите baseURL на compatible-mode endpoint DashScope и передайте API-ключ. Паттерны, показанные в Python, работают идентично в Node.js SDK.

Поддерживает ли DashScope Batch API? Да. Модели, отмеченные как поддерживающие batch-вызовы, принимают endpoint /v1/batches. Отправьте .jsonl-файл с запросами и получите результаты асинхронно за половину стоимости.

В чём разница между qwen3.8-max и qwen3.8-max-prime? Prime — вариант, оптимизированный по скорости, с удвоенной стоимостью (¥24/¥72 против ¥12/¥36). Предназначен для нагрузок, где время до первого токена критично.

Есть ли бесплатные кредиты? Новые аккаунты получают 1 миллион бесплатных токенов для большинства моделей Qwen, действительных 90 дней от активации аккаунта или релиза модели (что наступит позже). Сторонние модели на DashScope могут иметь отдельные промо-квоты.

Поддерживает ли DashScope Assistants API или Responses API? DashScope реализует endpoint Chat Completions. Assistants API и Responses API не поддерживаются. Для агентной оркестрации используйте собственный Application API DashScope или реализуйте agent-цикл поверх Chat Completions с tool calling.