Sdílet prostřednictvím

integrace .NET AspireAzureOpenAI (Náhled)

  • Článek

zahrnuje: integraci hostování a Client integraci

Azure OpenAI Service poskytuje přístup k výkonnému jazyku a vkládání modelů OpenAIs využitím zabezpečení a podnikového příslibu Azure. Integrace .NET AspireAzureOpenAI umožňuje připojení k rozhraní API služby AzureOpenAI nebo OpenAIz vašich aplikací .NET.

Integrace hostování

.NET .NET Aspire Azure OpenAI hostování modelů integrace AzureOpenAI prostředky jako AzureOpenAIResource. Pokud chcete získat přístup k těmto typům a rozhraním API k jejich použití v projektu hostování aplikace , nainstalujte balíček NuGet 📦Aspire.Hosting.Azure.CognitiveServices.

dotnet add package Aspire.Hosting.Azure.CognitiveServices

Další informace najdete v tématu dotnet add package nebo Manage package dependencies in .NET applications.

Přidejte prostředek AzureOpenAI

Pokud chcete do hostitelského projektu aplikace přidat AzureOpenAIResource, zavolejte metodu AddAzureOpenAI:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Předchozí kód přidá do hostitelského projektu aplikace AzureOpenAI prostředek s názvem openai. Metoda WithReference předá informace o připojení do projektu ExampleProject.

Důležité

Když voláte AddAzureOpenAI, implicitně volá AddAzureProvisioning(IDistributedApplicationBuilder)– což umožňuje dynamické generování Azure prostředků během spouštění aplikace. Aplikace musí nakonfigurovat příslušné předplatné a umístění. Pro více informací si přečtěte Místní zřizování: Konfigurace.

Přidejte prostředek nasazení AzureOpenAI

Pokud chcete přidat prostředek nasazení AzureOpenAI, zavolejte metodu 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...

Předchozí kód:

  • Přidá AzureOpenAI prostředek s názvem openai.
  • Přidá nasazovací prostředek AzureOpenAI s názvem preview a modelem gpt-4.5-preview. Název modelu musí odpovídat modelu dostupnému ve službě AzureOpenAI.

Vygenerovaný provisioning skript Bicep

Pokud jste nováčkem v Bicep, jedná se o specifický jazyk pro danou oblast k definování Azure prostředků. S .NET.NET Aspire nemusíte psát Bicep ručně, protože provisioningové API ho generují za vás. Když publikujete aplikaci, vygenerovaný Bicep zřídí AzureOpenAI prostředek s výchozími standardními nastaveními.

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

Předchozí modul Bicep zřizuje prostředek Azure Cognitive Services s těmito výchozími nastaveními:

  • location: Umístění skupiny prostředků.
  • principalType: Hlavní typ prostředku Cognitive Services.
  • principalId: Hlavní ID prostředku Cognitive Services.
  • openai: Prostředek účtu služeb Cognitive Services.
    • kind: Typ zdroje, nastaven na OpenAI.
    • properties: Vlastnosti prostředku.
      • customSubDomainName: Název vlastní subdomény prostředku, vytvořený na základě jedinečného řetězce ID skupiny prostředků.
      • publicNetworkAccess: Nastaveno na Enabled.
      • disableLocalAuth: Nastaveno na true.
    • sku: Identifikátor SKU prostředku nastaven na S0.
  • openai_CognitiveServicesOpenAIContributor: Vlastník prostředku Cognitive Services podle vestavěné role Azure Cognitive Services OpenAI Contributor. Další informace najdete v tématu Azurepřispěvatelů služeb Cognitive Services OpenAI .
  • preview: Prostředek pro nasazení na základě názvu preview.
    • properties: Vlastnosti prostředku nasazení.
      • format: Formát prostředku pro nasazení, nastavený na OpenAI.
      • modelName: Název modelu prostředku nasazení, který je nastavený na gpt-4.5-preview.
      • modelVersion: Verze modelu prostředku nasazení nastavená na 2025-02-27.
  • connectionString: Připojovací řetězec, který obsahuje koncový bod prostředku služby Cognitive Services.

