.NET Aspire Azure OpenAI integráció (előzetes verzió)

Tartalmazza: Üzemeltetési integráció és Client integráció

Azure OpenAI Service hozzáférést biztosít OpenAIhatékony nyelvi és beágyazási modelljeihez, Azurebiztonságának és vállalati ígéretének köszönhetően. A .NET AspireAzureOpenAI integráció lehetővé teszi AzureOpenAI szolgáltatáshoz vagy OpenAIAPI-hoz való csatlakozást .NET-alkalmazásokból.

Üzemeltetési integráció

Az .NET.NET AspireAzure OpenAI integrációs modellek AzureOpenAI erőforrásokat üzemeltetnek, mint AzureOpenAIResource. Ha ezeket a típusokat és API-kat az alkalmazásgazda projektben szeretné használni, telepítse a 📦Aspire.Hosting.Azure.CognitiveServices NuGet-csomagot:

dotnet add package Aspire.Hosting.Azure.CognitiveServices

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

További információért lásd: dotnet add package vagy Csomagfüggőségek kezelése .NET alkalmazásokban.

Azure OpenAI-erőforrás hozzáadása

Ha AzureOpenAIResource szeretne hozzáadni az alkalmazásgazdaprojekthez, hívja meg a AddAzureOpenAI metódust:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Az előző kód hozzáad egy openai nevű AzureOpenAI erőforrást az alkalmazásgazdaprojekthez. A WithReference metódus átadja a kapcsolati adatokat a ExampleProject projektnek.

Azure OpenAI üzembehelyezési erőforrás hozzáadása

Azure OpenAI üzembehelyezési erőforrás hozzáadásához hívja meg a AddDeployment(IResourceBuilder<AzureOpenAIResource>, AzureOpenAIDeployment) metódust:

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

Az előző kód:

• Hozzáad egy openainevű AzureOpenAI erőforrást.
• Hozzáad egy preview nevű AzureOpenAI üzembehelyezési erőforrást gpt-4.5-previewmodellnévvel. A modell nevének meg kell felelnie az AzureOpenAI szolgáltatásban elérhető modell.

Generált erőforrás-előkészítés Bicep

Ha új vagy a Bicep-ben, az egy domain-specifikus nyelv az Azure erőforrások definiálására. A .NET.NET Aspirehasználatával nem kell kézzel megírnia a Bicepet, mert a kiépítési API-k generálják azt ön helyett. Az alkalmazás közzétételekor a létrehozott Bicep kiépít egy AzureOpenAI erőforrást a szokásos alapértelmezett értékekkel.

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

Az előző Bicep egy olyan modul, amely egy Azure Cognitive Services-erőforrást helyez üzembe az alábbi alapértelmezett értékekkel:

• location: Az erőforráscsoport helye.
• principalType: A Cognitive Services-erőforrás fő típusa.
• principalId: A Cognitive Services-erőforrás fő azonosítója.
• openai: A Cognitive Services szolgáltatás fiókhoz tartozó erőforrás.
  • kind: Az erőforrás típusa, amely a OpenAIértékre van állítva.
  • properties: Az erőforrás tulajdonságai.
    • customSubDomainName: Az erőforrás egyéni altartományának neve az erőforráscsoport-azonosító egyedi karaktersorozata alapján.
    • publicNetworkAccess: Beállítva: Enabled.
    • disableLocalAuth: Beállítva: true.
  • sku: Az erőforrás termékváltozata beállítva S0.
• openai_CognitiveServicesOpenAIContributor: A Cognitive Services-erőforrás tulajdonosa a beépített Azure Cognitive Services OpenAI Contributor szerepkör alapján van meghatározva. További információ: Azure Cognitive Services OpenAI Közreműködői.
• preview: A telepítési erőforrás a preview neve alapján.
  • properties: Az üzembehelyezési erőforrás tulajdonságai.
    • format: Az üzembe helyezési erőforrás formátuma beállítva OpenAI.
    • modelName: Az üzembe helyezési erőforrás modellneve gpt-4.5-preview-re van állítva.
    • modelVersion: Az üzembe helyezési erőforrás modellverziója (2025-02-27-re van beállítva).
• connectionString: A Cognitive Services-erőforrás végpontját tartalmazó kapcsolati sztring.

