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

Inclui: integração de hospedagem e Client integração

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

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

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.

Adicionar um recurso de implantação AzureOpenAI

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

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.

Provisionamento gerado por Bicep

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 padrões padrão.

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

O Bicep anterior é um módulo que provisiona um recurso dos Serviços Cognitivos Azure com os seguintes padrões:

• location: O local do grupo de recursos.
• principalType: o tipo principal do recurso dos Serviços Cognitivos.
• principalId: o ID principal do recurso dos Serviços Cognitivos.
• openai: a conta de recurso dos Serviços Cognitivos.
  • kind: o tipo do recurso, definido como OpenAI.
  • properties: as propriedades do recurso.
    • customSubDomainName: o nome do subdomínio personalizado para o recurso, com base na cadeia de caracteres exclusiva da ID do grupo de recursos.
    • publicNetworkAccess: definido como Enabled.
    • disableLocalAuth: definido como true.
  • sku: a SKU do recurso, definida como S0.
• openai_CognitiveServicesOpenAIContributor: o proprietário do recurso dos Serviços Cognitivos, com base na função embutida Azure Cognitive Services OpenAI Contributor. Para obter mais informações, consulte Azure Serviços Cognitivos OpenAI Colaborador.
• preview: O recurso de implantação, baseado no nome preview.
  • properties: as propriedades do recurso de implantação.
    • format: o formato do recurso de implantação, definido como OpenAI.
    • modelName: o nome do modelo do recurso de implantação, configurado como gpt-4.5-preview.
    • modelVersion: a versão do modelo do recurso de implantação, definida como 2025-02-27.
• connectionString: A string de conexão, que contém o endpoint do recurso dos Serviços Cognitivos.

O Bicep gerado é um ponto de partida e pode ser personalizado para atender aos seus requisitos específicos.

Personalizar a infraestrutura de provisionamento

Todos os recursos .NET AspireAzure são subclasses do tipo AzureProvisioningResource. Isso permite a personalização do Bicep gerado fornecendo uma API fluente para 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:

• Encadeia uma chamada para a API ConfigureInfrastructure:
  • O parâmetro infra é uma instância do tipo AzureResourceInfrastructure.
  • Os recursos provisionáveis são recuperados chamando o método GetProvisionableResources().
  • O único recurso CognitiveServicesAccount é recuperado.
  • A propriedade CognitiveServicesAccount.Sku é atribuída a uma nova instância de CognitiveServicesSku com um nome E0 e um nível CognitiveServicesSkuTier.Enterprise.
  • Uma tag é adicionada ao recurso dos Serviços Cognitivos com a chave ExampleKey e o valor Example value.

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

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

Como alternativa, em vez de representar um recurso de AzureOpenAI, você pode adicionar uma cadeia de conexão ao host do aplicativo. Que é uma abordagem de tipo fraco que se baseia apenas em um valor string. Para adicionar uma conexão a um serviço de AzureOpenAI existente, chame o método 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...

A cadeia de conexão é configurada na configuração do host do aplicativo, normalmente em Segredos do Usuário, na seção ConnectionStrings:

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

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

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

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

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:

• Azure. AI.OpenAI documentação para exemplos de como usar o OpenAIClient.
• Injeção de dependência em .NET para mais detalhes.
• Início Rápido: Introdução ao uso do GPT-35-Turbo e GPT-4 com AzureOpenAI Service.

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:

• AddChatClient(AspireOpenAIClientBuilder, String): Registra um singleton IChatClient nos serviços fornecidos pelo AspireOpenAIClientBuilder.
• AddKeyedChatClient(AspireOpenAIClientBuilder, String, String): registra um IChatClient singleton chaveado nos serviços fornecidos pelo AspireOpenAIClientBuilder.

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

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

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

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 JSON de integração completa do cliente AzureOpenAI, consulte Aspire.Azure. AI.OpenAI/ConfigurationSchema.json.

Usar delegados embutidos

Você pode passar o delegado Action<AzureOpenAISettings> configureSettings para configurar algumas ou todas as opções embutidas, 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.

Consulte também

• Azure OpenAI
• visão geral das integrações .NET.NET Aspire
• visão geral das integrações .NET AspireAzure
• .NET Aspire GitHub repositório