Vygenerovaný Bicep je výchozím bodem a můžete ho přizpůsobit tak, aby splňoval vaše konkrétní požadavky.

Přizpůsobení infrastruktury implementace

Všechny zdroje .NET AspireAzure jsou podtřídy typu AzureProvisioningResource. To umožňuje přizpůsobení vygenerovaného Bicep tím, že poskytuje plynulé API pro konfiguraci Azure prostředků pomocí 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");
    });

Předchozí kód:

Připojení k existující službě AzureOpenAI

Možná máte existující službu AzureOpenAI, ke které se chcete připojit. Můžete řetězit volání, abyste označili, že AzureOpenAIResource je existující prostředek:

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

Další informace o zacházení s prostředky AzureOpenAI jako s existujícími prostředky najdete v tématu Použití existujících prostředků Azure.

Alternativně místo toho, abyste představovali prostředek AzureOpenAI, můžete k hostiteli aplikace přidat připojovací řetězec. Což je slabě typovaný přístup, který je založený výhradně na hodnotě string. Pokud chcete přidat připojení k existující službě AzureOpenAI, zavolejte metodu 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...

Poznámka:

Připojovací řetězce se používají k reprezentaci široké škály informací o připojení, včetně databázových připojení, zprostředkovatelů zpráv, identifikátorů URI koncových bodů a dalších služeb. V .NET.NET Aspire terminologii se výraz "připojovací řetězec" používá k reprezentaci jakéhokoli druhu informací o připojení.

Připojovací řetězec se konfiguruje v konfiguraci hostitele aplikace, obvykle v části Tajné kódy uživatelů v části ConnectionStrings:

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

Další informace najdete v tématu Přidání existujících prostředků Azure s připojovacími řetězci.

Client integrace

Pokud chcete začít s integrací klienta .NET AspireAzureOpenAI, nainstalujte balíček NuGet 📦Aspire.Azure.AI.OpenAI v klientsky spotřebovávaném projektu, to znamená v projektu aplikace, která používá klienta AzureOpenAI.

dotnet add package Aspire.Azure.AI.OpenAI

Přidejte klienta AzureOpenAI

V souboru Program.cs vašeho projektu, který využívá klienta, použijte metodu AddAzureOpenAIClient(IHostApplicationBuilder, String, Action<AzureOpenAISettings>, Action<IAzureClientBuilder<AzureOpenAIClient,AzureOpenAIClientOptions>>) na libovolném IHostApplicationBuilder, abyste zaregistrovali OpenAIClient pro injektování závislostí (DI). AzureOpenAIClient je podtřída OpenAIClient, která umožňuje požadovat některý typ z DI. Tím se zajistí, že kód nezávislý na funkcích specifických pro Azurezůstane obecný. Metoda AddAzureOpenAIClient vyžaduje parametr názvu připojení.

builder.AddAzureOpenAIClient(connectionName: "openai");

Doporučení

Parametr connectionName se musí shodovat s názvem použitým při přidávání prostředku AzureOpenAI do hostitelského projektu aplikace. Další informace viz Přidání AzureOpenAI prostředku.

Po přidání OpenAIClientmůžete načíst instanci klienta pomocí injektáže závislostí:

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

Další informace najdete tady:

Přidejte klienta AzureOpenAI s registrovaným IChatClient

Pokud vás zajímá použití rozhraní IChatClient s klientem OpenAI, jednoduše zřetězte některé z následujících rozhraní API k metodě AddAzureOpenAIClient:

Představte si například následující kód jazyka C#, který do kontejneru DI přidá IChatClient:

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

Podobně můžete přiřadit klíč IChatClient pomocí následujícího kódu v jazyce C#:

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

