Ciclo di vita dell'API di Azure OpenAI nei modelli di Azure AI 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 senza modifiche alla versione. È consigliabile analizzare solo gli oggetti risposta necessari.

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

Evoluzione dell'API

Storicamente, 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 maggio 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 dover aggiornare api-version ogni mese.
• Supporto client OpenAI con minime modifiche al codice per consentire il passaggio tra OpenAI e Azure OpenAI utilizzando l'autenticazione basata su chiave.

Per l'avvio dell'anteprima iniziale è supportato solo un subset dell'API di inferenza. Durante l'anteprima, le operazioni potrebbero avere funzionalità incomplete che verranno espanse continuamente.

Modifiche al codice

Chiave API

API di ultima generazione

import os
from openai import AzureOpenAI

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2025-04-01-preview",
    azure_endpoint="https://YOUR-RESOURCE-NAME.openai.azure.com")
    )

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 di nuova generazione

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/",
    default_query={"api-version": "preview"}, 
)

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.
• default_query={"api-version": "preview"} indica che viene usata sempre l'API di anteprima senza versione up-to-data.

Dopo aver rilasciato l'API di prossima generazione v1 a livello generale, verranno supportati due valori: latest e preview. Se api-version non viene passato, il traffico viene indirizzato automaticamente alla versione GA latest. Attualmente è supportato solo preview.

Microsoft Entra ID

API di ultima generazione

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

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

client = AzureOpenAI(
  azure_endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/", 
  azure_ad_token_provider=token_provider,
  api_version="2025-04-01-preview"
)

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 di nuova generazione

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

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

client = AzureOpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  azure_ad_token_provider=token_provider,
  api_version="preview"
)

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

print(response.model_dump_json(indent=2)) 

• AzureOpenAI() viene usato per sfruttare i vantaggi dell'aggiornamento automatico dei token fornito da azure_ad_token_provider.
• base_url trasmette l'endpoint OpenAI di Azure e /openai/v1 viene aggiunto all'indirizzo dell'endpoint.
• api-version="preview" indica che viene usata sempre l'API di anteprima senza versione up-to-data.

Dopo aver rilasciato l'API di prossima generazione v1 a livello generale, verranno supportati due valori: latest e preview. Se api-version non viene passato, il traffico viene indirizzato automaticamente alla versione GA latest. Attualmente è supportato solo preview.

REST

API di ultima generazione

Chiave API:

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/responses?api-version=2025-04-01-preview \
  -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/responses?api-version=2025-04-01-preview \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
     "model": "gpt-4.1-nano",
     "input": "This is a test"
    }'

API di nuova generazione

Chiave API:

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses?api-version=preview \
  -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?api-version=preview \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
     "model": "gpt-4o",
     "input": "This is a test"
    }'

Risultato

{
  "id": "resp_682f7eb5dc408190b491cbbe57be2fbf0f98d661c3dc276d",
  "created_at": 1747943093.0,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "metadata": {},
  "model": "gpt-4.1-nano",
  "object": "response",
  "output": [
    {
      "id": "msg_682f7eb61d908190926a004c15c5ddd00f98d661c3dc276d",
      "content": [
        {
          "annotations": [],
          "text": "Hello! It looks like you've sent a test message. How can I assist you today?",
          "type": "output_text"
        }
      ],
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": true,
  "temperature": 1.0,
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1.0,
  "background": null,
  "max_output_tokens": null,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "generate_summary": null,
    "summary": null
  },
  "service_tier": "default",
  "status": "completed",
  "text": {
    "format": {
      "type": "text"
    }
  },
  "truncation": "disabled",
  "usage": {
    "input_tokens": 12,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 19,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 31
  },
  "user": null,
  "store": true
}

Versioni dell'API di anteprima

Versioni più recenti dell'API OpenAI di Azure:

• NUOVA API di anteprima v1
• Inferenza: 2025-04-01-preview
• Creazione: 2025-04-01-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 (distillazione) Supporto API.

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

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

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

• storeParametri e metadata aggiunti per il supporto dei completamenti archiviati.
• reasoning_effortaggiunta per i modelli di ragionamento più recenti.
• user_security_contextaggiunta per l'integrazione di Microsoft Defender per il cloud.

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

• max_completion_tokens aggiunta al supporto o1-preview e o1-mini ai modelli. max_tokens non funziona con i modelli di serie o1.
• parallel_tool_calls aggiunto.
• completion_tokens_details & reasoning_tokens aggiunto.
• stream_options & include_usage aggiunto.

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 che causa un'interruzione: i parametri dei miglioramenti sono stati rimossi. Ciò influisce sulla Versione di gpt-4: modello vision-preview.
• Parametro timestamp_granularities aggiunto.
• Oggetto audioWord aggiunto.
• Ulteriore TTS response_formats: wav & pcm.

Versione più recente dell'API con disponibilità generale

L'API OpenAI di Azure versione 2024-10-21 è attualmente la versione più recente dell'API ga. Questa versione dell'API è la sostituzione della versione precedente dell'API con disponibilità generale 2024-06-01.

Aggiornamento delle versioni dell'API

È consigliabile testare prima l'aggiornamento alle nuove versioni dell'API per verificare che l'aggiornamento dell'API non abbia alcun impatto sull'applicazione prima di effettuare la modifica a livello globale nell'ambiente.

Se si usano librerie client Python OpenAI o JavaScript, oppure l'API REST, è necessario aggiornare il codice direttamente alla versione dell'API di anteprima più recente.

Se si usa uno degli SDK di Azure OpenAI per C#, Go o Java, è invece necessario eseguire l'aggiornamento all'ultima versione dell'SDK. Ogni versione dell'SDK è hardcoded per funzionare con versioni specifiche dell'API OpenAI di Azure.

Passaggi successivi

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