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.
Attualmente visualizzando:
Portale Foundry (versione classica) - Passare alla versione del nuovo portale Foundry
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
Nota
Questo articolo si applica a un progetto Foundry. Il codice illustrato di seguito non funziona per un progetto basato su hub. Per altre informazioni, vedere Tipi di progetti.
Nota
Versioni dell'SDK: Questo articolo illustra l'installazione dell'SDK 1.x. Assicurarsi che gli esempi seguiti corrispondano al pacchetto installato. Passare alla nuova documentazione del portale Foundry per visualizzare l'articolo per la versione 2.x.
| 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.
Esegui il comando per installare i pacchetti 1.x per i progetti classici Foundry.
pip install openai azure-identity azure-ai-projects==1.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-beta.1 (anteprima) | Fonderia (nuovo) | Anteprima | Azure.AI.ProjectsAzure.AI.Projects.OpenAI |
| 1.1.0 (GA) | Foundry classic | Stabile | Azure.AI.Projects |
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.
Importante
Il pacchetto Java azure-ai-projects non ha una versione GA 1.x. Gli esempi di codice nelle sezioni Java usano direttamente il pacchetto azure-ai-inference, che è deprecato e verrà ritirato il 30 maggio 2026.
Per Projects SDK 2.x passare alla nuova documentazione del portale Foundry.
Aggiungi queste dipendenze a Maven pom.xml per i progetti Foundry classic.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-ai-inference</artifactId>
<version>1.0.0-beta.6</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
<version>1.18.2</version>
</dependency>
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 1.x per i progetti classici Foundry.
npm install @azure/ai-projects@1.0.1 @azure/identity
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 1.x Azure AI SDK per i progetti classici Foundry.
# Add 1.x Azure AI SDK packages
dotnet add package Azure.Identity
dotnet add package Azure.AI.Projects --version 1.1.0
dotnet add package Azure.AI.Agents.Persistent --version 1.1.0
dotnet add package Azure.AI.Inference
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.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
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:
models = project_client.get_openai_client(api_version="2024-10-21")
chat_responses = models.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "You are a helpful assistant"},
{"role": "user", "content": "What is the size of France in square miles?"},
],
)
print(chat_responses.choices[0].message.content)
Creare un client di progetto:
package com.azure.ai.foundry.samples;
import com.azure.ai.inference.ChatCompletionsClient;
import com.azure.ai.inference.ChatCompletionsClientBuilder;
import com.azure.ai.inference.models.ChatCompletions;
import com.azure.core.credential.AzureKeyCredential;
import com.azure.core.credential.TokenCredential;
import com.azure.core.exception.HttpResponseException;
import com.azure.core.util.logging.ClientLogger;
import com.azure.identity.DefaultAzureCredentialBuilder;
String prompt = "What best practices should I follow when asking an AI model to review Java code?";
String endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
TokenCredential credential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
.credential(credential)
.endpoint(endpoint)
.buildClient();
```**Create and use an OpenAI-compatible client from your project:**
```java
ChatCompletions completions = client.complete(prompt);
String content = completions.getChoice().getMessage().getContent();
System.out.println("\nResponse from AI assistant:\n" + content);
Creare un client di progetto:
const endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
const deployment = "gpt-4o";
const project = new AIProjectClient(endpoint, new DefaultAzureCredential());
Creare un client compatibile con OpenAI dal progetto:
const client = await project.getAzureOpenAIClient({
// The API version should match the version of the Azure OpenAI resource
apiVersion: "2024-12-01-preview"
});
const chatCompletion = await client.chat.completions.create({
model: deployment,
messages: [
{ role: "system", content: "You are a helpful assistant" },
{ role: "user", content: "What is the speed of light?" },
],
});
console.log(chatCompletion.choices[0].message.content);
Creare un client di progetto:
using System.ClientModel.Primitives;
using Azure.AI.OpenAI;
using Azure.AI.Projects;
using Azure.Identity;
using OpenAI.Chat;
string endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
AIProjectClient projectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());
Creare un client compatibile con OpenAI dal progetto:
ClientConnection connection = projectClient.GetConnection(typeof(AzureOpenAIClient).FullName!);
if (!connection.TryGetLocatorAsUri(out Uri uri) || uri is null)
{
throw new InvalidOperationException("Invalid URI.");
}
uri = new Uri($"https://{uri.Host}");
const string modelDeploymentName = "gpt-4o";
AzureOpenAIClient azureOpenAIClient = new AzureOpenAIClient(uri, new DefaultAzureCredential());
ChatClient chatClient = azureOpenAIClient.GetChatClient(deploymentName: modelDeploymentName);
Console.WriteLine("Complete a chat");
ChatCompletion result = chatClient.CompleteChat("List all the rainbow colors");
Console.WriteLine(result.Content[0].Text);
Operazioni che è possibile eseguire con Foundry SDK
- Access Foundry Models, tra cui Azure OpenAI
- Usare il servizio Foundry Agent
- Eseguire valutazioni cloud
- 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 fornisce l'accesso ai modelli OpenAI Azure e ai modelli diretti Foundry (tramite l'API Completamento chat). 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 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))
Per altre informazioni, vedere Azure Linguaggi di programmazione supportati da OpenAI. 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
Importante
Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente 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 avere funzionalità limitate. Per altre informazioni, vedere Condizioni aggiuntive di utilizzo per le anteprime di Microsoft Azure.
Il frammento di codice seguente illustra come usare direttamente l'endpoint Azure OpenAI /openai/v1.
import com.azure.ai.openai.OpenAIClient;
import com.azure.ai.openai.OpenAIClientBuilder;
import com.azure.ai.openai.models.ChatChoice;
import com.azure.ai.openai.models.ChatCompletions;
import com.azure.ai.openai.models.ChatCompletionsOptions;
import com.azure.ai.openai.models.ChatRequestAssistantMessage;
import com.azure.ai.openai.models.ChatRequestMessage;
import com.azure.ai.openai.models.ChatRequestSystemMessage;
import com.azure.ai.openai.models.ChatRequestUserMessage;
import com.azure.ai.openai.models.ChatResponseMessage;
import com.azure.core.credential.AzureKeyCredential;
import com.azure.core.util.Configuration;
import java.util.ArrayList;
import java.util.List;
String endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
String deploymentName = "gpt-5.2";
TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
OpenAIClient client = new OpenAIClientBuilder()
.credential(defaultCredential)
.endpoint("{endpoint}")
.buildClient();
List<ChatRequestMessage> chatMessages = new ArrayList<>();
chatMessages.add(new ChatRequestSystemMessage("You are a helpful assistant."));
chatMessages.add(new ChatRequestUserMessage("What is the speed of light?"));
ChatCompletions chatCompletions = client.getChatCompletions(deploymentName, new ChatCompletionsOptions(chatMessages));
System.out.printf("Model ID=%s is created at %s.%n", chatCompletions.getId(), chatCompletions.getCreatedAt());
for (ChatChoice choice : chatCompletions.getChoices()) {
ChatResponseMessage message = choice.getMessage();
System.out.printf("Index: %d, Chat Role: %s.%n", choice.getIndex(), message.getRole());
System.out.println("Message:");
System.out.println(message.getContent());
Per altre informazioni sull'uso di OpenAI SDK, vedere Azure Linguaggi di programmazione supportati da OpenAI.
import { AzureOpenAI } from "openai";
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
const deployment = "gpt-4o";
const endpoint = "https://<resource-name>.openai.azure.com";
const scope = "https://ai.azure.com/.default";
const apiVersion = "2024-04-01-preview";
const azureADTokenProvider = getBearerTokenProvider(new DefaultAzureCredential(), scope);
const options = { azureADTokenProvider, deployment, apiVersion, endpoint };
const client = new AzureOpenAI(options);
const result = await client.chat.completions.create({
model: deployment,
messages: [
{ role: "system", content: "You are a helpful assistant" },
{ role: "user", content: "What is the speed of light?" },
],
});
console.log(result.choices[0].message.content);
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 `ChatClient` for the Azure OpenAI v1 endpoint. ```csharp using System.ClientModel.Primitives; using Azure.Identity; using OpenAI; using OpenAI.Chat; #pragma warning disable OPENAI001 const string directModelEndpoint = "https://<resource-name>.openai.azure.com/openai/v1/"; const string modelDeploymentName = "gpt-5.2"; BearerTokenPolicy tokenPolicy = new( new DefaultAzureCredential(), "https://ai.azure.com/.default"); OpenAIClient openAIClient = new( authenticationPolicy: tokenPolicy, options: new OpenAIClientOptions() { Endpoint = new($"{directModelEndpoint}"), }); ChatClient chatClient = openAIClient.GetChatClient(modelDeploymentName); ChatCompletion completion = await chatClient.CompleteChatAsync( [ new SystemChatMessage("You are a helpful assistant."), new UserChatMessage("How many feet are in a mile?") ]); Console.WriteLine(completion.Content[0].Text); #pragma warning restore OPENAI001
Per altre informazioni sull'uso di OpenAI SDK, vedere Azure Linguaggi di programmazione supportati da 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 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 di 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.
(