Další informace o IChatClient a příslušné knihovně najdete v tématu umělé inteligence v .NET (Preview).

Konfigurace nastavení klienta AzureOpenAI

Knihovna .NET AspireAzureOpenAI poskytuje sadu nastavení pro konfiguraci klienta AzureOpenAI. Metoda AddAzureOpenAIClient zveřejňuje volitelný parametr configureSettings typu Action<AzureOpenAISettings>?. Pokud chcete nakonfigurovat nastavení přímo, zvažte následující příklad:

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

Předchozí kód nastaví vlastnost AzureOpenAISettings.DisableTracing na truea nastaví AzureOpenAISettings.Endpoint vlastnost na koncový bod AzureOpenAI.

Konfigurujte možnosti klientského tvůrce AzureOpenAI

Ke konfiguraci AzureOpenAIClientOptions pro klienta můžete použít metodu AddAzureOpenAIClient. Tato metoda přebírá volitelný parametr configureClientBuilder typu Action<IAzureClientBuilder<OpenAIClient, AzureOpenAIClientOptions>>?. Podívejte se na následující příklad:

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

Tvůrce klienta je instance typu IAzureClientBuilder<TClient,TOptions>, která poskytuje rozhraní API pro plynulou konfiguraci možností klienta. Předchozí kód nastaví vlastnost AzureOpenAIClientOptions.UserAgentApplicationId na CLIENT_ID. Další informace najdete v tématu ConfigureOptions(ChatClientBuilder, Action<ChatOptions>).

Přidání klienta AzureOpenAI z konfigurace

Balíček navíc poskytuje metodu rozšíření AddOpenAIClientFromConfiguration(IHostApplicationBuilder, String) pro registraci OpenAIClient nebo AzureOpenAIClient instance na základě zadaného připojovacího řetězce. Tato metoda se řídí těmito pravidly:

  • Pokud je atribut Endpoint prázdný nebo chybí, je OpenAIClient instance zaregistrována pomocí zadaného klíče, například Key={key};.
  • Je-li atribut IsAzuretrue, je registrován AzureOpenAIClient; v opačném případě se OpenAIClient zaregistruje, například Endpoint={azure_endpoint};Key={key};IsAzure=true zaregistruje AzureOpenAIClient, zatímco Endpoint=https://localhost:18889;Key={key} zaregistruje OpenAIClient.
  • Pokud atribut Endpoint obsahuje ".azure.", zaregistruje se AzureOpenAIClient; v opačném případě je OpenAIClient registrován, například Endpoint=https://{account}.azure.com;Key={key};.

Podívejte se na následující příklad:

builder.AddOpenAIClientFromConfiguration("openai");

Doporučení

Platný připojovací řetězec musí obsahovat alespoň Endpoint nebo Key.

Podívejte se na následující příklad připojovacích řetězců a na to, jestli registrují OpenAIClient nebo AzureOpenAIClient:

Příklad připojovacího řetězce Registrovaný typ klienta
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

Přidejte označené klienty AzureOpenAI

Mohou nastat situace, kdy chcete registrovat více instancí OpenAIClient s různými jmény připojení. Pokud chcete zaregistrovat klíčované klienty AzureOpenAI, zavolejte metodu AddKeyedAzureOpenAIClient:

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

Důležité

Pokud používáte služby s klíči, ujistěte se, že váš prostředek AzureOpenAI konfiguruje dvě pojmenovaná připojení, jedno pro chat a jedno pro code.

Potom můžete získat instance klienta pomocí dependency injection. Pokud chcete například získat klienty ze služby:

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

Další informace naleznete v části Klíčové služby v .NET.

Přidejte klienty kódů AzureaOpenAI z konfigurace

Stejné funkce a pravidla existují pro klienty s klíči AzureOpenAI jako pro klienty bez klíče. Metodu rozšíření AddKeyedOpenAIClientFromConfiguration(IHostApplicationBuilder, String) můžete použít k registraci OpenAIClient nebo AzureOpenAIClient instance na základě zadaného připojovacího řetězce.

