Leggere in inglese

Condividi tramite

integrazione di .NET AspireAzureOpenAI (anteprima)

  • Articolo

include integrazione dell'hosting e integrazione di Client

Azure OpenAI Service consente di accedere ai potenti modelli linguistici avanzati e di incorporamento di OpenAIcon la sicurezza e la garanzia aziendale di Azure. L'integrazione .NET AspireAzureOpenAI consente di connettersi all'API di AzureOpenAI o di OpenAIdalle applicazioni .NET.

Integrazione del servizio di hosting

Il .NET.NET AspireAzure OpenAI ospita modelli di integrazione delle risorse AzureOpenAI come AzureOpenAIResource. Per accedere a questi tipi e API e utilizzarli all'interno del progetto host dell'app , installare il pacchetto NuGet 📦Aspire.Hosting.Azure.CognitiveServices.

dotnet add package Aspire.Hosting.Azure.CognitiveServices

Per altre informazioni, vedere dotnet add package o Gestire le dipendenze dei pacchetti nelle applicazioni .NET.

Aggiungere una risorsa AzureOpenAI

Per aggiungere un AzureOpenAIResource al progetto host dell'app, chiamare il metodo AddAzureOpenAI:

var builder = DistributedApplication.CreateBuilder(args);

var openai = builder.AddAzureOpenAI("openai");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(openai);

// After adding all resources, run the app...

Il codice precedente aggiunge una risorsa AzureOpenAI denominata openai al progetto host dell'app. Il metodo WithReference passa le informazioni di connessione al progetto ExampleProject.

Importante

Quando chiami AddAzureOpenAI, chiama implicitamente AddAzureProvisioning(IDistributedApplicationBuilder), che aggiunge il supporto per la generazione dinamica delle risorse Azure durante l'avvio dell'app. L'app deve configurare l'abbonamento e la località appropriate. Per ulteriori informazioni, consultare Fornitura locale: Configurazione.

Aggiungere una risorsa di distribuzione AzureOpenAI

Per aggiungere una risorsa di distribuzione AzureOpenAI, chiamare il metodo AddDeployment(IResourceBuilder<AzureOpenAIResource>, AzureOpenAIDeployment):

var builder = DistributedApplication.CreateBuilder(args);

var openai = builder.AddAzureOpenAI("openai");
openai.AddDeployment(
    new AzureOpenAIDeployment(
        name: "preview",
        modelName: "gpt-4.5-preview",
        modelVersion: "2025-02-27"));

builder.AddProject<Projects.ExampleProject>()
       .WithReference(openai)
       .WaitFor(openai);

// After adding all resources, run the app...

Il codice precedente:

  • Aggiunge una risorsa AzureOpenAI denominata openai.
  • Aggiunge una risorsa di distribuzione AzureOpenAI chiamata preview con il nome del modello gpt-4.5-preview. Il nome del modello deve corrispondere a un modello OpenAI.

Generazione dell'approvvigionamento Bicep

Se sei nuovo a Bicep, si tratta di un linguaggio specifico per definire le risorse Azure. Con .NET.NET Aspire, non è necessario scrivere manualmente Bicep, poiché le API di provisioning generano automaticamente Bicep per te. Quando si pubblica l'applicazione, il Bicep generato provvede al provisioning di una risorsa AzureOpenAI con impostazioni predefinite standard.

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param principalType string

param principalId string

resource openai 'Microsoft.CognitiveServices/accounts@2024-10-01' = {
  name: take('openai-${uniqueString(resourceGroup().id)}', 64)
  location: location
  kind: 'OpenAI'
  properties: {
    customSubDomainName: toLower(take(concat('openai', uniqueString(resourceGroup().id)), 24))
    publicNetworkAccess: 'Enabled'
    disableLocalAuth: true
  }
  sku: {
    name: 'S0'
  }
  tags: {
    'aspire-resource-name': 'openai'
  }
}

resource openai_CognitiveServicesOpenAIContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(openai.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'a001fd3d-188f-4b5d-821b-7da978bf7442'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'a001fd3d-188f-4b5d-821b-7da978bf7442')
    principalType: principalType
  }
  scope: openai
}

