Azure OpenAI nell'API Microsoft Foundry Models v1 (versione classica)

Attualmente visualizzando:Versione del portale Foundry (Versione Classica) - Passa alla versione per il nuovo portale Foundry

Annotazioni

I collegamenti in questo articolo potrebbero aprire contenuto nella nuova documentazione di Microsoft Foundry anziché nella documentazione di Foundry (versione classica) visualizzata.

Questo articolo illustra come usare l'API OpenAI v1 Azure. L'API v1 semplifica l'autenticazione, rimuove la necessità di parametri datati api-version e supporta le chiamate al modello tra provider.

Annotazioni

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

Prerequisiti

• Una sottoscrizione Azure - Crearne una gratuitamente
• Una risorsa Foundry o risorsa Azure OpenAI distribuita in un'area supportata
• Almeno un'implementazione del modello
• Per l'autenticazione di Microsoft Entra ID: il ruolo Cognitive Services OpenAI User è assegnato all'identità interessata. Per altre informazioni, vedere Controllo degli accessi in base al ruolo per Azure OpenAI

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 Azure client specifici che hanno creato un sovraccarico durante la migrazione del codice tra OpenAI e Azure OpenAI.

A partire da agosto 2025, è possibile optare per le API Azure OpenAI di nuova generazione v1 che aggiungono supporto per:

• Accesso continuo alle funzionalità più recenti senza dover specificare nuovi api-version ogni mese.
• Ciclo di rilascio più rapido dell'API con nuove funzionalità che vengono lanciate più frequentemente.
• Supporto client OpenAI con modifiche minime al codice per passare tra OpenAI e Azure OpenAI quando si usa l'autenticazione basata su chiave.
• Supporto client OpenAI per l'autenticazione basata su token e l'aggiornamento automatico del token senza la necessità di accettare una dipendenza da un client OpenAI separato Azure.
• 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 per funzionalità per consentire di selezionare esplicitamente le funzionalità desiderate, senza dover cambiare le versioni dell'API. In alternativa, alcune funzionalità indicheranno lo stato di anteprima tramite il percorso dell'API e non richiedono un'intestazione aggiuntiva.

Esempi:

• Quando /openai/v1/evals era in fase di anteprima, era necessario inviare un'intestazione "aoai-evals":"preview". /evals non è più in anteprima.
• /openai/v1/fine_tuning/alpha/graders/ è in anteprima e non richiede alcuna intestazione personalizzata a causa della presenza di alpha nel percorso API.

Per il lancio iniziale della versione v1 GA (General Availability) dell'API, è supportato solo un sottoinsieme delle funzionalità di inferenza e creazione. Tutte le funzionalità di disponibilità generale sono supportate per l'uso nell'ambiente di produzione. Il supporto per altre funzionalità viene aggiunto rapidamente.

Modifiche al codice

Python

API v1

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

Differenze principali rispetto all'API precedente:

• OpenAI() il client viene usato invece di AzureOpenAI().
• base_url passa attraverso 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:

Impostare le variabili di ambiente seguenti prima di eseguire il codice:

Variable	Value
OPENAI_BASE_URL	https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/
OPENAI_API_KEY	La tua chiave API di Azure OpenAI

Creare quindi il client senza parametri:

client = OpenAI()

Microsoft Entra ID:

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://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 passa l'endpoint di Azure OpenAI 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/"),
    })

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

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

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

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

esempi 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();

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

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

Supporto di modelli

Per Azure modelli OpenAI è consigliabile usare l'API Responses, 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 Microsoft modelli di intelligenza artificiale, DeepSeek e Grok. Per informazioni su come usare l'API Risposte con questi modelli, vedere Come generare risposte di testo con Microsoft Modelli 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);

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

Supporto delle API v1

• Specifica v1 OpenAPI 3.0

Log delle modifiche della versione dell'API

Le sezioni seguenti riepilogano le modifiche tra le versioni dell'API.

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

• GPT-image-1 supporto
• Riepilogo del ragionamento per o3 e o4-mini
• Evaluation API

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

• API 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.
• user_security_context aggiunto 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-05-01-preview e 2024-07-01-preview

• Supporto dell'API Batch aggiunto
• Parametri della strategia di suddivisione in blocchi per archiviazione 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 degli Assistenti v2 - Strumento di ricerca file e memorizzazione vettoriale
• Ottimizzazione di punti di controllo, seed, 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.
• timestamp_granularities parametro aggiunto.
• audioWord oggetto aggiunto.
• TTS aggiuntivo response_formats: wav & pcm.

Problemi noti

• La specifica 2025-04-01-preview Azure OpenAI usa OpenAPI 3.1. Si tratta di un problema noto che questa versione non è completamente supportata da Gestione API di Azure.

Passaggi successivi

• Linguaggi di programmazione supportati per l'API v1
• Modelli di fonderia venduti direttamente da Azure
• Lavorare con i modelli Azure OpenAI
• Azure OpenAI: quote e limiti
• Specifica v1 OpenAPI 3.0