Azure OpenAI в API Microsoft Foundry Models версии 1

В этой статье показано, как использовать API Azure OpenAI версии 1. API версии 1 упрощает проверку подлинности, удаляет потребность в устаревших api-version параметрах и поддерживает вызовы модели между поставщиками.

Замечание

Новые объекты ответа API могут добавляться в ответ API в любое время. Рекомендуется анализировать только необходимые объекты ответа.

Предпосылки

• подписка Azure — создайте бесплатную учетную запись.
• Ресурс Foundry или ресурс Azure OpenAI, развернутый в поддерживаемом регионе
• По крайней мере одно развертывание модели
• Для аутентификации Microsoft Entra ID: Cognitive Services OpenAI User роль, назначенная вашей учетной записи. Дополнительные сведения см. в статье "Управление доступом на основе ролей" для Azure OpenAI

Эволюция API

Ранее Azure OpenAI получил ежемесячные обновления новых версий API. Использование новых функций требует постоянного обновления кода и переменных среды с каждым новым выпуском API. Azure OpenAI также требует дополнительного шага использования конкретных клиентов Azure, создающих затраты при переносе кода между OpenAI и Azure OpenAI.

Начиная с августа 2025 г. вы можете принять участие в следующем поколении API Azure OpenAI версии 1, которые добавляют поддержку:

• Постоянный доступ к последним функциям без необходимости задавать новый api-version каждый месяц.
• Более быстрый цикл выпуска API с новыми функциями, запускаемыми чаще.
• Поддержка клиента OpenAI с минимальными изменениями кода для переключения между OpenAI и Azure OpenAI при использовании проверки подлинности на основе ключей.
• Поддержка клиентов OpenAI для проверки подлинности на основе маркеров и автоматического обновления маркеров без необходимости принимать зависимость от отдельного клиента Azure OpenAI.
• Вызовы завершения чата с моделями других поставщиков, таких как DeepSeek и Grok, которые поддерживают синтаксис завершения чата версии 1.

Доступ к новым вызовам API, которые по-прежнему находятся в предварительной версии, будет контролироваться путем передачи определенных заголовков предварительной версии функций, позволяющих использовать нужные функции без необходимости переключать версии API. Кроме того, некоторые функции будут указывать состояние предварительного просмотра через путь к API и не требуют дополнительного заголовка.

Примеры.

• Когда /openai/v1/evals ранее находилась в предварительном просмотре, требовалось указать заголовок "aoai-evals":"preview". /evals больше не находится в предварительной версии.
• /openai/v1/fine_tuning/alpha/graders/ находится в предварительной версии и не требует пользовательского заголовка из-за наличия alpha в пути API.

Для начального запуска API общедоступной версии 1 поддерживаются только подмножество возможностей api вывода и разработки. Все функции общедоступной версии доступны для использования в рабочей среде. Поддержка дополнительных возможностей быстро добавляется.

Изменения в коде

Python

API версии 1

Примеры Python версии 1

Ключ API:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
)

response = client.responses.create(   
  model="gpt-4.1-nano", # Replace with your model deployment name 
  input="This is a test.",
)

print(response.model_dump_json(indent=2)) 

Основные отличия от предыдущего API:

• OpenAI() клиент используется вместо AzureOpenAI().
• base_url передает конечную точку Azure OpenAI и /openai/v1 добавляется к адресу конечной точки.
• api-version больше не является обязательным параметром в API версии 1 GA.

Ключ API с переменными среды:

Задайте следующие переменные среды перед выполнением кода:

Variable	Ценность
OPENAI_BASE_URL	https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/
OPENAI_API_KEY	Ваш ключ API Azure OpenAI

Затем создайте клиент без параметров:

client = OpenAI()

Идентификатор Microsoft Entra:

Это важно

Ранее автоматическое обновление токенов выполнялось с помощью AzureOpenAI() клиента. API версии 1 удаляет эту зависимость, включив поддержку автоматического обновления токенов в OpenAI() клиенте.

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key = token_provider  
)

response = client.responses.create(
    model="gpt-4.1-nano",
    input= "This is a test" 
)

print(response.model_dump_json(indent=2)) 

• base_url передает конечную точку Azure OpenAI и /openai/v1 добавляется к адресу конечной точки.
• api_key параметр установлен на token_provider значение, что позволяет автоматически извлекать и обновлять токен аутентификации вместо использования статического ключа API.

C#

API версии 1

Примеры C# версии 1

Ключ API:

OpenAIClient client = new(
    new ApiKeyCredential("{your-api-key}"),
    new OpenAIClientOptions()
    {
        Endpoint = new("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
    })

Идентификатор Microsoft Entra:

#pragma warning disable OPENAI001

BearerTokenPolicy tokenPolicy = new(
    new DefaultAzureCredential(),
    "https://ai.azure.com/.default");
OpenAIClient client = new(
    authenticationPolicy: tokenPolicy,
    options: new OpenAIClientOptions()
    {
        Endpoint = new("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
    })

JavaScript

API версии 1

Примеры JavaScript версии 1

Ключ API:

const client = new OpenAI({
    baseURL: "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    apiKey: "{your-api-key}" 
});

Ключ API с установленными переменными среды для OPENAI_BASE_URL и OPENAI_API_KEY:

const client = new OpenAI();

Идентификатор Microsoft Entra:

const tokenProvider = getBearerTokenProvider(
    new DefaultAzureCredential(),
    'https://ai.azure.com/.default');
const client = new OpenAI({
    baseURL: "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    apiKey: tokenProvider
});

Вперед

API версии 1

Примеры Go версии 1

Ключ API:

client := openai.NewClient(
    option.WithBaseURL("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
    option.WithAPIKey("{your-api-key}")
)

Ключ API с установленными переменными среды для OPENAI_BASE_URL и OPENAI_API_KEY:

client := openai.NewClient()

Идентификатор Microsoft Entra:

tokenCredential, err := azidentity.NewDefaultAzureCredential(nil)

client := openai.NewClient(
    option.WithBaseURL("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
    azure.WithTokenCredential(tokenCredential)
)

Java

Примеры Java версии 1

API версии 1

Ключ API:

OpenAIClient client = OpenAIOkHttpClient.builder()
                .baseUrl("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/")
                .apiKey(apiKey)
                .build();

Ключ API с установленными переменными среды для OPENAI_BASE_URL и OPENAI_API_KEY:

OpenAIClient client = OpenAIOkHttpClient.builder()
                .fromEnv()
                .build();

Идентификатор Microsoft Entra:

Credential tokenCredential = BearerTokenCredential.create(
        AuthenticationUtil.getBearerTokenSupplier(
                new DefaultAzureCredentialBuilder().build(),
                "https://ai.azure.com/.default"));
OpenAIClient client = OpenAIOkHttpClient.builder()
        .baseUrl("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/")
        .credential(tokenCredential)
        .build();

REST

API версии 1

Ключ API:

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d '{
     "model": "gpt-4.1-nano",
     "input": "This is a test"
    }'

Идентификатор Microsoft Entra:

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
     "model": "gpt-4o",
     "input": "This is a test"
    }'

Поддержка модели

Для моделей Azure OpenAI мы рекомендуем использовать API ответов, однако API версии 1 также позволяет выполнять вызовы завершения чата с моделями других поставщиков, таких как DeepSeek и Grok, которые поддерживают синтаксис завершения чата OpenAI версии 1.

base_url будет принимать оба https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/ формата и https://YOUR-RESOURCE-NAME.services.ai.azure.com/openai/v1/ форматы.

Замечание

API для ответов также работает с моделями Foundry, которые были проданы непосредственно в Azure, такими как модели Microsoft AI, DeepSeek и Grok. Сведения об использовании API ответов с этими моделями см. в статье "Создание текстовых ответов с помощью моделей Microsoft Foundry".

Python

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)
completion = client.chat.completions.create(
  model="MAI-DS-R1", # Replace with your model deployment name.
  messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Tell me about the attention is all you need paper"}
  ]
)

#print(completion.choices[0].message)
print(completion.model_dump_json(indent=2))

C#

using Azure.Identity;
using OpenAI;
using OpenAI.Chat;
using System.ClientModel.Primitives;

#pragma warning disable OPENAI001

BearerTokenPolicy tokenPolicy = new(
    new DefaultAzureCredential(),
    "https://ai.azure.com/.default");

ChatClient client = new(
    model: "MAI-DS-R1", // Replace with your model deployment name.
    authenticationPolicy: tokenPolicy,
    options: new OpenAIClientOptions() { 
    
        Endpoint = new Uri("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1")
   }
);

ChatCompletion completion = client.CompleteChat("Tell me about the attention is all you need paper");

Console.WriteLine($"[ASSISTANT]: {completion.Content[0].Text}");

JavaScript

import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
import { OpenAI } from "openai";

const tokenProvider = getBearerTokenProvider(
    new DefaultAzureCredential(),
    'https://ai.azure.com/.default');
const client = new OpenAI({
    baseURL: "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    apiKey: tokenProvider
});

const messages = [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Tell me about the attention is all you need paper' }
];

// Make the API request with top-level await
const result = await client.chat.completions.create({ 
    messages, 
    model: 'MAI-DS-R1', // model deployment name
    max_tokens: 100 
});

// Print the full response
console.log('Full response:', result);

// Print just the message content from the response
console.log('Response content:', result.choices[0].message.content);

Вперед

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/azure"
	"github.com/openai/openai-go/v3/option"
)

func main() {
	// Create an Azure credential
	tokenCredential, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("Failed to create credential: %s", err)
	}

	// Create a client with Azure OpenAI endpoint and token credential
	client := openai.NewClient(
		option.WithBaseURL("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
		azure.WithTokenCredential(tokenCredential),
	)

	// Make a completion request
	chatCompletion, err := client.Chat.Completions.New(context.TODO(), openai.ChatCompletionNewParams{
		Messages: []openai.ChatCompletionMessageParamUnion{
			openai.UserMessage("Explain what the bitter lesson is?"),
		},
		Model: "MAI-DS-R1", // Use your deployed model name on Azure
	})
	if err != nil {
		log.Fatalf("Failed to get chat completions: %s", err)
	}

	fmt.Println(chatCompletion.Choices[0].Message.Content)
}

