Delen via

.NET Aspire Azure OpenAI-integratie (voorvertoning)

  • Artikel

Omvat: Hostingintegratie en Client-integratie

Azure OpenAI Service biedt toegang tot de krachtige taal van OpenAIen het insluiten van modellen met de beveiliging en bedrijfsbelofte van Azure. Met de integratie van .NET AspireAzureOpenAI kunt u verbinding maken met AzureOpenAI Service of de API van OpenAIvanuit uw .NET-toepassingen.

Hostingintegratie

De .NET.NET AspireAzure OpenAI hosting integratiemodellen met AzureOpenAI resources als AzureOpenAIResource. Installeer het 📦Aspire.Hosting.Azure.CognitiveServices NuGet-pakket om toegang te krijgen tot deze typen en API's en ze te gebruiken binnen uw app-host project.

dotnet add package Aspire.Hosting.Azure.CognitiveServices

Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.

Een AzureOpenAI-resource toevoegen

Als u een AzureOpenAIResource wilt toevoegen aan uw app-hostproject, roept u de methode AddAzureOpenAI aan:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Met de voorgaande code wordt een AzureOpenAI resource met de naam openai toegevoegd aan het app-hostproject. De methode WithReference geeft de verbindingsgegevens door aan het ExampleProject-project.

Belangrijk

Wanneer u AddAzureOpenAIaanroept, wordt impliciet AddAzureProvisioning(IDistributedApplicationBuilder)aangeroepen. Hiermee wordt ondersteuning toegevoegd voor het dynamisch genereren van Azure resources tijdens het opstarten van de app. De app moet het juiste abonnement en de juiste locatie configureren. Zie Lokale inrichting: Configuratievoor meer informatie.

Een AzureOpenAI-implementatieresource toevoegen

Als u een AzureOpenAI implementatieresource wilt toevoegen, roept u de AddDeployment(IResourceBuilder<AzureOpenAIResource>, AzureOpenAIDeployment) methode aan:

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

De voorgaande code:

  • Hiermee wordt een AzureOpenAI resource met de naam openaitoegevoegd.
  • Hiermee voegt u een AzureOpenAI implementatieresource toe met de naam preview met een modelnaam van gpt-4.5-preview. De modelnaam moet overeenkomen met een beschikbaar model in de AzureOpenAI-service.

Gegenereerde implementatie Bicep

Als je nieuw bent met Bicep, is dit een domeinspecifieke taal voor het definiëren van Azure-bronnen. Met .NET.NET Aspirehoeft u bicep niet handmatig te schrijven, in plaats daarvan genereren de inrichtings-API's Bicep voor u. Wanneer u uw app publiceert, richt de gegenereerde Bicep een AzureOpenAI-resource in met standaardinstellingen.

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

De voorgaande Bicep is een module die een Azure Cognitive Services-resource in richt met de volgende standaardwaarden:

  • location: de locatie van de resourcegroep.
  • principalType: Het hoofdtype van de Cognitive Services-resource.
  • principalId: De Hoofd-ID van de Cognitive Services-resource.
  • openai: de Cognitive Services-accountresource.
    • kind: het type resource, ingesteld op OpenAI.
    • properties: de eigenschappen van de resource.
      • customSubDomainName: de naam van het aangepaste subdomein voor de resource, op basis van de unieke tekenreeks van de resourcegroep-id.
      • publicNetworkAccess: Ingesteld op Enabled.
      • disableLocalAuth: Ingesteld op true.
    • sku: de SKU van de resource, ingesteld op S0.
  • openai_CognitiveServicesOpenAIContributor: De eigenaar van de Cognitive Services-resource, op basis van de ingebouwde Azure Cognitive Services OpenAI Contributor-rol. Zie Azure Cognitive Services OpenAI Inzendervoor meer informatie.
  • preview: de implementatieresource, op basis van de naam van de preview.
    • properties: de eigenschappen van de implementatieresource.
      • format: de indeling van de implementatieresource, ingesteld op OpenAI.
      • modelName: de modelnaam van de implementatieresource, ingesteld op gpt-4.5-preview.
      • modelVersion: de modelversie van de implementatieresource, ingesteld op 2025-02-27.
  • connectionString: de verbindingsreeks die het eindpunt van de Cognitive Services-resource bevat.

