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 | A cosa serve | Endpoint |
|---|---|---|
| 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, inclusi gli incorporamenti. Modelli diretti di Foundry disponibili tramite Chat Completions API (non risposte). | https://<resource-name>.openai.azure.com/openai/v1 |
| SDK degli strumenti di fonderia | Soluzioni predefinite (Visione, Riconoscimento vocale, Sicurezza del contenuto e altro ancora). | Endpoint specifici degli strumenti (varia in base al servizio). |
| Framework agente | 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 massima compatibilità OpenAI, durante la generazione di incorporamenti o l'uso di modelli diretti Foundry tramite Chat Completions.
- 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)
Nota
Tipi di risorsa: Una risorsa Foundry fornisce tutti gli endpoint elencati in precedenza. Una risorsa OpenAI Azure fornisce solo l'endpoint /openai/v1.
Authentication: Esempi usano Microsoft Entra ID (DefaultAzureCredential). Le chiavi API funzionano in /openai/v1. Passa 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 un abbonamento di prova gratuito.
Disporre di uno dei seguenti ruoli di Controllo degli Accessi in Base al Ruolo di Azure per creare e gestire le risorse Foundry:
- Azure Utente di intelligenza artificiale (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:
- Azure sottoscrizione è attiva:
az account show - Hai il ruolo RBAC richiesto: verifica nel portale di Azure → risorsa Foundry → Controllo di accesso (IAM)
- Runtime del linguaggio installato:
- Python:
python --version(≥3.8)
- Python:
- Runtime del linguaggio installato:
- Node.js:
node --version(≥18)
- Node.js:
- Runtime del linguaggio installato:
- .NET:
dotnet --version(≥6.0)
- .NET:
- Runtime del linguaggio installato:
- Java:
java --version(≥11)
- Java:
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>
Nota
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.
Installare l'SDK
| Versione dell'SDK | Versione del portale | Stato | Pacchetto Python |
|---|---|---|---|
| 2.x | Fonderia (nuovo) | Stabile | azure-ai-projects>=2.0.0 |
| 1.x | Foundry (classico) | Stabile | azure-ai-projects==1.0.0 |
La libreria client Azure ai projects per Python è 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 per i progetti Foundry.
pip install "azure-ai-projects>=2.0.0"
| Versione dell'SDK | Versione del portale | Stato | pacchetto Java |
|---|---|---|---|
| 2.0.0 | Fonderia (nuovo) | Stabile | azure-ai-projectsazure-ai-agents |
| Versione dell'SDK | Versione del portale | Stato | Pacchetto JavaScript |
|---|---|---|---|
| 2.0.1 | Fonderia (nuovo) | Stabile | @azure/ai-projects |
| 1.0.1 | Foundry classic | Stabile | @azure/ai-projects |
| Versione dell'SDK | Versione del portale | Stato | pacchetto .NET |
|---|---|---|---|
| 2.0.0 (GA) | Fonderia (nuovo) | Stabile | Azure.AI.ProjectsAzure.AI.Projects.AgentsAzure.AI.Extensions.OpenAI |
| 1.1.0 (GA) | Foundry classic | Stabile | Azure.AI.Projects |
Importante
Non installare Azure.AI.Projects.OpenAI (anteprima) insieme a Azure.AI.Extensions.OpenAI (GA). Entrambi i pacchetti definiscono gli stessi tipi in spazi dei nomi diversi, causando errori di riferimento ambigui. Usare solo Azure.AI.Extensions.OpenAI per gli scenari dell'agente.
La libreria client Azure ai projects per Java è una libreria unificata che consente di usare più librerie client insieme connettendosi a un singolo endpoint di progetto.
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 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 per i progetti Foundry.
npm install @azure/ai-projects @azure/identity dotenv
La libreria client Azure AI Projects per .NET è una libreria unificata che consente di usare più biblioteche client connettendosi insieme a un singolo endpoint di progetto.
Eseguire questi comandi per aggiungere i pacchetti necessari al progetto di .NET.
dotnet add package Azure.AI.Projects
dotnet add package Azure.AI.Projects.Agents
dotnet add package Azure.AI.Extensions.OpenAI
dotnet add package Azure.Identity
Uso di Foundry SDK
L'SDK espone due tipi di client perché Foundry e OpenAI hanno forme API diverse:
- Project client: usare per le operazioni native di 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 eseguire agenti, valutazioni e chiamare modelli (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;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
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:
var responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForModel("gpt-5.2");
var response = responseClient.CreateResponse("What is the speed of light?");
Console.WriteLine(response.GetOutputText());
Operazioni che è possibile eseguire con Foundry SDK
- Access Foundry Models, tra cui Azure OpenAI
- Usare il servizio Foundry Agent
- Eseguire valutazioni batch
- Abilitare la traccia delle app
- Ottimizzare un modello
- Ottenere endpoint e chiavi per gli strumenti Foundry, l'orchestrazione locale e altro ancora
Risoluzione dei problemi
Errori di autenticazione
Se viene visualizzato DefaultAzureCredential failed to retrieve a token:
Verifica che interfaccia della riga di comando di Azure sia autenticato
az account show az login # if not logged inVerificare l'assegnazione del ruolo RBAC:
- Verificare di avere almeno il ruolo utente di intelligenza artificiale Azure nel progetto Foundry
- Consulta Assign Azure roles
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
Incompatibilità di versione dell'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 # .NETReinstallare con i flag di versione corretti: vedere i comandi di installazione nella sezione della lingua sopra
OpenAI SDK
Usare l'SDK di OpenAI quando si desidera avere tutte le funzionalità dell'API OpenAI e la massima compatibilità per il client. Questo endpoint consente di accedere ai modelli OpenAI di Azure e ai modelli diretti Foundry (tramite l'API Risposte), inclusi incorporazioni, completamento delle chat e generazione di immagini. Non fornisce l'accesso a funzionalità specifiche di Foundry, ad esempio agenti e valutazioni.
Suggerimento
Usare l'endpoint OpenAI SDK per generare incorporamenti. L'endpoint del progetto usato da Foundry SDK attualmente non instrada le richieste di incorporamento.
Il frammento di codice seguente illustra come usare direttamente l'endpoint Azure OpenAI /openai/v1.
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-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 Azure Linguaggi di programmazione supportati da OpenAI
Il frammento di codice seguente illustra come usare direttamente l'endpoint Azure OpenAI /openai/v1.
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://ai.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 Azure Linguaggi di programmazione supportati da OpenAI
const endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
const scope = "https://ai.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 Azure Linguaggi di programmazione supportati da 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 `ResponsesClient` for the Azure OpenAI v1 endpoint. ```csharp using Azure.Identity; using OpenAI; using OpenAI.Responses; 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://ai.azure.com/.default"); OpenAIClient openAIClient = new( authenticationPolicy: tokenPolicy, options: new OpenAIClientOptions() { Endpoint = new($"{directModelEndpoint}"), }); ResponsesClient client = openAIClient.GetResponsesClient(); CreateResponseOptions options = new() { Model = deploymentName, InputItems = { ResponseItem.CreateUserMessageItem("What is the size of France in square miles?") }, Temperature = (float)0.7, }; var modelDirectResponse = client.CreateResponse(options); Console.WriteLine($"[ASSISTANT]: {modelDirectResponse.Value.GetOutputText()}"); #pragma warning restore OPENAI001
Per altre informazioni sull'uso di OpenAI SDK, vedere Azure Linguaggi di programmazione supportati da OpenAI
Generare incorporamenti con OpenAI SDK
Usare lo stesso /openai/v1 endpoint per generare incorporamenti con un modello di incorporamento distribuito.
embedding = client.embeddings.create(
model="text-embedding-3-large",
input="How do I get started with Microsoft Foundry?",
)
print(f"Embedding dimension: {len(embedding.data[0].embedding)}")
const embedding = await client.embeddings.create({
model: "text-embedding-3-large",
input: "How do I get started with Microsoft Foundry?",
});
console.log(`Embedding dimension: ${embedding.data[0].embedding.length}`);
var embeddingClient = openAIClient.GetEmbeddingClient("text-embedding-3-large");
var result = embeddingClient.GenerateEmbedding(
"How do I get started with Microsoft Foundry?");
Console.WriteLine($"Embedding dimension: {result.Value.ToFloats().Length}");
// Use the same OpenAI client created above
// Embeddings are available through the OpenAI SDK embeddings API
Per le procedure di incorporamento completo, vedere Generare incorporamenti.
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 di Foundry
Gli strumenti Foundry (precedentemente Azure AI Services) sono soluzioni pronte all'uso con SDK dedicati. Utilizzare i seguenti endpoint per interagire con gli strumenti Foundry.
Quale endpoint è necessario usare?
Scegliere un endpoint in base alle esigenze:
Usare l'endpoint di servizi di intelligenza artificiale Azure per accedere a Visione artificiale, sicurezza del contenuto, intelligence sui documenti, lingua, traduzione e strumenti di ricerca token.
Endpoint degli strumenti di fonderia: https://<your-resource-name>.cognitiveservices.azure.com/
Nota
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.
Se i carichi di lavoro usano funzionalità di Lingua di Azure AI in fase di ritiro, ad esempio analisi del sentiment, estrazione di frasi chiave, riepilogo, collegamento di entità, CLU o CQA, pianificare la migrazione verso alternative di Microsoft Foundry. Per un nuovo sviluppo, è consigliabile usare Foundry SDK o l'endpoint compatibile con OpenAI, come descritto in precedenza in questo articolo. Consultare Migrate da Language Studio a Microsoft Foundry.
Per gli strumenti Speech and Translation Foundry, usare gli endpoint nelle tabelle seguenti. Sostituire i segnaposto con le informazioni sulla risorsa.
Endpoint voce
| Strumento Fonderia | Endpoint |
|---|---|
| Riconoscimento vocale (standard) | https://<YOUR-RESOURCE-REGION>.stt.speech.microsoft.com |
| Sintesi vocale (Neurale) | https://<YOUR-RESOURCE-REGION>.tts.speech.microsoft.com |
| Voce personalizzata | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Endpoint di traduzione
| Strumento di Fonderia | Endpoint |
|---|---|
| Traduzione di testo | https://api.cognitive.microsofttranslator.com/ |
| Traduzione documenti | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Endpoint linguistici
| Strumento di Fonderia | Endpoint |
|---|---|
| Analisi del testo | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com |
Importante
Il 20 marzo 2027, Azure Language Studio ritirerà ed eseguirà la migrazione a Microsoft Foundry. Tutte le funzionalità e i miglioramenti futuri saranno disponibili in Microsoft Foundry.
Il 31 marzo 2029, le seguenti funzionalità del linguaggio di Azure verranno ritirati (fine del supporto). Prima di tale data, gli utenti devono eseguire la migrazione dei carichi di lavoro esistenti ed eseguire l'onboarding di nuovi progetti in Microsoft modelli Foundry per una migliore comprensione del linguaggio naturale e l'integrazione semplificata delle applicazioni:
- Estrazione frasi chiave
- Analisi del sentiment e estrazione delle opinioni
- Classificazione testo personalizzata
- Comprensione del Linguaggio Conversazionale (CLU)
- Risposta alle domande personalizzata (CQA)
- Flusso di lavoro di orchestrazione
- Riepilogo (estratto e astrazione, per documenti e conversazioni)
- Collegamento di entità
Funzionalità principali con supporto continuo: Rilevamento della Lingua, Rilevamento delle Informazioni Personali, Analisi del testo per la Salute, NER predefinito e NER personalizzato.
Per le opzioni di migrazione, vedere Migrate da Language Studio a Microsoft Foundry.
(
