.NET Aspire Azure OpenAI Integration (Vorschau)

umfasst: Hostingintegration und Client Integration

Azure OpenAI Service bietet Zugriff auf die leistungsstarken Sprach- und Einbettungsmodelle von OpenAImit dem Sicherheits- und Unternehmensversprechen von Azure. Mit der .NET AspireAzureOpenAI-Integration können Sie über Ihre .NET-Anwendungen eine Verbindung mit AzureOpenAI Service- oder OpenAI-API herstellen.

Hosting-Integration

Die .NET.NET AspireAzure OpenAI Hosting-Integrationsmodelle AzureOpenAI Ressourcen als AzureOpenAIResource. Um auf diese Typen und APIs zuzugreifen und sie in Ihrem App-Host Projekt zu verwenden, installieren Sie das 📦Aspire.Hosting.Azure.CognitiveServices NuGet-Paket:

dotnet add package Aspire.Hosting.Azure.CognitiveServices

<PackageReference Include="Aspire.Hosting.Azure.CognitiveServices"
                  Version="*" />

Weitere Informationen finden Sie in dotnet add package oder Verwalten von Paketabhängigkeiten in .NET Anwendungen.

Hinzufügen einer AzureOpenAI-Ressource

Rufen Sie die AddAzureOpenAI-Methode auf, um Ihrem App-Hostprojekt eine AzureOpenAIResource hinzuzufügen:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Der vorangehende Code fügt dem App-Hostprojekt eine AzureOpenAI Ressource mit dem Namen openai hinzu. Die WithReference Methode übergibt die Verbindungsinformationen an das ExampleProject Projekt.

Hinzufügen einer AzureOpenAI Bereitstellungsressource

Rufen Sie die AddDeployment(IResourceBuilder<AzureOpenAIResource>, AzureOpenAIDeployment)-Methode auf, um eine AzureOpenAI-Bereitstellungsressource hinzuzufügen:

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...

Der vorherige Code:

• Fügt eine AzureOpenAI Ressource namens openaihinzu.
• Fügt eine AzureOpenAI Bereitstellungsressource namens preview mit dem Modellnamen gpt-4.5-previewhinzu. Der Modellname muss einem der verfügbaren Modelle im AzureOpenAI-Dienst entsprechen.

Generierte Bereitstellungs-Bicep-Skripte

Wenn Sie neu bei Bicepsind, handelt es sich um eine domänenspezifische Sprache zum Definieren von Azure Ressourcen. Mit .NET.NET Aspiremüssen Sie Bicep nicht selbst schreiben, sondern die Bereitstellungs-APIs generieren Bicep für Sie. Wenn Sie Ihre App veröffentlichen, stellt das generierte Bicep eine AzureOpenAI Ressource mit Standardeinstellungen bereit.

@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}'

Das vorangehende Bicep ist ein Modul, das eine Azure Cognitive Services-Ressource mit den folgenden Standardwerten darstellt:

• location: Der Speicherort der Ressourcengruppe.
• principalType: Der Haupttyp der Cognitive Services-Ressource.
• principalId: Die Haupt-ID der Cognitive Services-Ressource.
• openai: Die Ressource des Cognitive Services-Kontos.
  • kind: Die Art der Ressource, die auf OpenAIfestgelegt ist.
  • properties: Die Eigenschaften der Ressource.
    • customSubDomainName: Der benutzerdefinierte Unterdomänenname für die Ressource basierend auf der eindeutigen Zeichenfolge der Ressourcengruppen-ID.
    • publicNetworkAccess: Auf Enabledfestgelegt.
    • disableLocalAuth: Auf truefestgelegt.
  • sku: Die SKU der Ressource, auf S0festgelegt.
• openai_CognitiveServicesOpenAIContributor: Der Ressourcenbesitzer der Cognitive Services, basierend auf der integrierten Azure Cognitive Services OpenAI Contributor-Rolle. Weitere Informationen finden Sie unter Azure Cognitive Services OpenAI Contributor.
• preview: Die Bereitstellungsressource basierend auf dem preview Namen.
  • properties: Die Eigenschaften der Bereitstellungsressource.
    • format: Das Format der Bereitstellungsressource, auf OpenAIfestgelegt.
    • modelName: Der Modellname der Bereitstellungsressource, auf gpt-4.5-previewfestgelegt.
    • modelVersion: Die Modellversion der Bereitstellungsressource, auf 2025-02-27festgelegt.
• connectionString: Die Verbindungszeichenfolge, die den Endpunkt der Cognitive Services-Ressource enthält.

Der generierte Bicep ist ein Ausgangspunkt und kann individuell an Ihre spezifischen Anforderungen angepasst werden.

