interfejs API platformy Azure OpenAI w modelach Microsoft Foundry w wersji 1

W tym artykule pokazano, jak używać interfejsu API OpenAI w wersji 1 usługi Azure. Interfejs API w wersji 1 upraszcza uwierzytelnianie, eliminuje potrzebę przestarzałych parametrów api-version i obsługuje wywołania modelu między dostawcami.

Uwaga

Nowe obiekty odpowiedzi interfejsu API mogą być dodawane do odpowiedzi interfejsu API w dowolnym momencie. Zalecamy analizowanie tylko potrzebnych obiektów odpowiedzi.

Wymagania wstępne

• Subskrypcja Azure — Utwórz ją bezpłatnie
• Zasób Foundry lub zasób Azure OpenAI wdrożony w obsługiwanym regionie.
• Co najmniej jedno wdrożenie modelu
• W przypadku uwierzytelniania Microsoft Entra ID: rola Cognitive Services OpenAI User przypisana do twojej tożsamości. Aby uzyskać więcej informacji, zobacz Kontrola dostępu oparta na rolach dla Azure OpenAI

Ewolucja interfejsu API

Wcześniej Azure openAI otrzymał comiesięczne aktualizacje nowych wersji interfejsu API. Korzystanie z nowych funkcji wymagało stałego aktualizowania kodu i zmiennych środowiskowych wraz z każdą nową wersją interfejsu API. Azure OpenAI wymagała również dodatkowego kroku korzystania z klientów specyficznych dla Azure, co stworzyło obciążenie podczas migrowania kodu między OpenAI a Azure OpenAI.

Począwszy od sierpnia 2025 r., możesz wyrazić zgodę na interfejsy API nowej generacji w wersji 1 Azure OpenAI, które dodają obsługę:

• Ciągły dostęp do najnowszych funkcji bez potrzeby określania nowych api-version w każdym miesiącu.
• Szybszy cykl wydawania interfejsu API z nowszymi funkcjami uruchamianymi częściej.
• Obsługa klienta OpenAI z minimalnymi zmianami kodu w celu przełączania się między usługami OpenAI i Azure OpenAI podczas korzystania z uwierzytelniania opartego na kluczach.
• Obsługa klienta openAI na potrzeby uwierzytelniania opartego na tokenach i automatycznego odświeżania tokenu bez konieczności podejmowania zależności od oddzielnego klienta Azure OpenAI.
• Wykonywanie wywołań czatu za pomocą modeli innych dostawców, takich jak DeepSeek i Grok, które obsługują składnię uzupełniania czatu w wersji 1.

Dostęp do nowych wywołań interfejsu API, które są nadal dostępne w wersji zapoznawczej, jest kontrolowany przez przekazywanie nagłówków specyficznych dla funkcji w wersji zapoznawczej. Takie podejście umożliwia wybranie żądanych funkcji bez konieczności zamiany wersji interfejsu API. Alternatywnie niektóre funkcje wskazują stan wersji zapoznawczej za pośrednictwem ścieżki interfejsu API i nie wymagają dodatkowego nagłówka.

Przykłady:

• Gdy /openai/v1/evals był wcześniej dostępny w wersji zapoznawczej, wymagane było przesłanie nagłówka "aoai-evals":"preview". /evals nie jest już w wersji zapoznawczej.
• /openai/v1/fine_tuning/alpha/graders/ jest w wersji zapoznawczej i nie wymaga niestandardowego nagłówka z powodu obecności alpha w ścieżce interfejsu API.

Podczas początkowego udostępnienia ogólnego interfejsu API w wersji 1 (GA) obsługiwane są jedynie wybrane funkcje wnioskowania i tworzenia interfejsu API. Wszystkie funkcje w wersji ogólnodostępnej są obsługiwane do użytku w środowisku produkcyjnym. Obsługa dodatkowych funkcji jest szybko rozszerzana.

Zmiany kodu

Python

API w wersji 1

Przykłady v1 Python

Klucz interfejsu 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)) 

Kluczowe różnice w stosunku do poprzedniego interfejsu API:

• OpenAI() klient jest używany zamiast AzureOpenAI().
• Przekaż punkt końcowy Azure OpenAI do base_url i dołącz /openai/v1 do adresu punktu końcowego.
• api-version nie jest już wymaganym parametrem w wersji 1 GA API.

Klucz interfejsu API ze zmiennymi środowiskowymi:

Przed uruchomieniem kodu ustaw następujące zmienne środowiskowe:

Zmienna	Wartość
OPENAI_BASE_URL	https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/
OPENAI_API_KEY	Twój klucz interfejsu API Azure OpenAI

Następnie utwórz klienta bez parametrów:

client = OpenAI()

Microsoft Entra ID:

Ważne

Obsługa automatycznego odświeżania tokenu była wcześniej obsługiwana przy użyciu AzureOpenAI() klienta. Interfejs API w wersji 1 usuwa tę zależność, dodając do klienta OpenAI() funkcjonalność automatycznego odświeżania tokenu.

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)) 

• Przekaż punkt końcowy Azure OpenAI do base_url i dołącz /openai/v1 do adresu punktu końcowego.
• Ustaw parametr api_key na token_provider, aby włączyć automatyczne pobieranie i odświeżanie tokenu uwierzytelniającego zamiast używania statycznego klucza API.

C#

API w wersji 1

Przykłady języka C# w wersji 1

Klucz interfejsu API:

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

Microsoft Entra ID:

#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 w wersji 1

Przykłady kodu JavaScript w wersji 1

Klucz interfejsu API:

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

Klucz interfejsu API ze zmiennymi środowiskowymi ustawionymi dla i OPENAI_BASE_URL.

const client = new OpenAI();

