概述

这是一个用于访问 OpenAI API 的 .NET 库，由社区维护提供。该库使您能够轻松地将 OpenAI 的功能集成到您的 .NET 应用程序中。

⭐ 您的 Star 让我们倍感鼓舞！GitHub 仓库星标数

社区链接

• 欢迎加入我们，共同建设 .NET AI 社区
• 
• 

安装包

核心库

⚠️ 我们现在有了新的 PackageId 和新的命名空间。⚠️
⚠️ Betalgo.OpenAI 现已更名为 Betalgo.Ranul.OpenAI ⚠️

Install-Package Betalgo.Ranul.OpenAI

实验性工具库

Install-Package Betalgo.OpenAI.Utilities

文档与链接

• 实时 API ✨新功能
• 维基页面
• 功能可用性表
• 变更日志
• 重大变更迁移指南
• 合约升级指南 (9.2.0)

---

致谢

本项目的维护离不开各位报告问题的用户、贡献者以及赞助者的支持。

💖 赞助者：
@betalgo, Laser Cat Eyes
@tylerje, @oferavnery, @MayDay-wpf, @AnukarOP, @Removable, @Scar11

---

示例用法

仓库中包含一个名为 OpenAI.Playground 的示例项目，帮助您理解该库的工作方式。然而，在进行实验时请务必小心，因为某些测试方法可能会导致意外后果，例如文件删除或模型微调。

!! 强烈建议您在使用 Playground 时不要使用主账号，而另开一个账号。部分测试方法可能会添加或删除您的文件和模型，从而引发不必要的麻烦。 !!

您的 API 密钥可在此处获取：https://platform.openai.com/account/api-keys
您的组织 ID 可在此处找到：https://platform.openai.com/account/org-settings

不使用依赖注入

var openAIService = new OpenAIService(new OpenAIOptions()
{
    ApiKey = Environment.GetEnvironmentVariable("MY_OPEN_AI_API_KEY")
});

使用依赖注入

secrets.json

"OpenAIServiceOptions": {
    "ApiKey": "您的 API 密钥放这里",
    "Organization": "您的组织 ID 放这里（可选）",
    "UseBeta": "true/false（可选）"
}

(要使用 用户机密：在“解决方案资源管理器”中右键单击您的项目名称，然后选择“管理用户机密”。这是保护您的 API 密钥的好方法。)

Program.cs

serviceCollection.AddOpenAIService();

或者

serviceCollection.AddOpenAIService(settings => { settings.ApiKey = Environment.GetEnvironmentVariable("MY_OPEN_AI_API_KEY"); });

注入服务后，您可以从服务提供商那里获取它：

var openAiService = serviceProvider.GetRequiredService<IOpenAIService>();

您还可以设置默认模型（可选）：

openAiService.SetDefaultModelId(Models.Gpt_4o);

ChatGPT 示例

var completionResult = await openAiService.ChatCompletion.CreateCompletion(new ChatCompletionCreateRequest
{
    Messages = new List<ChatMessage>
    {
        ChatMessage.FromSystem("你是一个乐于助人的助手。"),
        ChatMessage.FromUser("2020 年世界大赛是谁赢了？"),
        ChatMessage.FromAssistant("2020 年世界大赛是由洛杉矶道奇队赢得的。"),
        ChatMessage.FromUser("比赛是在哪里举行的？")
    },
    Model = Models.Gpt_4o,
});
if (completionResult.Successful)
{
    Console.WriteLine(completionResult.Choices.First().Message.Content);
}

---

注意事项

由于时间限制，不是所有方法都经过充分测试或完全文档化。如果您遇到任何问题，请随时报告或提交拉取请求。您的贡献始终受到欢迎。

毋庸置疑，对于因使用该库而导致的任何损害，我概不负责。

更改记录

9.2.4

• 修复了函数工具模式生成，确保参数始终输出 JSON Schema type: "object"，避免出现类似 schema must be a JSON Schema of 'type: "object"', got 'type: "None"' 的 invalid_function_parameters 错误。

9.2.0

• 引入了 Betalgo.Ranul.OpenAI.Contracts 项目，用于集中管理请求/响应模型、枚举/值类型以及能力接口。
• 用 Contracts 对应版本替换了旧版图像请求模型：
  • CreateImageRequest, CreateImageEditRequest, CreateImageVariationRequest
• 将图像枚举重新组织到 Betalgo.Ranul.OpenAI.Contracts.Enums.Image.* 下，并新增了值类型（ImageOutputFormat, ImageResponseFormat, ImageSize, ImageModeration）。
• 用 Voice（值类型）替换了 VoiceEnum。用 ChatCompletionRole 和/或 AssistantMessageRole 替换了 MessageRole。
• 新增了基础响应类型：ResponseBase, ResponseBaseHeaderValues，改进了头部解析及使用暴露。
• 更新了 IImageService 接口，使其消费 Contracts 请求模型并返回 ImageResponse；目前编辑/变体仍为旧版响应。
• 这是逐步迁移的第一步，更改幅度较小，后续会根据测试情况进一步调整。
• 详细指南请参阅：合约升级指南 (9.2.0)

