Dela via

.NET Aspire Azure OpenAI integrering (förhandsvisning)

  • Artikel

omfattar: Hosting-integration och Client integrering

Azure OpenAI Service ger åtkomst till OpenAI:s kraftfulla språk- och inbäddningsmodeller med den säkerhet och det företagslöfte som erbjuds av Azure. Med integreringen .NET AspireAzureOpenAI kan du ansluta till AzureOpenAI Service eller OpenAIAPI från dina .NET program.

Integrering av värdtjänster

.NET .NET Aspire Azure OpenAI som är värd för integrationsmodeller AzureOpenAI resurser som AzureOpenAIResource. Om du vill komma åt dessa typer och API:er för uttryck i din applikationsvärd projekt installerar du 📦Aspire.Hosting.Azure.CognitiveServices NuGet-paketet:

dotnet add package Aspire.Hosting.Azure.CognitiveServices

Mer information finns i dotnet add package eller Hantera paketberoenden i .NET applikationer.

Lägga till en AzureOpenAI resurs

För att lägga till en AzureOpenAIResource i ditt appvärdprojekt, anropa metoden AddAzureOpenAI:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Föregående kod lägger till en AzureOpenAI resurs med namnet openai till appvärdprojektet. Metoden WithReference skickar anslutningsinformationen till ExampleProject-projektet.

Viktigt!

När du anropar AddAzureOpenAIanropas implicit AddAzureProvisioning(IDistributedApplicationBuilder)– vilket ger stöd för att generera Azure resurser dynamiskt under appstarten. Appen måste konfigurera lämplig prenumeration och plats. För mer information, se Lokal etablering: Konfiguration.

Lägga till en AzureOpenAI distributionsresurs

Om du vill lägga till en AzureOpenAI distributionsresurs anropar du metoden 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...

Föregående kod:

  • Lägger till en AzureOpenAI resurs med namnet openai.
  • Lägger till en AzureOpenAI distributionsresurs med namnet preview med modellnamnet gpt-4.5-preview. Modellnamnet måste motsvara en tillgänglig modell i AzureOpenAI-tjänsten.

Genererat tillhandahållande av Bicep

Om du är ny på Bicepär det ett domänspecifikt språk för att definiera Azure-resurser. Med .NET.NET Aspirebehöver du inte skriva Bicep för hand, i stället genererar etablerings-API:erna Bicep åt dig. När du publicerar din app etablerar den genererade Bicep en AzureOpenAI resurs med standardvärden.

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

Föregående Bicep är en modul som etablerar en Azure Cognitive Services-resurs med följande standardvärden:

  • location: Platsen för resursgruppen.
  • principalType: Huvudtypen för Cognitive Services-resursen.
  • principalId: Huvud-ID för Cognitive Services-resursen.
  • openai: Cognitive Services-kontoresursen.
    • kind: Typen av resurs, inställd på OpenAI.
    • properties: Resursens egenskaper.
      • customSubDomainName: Resursens anpassade underdomännamn baserat på den unika strängen i resursgrupps-ID:t.
      • publicNetworkAccess: Ange till Enabled.
      • disableLocalAuth: Ange till true.
    • sku: Resursens SKU, inställd på S0.
  • openai_CognitiveServicesOpenAIContributor: Cognitive Services-resursägare baserat på den inbyggda rollen Azure Cognitive Services OpenAI Contributor. Mer information finns i Azure Cognitive Services OpenAI Medverkare.
  • preview: Distributionsresursen baserat på preview namn.
    • properties: Egenskaperna för distributionsresursen.
      • format: Distributionsresursens format, inställt på OpenAI.
      • modelName: Modellnamnet för distributionsresursen, inställt på gpt-4.5-preview.
      • modelVersion: Modellversionen av distributionsresursen, inställd på 2025-02-27.
  • connectionString: Anslutningssträngen som innehåller slutpunkten för Cognitive Services-resursen.

Den genererade Bicep-mallen är en utgångspunkt och kan anpassas för att möta dina specifika behov.

Anpassa infrastruktur för provisionering

Alla .NET AspireAzure resurser är underklasser av den AzureProvisioningResource typen. Detta möjliggör anpassning av den genererade Bicep genom att tillhandahålla ett fluent API för att konfigurera Azure resurser med hjälp av ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-API:et.

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

Föregående kod:

Ansluta till en befintlig AzureOpenAI-tjänst

Du kan ha en befintlig AzureOpenAI tjänst som du vill ansluta till. Du kan länka ett anrop för att kommentera att din AzureOpenAIResource är en befintlig resurs:

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

Mer information om hur du behandlar AzureOpenAI resurser som befintliga resurser finns i Använd befintliga Azure resurser.

I stället för att representera en AzureOpenAI resurs kan du också lägga till en anslutningssträng till appvärden. Vilket är en svagt typad metod som baseras enbart på ett string värde. Om du vill lägga till en anslutning till en befintlig AzureOpenAI-tjänst anropar du metoden 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...