Podívejte se na následující příklad:

builder.AddKeyedOpenAIClientFromConfiguration("openai");

Tato metoda se řídí stejnými pravidly, jak je podrobně uvedeno v Přidat klienta AzureOpenAI z konfigurace.

Konfigurace

Knihovna .NET AspireAzureOpenAI nabízí několik možností konfigurace připojení AzureOpenAI na základě požadavků a konvencí projektu. Je nutné zadat Endpoint nebo ConnectionString.

Použijte připojovací řetězec

Při použití připojovacího řetězce z oddílu konfigurace ConnectionStrings můžete při volání builder.AddAzureOpenAIClientzadat název připojovacího řetězce:

builder.AddAzureOpenAIClient("openai");

Připojovací řetězec se načte z oddílu konfigurace ConnectionStrings a existují dva podporované formáty:

Koncový bod účtu

Doporučeným přístupem je použití koncového bodu, který pracuje s vlastností AzureOpenAISettings.Credential pro navázání připojení. Pokud nejsou nakonfigurované žádné přihlašovací údaje, použije se DefaultAzureCredential.

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

Další informace najdete v tématu Použití AzureOpenAI bez klíčů.

Připojovací řetězec

Případně můžete použít vlastní připojovací řetězec:

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

Pokud se chcete připojit ke službě, která neníAzureOpenAI, vypusťte vlastnost Endpoint a nastavte pouze vlastnost Klíč tak, aby nastavil klíč rozhraní API.

Použití zprostředkovatelů konfigurace

Integrace .NET AspireAzureOpenAI podporuje Microsoft.Extensions.Configuration. Načte AzureOpenAISettings z konfigurace pomocí klíče Aspire:Azure:AI:OpenAI. Příklad appsettings.json, který konfiguruje některé z možností:

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

Kompletní schéma integrace klienta AzureOpenAIJSON naleznete v tématu Aspire.Azure. Umělá inteligence.OpenAI/ConfigurationSchema.json.

Použití vložených delegátů

Delegáta Action<AzureOpenAISettings> configureSettings můžete předat k nastavení některých nebo všech možností přímo ve kódu, například pro zakázání trasování z kódu:

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

OpenAIClientOptions můžete také nastavit pomocí volitelného parametru Action<IAzureClientBuilder<OpenAIClient, OpenAIClientOptions>> configureClientBuilder metody AddAzureOpenAIClient. Pokud chcete například nastavit ID klienta pro tohoto klienta:

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

Pozorovatelnost a telemetrie

.NET .NET Aspire integrace automaticky nastaví konfigurace protokolování, trasování a metrik, které se někdy označují jako základy pozorovatelnosti. Další informace o pozorovatelnosti a telemetrii integrace najdete v přehledu integrace .NET.NET Aspire. V závislosti na zálohovací službě můžou některé integrace podporovat pouze některé z těchto funkcí. Například některé integrace podporují protokolování a trasování, ale ne metriky. Funkce telemetrie je také možné zakázat pomocí technik uvedených v části Konfigurace.

Protokolování

Integrace .NET AspireAzureOpenAI používá následující kategorie protokolů:

  • Azure
  • Azure.Core
  • Azure.Identity

Trasování

Integrace .NET AspireAzureOpenAI generuje aktivity trasování pomocí OpenTelemetry pro operace prováděné s OpenAIClient.

Důležité

Trasování je v současné době experimentální u této integrace. Pokud se k němu chcete přihlásit, nastavte proměnnou prostředí OPENAI_EXPERIMENTAL_ENABLE_OPEN_TELEMETRY na true nebo 1nebo volejte AppContext.SetSwitch("OpenAI.Experimental.EnableOpenTelemetry", true)) během spouštění aplikace.

Viz také