- Создайте рабочий проект, настройте доступ к модели и биллинг, получите API-ключ.
- Для OpenAI-совместимого API используйте соответствующую библиотеку.
- Установите Python и библиотеку openai в отдельном окружении: python -m pip install openai.
- Для Telegram-бота логика сходная, но важно дополнительно контролировать права доступа и команды, которые запускают действия.
- Стоимость обычно связана с количеством входных и выходных токенов и выбранной моделью.
Qwen API нужен, когда ответы модели должны появляться внутри собственного сайта, бота или приложения. В отличие от ручного общения в чате, здесь необходимо отвечать за секретные ключи, бюджет, обработку персональных данных и отказоустойчивость. У Alibaba Cloud Model Studio есть OpenAI-совместимый API, что упрощает интеграцию с популярными SDK, но региональные адреса и модели нужно выбирать под свой аккаунт.
Что подготовить до подключения
Создайте рабочий проект, настройте доступ к модели и биллинг, получите API-ключ. Запишите выбранный регион и идентификатор модели, доступной для него. У разных регионов могут отличаться ключи, адреса и квоты. Не используйте пользовательскую подписку на чат как замену API: это разные продукты с разными условиями доступа.
Храните ключ исключительно на сервере в переменной окружения или хранилище секретов. Если вставить его в HTML, JavaScript страницы либо публичный репозиторий, третьи лица смогут расходовать ваш бюджет. Для формы сайта создайте свой серверный endpoint, который валидирует запрос пользователя и только затем обращается к модели.
Первый запрос из Python
Для OpenAI-совместимого API используйте соответствующую библиотеку. В коде ниже адрес вынесен в переменную окружения QWEN_BASE_URL, которую нужно заполнить значением из настроек вашего региона и рабочего пространства. Имя модели также задайте в конфигурации, чтобы не менять исходник при обновлении.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DASHSCOPE_API_KEY"],
base_url=os.environ["QWEN_BASE_URL"],
)
answer = client.chat.completions.create(
model=os.environ["QWEN_MODEL"],
messages=[
{"role": "system", "content": "Отвечай по-русски и кратко."},
{"role": "user", "content": "Составь три темы для статьи о ремонте."},
],
)
print(answer.choices[0].message.content)
Сначала выполните тест на нейтральных данных. Если получена ошибка авторизации, проверьте ключ и регион. При ошибке недоступной модели уточните её идентификатор в своём проекте. Не пытайтесь исправить несоответствие региона многократной отправкой одинакового запроса.
Полный минимальный запуск и проверка ответа
Установите Python и библиотеку openai в отдельном окружении: python -m pip install openai. Для Singapore (International) в новой региональной схеме Model Studio используйте адрес вида https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1, где {WorkspaceId} заменён идентификатором рабочего пространства. Создайте ключ в том же регионе, иначе запрос может быть отклонён. Не вставляйте ключ в код или на страницу сайта.
Перед запуском примера установите переменные окружения DASHSCOPE_API_KEY, QWEN_BASE_URL и QWEN_MODEL. В QWEN_MODEL укажите модель, доступную аккаунту, например qwen3.8-flash. Выполните код из предыдущего раздела. При успешном ответе скрипт печатает текст из answer.choices[0].message.content, а объект ответа содержит служебные поля и сведения об использовании токенов при их наличии.
- При ошибке 401 проверьте наличие ключа и регион, не выводя секрет в терминал целиком.
- При 404 убедитесь, что базовый адрес и модель указаны точно, без пропущенной части
/compatible-mode/v1. - При 429 проверьте квоту и частоту обращений; не запускайте бесконечные повторы.
- После первого успешного запроса запишите расход токенов. Установите лимит бюджета до подключения формы сайта или Telegram-бота.
Это воспроизводимая инструкция по официальному API, а не утверждение, что код был выполнен на чужом аккаунте. Если выбран сторонний агрегатор, его base_url, ключ и имя модели будут другими. Особенности платёжного доступа разобраны в материале об оплате Qwen.
Как организовать API для сайта
- Браузер отправляет текст на ваш сервер.
- Сервер проверяет длину, допустимость и частоту запросов.
- Приложение добавляет необходимые системные правила и вызывает модель.
- Сервер проверяет ответ и удаляет нежелательные технические данные.
- Пользователь получает ответ; расходы и ошибки записываются в журнал без секретов.
Для Telegram-бота логика сходная, но важно дополнительно контролировать права доступа и команды, которые запускают действия. Если бот обрабатывает документы клиентов, заранее определите сроки хранения файлов и кто может увидеть историю запросов.
Учёт токенов и бюджета
Стоимость обычно связана с количеством входных и выходных токенов и выбранной моделью. Длинный контекст может заметно поднять счёт. Ограничьте объём пользовательского ввода, храните краткие резюме переписок и задайте предельный размер ответа. Для дорогих операций можно добавить отдельное подтверждение администратора.
| Риск | Что внедрить |
|---|---|
| Раскрытие ключа | Серверное хранение секретов |
| Непредвиденные расходы | Лимиты пользователей и бюджета |
| Сетевой таймаут | Повтор с ограничением и журналом |
| Большой входной текст | Проверку размера и разбиение |
| Ошибочный ответ | Валидацию структуры и ручную проверку |
Частые ошибки интеграции
Код 401 обычно указывает на проблемы авторизации; 429 — на ограничения частоты или квоты; ошибки 5xx могут означать временную недоступность услуги. Уточняйте фактический текст ответа API и значение кодов именно у используемого провайдера. Повторы должны иметь предел, случайную задержку и защиту от дублирования платных задач. Не записывайте токены API в логи даже при диагностике.
Как проверять качество модели в приложении
Составьте набор типовых пользовательских вопросов и эталонных ответов. Проверьте корректность формата, отказ при недостатке данных, длину ответа и поведение на некорректном вводе. Для структурированных ответов применяйте проверку JSON по схеме: модель может сгенерировать синтаксически неправильные данные даже при чётком запросе. Обновления модели проводите через тестовую среду.
Когда выбирать Qwen API, а когда локальную модель
Облако удобнее при переменной нагрузке и отсутствии собственных видеокарт. Локальная модель помогает контролировать вычисления и работу с закрытыми файлами, но требует ресурсов и обслуживания. Для выбора ознакомьтесь с локальной установкой Qwen. Если разработка идёт с помощью агента в терминале, используйте Qwen Code.
Сколько стоит один ответ?
Зависит от входных и выходных токенов, режима и выбранной модели. Для оценки бюджета возьмите свои типовые сообщения, посчитайте потребление и примените ставки текущего плана. Методика расчёта вынесена в материал о тарифах.