resource preview 'Microsoft.CognitiveServices/accounts/deployments@2024-10-01' = {
  name: 'preview'
  properties: {
    model: {
      format: 'OpenAI'
      name: 'gpt-4.5-preview'
      version: '2025-02-27'
    }
  }
  sku: {
    name: 'Standard'
    capacity: 8
  }
  parent: openai
}

output connectionString string = 'Endpoint=${openai.properties.endpoint}'

Il Bicep precedente è un modulo che fornisce una risorsa dei Servizi cognitivi Azure con le seguenti impostazioni predefinite:

  • location: posizione del gruppo di risorse.
  • principalType: tipo principale della risorsa Servizi cognitivi.
  • principalId: ID principale della risorsa servizi cognitivi.
  • openai: la risorsa dell'account Servizi Cognitivi.
    • kind: tipo di risorsa, impostato su OpenAI.
    • properties: proprietà della risorsa.
      • customSubDomainName: nome del sottodominio personalizzato per la risorsa, in base alla stringa univoca dell'ID del gruppo di risorse.
      • publicNetworkAccess: impostare su Enabled.
      • disableLocalAuth: impostare su true.
    • sku: SKU della risorsa, impostato su S0.
  • openai_CognitiveServicesOpenAIContributor: Proprietario della risorsa di Servizi cognitivi, basato sul ruolo predefinito Azure Cognitive Services OpenAI Contributor. Per altre informazioni, vedere Azure Servizi cognitivi OpenAI Collaboratore.
  • preview: La risorsa di distribuzione, basata sul nome preview.
    • properties: proprietà della risorsa di distribuzione.
      • format: formato della risorsa di distribuzione, impostato su OpenAI.
      • modelName: nome del modello della risorsa di distribuzione, impostato su gpt-4.5-preview.
      • modelVersion: versione del modello della risorsa di distribuzione, impostata su 2025-02-27.
  • connectionString: stringa di connessione contenente l'endpoint della risorsa servizi cognitivi.

Il Bicep generato è un punto di partenza e viene influenzato dalle modifiche apportate all'infrastruttura di provisioning in C#. Le personalizzazioni del file Bicep verranno direttamente sovrascritte, quindi è necessario apportare modifiche tramite le API di provisioning C# per garantire che siano riflesse nei file generati.

Personalizzare l'infrastruttura di provisioning

Tutte le risorse .NET AspireAzure sono sottoclassi del tipo di AzureProvisioningResource. Ciò consente la personalizzazione del Bicep generato fornendo un'API fluente per configurare le risorse Azure, usando l'API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>).

builder.AddAzureOpenAI("openai")
    .ConfigureInfrastructure(infra =>
    {
        var resources = infra.GetProvisionableResources();
        var account = resources.OfType<CognitiveServicesAccount>().Single();

        account.Sku = new CognitiveServicesSku
        {
            Tier = CognitiveServicesSkuTier.Enterprise,
            Name = "E0"
        };
        account.Tags.Add("ExampleKey", "Example value");
    });

Il codice precedente:

Collegarsi a un servizio esistente AzureOpenAI

Potrebbe essere disponibile un servizio di AzureOpenAI esistente a cui connettersi. È possibile concatenare una chiamata per annotare che il AzureOpenAIResource è una risorsa esistente:

var builder = DistributedApplication.CreateBuilder(args);

var existingOpenAIName = builder.AddParameter("existingOpenAIName");
var existingOpenAIResourceGroup = builder.AddParameter("existingOpenAIResourceGroup");

var openai = builder.AddAzureOpenAI("openai")
                    .AsExisting(existingOpenAIName, existingOpenAIResourceGroup);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(openai);

// After adding all resources, run the app...

Per altre informazioni sulla gestione delle risorse di AzureOpenAI come risorse esistenti, vedere Usare risorse Azure esistenti.

In alternativa, anziché rappresentare una risorsa AzureOpenAI, è possibile aggiungere una stringa di connessione all'host dell'app. Si tratta di un approccio di tipo debole basato esclusivamente su un valore string. Per aggiungere una connessione a un servizio di AzureOpenAI esistente, chiamare il metodo AddConnectionString:

var builder = DistributedApplication.CreateBuilder(args);

var openai = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureOpenAI("openai")
    : builder.AddConnectionString("openai");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(openai);

