intégration de .NET AspireAzureOpenAI (préversion)

inclut : l’intégration d’hébergement et l’intégration de Client

Azure OpenAI Service permet d’accéder au langage puissant et aux modèles d’incorporation de OpenAIavec la promesse de sécurité et d’entreprise de Azure. L’intégration .NET AspireAzureOpenAI vous permet de vous connecter à AzureOpenAI Service ou à l’API de OpenAIà partir de vos applications .NET.

Intégration de l’hébergement

Les modèles d'intégration de l'hébergement .NET.NET AspireAzure OpenAI intègrent des ressources AzureOpenAI en tant que AzureOpenAIResource. Pour accéder à ces types et API pour les exprimer dans votre 'hôte d’application projet, installez le 📦Aspire. Hébergement.Azure. CognitiveServices package NuGet :

dotnet add package Aspire.Hosting.Azure.CognitiveServices

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

Pour plus d’informations, consultez dotnet add package ou Gérer les dépendances de packages dans les applications .NET.

Ajouter une ressource AzureOpenAI

Pour ajouter un AzureOpenAIResource à votre projet hôte d’application, appelez la méthode AddAzureOpenAI :

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Le code précédent ajoute une ressource AzureOpenAI nommée openai au projet hôte d’application. La méthode WithReference transmet les informations de connexion au projet ExampleProject.

Ajouter une ressource de déploiement AzureOpenAI

Pour ajouter une ressource de déploiement AzureOpenAI, appelez la méthode 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...

Code précédent :

• Ajoute une ressource AzureOpenAI nommée openai.
• Ajoute une ressource de déploiement AzureOpenAI nommée preview avec un nom de modèle de gpt-4.5-preview. Le nom du modèle doit correspondre à un modèle disponible dans le service AzureOpenAI.

Génération d'approvisionnement Bicep

Si vous êtes nouveau dans le domaine de Bicep, sachez qu'il s'agit d'un langage spécifique au domaine pour définir les ressources Azure. Avec .NET.NET Aspire, vous n’avez pas besoin d’écrire Bicep manuellement, au lieu de cela, les API d’approvisionnement génèrent Bicep pour vous. Lorsque vous publiez votre application, le Bicep généré provisionne une ressource AzureOpenAI avec des valeurs par défaut standard.

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

Bicep précédent est un module qui provisionne une ressource Cognitive Services Azure avec les valeurs par défaut suivantes :

• location: emplacement du groupe de ressources.
• principalType: type principal de la ressource Cognitive Services.
• principalId: ID principal de la ressource Cognitive Services.
• openai: ressource de compte Cognitive Services.
  • kind: type de ressource, défini sur OpenAI.
  • properties: propriétés de la ressource.
    • customSubDomainName: nom de sous-domaine personnalisé pour la ressource, en fonction de la chaîne unique de l’ID de groupe de ressources.
    • publicNetworkAccess: défini sur Enabled.
    • disableLocalAuth: défini sur true.
  • sku: référence SKU de la ressource, définie sur S0.
• openai_CognitiveServicesOpenAIContributor: Le propriétaire de la ressource Cognitive Services, en fonction du rôle intégré Azure Cognitive Services OpenAI Contributor. Pour plus d’informations, consultez Azure Cognitive Services OpenAI Contributeur.
• preview: ressource de déploiement, en fonction du nom de preview.
  • properties: propriétés de la ressource de déploiement.
    • format: format de la ressource de déploiement, défini sur OpenAI.
    • modelName: nom du modèle de la ressource de déploiement, défini sur gpt-4.5-preview.
    • modelVersion: version du modèle de la ressource de déploiement, définie sur 2025-02-27.
• connectionString: chaîne de connexion contenant le point de terminaison de la ressource Cognitive Services.

Bicep généré est un point de départ et peut être personnalisé pour répondre à vos besoins spécifiques.

Personnaliser l’infrastructure d’approvisionnement

