Aspire.Azure.AI.OpenAI 8.2.1-preview.1.24473.4

Aspire.Azure.AI.OpenAI library

Registers OpenAIClient as a singleton in the DI container for connecting to Azure OpenAI or OpenAI. Enables corresponding logging and telemetry.

Getting started

Prerequisites

• Azure subscription - create one for free
• Azure OpenAI or OpenAI account - create an Azure OpenAI Service resource

Install the package

Install the .NET Aspire Azure OpenAI library with NuGet:

dotnet add package Aspire.Azure.AI.OpenAI

Usage example

In the Program.cs file of your project, call the AddAzureOpenAIClient extension method to register an OpenAIClient for use via the dependency injection container. The method takes a connection name parameter.

builder.AddAzureOpenAIClient("openaiConnectionName");

You can then retrieve the AzureOpenAIClient instance using dependency injection. For example, to retrieve the client from a Web API controller:

private readonly AzureOpenAIClient _client;

public CognitiveController(AzureOpenAIClient client)
{
    _client = client;
}

Additionally, you can retrieve the AzureOpenAIClient object using the base OpenAIClient service type. This allows for code that is not dependent on Azure OpenAI-specific features to not depend directly on Azure types.

See the Azure OpenAI Service quickstarts for examples on using the AzureOpenAIClient.

Configuration

The .NET Aspire Azure OpenAI library provides multiple options to configure the Azure OpenAI Service based on the requirements and conventions of your project. Note that either an Endpoint or a ConnectionString is required to be supplied.

Use a connection string

A connection can be constructed from the Keys and Endpoint tab with the format Endpoint={endpoint};Key={key};. You can provide the name of the connection string when calling builder.AddAzureOpenAIClient():

builder.AddAzureOpenAIClient("openaiConnectionName");

And then the connection string will be retrieved from the ConnectionStrings configuration section. Two connection formats are supported:

Account Endpoint

The recommended approach is to use an Endpoint, which works with the AzureOpenAISettings.Credential property to establish a connection. If no credential is configured, the DefaultAzureCredential is used.

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

Connection string

Alternatively, a custom connection string can be used.

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

In order to connect to the non-Azure OpenAI service, drop the Endpoint property and only set the Key property to set the API key (https://platform.openai.com/account/api-keys).

Use configuration providers

The .NET Aspire Azure OpenAI library supports Microsoft.Extensions.Configuration. It loads the AzureOpenAISettings and AzureOpenAIClientOptions from configuration by using the Aspire:Azure:AI:OpenAI key. Example appsettings.json that configures some of the options:

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

Use inline delegates

You can also pass the Action<AzureOpenAISettings> configureSettings delegate to set up some or all the options inline, for example to disable tracing from code:

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

You can also setup the AzureOpenAIClientOptions using the optional Action<IAzureClientBuilder<AzureOpenAIClient, AzureOpenAIClientOptions>> configureClientBuilder parameter of the AddAzureOpenAIClient method. For example, to set the client ID for this client:

builder.AddAzureOpenAIClient("openaiConnectionName", configureClientBuilder: configureClientBuilder: builder => builder.ConfigureOptions(options => options.NetworkTimeout = TimeSpan.FromSeconds(2)));

AppHost extensions

In your AppHost project, install the Aspire Azure Cognitive Services Hosting library with NuGet:

dotnet add package Aspire.Hosting.Azure.CognitiveServices

Then, in the Program.cs file of AppHost, add an Azure OpenAI service and consume the connection using the following methods:

var openai = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureOpenAI("openai")
    : builder.AddConnectionString("openai");

var myService = builder.AddProject<Projects.MyService>()
                       .WithReference(openai);

The AddAzureOpenAI method adds an Azure OpenAI resource to the builder. Or AddConnectionString can be used to read connection information from the AppHost's configuration (for example, from "user secrets") under the ConnectionStrings:openai config key. The WithReference method passes that connection information into a connection string named openai in the MyService project. In the Program.cs file of MyService, the connection can be consumed using:

builder.AddAzureOpenAIClient("openai");

Additional documentation

• https://learn.microsoft.com/dotnet/api/overview/azure/ai.openai-readme
• https://github.com/dotnet/aspire/tree/main/src/Components/README.md

Feedback & contributing

https://github.com/dotnet/aspire