// After adding all resources, run the app...

Nota

Le stringhe di connessione vengono usate per rappresentare un'ampia gamma di informazioni di connessione, tra cui connessioni di database, broker di messaggi, URI degli endpoint e altri servizi. Nella nomenclatura .NET.NET Aspire, il termine "stringa di connessione" è utilizzato per rappresentare qualsiasi tipo di informazioni di connessione.

La stringa di connessione è configurata nella configurazione dell'host dell'app, in genere in Segreti utente, nella sezione ConnectionStrings:

{
  "ConnectionStrings": {
    "openai": "https://{account_name}.openai.azure.com/"
  }
}

Per ulteriori dettagli, consulta Aggiungi le risorse esistenti di Azure con le stringhe di connessione.

Client integrazione

Per iniziare a usare l'integrazione client .NET AspireAzureOpenAI, installare il pacchetto NuGet 📦Aspire.Azure.AI.OpenAI nel progetto consumer, ovvero il progetto per l'applicazione che utilizza il client AzureOpenAI.

dotnet add package Aspire.Azure.AI.OpenAI

Aggiungere un client AzureOpenAI

Nel file Program.cs del progetto che utilizza il client, utilizzare il metodo AddAzureOpenAIClient(IHostApplicationBuilder, String, Action<AzureOpenAISettings>, Action<IAzureClientBuilder<AzureOpenAIClient,AzureOpenAIClientOptions>>) su qualsiasi IHostApplicationBuilder per registrare un OpenAIClient per l'inserimento delle dipendenze (DI). Il AzureOpenAIClient è una sottoclasse di OpenAIClient, che consente di richiedere l'uno o l'altro tipo da DI. In questo modo, il codice che non dipende dalle funzionalità specifiche di Azurerimane generico. Il metodo AddAzureOpenAIClient richiede un parametro del nome di connessione.

builder.AddAzureOpenAIClient(connectionName: "openai");

Suggerimento

Il parametro connectionName deve corrispondere al nome usato quando si aggiunge la risorsa AzureOpenAI nel progetto host dell'app. Per altre informazioni, vedere Aggiungere una risorsa AzureOpenAI.

Dopo aver aggiunto il OpenAIClient, è possibile recuperare l'istanza client tramite Dependency Injection:

public class ExampleService(OpenAIClient client)
{
    // Use client...
}

Per altre informazioni, vedere:

Aggiungere AzureOpenAI client con IChatClient registrati

Se si è interessati a usare l'interfaccia IChatClient, con il client OpenAI, è sufficiente concatenare una delle API seguenti al metodo AddAzureOpenAIClient:

Si consideri ad esempio il codice C# seguente che aggiunge un IChatClient al contenitore delle dipendenze:

builder.AddAzureOpenAIClient(connectionName: "openai")
       .AddChatClient("deploymentName");

Analogamente, è possibile aggiungere un IChatClient con chiave con il codice C# seguente:

builder.AddAzureOpenAIClient(connectionName: "openai")
       .AddKeyedChatClient("serviceKey", "deploymentName");

Per altre informazioni sul IChatClient e sulla relativa libreria corrispondente, vedere Intelligenza artificiale in .NET (anteprima).

Configurare le impostazioni client di AzureOpenAI

La libreria .NET AspireAzureOpenAI fornisce un set di impostazioni per configurare il client AzureOpenAI. Il metodo AddAzureOpenAIClient espone un parametro facoltativo configureSettings di tipo Action<AzureOpenAISettings>?. Per configurare le impostazioni inline, considerare l'esempio seguente:

builder.AddAzureOpenAIClient(
    connectionName: "openai",
    configureSettings: settings =>
    {
        settings.DisableTracing = true;

        var uriString = builder.Configuration["AZURE_OPENAI_ENDPOINT"]
            ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");

        settings.Endpoint = new Uri(uriString);
    });

Il codice precedente imposta la proprietà AzureOpenAISettings.DisableTracing su truee imposta la proprietà AzureOpenAISettings.Endpoint sull'endpoint AzureOpenAI.

Configurare le opzioni del costruttore client AzureOpenAI

