Aspire Azure OpenAI integrering (förhandsvisning)

Inkluderar:Värdintegrering ingår Värdintegrering &–& integrering ingår integration

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 AspireAzureOpenAI kan du ansluta till AzureOpenAI Service eller OpenAIAPI från dina .NET program.

Integrering av värdtjänster

Integrationsmodeller för värd AspireAzure OpenAI modellerar AzureOpenAI resurser som AzureOpenAIResource. Om du vill komma åt dessa typer och API:er för att uttrycka dem i ditt AppHost-projekt installerar du 📦Aspire. Hosting.Azure. CognitiveServices NuGet-paket :

dotnet add package Aspire.Hosting.Azure.CognitiveServices

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

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

Lägga till en AzureOpenAI resurs

Om du vill lägga till en AzureOpenAIResource i ditt AppHost-projekt anropar du AddAzureOpenAI metoden:

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 AppHost-projektet. Metoden WithReference skickar anslutningsinformationen till ExampleProject-projektet.

Lägga till en AzureOpenAI distributionsresurs

Om du vill lägga till en AzureOpenAI distributionsresurs anropar du metoden AddDeployment(IResourceBuilder<AzureOpenAIResource>, String, String, String):

var builder = DistributedApplication.CreateBuilder(args);

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

openai.AddDeployment(
    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.

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

Konfigurationsgenererad Bicep

Om du är ny på Bicepär det ett domänspecifikt språk för att definiera Azure-resurser. Med 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

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

output name string = openai.name

Föregående Bicep är en modul som etablerar en Azure Cognitive Services-resurs. Dessutom skapas rolltilldelningar för resursen Azure i en separat modul:

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

param openai_outputs_name string

param principalType string

param principalId string

resource openai 'Microsoft.CognitiveServices/accounts@2024-10-01' existing = {
  name: openai_outputs_name
}

resource openai_CognitiveServicesOpenAIUser 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(openai.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '5e0bd9bd-7b93-4f28-af87-19fc36ad61bd'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '5e0bd9bd-7b93-4f28-af87-19fc36ad61bd')
    principalType: principalType
  }
  scope: openai
}

Den genererade Bicep är en startpunkt och påverkas av ändringar i tillhandahållandeinfrastrukturen i C#. Anpassningar till Bicep-filen skrivs över direkt, så gör ändringar via C#-etablerings-API:erna för att säkerställa att de återspeglas i de genererade filerna.

Anpassa infrastruktur för provisionering

Alla 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:

• Kedjar ett anrop till ConfigureInfrastructure-API:et:
  • Parametern infra är en instans av den AzureResourceInfrastructure typen.
  • De tillgängliga resurserna hämtas genom att anropa GetProvisionableResources()-metoden.
  • Den enda CognitiveServicesAccount resursen hämtas.
  • Egenskapen CognitiveServicesAccount.Sku tilldelas till en ny instans av CognitiveServicesSku med ett E0 namn och CognitiveServicesSkuTier.Enterprise nivå.
  • En tagg läggs till i Cognitive Services-resursen med nyckeln ExampleKey och värdet Example value.

Client integration

Kom igång med 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

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

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

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:

• Azure.AI.OpenAI dokumentation för exempel på hur du använder OpenAIClient.
• Beroendeinjektion i .NET för mer information om beroendeinjektion.
• Snabbstart: Kom igång med GPT-35-Turbo och GPT-4 med AzureOpenAI Service.

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:

• AddChatClient(AspireOpenAIClientBuilder, String): Registrerar en singleton-IChatClient i de tjänster som tillhandahålls av AspireOpenAIClientBuilder.
• AddKeyedChatClient(AspireOpenAIClientBuilder, String, String): Registrerar en singleton med nyckel IChatClient bland de tjänster som tillhandahålls av AspireOpenAIClientBuilder.

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

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

public class ExampleService(IChatClient chatClient)
{
    public async Task<string> GetResponseAsync(string userMessage)
    {
        var response = await chatClient.CompleteAsync(userMessage);
        return response.Message.Text ?? string.Empty;
    }
}

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

Konfigurera klientinställningar för AzureOpenAI

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

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

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

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

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

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,
          "EnableSensitiveTelemetryData": false
        }
      }
    }
  }
}

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

Använda namngiven konfiguration

Integreringen AspireAzureOpenAI stöder namngiven konfiguration, vilket gör att du kan konfigurera flera instanser av samma resurstyp med olika inställningar. Den namngivna konfigurationen använder anslutningsnamnet som en nyckel under huvudkonfigurationsavsnittet.

{
  "Aspire": {
    "Azure": {
      "AI": {
        "OpenAI": {
          "openai1": {
            "Endpoint": "https://account1.openai.azure.com/",
            "DisableTracing": false
          },
          "openai2": {
            "Endpoint": "https://account2.openai.azure.com/",
            "DisableTracing": true
          }
        }
      }
    }
  }
}

I det här exemplet kan anslutningsnamnen openai1 och openai2 användas när du anropar AddAzureOpenAIClient:

builder.AddAzureOpenAIClient("openai1");
builder.AddAzureOpenAIClient("openai2");

Den namngivna konfigurationen har företräde framför konfigurationen på den översta nivån. Om båda anges åsidosätter inställningarna från den namngivna konfigurationen inställningarna på den översta nivån.

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

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 Aspire översikten över 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

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

• Azure
• Azure.Core
• Azure.Identity

Spårning

Integreringen AspireAzureOpenAI genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

• Experimental.Microsoft.Extensions.AI – Används av Microsoft.Extensions.AI för att registrera AI-åtgärder

Konfigurera känsliga data i telemetri

Som standard innehåller telemetri metadata som tokenantal, men inte råa indata och utdata som meddelandeinnehåll. Om du vill inkludera potentiellt känslig information i telemetri anger du konfigurationsalternativet EnableSensitiveTelemetryData :

builder.AddAzureOpenAIClient(
    connectionName: "openai",
    configureSettings: settings =>
    {
        settings.EnableSensitiveTelemetryData = true;
    })
    .AddChatClient("deploymentName");

Eller genom konfiguration:

{
  "Aspire": {
    "Azure": {
      "AI": {
        "OpenAI": {
          "EnableSensitiveTelemetryData": true
        }
      }
    }
  }
}

Du kan också aktivera känslig datainsamling genom att ange miljövariabeln:

OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

Använda underliggande bibliotekstelemetri

Om du behöver komma åt telemetri direkt från det underliggande OpenAI biblioteket kan du lägga till lämpliga aktivitetskällor och mätare manuellt i konfigurationen OpenTelemetry :

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing.AddSource("OpenAI.*"))
    .WithMetrics(metrics => metrics.AddMeter("OpenAI.*"));

Du måste dock aktivera stöd för experimentell telemetri i OpenAI biblioteket genom att ange OPENAI_EXPERIMENTAL_ENABLE_OPEN_TELEMETRY miljövariabeln till true eller anropa AppContext.SetSwitch("OpenAI.Experimental.EnableOpenTelemetry", true) under appstart.

Se även

• Azure OpenAI
• Aspire översikt över integreringar
• översikt över AspireAzure integreringar
• Aspire GitHub Repo