Anmärkning

Anslutningssträngar används för att representera ett brett spektrum av anslutningsinformation, inklusive databasanslutningar, meddelandeköer, slutpunkts-URI:er och andra tjänster. I .NET.NET Aspire nomenklatur används termen "anslutningssträng" för att representera alla typer av anslutningsinformation.

Anslutningssträngen konfigureras i appvärdens konfiguration, vanligtvis under Användarhemligheter, under avsnittet ConnectionStrings:

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

För mer information, se Lägg till befintliga Azure resurser med anslutningssträngar.

Client integration

Kom igång med .NET AspireAzureOpenAI-klientintegrering genom att installera 📦Aspire.Azure.AI.OpenAI NuGet-paket i det klientanropande projektet, det vill säga projektet för programmet som använder AzureOpenAI-klienten.

dotnet add package Aspire.Azure.AI.OpenAI

Lägga till en AzureOpenAI-klient

I den Program.cs-filen för ditt klientkrävande projekt använder du metoden AddAzureOpenAIClient(IHostApplicationBuilder, String, Action<AzureOpenAISettings>, Action<IAzureClientBuilder<AzureOpenAIClient,AzureOpenAIClientOptions>>) på någon IHostApplicationBuilder för att registrera en OpenAIClient för beroendeinjektion (DI). AzureOpenAIClient är en underklass av OpenAIClient, så att du kan begära någon av typerna från DI. Detta säkerställer att koden inte är beroende av Azure-specifika funktioner förblir generisk. Metoden AddAzureOpenAIClient kräver en parameter för anslutningsnamn.

builder.AddAzureOpenAIClient(connectionName: "openai");

Tips

Parametern connectionName måste matcha namnet som används när du lägger till AzureOpenAI-resurs i appens värdprojekt. För mer information, se Lägg till en AzureOpenAI resurs.

När du har lagt till OpenAIClientkan du hämta klientinstansen med hjälp av beroendeinjektion.

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

Mer information finns i:

Lägg till AzureOpenAI klient med registrerad IChatClient

Om du är intresserad av att använda IChatClient-gränssnittet, med OpenAI-klienten, kedjar du bara någon av följande API:er till metoden AddAzureOpenAIClient:

Tänk till exempel på följande C#-kod som lägger till en IChatClient till DI-containern:

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

På samma sätt kan du lägga till en nyckelad IChatClient med följande C#-kod:

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

Mer information om IChatClient och dess motsvarande bibliotek finns i Artificiell intelligens i .NET (förhandsversion).

Konfigurera klientinställningar för AzureOpenAI

.NET Aspire Azure OpenAI-biblioteket innehåller en uppsättning inställningar för att konfigurera AzureOpenAI-klienten. Metoden AddAzureOpenAIClient exponerar en valfri configureSettings parameter av typen Action<AzureOpenAISettings>?. För att konfigurera inställningar direkt, överväg följande exempel:

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

Föregående kod anger egenskapen AzureOpenAISettings.DisableTracing till trueoch anger egenskapen AzureOpenAISettings.Endpoint till AzureOpenAI slutpunkt.

Konfigurera AzureOpenAI klientbyggarens inställningar

Om du vill konfigurera AzureOpenAIClientOptions för klienten kan du använda metoden AddAzureOpenAIClient. Den här metoden tar en valfri configureClientBuilder parameter av typen Action<IAzureClientBuilder<OpenAIClient, AzureOpenAIClientOptions>>?. Tänk på följande exempel:

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

Klientbyggaren är en instans av den IAzureClientBuilder<TClient,TOptions> typen, som tillhandahåller ett fluent-API för att konfigurera klientalternativen. Koden ovan anger egenskapen AzureOpenAIClientOptions.UserAgentApplicationId till CLIENT_ID. Mer information finns i ConfigureOptions(ChatClientBuilder, Action<ChatOptions>).

Lägga till AzureOpenAI klient från konfigurationen

Dessutom tillhandahåller paketet tilläggsmetoden AddOpenAIClientFromConfiguration(IHostApplicationBuilder, String) för att registrera en instans av antingen OpenAIClient eller AzureOpenAIClient, baserat på den angivna anslutningssträngen. Den här metoden följer dessa regler:

  • Om attributet Endpoint är tomt eller saknas registreras en OpenAIClient-instans med hjälp av den angivna nyckeln, till exempel Key={key};.
  • Om attributet IsAzure är trueregistreras en AzureOpenAIClient. Annars registreras en OpenAIClient, till exempel Endpoint={azure_endpoint};Key={key};IsAzure=true registrerar en AzureOpenAIClient, medan Endpoint=https://localhost:18889;Key={key} registrerar en OpenAIClient.
  • Om attributet Endpoint innehåller ".azure."registreras en AzureOpenAIClient. annars registreras en OpenAIClient, till exempel Endpoint=https://{account}.azure.com;Key={key};.

