integración de .NET AspireAzureOpenAI (versión preliminar)

incluye: integración de hospedaje de e integración de Client

Azure OpenAI Service proporciona acceso a los potentes modelos de lenguaje e incrustación de OpenAIcon la promesa de seguridad y empresa de Azure. La integración de .NET AspireAzureOpenAI permite conectarse a AzureOpenAI Service o a la API de OpenAIdesde las aplicaciones de .NET.

Integración de hospedaje

Los modelos de integración de alojamiento .NET.NET AspireAzure OpenAI integran recursos AzureOpenAI como AzureOpenAIResource. Para acceder a estos tipos y APIs para expresarlos dentro del proyecto de host de la aplicación , instale el paquete NuGet 📦Aspire.Hosting.Azure.CognitiveServices.

dotnet add package Aspire.Hosting.Azure.CognitiveServices

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

Para obtener más información, consulte dotnet add package o Administrar dependencias de paquetes en .NET aplicaciones.

Adición de un recurso de AzureOpenAI

Para agregar un AzureOpenAIResource al proyecto host de la aplicación, llame al 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...

El código anterior agrega un recurso de AzureOpenAI denominado openai al proyecto host de la aplicación. El método WithReference pasa la información de conexión al proyecto de ExampleProject.

Añadir un recurso de implementación AzureOpenAI

Para agregar un recurso de implementación de AzureOpenAI, llame al 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...

El código anterior:

• Agrega un recurso de AzureOpenAI denominado openai.
• Agrega un recurso de implementación de AzureOpenAI denominado preview con un nombre de modelo de gpt-4.5-preview. El nombre del modelo debe corresponder a un modelo disponible en el servicio AzureOpenAI.

Aprovisionamiento generado de Bicep

Si no está familiarizado con Bicep, es un lenguaje específico del dominio para definir los recursos Azure. Con .NET.NET Aspire, no es necesario escribir Bicep manualmente, sino que las API de aprovisionamiento generan Bicep automáticamente. Al publicar la aplicación, el Bicep generado aprovisiona un recurso AzureOpenAI con valores estándar.

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

El Bicep mencionado previamente es un módulo que aprovisiona un recurso Azure de Cognitive Services con los siguientes valores predeterminados:

• location: ubicación del grupo de recursos.
• principalType: el tipo principal del recurso de Cognitive Services.
• principalId: el identificador principal del recurso de Azure Cognitive Services.
• openai: el recurso de la cuenta de Cognitive Services.
  • kind: el tipo de recurso, fijado a OpenAI.
  • properties: las propiedades del recurso.
    • customSubDomainName: el nombre del subdominio personalizado para el recurso, en función de la cadena única del identificador del grupo de recursos.
    • publicNetworkAccess: establezca en Enabled.
    • disableLocalAuth: establezca en true.
  • sku: la SKU del recurso, establecida en S0.
• openai_CognitiveServicesOpenAIContributor: El propietario del recurso de Cognitive Services, basado en el rol incorporado Azure Cognitive Services OpenAI Contributor. Para obtener más información, consulte Azure colaborador de Cognitive Services OpenAI.
• preview: el recurso de implementación, basado en el nombre del preview.
  • properties: Las propiedades del recurso de implementación.
    • format: el formato del recurso de implementación, establecido en OpenAI.
    • modelName: el nombre del modelo del recurso de implementación, establecido en gpt-4.5-preview.
    • modelVersion: la versión del modelo del recurso de implementación, establecida en 2025-02-27.
• connectionString: la cadena de conexión, que contiene el endpoint del recurso de Servicios Cognitivos.

El Bicep generado es solo un punto de partida y puede personalizarse para satisfacer sus requisitos específicos.

Personalización de la infraestructura de aprovisionamiento

Todos los recursos .NET AspireAzure son subclases del tipo AzureProvisioningResource. Esto permite la personalización del archivo Bicep generado al proporcionar una API fluida para configurar los recursos de Azure utilizando la API de 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");
    });

El código anterior:

• Encadena una llamada a API ConfigureInfrastructure:
  • El parámetro infra es una instancia del tipo AzureResourceInfrastructure.
  • Los recursos aprovisionables se recuperan llamando al método GetProvisionableResources().
  • Se recupera el único recurso CognitiveServicesAccount.
  • La propiedad CognitiveServicesAccount.Sku se asigna a una nueva instancia de CognitiveServicesSku con un nombre de E0 y un nivel de CognitiveServicesSkuTier.Enterprise.
  • Se agrega una etiqueta al recurso de Cognitive Services con una clave de ExampleKey y un valor de Example value.

Conexión a un servicio de AzureOpenAI existente

Es posible que tenga un servicio AzureOpenAI existente al que desea conectarse. Puede encadenar una llamada para indicar que el AzureOpenAIResource es un 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 obtener más información sobre cómo tratar los recursos de AzureOpenAI como recursos existentes, consulte Uso de recursos de Azure existentes.