De gegenereerde Bicep is een uitgangspunt en kan worden aangepast aan uw specifieke vereisten.

Voorzieningsinfrastructuur personaliseren

Alle .NET AspireAzure resources zijn subklassen van het AzureProvisioningResource type. Hierdoor kunt u de gegenereerde Bicep aanpassen door een fluent-API te bieden voor het configureren van de Azure-resources, met behulp van de ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-API:

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

De voorgaande code:

Verbinding maken met een bestaande AzureOpenAI-service

Mogelijk hebt u een bestaande AzureOpenAI-service waarmee u verbinding wilt maken. U kunt een aanroep koppelen om aantekeningen te maken dat uw AzureOpenAIResource een bestaande resource is:

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

Zie Bestaande Azure bronnen gebruikenvoor meer informatie over het behandelen van AzureOpenAI bronnen als bestaande.

U kunt ook een verbindingsreeks aan de app-host toevoegen in plaats van het weergeven van een AzureOpenAI resource. Dit is een zwak getypte benadering die uitsluitend is gebaseerd op een string waarde. Als u een verbinding wilt toevoegen aan een bestaande AzureOpenAI-service, roept u de AddConnectionString methode aan:

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

Notitie

Verbindingsreeksen worden gebruikt om een breed scala aan verbindingsgegevens weer te geven, waaronder databaseverbindingen, berichtbrokers, eindpunt-URI's en andere services. In .NET.NET Aspire nomenclatuur wordt de term "verbindingsreeks" gebruikt om alle soorten verbindingsgegevens weer te geven.

De verbindingsreeks wordt geconfigureerd in de configuratie van de app-host, meestal onder Gebruikersgeheimen, onder de sectie ConnectionStrings:

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

Voor meer informatie, zie Bestaande Azure resources toevoegen met verbindingsreeksen.

Client integratie

Installeer het 📦Aspire.Azure.AI.OpenAI NuGet-pakket in het project dat door de client wordt gebruikt, oftewel het project voor de toepassing die van de AzureOpenAI-client gebruikmaakt, om te beginnen met de .NET AspireAzureOpenAI-clientintegratie.

dotnet add package Aspire.Azure.AI.OpenAI

Een AzureOpenAI-client toevoegen

Gebruik in het Program.cs-bestand van uw clientgebruikte project de methode AddAzureOpenAIClient(IHostApplicationBuilder, String, Action<AzureOpenAISettings>, Action<IAzureClientBuilder<AzureOpenAIClient,AzureOpenAIClientOptions>>) op elke IHostApplicationBuilder om een OpenAIClient te registreren voor afhankelijkheidsinjectie (DI). De AzureOpenAIClient is een subklasse van OpenAIClient, zodat u een van beide typen kunt aanvragen bij DI. Dit zorgt ervoor dat code die niet afhankelijk is van Azure-specifieke functies generiek blijft. Voor de AddAzureOpenAIClient-methode is een verbindingsnaamparameter vereist.

builder.AddAzureOpenAIClient(connectionName: "openai");

Hint

De parameter connectionName moet overeenkomen met de naam die wordt gebruikt bij het toevoegen van de AzureOpenAI resource in het app-hostproject. Zie Een AzureOpenAI-resource toevoegenvoor meer informatie.

Nadat u de OpenAIClienthebt toegevoegd, kunt u het clientexemplaar ophalen met behulp van dependency injection:

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

Zie voor meer informatie:

Azure OpenAI-client toevoegen met geregistreerde IChatClient

Als u geïnteresseerd bent in het gebruik van de IChatClient-interface, koppelt u met de OpenAI-client een van de volgende API's aan de AddAzureOpenAIClient methode:

Bekijk bijvoorbeeld de volgende C#-code waarmee een IChatClient wordt toegevoegd aan de DI-container:

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

Op dezelfde manier kunt u een sleutel IChatClient toevoegen met de volgende C#-code.

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

Zie Kunstmatige intelligentie in .NET (preview)-voor meer informatie over de IChatClient en de bijbehorende bibliotheek.

Clientinstellingen voor AzureOpenAI configureren