Per configurare il AzureOpenAIClientOptions per il client, è possibile usare il metodo AddAzureOpenAIClient. Questo metodo accetta un parametro configureClientBuilder facoltativo di tipo Action<IAzureClientBuilder<OpenAIClient, AzureOpenAIClientOptions>>?. Si consideri l'esempio seguente:

builder.AddAzureOpenAIClient(
    connectionName: "openai",
    configureClientBuilder: clientBuilder =>
    {
        clientBuilder.ConfigureOptions(options =>
        {
            options.UserAgentApplicationId = "CLIENT_ID";
        });
    });

Il generatore di client è un'istanza del tipo di IAzureClientBuilder<TClient,TOptions>, che fornisce un'API Fluent per configurare le opzioni client. Il codice precedente imposta la proprietà AzureOpenAIClientOptions.UserAgentApplicationId su CLIENT_ID. Per altre informazioni, vedere ConfigureOptions(ChatClientBuilder, Action<ChatOptions>).

Aggiungere AzureOpenAI client dalla configurazione

Inoltre, il pacchetto fornisce il metodo di estensione AddOpenAIClientFromConfiguration(IHostApplicationBuilder, String) per registrare un'istanza di OpenAIClient o AzureOpenAIClient in base alla stringa di connessione specificata. Questo metodo segue queste regole:

  • Se l'attributo Endpoint è vuoto o mancante, un'istanza di OpenAIClient viene registrata usando la chiave fornita, ad esempio Key={key};.
  • Se l'attributo IsAzure è true, viene registrato un AzureOpenAIClient; in caso contrario, viene registrato un OpenAIClient, ad esempio, Endpoint={azure_endpoint};Key={key};IsAzure=true registra un AzureOpenAIClient, mentre Endpoint=https://localhost:18889;Key={key} registra un OpenAIClient.
  • Se l'attributo Endpoint contiene ".azure.", viene registrato un AzureOpenAIClient; in caso contrario, viene registrato un OpenAIClient, ad esempio Endpoint=https://{account}.azure.com;Key={key};.

Si consideri l'esempio seguente:

builder.AddOpenAIClientFromConfiguration("openai");

Suggerimento

Una stringa di connessione valida deve contenere almeno un Endpoint o un Key.

Si considerino le stringhe di connessione di esempio seguenti e se registrano un OpenAIClient o AzureOpenAIClient:

Stringa di connessione di esempio Tipo di client registrato
Endpoint=https://{account_name}.openai.azure.com/;Key={account_key} AzureOpenAIClient
Endpoint=https://{account_name}.openai.azure.com/;Key={account_key};IsAzure=false OpenAIClient
Endpoint=https://{account_name}.openai.azure.com/;Key={account_key};IsAzure=true AzureOpenAIClient
Endpoint=https://localhost:18889;Key={account_key} OpenAIClient

Aggiungere clienti con chiave AzureOpenAI

In alcuni casi potrebbe essere necessario registrare più istanze di OpenAIClient con nomi di connessione diversi. Per registrare i client AzureOpenAI con chiave, chiamare il metodo AddKeyedAzureOpenAIClient:

builder.AddKeyedAzureOpenAIClient(name: "chat");
builder.AddKeyedAzureOpenAIClient(name: "code");

Importante

Quando si usano i servizi con chiave, assicurarsi che la risorsa AzureOpenAI configuri due connessioni denominate, una per chat e una per code.

È quindi possibile recuperare le istanze client usando l'iniezione delle dipendenze. Ad esempio, per recuperare i client da un servizio:

public class ExampleService(
    [KeyedService("chat")] OpenAIClient chatClient,
    [KeyedService("code")] OpenAIClient codeClient)
{
    // Use clients...
}

Per altre informazioni, vedere Servizi con chiave in .NET.

Aggiungi client AzureOpenAI con chiave dalla configurazione

Esistono le stesse funzionalità e regole per i client con chiave AzureOpenAI per i client non con chiave. È possibile usare il metodo di estensione AddKeyedOpenAIClientFromConfiguration(IHostApplicationBuilder, String) per registrare un'istanza di OpenAIClient o AzureOpenAIClient in base alla stringa di connessione specificata.

Si consideri l'esempio seguente:

builder.AddKeyedOpenAIClientFromConfiguration("openai");

Questo metodo segue le stesse regole descritte nel Aggiungere AzureOpenAI client dalla configurazione.