A létrehozott Bicep kiindulási pont, és testre szabható az adott követelményeknek megfelelően.

Az ellátási infrastruktúra testreszabása

Minden .NET AspireAzure erőforrás a AzureProvisioningResource típusú alosztály. Ez lehetővé teszi a létrehozott Bicep testreszabását azáltal, hogy egy folyékony API-t biztosít a Azure erőforrások konfigurálásához – a ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API használatával:

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

Az előző kód:

• A hívást az ConfigureInfrastructure API-hoz láncolja:
  • A infra paraméter a AzureResourceInfrastructure típusú példány.
  • A kiosztható erőforrások a GetProvisionableResources() metódus meghívásával kérhetők le.
  • Az egyetlen CognitiveServicesAccount erőforrást lekérik.
  • A CognitiveServicesAccount.Sku tulajdonság egy új CognitiveServicesSku-példányhoz van hozzárendelve E0 névvel és CognitiveServicesSkuTier.Enterprise réteggel.
  • A Cognitive Services-erőforráshoz egy ExampleKey kulcsú és Example valueértékű címke kerül hozzáadásra.

Csatlakozás meglévő AzureOpenAI szolgáltatáshoz

Előfordulhat, hogy rendelkezik egy meglévő AzureOpenAI szolgáltatással, amelyhez csatlakozni szeretne. A AzureOpenAIResource meglévő erőforrásként való használatát jelző megjegyzéseket fűzhet a híváslánchoz:

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

A AzureOpenAI erőforrások meglévő erőforrásként való kezeléséről további információt a Meglévő Azure erőforrások használatacímű témakörben talál.

Másik lehetőségként ahelyett, hogy egy AzureOpenAI erőforrást jelölné, hozzáadhat egy kapcsolati karakterláncot az alkalmazás gazdagépébe. Ez egy gyengén típusos megközelítés, amely kizárólag egy string értéken alapul. Ha meglévő AzureOpenAI szolgáltatáshoz szeretne kapcsolatot létesíteni, hívja meg a AddConnectionString metódust:

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

A kapcsolati karakterlánc az alkalmazás hosztjának konfigurációjában van beállítva, általában a Felhasználói titkok alatt, a ConnectionStrings szakaszban:

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

További információért lásd a Meglévő Azure erőforrások kapcsolati sztringekkel való hozzáadását.

Client integráció

Az .NET AspireAzureOpenAI ügyfélintegráció első lépéseihez telepítse a 📦Aspire.Azure. AI.OpenAI NuGet-csomagot az ügyfélfogyasztó projektben, vagyis a AzureOpenAI ügyfelet használó alkalmazás projektjében.

dotnet add package Aspire.Azure.AI.OpenAI

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

Egy AzureOpenAI ügyfél hozzáadása

Az ügyfélfogyasztó projekt Program.cs fájljában a IHostApplicationBuilderAddAzureOpenAIClient(IHostApplicationBuilder, String, Action<AzureOpenAISettings>, Action<IAzureClientBuilder<AzureOpenAIClient,AzureOpenAIClientOptions>>) metódusával regisztráljon egy OpenAIClient függőséginjektáláshoz (DI). A AzureOpenAIClient a OpenAIClientalosztálya, amely lehetővé teszi, hogy bármelyik típust lekérje a DI-től. Ez biztosítja, hogy a kód ne függ Azure-specifikus funkcióktól, általános maradjon. A AddAzureOpenAIClient metódushoz kapcsolatnévparaméter szükséges.

builder.AddAzureOpenAIClient(connectionName: "openai");

A OpenAIClienthozzáadása után a függőség injektálásával lekérheti a klienspéldányt.

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

További információk:

• Azure. AI.OpenAI dokumentáció példák a OpenAIClienthasználatára.
• függőséginjektálás .NET a függőséginjektálás részleteiért.
• Rövid útmutató: A GPT-35-Turbo és a GPT-4 használatának első lépései a AzureOpenAI szolgáltatáskeretében.

Adja hozzá a AzureOpenAI ügyfelet regisztrált IChatClient-vel

Ha a IChatClient felületet szeretné használni a OpenAI-ügyféllel, egyszerűen láncossa az alábbi API-k egyikét a AddAzureOpenAIClient metódushoz:

• AddChatClient(AspireOpenAIClientBuilder, String): Regisztrálja a singleton IChatClient-et a AspireOpenAIClientBuilderáltal biztosított szolgáltatások közé.
• AddKeyedChatClient(AspireOpenAIClientBuilder, String, String): Egy kulcsos singleton IChatClient regisztrálva van a AspireOpenAIClientBuilderáltal nyújtott szolgáltatások között.

Vegyük például a következő C# kódot, amely hozzáad egy IChatClient-t a DI-tárolóhoz:

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

Hasonlóképpen hozzáadhat egy IChatClient kulcsot a következő C#-kóddal:

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

További információ a IChatClient és a hozzá tartozó kódtárról: Mesterséges intelligencia .NET (előzetes verzió).

Azure OpenAI ügyfélbeállítások konfigurálása

A .NET AspireAzureOpenAI kódtár számos beállítást biztosít a AzureOpenAI-ügyfél konfigurálásához. A AddAzureOpenAIClient metódus egy választható configureSettings típusú paramétert tesz elérhetővé Action<AzureOpenAISettings>?. A beállítások beágyazott konfigurálásához vegye figyelembe a következő példát:

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

Az előző kód a AzureOpenAISettings.DisableTracing tulajdonságot trueértékre állítja, és a AzureOpenAISettings.Endpoint tulajdonságot a AzureOpenAI végpontra állítja.

Azure OpenAI ügyfélépítő beállításainak konfigurálása

Az ügyfél AzureOpenAIClientOptions konfigurálásához használhatja a AddAzureOpenAIClient metódust. Ez a metódus Action<IAzureClientBuilder<OpenAIClient, AzureOpenAIClientOptions>>?típusú opcionális configureClientBuilder paramétert használ. Vegye figyelembe a következő példát:

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

Az ügyfélszerkesztő a IAzureClientBuilder<TClient,TOptions> típusú példány, amely egy fluent API-t biztosít az ügyfélbeállítások konfigurálásához. Az előző kód a AzureOpenAIClientOptions.UserAgentApplicationId tulajdonságot CLIENT_IDértékre állítja. További információ: ConfigureOptions(ChatClientBuilder, Action<ChatOptions>).

Azure OpenAI-ügyfél hozzáadása konfigurációból

A csomag emellett AddOpenAIClientFromConfiguration(IHostApplicationBuilder, String) bővítménymetódussal is rendelkezik egy OpenAIClient vagy AzureOpenAIClient-példány regisztrálásához a megadott kapcsolati sztring alapján. Ez a módszer a következő szabályokat követi:

• Ha a Endpoint attribútum üres vagy hiányzik, a megadott kulccsal regisztrál egy OpenAIClient-példányt, például Key={key};.
• Ha a IsAzure attribútum true, a rendszer regisztrál egy AzureOpenAIClient; ellenkező esetben egy OpenAIClient regisztrál, például Endpoint={azure_endpoint};Key={key};IsAzure=true regisztrál egy AzureOpenAIClient, míg Endpoint=https://localhost:18889;Key={key} regisztrál egy OpenAIClient.
• Ha a Endpoint attribútum ".azure."tartalmaz, a rendszer regisztrál egy AzureOpenAIClient; ellenkező esetben egy OpenAIClient regisztrálva van, például Endpoint=https://{account}.azure.com;Key={key};.

Vegye figyelembe a következő példát:

builder.AddOpenAIClientFromConfiguration("openai");

Vegye figyelembe a következő példa kapcsolati sztringeket, és hogy regisztrálnak-e OpenAIClient vagy AzureOpenAIClient:

Kulcsos AzureOpenAI-ügyfelek hozzáadása

Előfordulhatnak olyan helyzetek, amikor több OpenAIClient instance-t szeretne regisztrálni különböző kapcsolatnevekkel. A kulcsos AzureOpenAI ügyfelek regisztrálásához hívja meg a AddKeyedAzureOpenAIClient metódust:

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

Ezután függőséginjektálással lekérheti az ügyfélpéldányokat. Például az ügyfelek előhívása egy szolgáltatásból:

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

További részletekért lásd Kulcsos szolgáltatások a .NET.

Kulccsal ellátott AzureOpenAI ügyfelek hozzáadása a konfigurációból