De .NET AspireAzureOpenAI-bibliotheek biedt een set instellingen voor het configureren van de AzureOpenAI-client. De methode AddAzureOpenAIClient maakt een optionele configureSettings parameter van het type Action<AzureOpenAISettings>?beschikbaar. Als u instellingen inline wilt configureren, bekijkt u het volgende voorbeeld:

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

Met de voorgaande code wordt de eigenschap AzureOpenAISettings.DisableTracing ingesteld op trueen wordt de eigenschap AzureOpenAISettings.Endpoint ingesteld op het AzureOpenAI-eindpunt.

Opties voor AzureOpenAI clientbouwer configureren

Als u de AzureOpenAIClientOptions voor de client wilt configureren, kunt u de AddAzureOpenAIClient methode gebruiken. Deze methode gebruikt een optionele configureClientBuilder parameter van het type Action<IAzureClientBuilder<OpenAIClient, AzureOpenAIClientOptions>>?. Bekijk het volgende voorbeeld:

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

De clientbouwer is een exemplaar van het IAzureClientBuilder<TClient,TOptions> type, dat een fluent-API biedt voor het configureren van de clientopties. Met de voorgaande code wordt de eigenschap AzureOpenAIClientOptions.UserAgentApplicationId ingesteld op CLIENT_ID. Zie ConfigureOptions(ChatClientBuilder, Action<ChatOptions>)voor meer informatie.

Azure OpenAI client toevoegen vanuit de configuratie

Daarnaast biedt het pakket de AddOpenAIClientFromConfiguration(IHostApplicationBuilder, String) extensiemethode voor het registreren van een OpenAIClient of AzureOpenAIClient exemplaar op basis van de opgegeven verbindingsreeks. Deze methode volgt deze regels:

  • Als het kenmerk Endpoint leeg is of ontbreekt, wordt een OpenAIClient exemplaar geregistreerd met behulp van de opgegeven sleutel, bijvoorbeeld Key={key};.
  • Als het kenmerk IsAzuretrueis, wordt een AzureOpenAIClient geregistreerd; anders wordt een OpenAIClient geregistreerd, bijvoorbeeld Endpoint={azure_endpoint};Key={key};IsAzure=true een AzureOpenAIClientregistreert, terwijl Endpoint=https://localhost:18889;Key={key} een OpenAIClientregistreert.
  • Als het kenmerk Endpoint".azure."bevat, wordt er een AzureOpenAIClient geregistreerd; anders wordt een OpenAIClient geregistreerd, bijvoorbeeld Endpoint=https://{account}.azure.com;Key={key};.

Bekijk het volgende voorbeeld:

builder.AddOpenAIClientFromConfiguration("openai");

Hint

Een geldige verbindingsreeks moet ten minste een Endpoint of een Keybevatten.

Bekijk het volgende voorbeeld van verbindingsreeksen en of ze een OpenAIClient of AzureOpenAIClientregistreren:

Voorbeeld van verbindingsreeks Geregistreerd cliënttype
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

Keyed AzureOpenAI-clients toevoegen

Er kunnen situaties zijn waarin u meerdere OpenAIClient exemplaren met verschillende verbindingsnamen wilt registreren. Als u keyed AzureOpenAI-clients wilt registreren, roept u de methode AddKeyedAzureOpenAIClient aan:

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

Belangrijk

Wanneer u sleutelservices gebruikt, moet u ervoor zorgen dat uw AzureOpenAI resource twee benoemde verbindingen configureert, één voor chat en één voor code.

Vervolgens kunt u de clientexemplaren ophalen met behulp van afhankelijkheidsinjectie. Bijvoorbeeld om de clients op te halen uit een service:

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

Zie Keyed-services in .NETvoor meer informatie.

Sleutel-AzureOpenAI-clients toevoegen vanuit de configuratie

Dezelfde functionaliteit en regels bestaan voor keyed AzureOpenAI clients als voor de niet-gecodeerde clients. U kunt de extensiemethode AddKeyedOpenAIClientFromConfiguration(IHostApplicationBuilder, String) gebruiken om een OpenAIClient of AzureOpenAIClient exemplaar te registreren op basis van de opgegeven verbindingsreeks.