Como alternativa, en lugar de representar un recurso de AzureOpenAI, puede agregar una cadena de conexión al host de la aplicación. Este es un enfoque débilmente tipado que se basa únicamente en un valor de string. Para agregar una conexión a un servicio de AzureOpenAI existente, llame al 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...

La cadena de conexión se configura en la configuración del host de la aplicación, normalmente en Secretos de usuario, en la sección ConnectionStrings:

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

Para obtener más información, consulte Agregar recursos de Azure existentes con cadenas de conexión.

integración Client

Para empezar con la integración del cliente .NET AspireAzureOpenAI, instale el paquete NuGet 📦Aspire.Azure.AI.OpenAI en el proyecto consumidor de la aplicación que utiliza el cliente AzureOpenAI.

dotnet add package Aspire.Azure.AI.OpenAI

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

Agregar un cliente AzureOpenAI

En el archivo Program.cs de tu proyecto cliente consumidor, usa el método AddAzureOpenAIClient(IHostApplicationBuilder, String, Action<AzureOpenAISettings>, Action<IAzureClientBuilder<AzureOpenAIClient,AzureOpenAIClientOptions>>) en cualquier IHostApplicationBuilder para registrar un OpenAIClient para la inyección de dependencias (DI). El AzureOpenAIClient es una subclase de OpenAIClient, lo que permite solicitar cualquiera de los dos tipos de DI. Esto garantiza que el código que no depende de características específicas de Azurepermanezca genérico. El método AddAzureOpenAIClient requiere un parámetro de nombre de conexión.

builder.AddAzureOpenAIClient(connectionName: "openai");

Después de agregar el OpenAIClient, puede recuperar la instancia de cliente usando inyección de dependencias.

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

Para obtener más información, consulte:

• Azure.AI.OpenAI documentación para ejemplos sobre el uso de OpenAIClient.
• Inyección de dependencias en .NET para obtener más información sobre la inyección de dependencias.
• Inicio rápido: Introducción al uso de GPT-35-Turbo y GPT-4 con AzureOpenAI Service.

Agregar cliente AzureOpenAI con IChatClient registrado

Si está interesado en usar la interfaz de IChatClient, con el cliente de OpenAI, simplemente encadene cualquiera de las siguientes API al método AddAzureOpenAIClient:

• AddChatClient(AspireOpenAIClientBuilder, String): registra un singleton IChatClient en los servicios proporcionados por AspireOpenAIClientBuilder.
• AddKeyedChatClient(AspireOpenAIClientBuilder, String, String): registra un singleton con clave IChatClient en los servicios proporcionados por el AspireOpenAIClientBuilder.

Por ejemplo, considere el siguiente código de C# que agrega un IChatClient al contenedor de inyección de dependencias:

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

Del mismo modo, puede agregar un IChatClient con clave con el siguiente código de C#:

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

Para obtener más información sobre el IChatClient y su biblioteca correspondiente, consulte Inteligencia artificial en .NET (versión preliminar).

Configurar la configuración del cliente AzureOpenAI

La biblioteca .NET AspireAzureOpenAI proporciona un conjunto de opciones para configurar el cliente de AzureOpenAI. El método AddAzureOpenAIClient expone un parámetro opcional configureSettings de tipo Action<AzureOpenAISettings>?. Para configurar la configuración en línea, considere el ejemplo siguiente:

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

El código anterior establece la propiedad AzureOpenAISettings.DisableTracing en truey establece la propiedad AzureOpenAISettings.Endpoint en el punto de conexión de AzureOpenAI.

Configurar las opciones del generador de clientes AzureOpenAI

Para configurar el AzureOpenAIClientOptions para el cliente, puede usar el método AddAzureOpenAIClient. Este método toma un parámetro opcional configureClientBuilder de tipo Action<IAzureClientBuilder<OpenAIClient, AzureOpenAIClientOptions>>?. Considere el ejemplo siguiente:

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

El generador de clientes es una instancia del tipo IAzureClientBuilder<TClient,TOptions>, que proporciona una API fluida para configurar las opciones de cliente. El código anterior establece la propiedad AzureOpenAIClientOptions.UserAgentApplicationId en CLIENT_ID. Para obtener más información, consulte ConfigureOptions(ChatClientBuilder, Action<ChatOptions>).

Añadir cliente AzureOpenAI desde la configuración

Además, el paquete proporciona el método de extensión AddOpenAIClientFromConfiguration(IHostApplicationBuilder, String) para registrar una instancia de OpenAIClient o AzureOpenAIClient en función de la cadena de conexión proporcionada. Este método sigue estas reglas:

• Si el atributo Endpoint está vacío o falta, se registra una instancia de OpenAIClient mediante la clave proporcionada, por ejemplo, Key={key};.
• Si el atributo IsAzure es true, se registra un AzureOpenAIClient; De lo contrario, se registra un OpenAIClient, por ejemplo, Endpoint={azure_endpoint};Key={key};IsAzure=true registra un AzureOpenAIClient, mientras que Endpoint=https://localhost:18889;Key={key} registra un OpenAIClient.
• Si el atributo Endpoint contiene ".azure.", se registra un AzureOpenAIClient; De lo contrario, se registra un OpenAIClient, por ejemplo, Endpoint=https://{account}.azure.com;Key={key};.

