Get started with the OpenAI integration

OpenAI provides access to chat/completions, embeddings, image, and audio models via a REST API. The OpenAI integration lets you:

• Model an OpenAI account (endpoint + API key) once in the AppHost.
• Add one or more model resources that compose their connection strings from the parent.
• Reference those model resources from projects to get strongly-named connection strings.
• Consume those connection strings with the Aspire.OpenAI component to obtain an OpenAIClient and (optionally) an IChatClient.

In this introduction, you’ll see how to install and use the Aspire OpenAI integrations in a simple configuration. If you already have this knowledge, see OpenAI hosting integration for full reference details.

Заметка

To follow this guide, you must have created an Aspire solution to work with. To learn how to do that, see Build your first Aspire app.

Set up hosting integration

To begin, install the Aspire OpenAI hosting integration in your Aspire AppHost project:

Aspire CLI

Aspire CLI — Добавить пакет Aspire.Hosting.OpenAI

aspire add openai

Aspire CLI интерактивен; выберите подходящий результат поиска при запросе:

Aspire CLI — Пример вывода

Select an integration to add:

> openai (Aspire.Hosting.OpenAI)
> Other results listed as selectable options...

Заметка

Если всего один результат, он выбирается автоматически. Всё равно подтвердите версию.

apphost.cs (C# file-based app)

C# — AppHost.cs

#:package Aspire.Hosting.OpenAI@*

PackageReference (*.csproj)

XML — Добавить ссылку на пакет Aspire.Hosting.OpenAI

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

Next, in the AppHost project, create instances of OpenAI resources and pass them to the consuming client projects:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

var chat = openai.AddModel("chat", "gpt-4o-mini");
var embeddings = openai.AddModel("embeddings", "text-embedding-3-small");

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

builder.Build().Run();

The preceding code adds an OpenAI parent resource and two model resources. Referencing chat passes a connection string named chat to the project. Multiple models can share the single API key and endpoint via the parent resource.

Configure authentication

The integration creates a secret parameter named openai-openai-apikey that automatically falls back to the OPENAI_API_KEY environment variable. Provide the key via user-secrets:

dotnet user-secrets set Parameters:openai-openai-apikey sk-your-api-key

Set up client integration

To get started with the Aspire OpenAI client integration, install the package:

.NET CLI

.NET CLI — Add Aspire.OpenAI package

dotnet add package Aspire.OpenAI

Program.cs (C# file-based app)

Program.cs

#:package Aspire.OpenAI@*

PackageReference (*.csproj)

XML — Add Aspire.OpenAI package reference

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

In the Program.cs file of your client-consuming project, use AddOpenAIClient to register an OpenAIClient for dependency injection:

builder.AddOpenAIClient(connectionName: "chat");

Совет

The connectionName parameter must match the name used when adding the OpenAI resource in the AppHost project.

After adding the OpenAIClient, you can retrieve the client instance using dependency injection:

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

See also

• OpenAI hosting integration
• OpenAI client integration
• OpenAI documentation