Bekijk het volgende voorbeeld:

builder.AddKeyedOpenAIClientFromConfiguration("openai");

Deze methode volgt dezelfde regels als beschreven in de Toevoegen AzureOpenAI client vanuit configuratie.

Configuratie

De .NET AspireAzureOpenAI-bibliotheek biedt meerdere opties voor het configureren van de AzureOpenAI verbinding op basis van de vereisten en conventies van uw project. Er moet een Endpoint of een ConnectionString worden opgegeven.

Een verbindingsreeks gebruiken

Wanneer u een verbindingsreeks uit de sectie ConnectionStrings configuratie gebruikt, kunt u de naam van de verbindingsreeks opgeven bij het aanroepen van builder.AddAzureOpenAIClient:

builder.AddAzureOpenAIClient("openai");

De verbindingsreeks wordt opgehaald uit de ConnectionStrings configuratiesectie en er zijn twee ondersteunde indelingen:

Accounteindpunt

De aanbevolen methode is om een Endpoint-te gebruiken, die werkt met de eigenschap AzureOpenAISettings.Credential om een verbinding tot stand te brengen. Als er geen referentiegegevens zijn geconfigureerd, wordt de DefaultAzureCredential gebruikt.

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

Zie Gebruik AzureOpenAI zonder sleutelsvoor meer informatie.

Verbindingsreeks

U kunt ook een aangepaste verbindingsreeks gebruiken:

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

Als u verbinding wilt maken met de niet-AzureOpenAI-service, laat u de eigenschap Endpoint achterwege en stelt u alleen de eigenschap Sleutel in om de API-sleutelin te stellen.

Configuratieproviders gebruiken

De .NET AspireAzureOpenAI-integratie ondersteunt Microsoft.Extensions.Configuration. Het laadt AzureOpenAISettings vanuit de configuratie met behulp van de Aspire:Azure:AI:OpenAI sleutel. Voorbeeld appsettings.json waarmee een aantal van de opties wordt geconfigureerd:

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

Zie Aspirevoor het volledige AzureOpenAI client-integratieschema JSON.Azure. AI.OpenAI/ConfigurationSchema.json.

Inline delegates gebruiken

Je kunt de Action<AzureOpenAISettings> configureSettings delegate doorgeven om enkele of alle opties inline in te stellen, bijvoorbeeld om tracering vanuit de code uit te schakelen.

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

U kunt de OpenAIClientOptions ook instellen met behulp van de optionele Action<IAzureClientBuilder<OpenAIClient, OpenAIClientOptions>> configureClientBuilder parameter van de AddAzureOpenAIClient methode. Als u bijvoorbeeld de client-id voor deze client wilt instellen:

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

Waarneembaarheid en telemetrie

.NET .NET Aspire integraties stellen automatisch Logging, Tracing en metrische configuraties in, die soms ook wel aangeduid worden als de pijlers van waarneembaarheid. Zie .NET.NET Aspire overzicht van integratieintegratiesvoor meer informatie over de waarneembaarheid en telemetrie van integraties. Afhankelijk van de back-upservice ondersteunen sommige integraties mogelijk slechts enkele van deze functies. Sommige integraties ondersteunen bijvoorbeeld logboekregistratie en tracering, maar geen metrische gegevens. Telemetriefuncties kunnen ook worden uitgeschakeld met behulp van de technieken die worden weergegeven in de sectie Configuratie.

Loggen

De .NET AspireAzureOpenAI-integratie maakt gebruik van de volgende logboekcategorieën:

  • Azure
  • Azure.Core
  • Azure.Identity

Opsporing

De .NET AspireAzureOpenAI-integratie verzendt traceringsactiviteiten met behulp van OpenTelemetry voor bewerkingen die met de OpenAIClientworden uitgevoerd.

Belangrijk

Tracing is momenteel proefondervindelijk met deze integratie. Als u zich hiervoor wilt aanmelden, stelt u de OPENAI_EXPERIMENTAL_ENABLE_OPEN_TELEMETRY omgevingsvariabele in op true of 1of roept u AppContext.SetSwitch("OpenAI.Experimental.EnableOpenTelemetry", true)) aan tijdens het opstarten van de app.

Zie ook