A kulcsos AzureOpenAI-ügyfelekre ugyanazok a funkciók és szabályok vonatkoznak, mint a nem kulcsos ügyfelekre. A AddKeyedOpenAIClientFromConfiguration(IHostApplicationBuilder, String) bővítménymetódussal regisztrálhat egy OpenAIClient vagy AzureOpenAIClient példányt a megadott kapcsolati sztring alapján.

Vegye figyelembe a következő példát:

builder.AddKeyedOpenAIClientFromConfiguration("openai");

Ez a módszer ugyanazokat a szabályokat követi, mint a AzureOpenAI ügyfél hozzáadása akonfigurációból.

Konfiguráció

A .NET AspireAzureOpenAI kódtár több lehetőséget is kínál a AzureOpenAI kapcsolat konfigurálására a projekt követelményei és konvenciók alapján. Meg kell adni vagy egy Endpoint-t, vagy egy ConnectionString-et.

Kapcsolati karakterlánc használata

Ha kapcsolati sztringet használ a ConnectionStrings konfigurációs szakaszból, megadhatja a kapcsolati sztring nevét builder.AddAzureOpenAIClienthívásakor:

builder.AddAzureOpenAIClient("openai");

A kapcsolati sztring a ConnectionStrings konfigurációs szakaszból lesz lekérve, és két támogatott formátum létezik:

Fiókvégpont

Az ajánlott módszer egy Végponthasználata, amely a AzureOpenAISettings.Credential tulajdonsággal együttműködve hoz létre kapcsolatot. Ha nincs hitelesítő adat konfigurálva, a rendszer a DefaultAzureCredential használja.

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

További információ: AzureOpenAI használata kulcsok nélkül.

Kapcsolati karakterlánc

Másik lehetőségként egy egyéni kapcsolati sztring is használható:

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

A nemAzureOpenAI szolgáltatáshoz való csatlakozáshoz ejtse a Endpoint tulajdonságot, és csak a Key tulajdonságot állítsa be a API-kulcsbeállításához.

Konfigurációs szolgáltatók használata

A .NET AspireAzureOpenAI integráció támogatja a Microsoft.Extensions.Configuration. A AzureOpenAISettings kulccsal a Aspire:Azure:AI:OpenAI-et tölti be a konfigurációból. Példa appsettings.json, amely konfigurál néhány beállítást:

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

A teljes AzureOpenAI ügyfél-integrációs JSON sémát lásd: Aspire.Azure. AI.OpenAI/ConfigurationSchema.json.

Beágyazott delegáltak használata

Átadhatja a Action<AzureOpenAISettings> configureSettings delegáltat, hogy beállítson néhány vagy akár az összes opciót közvetlenül a kódban, például letilthatja a nyomkövetést a programkódból.

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

Az OpenAIClientOptionst a AddAzureOpenAIClient metódus opcionális Action<IAzureClientBuilder<OpenAIClient, OpenAIClientOptions>> configureClientBuilder paraméterével is beállíthatja. Például az ügyfél ügyfélazonosítójának beállításához:

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

Megfigyelhetőség és telemetria

.NET .NET Aspire integrációk automatikusan beállítják a naplózási, nyomkövetési és metrikakonfigurációkat, amelyeket más néven a megfigyelhetőség alappillérei. Az integráció megfigyelhetőségéről és telemetriáról további információt .NET.NET Aspire integrációk áttekintésében. A háttérszolgáltatástól függően egyes integrációk csak bizonyos funkciókat támogatnak. Egyes integrációk például támogatják a naplózást és a nyomkövetést, a metrikákat azonban nem. A telemetriai funkciók a Konfiguráció szakaszban ismertetett technikákkal is letilthatók.

Fakitermelés

Az .NET AspireAzureOpenAI integráció a következő naplókategóriákat használja:

• Azure
• Azure.Core
• Azure.Identity

Nyomkövetés

Az .NET AspireAzureOpenAI integráció nyomkövetési tevékenységeket bocsát ki OpenTelemetry használatával a OpenAIClient-el végrehajtott műveletekhez.

Lásd még:

• Azure OpenAI
• .NET .NET Aspire integráció áttekintése
• .NET Aspire Azure integráció áttekintése
• .NET Aspire GitHub tárhely