Microsoft i modelli Foundry consentono di accedere a un'ampia gamma di modelli da molti provider tramite un singolo endpoint e un set di credenziali. Questa funzionalità consente di passare da un modello all'altro e usarli nell'applicazione senza apportare modifiche al codice.
Questo articolo illustra come i servizi Foundry organizzano i modelli e come usare l'endpoint di inferenza per accedervi.
Prerequisiti
Distribuzioni
Foundry utilizza le distribuzioni come alias per l'accesso al modello. Una distribuzione assegna un nome a un modello e a un set di configurazioni. È possibile accedere a un modello usando il relativo nome di distribuzione nelle richieste.
Una distribuzione definisce:
- Nome di un modello
- Una versione del modello
- Approvvigionamento o tipo di capacità1
- Configurazione del filtro del contenuto1
- Configurazione di limitazione della frequenza1
1 Queste configurazioni possono cambiare a seconda del modello selezionato.
Una risorsa Foundry può avere molte implementazioni di modelli. Si paga solo per l'inferenza eseguita nelle implementazioni dei modelli. Le distribuzioni sono risorse di Azure, quindi sono soggette alle politiche di Azure.
Per altre informazioni sulla creazione di distribuzioni, vedere Aggiungere e configurare distribuzioni di modelli.
Azure endpoint di inferenza OpenAI
LAzure API OpenAI espone le funzionalità complete dei modelli OpenAI e supporta altre funzionalità come assistenti, thread, file e inferenza batch. È anche possibile usarlo per accedere ai modelli non OpenAI.
Gli endpoint Azure OpenAI sono formattati come https://<resource-name>.openai.azure.com. Gli endpoint corrispondono alle distribuzioni e ogni distribuzione ha il proprio URL associato. Tuttavia, è possibile usare lo stesso meccanismo di autenticazione per utilizzare più distribuzioni. Per altre informazioni, vedere la pagina di riferimento per Azure API OpenAI.
Gli URL di distribuzione sono formati concatenando l'URL di base OpenAI Azure e la route /deployments/<model-deployment-name>. Quando utilizzi l'API OpenAI v1, chiama la route /openai/v1/ sull'URL di base, https://<resource-name>.openai.azure.com/openai/v1/, e passa il nome del deployment nel campo model della richiesta. La route /openai/v1/ usa il controllo di versione implicito, quindi non devi passare un api-version.
Gli esempi seguenti usano l'API Risposte, che supporta le funzionalità di inferenza più recenti.
Note
L'API Risposte funziona con Azure modelli OpenAI e con i modelli Foundry venduti da Azure che lo supportano, ad esempio i modelli DeepSeek, Llama e Grok. Se una distribuzione non supporta l'API Risposte, la richiesta restituisce 400 Model not supported. In tal caso, usa invece l'API Chat Completions chiamando client.chat.completions.create.
Usare l'autenticazione con chiave API
È possibile autenticare le richieste di inferenza con una chiave API dalla risorsa Foundry. Le chiavi API sono rapide da configurare, ma concedono l'accesso completo alla risorsa, sono difficili da definire per specifici utenti o azioni e richiedono una rotazione manuale per rimanere sicuri. Per i carichi di lavoro di produzione, usare invece l'autenticazione senza chiave con Microsoft Entra ID.
Nell'esempio seguente è deepseek-v3-0324 il nome di una distribuzione del modello nella risorsa Microsoft Foundry. Sostituirlo con il proprio nome di distribuzione e archiviare la AZURE_INFERENCE_CREDENTIAL chiave API nella variabile di ambiente.
Installare il openai pacchetto usando pip:
pip install openai --upgrade
Creare un client che punti all'endpoint Azure OpenAI v1 e quindi generare una risposta. La route /openai/v1/ usa il controllo di versione implicito, quindi non devi passare un api-version. Inserisci il nome della distribuzione nel campo model:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://<resource>.openai.azure.com/openai/v1/",
api_key=os.environ["AZURE_INFERENCE_CREDENTIAL"],
)
response = client.responses.create(
model="deepseek-v3-0324", # Replace with your model deployment name.
input="Explain the Riemann hypothesis in one paragraph.",
)
print(response.output_text)
Installare il openai pacchetto usando npm:
npm install openai
Creare un client che punti all'endpoint Azure OpenAI v1 e quindi generare una risposta:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://<resource>.openai.azure.com/openai/v1/",
apiKey: process.env.AZURE_INFERENCE_CREDENTIAL,
});
const response = await client.responses.create({
model: "deepseek-v3-0324", // Replace with your model deployment name.
input: "Explain the Riemann hypothesis in one paragraph.",
});
console.log(response.output_text);
Installare la libreria OpenAI:
dotnet add package OpenAI
Creare un client che punti all'endpoint Azure OpenAI v1 e quindi generare una risposta:
using System.ClientModel;
using OpenAI;
using OpenAI.Responses;
OpenAIClient client = new(
new ApiKeyCredential(Environment.GetEnvironmentVariable("AZURE_INFERENCE_CREDENTIAL")),
new OpenAIClientOptions
{
Endpoint = new Uri("https://<resource>.openai.azure.com/openai/v1/")
});
OpenAIResponseClient responseClient = client.GetResponsesClient("deepseek-v3-0324");
OpenAIResponse response = responseClient.CreateResponse(
"Explain the Riemann hypothesis in one paragraph.");
Console.WriteLine(response.GetOutputText());
Aggiungere OpenAI Java SDK al progetto. Controllare il repository Java OpenAI per la versione più recente.
Creare un client che punti all'endpoint Azure OpenAI v1 e quindi generare una risposta:
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;
OpenAIClient client = OpenAIOkHttpClient.builder()
.baseUrl("https://<resource>.openai.azure.com/openai/v1/")
.apiKey(System.getenv("AZURE_INFERENCE_CREDENTIAL"))
.build();
Response response = client.responses().create(
ResponseCreateParams.builder()
.model("deepseek-v3-0324") // Replace with your model deployment name.
.input("Explain the Riemann hypothesis in one paragraph.")
.build());
// The Responses API has no single output-text accessor; concatenate the output items.
response.output().stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(outputText -> System.out.println(outputText.text()));
Inviare richieste direttamente alla route v1. Il percorso /openai/v1/ usa il controllo delle versioni implicito, quindi non includi un parametro di query api-version. Passare la chiave nell'intestazione Authorization come token di connessione:
curl -X POST https://<resource>.openai.azure.com/openai/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AZURE_INFERENCE_CREDENTIAL" \
-d '{
"model": "deepseek-v3-0324",
"input": "Explain the Riemann hypothesis in one paragraph."
}'
Per ulteriori informazioni su come utilizzare l'endpoint di Azure OpenAI, vedi supporto linguistico dell'SDK di Azure OpenAI.
Usare l'autenticazione senza chiave
I modelli Foundry distribuiti supportano l'autorizzazione senza chiave con Microsoft Entra ID. L'autorizzazione senza chiave migliora la sicurezza, semplifica l'esperienza utente, riduce la complessità operativa e offre un supporto affidabile per la conformità. Usare l'autorizzazione senza chiave se l'organizzazione usa soluzioni di gestione delle identità sicure e scalabili.
Per usare l'autenticazione senza chiave, configurare la risorsa e concedere l'accesso agli utenti per eseguire l'inferenza. Dopo aver configurato la risorsa e concesso l'accesso, eseguire l'autenticazione come indicato di seguito:
Installare OpenAI SDK usando una gestione pacchetti come pip:
pip install openai
Per l'autenticazione Microsoft Entra ID, installare anche:
pip install azure-identity
Usare il pacchetto per utilizzare il modello. L'esempio seguente illustra come creare un client e effettuare una chiamata di test all'API Responses usando Microsoft Entra ID e la distribuzione del modello.
Sostituire <resource> con il nome della risorsa Foundry. Trovarlo nel portale di Azure o eseguendo az cognitiveservices account list. Sostituire deepseek-v3-0324 con il nome effettivo della distribuzione.
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://<resource>.openai.azure.com/openai/v1/",
api_key=token_provider,
)
response = client.responses.create(
model="deepseek-v3-0324", # Replace with your model deployment name.
input="What is Azure AI?",
)
print(response.output_text)
Output previsto
Azure AI is a comprehensive suite of artificial intelligence services and tools from Microsoft that enables developers to build intelligent applications. It includes services for natural language processing, computer vision, speech recognition, and machine learning capabilities.
Riferimento: OpenAI Python SDK e DefaultAzureCredential classe.
Installare OpenAI SDK:
dotnet add package OpenAI
Per l'autenticazione Microsoft Entra ID, installare anche il pacchetto Azure.Identity:
dotnet add package Azure.Identity
Usare quindi il pacchetto per utilizzare il modello. L'esempio seguente illustra come creare un client e effettuare una chiamata di test all'API Responses usando Microsoft Entra ID e la distribuzione del modello.
Sostituire <resource> con il nome della risorsa Foundry (trovarlo nel portale di Azure). Sostituire deepseek-v3-0324 con il nome effettivo della distribuzione.
using Azure.Identity;
using OpenAI;
using OpenAI.Responses;
using System.ClientModel.Primitives;
#pragma warning disable OPENAI001
BearerTokenPolicy tokenPolicy = new(
new DefaultAzureCredential(),
"https://ai.azure.com/.default"
);
OpenAIResponseClient client = new(
model: "deepseek-v3-0324", // Replace with your model deployment name.
authenticationPolicy: tokenPolicy,
options: new OpenAIClientOptions()
{
Endpoint = new Uri("https://<resource>.openai.azure.com/openai/v1/")
}
);
OpenAIResponse response = client.CreateResponse("What is Azure AI?");
Console.WriteLine(response.GetOutputText());
Output previsto:
Azure AI is a comprehensive suite of artificial intelligence services and tools from Microsoft that enables developers to build intelligent applications. It includes services for natural language processing, computer vision, speech recognition, and machine learning capabilities.
Riferimento: OpenAI .NET SDK e DefaultAzureCredential classe.
Installare OpenAI SDK con npm:
npm install openai
Per l'autenticazione Microsoft Entra ID, installare anche:
npm install @azure/identity
Usare quindi il pacchetto per utilizzare il modello. L'esempio seguente illustra come creare un client e effettuare una chiamata di test all'API Responses usando Microsoft Entra ID e la distribuzione del modello.
Sostituire <resource> con il nome della risorsa Foundry (trovarlo nel portale di Azure o eseguendo az cognitiveservices account list). Sostituire deepseek-v3-0324 con il nome effettivo della distribuzione.
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://<resource>.openai.azure.com/openai/v1/",
apiKey: tokenProvider
});
const response = await client.responses.create({
model: "deepseek-v3-0324", // Replace with your model deployment name.
input: "What is Azure AI?"
});
console.log(response.output_text);
Output previsto:
Azure AI is a comprehensive suite of artificial intelligence services and tools from Microsoft that enables developers to build intelligent applications. It includes services for natural language processing, computer vision, speech recognition, and machine learning capabilities.
Riferimento: OpenAI Node.js SDK e classe DefaultAzureCredential.
Aggiungere OpenAI SDK al progetto. Controllare il repository GitHub Java di OpenAI per la versione più recente e le istruzioni di installazione.
Per l'autenticazione Microsoft Entra ID, aggiungere anche:
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
<version>1.18.0</version>
</dependency>
Usare quindi il pacchetto per utilizzare il modello. L'esempio seguente illustra come creare un client e effettuare una chiamata di test all'API Responses usando Microsoft Entra ID e la distribuzione del modello.
Sostituire <resource> con il nome della risorsa Foundry (trovarlo nel portale di Azure). Sostituire deepseek-v3-0324 con il nome effettivo della distribuzione.
import com.azure.identity.AuthenticationUtil;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.credential.BearerTokenCredential;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;
DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
OpenAIClient client = OpenAIOkHttpClient.builder()
.baseUrl("https://<resource>.openai.azure.com/openai/v1/")
.credential(BearerTokenCredential.create(
AuthenticationUtil.getBearerTokenSupplier(
tokenCredential,
"https://ai.azure.com/.default"
)
))
.build();
ResponseCreateParams params = ResponseCreateParams.builder()
.model("deepseek-v3-0324") // Replace with your model deployment name.
.input("What is Azure AI?")
.build();
Response response = client.responses().create(params);
// The Responses API has no single output-text accessor; concatenate the output items.
response.output().stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(outputText -> System.out.println(outputText.text()));
Output previsto:
Azure AI is a comprehensive suite of artificial intelligence services and tools from Microsoft that enables developers to build intelligent applications. It includes services for natural language processing, computer vision, speech recognition, and machine learning capabilities.
Riferimento: OpenAI Java SDK e DefaultAzureCredential classe.
Esplorare la progettazione dell'API nella sezione di riferimento per vedere quali parametri sono disponibili. Inserire il token di autenticazione (bearer) nell'header Authorization.
Ad esempio, la sezione di riferimento dell'API Risposte illustra in dettaglio come usare la /responses route per generare stime. Il /openai/v1/ percorso è incluso nella radice dell'URL:
Richiesta
Sostituire <resource> con il nome della risorsa Foundry (trovarlo nel portale di Azure o eseguendo az cognitiveservices account list). Sostituire deepseek-v3-0324 con il nome effettivo della distribuzione.
L'URL di base accetta entrambi i https://<resource>.openai.azure.com/openai/v1/ formati e https://<resource>.services.ai.azure.com/openai/v1/ .
curl -X POST https://<resource>.openai.azure.com/openai/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
-d '{
"model": "deepseek-v3-0324",
"input": "Explain what the bitter lesson is?"
}'
Risposta
Se l'autenticazione ha esito positivo, si riceve una 200 OK risposta con il risultato della risposta nel corpo della risposta:
{
"id": "resp_...",
"object": "response",
"created_at": 1738368234,
"model": "deepseek-v3-0324",
"status": "completed",
"output": [
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "The bitter lesson refers to a key insight in AI research that emphasizes the importance of general-purpose learning methods that leverage computation, rather than human-designed domain-specific approaches. It suggests that methods which scale with increased computation tend to be more effective in the long run."
}
]
}
],
"usage": {
"input_tokens": 28,
"output_tokens": 52,
"total_tokens": 80
}
}
I token devono essere rilasciati con l'ambito https://ai.azure.com/.default.
Ai fini dei test, il modo più semplice per ottenere un token valido per l'account utente consiste nell'usare il interfaccia della riga di comando di Azure. In una console accedere e richiedere un token eseguendo i comandi interfaccia della riga di comando di Azure seguenti:
az login
az account get-access-token --resource https://ai.azure.com --query "accessToken" --output tsv
Questo comando restituisce un token di accesso che è possibile archiviare nella $AZURE_OPENAI_AUTH_TOKEN variabile di ambiente.
Riferimento: API Responses
Contenuto correlato