Tänk på följande exempel:

builder.AddOpenAIClientFromConfiguration("openai");

Tips

En giltig anslutningssträng måste innehålla minst en Endpoint eller en Key.

Överväg följande exempel på anslutningssträngar och om de registrerar en OpenAIClient eller AzureOpenAIClient:

Exempel på anslutningssträng Registrerad klienttyp
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

Lägga till nyckelade AzureOpenAI klienter

Det kan finnas situationer där du vill registrera flera OpenAIClient instanser med olika anslutningsnamn. Om du vill registrera nyckelade AzureOpenAI klienter anropar du metoden AddKeyedAzureOpenAIClient:

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

Viktigt!

När du använder nyckelade tjänster kontrollerar du att din AzureOpenAI resurs konfigurerar två namngivna anslutningar, en för chat och en för code.

Sedan kan du hämta klientinstanserna med hjälp av dependency injection. Om du till exempel vill hämta klienterna från en tjänst:

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

Mer information finns i Nyckelade tjänster i .NET.

Lägga till nyckelade AzureOpenAI klienter från konfigurationen

Samma funktioner och regler finns för nyckelade AzureOpenAI klienter som för icke-nyckelade klienter. Du kan använda AddKeyedOpenAIClientFromConfiguration(IHostApplicationBuilder, String)-tilläggsmetoden för att registrera en OpenAIClient eller AzureOpenAIClient instans baserat på den angivna anslutningssträngen.

Tänk på följande exempel:

builder.AddKeyedOpenAIClientFromConfiguration("openai");

Den här metoden följer samma regler som beskrivs i Lägg till AzureOpenAI-klienten från konfigurationen.

Konfiguration

.NET Aspire Azure OpenAI-biblioteket innehåller flera alternativ för att konfigurera AzureOpenAI-anslutningen baserat på kraven och konventionerna i projektet. Antingen måste en Endpoint eller en ConnectionString anges.

Använda en anslutningssträng

När du använder en anslutningssträng från ConnectionStrings konfigurationsavsnittet kan du ange namnet på anslutningssträngen när du anropar builder.AddAzureOpenAIClient:

builder.AddAzureOpenAIClient("openai");

Anslutningssträngen hämtas från avsnittet ConnectionStrings konfiguration och det finns två format som stöds:

Kontoslutpunkt

Den rekommenderade metoden är att använda en slutpunkt, som fungerar med egenskapen AzureOpenAISettings.Credential för att upprätta en anslutning. Om inga autentiseringsuppgifter har konfigurerats används DefaultAzureCredential.

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

Mer information finns i Använd AzureOpenAI utan nycklar.

Anslutningssträng

Du kan också använda en anpassad anslutningssträng:

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

Om du vill ansluta till tjänsten som inte ärAzureOpenAI släpper du egenskapen Endpoint och anger endast egenskapen Nyckel för att ange API-nyckel.

Använda konfigurationsprovidrar

.NET Aspire Azure OpenAI-integreringen stöder Microsoft.Extensions.Configuration. Den läser in AzureOpenAISettings från konfigurationen med hjälp av Aspire:Azure:AI:OpenAI-nyckeln. Exempel appsettings.json som konfigurerar några av alternativen:

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

Det fullständiga AzureOpenAI klientintegreringsschemat JSON finns i Aspire.Azure. Artificiell intelligens.OpenAI/ConfigurationSchema.json.

Använd inline-delegater

Du kan skicka Action<AzureOpenAISettings> configureSettings-delegat för att konfigurera vissa eller alla alternativ inline, till exempel för att inaktivera spårning från koden:

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

Du kan också konfigurera OpenAIClientOptions med den valfria parametern Action<IAzureClientBuilder<OpenAIClient, OpenAIClientOptions>> configureClientBuilder för metoden AddAzureOpenAIClient. Om du till exempel vill ange klient-ID för den här klienten:

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

Observerbarhet och telemetri

.NET .NET Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i översikten över .NET.NET Aspire integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Configuration.

Skogsavverkning

.NET Aspire Azure OpenAI-integreringen använder följande loggkategorier:

  • Azure
  • Azure.Core
  • Azure.Identity

Spårning

.NET Aspire Azure OpenAI-integreringen genererar spårningsaktiviteter med hjälp av OpenTelemetry för åtgärder som utförs med OpenAIClient.

Viktigt!

Spårning är för närvarande på experimentstadiet med den här integrationen. Om du vill anmäla dig till den anger du antingen OPENAI_EXPERIMENTAL_ENABLE_OPEN_TELEMETRY miljövariabeln till true eller 1, eller anropar AppContext.SetSwitch("OpenAI.Experimental.EnableOpenTelemetry", true)) under appstart.

Se även