Compartilhar via

integração .NET AspireAzureOpenAI (versão prévia)

Inclui:Integração de hospedagem incluída —&— Client Integração incluídaClient

Azure OpenAI Service fornece acesso a modelos de linguagem e de incorporação avançados de OpenAIcom a promessa de segurança e garantia empresarial de Azure. A integração .NET AspireAzureOpenAI permite que você se conecte ao Serviço AzureOpenAI ou à API do OpenAIdos seus aplicativos .NET.

Integração de hospedagem

Os modelos de integração de hospedagem .NET.NET AspireAzure OpenAI integram AzureOpenAI recursos como sendo AzureOpenAIResource. Para acessar esses tipos e APIs para expressá-los em seu projeto de host do aplicativo , instale o pacote NuGet 📦Aspire.Hosting.Azure.CognitiveServices:

dotnet add package Aspire.Hosting.Azure.CognitiveServices

Para obter mais informações, consulte dotnet add package ou Gerenciar dependências de pacotes em .NET aplicações.

Adicionar um recurso de AzureOpenAI

Para adicionar um AzureOpenAIResource ao projeto de host do aplicativo, chame o método AddAzureOpenAI:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

O código anterior adiciona um recurso de AzureOpenAI chamado openai ao projeto de host do aplicativo. O método WithReference passa as informações de conexão para o projeto ExampleProject.

Importante

Quando você chama AddAzureOpenAI, ele chama implicitamente AddAzureProvisioning(IDistributedApplicationBuilder)— o que adiciona suporte para gerar recursos Azure dinamicamente durante a inicialização do aplicativo. O aplicativo deve configurar a assinatura e o local apropriados. Para obter mais informações, consulte Provisionamento local: Configuração.

Adicionar um recurso de implantação AzureOpenAI

Para adicionar um recurso de implantação AzureOpenAI, chame o método 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...

O código anterior:

  • Adiciona um recurso de AzureOpenAI chamado openai.
  • Adiciona um recurso de implantação AzureOpenAI chamado preview com um nome de modelo de gpt-4.5-preview. O nome do modelo deve corresponder a um modelo disponível no serviço AzureOpenAI.

Bicep gerado por provisionamento

Caso você seja novo no Bicep, saiba que é uma linguagem de domínio específico para definir recursos Azure. Com .NET.NET Aspire, você não precisa escrever Bicep manualmente; as APIs de provisionamento geram Bicep para você. Quando você publica seu aplicativo, o Bicep gerado provisiona um recurso AzureOpenAI com configurações padrão.

@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

O Bicep precedente é um módulo que provisiona um recurso de Serviços Cognitivos. Além disso, as atribuições de função são criadas para o Azure recurso em um módulo separado:

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

O Bicep gerado é um ponto de partida e é influenciado por alterações na infraestrutura de provisionamento em C#. As personalizações feitas diretamente no arquivo Bicep serão substituídas, portanto, faça alterações por meio das APIs de provisionamento do C# para garantir que elas sejam refletidas nos arquivos gerados.

Personalizar a infraestrutura de provisionamento

Todos os recursos .NET AspireAzure são subclasses do tipo AzureProvisioningResource. Isso possibilita a personalização do Bicep gerado com uma API fluente que permite configurar os recursos de Azure, usando a API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>).

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

O código anterior:

Conectar a um serviço de AzureOpenAI existente

Você pode ter um serviço de AzureOpenAI existente ao qual deseja se conectar. Você pode encadear uma chamada para anotar que seu AzureOpenAIResource é um recurso existente:

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

Importante

Quando você chama RunAsExisting, PublishAsExisting, ou AsExisting métodos para trabalhar com recursos que já estão presentes em sua Azure assinatura, você deve adicionar determinados valores de configuração ao App Host para garantir que .NET Aspire possa localizá-los. Os valores de configuração necessários incluem SubscriptionId, AllowResourceGroupCreation, ResourceGroup e Location. Se você não defini-los, erros de "Configuração ausente" aparecerão no .NET.NET Aspire painel de controle. Para obter mais informações sobre como defini-los, consulte Configuração.

Para obter mais informações sobre como tratar recursos AzureOpenAI como recursos existentes, consulte Usar recursos de Azure existentes.

Observação

Como alternativa, em vez de representar um recurso de AzureOpenAI, você pode adicionar uma cadeia de conexão ao host do aplicativo. Essa abordagem é de tipo fraco e não funciona com atribuições de função ou personalizações de infraestrutura. Para obter mais informações, consulte Adicionar os recursos existentes de Azure com cadeias de conexão.

integração Client