Toutes les ressources .NET AspireAzure sont des sous-classes du type AzureProvisioningResource. Cela permet de personnaliser le Bicep généré en fournissant une API fluide pour configurer les ressources Azure à l'aide de l'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");
    });

Code précédent :

• Chaîne un appel à l’API ConfigureInfrastructure :
  • Le paramètre infra est une instance du type AzureResourceInfrastructure.
  • Les ressources provisionnables sont récupérées en appelant la méthode GetProvisionableResources().
  • La ressource unique CognitiveServicesAccount est récupérée.
  • La propriété CognitiveServicesAccount.Sku est affectée à une nouvelle instance de CognitiveServicesSku avec un nom de E0 et un niveau CognitiveServicesSkuTier.Enterprise.
  • Une balise est ajoutée à la ressource Cognitive Services avec une clé de ExampleKey et une valeur de Example value.

Se connecter à un service existant AzureOpenAI

Vous disposez peut-être d’un service de AzureOpenAI existant auquel vous souhaitez vous connecter. Vous pouvez chaîner un appel pour annoter que votre AzureOpenAIResource est une ressource existante :

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

Pour plus d’informations sur le traitement des ressources AzureOpenAI en tant que ressources existantes, consultez Utiliser des ressources Azure existantes.

Vous pouvez également ajouter une chaîne de connexion à l’hôte de l’application au lieu de représenter une ressource AzureOpenAI. Il s’agit d’une approche faiblement typée basée uniquement sur une valeur string. Pour ajouter une connexion à un service de AzureOpenAI existant, appelez la méthode 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 chaîne de connexion est configurée dans la configuration de l’hôte d’application, généralement sous Secrets utilisateur, sous la section ConnectionStrings :

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

Pour plus d’informations, consultez Ajouter des ressources Azure existantes avec des chaînes de connexion.

intégration Client

Pour commencer à utiliser l’intégration du client .NET AspireAzureOpenAI, installez le package NuGet 📦Aspire.Azure.IA.OpenAI dans le projet consommant le client, c’est-à-dire le projet de l’application qui utilise le client AzureOpenAI.

dotnet add package Aspire.Azure.AI.OpenAI

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

Ajouter un client AzureOpenAI

Dans le fichier Program.cs de votre projet consommant le client, utilisez la méthode AddAzureOpenAIClient(IHostApplicationBuilder, String, Action<AzureOpenAISettings>, Action<IAzureClientBuilder<AzureOpenAIClient,AzureOpenAIClientOptions>>) sur n’importe quel IHostApplicationBuilder pour inscrire un OpenAIClient pour l’injection de dépendances (DI). L'AzureOpenAIClient est une sous-classe de OpenAIClient, ce qui vous permet de demander l'un ou l'autre de ces types à partir de DI. Cela garantit que le code qui ne dépend pas des fonctionnalités spécifiques de Azurereste générique. La méthode AddAzureOpenAIClient nécessite un paramètre de nom de connexion.

builder.AddAzureOpenAIClient(connectionName: "openai");

Après avoir ajouté le OpenAIClient, vous pouvez récupérer l’instance du client à l’aide de l’injection de dépendances :

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

Pour plus d’informations, consultez :

• Azure.IA.OpenAI documentation pour des exemples sur l'utilisation du OpenAIClient.
• Injection de dépendances dans .NET pour en savoir plus sur l'injection de dépendances.
• Démarrage rapide : Prise en main de GPT-35-Turbo et GPT-4 avec AzureOpenAI Service.

Ajouter AzureOpenAI client avec le IChatClient enregistré

Si vous souhaitez utiliser l’interface IChatClient, avec le client OpenAI, il vous suffit de chaîner l’une des API suivantes à la méthode AddAzureOpenAIClient :

• AddChatClient(AspireOpenAIClientBuilder, String): Enregistre un singleton IChatClient dans les services fournis par le AspireOpenAIClientBuilder.
• AddKeyedChatClient(AspireOpenAIClientBuilder, String, String): inscrit un singleton à clé IChatClient dans les services fournis par le AspireOpenAIClientBuilder.