Microsoft Entra ID:

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
});

Przejdź

API w wersji 1

Przykłady języka Go w wersji 1

Klucz interfejsu API:

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

Klucz interfejsu API ze zmiennymi środowiskowymi ustawionymi dla i OPENAI_BASE_URL.

client := openai.NewClient()

Microsoft Entra ID:

tokenCredential, err := azidentity.NewDefaultAzureCredential(nil)

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

Java

przykłady Java v1

API w wersji 1

Klucz interfejsu API:

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

Klucz interfejsu API ze zmiennymi środowiskowymi ustawionymi dla i OPENAI_BASE_URL.

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

Microsoft Entra ID:

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 w wersji 1

Klucz interfejsu 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 ID:

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"
    }'

Obsługa modelu

W przypadku modeli Azure OpenAI zalecamy używanie interfejsu API Responses API jednak interfejs API w wersji 1 umożliwia również wykonywanie wywołań uzupełniania czatów z modelami innych dostawców, takich jak DeepSeek i Grok, które obsługują składnię uzupełniania czatu OpenAI v1.

base_url akceptuje zarówno formaty, jak https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/ i https://YOUR-RESOURCE-NAME.services.ai.azure.com/openai/v1/ .

Uwaga

Responses API działa również z modelami Foundry oferowanymi przez Azure, takimi jak modele Microsoft AI, DeepSeek i Grok. Aby dowiedzieć się, jak używać interfejsu API odpowiedzi z tymi modelami, zobacz Jak wygenerować odpowiedzi tekstowe za pomocą modeli 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);

Przejdź

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?"
      }
    ]
  }'

Obsługa API wersji 1

• v1 Specyfikacje openAPI 3.0

Dziennik zmian wersji interfejsu API

W poniższych sekcjach podsumowano zmiany między wersjami interfejsu API.

Zmiany między wersją zapoznawczą v1 a wersją 2025-04-01-preview

• API w wersji wstępnej v1
• Obsługa generowania wideo
• NOWE Funkcje interfejsu API odpowiedzi:
  • Integracja narzędzi z serwerami protokołu MCP (Remote Model Context Protocol)
  • Obsługa zadań asynchronicznych w tle
  • Zaszyfrowane elementy rozumowania
  • Generowanie obrazu

Zmiany między 2025-04-01-preview i 2025-03-01-preview

• GPT-image-1 Wsparcie
• Podsumowanie rozumowania dla o3 i o4-mini
• API ewaluacyjny

Zmiany między 2025-03-01-preview i 2025-02-01-preview

• API odpowiedzi
• Korzystanie z komputera

Zmiany między 2025-02-01-preview i 2025-01-01-preview

• Przechowywane uzupełnienia (obsługa interfejsu API Distillation).

Zmiany między 2025-01-01-preview i 2024-12-01-preview

• prediction Dodano parametr do obsługi przewidywanych wyników.
• gpt-4o-audio-preview obsługa modelu.

Zmiany między 2024-12-01-preview i 2024-10-01-preview

• store i metadata dodano jako parametry do obsługi przechowywanych uzupełnień.
• reasoning_effort dodano do najnowszych modeli rozumowania.
• user_security_context dodano do integracji z Microsoft Defender dla Chmury.

Zmiany między 2024-09-01-preview i 2024-08-01-preview

• max_completion_tokens dodano do obsługi o1-preview i o1-mini modeli. max_tokens nie działa z modelami serii o1 .
• parallel_tool_calls Dodane.
• completion_tokens_details i reasoning_tokens dodano.
• stream_options i include_usage dodano.

Zmiany pomiędzy 2024-07-01-preview i 2024-08-01-preview specyfikacji API

• Obsługa danych wyjściowych ze strukturą.
• Dodano API przesyłania dużych plików.
• Zmiany waszych danych:
  • Integracja z bazą danych Mongo DB.
  • role_information parametr został usunięty.
  • rerank_score został dodany do obiektu cytatu.
  • Usunięto źródło danych AML.
  • Ulepszenia integracji wektoryzacji sztucznej inteligencji w wyszukiwaniu.

Zmiany między 2024-05-01-preview oraz 2024-07-01-preview specyfikacji API

• Dodano obsługę interfejsu Batch API.
• Parametry strategii fragmentowania magazynu wektorów.
• max_num_results że narzędzie wyszukiwania plików powinno zwrócić wyniki.

Zmiany między 2024-04-01-preview oraz 2024-05-01-preview specyfikacji API

• Obsługa Asystentów w wersji 2 – narzędzie do wyszukiwania plików i magazynowanie wektorów
• Dostrajanie checkpoints, seed, events
• Aktualizacje Twoich danych
• DALL-E 2 obsługuje teraz implementację modelu i może być używany z najnowszą wersją zapoznawczą API.
• Aktualizacje filtrowania zawartości

Zmiany w specyfikacji interfejsu API między 2024-03-01-preview oraz 2024-04-01-preview

• Zmiana powodująca niezgodność: usunięto parametry ulepszeń. Ta zmiana ma wpływ na model gpt-4Wersja:vision-preview.
• dodano parametr timestamp_granularities.
• dodano obiekt audioWord.
• Dodatkowe response_formats: wav & pcm TTS.

Znane problemy

• Specyfikacja 2025-04-01-preview Azure OpenAI używa specyfikacji OpenAPI 3.1. Jest to znany problem, że ta wersja nie jest w pełni obsługiwana przez Azure API Management.

Następne kroki

• Obsługiwane języki programowania dla interfejsu API w wersji 1
• Modele Foundry sprzedawane przez platformę Azure
• Pracowanie z modelami Azure OpenAI
• Limity przydziału i limity Azure OpenAI
• v1 Specyfikacje openAPI 3.0