Aspire OpenAI 集成（预览版）

2025-10-02

包含： - Client 集成

OpenAI 通过 API 提供对聊天/完成、嵌入、图像和音频模型 REST 的访问权限。通过集成 AspireOpenAI，您可以：

在 AppHost 中为 OpenAI 帐户（终结点 + API 密钥）建模一次。
添加一个或多个模型资源，用于从父级构成其连接字符串。
从项目中引用这些模型资源以获取强命名的连接字符串。
使用Aspire.OpenAI组件消耗这些连接字符串以获取OpenAIClient和（可选的）IChatClient。

托管集成

具有两种资源类型的托管集成模型 OpenAI ：

OpenAIResource：持有共享 API 密钥和基本终结点的父对象（默认为 https://api.openai.com/v1）。
OpenAIModelResource：表示特定模型的子级；从父级（Endpoint + Key + Model）组合连接字符串。

若要访问这些类型和 API 以在 AppHost 项目中使用它们，请安装 📦Aspire.Hosting.OpenAI NuGet 包：

.NETCLI（命令行界面）
包引用

dotnet add package Aspire.Hosting.OpenAI

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

有关详细信息，请参阅 dotnet 添加包或管理 .NET 应用程序中的包依赖性。

OpenAI添加父资源

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

添加 OpenAI 模型资源

在父级下添加一个或多个子模型，并从项目中引用它们：

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

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

引用chat会将一个名为chat的连接字符串传递给项目。多个模型可以通过父资源共享单个 API 密钥和终结点。

使用默认 API 密钥参数

调用将创建名为 AddOpenAI("openai") 的 openai-openai-apikey机密参数。 Aspire 按以下顺序解析其值：

Parameters:openai-openai-apikey配置密钥（用户机密或appsettings.*环境变量）。
OPENAI_API_KEY 环境变量。

如果两个源都未提供值，则启动将引发一个 MissingParameterValueException。设置其中一个值以避免异常。

通过用户机密提供密钥：

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

使用自定义 API 密钥参数

通过创建自己的机密参数并调用 WithApiKey 父参数来替换默认参数：

var builder = DistributedApplication.CreateBuilder(args);

var apiKey = builder.AddParameter("my-api-key", secret: true);

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

var chat = openai.AddModel("chat", "gpt-4o-mini");

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

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

替换时，原始生成的参数将从资源图中删除。必须标记 secret: true自定义参数。

添加自定义终结点

覆盖默认端点（例如，使用代理或兼容网关）：

var builder = DistributedApplication.CreateBuilder(args);

var openai = builder.AddOpenAI("openai")
                    .WithEndpoint("https://my-gateway.example.com/v1");

var chat = openai.AddModel("chat", "gpt-4o-mini");

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

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

父连接字符串和模型连接字符串都包含自定义终结点。

健康检查

诊断问题时，为每个模型添加可选的单次运行健康检查。

var chat = builder.AddOpenAI("openai")
                  .AddModel("chat", "gpt-4o-mini")
                  .WithHealthCheck();

模型运行状况检查验证终结点可访问性、API 密钥有效性（401）和模型存在（404）。每个应用程序实例只执行一次，以限制速率限制影响。会自动为每个父资源注册一个针对https://status.openai.com/api/v2/status.json的状态页检查。

可用模型

常见标识符：

gpt-5
gpt-4o-mini
gpt-4o
gpt-4-turbo
gpt-realtime
text-embedding-3-small
text-embedding-3-large
dall-e-3
whisper-1

注释

模型名称不区分大小写，但我们通常以小写形式编写它。

有关详细信息，请参阅 OpenAI 模型文档。

Client 集成

若要开始使用AspireOpenAI客户端集成，请在使用📦客户端的应用程序项目中安装Aspire NuGet 包。

.NETCLI（命令行界面）
包引用

dotnet add package Aspire.OpenAI

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