Considere el ejemplo siguiente:

builder.AddOpenAIClientFromConfiguration("openai");

Tenga en cuenta las cadenas de conexión de ejemplo siguientes y si registran un OpenAIClient o AzureOpenAIClient:

Agregar clientes de AzureOpenAI con clave

Puede haber situaciones en las que quiera registrar varias instancias de OpenAIClient con nombres de conexión diferentes. Para registrar clientes de AzureOpenAI con clave, llame al método AddKeyedAzureOpenAIClient:

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

A continuación, puede recuperar las instancias de cliente mediante la inyección de dependencias. Por ejemplo, para recuperar los clientes de un servicio:

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

Para obtener más información, consulte Servicios con clave en .NET.

Agregar clientes clave AzureOpenAI desde la configuración

Existen las mismas funciones y reglas para los clientes con clave AzureOpenAI que para los clientes sin clave. Puede usar el método de extensión AddKeyedOpenAIClientFromConfiguration(IHostApplicationBuilder, String) para registrar una instancia de OpenAIClient o AzureOpenAIClient en función de la cadena de conexión proporcionada.

Considere el ejemplo siguiente:

builder.AddKeyedOpenAIClientFromConfiguration("openai");

Este método sigue las mismas reglas que se detallan en el Agregar AzureOpenAI cliente desde la configuración.

Configuración

La biblioteca .NET AspireAzureOpenAI proporciona varias opciones para configurar la conexión de AzureOpenAI en función de los requisitos y convenciones del proyecto. Es necesario proporcionar un Endpoint o un ConnectionString.

Uso de una cadena de conexión

Al usar una cadena de conexión de la sección de configuración de ConnectionStrings, puede proporcionar el nombre de la cadena de conexión al llamar a builder.AddAzureOpenAIClient:

builder.AddAzureOpenAIClient("openai");

La cadena de conexión se recupera de la sección de configuración de ConnectionStrings y hay dos formatos admitidos:

Punto de conexión de cuenta

El enfoque recomendado es usar un punto de conexión , que funciona con la propiedad AzureOpenAISettings.Credential para establecer una conexión. Si no se configura ninguna credencial, se usa el DefaultAzureCredential.

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

Para obtener más información, consulte Usar AzureOpenAI sin claves.

Cadena de conexión

Como alternativa, se puede usar una cadena de conexión personalizada:

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

Para conectarse al servicio que no es deAzureOpenAI, quite la propiedad Endpoint y establezca solo la propiedad Clave para configurar la clave de API .

Uso de proveedores de configuración

La integración de .NET AspireAzureOpenAI admite Microsoft.Extensions.Configuration. Carga el AzureOpenAISettings desde la configuración usando la clave Aspire:Azure:AI:OpenAI. Ejemplo appsettings.json que configura algunas de las opciones:

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

Para obtener el esquema completo de integración de cliente AzureOpenAIJSON, consulte Aspire.Azure. IA.OpenAI/ConfigurationSchema.json.

Utilice delegados en línea

Puede pasar el delegado de Action<AzureOpenAISettings> configureSettings para configurar algunas opciones o todas ellas directamente en el código, por ejemplo, para deshabilitar el seguimiento dentro del código:

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

También puede configurar OpenAIClientOptions mediante el parámetro opcional Action<IAzureClientBuilder<OpenAIClient, OpenAIClientOptions>> configureClientBuilder del método AddAzureOpenAIClient. Por ejemplo, para establecer el identificador de cliente para este cliente:

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

Observabilidad y telemetría

.NET .NET Aspire integraciones configuran automáticamente las configuraciones relacionadas con el registro, el seguimiento y las métricas, que a veces se conocen como los pilares de la observabilidad. Para obtener más información sobre la observabilidad de integración y la telemetría, consulte información general sobre las integraciones de .NET.NET Aspire. En función del servicio de respaldo, algunas integraciones solo pueden admitir algunas de estas características. Por ejemplo, algunas integraciones admiten el registro y el seguimiento, pero no las métricas. Las características de telemetría también se pueden deshabilitar mediante las técnicas presentadas en la sección Configuración.

Registro

La integración de .NET AspireAzureOpenAI usa las siguientes categorías de registro:

• Azure
• Azure.Core
• Azure.Identity

Rastreo

La integración de .NET AspireAzureOpenAI emite actividades de seguimiento mediante OpenTelemetry para las operaciones realizadas con el OpenAIClient.

Consulte también

• Azure OpenAI
• resumen de las integraciones de .NET.NET Aspire
• resumen de las integraciones de .NET AspireAzure
• .NET Aspire GitHub repo