Par exemple, considérez le code C# suivant qui ajoute un IChatClient au conteneur DI :

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

De même, vous pouvez ajouter un IChatClient à clé avec le code C# suivant :

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

Pour plus d’informations sur le IChatClient et sa bibliothèque correspondante, consultez Intelligence artificielle dans .NET (aperçu).

Configurer les paramètres du client AzureOpenAI

La bibliothèque .NET AspireAzureOpenAI fournit un ensemble de paramètres pour configurer le client AzureOpenAI. La méthode AddAzureOpenAIClient expose un paramètre configureSettings facultatif de type Action<AzureOpenAISettings>?. Pour configurer les paramètres inline, tenez compte de l’exemple suivant :

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

Le code précédent définit la propriété AzureOpenAISettings.DisableTracing sur trueet définit la propriété AzureOpenAISettings.Endpoint sur le point de terminaison AzureOpenAI.

Configurer les options du générateur de clients AzureOpenAI

Pour configurer la AzureOpenAIClientOptions pour le client, vous pouvez utiliser la méthode AddAzureOpenAIClient. Cette méthode prend un paramètre configureClientBuilder facultatif de type Action<IAzureClientBuilder<OpenAIClient, AzureOpenAIClientOptions>>?. Prenons l’exemple suivant :

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

Le générateur client est une instance du type IAzureClientBuilder<TClient,TOptions>, qui fournit une API Fluent pour configurer les options du client. Le code précédent définit la propriété AzureOpenAIClientOptions.UserAgentApplicationId sur CLIENT_ID. Pour plus d’informations, consultez ConfigureOptions(ChatClientBuilder, Action<ChatOptions>).

Ajouter le client AzureOpenAI à partir de la configuration

En outre, le package fournit la méthode d’extension AddOpenAIClientFromConfiguration(IHostApplicationBuilder, String) pour inscrire une instance OpenAIClient ou AzureOpenAIClient en fonction de la chaîne de connexion fournie. Cette méthode suit ces règles :

• Si l’attribut Endpoint est vide ou manquant, une instance de OpenAIClient est inscrite à l’aide de la clé fournie, par exemple, Key={key};.
• Si l’attribut IsAzure est true, un AzureOpenAIClient est inscrit ; sinon, un OpenAIClient est inscrit, par exemple, Endpoint={azure_endpoint};Key={key};IsAzure=true inscrit un AzureOpenAIClient, tandis que Endpoint=https://localhost:18889;Key={key} inscrit un OpenAIClient.
• Si l’attribut Endpoint contient ".azure.", un AzureOpenAIClient est inscrit ; sinon, un OpenAIClient est inscrit, par exemple, Endpoint=https://{account}.azure.com;Key={key};.

Prenons l’exemple suivant :

builder.AddOpenAIClientFromConfiguration("openai");

Considérez les exemples de chaînes de connexion suivants et déterminez si elles enregistrent une OpenAIClient ou une AzureOpenAIClient:

Ajouter des clients identifiés par un code AzureOpenAI

Il peut arriver que vous souhaitiez inscrire plusieurs instances de OpenAIClient avec différents noms de connexion. Pour inscrire des clients AzureOpenAI référencés par clé, appelez la méthode AddKeyedAzureOpenAIClient :

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

Vous pouvez ensuite récupérer les instances clientes à l’aide de l’injection de dépendances. Par exemple, pour récupérer les clients à partir d’un service :

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

Pour plus d’informations, consultez les services liés dans .NET.

Ajouter des clients AzureOpenAI identifiés à partir de la configuration

Les mêmes fonctionnalités et règles existent pour les clients avec clé AzureOpenAI que pour les clients non clés. Vous pouvez utiliser la méthode d’extension AddKeyedOpenAIClientFromConfiguration(IHostApplicationBuilder, String) pour inscrire une instance OpenAIClient ou AzureOpenAIClient en fonction de la chaîne de connexion fournie.