Para começar a usar a integração do cliente .NET AspireAzureOpenAI, instale o pacote NuGet 📦Aspire.Azure. AI.OpenAI no projeto do consumidor, ou seja, o projeto do aplicativo que utiliza o cliente AzureOpenAI.

dotnet add package Aspire.Azure.AI.OpenAI

Adicionar um cliente AzureOpenAI

No arquivo Program.cs do projeto consumidor, use o método AddAzureOpenAIClient(IHostApplicationBuilder, String, Action<AzureOpenAISettings>, Action<IAzureClientBuilder<AzureOpenAIClient,AzureOpenAIClientOptions>>) em qualquer IHostApplicationBuilder para registrar um OpenAIClient para Injeção de Dependência (DI). O AzureOpenAIClient é uma subclasse de OpenAIClient, permitindo que você solicite um dos tipos de DI. Isso garante que o código que não depende de recursos específicos de Azure, permanece genérico. O método AddAzureOpenAIClient requer um parâmetro de nome de conexão.

builder.AddAzureOpenAIClient(connectionName: "openai");

Dica

O parâmetro connectionName deve corresponder ao nome usado ao adicionar o recurso AzureOpenAI no projeto de host do aplicativo. Para obter mais informações, consulte Adicionar um recurso AzureOpenAI.

Depois de adicionar o OpenAIClient, você pode recuperar a instância do cliente usando a injeção de dependência:

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

Para obter mais informações, consulte:

Adicionar cliente AzureOpenAI com IChatClient registrado

Se você estiver interessado em usar a interface IChatClient, com o cliente OpenAI, basta encadear qualquer uma das seguintes APIs ao método AddAzureOpenAIClient:

Por exemplo, considere o seguinte código C# que adiciona um IChatClient ao contêiner de DI:

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

Da mesma forma, você pode adicionar um IChatClient associado a uma chave com o seguinte código C#:

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

Para obter mais informações sobre o IChatClient e sua biblioteca correspondente, consulte Inteligência Artificial em .NET (Prévia).

Definir AzureOpenAI configurações do cliente

A biblioteca de .NET AspireAzureOpenAI fornece um conjunto de configurações para configurar o cliente AzureOpenAI. O método AddAzureOpenAIClient expõe um parâmetro configureSettings opcional do tipo Action<AzureOpenAISettings>?. Para configurar as configurações em linha, considere o seguinte exemplo:

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

O código anterior define a propriedade AzureOpenAISettings.DisableTracing como truee define a propriedade AzureOpenAISettings.Endpoint como o ponto de extremidade AzureOpenAI.

Configurar as opções do construtor de cliente AzureOpenAI

Para configurar o AzureOpenAIClientOptions para o cliente, você pode usar o método AddAzureOpenAIClient. Esse método usa um parâmetro configureClientBuilder opcional do tipo Action<IAzureClientBuilder<OpenAIClient, AzureOpenAIClientOptions>>?. Considere o seguinte exemplo:

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

O construtor de clientes é uma instância do tipo IAzureClientBuilder<TClient,TOptions>, que fornece uma API fluente para configurar as opções do cliente. O código anterior define a propriedade AzureOpenAIClientOptions.UserAgentApplicationId como CLIENT_ID. Para obter mais informações, consulte ConfigureOptions(ChatClientBuilder, Action<ChatOptions>).

Adicionar AzureOpenAI cliente por meio da configuração

Além disso, o pacote fornece o método de extensão AddOpenAIClientFromConfiguration(IHostApplicationBuilder, String) para registrar uma instância de OpenAIClient ou AzureOpenAIClient com base na cadeia de conexão fornecida. Esse método segue estas regras:

  • Se o atributo Endpoint estiver vazio ou ausente, uma instância OpenAIClient será registrada usando a chave fornecida, por exemplo, Key={key};.
  • Se o atributo IsAzure for true, um AzureOpenAIClient será registrado; caso contrário, um OpenAIClient será registrado. Por exemplo, Endpoint={azure_endpoint};Key={key};IsAzure=true registra um AzureOpenAIClient, enquanto Endpoint=https://localhost:18889;Key={key} registra um OpenAIClient.
  • Se o atributo Endpoint contiver ".azure.", um AzureOpenAIClient será registrado; caso contrário, um OpenAIClient é registrado, por exemplo, Endpoint=https://{account}.azure.com;Key={key};.

Considere o seguinte exemplo:

builder.AddOpenAIClientFromConfiguration("openai");

Dica

Uma cadeia de conexão válida deve conter pelo menos um Endpoint ou um Key.

Considere os seguintes exemplos de cadeias de conexão e se eles registram um OpenAIClient ou AzureOpenAIClient:

Exemplo de cadeia de conexão Tipo de cliente registrado
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

Adicionar clientes chaveados de AzureOpenAI

Pode haver situações em que você deseja registrar várias instâncias de OpenAIClient com nomes de conexão diferentes. Para registrar clientes chaveados AzureOpenAI, chame o método AddKeyedAzureOpenAIClient:

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

Importante

Ao usar serviços com chave, verifique se o recurso AzureOpenAI configura duas conexões nomeadas, uma para chat e outra para code.

Em seguida, você pode recuperar as instâncias do cliente usando a injeção de dependência. Por exemplo, para recuperar os clientes de um serviço:

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

Para obter mais informações, consulte Serviços chaveados no .NET.

Adicionar clientes identificados pelas chaves AzureOpenAI a partir da configuração

A mesma funcionalidade e as mesmas regras existem para clientes de AzureOpenAI com chave como para clientes sem chave. Você pode usar o método de extensão AddKeyedOpenAIClientFromConfiguration(IHostApplicationBuilder, String) para registrar uma instância OpenAIClient ou AzureOpenAIClient com base na cadeia de conexão fornecida.

Considere o seguinte exemplo:

builder.AddKeyedOpenAIClientFromConfiguration("openai");

Esse método segue as mesmas regras detalhadas no cliente Adicionar AzureOpenAI a partir da configuração.

Configuração

A biblioteca .NET AspireAzureOpenAI fornece várias opções para configurar a conexão AzureOpenAI com base nos requisitos e convenções do seu projeto. É necessário fornecer um Endpoint ou um ConnectionString.

Usar uma string de conexão

Ao usar uma cadeia de conexão da seção de configuração ConnectionStrings, você pode fornecer o nome da cadeia de conexão ao chamar builder.AddAzureOpenAIClient:

builder.AddAzureOpenAIClient("openai");

A cadeia de conexão é recuperada da seção de configuração ConnectionStrings e há dois formatos com suporte:

Ponto de extremidade da conta

A abordagem recomendada é usar um Endpoint , que funciona com a propriedade AzureOpenAISettings.Credential para estabelecer uma conexão. Se nenhuma credencial estiver configurada, o DefaultAzureCredential será usado.

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

Para obter mais informações, consulte Usar AzureOpenAI sem as teclas.

Cadeia de conexão

Como alternativa, uma cadeia de conexão personalizada pode ser usada:

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

Para se conectar ao serviço nãoAzureOpenAI, elimine a propriedade Endpoint e defina apenas a propriedade Chave para definir a chave de API .

Usar provedores de configuração

A integração .NET AspireAzureOpenAI dá suporte a Microsoft.Extensions.Configuration. Ele carrega AzureOpenAISettings da configuração usando a chave Aspire:Azure:AI:OpenAI. Exemplo appsettings.json que configura algumas das opções:

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

Para obter o esquema Azure de integração completa do cliente OpenAIJSON, consulte Aspire.Azure. AI.OpenAI/ConfigurationSchema.json.

Usar delegados em linha

Você pode passar o delegado Action<AzureOpenAISettings> configureSettings para configurar algumas ou todas as opções diretamente, por exemplo, para desabilitar o rastreamento do código.

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

Você também pode configurar o OpenAIClientOptions usando o parâmetro Action<IAzureClientBuilder<OpenAIClient, OpenAIClientOptions>> configureClientBuilder opcional do método AddAzureOpenAIClient. Por exemplo, para definir a ID do cliente para este cliente:

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

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente configurações de Log, Rastreamento e Métricas, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre a observabilidade e a telemetria de integração, consulte .NET.NET Aspire visão geral das integrações. Dependendo do serviço de backup, algumas integrações só podem dar suporte a alguns desses recursos. Por exemplo, algumas integrações dão suporte a registro em log e rastreamento, mas não a métricas. Os recursos de telemetria também podem ser desabilitados usando as técnicas apresentadas na seção Configuration.

Registro

A integração .NET AspireAzureOpenAI usa as seguintes categorias de log:

  • Azure
  • Azure.Core
  • Azure.Identity

Rastreamento

A integração .NET AspireAzureOpenAI emite atividades de rastreamento usando OpenTelemetry para operações executadas com o OpenAIClient.

Importante

No momento, o rastreamento é experimental com essa integração. Para aceitar, defina a variável de ambiente OPENAI_EXPERIMENTAL_ENABLE_OPEN_TELEMETRY como true ou 1ou chame AppContext.SetSwitch("OpenAI.Experimental.EnableOpenTelemetry", true)) durante a inicialização do aplicativo.

Consulte também