Interfejs API usługi Azure OpenAI w modelach usługi Microsoft Foundry w wersji 1 (wersja klasyczna)

Uwaga / Notatka

Ten dokument odnosi się do portalu Microsoft Foundry (klasycznego).

🔍 Zapoznaj się z dokumentacją rozwiązania Microsoft Foundry (nową), aby dowiedzieć się więcej o nowym portalu.

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

Uwaga / Notatka

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 platformy Azure - Utwórz ją za darmo
• Zasób Foundry lub zasób Azure OpenAI wdrożony w obsługiwanym regionie
• Co najmniej jedno wdrożenie modelu
• W przypadku uwierzytelniania w Microsoft Entra ID: przypisana do twojej tożsamości rola Cognitive Services OpenAI User. Aby uzyskać więcej informacji, zobacz Kontrola dostępu oparta na rolach dla usługi Azure OpenAI

Ewolucja interfejsu API

Wcześniej usługa Azure OpenAI otrzymała comiesięczne aktualizacje nowych wersji interfejsu API. Korzystanie z nowych funkcji wymagało stałego aktualizowania kodu i zmiennych środowiskowych przy każdej nowej wersji API. Usługa Azure OpenAI wymagała również dodatkowego kroku korzystania z klientów specyficznych dla platformy Azure, którzy utworzyli obciążenie podczas migrowania kodu między usługą OpenAI i usługą Azure OpenAI.

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

• Ciągły dostęp do najnowszych funkcji bez konieczności określania nowych api-version w każdym miesiącu.
• Szybszy cykl wydawania interfejsu API z nowszymi funkcjami uruchamianymi częściej.
• Wsparcie klienta OpenAI przy minimalnych zmianach kodu umożliwiających przełączanie między OpenAI i Azure OpenAI przy użyciu 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 usługi 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, będzie kontrolowany przez przekazywanie nagłówków specyficznych dla funkcji w wersji zapoznawczej, co umożliwia wybranie żądanych funkcji bez konieczności zamiany wersji interfejsu API. Alternatywnie niektóre funkcje będą wskazywać stan wersji zapoznawczej za pośrednictwem ścieżki interfejsu API i nie wymagają dodatkowego nagłówka.

Przykłady:

• /openai/v1/evals jest w wersji zapoznawczej i wymaga przekazania nagłówka "aoai-evals":"preview" .
• /openai/v1/fine_tuning/alpha/graders/ jest w wersji zapoznawczej i nie wymaga nagłówka niestandardowego z powodu obecności alpha w ścieżce interfejsu API.

W przypadku początkowego uruchomienia ogólnodostępnego interfejsu API (GA) w wersji 1 obsługiwane są tylko niektóre możliwości związane z wnioskowaniem i tworzeniem interfejsu API. Wszystkie funkcje oznaczone jako ogólnie dostępne (GA) są obsługiwane do użytku w środowisku produkcyjnym. Obsługa większej liczby funkcjonalności jest szybko rozszerzana.

Zmiany kodu

Python

API wersja 1

Przykłady języka Python w wersji 1

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().
• base_url przekazuje punkt końcowy usługi Azure OpenAI i /openai/v1 jest dołączany 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:

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

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

client = OpenAI()

Microsoft Entra ID:

Ważna

Obsługa automatycznego odświeżania tokenu była wcześniej obsługiwana przy użyciu AzureOpenAI() klienta. Interfejs API v1 usuwa tę zależność, dodając do klienta OpenAI() obsługę 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://cognitiveservices.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 przekazuje punkt końcowy usługi Azure OpenAI i /openai/v1 jest dołączany do adresu punktu końcowego.
• api_key Parametr jest ustawiony na token_provider, co umożliwia automatyczne pobieranie i odświeżanie tokenu uwierzytelniania zamiast używania statycznego klucza API.

C#