Bereitstellungsinfrastruktur anpassen

Alle .NET AspireAzure Ressourcen sind Unterklassen des AzureProvisioningResource Typs. Dadurch wird die Anpassung der generierten Bicep ermöglicht, indem eine Fluent-API bereitgestellt wird, um die Azure Ressourcen mithilfe der ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-API zu konfigurieren:

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");
    });

Der vorherige Code:

• Verkettet einen Aufruf an die ConfigureInfrastructure-API.
  • Der infra-Parameter ist eine Instanz des typs AzureResourceInfrastructure.
  • Die bereitstellbaren Ressourcen werden durch Aufrufen der GetProvisionableResources()-Methode abgerufen.
  • Die einzige CognitiveServicesAccount-Ressource wird abgerufen.
  • Die CognitiveServicesAccount.Sku-Eigenschaft wird einer neuen Instanz von CognitiveServicesSku mit einem E0-Namen und CognitiveServicesSkuTier.Enterprise-Rang zugewiesen.
  • Ein Tag wird der Cognitive Services-Ressource mit einem Schlüssel von ExampleKey und einem Wert von Example valuehinzugefügt.

Herstellen einer Verbindung mit einem vorhandenen AzureOpenAI-Dienst

Möglicherweise verfügen Sie über einen vorhandenen AzureOpenAI Dienst, mit dem Sie eine Verbindung herstellen möchten. Sie können einen Aufruf verketten, um anzumerken, dass Ihr AzureOpenAIResource eine vorhandene Ressource ist.

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...

Weitere Informationen zum Behandeln von AzureOpenAI Ressourcen als vorhandene Ressourcen finden Sie unter Verwenden vorhandener Azure Ressourcen.

Alternativ können Sie dem Host der App anstelle einer AzureOpenAI-Ressource eine Verbindungszeichenfolge hinzufügen. Dies ist ein schwach typisierter Ansatz, der ausschließlich auf einem string-Wert basiert. Rufen Sie zum Hinzufügen einer Verbindung zu einem vorhandenen AzureOpenAI-Dienst die AddConnectionString-Methode auf:

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...

Die Verbindungszeichenfolge wird in der Konfiguration des App-Hosts konfiguriert, in der Regel unter "Benutzergeheimnisse", unter dem Abschnitt ConnectionStrings:

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

Weitere Informationen finden Sie unter Hinzufügen vorhandener Azure Ressourcen mit Verbindungszeichenfolgen.

ClientIntegration

Um mit der .NET AspireAzureOpenAI Clientintegration zu beginnen, installieren Sie das 📦Aspire.Azure.AI.OpenAI NuGet-Paket im clientverwendenden Projekt, d. h. im Projekt für die Anwendung, die den AzureOpenAI Client verwendet.

dotnet add package Aspire.Azure.AI.OpenAI

<PackageReference Include="Aspire.Azure.AI.OpenAI"
                  Version="*" />

Hinzufügen eines AzureOpenAI-Clients

Verwenden Sie in der Program.cs Datei Ihres clientaufwendigen Projekts die AddAzureOpenAIClient(IHostApplicationBuilder, String, Action<AzureOpenAISettings>, Action<IAzureClientBuilder<AzureOpenAIClient,AzureOpenAIClientOptions>>) Methode für alle IHostApplicationBuilder, um eine OpenAIClient für die Abhängigkeitsinjektion (DI) zu registrieren. Die AzureOpenAIClient ist eine Unterklasse von OpenAIClient, sodass Sie einen der beiden Typen von DI anfordern können. Dadurch wird sichergestellt, dass Code, der nicht von Azure-spezifischen Features abhängig ist, generisch bleibt. Für die AddAzureOpenAIClient-Methode ist ein Verbindungsnameparameter erforderlich.

builder.AddAzureOpenAIClient(connectionName: "openai");

Nach dem Hinzufügen des OpenAIClientkönnen Sie die Clientinstanz mithilfe der Abhängigkeitseinfügung abrufen:

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

Weitere Informationen finden Sie unter:

• Azure.AI.OpenAI-Dokumentation für Beispiele zur Nutzung der OpenAIClient.
• Abhängigkeitsinjektion in .NET Details zur Abhängigkeitsinjektion.
• Schnellstart: Erste Schritte mit GPT-35-Turbo und GPT-4 mit AzureOpenAI Service.

Hinzufügen Sie AzureOpenAI Client mit registriertem IChatClient

Wenn Sie die IChatClient Schnittstelle verwenden möchten, verketten Sie mit dem OpenAI Client einfach eine der folgenden APIs mit der AddAzureOpenAIClient-Methode:

