Partilhar via

Integração .NET AspireAzureOpenAI (Pré-visualização)

  • Artigo

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

Azure OpenAI Service fornece acesso aos poderosos modelos de linguagem e incorporação do OpenAIcom a promessa de segurança e valores empresariais da Azure. A integração .NET AspireAzureOpenAI permite que você se conecte à API do AzureOpenAI Service ou do OpenAIa partir de seus aplicativos .NET.

Integração de hospedagem

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

dotnet add package Aspire.Hosting.Azure.CognitiveServices

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

Adicionar um recurso AzureOpenAI

Para adicionar um AzureOpenAIResource ao seu projeto de host de 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 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)—que adiciona suporte para gerar recursos de 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>, 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 AzureOpenAI chamado openai.
  • Adiciona um recurso de implantação AzureOpenAI chamado preview com o nome de modelo gpt-4.5-preview. O nome do modelo deve corresponder a um modelo disponível no serviço AzureOpenAI.

Provisionamento automatizado com Bicep

Se és novo no Bicep, é uma linguagem de domínio específico para a definição de recursos Azure. Com .NET.NET Aspire, você não precisa escrever Bicep manualmente, em vez disso, 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 Azure Serviços Cognitivos com os seguintes padrões:

  • location: Localização do grupo de recursos.
  • principalType: O principal tipo de recurso dos Serviços Cognitivos.
  • principalId: O ID principal do recurso de Serviços Cognitivos.
  • openai: O recurso da conta dos Serviços Cognitivos.
    • kind: O tipo de recurso, definido como OpenAI.
    • properties: As propriedades do recurso.
      • customSubDomainName: O nome de 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 integrada Azure Cognitive Services OpenAI Contributor. Para obter mais informações, consulte Azure Cognitive Services OpenAI Contributor.
  • preview: O recurso de implantação, com base no nome do 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 implementaçã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 de Serviços Cognitivos.

O Bíceps gerado é um ponto de partida e pode ser personalizado para atender às suas necessidades específicas.

Personalizar a infraestrutura de provisionamento

Todos os recursos .NET AspireAzure são subclasses do tipo AzureProvisioningResource. Permite-se a personalização do Bicep gerado ao fornecer uma API fluente para a configuração dos recursos 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-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 Azure existentes.

Como alternativa, em vez de representar um recurso 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...

Observação

As cadeias de conexão são usadas para representar uma ampla gama de informações de conexão, incluindo conexões de banco de dados, agentes de mensagens, URIs de ponto de extremidade e outros serviços. Na nomenclatura .NET.NET Aspire, o termo "cadeia de conexão" é usado para representar qualquer tipo de informação de conexão.

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 recursos existentes de Azure através de cadeias de conexão.

Client Integração

Para começar com a integração do cliente .NET AspireAzureOpenAI, instale o 📦Aspire.Azure. IA.OpenAI pacote NuGet no projeto que consome cliente, ou seja, o projeto para o aplicativo que usa o cliente AzureOpenAI.

dotnet add package Aspire.Azure.AI.OpenAI

Adicionar um cliente AzureOpenAI

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

builder.AddAzureOpenAIClient(connectionName: "openai");

")

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, pode-se 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 o cliente AzureOpenAI com o IChatClient registado

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

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

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

Da mesma forma, pode adicionar uma chave IChatClient com o seguinte código C#:

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

Para obter mais informações sobre o IChatClient e a sua biblioteca correspondente, consulte Inteligência artificial em .NET (Pré-visualização).

Definir as configurações do cliente AzureOpenAI

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 definir as configurações embutidas, 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 builder de cliente AzureOpenAI

Para configurar o AzureOpenAIClientOptions para o cliente, você pode usar o método AddAzureOpenAIClient. Este 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 o cliente AzureOpenAI da configuração

Além disso, o pacote fornece o método de extensão AddOpenAIClientFromConfiguration(IHostApplicationBuilder, String) para registrar uma instância OpenAIClient ou AzureOpenAIClient com base na cadeia de conexão fornecida. Este 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 é 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");

")

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 elas registram um OpenAIClient ou AzureOpenAIClient:

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

Pode haver situações em que você queira registrar várias instâncias de OpenAIClient com nomes de conexão diferentes. Para registrar clientes AzureOpenAI chaveados, 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 indexados no .NET.

Adicionar clientes AzureOpenAI chaveados a partir da configuração

A mesma funcionalidade e regras existem para clientes com chave AzureOpenAI e 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");

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

Configuração

A biblioteca de .NET AspireAzureOpenAI fornece várias opções para configurar a conexão AzureOpenAI com base nos requisitos e convenções do seu projeto. É obrigatoriamente 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 de 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 suportados:

Ponto final 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 chaves.

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 que não éAzureOpenAI, solte a propriedade Endpoint e defina apenas a propriedade Key para definir a chave de API .

Usar provedores de configuração

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

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

Para obter o esquema completo de integração do cliente AzureOpenAIJSON, consulte Aspire.Azure. IA.OpenAI/ConfigurationSchema.json.

Usar delegados embutidos

Você pode passar o Action<AzureOpenAISettings> configureSettings delegado para configurar algumas ou todas as opções embutidas, por exemplo, para desativar 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 as configurações de Logging, Trace e Metrics, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre observabilidade e telemetria de integração, consulte Visão geral de integrações .NET.NET Aspire. Dependendo do serviço de suporte, algumas integrações podem suportar apenas alguns desses recursos. Por exemplo, algumas integrações suportam registro em log e rastreamento, mas não métricas. As funcionalidades de telemetria também podem ser desativadas usando as técnicas apresentadas na secção Configuração.

Registo

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

  • Azure
  • Azure.Core
  • Azure.Identity

Rastreio

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

Importante

O rastreio é atualmente experimental com esta integração. Para aceitá-la, 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.

Ver também