Ciclo di vita dell'API Azure OpenAI nei modelli di Microsoft Foundry

Questo articolo illustra il ciclo di vita del supporto per le API OpenAI di Azure.

Annotazioni

È possibile aggiungere nuovi oggetti di risposta API alla risposta API in qualsiasi momento. È consigliabile analizzare solo gli oggetti risposta necessari.

Evoluzione dell'API

In precedenza, Azure OpenAI ha ricevuto aggiornamenti mensili delle nuove versioni delle API. Sfruttare le nuove funzionalità necessarie per aggiornare costantemente il codice e le variabili di ambiente con ogni nuova versione dell'API. Azure OpenAI richiede anche il passaggio aggiuntivo dell'uso di client specifici di Azure che hanno creato un sovraccarico durante la migrazione del codice tra OpenAI e Azure OpenAI.

A partire da agosto 2025, è ora possibile acconsentire esplicitamente alle API OpenAI di Azure v1 di nuova generazione che aggiungono supporto per:

• Accesso continuo alle funzionalità più recenti senza la necessità di specificare nuovi api-versionogni mese.
• Ciclo di rilascio più rapido dell'API con nuove funzionalità che vengono lanciate più frequentemente.
• Supporto client OpenAI con minime modifiche al codice per consentire il passaggio tra OpenAI e Azure OpenAI utilizzando l'autenticazione basata su chiave.
• Supporto client OpenAI per l'autenticazione basata su token e l'aggiornamento automatico dei token senza la necessità di accettare una dipendenza da un client OpenAI di Azure separato.
• Effettuare chiamate di completamento della chat con modelli di altri provider, ad esempio DeepSeek e Grok, che supportano la sintassi dei completamenti della chat v1.

L'accesso alle nuove chiamate API ancora in anteprima verrà controllato passando intestazioni di anteprima specifiche delle funzionalità che consentono di acconsentire esplicitamente alle funzionalità desiderate, senza dover scambiare le versioni dell'API. In alternativa, alcune funzionalità indicheranno lo stato di anteprima tramite il percorso dell'API e non richiedono un'intestazione aggiuntiva.

Examples:

• /openai/v1/evals è in anteprima e richiede il passaggio di un'intestazione "aoai-evals":"preview".
• /openai/v1/fine_tuning/alpha/graders/ è in anteprima e non richiede alcuna intestazione personalizzata a causa della presenza di alpha nel percorso API.

Per l'avvio iniziale dell'API v1 disponibile a livello generale è supportato solo un sottoinsieme delle funzionalità API di inferenza e creazione. Tutte le funzionalità di disponibilità generale sono supportate per l'uso nell'ambiente di produzione. Presto verrà aggiunto il supporto per altre funzionalità.

Modifiche al codice

Python

API v1

Esempi di Python v1

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

• OpenAI() il client viene usato invece di AzureOpenAI().
• base_url trasmette l'endpoint OpenAI di Azure e /openai/v1 viene aggiunto all'indirizzo dell'endpoint.
• api-version non è più un parametro obbligatorio con l'API di disponibilità generale v1.

Chiave API con variabili di ambiente impostate per OPENAI_BASE_URL e OPENAI_API_KEY:

client = OpenAI()

ID Microsoft Entra:

Importante

La gestione dell'aggiornamento automatico dei token è stata gestita in precedenza tramite l'uso del client AzureOpenAI(). L'API v1 rimuove questa dipendenza aggiungendo il supporto dell'aggiornamento automatico dei token al client OpenAI().

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 trasmette l'endpoint OpenAI di Azure e /openai/v1 viene aggiunto all'indirizzo dell'endpoint.
• Il parametro api_key è impostato su token_provider, abilitando il recupero automatico e l'aggiornamento di un token di autenticazione invece di usare una chiave API statica.

C#

API v1

Esempi di C# v1

Chiave API:

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

ID Microsoft Entra:

#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 v1

Esempi di JavaScript v1

Chiave API:

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

Chiave API con variabili di ambiente impostate per OPENAI_BASE_URL e OPENAI_API_KEY:

const client = new OpenAI();

ID Microsoft Entra:

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

Go

API v1

Esempi di Go v1

Chiave API:

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

Chiave API con variabili di ambiente impostate per OPENAI_BASE_URL e OPENAI_API_KEY:

client := openai.NewClient()

ID 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

Esempi di Java v1

API v1

Chiave API:

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

Chiave API con variabili di ambiente impostate per OPENAI_BASE_URL e OPENAI_API_KEY:

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

ID Microsoft Entra:

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 v1

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

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

Supporto di modelli

Per i modelli OpenAI di Azure è consigliabile usare l'API Risposte, tuttavia, l'API v1 consente anche di effettuare chiamate di completamento della chat con modelli di altri provider, ad esempio DeepSeek e Grok, che supportano la sintassi di completamenti chat OpenAI v1.

