Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Una risorsa Foundry consente l'accesso unificato a modelli, agenti e strumenti. Questo articolo illustra l'SDK e l'endpoint da usare per lo scenario.
| SDK | Scopo | Punto finale |
|---|---|---|
| Foundry SDK | Funzionalità specifiche di Foundry con interfacce compatibili con OpenAI. Include l'accesso ai modelli diretti di Foundry tramite l'API Risposte (non i completamenti della chat). | https://<resource-name>.services.ai.azure.com/api/projects/<project-name> |
| OpenAI SDK | Modelli e funzionalità più recenti di OpenAI SDK con la superficie completa dell'API OpenAI. Modelli Foundry diretti disponibili tramite l'API di Completamento Chat (non Risposte). | https://<resource-name>.openai.azure.com/openai/v1 |
| Foundry Tools SDK | Soluzioni predefinite (Visione, Riconoscimento vocale, Sicurezza del contenuto e altro ancora). | Endpoint specifici degli strumenti (varia in base al servizio). |
| Framework degli agenti | Orchestrazione multi-agente nel codice. Indipendente dal cloud. | Usa l'endpoint del progetto tramite Foundry SDK. |
Scegliere l'SDK:
- Usare Foundry SDK per la creazione di app con agenti, valutazioni o funzionalità specifiche di Foundry
- Usare OpenAI SDK quando è necessaria la compatibilità massima di OpenAI o l'uso di modelli diretti di Foundry tramite completamento chat
- Usare gli SDK degli strumenti Foundry quando si usano servizi di intelligenza artificiale specifici (Visione, Riconoscimento vocale, Lingua e così via)
- Usare Agent Framework quando si creano sistemi multi-agente nel codice (orchestrazione locale)
Annotazioni
Tipi di risorsa: Una risorsa Foundry fornisce tutti gli endpoint elencati in precedenza. Una risorsa OpenAI di Azure fornisce solo l'endpoint /openai/v1 .
Autenticazione: Gli esempi qui usano Microsoft Entra ID (DefaultAzureCredential). Le chiavi API funzionano in /openai/v1. Passare la chiave come api_key anziché un provider di token.
Prerequisiti
-
Un account Azure con una sottoscrizione attiva. Se non ne hai uno, crea un account Azure gratuito, che include una sottoscrizione gratuita di prova.
Avere uno dei seguenti ruoli RBAC di Azure per creare e gestire le risorse Foundry.
- Utente di Intelligenza artificiale di Azure (ruolo con privilegi minimi per lo sviluppo)
- Azure AI Project Manager (per la gestione dei progetti Foundry)
- Collaboratore o proprietario (per le autorizzazioni a livello di sottoscrizione)
Per informazioni dettagliate sulle autorizzazioni di ogni ruolo, vedere Controllo degli accessi in base al ruolo per Microsoft Foundry.
Installare i runtime del linguaggio necessari, gli strumenti globali e le estensioni di VS Code, come descritto in Preparare l'ambiente di sviluppo.
Importante
Prima di iniziare, assicurarsi che l'ambiente di sviluppo sia pronto.
Questo articolo è incentrato su passaggi specifici dello scenario , ad esempio l'installazione dell'SDK, l'autenticazione e l'esecuzione di codice di esempio.
Verificare i prerequisiti
Prima di procedere, confermare:
- [ ] La sottoscrizione di Azure è attiva:
az account show - [ ] Si dispone del ruolo RBAC richiesto: controllare il portale di Azure → risorsa Foundry → Controllo di accesso (IAM)
- [ ] Runtime del linguaggio installato:
- Python:
python --version(≥3.8) - Node.js:
node --version(≥18) - .NET:
dotnet --version(≥6.0) - Java:
java --version(≥11)
- Python:
Foundry SDK
Foundry SDK si connette a un singolo endpoint di progetto che fornisce l'accesso alle funzionalità foundry più diffuse:
https://<resource-name>.services.ai.azure.com/api/projects/<project-name>
Annotazioni
Se l'organizzazione usa un sottodominio personalizzato, sostituire <resource-name> con <your-custom-subdomain> nell'URL dell'endpoint.
Questo approccio semplifica la configurazione dell'applicazione. Anziché gestire più endpoint, è necessario configurare uno.
Installazione dell'SDK
Annotazioni
Versioni dell'SDK: L'SDK di anteprima 2.x è destinato al nuovo portale e all'API Foundry. L'SDK 1.x GA è destinato a Foundry Classico. Assicurarsi che gli esempi seguiti corrispondano al pacchetto installato.
| Versione SDK | Versione del portale | Condizione | Pacchetto Python |
|---|---|---|---|
| 2.x (anteprima) | Fonderia (nuovo) | Anteprima | azure-ai-projects>=2.0.0b1 --pre |
| 1.x (GA) | Fonderia classica | Stabile | azure-ai-projects==1.0.0 |
La libreria client di Azure AI Projects per Python è una libreria unificata che consente di usare più librerie client insieme connettendosi a un singolo endpoint di progetto.
Eseguire questi comandi per installare i pacchetti di anteprima per i progetti Foundry.
pip install --pre azure-ai-projects
pip install azure-identity openai
| Versione SDK | Versione del portale | Condizione | Pacchetto Java |
|---|---|---|---|
| 1.0.0-beta.3 1.0.0-beta.1 |
Fonderia (nuovo) | Anteprima | azure-ai-projectsazure-ai-agents |
| Versione SDK | Versione del portale | Condizione | Pacchetto JavaScript |
|---|---|---|---|
| 2.0.0-beta.4 (anteprima) | Fonderia (nuovo) | Anteprima | @azure/ai-projects 'prerelease' |
| 1.0.1 | Fonderia classica | Stabile | @azure/ai-projects |
| Versione SDK | Versione del portale | Condizione | Pacchetto .NET |
|---|---|---|---|
| 1.2.0-beta.5 (anteprima) | Fonderia (nuovo) | Anteprima | Azure.AI.ProjectsAzure.AI.Projects.Openai |
| 1.x (GA) | Fonderia classica | Stabile | Azure.AI.Projects |
La libreria client di Azure AI Projects per Java (anteprima) è una libreria unificata che consente di usare più librerie client insieme connettendosi a un singolo endpoint di progetto.
Importante
Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente disponibili in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliabile per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.
Aggiungere questi pacchetti all'installazione per i progetti Foundry.
package com.azure.ai.agents;
import com.azure.core.util.Configuration;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;
La libreria client di Azure AI Projects per JavaScript è una libreria unificata che consente di usare più librerie client insieme connettendosi a un singolo endpoint di progetto.
Eseguire questo comando per installare i pacchetti JavaScript di anteprima per i progetti Foundry.
npm install @azure/ai-projects@beta @azure/identity dotenv
La libreria client di Progetti di intelligenza artificiale di Azure per .NET è una libreria unificata che consente di usare più librerie client insieme connettendosi a un singolo endpoint di progetto.
Eseguire questo comando per aggiungere il pacchetto Azure.AI.Projects al progetto .NET.
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.AI.Projects.OpenAI --prerelease
dotnet add package Azure.Identity
Uso di Foundry SDK
L'SDK espone due tipi di client perché Foundry e OpenAI hanno forme API diverse:
- Client del progetto – usare per le operazioni native Foundry in cui OpenAI non ha equivalenti. Esempi: elencare le connessioni, recuperare le proprietà del progetto, abilitare la traccia.
-
Client compatibile con OpenAI : usare per la funzionalità Foundry basata sui concetti di OpenAI. L'API Risposte, gli agenti, le valutazioni e l'ottimizzazione usano tutti modelli di richiesta/risposta in stile OpenAI. Questo client consente inoltre di accedere ai modelli diretti Foundry (modelli nonAzure-OpenAI ospitati in Foundry). L'endpoint del progetto gestisce questo traffico sulla
/openairoute.
La maggior parte delle app usa entrambi i client. Usare il client di progetto per l'installazione e la configurazione, quindi usare il client compatibile con OpenAI per l'esecuzione di agenti, valutazioni e modelli di invocazione (inclusi i modelli diretti Foundry).
Creare un client di progetto:
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
project_client = AIProjectClient(
endpoint="https://<resource-name>.services.ai.azure.com/api/projects/<project-name>",
credential=DefaultAzureCredential())
Creare un client compatibile con OpenAI dal progetto:
with project_client.get_openai_client() as openai_client:
response = openai_client.responses.create(
model="gpt-5.2",
input="What is the size of France in square miles?",
)
print(f"Response output: {response.output_text}")
Output previsto:
Response output: France has an area of approximately 213,011 square miles (551,695 square kilometers).
Creare un client di progetto:
import com.azure.ai.projects.ProjectsClient;
import com.azure.ai.projects.ProjectsClientBuilder;
import com.azure.identity.DefaultAzureCredentialBuilder;
String endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
ProjectsClient projectClient = new ProjectsClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.endpoint(endpoint)
.buildClient();
```**Create and use an OpenAI-compatible client from your project:**
```java
OpenAIClient openAIClient = projectClient.getOpenAIClient();
Creare un client di progetto:
import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import "dotenv/config";
const projectEndpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
const deploymentName = "gpt-5.2";
const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
Creare un client compatibile con OpenAI dal progetto:
const openAIClient = await project.getOpenAIClient();
const response = await openAIClient.responses.create({
model: deploymentName,
input: "What is the size of France in square miles?",
});
console.log(`Response output: ${response.output_text}`);
Creare un client di progetto:
using Azure.AI.Projects.OpenAI;
using Azure.Identity;
using OpenAI.Responses;
string endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
AIProjectClient projectClient = new(
endpoint: new Uri(endpoint),
tokenProvider: new DefaultAzureCredential());
Creare un client compatibile con OpenAI dal progetto:
#pragma warning disable OPENAI001
OpenAIResponseClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForModel("gpt-5.2");
OpenAIResponse response = responseClient.CreateResponse("What is the speed of light?");
Console.WriteLine(response.GetOutputText());
#pragma warning restore OPENAI001
Operazioni che è possibile eseguire con Foundry SDK
- Accesso ai modelli Foundry, tra cui Azure OpenAI
- Usare il servizio agente Foundry
- Avviare valutazioni cloud
- Abilitare la traccia delle app
- Ottimizzare un modello
- Ottenere endpoint e chiavi per Foundry Tools, l'orchestrazione locale e altro ancora
Risoluzione dei problemi
Errori di autenticazione
Se viene visualizzato DefaultAzureCredential failed to retrieve a token:
Verificare che l'interfaccia della riga di comando di Azure sia autenticata:
az account show az login # if not logged inControllare l'assegnazione del ruolo RBAC
- Verificare di avere almeno il ruolo utente di Intelligenza artificiale di Azure nel progetto Foundry
- Consulta Assegnare ruoli di Azure
Per l'identità gestita nell'ambiente di produzione:
- Verificare che all'identità gestita sia assegnato il ruolo appropriato
- Vedere Configurare le identità gestite
Errori di configurazione degli endpoint
Se viene visualizzato Connection refused o 404 Not Found:
- Verificare che i nomi delle risorse e dei progetti corrispondano alla distribuzione effettiva
-
Controllare il formato dell'URL dell'endpoint: deve essere
https://<resource-name>.services.ai.azure.com/api/projects/<project-name> -
Per i sottodomini personalizzati: sostituire
<resource-name>con il sottodominio personalizzato
Discrepanze della versione SDK
Se gli esempi di codice hanno esito negativo con AttributeError o ModuleNotFoundError:
-
Controllare la versione dell'SDK:
pip show azure-ai-projects # Python npm list @azure/ai-projects # JavaScript dotnet list package # .NET - Verificare l'allineamento del moniker: 2.x SDK richiede il portale Foundry, 1.x SDK richiede Foundry classico
- Reinstallare con i flag di versione corretti: consultare i comandi di installazione in ogni sezione della lingua sopra
OpenAI SDK
Utilizza l'SDK di OpenAI quando desideri tutte le funzionalità complete dell'API OpenAI e la massima compatibilità con i client. Questo endpoint fornisce l'accesso ai modelli OpenAI di Azure e ai modelli diretti Foundry (tramite l'API Risposte). Non fornisce l'accesso a funzionalità specifiche di Foundry, ad esempio agenti e valutazioni.
Il frammento di codice seguente illustra come usare direttamente l'endpoint OpenAI /openai/v1 di Azure.
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://<resource-name>.openai.azure.com/openai/v1/",
api_key=token_provider,
)
response = client.responses.create(
model="model_deployment_name",
input= "What is the size of France in square miles?"
)
print(response.model_dump_json(indent=2))
Output previsto:
{
"id": "resp_abc123",
"object": "response",
"created": 1234567890,
"model": "gpt-5.2",
"output_text": "France has an area of approximately 213,011 square miles (551,695 square kilometers)."
}
Per altre informazioni, vedere Linguaggi di programmazione supportati da Azure OpenAI
Importante
Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente disponibili in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliabile per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.
Il frammento di codice seguente illustra come usare direttamente l'endpoint OpenAI /openai/v1 di Azure.
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 java.util.function.Supplier;
DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
String endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
String deploymentName = "gpt-5.2";
Supplier<String> bearerTokenSupplier = AuthenticationUtil.getBearerTokenSupplier(
tokenCredential, "https://cognitiveservices.azure.com/.default");
OpenAIClient openAIClient = OpenAIOkHttpClient.builder()
.baseUrl(endpoint)
.credential(BearerTokenCredential.create(bearerTokenSupplier))
.build();
ResponseCreateParams responseCreateParams = ResponseCreateParams.builder()
.input("What is the speed of light?")
.model(deploymentName)
.build();
Response response = openAIClient.responses().create(responseCreateParams);
System.out.println("Response output: " + response.getOutputText());
Per altre informazioni sull'uso di OpenAI SDK, vedere Linguaggi di programmazione supportati da Azure OpenAI
const endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
const scope = "https://cognitiveservices.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(new DefaultAzureCredential(), scope);
const client = new OpenAI({ baseURL: endpoint, apiKey: azureADTokenProvider });
const response = await client.responses.create({
model: deploymentName,
input: "What is the size of France in square miles?",
});
console.log(`Response output: ${response.output_text}`);
Per altre informazioni sull'uso di OpenAI SDK, vedere Linguaggi di programmazione supportati da Azure OpenAI
- Installare il pacchetto OpenAI: eseguire questo comando per aggiungere la libreria client OpenAI al progetto .NET.
dotnet add package OpenAI ```When it succeeds, the .NET CLI confirms that it installed the `OpenAI` package. This snippet configures `DefaultAzureCredential`, builds `OpenAIClientOptions`, and creates a `ResponseClient` for the Azure OpenAI v1 endpoint. ```csharp using Azure.Identity; using Azure.Core; using OpenAI; using System; using System.ClientModel.Primitives; #pragma warning disable OPENAI001 const string directModelEndpoint = "https://<resource-name>.openai.azure.com/openai/v1/"; const string deploymentName = "gpt-5.2"; BearerTokenPolicy tokenPolicy = new( new DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"); OpenAIResponseClient client = new( model: deploymentName, authenticationPolicy: tokenPolicy, // To use Entra // credential: new ApiKeyCredential("<YOUR-AZURE-OPENAI-API-KEY>") // To use APIKEY options: new OpenAIClientOptions() { Endpoint = new($"{directModelEndpoint}"), }); ResponseCreationOptions options = new ResponseCreationOptions { Temperature = (float)0.7, }; OpenAIResponse modelDirectResponse = client.CreateResponse( [ ResponseItem.CreateUserMessageItem("What is the size of France in square miles?"), ], options); Console.WriteLine($"[ASSISTANT]: {modelDirectResponse.GetOutputText()}"); #pragma warning restore OPENAI001 // The ResponseClient lets you interact with models and services in your project.
Per altre informazioni sull'uso di OpenAI SDK, vedere Linguaggi di programmazione supportati da Azure OpenAI
Uso di Agent Framework per l'orchestrazione locale
Microsoft Agent Framework è un SDK open source per la creazione di sistemi multi-agente nel codice ( ad esempio .NET e Python) con un'interfaccia indipendente dal provider di servizi cloud.
Usare Agent Framework quando si vogliono definire e orchestrare gli agenti in locale. Associarlo a Foundry SDK quando si vuole che tali agenti vengano eseguiti nei modelli Foundry o quando si vuole che Agent Framework orchestra gli agenti ospitati in Foundry.
Per altre informazioni, vedere Panoramica di Microsoft Agent Framework.
SDK degli strumenti della foundry
Foundry Tools (in precedenza Servizi di intelligenza artificiale di Azure) sono soluzioni punto predefinite con SDK dedicati. Utilizzare i seguenti endpoint per lavorare con gli strumenti di Foundry.
Quale endpoint è necessario usare?
Scegliere un endpoint in base alle esigenze:
Usare l'endpoint di Servizi di intelligenza artificiale di Azure per accedere agli strumenti Visione artificiale, Sicurezza del contenuto, Intelligence sui documenti, Lingua, Traduzione e Token Foundry.
Endpoint degli strumenti Foundry: https://<your-resource-name>.cognitiveservices.azure.com/
Annotazioni
Gli endpoint usano il nome della risorsa o un sottodominio personalizzato. Se l'organizzazione configura un sottodominio personalizzato, sostituire your-resource-name con your-custom-subdomain in tutti gli esempi di endpoint.
Per gli strumenti Speech and Translation Foundry, utilizzare gli endpoint nelle tabelle seguenti. Sostituire i segnaposto con le informazioni sulla risorsa.
Endpoint voce
| Strumento di Foundry | Punto finale |
|---|---|
| Trascrizione vocale (standard) | https://<YOUR-RESOURCE-REGION>.stt.speech.microsoft.com |
| Sintesi vocale (neurale) | https://<YOUR-RESOURCE-REGION>.tts.speech.microsoft.com |
| Custom Voice | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Endpoint di traduzione
| Strumento di Foundry | Punto finale |
|---|---|
| Traduzione di testi | https://api.cognitive.microsofttranslator.com/ |
| Traduzione di documenti | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Le sezioni seguenti includono collegamenti di avvio rapido per gli SDK degli strumenti foundry e le informazioni di riferimento.