9.1.0

图像生成

• 添加了 UsageModel，以在图像生成响应中包含详细的 token 使用跟踪信息。

JSON Schema 验证

• 增强了 FunctionParameters，支持 MultipleOf、Minimum、Maximum 和 Pattern。
• 添加了 SingleOrArrayToListConverter，用于处理单个值或数组。

代码改进

• 重构了 MessageContent，使用表达式体辅助方法，并增加了对二进制文件的支持。
• 将 ToolDefinition 中的过滤器类型定义从 static string 改为 const string，以提高清晰度和性能。
• 简化了过滤器创建方法。

文档与格式

• 改进了 ToolDefinition 中的注释和格式。
• 修复了 FunctionParameters 中的 BOM 字符问题。

9.0.4

• 将 Microsoft.Extensions.AI 更新至版本 9.5.0

9.0.3

• 将 Microsoft.Extensions.AI 更新至版本 9.4.0-preview.1.25207.5
• 向模型列表中添加了新模型

9.0.2

• 将 Microsoft.Extensions.AI 更新至版本 9.3.0-preview.1.25114.11
• 添加了推理耗力度参数
• 向模型列表中添加了 o1 和 o3-mini 模型

9.0.1

• 消息列表现在接受 RunId。
• 升级到 Microsoft.Extensions.AI 9.0.1 版本，解决了与其他 SDK 不同版本一起使用时出现的“未找到方法：‘!!0’”错误。

9.0.0

• 新增 .NET 9 支持。
• ⚠️ 对 .NET 6 和 .NET 7 的支持已结束。
• 修复了工具库中的问题，并同步到最新版本。

更多变更日志

---

如遇任何问题、需要贡献或提供反馈，请随时联系我们或提交 Pull Request。

Betalgo X：Betalgo (@Betalgo) / X (twitter.com)
Betalgo LinkedIn：Betalgo | LinkedIn
Tolga X：Tolga Kayhan (@kayhantolga) / X (twitter.com)
Tolga LinkedIn：Tolga Kayhan | LinkedIn

OpenAI .NET 库快速上手指南

本指南帮助 .NET 开发者快速集成 Betalgo.Ranul.OpenAI 社区库，以便在应用中调用 OpenAI API。

环境准备

• 操作系统：Windows、Linux 或 macOS
• .NET 版本：必须使用 .NET 8 或 .NET 9（注：.NET 6 和 .NET 7 已停止支持）
• 前置依赖：
  • 有效的 OpenAI API Key（获取地址：https://platform.openai.com/account/api-keys）
  • （可选）Organization ID
• 开发工具：Visual Studio 2022+、VS Code 或 JetBrains Rider

安装步骤

⚠️ 重要提示：该库近期进行了重构，包名和命名空间已变更。

• 旧包名：Betalgo.OpenAI
• 新包名：Betalgo.Ranul.OpenAI

请在项目目录下运行以下命令安装核心库：

dotnet add package Betalgo.Ranul.OpenAI

或者在 Visual Studio 的“程序包管理器控制台”中运行：

Install-Package Betalgo.Ranul.OpenAI

国内加速建议：如果下载速度较慢，可配置 NuGet 国内镜像源（如阿里云、腾讯云）。 例如临时使用阿里云源安装：

dotnet add package Betalgo.Ranul.OpenAI --source https://api.nuget.org/v3/index.json

(注：若需永久配置，请在 NuGet.Config 文件中添加国内源地址)

基本使用

1. 初始化服务

最简单的方式是直接实例化 OpenAIService。请确保将 API Key 设置为环境变量 MY_OPEN_AI_API_KEY，或在代码中直接替换（生产环境建议使用用户机密或环境变量管理密钥）。

var openAIService = new OpenAIService(new OpenAIOptions()
{
    ApiKey = Environment.GetEnvironmentVariable("MY_OPEN_AI_API_KEY")
});

2. 调用聊天完成接口 (Chat Completion)

以下示例展示了如何调用 GPT-4o 模型进行对话：

var completionResult = await openAiService.ChatCompletion.CreateCompletion(new ChatCompletionCreateRequest
{
    Messages = new List<ChatMessage>
    {
        ChatMessage.FromSystem("You are a helpful assistant."),
        ChatMessage.FromUser("Who won the world series in 2020?"),
        ChatMessage.FromAssistant("The Los Angeles Dodgers won the World Series in 2020."),
        ChatMessage.FromUser("Where was it played?")
    },
    Model = Models.Gpt_4o,
});

if (completionResult.Successful)
{
    Console.WriteLine(completionResult.Choices.First().Message.Content);
}
else
{
    Console.WriteLine($"Error: {completionResult.ErrorMessage}");
}

3. (可选) 设置默认模型

为了避免每次请求都指定模型，可以全局设置默认模型：

openAiService.SetDefaultModelId(Models.Gpt_4o);

---

安全提示：初次尝试时，建议使用独立的测试账号和 API Key，避免测试代码误操作（如删除文件或微调模型）影响主账户资源。