• AddChatClient(AspireOpenAIClientBuilder, String): Registriert einen Singleton IChatClient in den Diensten, die vom AspireOpenAIClientBuilderbereitgestellt werden.
• AddKeyedChatClient(AspireOpenAIClientBuilder, String, String): Registriert einen Keyed Singleton IChatClient in den Diensten, die von den AspireOpenAIClientBuilderbereitgestellt werden.

Betrachten Sie beispielsweise den folgenden C#-Code, der dem DI-Container eine IChatClient hinzufügt:

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

Ebenso können Sie einen Schlüssel IChatClient mit dem folgenden C#-Code hinzufügen:

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

Weitere Informationen zum IChatClient und der entsprechenden Bibliothek finden Sie unter Künstliche Intelligenz in .NET (Vorschau).

Konfigurieren Sie die AzureOpenAI Client-Einstellungen

Die .NET AspireAzureOpenAI-Bibliothek bietet eine Reihe von Einstellungen zum Konfigurieren des AzureOpenAI Clients. Die AddAzureOpenAIClient-Methode macht einen optionalen configureSettings Parameter vom Typ Action<AzureOpenAISettings>?verfügbar. Um Einstellungen inline zu konfigurieren, berücksichtigen Sie das folgende Beispiel:

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);
    });

Der vorangehende Code legt die AzureOpenAISettings.DisableTracing-Eigenschaft auf truefest und legt die eigenschaft AzureOpenAISettings.Endpoint auf den AzureOpenAI Endpunkt fest.

Konfigurieren AzureOpenAI Client-Generator-Optionen

Um die AzureOpenAIClientOptions für den Client zu konfigurieren, können Sie die AddAzureOpenAIClient-Methode verwenden. Diese Methode verwendet einen optionalen configureClientBuilder Parameter vom Typ Action<IAzureClientBuilder<OpenAIClient, AzureOpenAIClientOptions>>?. Betrachten Sie das folgende Beispiel:

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

Der Client-Generator ist eine Instanz des IAzureClientBuilder<TClient,TOptions> Typs, die eine Fluent-API zum Konfigurieren der Clientoptionen bereitstellt. Der vorangehende Code legt die AzureOpenAIClientOptions.UserAgentApplicationId-Eigenschaft auf CLIENT_IDfest. Weitere Informationen finden Sie unter ConfigureOptions(ChatClientBuilder, Action<ChatOptions>).

Hinzufügen des AzureOpenAI Clients aus der Konfiguration

Darüber hinaus stellt das Paket die AddOpenAIClientFromConfiguration(IHostApplicationBuilder, String) Erweiterungsmethode bereit, um eine OpenAIClient- oder AzureOpenAIClient Instanz basierend auf der bereitgestellten Verbindungszeichenfolge zu registrieren. Diese Methode folgt den folgenden Regeln:

• Wenn das attribut Endpoint leer oder fehlt, wird eine OpenAIClient Instanz mithilfe des bereitgestellten Schlüssels registriert, z. B. Key={key};.
• Wenn das attribut IsAzuretrueist, wird ein AzureOpenAIClient registriert; andernfalls wird ein OpenAIClient registriert, z. B. Endpoint={azure_endpoint};Key={key};IsAzure=true eine AzureOpenAIClientregistriert, während Endpoint=https://localhost:18889;Key={key} eine OpenAIClientregistriert.
• Wenn das attribut Endpoint".azure."enthält, wird ein AzureOpenAIClient registriert; andernfalls wird ein OpenAIClient registriert, z. B. Endpoint=https://{account}.azure.com;Key={key};.

Betrachten Sie das folgende Beispiel:

builder.AddOpenAIClientFromConfiguration("openai");

Betrachten Sie die folgenden Beispielverbindungszeichenfolgen und ob sie eine OpenAIClient oder AzureOpenAIClientregistrieren:

Hinzufügen von AzureOpenAI gekennzeichneten Clients

Es kann Situationen geben, in denen Sie mehrere OpenAIClient-Instanzen mit unterschiedlichen Verbindungsnamen registrieren möchten. Rufen Sie die AddKeyedAzureOpenAIClient-Methode auf, um Azure-OpenAI-Clients mit Schlüssel zu registrieren.

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

Anschließend können Sie die Clientinstanzen mithilfe der Abhängigkeitseinfügung abrufen. So rufen Sie beispielsweise die Clients aus einem Dienst ab:

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

Weitere Informationen finden Sie unter Schlüsselservices in .NET.

Hinzufügen von Schlüsseln AzureOpenAI Clients aus der Konfiguration