API wersja 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://cognitiveservices.azure.com/.default");
OpenAIClient client = new(
    authenticationPolicy: tokenPolicy,
    options: new OpenAIClientOptions()
    {
        Endpoint = new("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
    })

JavaScript

API wersja 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 OPENAI_BASE_URL i OPENAI_API_KEY:

const client = new OpenAI();

Microsoft Entra ID:

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

Idź

API wersja 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 OPENAI_BASE_URL i OPENAI_API_KEY:

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 języka Java w wersji 1

API wersja 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 OPENAI_BASE_URL i OPENAI_API_KEY:

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

Microsoft Entra ID:

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

REST

API wersja 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 usługi Azure OpenAI zalecamy korzystanie z Responses API, jednak interfejs API w wersji 1 umożliwia także 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 czatów OpenAI w wersji 1.

base_url będzie akceptować 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 / Notatka

Interfejs API odpowiedzi współpracuje również z modelami Foundry sprzedawanymi bezpośrednio przez platformę Azure, takimi jak Microsoft AI, DeepSeek i Grok. Aby dowiedzieć się, jak używać interfejsu API odpowiedzi z tymi modelami, zobacz Jak generować odpowiedzi tekstowe za pomocą modeli rozwiązania Microsoft Foundry.

Python

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

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://cognitiveservices.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://cognitiveservices.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://cognitiveservices.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);

Idź

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

• Specyfikacje interfejsu OpenAPI 3.0 w wersji 1

Status

Ogólnie dostępne funkcje są obsługiwane do użytku w środowisku produkcyjnym.

Ścieżka interfejsu API	Status
/openai/v1/chat/completions	Dostępne ogólnie
/openai/v1/embeddings	Dostępne ogólnie
/openai/v1/evals	Preview
/openai/v1/files	Dostępne ogólnie
/openai/v1/fine_tuning/jobs/{fine_tuning_job_id}/checkpoints/{fine_tuning_checkpoint_id}/copy	Preview
/openai/v1/fine_tuning/alpha/graders/	Preview
/openai/v1/fine_tuning/	Dostępne ogólnie
/openai/v1/models	Dostępne ogólnie
/openai/v1/responses	Dostępne ogólnie
/openai/v1/vector_stores	Dostępne ogólnie

Podgląd nagłówków

Ścieżka interfejsu API	Nagłówek
/openai/v1/evals	"aoai-evals":"preview"
/openai/v1/fine_tuning/jobs/{fine_tuning_job_id}/checkpoints/{fine_tuning_checkpoint_id}/copy	"aoai-copy-ft-checkpoints" : "preview"

Dziennik zmian wersji interfejsu API

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

Zmiany między wersją wstępną 1 a wersją 2025-04-01-preview

• API w wersji 1 zapoznawczej
• 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
• Interfejs API ewaluacji

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 wyniki (obsługa API destylacji).

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

• prediction Dodano parametr do obsługi przewidywanych danych wyjściowych .
• 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 obsługę integracji 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 .
• Dodano: parallel_tool_calls.
• completion_tokens_details i reasoning_tokens dodano.
• stream_options i include_usage dodano.

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

• Wsparcie dla strukturalnych danych wyjściowych.
• Dodano interfejs API przekazywania dużych plików.
• Zmiany twoich danych:
  • Integracja z bazą danych Mongo DB.
  • role_information parametr został usunięty.
  • rerank_score dodano do obiektu cytatu.
  • Usunięto źródło danych AML.
  • Ulepszenia integracji wektoryzacji wyszukiwania sztucznej inteligencji.

Zmiany między „2024-05-01-preview” a „2024-07-01-preview” specyfikacji API

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

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

• Obsługa asystentów wersja druga — narzędzie wyszukiwania plików i przechowywanie wektorów
• Dostrajanie punktów kontrolnych, nasion, zdarzeń
• Aktualizacje Twoich danych
• DALL-E 2 obsługuje teraz wdrażanie modelu i może być używany z najnowszym API w wersji zapoznawczej.
• Aktualizacje filtrowania zawartości

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

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

Rozwiązywanie problemów

Problematyka	Przyczyna	Rozwiązanie
404 Not Found podczas wywoływania interfejsu API w wersji 1	Nieprawidłowy base_url format	Sprawdź, czy adres URL kończy się ciągiem /openai/v1/. Oba https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/ i https://YOUR-RESOURCE-NAME.services.ai.azure.com/openai/v1/ są prawidłowe.
401 Unauthorized z identyfikatorem Entra	Brakujące lub nieprawidłowe przypisanie roli	Przypisz rolę Cognitive Services OpenAI User do swojej tożsamości. Propagowanie przypisań ról może potrwać do 5 minut.
AzureOpenAI() klient nie działa w wersji 1	Interfejs API w wersji 1 (OpenAI()) używa klienta	Zastąp AzureOpenAI() ciągiem OpenAI() i ustaw base_url na punkt końcowy platformy Azure z dołączonym /openai/v1/.
api-version parametr odrzucony	API v1 nie używa api-version	Usuń wszystkie api-version parametry zapytania z żądań. Interfejs API w wersji 1 nie wymaga ani nie akceptuje ich.
Funkcje w wersji zapoznawczej są niedostępne	Brak nagłówka podglądu	W przypadku interfejsów API w wersji zapoznawczej, takich jak /openai/v1/evals, przekaż wymagany nagłówek podglądu (na przykład "aoai-evals":"preview"). Zobacz Podgląd nagłówków.

Znane problemy

• Specyfikacja 2025-04-01-preview usługi Azure OpenAI używa interfejsu OpenAPI 3.1. Znanym problemem jest to, że ta wersja nie jest w pełni obsługiwana przez usługę Azure API Management.

Dalsze kroki

• Obsługiwane języki programowania dla interfejsu API w wersji 1
• Modele foundry sprzedawane bezpośrednio przez platformę Azure
• Praca z modelami usługi Azure OpenAI
• Limity przydziału i ograniczenia usługi Azure OpenAI
• Specyfikacje interfejsu OpenAPI 3.0 w wersji 1