OpenAI 添加一个客户端

在您的客户端使用项目的 Program.cs 文件中，使用 AddOpenAIClient 注册一个 OpenAIClient 以实现依赖项注入（DI）。 AddOpenAIClient 方法需要连接名称参数。

builder.AddOpenAIClient(connectionName: "chat");

小窍门

参数 connectionName 必须与在 AppHost 项目中添加 AzureOpenAI 资源时使用的名称匹配。有关详细信息，请参阅 “添加 OpenAI 父资源 ”或 “添加 OpenAI 模型资源”。

添加 OpenAIClient后，可以使用依赖项注入检索客户端实例：

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

使用已注册的 IChatClient 添加 OpenAI 客户端

builder.AddOpenAIClient("chat")
       .AddChatClient(); // Model inferred from connection string (Model=...)

如果只定义了父资源（没有子模型），请显式提供模型名称：

builder.AddOpenAIClient("openai")
       .AddChatClient("gpt-4o-mini");

AddChatClient （可选）接受模型/部署名称，如果省略，它将来自连接字符串的 Model 项目。根据需要注入 OpenAIClient 或 IChatClient。

配置

Aspire OpenAI 库提供了多个选项，用于根据项目的要求和约定配置 OpenAI 连接。需要提供 Endpoint 或 ConnectionString 中的任意一个。

使用连接字符串

已解析的连接字符串格式：

父级（无模型）：

Endpoint={endpoint};Key={api_key}

模型子级：

Endpoint={endpoint};Key={api_key};Model={model_name}

使用配置提供器

通过 Aspire:OpenAI 键（全局）和 Aspire:OpenAI:{connectionName}（每个命名客户端）进行配置。支持的设置包括Key、Endpoint、DisableTracing、DisableMetrics以及ClientOptions子树（UserAgentApplicationId、OrganizationId、ProjectId、NetworkTimeout、日志记录选项等）。

{
  "ConnectionStrings": {
    "chat": "Endpoint=https://api.openai.com/v1;Key=${OPENAI_API_KEY};Model=gpt-4o-mini"
  },
  "Aspire": {
    "OpenAI": {
      "DisableTracing": false,
      "DisableMetrics": false,
      "ClientOptions": {
        "UserAgentApplicationId": "myapp",
        "NetworkTimeout": "00:00:30"
      }
    }
  }
}

内联配置：

builder.AddOpenAIClient("chat", settings => settings.DisableTracing = true);
builder.AddOpenAIClient("chat", configureOptions: o => o.NetworkTimeout = TimeSpan.FromSeconds(30));

遥测（跟踪 + 指标）在 SDK 中是实验性的 OpenAI.NET 。可以通过 OpenAI.Experimental.EnableOpenTelemetry AppContext 开关或 OPENAI_EXPERIMENTAL_ENABLE_OPEN_TELEMETRY=true 全局启用。在启用时使用 DisableTracing / DisableMetrics 选择退出。

示例应用程序

探索将托管和客户端集成连接在一起的端到端示例，通过参数设置 API 密钥，注册聊天客户端，并执行简单的提示/响应往返过程。克隆存储库，运行它，然后根据模型对其进行调整： https://github.com/dotnet/aspire/tree/main/playground/OpenAIEndToEnd

可观测性和遥测

Aspire 集成会自动设置日志记录、跟踪和指标配置，这些配置有时称为 可观测性支柱。有关集成可观测性和遥测的详细信息，请参阅 Aspire 集成概述。根据支持服务，某些集成可能仅支持其中一些功能。例如，某些集成支持日志记录和跟踪，但不支持指标。还可以使用 “配置” 部分中介绍的技术禁用遥测功能。

伐木业

OpenAI.*

跟踪

OpenAI.* （启用遥测且未禁用时）

Metrics

OpenAI.* 计量（启用遥测且未禁用时）

另请参阅

反馈

此页面是否有帮助？