Für schlüsselierte AzureOpenAI Clients sind die gleichen Funktionen und Regeln vorhanden wie für die Nichtschlüsselclients. Sie können die AddKeyedOpenAIClientFromConfiguration(IHostApplicationBuilder, String) Erweiterungsmethode verwenden, um eine OpenAIClient- oder AzureOpenAIClient Instanz basierend auf der bereitgestellten Verbindungszeichenfolge zu registrieren.

Betrachten Sie das folgende Beispiel:

builder.AddKeyedOpenAIClientFromConfiguration("openai");

Diese Methode folgt denselben Regeln, wie im Hinzufügen AzureOpenAI-Client aus der Konfigurationbeschrieben.

Konfiguration

Die .NET AspireAzureOpenAI-Bibliothek bietet mehrere Optionen zum Konfigurieren der AzureOpenAI Verbindung basierend auf den Anforderungen und Konventionen Ihres Projekts. Es muss entweder ein Endpoint oder ein ConnectionString bereitgestellt werden.

Verwenden Sie eine Verbindungszeichenfolge

Wenn Sie eine Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings verwenden, können Sie beim Aufrufen von builder.AddAzureOpenAIClientden Namen der Verbindungszeichenfolge angeben:

builder.AddAzureOpenAIClient("openai");

Die Verbindungszeichenfolge wird aus dem Konfigurationsabschnitt ConnectionStrings abgerufen, und es gibt zwei unterstützte Formate:

Kontoendpunkt

Der empfohlene Ansatz besteht darin, einen Endpointzu verwenden, der mit der AzureOpenAISettings.Credential-Eigenschaft funktioniert, um eine Verbindung herzustellen. Wenn keine Anmeldeinformationen konfiguriert sind, wird das DefaultAzureCredential verwendet.

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

Weitere Informationen finden Sie unter Verwendung von AzureOpenAI ohne Tasten.

Verbindungskette

Alternativ kann eine benutzerdefinierte Verbindungszeichenfolge verwendet werden:

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

Um eine Verbindung mit dem Nicht-Azure-OpenAI-Dienst herzustellen, lassen Sie die Eigenschaft Endpoint weg und setzen Sie nur die Schlüssel-Eigenschaft, um den -API-Schlüsselfestzulegen.

Verwenden von Konfigurationsanbietern

Die .NET AspireAzureOpenAI Integration unterstützt Microsoft.Extensions.Configuration. Es lädt die AzureOpenAISettings aus der Konfiguration mithilfe des Aspire:Azure:AI:OpenAI-Schlüssels. Beispiel appsettings.json, das einige der Optionen konfiguriert:

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

Die vollständige Schema der Kundenintegration AzureOpenAIJSON finden Sie unter Aspire.Azure. Künstliche Intelligenz.OpenAI/ConfigurationSchema.json.

Verwenden Sie Inline-Delegaten

Sie können den Action<AzureOpenAISettings> configureSettings Delegat übergeben, um einige oder alle Optionen inline einzurichten, z. B. zum Deaktivieren der Ablaufverfolgung aus Code:

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

Sie können die OpenAIClientOptions auch mithilfe des optionalen Action<IAzureClientBuilder<OpenAIClient, OpenAIClientOptions>> configureClientBuilder Parameters der AddAzureOpenAIClient-Methode einrichten. So legen Sie beispielsweise die Client-ID für diesen Client fest:

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

Observability und Telemetrie

.NET .NET Aspire Integrationen richten automatisch Protokollierungs-, Tracing- und Metrikkonfigurationen ein, die manchmal als die Säulen der Beobachtbarkeitbezeichnet werden. Weitere Informationen zur Integrationsüberwachung und Telemetrie finden Sie unter Übersicht über .NET.NET Aspire Integrationen. Abhängig vom unterstützenden Dienst unterstützen manche Integrationen möglicherweise nur bestimmte dieser Funktionen. Beispielsweise unterstützen einige Integrationen Protokollierung und Ablaufverfolgung, aber keine Metriken. Telemetriefunktionen können auch mithilfe der Techniken deaktiviert werden, die im Abschnitt Configuration dargestellt werden.

Protokollierung

Die .NET AspireAzureOpenAI Integration verwendet die folgenden Protokollkategorien:

• Azure
• Azure.Core
• Azure.Identity

Nachverfolgung

Die .NET AspireAzureOpenAI Integration sendet Protokollierungsaktivitäten unter Verwendung von OpenTelemetry für Vorgänge, die mit dem OpenAIClientausgeführt werden.

Siehe auch

• Azure OpenAI
• Überblick über Integrationen .NET.NET Aspire
• Überblick über Integrationen .NET AspireAzure
• .NET Aspire GitHub Repo