Configurazione

La libreria .NET AspireAzureOpenAI offre più opzioni per configurare la connessione AzureOpenAI in base ai requisiti e alle convenzioni del progetto. È necessario fornire un Endpoint o un ConnectionString.

Usare una stringa di connessione

Quando si usa una stringa di connessione dalla sezione di configurazione ConnectionStrings, è possibile specificare il nome della stringa di connessione quando si chiama builder.AddAzureOpenAIClient:

builder.AddAzureOpenAIClient("openai");

La stringa di connessione viene recuperata dalla sezione di configurazione ConnectionStrings e sono supportati due formati:

Endpoint dell'account

L'approccio consigliato consiste nell'usare un Endpoint, che funziona con la proprietà AzureOpenAISettings.Credential per stabilire una connessione. Se non è configurata alcuna credenziale, viene usato il DefaultAzureCredential.

{
  "ConnectionStrings": {
    "openai": "https://{account_name}.openai.azure.com/"
  }
}

Per altre informazioni, vedere Usare AzureOpenAI senza chiavi.

Stringa di connessione

In alternativa, è possibile usare una stringa di connessione personalizzata:

{
  "ConnectionStrings": {
    "openai": "Endpoint=https://{account_name}.openai.azure.com/;Key={account_key};"
  }
}

Per connettersi al servizio nonAzureOpenAI, eliminare la proprietà Endpoint e impostare solo la proprietà Key per impostare la chiave API .

Usare i fornitori di configurazione

L'integrazione .NET AspireAzureOpenAI supporta Microsoft.Extensions.Configuration. Carica il AzureOpenAISettings dalla configurazione usando la chiave Aspire:Azure:AI:OpenAI. Esempio appsettings.json che configura alcune delle opzioni:

{
  "Aspire": {
    "Azure": {
      "AI": {
        "OpenAI": {
          "DisableTracing": false
        }
      }
    }
  }
}

Per lo schema completo AzureOpenAIJSON di integrazione client, vedere Aspire.Azure. Intelligenza artificiale.OpenAI/ConfigurationSchema.json.

Usare delegati in linea

È possibile passare il delegato Action<AzureOpenAISettings> configureSettings per configurare alcune o tutte le opzioni direttamente, ad esempio per disabilitare il tracciamento dal codice:

builder.AddAzureOpenAIClient(
    "openai",
    static settings => settings.DisableTracing = true);

È anche possibile configurare OpenAIClientOptions usando il parametro facoltativo Action<IAzureClientBuilder<OpenAIClient, OpenAIClientOptions>> configureClientBuilder del metodo AddAzureOpenAIClient. Ad esempio, per impostare l'ID client per questo client:

builder.AddAzureOpenAIClient(
    "openai",
    configureClientBuilder: builder => builder.ConfigureOptions(
        options => options.Diagnostics.ApplicationId = "CLIENT_ID"));

Osservabilità e telemetria

.NET .NET Aspire le integrazioni impostano automaticamente le configurazioni di logging, tracciamento e metriche, talvolta chiamate i pilastri dell'osservabilità. Per altre informazioni sull'osservabilità e la telemetria dell'integrazione, vedere panoramica delle integrazioni .NET.NET Aspire. A seconda del servizio di backup, alcune integrazioni possono supportare solo alcune di queste funzionalità. Ad esempio, alcune integrazioni supportano la registrazione e la traccia, ma non le metriche. Le funzionalità di telemetria possono essere disabilitate anche usando le tecniche presentate nella sezione Configurazione .

Registrazione

L'integrazione .NET AspireAzureOpenAI usa le categorie di log seguenti:

  • Azure
  • Azure.Core
  • Azure.Identity

Tracciamento

L'integrazione .NET AspireAzureOpenAI genera attività di traccia usando OpenTelemetry per le operazioni eseguite con il OpenAIClient.

Importante

Il monitoraggio è attualmente sperimentale con questa integrazione. Per acconsentire esplicitamente, impostare la variabile di ambiente OPENAI_EXPERIMENTAL_ENABLE_OPEN_TELEMETRY su true o 1o chiamare AppContext.SetSwitch("OpenAI.Experimental.EnableOpenTelemetry", true)) durante l'avvio dell'app.

Vedere anche