Azure OpenAI API: как отправить первый запрос к своей модели

Azure OpenAI — доступ к моделям OpenAI через инфраструктуру Azure и Microsoft Foundry. Чтобы вызвать модель из программы, нужны ресурс Azure, развёртывание модели и подходящий способ аутентификации. В API вы указываете имя своего развёртывания: оно может отличаться от названия самой модели. Развёртывание моделей в Foundry.

Разберём один текстовый запрос на Python через Azure OpenAI v1 и Responses API: от параметров развёртывания до проверки сокращённой заметки.

Подготовьте ресурс и развёртывание

Для работы нужны подписка Azure, ресурс Foundry или Azure OpenAI в подходящем регионе и хотя бы одно развёртывание модели. Не всякая модель доступна в любом регионе; отдельно проверьте поддержку Responses API. Условия v1 API, модели и регионы Responses API.

Если проект Foundry уже создан, в новом интерфейсе откройте Discover → Models, выберите модель OpenAI и нажмите Deploy. В настройках задайте имя развёртывания и проверьте параметры. Дождитесь статуса Succeeded. В Build → Models можно открыть детали развёртывания, посмотреть endpoint и ключи; Playground позволяет проверить модель вручную. Для создания развёртывания нужны соответствующие права на ресурс. Порядок действий в Foundry.

Запишите три значения:

Значение	Для чего оно нужно
Адрес ресурса	Определяет, в какой ресурс Azure уйдёт запрос
Имя развёртывания	Передаётся в поле model и выбирает ваше развёртывание
Ключ этого ресурса	Используется в примере для аутентификации

Например, вы могли назвать развёртывание notes-demo, хотя базовая модель называется иначе. В этом случае model="notes-demo" — правильный выбор. Подставлять знакомое название GPT вместо имени развёртывания наугад не нужно. Это условный пример имени, а не существующий публичный endpoint.

Используйте адрес v1, не смешивая два формата API

Для рассматриваемого варианта адрес клиента выглядит так:

https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/

Microsoft также допускает адрес ресурса на services.ai.azure.com с тем же окончанием /openai/v1/. В Python используется клиент OpenAI, а обязательного параметра с датой api-version у v1 GA нет. Если переносите старый пример с AzureOpenAI, сверяйте весь способ подключения, а не меняйте только название модели. Переход на Azure OpenAI v1.

В переменной AZURE_OPENAI_BASE_URL ниже должен быть именно полный адрес с /openai/v1/. Не добавляйте туда /responses: этот путь добавляет библиотека при вызове метода.

Общие принципы запросов и ответов разобраны в статье о том, как устроен GPT API.

Установите библиотеку и задайте параметры

В своём окружении Python выполните:

python -m pip install --upgrade openai

Пример использует текущий интерфейс библиотеки с OpenAI и responses.create. После установки сохраните фактическую версию для воспроизводимости:

python -m pip show openai

Установка клиентской библиотеки и вызов Responses через неё описаны в инструкции Microsoft.

Перед запуском задайте переменные окружения средствами своего терминала или среды разработки:

• AZURE_OPENAI_BASE_URL — полный адрес v1 вашего ресурса.
• AZURE_OPENAI_API_KEY — ключ этого ресурса.
• AZURE_OPENAI_DEPLOYMENT — точное имя развёртывания.

Не сохраняйте настоящий ключ в файле программы или примере для коллег. В этом материале выбран вход по ключу ради короткого первого запроса. Microsoft рекомендует Microsoft Entra ID; для него используются другой способ получения токена и права доступа. В инструкции v1 для вызова указана роль Cognitive Services OpenAI User. Это не те же права, которые нужны для создания развёртываний. Аутентификация и роли.

Отправьте текстовый запрос

Сохраните код как azure_first_request.py:

import os
from openai import OpenAI

base_url = os.environ["AZURE_OPENAI_BASE_URL"].strip()
deployment = os.environ["AZURE_OPENAI_DEPLOYMENT"].strip()

if not base_url.startswith("https://") or not base_url.endswith("/openai/v1/"):
    raise ValueError("Нужен HTTPS-адрес ресурса с окончанием /openai/v1/")
if not deployment:
    raise ValueError("Укажите имя развёртывания")

client = OpenAI(
    base_url=base_url,
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
)

response = client.responses.create(
    model=deployment,
    input=(
        "Сократи заметку до одного предложения, сохрани время и действие. "
        "Не добавляй неизвестные сведения. "
        "Заметка: завтра в 11:30 нужно передать три коробки на склад."
    ),
)

print("Response ID:", response.id)
print(response.output_text)

Запуск:

python azure_first_request.py

Поля base_url, api_key, model и вызов responses.create соответствуют примеру Azure Responses API. Проверка адреса в нашем коде ловит распространённую ошибку с окончанием пути; она не проверяет существование ресурса или права доступа.

Успешный сетевой вызов и полезный ответ — две отдельные проверки. Сначала убедитесь, что программа получила ответ без исключения и вывела его идентификатор. Затем прочитайте текст: в нём должны остаться завтра, 11:30, три коробки, передать на склад. Имя получателя, адрес склада или календарная дата добавляться не должны.

Авторский образец подходящего результата: «Завтра в 11:30 передайте три коробки на склад». Это не ответ, полученный от Azure при подготовке статьи: реальный вызов к аккаунту здесь не выполнялся. Мы даём пример запроса и критерий, по которому вы проверите свой запуск.

Если запрос не прошёл

Начните с фактического сообщения ошибки, а затем проверьте соответствующий уровень:

Где остановилось выполнение	Что проверить
ModuleNotFoundError: openai	Установлена ли библиотека в том же Python, которым запускается файл
KeyError с именем переменной	Передана ли эта переменная текущему процессу
Наша ошибка адреса	Есть ли HTTPS и окончание /openai/v1/
Ошибка от сервиса	Совпадают ли ресурс, ключ и имя развёртывания; доступна ли модель и завершено ли развёртывание
Проблема с квотой при развёртывании	Проверьте доступную квоту для модели и региона

Microsoft связывает неуспешное развёртывание, в частности, с доступностью модели в регионе и достаточной квотой. Не пытайтесь исправить такую проблему бесконечным повторением одинакового запроса. Проверки квот и развёртывания.

Когда простой запрос заработает, замените учебную заметку одной своей задачей и заранее запишите условия правильного ответа. Так вы отдельно проверите подключение и качество обработки текста, прежде чем добавлять этот вызов в приложение.