Prenons l’exemple suivant :

builder.AddKeyedOpenAIClientFromConfiguration("openai");

Cette méthode suit les mêmes règles que celles détaillées dans le client Ajouter AzureOpenAI de la configuration.

Configuration

La bibliothèque .NET AspireAzureOpenAI fournit plusieurs options pour configurer la connexion AzureOpenAI en fonction des exigences et des conventions de votre projet. Il est nécessaire de fournir soit un Endpoint, soit un ConnectionString.

Utiliser une chaîne de connexion

Lorsque vous utilisez une chaîne de connexion à partir de la section de configuration ConnectionStrings, vous pouvez fournir le nom de la chaîne de connexion lors de l’appel de builder.AddAzureOpenAIClient:

builder.AddAzureOpenAIClient("openai");

La chaîne de connexion est récupérée à partir de la section de configuration ConnectionStrings, et il existe deux formats pris en charge :

Point de terminaison de compte

L’approche recommandée consiste à utiliser un point de terminaison , qui fonctionne avec la propriété AzureOpenAISettings.Credential pour établir une connexion. Si aucune information d’identification n’est configurée, la DefaultAzureCredential est utilisée.

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

Pour plus d’informations, consultez Utiliser AzureOpenAI sans clés.

Chaîne de connexion

Vous pouvez également utiliser une chaîne de connexion personnalisée :

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

Pour vous connecter au service nonAzureOpenAI, supprimez la propriété Endpoint et définissez uniquement la propriété Clé pour définir la clé API .

Utiliser des fournisseurs de configuration

L’intégration .NET AspireAzureOpenAI prend en charge Microsoft.Extensions.Configuration. Il charge le AzureOpenAISettings à partir de la configuration en utilisant la clé Aspire:Azure:AI:OpenAI. Exemple appsettings.json qui configure certaines des options suivantes :

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

Pour obtenir le schéma complet d’intégration AzureOpenAI client JSON, consultez Aspire.Azure. IA.OpenAI/ConfigurationSchema.json.

Utiliser des délégués inline

Vous pouvez transmettre le délégué Action<AzureOpenAISettings> configureSettings pour configurer certaines ou toutes les options en ligne, par exemple pour désactiver le suivi à partir du code :

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

Vous pouvez également configurer OpenAIClientOptions à l’aide du paramètre facultatif Action<IAzureClientBuilder<OpenAIClient, OpenAIClientOptions>> configureClientBuilder de la méthode AddAzureOpenAIClient. Par exemple, pour définir l’ID client pour ce client :

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

Observabilité et télémétrie

.NET .NET Aspire intégrations configurent automatiquement les configurations de journalisation, de suivi et de métriques, parfois appelées les piliers de l’observabilité. Pour plus d’informations sur l’observabilité de l’intégration et la télémétrie, consultez .NET.NET Aspire vue d’ensemble des intégrations. Selon le service de stockage, certaines intégrations peuvent uniquement prendre en charge certaines de ces fonctionnalités. Par exemple, certaines intégrations prennent en charge la journalisation et le suivi, mais pas les métriques. Les fonctionnalités de télémétrie peuvent également être désactivées à l’aide des techniques présentées dans la section Configuration.

Exploitation forestière

L’intégration .NET AspireAzureOpenAI utilise les catégories de journaux suivantes :

• Azure
• Azure.Core
• Azure.Identity

Traçage

L’intégration .NET AspireAzureOpenAI émet des activités de suivi à l’aide de OpenTelemetry pour les opérations effectuées avec le OpenAIClient.

Voir aussi

• Azure OpenAI
• Vue d’ensemble des intégrations .NET.NET Aspire
• Vue d’ensemble des intégrations .NET AspireAzure
• .NET Aspire GitHub repo