base_url accetterà sia i formati https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/ che https://YOUR-RESOURCE-NAME.services.ai.azure.com/openai/v1/.

Annotazioni

L'API Risposte funziona anche con i modelli Foundry venduti direttamente da Azure, ad esempio i modelli Microsoft AI, DeepSeek e Grok. Per informazioni su come usare l'API Risposte con questi modelli, vedere Come generare risposte di testo con i modelli di 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);

Go

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

Supporto delle API v1

• Specifica v1 OpenAPI 3.0

Stato

Le funzionalità disponibili a livello generale sono supportate per l'uso nell'ambiente di produzione.

Percorso API	Stato
/openai/v1/chat/completions	Generalmente disponibile
/openai/v1/embeddings	Generalmente disponibile
/openai/v1/evals	Preview
/openai/v1/files	Generalmente disponibile
/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/	Generalmente disponibile
/openai/v1/models	Generalmente disponibile
/openai/v1/responses	Generalmente disponibile
/openai/v1/vector_stores	Generalmente disponibile

Intestazioni di anteprima

Percorso API	Intestazione
/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"

Modifiche tra la versione di anteprima v1 e la versione 2025-04-01-preview

• API di anteprima v1
• Supporto per la generazione di video
• NUOVE funzionalità dell'API delle risposte:
  • Integrazione di strumenti per i server del protocollo Remote Model Context (MCP)
  • Supporto per le attività in background asincrone
  • Elementi di ragionamento crittografati
  • Generazione di immagini

Modifiche tra 2025-04-01-preview e 2025-03-01-preview

• Supporto GPT-image-1
• Riepilogo del ragionamento per o3 e o4-mini
• API di valutazione

Modifiche tra 2025-03-01-preview e 2025-02-01-preview

• API delle risposte
• Uso del computer

Modifiche tra 2025-02-01-preview e 2025-01-01-preview

• Completamenti archiviati (supporto API di distillazione).

Modifiche tra 2025-01-01-preview e 2024-12-01-preview

• È stato aggiunto il parametro prediction per il supporto degli output previsti.
• gpt-4o-audio-preview supporto del modello.

Modifiche tra 2024-12-01-preview e 2024-10-01-preview

• Parametri store e metadata aggiunti per il supporto per le stored completion.
• È stato aggiunto reasoning_effort per i modelli di ragionamento più recenti.
• È stato aggiunto user_security_context per l’integrazione di Microsoft Defender per il cloud.

Modifiche tra 2024-09-01-preview e 2024-08-01-preview

• È stato aggiunto max_completion_tokens per supportare i modelli o1-preview e o1-mini. max_tokens non funziona con i modelli della serie o1.
• parallel_tool_calls aggiunto.
• Sono stati aggiunti completion_tokens_details e reasoning_tokens.
• Sono stati aggiunti stream_options e include_usage.

Modifiche delle specifiche tra l’API 2024-07-01-preview e 2024-08-01-preview

• Supporto degli output strutturati.
• API di caricamento di file di grandi dimensioni aggiunta.
• Nelle modifiche apportate ai dati:
  • Integrazione di Mongo DB.
  • Parametro role_information rimosso.
  • rerank_score aggiunto all’oggetto di citazione.
  • Origine dati AML rimossa.
  • Miglioramenti all’integrazione della vettorizzazione della ricerca di intelligenza artificiale.

Modifiche tra la specifica dell'API 2024-5-01-preview e 2024-07-01-preview

• Supporto dell'API Batch aggiunto
• Parametri della strategia di suddivisione in blocchi dell'archivio vettoriale
• max_num_results che lo strumento di ricerca file deve produrre.

Modifiche tra la specifica dell'API 2024-04-01-preview e 2024-05-01-preview

• Supporto per Assistants v2 - Strumento di ricerca file e archiviazione vettoriale
• Ottimizzazione di checkpoint, valori di inizializzazione, eventi
• Aggiornamenti sui dati
• DALL-E 2 ora supporta la distribuzione del modello e può essere usato con l'API di anteprima più recente.
• Aggiornamenti del filtro del contenuto

Modifiche tra la specifica dell'API 2024-03-01-preview e 2024-04-01-preview

• Modifica di rilievo: i parametri dei miglioramenti sono stati rimossi. Ciò influisce sul modello gpt-4Versione:vision-preview.
• Parametro timestamp_granularities aggiunto.
• Oggetto audioWord aggiunto.
• Sintesi vocale aggiuntiva response_formats: wav & pcm.

Problemi noti

• La 2025-04-01-preview specifica OpenAI di Azure usa OpenAPI 3.1, è un problema noto che attualmente non è completamente supportato da Gestione API di Azure

Passaggi successivi

• Altre informazioni su Azure OpenAI
• Informazioni sull'uso dei modelli OpenAI di Azure