Java

package com.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.ChatModel;
import com.openai.models.chat.completions.ChatCompletion;
import com.openai.models.chat.completions.ChatCompletionCreateParams;

public class OpenAITest {
    public static void main(String[] args) {
        // Get API key from environment variable for security
        String apiKey = System.getenv("OPENAI_API_KEY");
        String resourceName = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1";
        String modelDeploymentName = "MAI-DS-R1"; //replace with your model deployment name

        try {
            OpenAIClient client = OpenAIOkHttpClient.builder()
                    .baseUrl(resourceName)
                    .apiKey(apiKey)
                    .build();

           ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
              .addUserMessage("Explain what the bitter lesson is?")
              .model(modelDeploymentName)
              .build();
           ChatCompletion chatCompletion = client.chat().completions().create(params);
        }
    }
}

REST

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
      "model": "MAI-DS-R1",
      "messages": [
      {
        "role": "developer",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Explain what the bitter lesson is?"
      }
    ]
  }'

Поддержка API версии 1

• Спецификация OpenAPI 3.0 версии 1

Журнал изменений версий API

В следующих разделах перечислены изменения между версиями API.

Изменения между предварительной версией версии 1 и 2025-04-01-preview

• API предварительной версии 1
• Поддержка создания видео
• НОВЫЕ ФУНКЦИИ Функции API ответов:
  • Интеграция инструментов с серверами протокола контекста удаленной модели (MCP)
  • Поддержка асинхронных фоновых задач
  • Зашифрованные элементы рассуждений
  • Генерирование изображений

Изменения между 2025-04-01-preview и 2025-03-01-preview

• GPT-image-1 поддержка
• Сводка рассуждений для o3 и o4-mini
• API оценки

Изменения между 2025-03-01-preview и 2025-02-01-preview

• API ответов
• Использование компьютера

Изменения между 2025-02-01-preview и 2025-01-01-preview

• Хранимые завершения (поддержка API дистилляции).

Изменения между 2025-01-01-preview и 2024-12-01-preview

• prediction параметр, добавленный для поддержки прогнозируемых выходных данных.
• gpt-4o-audio-preview поддержка модели.

Изменения между 2024-12-01-preview и 2024-10-01-preview

• store и metadata параметры добавлены для поддержки хранимых завершений.
• reasoning_effort добавлены последние модели рассуждений.
• user_security_contextдобавлена интеграция Microsoft Defender для облачных решений.

Изменения между 2024-09-01-preview и 2024-08-01-preview

• max_completion_tokens добавлена поддержка моделей o1-preview и o1-mini. max_tokens не работает с моделями серии o1 .
• Добавлено: parallel_tool_calls.
• completion_tokens_details и reasoning_tokens добавлено.
• stream_options и include_usage добавлено.

Изменения между спецификацией API 2024-07-01-preview и 2024-08-01-preview API

• Поддержка структурированных выходных данных.
• Добавлен API отправки больших файлов.
• В отношении ваших изменений данных:
  • Интеграция с Mongo DB.
  • role_information удален параметр.
  • rerank_score добавлен в объект ссылок.
  • Удален источник данных AML.
  • Улучшения интеграции векторизации поиска ИИ.

Изменения между спецификацией API 2024-05-01-preview и спецификацией API 2024-07-01-preview

• Добавлена поддержка пакетного API
• Параметры стратегии разбиения хранилища векторов
• max_num_results результаты, которые должен вывести инструмент поиска файлов.

Изменения в спецификации API между 2024-04-01-preview и 2024-05-01-preview

• Поддержка помощников версии 2— средство поиска файлов и векторное хранилище
• Точная настройка контрольных точек, начальный параметр, события
• Обновления ваших данных
• DALL-E 2 теперь поддерживает развертывание модели и может использоваться с последней предварительной версией API.
• Обновления фильтрации содержимого

Изменения между спецификацией API 2024-03-01-preview и 2024-04-01-preview API

• Критическое изменение: удалены параметры усовершенствования. Это влияет на модель gpt-4Версия:vision-preview.
• добавлен параметр timestamp_granularities.
• audioWord добавлен объект.
• Дополнительные TTS response_formats: wav & pcm.

Известные проблемы

• Спецификация 2025-04-01-preview Azure OpenAI использует OpenAPI 3.1. Известной проблемой является то, что эта версия не полностью поддерживается управлением API Azure.

Дальнейшие шаги

• Поддерживаемые языки программирования для API версии 1
• Модели Foundry, проданные непосредственно в Azure
• Работа с моделями Azure OpenAI
• Квоты и ограничения Azure OpenAI
• Спецификация OpenAPI 3.0 версии 1