OpenAI

基于 OpenAI-DotNet

一个用于 Unity 的 OpenAI 包，可通过其 RESTful API 使用。 本项目为独立开发，并非官方库，本人与 OpenAI 无任何关联。使用前需拥有 OpenAI API 账号。

所有版权、商标、标识及资产均属于其各自所有者。

安装

需要 Unity 2021.3 LTS 或更高版本。

推荐通过 Unity 包管理器和 OpenUPM 进行安装。

通过 Unity 包管理器和 OpenUPM

终端

openupm add com.openai.unity

手动操作

• 打开您的 Unity 项目设置。
• 添加 OpenUPM 包注册表：
  • 名称：OpenUPM
  • URL：https://package.openupm.com
  • 作用域：
    • com.openai
    • com.utilities

• 打开 Unity 包管理器窗口。
• 将注册表从 Unity 切换到 My Registries。
• 添加 OpenAI 包。

通过 Unity 包管理器和 Git URL

[!WARNING] 本仓库依赖其他仓库！您需要自行添加这些依赖。

• 打开您的 Unity 包管理器。
• 从 Git URL 添加包：https://github.com/RageAgainstThePixel/com.openai.unity.git#upm
  • com.utilities.async
  • com.utilities.websockets
  • com.utilities.extensions
  • com.utilities.rest
  • com.utilities.audio
  • com.utilities.encoder.wav

---

文档

欢迎查看我们的全新 API 文档！

https://rageagainstthepixel.github.io/OpenAI-DotNet

目录

• 身份验证
• Azure OpenAI
  • Azure Active Directory 身份验证
• OpenAI API 代理
• 模型
  • 列出模型
  • 获取模型
  • 删除微调模型
• 响应
  • 创建响应
    • 简单的文本响应
    • 带有函数调用的流式响应
  • 获取响应
  • 列出输入项
  • 取消响应
  • 删除响应
• 对话
  • 创建对话
  • 获取对话
  • 更新对话
  • 删除对话
  • 列出对话项
  • 创建对话项
  • 获取对话项
  • 删除对话项
• 实时
  • 创建实时会话
  • 客户端事件
    • 发送客户端事件
  • 服务器事件
    • 接收服务器事件
• 助手
  • 列出助手
  • 创建助手
  • 获取助手
  • 修改助手
  • 删除助手
  • 助手流式处理
  • 线程
    • 创建线程
    • 创建线程并运行
      • 流式处理
    • 获取线程
    • 修改线程
    • 删除线程
    • 线程消息
      • 列出消息
      • 创建消息
      • 获取消息
      • 修改消息
    • 线程运行
      • 列出运行
      • 创建运行
        • 流式处理
      • 获取运行
      • 修改运行
      • 向运行提交工具输出
      • 结构化输出
      • 列出运行步骤
      • 获取运行步骤
      • 取消运行
  • 向量存储
    • 列出向量存储
    • 创建向量存储
    • 获取向量存储
    • 修改向量存储
    • 删除向量存储
    • 向量存储文件
      • 列出向量存储文件
      • 创建向量存储文件
      • 获取向量存储文件
      • 删除向量存储文件
    • 向量存储文件批次
      • 创建向量存储文件批次
      • 获取向量存储文件批次
      • 列出向量存储批次中的文件
      • 取消向量存储文件批次
• 聊天
  • 聊天完成
  • 流式处理
  • 工具
  • 视觉
  • 音频
  • 结构化输出
  • JSON 模式
• 音频
  • 创建语音
    • 流式语音
  • 创建转录
  • 创建翻译
• 图片
  • 创建图片
  • 编辑图片
  • 创建图片变体
• 文件
  • 列出文件
  • 上传文件
  • 删除文件
  • 获取文件信息
  • 下载文件内容
• 微调
  • 创建微调任务
  • 列出微调任务
  • 获取微调任务信息
  • 取消微调任务
  • 列出微调任务事件
• 批处理
  • 列出批处理
  • 创建批处理
  • 获取批处理
  • 取消批处理
• 嵌入
  • 创建嵌入
• 内容审核
  • 创建内容审核

身份验证

提供 API 密钥的方式有四种，按优先级顺序排列如下：

[!WARNING] 建议使用环境变量来加载 API 密钥，而不是将其硬编码在源代码中。不建议在生产环境中使用此方法，而仅适用于接收用户凭据、本地测试和快速入门场景。

1. 通过构造函数直接传递密钥 :warning:
2. Unity 可脚本化对象 :warning:
3. 从配置文件加载密钥
4. 使用系统环境变量

您可以在初始化 API 时使用 OpenAIAuthentication，如下所示：

通过构造函数直接传递密钥

[!WARNING] 建议使用环境变量来加载 API 密钥，而不是将其硬编码在源代码中。不建议在生产环境中使用此方法，而仅适用于接收用户凭据、本地测试和快速入门场景。

var api = new OpenAIClient("sk-apiKey");

或者手动创建一个 OpenAIAuthentication 对象：

var api = new OpenAIClient(new OpenAIAuthentication("sk-apiKey", "org-yourOrganizationId", "proj_yourProjectId"));

Unity 可脚本化对象

您可以将密钥直接保存到位于 Assets/Resources 文件夹中的可脚本化对象中。

可以通过项目面板的上下文菜单创建一个新的 OpenAIConfiguration 可脚本化对象。

[!WARNING] 请注意不要将此文件提交到版本控制系统中，因为其他人将能够看到您的 API 密钥。建议使用 OpenAI-DotNet-Proxy，并通过您首选的 OAuth 提供商对用户进行身份验证。

从配置文件加载密钥

尝试从配置文件中加载 API 密钥，默认情况下为当前目录下的 .openai 文件，也可以选择向上遍历目录树或在用户的主目录中查找。

要创建配置文件，可以新建一个名为 .openai 的文本文件，并在其中添加以下内容：

[!NOTE] 组织 ID 和项目 ID 是可选的。

JSON 格式

{
  "apiKey": "sk-aaaabbbbbccccddddd",
  "organizationId": "org-yourOrganizationId",
  "projectId": "proj_yourProjectId"
}

已弃用的格式

OPENAI_API_KEY=sk-aaaabbbbbccccddddd
OPENAI_ORGANIZATION_ID=org-yourOrganizationId
OPENAI_PROJECT_ID=proj_yourProjectId

您还可以通过调用 OpenAIAuthentication 中的静态方法，直接从已知路径加载配置文件：

• 加载指定目录中的默认 .openai 配置文件：

var api = new OpenAIClient(new OpenAIAuthentication().LoadFromDirectory("path/to/your/directory"));

• 从特定路径加载配置文件。文件不必命名为 .openai，只要符合 JSON 格式即可：

var api = new OpenAIClient(new OpenAIAuthentication().LoadFromPath("path/to/your/file.json"));

使用系统环境变量

使用系统的环境变量来指定要使用的 API 密钥和组织。

• 使用 OPENAI_API_KEY 指定您的 API 密钥。
• 使用 OPENAI_ORGANIZATION_ID 指定组织。
• 使用 OPENAI_PROJECT_ID 指定项目。

var api = new OpenAIClient(new OpenAIAuthentication().LoadFromEnvironment());

---

Azure OpenAI

您也可以选择使用 Microsoft 的 Azure OpenAI 部署。

您可以在 Azure Playground 中找到所需的信息，点击 View Code 按钮，查看类似如下的 URL：

https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

• your-resource-name 您的 Azure OpenAI 资源名称。
• deployment-id 您部署模型时选择的部署名称。
• api-version 用于此操作的 API 版本，格式为 YYYY-MM-DD。

要将客户端设置为使用您的部署，您需要在客户端构造函数中传入 OpenAISettings。

var auth = new OpenAIAuthentication("sk-apiKey");
var settings = new OpenAISettings(resourceName: "your-resource-name", deploymentId: "deployment-id", apiVersion: "api-version");
var api = new OpenAIClient(auth, settings);

Azure Active Directory 身份验证

按照常规方式使用 MSAL（Microsoft 身份验证库 for .NET）获取访问令牌，然后在创建 OpenAIAuthentication 时使用该访问令牌。此外，在创建 OpenAISettings 时，请确保将 useAzureActiveDirectory 设置为 true。

教程：调用 Web API 的桌面应用程序：获取令牌

// 使用任何 MSAL 方法获取访问令牌
var accessToken = result.AccessToken;
var auth = new OpenAIAuthentication(accessToken);
var settings = new OpenAISettings(resourceName: "your-resource", deploymentId: "deployment-id", apiVersion: "api-version", useActiveDirectoryAuthentication: true);
var api = new OpenAIClient(auth, settings);

---

OpenAI API 代理

在前端应用中直接使用 OpenAI-DotNet 或 com.openai.unity 包可能会暴露您的 API 密钥及其他敏感信息。为降低此风险，建议搭建一个中间 API，由该 API 代表您的前端应用向 OpenAI 发送请求。本库既可用于前端配置，也可用于中间层主机配置，从而确保与 OpenAI API 的安全通信。

前端示例

在前端示例中，您需要使用首选的 OAuth 提供商安全地验证用户身份。用户通过身份验证后，再将自定义的身份令牌与后端的 API 密钥进行交换。

请按照以下步骤操作：

1. 使用 OpenAI-DotNet 或 com.openai.unity 包创建新项目。
2. 使用您的 OAuth 提供商对用户进行身份验证。
3. 身份验证成功后，创建一个新的 OpenAIAuthentication 对象，并传入以 sess- 为前缀的自定义令牌。
4. 创建一个新的 OpenAISettings 对象，指定中间 API 所在的域名。
5. 在创建客户端实例时，将新的 auth 和 settings 对象传递给 OpenAIClient 构造函数。

以下是前端设置的示例：

var authToken = await LoginAsync();
var auth = new OpenAIAuthentication($"sess-{authToken}");
var settings = new OpenAISettings(domain: "api.your-custom-domain.com");
var api = new OpenAIClient(auth, settings);

通过这种设置，您的前端应用可以安全地与后端通信，而后端将使用 OpenAI-DotNet-Proxy 将请求转发至 OpenAI API。这样可以确保您的 OpenAI API 密钥及其他敏感信息在整个过程中始终保持安全。

后端示例

在此示例中，我们将演示如何在新的 ASP.NET Core Web 应用中设置并使用 OpenAIProxy。代理服务器将负责身份验证，并将请求转发至 OpenAI API，从而确保您的 API 密钥及其他敏感信息的安全。

1. 创建一个新的 ASP.NET Core 极简 Web API 项目。
2. 将 OpenAI-DotNet NuGet 包添加到您的项目中。
   • PowerShell 安装：Install-Package OpenAI-DotNet-Proxy
   • .NET CLI 安装：dotnet add package OpenAI-DotNet-Proxy
   • 手动编辑 .csproj 文件：<PackageReference Include="OpenAI-DotNet-Proxy" />
3. 创建一个继承自 AbstractAuthenticationFilter 的新类，并重写 ValidateAuthentication 方法。这将实现 IAuthenticationFilter 接口，用于根据内部服务器验证用户会话令牌。
4. 在 Program.cs 中，调用 OpenAIProxy.CreateWebApplication 方法创建新的代理 Web 应用程序，并将自定义的 AuthenticationFilter 作为类型参数传递。
5. 按照常规方式创建 OpenAIAuthentication 和 OpenAIClientSettings，使用您的 API 密钥、组织 ID 或 Azure 设置。

public partial class Program
{
    private class AuthenticationFilter : AbstractAuthenticationFilter
    {
        public override async Task ValidateAuthenticationAsync(IHeaderDictionary request)
        {
            await Task.CompletedTask; // 调用远程资源验证令牌

            // 您需要实现自己的类来正确测试为您终端用户颁发的自定义令牌。
            if (!request.Authorization.ToString().Contains(TestUserToken))
            {
                throw new AuthenticationException("用户未授权");
            }
        }
    }

    public static void Main(string[] args)
    {
        var auth = OpenAIAuthentication.LoadFromEnv();
        var settings = new OpenAIClientSettings(/* 如果使用 Azure OpenAI，请填写自定义设置 */);
        using var openAIClient = new OpenAIClient(auth, settings);
        OpenAIProxy.CreateWebApplication<AuthenticationFilter>(args, openAIClient).Run();
    }
}

一旦您设置了代理服务器，终端用户就可以向您的代理 API 发送经过身份验证的请求，而无需直接访问 OpenAI API。代理服务器将处理身份验证并将请求转发至 OpenAI API，从而确保您的 API 密钥及其他敏感信息的安全。

---

模型

列出并描述 API 中可用的各种模型。您可以参考 模型文档，了解有哪些模型以及它们之间的区别。

此外，请查看 模型端点兼容性，以了解哪些模型适用于哪些端点。

要指定本库中未预定义的自定义模型：

var model = new Model("model-id");

可通过 OpenAIClient.ModelsEndpoint 访问模型 API。

列出模型

列出当前可用的模型，并提供每个模型的基本信息，例如所有者和可用性。

var api = new OpenAIClient();
var models = await api.ModelsEndpoint.GetModelsAsync();

foreach (var model in models)
{
    Debug.Log(model.ToString());
}

获取模型

获取某个模型的详细信息，包括所有者和权限等基本信息。

var api = new OpenAIClient();
var model = await api.ModelsEndpoint.GetModelDetailsAsync("gpt-4o");
Debug.Log(model.ToString());

删除微调模型

删除一个微调过的模型。您必须在组织中拥有所有者角色。

var api = new OpenAIClient();
var isDeleted = await api.ModelsEndpoint.DeleteFineTuneModelAsync("your-fine-tuned-model");
Assert.IsTrue(isDeleted);

---

响应

OpenAI 最先进的模型响应生成接口。支持文本和图像输入，以及文本输出。利用先前响应的输出作为输入，与模型建立有状态的交互。通过内置的文件搜索、网页搜索、计算机操作等工具扩展模型的能力。使用函数调用功能让模型访问外部系统和数据。

• 相关指南：
  • 快速入门
  • 文本输入与输出
  • 图像输入
  • 结构化输出
  • 对话状态
  • 使用工具扩展模型

响应 API 可通过 OpenAIClient.ResponsesEndpoint 访问。

创建响应

创建模型响应。提供文本或图像输入以生成文本或 JSON 输出。让模型调用您自定义的代码，或使用内置工具（如网页搜索、文件搜索）来将您自己的数据作为模型响应的输入。

简单文本响应

var api = new OpenAIClient();
var response = await api.ResponsesEndpoint.CreateModelResponseAsync("给我讲一个关于独角兽的三句话睡前故事。");
var responseItem = response.Output.LastOrDefault();
Debug.Log($"{responseItem.Role}: {responseItem}");
response.PrintUsage();

带函数调用的流式响应

var api = new OpenAIClient();
var conversation = new List<IResponseItem>
{
    new Message(Role.System, "你是一个有用的助手。"),
    new Message(Role.User, "现在几点了？"),
};
var tools = new List<Tool>
{
    Tool.GetOrCreateTool(typeof(DateTimeUtility), nameof(DateTimeUtility.GetDateTime))
};
var request = new CreateResponseRequest(conversation, Model.GPT5_Nano, tools: tools);

async Task StreamCallback(string @event, IServerSentEvent sseEvent)
{
    switch (sseEvent)
    {
        case Message messageItem:
            conversation.Add(messageItem);
            break;
        case FunctionToolCall functionToolCall:
            conversation.Add(functionToolCall);
            var output = await functionToolCall.InvokeFunctionAsync();
            conversation.Add(output);
            await api.ResponsesEndpoint.CreateModelResponseAsync(new(conversation, Model.GPT5_Nano, tools: tools, toolChoice: "none"), StreamCallback);
            break;
    }
}

var response = await api.ResponsesEndpoint.CreateModelResponseAsync(request, StreamCallback);
var responseItem = response.Output.LastOrDefault();
Debug.Log($"{responseItem.Role}: {responseItem}");
response.PrintUsage();

获取响应

根据给定的 ID 获取模型响应。

var api = new OpenAIClient();
var response = await api.ResponsesEndpoint.GetModelResponseAsync("response-id");
Debug.Log(response.ToString());

列出输入项

返回指定响应的所有输入项列表。

var api = new OpenAIClient();
var responseInputItems = await api.ResponsesEndpoint.ListInputItemsAsync("response-id");
foreach (var item in responseInputItems)
{
    Debug.Log(item.ToJsonString());
}

取消响应

根据给定的 ID 取消模型响应。

[!注意] 只有在创建时将 background 参数设置为 true 的响应才能被取消。

var api = new OpenAIClient();
var isCancelled = await api.ResponsesEndpoint.CancelModelResponseAsync("response-id");
Assert.IsTrue(isCancelled);

删除响应

根据给定的 ID 删除模型响应。

var api = new OpenAIClient();
var isDeleted = await api.ResponsesEndpoint.DeleteModelResponseAsync("response-id");
Assert.IsTrue(isDeleted);

---

对话

创建和管理对话，以便在多次响应 API 调用之间存储和检索对话状态。

对话 API 通过 OpenAIClient.ConversationsEndpoint 访问。

创建对话

创建一个对话。

var api = new OpenAIClient();
conversation = await api.ConversationsEndpoint.CreateConversationAsync(
    new CreateConversationRequest(new Message(Role.Developer, systemPrompt)));
Debug.Log(conversation.ToString());
// 在创建响应时使用对话对象。
var request = await api.ResponsesEndpoint.CreateResponseAsync(
    new CreateResponseRequest(textInput: "Hello!", conversationId: conversation, model: Model.GPT5_Nano));
var response = await openAI.ResponsesEndpoint.CreateModelResponseAsync(request);
var responseItem = response.Output.LastOrDefault();
Debug.Log($"{responseItem.Role}:{responseItem}");
response.PrintUsage();

获取对话

根据 ID 获取对话。

var api = new OpenAIClient();
var conversation = await api.ConversationsEndpoint.GetConversationAsync("conversation-id");
Debug.Log(conversation.ToString());

更新对话

使用自定义元数据更新对话。

var api = new OpenAIClient();
var metadata = new Dictionary<string, object>
{
    { "favorite_color", "blue" },
    { "favorite_food", "pizza" }
};
var updatedConversation = await api.ConversationsEndpoint.UpdateConversationAsync("conversation-id", metadata);

删除对话

根据 ID 删除对话。

var api = new OpenAIClient();
var isDeleted = await api.ConversationsEndpoint.DeleteConversationAsync("conversation-id");
Assert.IsTrue(isDeleted);

列出对话项

列出具有给定 ID 的对话的所有项。

var api = new OpenAIClient();
var query = new ListQuery(limit: 10);
var items = await api.ConversationsEndpoint.ListConversationItemsAsync("conversation-id", query);

foreach (var item in items)
{
    Debug.Log(item.ToJsonString());
}

创建对话项

为具有给定 ID 的对话创建一个新的对话项。

var api = new OpenAIClient();
var items = new List<IResponseItem>
{
    new Message(Role.User, "Hello!"),
    new Message(Role.Assistant, "Hi! How can I help you?")
}
var addedItems = await api.ConversationsEndpoint.CreateConversationItemsAsync("conversation-id", items);

foreach (var item in addedItems)
{
    Debug.Log(item.ToJsonString());
}

获取对话项

根据 ID 获取对话项。

var api = new OpenAIClient();
var item = await api.ConversationsEndpoint.GetConversationItemAsync("conversation-id", "item-id");
Debug.Log(item.ToJsonString());

删除对话项

根据 ID 删除对话项。

var api = new OpenAIClient();
var isDeleted = await api.ConversationsEndpoint.DeleteConversationItemAsync("conversation-id", "item-id");
Assert.IsTrue(isDeleted);

---

实时

[!WARNING] 测试功能。API 可能会发生重大变更。

• 实时指南

实时 API 使您能够构建低延迟、多模态的对话体验。目前它支持文本和音频作为输入和输出，以及函数调用。

助手 API 通过 OpenAIClient.RealtimeEndpoint 访问。

创建实时会话

以下是一个简单的示例，说明如何创建实时会话，并向模型发送和接收消息。

var api = new OpenAIClient();
var cancellationTokenSource = new CancellationTokenSource();
var tools = new List<Tool>
{
    Tool.FromFunc("goodbye", () =>
    {
        cancellationTokenSource.Cancel();
        return "Goodbye!";
    })
};
var configuration = new SessionConfiguration(Model.GPT4oRealtime, tools: tools);
using var session = await api.RealtimeEndpoint.CreateSessionAsync(configuration);
var responseTask = session.ReceiveUpdatesAsync<IServerEvent>(ServerEvents, cancellationTokenSource.Token);
await session.SendAsync(new ConversationItemCreateRequest("Hello!"));
await session.SendAsync(new CreateResponseRequest());
await session.SendAsync(new InputAudioBufferAppendRequest(new ReadOnlyMemory<byte>(new byte[1024 * 4])), cancellationTokenSource.Token);
await session.SendAsync(new ConversationItemCreateRequest("GoodBye!"));
await session.SendAsync(new CreateResponseRequest());
await responseTask;

void ServerEvents(IServerEvent @event)
{
    switch (@event)
    {
        case ResponseAudioTranscriptResponse transcriptResponse:
            Debug.Log(transcriptResponse.ToString());
            break;
        case ResponseFunctionCallArgumentsResponse functionCallResponse:
            if (functionCallResponse.IsDone)
            {
                ToolCall toolCall = functionCallResponse;
                toolCall.InvokeFunction();
            }

            break;
    }
}

客户端事件

该库实现了用于发送客户端事件的 IClientEvent 接口。

• UpdateSessionRequest：使用新的会话选项更新会话。
• InputAudioBufferAppendRequest：将音频追加到输入音频缓冲区。（与其他客户端事件不同，服务器不会对此事件发送确认响应）。
• InputAudioBufferCommitRequest：提交输入音频缓冲区。（在服务器 VAD 模式下，客户端无需发送此事件）。
• InputAudioBufferClearRequest：清空输入音频缓冲区。
• ConversationItemCreateRequest：创建一个新的对话项。这是向模型发送用户内容的主要方式。
• ConversationItemTruncateRequest：发送此事件以截断先前助手消息的音频。
• ConversationItemDeleteRequest：删除一个对话项。当您希望从对话历史中移除某条消息时，这非常有用。
• CreateResponseRequest：从模型生成回复。在创建新的对话项或调用工具函数后发送此事件。这将触发模型生成回复。
• ResponseCancelRequest：发送此事件以取消正在进行的回复。

发送客户端事件

您可以随时通过调用会话对象上的 RealtimeSession.SendAsync 方法向服务器发送客户端事件。发送调用将返回一个 IServerEvent 句柄，该句柄最能代表服务器对该事件的适当响应。如果您希望以更细粒度的方式处理服务器响应，这将非常有用。

不过，理想情况下，您可能希望使用 RealtimeSession.ReceiveUpdatesAsync 来处理所有服务器响应。

[!注意] 服务器不会对 InputAudioBufferAppendRequest 事件发送确认响应。

[!重要提示] 您还需要发送 CreateResponseRequest 以触发模型生成回复。

var serverEvent = await session.SendAsync(new ConversationItemCreateRequest("你好！"));
Debug.Log(serverEvent.ToJsonString());
serverEvent = await session.SendAsync(new CreateResponseRequest());
Debug.Log(serverEvent.ToJsonString());

服务器事件

该库为传入的服务器发送事件实现了 IServerEvent 接口。

• RealtimeEventError：在发生错误时返回，可能是客户端问题或服务器问题。
• SessionResponse：用于 session.created 和 session.updated 事件。
• RealtimeConversationResponse：在创建新对话项时返回。
• ConversationItemCreatedResponse：在创建新对话项时返回。
• ConversationItemInputAudioTranscriptionResponse：在输入音频转录完成或失败时返回。
• ConversationItemTruncatedResponse：在对话项被截断时返回。
• ConversationItemDeletedResponse：在对话项被删除时返回。
• InputAudioBufferCommittedResponse：在输入音频缓冲区被提交时返回，无论是由客户端提交还是在服务器 VAD 模式下自动提交。
• InputAudioBufferClearedResponse：在输入音频缓冲区被清空时返回。
• InputAudioBufferStartedResponse：在服务器 VAD 模式下，当检测到音频缓冲区中有语音时，由服务器发送此事件。每当有音频添加到缓冲区时都可能发生（除非已检测到语音）。客户端可能会利用此事件来中断音频播放或向用户提供视觉反馈。
• InputAudioBufferStoppedResponse：在服务器 VAD 模式下，当服务器检测到音频缓冲区中的语音结束时返回。
• RealtimeResponse：在创建或完成回复时返回。
• ResponseOutputItemResponse：在添加或完成回复输出项时返回。
• ResponseContentPartResponse：在添加或完成回复内容部分时返回。
• ResponseTextResponse：在更新或完成回复文本时返回。
• ResponseAudioTranscriptResponse：在更新或完成回复音频转录时返回。
• ResponseAudioResponse：在更新或完成回复音频时返回。
• ResponseFunctionCallArgumentsResponse：在更新或完成回复函数调用参数时返回。
• RateLimitsResponse：在速率限制更新时返回。

接收服务器事件

要接收服务器事件，您需要在会话对象上调用 RealtimeSession.ReceiveUpdatesAsync 方法。该方法将返回一个 Task，当会话关闭或取消令牌触发时，此任务将完成。理想情况下，此方法只需调用一次，并在整个会话期间持续运行。

[!NOTE] 您也可以通过使用 IRealtimeEvent 接口而不是 IServerEvent 来获取 IClientEvent 回调。

await session.ReceiveUpdatesAsync<IServerEvent>(ServerEvents, cancellationTokenSource.Token);

void ServerEvents(IServerEvent @event)
{
    switch (@event)
    {
        case RealtimeEventError error:
            // 任何错误发生时都会触发
            break;
        case SessionResponse sessionResponse:
            // 当会话创建或更新时触发
            break;
        case RealtimeConversationResponse conversationResponse:
            // 当新对话创建时触发
            break;
        case ConversationItemCreatedResponse conversationItemCreated:
            // 当新对话项创建时触发
            break;
        case ConversationItemInputAudioTranscriptionResponse conversationItemTranscription:
            // 当输入音频转录完成或失败时触发
            break;
        case ConversationItemTruncatedResponse conversationItemTruncated:
            // 当对话项被截断时触发
            break;
        case ConversationItemDeletedResponse conversationItemDeleted:
            // 当对话项删除时触发
            break;
        case InputAudioBufferCommittedResponse committedResponse:
            // 当输入音频缓冲区提交时触发
            break;
        case InputAudioBufferClearedResponse clearedResponse:
            // 当输入音频缓冲区清空时触发
            break;
        case InputAudioBufferStartedResponse startedResponse:
            // 当音频缓冲区中检测到语音时触发
            break;
        case InputAudioBufferStoppedResponse stoppedResponse:
            // 当音频缓冲区中的语音停止时触发
            break;
        case RealtimeResponse realtimeResponse:
            // 当响应创建或完成时触发
            break;
        case ResponseOutputItemResponse outputItemResponse:
            // 当响应输出项添加或完成时触发
            break;
        case ResponseContentPartResponse contentPartResponse:
            // 当响应内容部分添加或完成时触发
            break;
        case ResponseTextResponse textResponse:
            // 当响应文本更新或完成时触发
            break;
        case ResponseAudioTranscriptResponse transcriptResponse:
            // 当响应音频转录更新或完成时触发
            break;
        case ResponseFunctionCallArgumentsResponse functionCallResponse:
            // 当响应函数调用参数更新或完成时触发
            break;
        case RateLimitsResponse rateLimitsResponse:
            // 当速率限制更新时触发
            break;
    }
}

---

助手

[!WARNING] 测试功能。API 可能会发生重大变更。

构建可以调用模型并使用工具来执行任务的助手。

• 助手指南
• OpenAI 助手示例库

助手 API 通过 OpenAIClient.AssistantsEndpoint 访问。

列出助手

返回助手列表。

var api = new OpenAIClient();
var assistantsList = await api.AssistantsEndpoint.ListAssistantsAsync();

foreach (var assistant in assistantsList.Items)
{
    Debug.Log($"{assistant} -> {assistant.CreatedAt}");
}

创建助手

使用模型和指令创建助手。

var api = new OpenAIClient();
var request = new CreateAssistantRequest(Model.GPT4o);
var assistant = await api.AssistantsEndpoint.CreateAssistantAsync(request);

获取助手

获取助手信息。

var api = new OpenAIClient();
var assistant = await api.AssistantsEndpoint.RetrieveAssistantAsync("assistant-id");
Debug.Log($"{assistant} -> {assistant.CreatedAt}");

修改助手

修改助手信息。

var api = new OpenAIClient();
var createRequest = new CreateAssistantRequest(Model.GPT4_Turbo);
var assistant = await api.AssistantsEndpoint.CreateAssistantAsync(createRequest);
var modifyRequest = new CreateAssistantRequest(Model.GPT4o);
var modifiedAssistant = await api.AssistantsEndpoint.ModifyAssistantAsync(assistant.Id, modifyRequest);
// 或者使用 AssistantExtension 更方便！
var modifiedAssistantEx = await assistant.ModifyAsync(modifyRequest);

删除助手

删除助手。

var api = new OpenAIClient();
var isDeleted = await api.AssistantsEndpoint.DeleteAssistantAsync("assistant-id");
// 或者使用 AssistantExtension 更方便！
var isDeleted = await assistant.DeleteAsync();
Assert.IsTrue(isDeleted);

助手流式传输

[!NOTE] 通过将 Func<IServerSentEvent, Task> streamEventHandler 回调传递给任何支持流式传输的方法，可以轻松地将助手流事件添加到现有的线程调用中。

线程

创建助手可以与之交互的线程。

线程 API 通过 OpenAIClient.ThreadsEndpoint 访问。

创建线程

创建线程。

var api = new OpenAIClient();
var thread = await api.ThreadsEndpoint.CreateThreadAsync();
Debug.Log($"创建线程 {thread.Id} -> {thread.CreatedAt}");

创建线程并运行

在一个请求中创建线程并运行。

另请参阅：线程运行

var api = new OpenAIClient();
var assistant = await api.AssistantsEndpoint.CreateAssistantAsync(
    new CreateAssistantRequest(
        name: "数学辅导老师",
        instructions: "你是一位私人数学辅导老师。请用一句话或更短的回答来解答问题。",
        model: Model.GPT4o));
var messages = new List<Message> { "我需要解方程 `3x + 11 = 14`。你能帮我吗？" };
var threadRequest = new CreateThreadRequest(messages);
var run = await assistant.CreateThreadAndRunAsync(threadRequest);
Debug.Log($"创建的线程和运行：{run.ThreadId} -> {run.Id} -> {run.CreatedAt}");

创建线程并流式执行

在一个请求中创建线程并执行，同时流式接收事件。

var api = new OpenAIClient();
var tools = new List<Tool>
{
    Tool.GetOrCreateTool(typeof(WeatherService), nameof(WeatherService.GetCurrentWeatherAsync))
};
var assistantRequest = new CreateAssistantRequest(tools: tools, instructions: "你是一位有用的天气助手。请根据地理位置使用合适的单位。");
var assistant = await api.AssistantsEndpoint.CreateAssistantAsync(assistantRequest);
ThreadResponse thread = null;
async Task StreamEventHandler(IServerSentEvent streamEvent)
{
    switch (streamEvent)
    {
        case ThreadResponse threadResponse:
            thread = threadResponse;
            break;
        case RunResponse runResponse:
            if (runResponse.Status == RunStatus.RequiresAction)
            {
                var toolOutputs = await assistant.GetToolOutputsAsync(runResponse);

                foreach (var toolOutput in toolOutputs)
                {
                    Debug.Log($"工具输出：{toolOutput}");
                }

                await runResponse.SubmitToolOutputsAsync(toolOutputs, StreamEventHandler);
            }
            break;
        default:
            Debug.Log(streamEvent.ToJsonString());
            break;
    }
}

var run = await assistant.CreateThreadAndRunAsync("我在吉隆坡，请告诉我现在温度是多少？", StreamEventHandler);
run = await run.WaitForStatusChangeAsync();
var messages = await thread.ListMessagesAsync();
foreach (var response in messages.Items.Reverse())
{
    Debug.Log($"{response.Role}: {response.PrintContent()}");
}

检索线程

检索一个线程。

var api = new OpenAIClient();
var thread = await api.ThreadsEndpoint.RetrieveThreadAsync("thread-id");
// 或者，如果你只想获取线程的最新状态
thread = await thread.UpdateAsync();
Debug.Log($"检索线程 {thread.Id} -> {thread.CreatedAt}");

修改线程

修改一个线程。

[!注意] 只能修改元数据。

var api = new OpenAIClient();
var thread = await api.ThreadsEndpoint.CreateThreadAsync();
var metadata = new Dictionary<string, string>
{
    { "key", "自定义线程元数据" }
};
thread = await api.ThreadsEndpoint.ModifyThreadAsync(thread.Id, metadata);
// 或者使用扩展方法以方便操作！
thread = await thread.ModifyAsync(metadata);
Debug.Log($"修改线程 {thread.Id} -> {thread.Metadata["key"]}");

删除线程

删除一个线程。

var api = new OpenAIClient();
var isDeleted = await api.ThreadsEndpoint.DeleteThreadAsync("thread-id");
// 或者使用扩展方法以方便操作！
var isDeleted = await thread.DeleteAsync();
Assert.IsTrue(isDeleted);

线程消息

在线程中创建消息。

列出线程消息

返回给定线程的消息列表。

var api = new OpenAIClient();
var messageList = await api.ThreadsEndpoint.ListMessagesAsync("thread-id");
// 或者使用扩展方法以方便操作！
var messageList = await thread.ListMessagesAsync();

foreach (var message in messageList.Items)
{
    Debug.Log($"{message.Id}: {message.Role}: {message.PrintContent()}");
}

创建线程消息

创建一条消息。

var api = new OpenAIClient();
var thread = await api.ThreadsEndpoint.CreateThreadAsync();
var request = new CreateMessageRequest("你好，世界！");
var message = await api.ThreadsEndpoint.CreateMessageAsync(thread.Id, request);
// 或者使用扩展方法以方便操作！
var message = await thread.CreateMessageAsync("你好，世界！");
Debug.Log($"{message.Id}: {message.Role}: {message.PrintContent()}");

检索线程消息

检索一条消息。

var api = new OpenAIClient();
var message = await api.ThreadsEndpoint.RetrieveMessageAsync("thread-id", "message-id");
// 或者使用扩展方法以方便操作！
var message = await thread.RetrieveMessageAsync("message-id");
var message = await message.UpdateAsync();
Debug.Log($"{message.Id}: {message.Role}: {message.PrintContent()}");

修改线程消息

修改一条消息。

[!注意] 只能修改消息的元数据。

var api = new OpenAIClient();
var metadata = new Dictionary<string, string>
{
    { "key", "自定义消息元数据" }
};
var message = await api.ThreadsEndpoint.ModifyMessageAsync("thread-id", "message-id", metadata);
// 或者使用扩展方法以方便操作！
var message = await message.ModifyAsync(metadata);
Debug.Log($"修改消息元数据：{message.Id} -> {message.Metadata["key"]}");

线程运行

表示在线程上执行的一次运行。

列出线程运行

返回属于某个线程的所有运行列表。

var api = new OpenAIClient();
var runList = await api.ThreadsEndpoint.ListRunsAsync("thread-id");
// 或者使用扩展方法以方便操作！
var runList = await thread.ListRunsAsync();

foreach (var run in runList.Items)
{
    Debug.Log($"[{run.Id}] {run.Status} | {run.CreatedAt}");
}

创建线程运行

创建一次运行。

var api = new OpenAIClient();
var assistant = await api.AssistantsEndpoint.CreateAssistantAsync(
    new CreateAssistantRequest(
        name: "数学家教",
        instructions: "你是一位私人数学家教。请用一句话或更短的篇幅简要回答问题。",
        model: Model.GPT4o));
var thread = await api.ThreadsEndpoint.CreateThreadAsync();
var message = await thread.CreateMessageAsync("我需要解方程 `3x + 11 = 14`。你能帮我吗？");
var run = await thread.CreateRunAsync(assistant);
Debug.Log($"[{run.Id}] {run.Status} | {run.CreatedAt}");

创建线程并流式处理运行

创建一个运行，并流式传输事件。

var api = new OpenAIClient();
var assistant = await api.AssistantsEndpoint.CreateAssistantAsync(
    new CreateAssistantRequest(
        name: "数学家教",
        instructions: "你是一位私人数学家教。请用一句话或更短的篇幅简要回答问题。你的回答应以 JSON 格式呈现。",
        model: Model.GPT4o,
        responseFormat: ChatResponseFormat.Json));
var thread = await api.ThreadsEndpoint.CreateThreadAsync();
var message = await thread.CreateMessageAsync("我需要解方程 `3x + 11 = 14`。你能帮我吗？");
var run = await thread.CreateRunAsync(assistant, async streamEvent =>
{
    Debug.Log(streamEvent.ToJsonString());
    await Task.CompletedTask;
});
var messages = await thread.ListMessagesAsync();

foreach (var response in messages.Items.Reverse())
{
    Debug.Log($"{response.Role}: {response.PrintContent()}");
}

检索线程运行

检索一个运行。

var api = new OpenAIClient();
var run = await api.ThreadsEndpoint.RetrieveRunAsync("thread-id", "run-id");
// 或者使用扩展方法以方便操作！
var run = await thread.RetrieveRunAsync("run-id");
var run = await run.UpdateAsync();
Debug.Log($"[{run.Id}] {run.Status} | {run.CreatedAt}");

修改线程运行

修改一个运行。

[!注意] 只能修改元数据。

var api = new OpenAIClient();
var metadata = new Dictionary<string, string>
{
    { "key", "自定义运行元数据" }
};
var run = await api.ThreadsEndpoint.ModifyRunAsync("thread-id", "run-id", metadata);
// 或者使用扩展方法以方便操作！
var run = await run.ModifyAsync(metadata);
Debug.Log($"修改运行 {run.Id} -> {run.Metadata["key"]}");

向运行提交工具输出

当运行状态为 requires_action，且 required_action.type 为 submit_tool_outputs 时，可以使用此端点在所有工具调用完成后提交工具输出。所有输出必须在一次请求中提交。

[!注意] 请参阅“创建线程并流式处理运行”示例，了解如何流式传输工具输出事件。

var api = new OpenAIClient();
var tools = new List<Tool>
{
    // 使用预定义工具
    Tool.Retrieval, Tool.CodeInterpreter,
    // 或者根据类型和您希望用于函数调用的方法名称创建工具
    Tool.GetOrCreateTool(typeof(WeatherService), nameof(WeatherService.GetCurrentWeatherAsync)),
    // 传入对象实例以在其上调用方法
    Tool.GetOrCreateTool(api.ImagesEndPoint, nameof(ImagesEndpoint.GenerateImageAsync)),
    // 定义 func<,> 回调函数
    Tool.FromFunc("name_of_func", () => { /* 回调函数 */ }),
    Tool.FromFunc<T1,T2,TResult>("func_with_multiple_params", (t1, t2) => { /* 计算返回值的逻辑 */ return tResult; })
};
var assistantRequest = new CreateAssistantRequest(tools: tools, instructions: "你是一位有用的天气助手。请根据地理位置使用适当的单位。");
var testAssistant = await api.AssistantsEndpoint.CreateAssistantAsync(assistantRequest);
var run = await testAssistant.CreateThreadAndRunAsync("我在吉隆坡，请告诉我现在的温度是多少？");
// 等待运行处于排队和进行中状态
run = await run.WaitForStatusChangeAsync();

// 调用所有工具调用函数并获取工具输出。
var toolOutputs = await testAssistant.GetToolOutputsAsync(run.RequiredAction.SubmitToolOutputs.ToolCalls);

foreach (var toolOutput in toolOutputs)
{
    Debug.Log($"工具调用输出：{toolOutput.Output}");
}
// 提交工具输出
run = await run.SubmitToolOutputsAsync(toolOutputs);
// 等待运行再次进入排队和进行中状态
run = await run.WaitForStatusChangeAsync();
var messages = await run.ListMessagesAsync。

foreach (var message in messages.Items.OrderBy(response => response.CreatedAt))
{
    Debug.Log($"{message.Role}: {message.PrintContent()}");
}

线程结构化输出

结构化输出是 JSON 模式的演进版本。虽然两者都能确保生成有效的 JSON，但只有结构化输出才能保证符合模式要求。

[!重要提示]

• 使用 JSON 模式时，务必通过对话中的某条消息（例如系统消息）指示模型生成 JSON。如果不明确指示生成 JSON，模型可能会生成无休止的空白内容，请求也可能持续进行，直到达到令牌限制。为了防止这种情况发生，API 会在上下文中未出现“JSON”字符串时抛出错误。
• 如果 finish_reason 是 length，表示生成内容超过了 max_tokens 或对话的令牌限制，则模型返回的消息中的 JSON 可能是不完整的（即被截断）。为避免这种情况，在解析响应前请检查 finish_reason。

首先定义您的响应结构。这些将用作您的模式。 这些是您将反序列化的目标对象，因此请务必使用标准的 Json 对象模型。

public class MathResponse
{
    [JsonProperty("steps")]
    public IReadOnlyList<MathStep> Steps { get; private set; }

    [JsonProperty("final_answer")]
    public string FinalAnswer { get; private set; }
}

public class MathStep
{
    [JsonProperty("explanation")]
    public string Explanation { get; private set; }

    [JsonProperty("output")]
    public string Output { get; private set; }
}

使用时，只需在 CreateAssistantAsync、CreateRunAsync 或 CreateThreadAndRunAsync 中将 MathResponse 类型指定为泛型约束即可。

var api = new OpenAIClient();
var assistant = await api.AssistantsEndpoint.CreateAssistantAsync<MathResponse>(
    new CreateAssistantRequest(
        name: "数学家教",
        instructions: "你是一位有帮助的数学家教。请逐步引导用户完成解题过程。",
        model: "gpt-4o-2024-08-06"));
ThreadResponse thread = null;

尝试
{
    异步任务 StreamEventHandler(IServerSentEvent @event)
    {
        try
        {
            切换 (@event)
            {
                案例 MessageResponse message:
                    如果 (message.Status != MessageStatus.Completed)
                    {
                        Debug.Log(@event.ToJsonString());
                        中断;
                    }

                    var mathResponse = message.FromSchema<MathResponse>();

                    对于 (var i = 0; i < mathResponse.Steps.Count; i++)
                    {
                        var step = mathResponse.Steps[i];
                        Debug.Log($"步骤 {i}: {step.Explanation}");
                        Debug.Log($"结果: {step.Output}");
                    }

                    Debug.Log($"最终答案: {mathResponse.FinalAnswer}");
                    中断;
                默认:
                    Debug.Log(@event.ToJsonString());
                    中断;
            }
        }
        抓取 (Exception e)
        {
            Debug.Log(e);
            抛出;
        }

        等待 Task.CompletedTask;
    }

    var run = await assistant.CreateThreadAndRunAsync("如何解方程 8x + 7 = -23", StreamEventHandler);
    thread = await run.GetThreadAsync();
    run = await run.WaitForStatusChangeAsync();
    Debug.Log($"创建了线程和运行：{run.ThreadId} -> {run.Id} -> {run.CreatedAt}");
    var messages = await thread.ListMessagesAsync();

    对于 (var response 在 messages.Items 中按 CreatedAt 排序)
    {
        Debug.Log($"{response.Role}: {response.PrintContent()}");
    }
}
最后
{
    等待 assistant.DeleteAsync(deleteToolResources: thread == null);

    如果 (thread != null)
    {
        var isDeleted = await thread.DeleteAsync(deleteToolResources: true);
    }
}

你也可以手动创建 JSON 模式 JSON 字符串，但你需要负责反序列化你的响应数据：

var api = new OpenAIClient();
var mathSchema = new JsonSchema("math_response", @"
{
  ""type"": ""object"",
  ""properties"": {
    ""steps"": {
      ""type"": ""array"",
      ""items"": {
        ""type"": ""object"",
        ""properties"": {
          ""explanation"": {
            ""type"": ""string""
          },
          ""output"": {
            ""type"": ""string""
          }
        },
        ""required"": [
          ""explanation"",
          ""output""
        ],
        ""additionalProperties"": false
      }
    },
    ""final_answer"": {
      ""type"": ""string""
    }
  },
  ""required"": [
    ""steps"",
    ""final_answer""
  ],
  ""additionalProperties"": false
}");
var assistant = await api.AssistantsEndpoint.CreateAssistantAsync(
    新的 CreateAssistantRequest(
        名称: "数学辅导老师",
        指令: "你是一位乐于助人的数学辅导老师。请逐步引导用户解决问题。",
        模型: "gpt-4o-2024-08-06",
        jsonSchema: mathSchema));
ThreadResponse thread = null;

尝试
{
    var run = await assistant.CreateThreadAndRunAsync("如何解方程 8x + 7 = -23",
        异步 @event =>
        {
            Debug.Log(@event.ToJsonString());
            等待 Task.CompletedTask;
        });
    thread = await run.GetThreadAsync();
    run = await run.WaitForStatusChangeAsync();
    Debug.Log($"创建了线程和运行：{run.ThreadId} -> {run.Id} -> {run.CreatedAt}");
    var messages = await thread.ListMessagesAsync。

    对于 (var response 在 messages.Items 中)
    {
        Debug.Log($"{response.Role}: {response.PrintContent()}");
    }
}
最后
{
    等待 assistant.DeleteAsync(deleteToolResources: thread == null);

    如果 (thread != null)
    {
        var isDeleted = await thread.DeleteAsync(deleteToolResources: true);
        Assert.IsTrue(isDeleted);
    }
}

列出线程运行步骤

返回属于某个运行的运行步骤列表。

var api = new OpenAIClient();
var runStepList = await api.ThreadsEndpoint.ListRunStepsAsync("thread-id", "run-id");
// 或者使用扩展方法以方便操作！
var runStepList = await run.ListRunStepsAsync。

对于 (var runStep 在 runStepList.Items 中)
{
    Debug.Log($"[{runStep.Id}] {runStep.Status} {runStep.CreatedAt} -> {runStep.ExpiresAt}");
}

获取线程运行步骤

获取一个运行步骤。

var api = new OpenAIClient();
var runStep = await api.ThreadsEndpoint.RetrieveRunStepAsync("thread-id", "run-id", "step-id");
// 或者使用扩展方法以方便操作！
var runStep = await run.RetrieveRunStepAsync("step-id");
var runStep = await runStep.UpdateAsync();
Debug.Log($"[{runStep.Id}] {runStep.Status} {runStep.CreatedAt} -> {runStep.ExpiresAt}");

取消线程运行

取消一个处于 in_progress 状态的运行。

var api = new OpenAIClient();
var isCancelled = await api.ThreadsEndpoint.CancelRunAsync("thread-id", "run-id");
// 或者使用扩展方法以方便操作！
var isCancelled = await run.CancelAsync();
Assert.IsTrue(isCancelled);

向量存储

向量存储用于存储文件，供 file_search 工具使用。

• 文件搜索指南

通过 OpenAIClient.VectorStoresEndpoint 访问向量存储 API。

列出向量存储

返回向量存储列表。

var api = new OpenAIClient();
var vectorStores = await api.VectorStoresEndpoint.ListVectorStoresAsync。

对于 (var vectorStore 在 vectorStores.Items 中)
{
    Debug.Log(vectorStore);
}

创建向量存储

创建一个向量存储。

var api = new OpenAIClient();
var createVectorStoreRequest = 新的 CreateVectorStoreRequest("测试向量存储");
var vectorStore = await api.VectorStoresEndpoint.CreateVectorStoreAsync(createVectorStoreRequest);
Debug.Log(vectorStore);

获取向量存储

获取一个向量存储。

var api = new OpenAIClient();
var vectorStore = await api.VectorStoresEndpoint.GetVectorStoreAsync("向量存储ID");
Debug.Log(vectorStore);

修改向量存储

修改一个向量存储。

var api = new OpenAIClient();
var metadata = 新的 字典<string, object> { { "测试", 当前时间 } };
var vectorStore = await api.VectorStoresEndpoint.ModifyVectorStoreAsync("向量存储ID", metadata: metadata);
Debug.Log(vectorStore);

删除向量存储

删除向量存储。

var api = new OpenAIClient();
var isDeleted = await api.VectorStoresEndpoint.DeleteVectorStoreAsync("vector-store-id");
Assert.IsTrue(isDeleted);

向量存储文件

向量存储文件表示向量存储中的文件。

• 文件搜索指南

列出向量存储文件

返回向量存储文件的列表。

var api = new OpenAIClient();
var files = await api.VectorStoresEndpoint.ListVectorStoreFilesAsync("vector-store-id");

foreach (var file in vectorStoreFiles.Items)
{
    Debug.Log(file);
}

创建向量存储文件

通过将文件附加到向量存储来创建向量存储文件。

var api = new OpenAIClient();
var file = await api.VectorStoresEndpoint.CreateVectorStoreFileAsync("vector-store-id", "file-id", new ChunkingStrategy(ChunkingStrategyType.Static));
Debug.Log(file);

获取向量存储文件

获取向量存储文件。

var api = new OpenAIClient();
var file = await api.VectorStoresEndpoint.GetVectorStoreFileAsync("vector-store-id", "vector-store-file-id");
Debug.Log(file);

删除向量存储文件

删除向量存储文件。这会从向量存储中移除文件，但文件本身不会被删除。要删除文件，请使用删除文件端点。

var api = new OpenAIClient();
var isDeleted = await api.VectorStoresEndpoint.DeleteVectorStoreFileAsync("vector-store-id", vectorStoreFile);
Assert.IsTrue(isDeleted);

向量存储文件批次

向量存储文件表示向量存储中的文件。

• 文件搜索指南

创建向量存储文件批次

创建向量存储文件批次。

var api = new OpenAIClient();
var files = new List<string> { "file_id_1","file_id_2" };
var vectorStoreFileBatch = await api.VectorStoresEndpoint.CreateVectorStoreFileBatchAsync("vector-store-id", files);
Debug.Log(vectorStoreFileBatch);

获取向量存储文件批次

获取向量存储文件批次。

var api = new OpenAIClient();
var vectorStoreFileBatch = await api.VectorStoresEndpoint.GetVectorStoreFileBatchAsync("vector-store-id", "vector-store-file-batch-id");
// 你也可以使用便捷方法！
vectorStoreFileBatch = await vectorStoreFileBatch.UpdateAsync();
vectorStoreFileBatch = await vectorStoreFileBatch.WaitForStatusChangeAsync();

列出向量存储批次中的文件

返回批次中向量存储文件的列表。

var api = new OpenAIClient();
var files = await api.VectorStoresEndpoint.ListVectorStoreBatchFilesAsync("vector-store-id", "vector-store-file-batch-id");

foreach (var file in files.Items)
{
    Debug.Log(file);
}

取消向量存储文件批次

取消向量存储文件批次。这会尽快尝试取消该批次中文件的处理。

var api = new OpenAIClient();
var isCancelled = await api.VectorStoresEndpoint.CancelVectorStoreFileBatchAsync("vector-store-id", "vector-store-file-batch-id");

---

聊天

给定一次聊天对话，模型将返回一个聊天完成响应。

聊天 API 通过 OpenAIClient.ChatEndpoint 访问。

聊天完成

为聊天消息创建完成。

var api = new OpenAIClient();
var messages = new List<Message>
{
    new Message(Role.System, "你是一个有用的助手。"),
    new Message(Role.User, "2020年的世界大赛是谁赢的？"),
    new Message(Role.Assistant, "洛杉矶道奇队在2020年赢得了世界大赛。"),
    new Message(Role.User, "比赛是在哪里举行的？"),
};
var chatRequest = new ChatRequest(messages, Model.GPT4o);
var response = await api.ChatEndpoint.GetCompletionAsync(chatRequest);
var choice = response.FirstChoice;
Debug.Log($"[{choice.Index}] {choice.Message.Role}: {choice.Message} | 结束原因: {choice.FinishReason}");

聊天流式传输

var api = new OpenAIClient();
var messages = new List<Message>
{
    new Message(Role.System, "你是一个有用的助手。"),
    new Message(Role.User, "2020年的世界大赛是谁赢的？"),
    new Message(Role.Assistant, "洛杉矶道奇队在2020年赢得了世界大赛。"),
    new Message(Role.User, "比赛是在哪里举行的？"),
};
var chatRequest = new ChatRequest(messages);
var response = await api.ChatEndpoint.StreamCompletionAsync(chatRequest, async partialResponse =>
{
    Debug.Log(partialResponse.FirstChoice.Delta.ToString());
    await Task.CompletedTask;
});
var choice = response.FirstChoice;
Debug.Log($"[{choice.Index}] {choice.Message.Role}: {choice.Message} | 结束原因: {choice.FinishReason}");

聊天工具

var api = new OpenAIClient();
var messages = new List<Message>
{
    new(Message.Role.System, "你是一个有用的天气助手。始终提示用户他们的位置。"),
    new Message(Role.User, "今天天气怎么样？"),
};

foreach (var message in messages)
{
    Debug.Log($"{message.Role}: {message}");
}

// 定义助手可以使用的工具：
// 1. 获取所有用 FunctionAttribute 装饰的静态方法列表
var tools = Tool.GetAllAvailableTools(includeDefaults: false, forceUpdate: true, clearCache: true);
// 2. 定义自定义工具列表：
var tools = new List<Tool>
{
    Tool.GetOrCreateTool(objectInstance, "要调用的方法名称"),
    Tool.FromFunc("你函数的自定义名称", ()=> { /* 某些逻辑要执行 */ })
};
var chatRequest = new ChatRequest(messages, 工具: tools, 工具选择: "auto");
var response = await api.ChatEndpoint.GetCompletionAsync(chatRequest);
messages.Add(response.FirstChoice.Message);

Debug.Log($"{response.FirstChoice.Message.Role}: {response.FirstChoice} | 结束原因: {response.FirstChoice.FinishReason}");

var locationMessage = new Message(Role.User, "我在苏格兰的格拉斯哥");
messages.Add(locationMessage);
Debug.Log($"{locationMessage.Role}: {locationMessage.Content}");
chatRequest = new ChatRequest(messages, tools: tools, toolChoice: "auto");
response = await api.ChatEndpoint.GetCompletionAsync(chatRequest);

messages.Add(response.FirstChoice.Message);

if (response.FirstChoice.FinishReason == "stop")
{
    Debug.Log($"{response.FirstChoice.Message.Role}: {response.FirstChoice} | 结束原因: {response.FirstChoice.FinishReason}");

    var unitMessage = new Message(Role.User, "华氏度");
    messages.Add(unitMessage);
    Debug.Log($"{unitMessage.Role}: {unitMessage.Content}");
    chatRequest = new ChatRequest(messages, tools: tools, toolChoice: "auto");
    response = await api.ChatEndpoint.GetCompletionAsync(chatRequest);
}

// 遍历所有工具调用并执行它们
foreach (var toolCall in response.FirstChoice.Message.ToolCalls)
{
    Debug.Log($"{response.FirstChoice.Message.Role}: {toolCall.Function.Name} | 结束原因: {response.FirstChoice.FinishReason}");
    Debug.Log($"{toolCall.Function.Arguments}");
    // 调用函数以获取通用的 JSON 结果作为工具调用的返回值。
    var functionResult = await toolCall.InvokeFunctionAsync();
    // 如果你知道返回类型并需要进行额外处理，可以使用泛型重载版本。
    var functionResult = await toolCall.InvokeFunctionAsync<string>();
    messages.Add(new Message(toolCall, functionResult));
    Debug.Log($"{Role.Tool}: {functionResult}");
}
// 系统：你是一个有用的天气助手。
// 用户：今天天气怎么样？
// 助手：当然，请问您目前的位置是哪里？| 结束原因：stop
// 用户：我在苏格兰的格拉斯哥
// 助手：GetCurrentWeather | 结束原因：tool_calls
// {
//   "location": "Glasgow, Scotland",
//   "unit": "celsius"
// }
// 工具：苏格兰格拉斯哥当前的气温为39°C。

视觉聊天

[!WARNING] 测试功能。API 可能会随时发生变化。

var api = new OpenAIClient();
var messages = new List<Message>
{
    new Message(Role.System, "你是一个有用的助手。"),
    new Message(Role.User, new List<Content>
    {
        "这张图片里有什么？",
        new ImageUrl("https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg", ImageDetail.Low)
    })
};
var chatRequest = new ChatRequest(messages, model: Model.GPT4o);
var response = await api.ChatEndpoint.GetCompletionAsync(chatRequest);
Debug.Log($"{response.FirstChoice.Message.Role}: {response.FirstChoice.Message.Content} | 结束原因: {response.FirstChoice.FinishDetails}");

你甚至可以直接传入一个 Texture2D！

var api = new OpenAIClient();
var messages = new List<Message>
{
    new Message(Role.System, "你是一个有用的助手。"),
    new Message(Role.User, new List<Content>
    {
        "这张图片里有什么？",
        texture
    })
};
var chatRequest = new ChatRequest(messages, model: Model.GPT4o);
var result = await api.ChatEndpoint.GetCompletionAsync(chatRequest);
Debug.Log($"{result.FirstChoice.Message.Role}: {result.FirstChoice} | 结束原因: {result.FirstChoice.FinishDetails}");

音频聊天

var api = new OpenAIClient();
var messages = new List<Message>
{
    new Message(Role.System, "你是一个有用的助手。"),
    new Message(Role.User, "金毛寻回犬适合作为家庭宠物吗？")
};
var chatRequest = new ChatRequest(messages, Model.GPT4oAudio, audioConfig: Voice.Alloy);
var response = await api.ChatEndpoint.GetCompletionAsync(chatRequest);
Debug.Log($"{response.FirstChoice.Message.Role}: {response.FirstChoice} | 结束原因: {response.FirstChoice.FinishDetails}");
audioSource.PlayOneShot(response.FirstChoice.Message.AudioOutput.AudioClip);

结构化输出聊天

这是 JSON 模式 的进一步发展。虽然两者都能确保生成有效的 JSON，但只有结构化输出才能保证符合预定义的模式。

[!IMPORTANT]

• 使用 JSON 模式时，务必在对话中通过某条消息明确指示模型生成 JSON，例如通过系统提示语。如果不包含明确的 JSON 生成指令，模型可能会持续输出空白字符，请求将一直运行直到达到令牌上限。为了防止这种情况发生，API 会在上下文中未出现“JSON”字样时抛出错误。
• 如果 finish_reason 是 length，则模型返回的消息中的 JSON 可能是不完整的（即被截断），这表明生成内容超出了最大令牌数或对话已超过令牌限制。为避免此问题，在解析响应之前请检查 finish_reason。

首先定义你的响应结构。这些将作为你的模式使用。 这些是你将反序列化的目标对象，因此请确保使用标准的 JSON 对象模型。

public class MathResponse
{
    [JsonProperty("steps")]
    public IReadOnlyList<MathStep> Steps { get; private set; }

    [JsonProperty("final_answer")]
    public string FinalAnswer { get; private set; }
}

public class MathStep
{
    [JsonProperty("explanation")]
    public string Explanation { get; private set; }

    [JsonProperty("output")]
    public string Output { get; private set; }
}

使用时，只需在请求完成时指定 MathResponse 类型作为泛型约束即可。

var api = new OpenAIClient();
var messages = new List<Message>
{
    new(Message.Role.System, "你是一位有用的教学助理。请逐步引导用户解决问题。"),
    new(Message.Role.User, "如何解方程 8x + 7 = -23")
};

var chatRequest = new ChatRequest(messages, model: "gpt-4o-2024-08-06");
var (mathResponse, chatResponse) = await api.ChatEndpoint.GetCompletionAsync<MathResponse>(chatRequest);

for (int i = 0; i < mathResponse.Steps.Count; i++)
{
    var step = mathResponse.Steps[i];
    Debug.Log($"第 {i} 步：{step.Explanation}");
    Debug.Log($"结果：{step.Output}");
}

Debug.Log($"最终答案：{mathResponse.FinalAnswer}");
chatResponse.GetUsage();

JSON 模式聊天

[!IMPORTANT]

• 使用 JSON 模式时，务必通过对话中的某条消息（例如系统消息）指示模型生成 JSON。如果不包含明确的 JSON 生成指令，模型可能会生成无休止的空白字符流，请求将持续运行直到达到令牌限制。为避免这种情况，如果上下文中未出现字符串“JSON”，API 将抛出错误。
• 如果 finish_reason 为 length，则模型返回的消息中的 JSON 可能是不完整的（即被截断），这表示生成内容超出了 max_tokens 或对话的令牌限制。为防止这种情况，在解析响应之前，请检查 finish_reason。
• JSON 模式不会保证输出符合任何特定模式，仅保证其有效且可无错误地解析。

var messages = new List<Message>
{
    new Message(Role.System, "你是一个旨在输出 JSON 的助手。"),
    new Message(Role.User, "2020 年世界大赛是谁赢了？"),
};
var chatRequest = new ChatRequest(messages, Model.GPT4o, responseFormat: ChatResponseFormat.Json);
var response = await api.ChatEndpoint.GetCompletionAsync(chatRequest);

foreach (var choice in response.Choices)
{
    Debug.Log($"[{choice.Index}] {choice.Message.Role}: {choice} | 结束原因: {choice.FinishReason}");
}

response.GetUsage();

---

音频

将音频转换为文本。

音频 API 通过 OpenAIClient.AudioEndpoint 访问。

创建语音

根据输入文本生成音频。

var api = new OpenAIClient();
var request = new SpeechRequest("你好，世界！");
var speechClip = await api.AudioEndpoint.GetSpeechAsync(request);
audioSource.PlayOneShot(speechClip);
Debug.Log(speechClip);

[流式语音]

根据输入文本生成流式音频。

var api = new OpenAIClient();
var request = new SpeechRequest("你好，世界！", responseFormat: SpeechResponseFormat.PCM);
var speechClip = await api.AudioEndpoint.GetSpeechAsync(request, partialClip =>
{
    audioSource.PlayOneShot(partialClip);
});
Debug.Log(speechClip);

[!NOTE] 请查看任何演示场景，以了解如何使用 OnAudioFilterRead 处理播放的最佳实践。

创建转录

将音频转录为输入语言。

var api = new OpenAIClient();
var request = new AudioTranscriptionRequest(audioClip, language: "en");
var result = await api.AudioEndpoint.CreateTranscriptionAsync(request);
Debug.Log(result);

您还可以使用 verbose_json 获取更详细的带时间戳信息：

var api = new OpenAIClient();
using var request = new AudioTranscriptionRequest(transcriptionAudio, responseFormat: AudioResponseFormat.Verbose_Json, timestampGranularity: TimestampGranularity.Word, temperature: 0.1f, language: "en");
var response = await api.AudioEndpoint.CreateTranscriptionTextAsync(request);

foreach (var word in response.Words)
{
    Debug.Log($"[{word.Start}-{word.End}] \"{word.Word}\"");
}

创建翻译

将音频翻译成英语。

var api = new OpenAIClient();
var request = new AudioTranslationRequest(audioClip);
var result = await api.AudioEndpoint.CreateTranslationAsync(request);
Debug.Log(result);

---

图片

根据提示和/或输入图像，模型会生成一张新图像。

图片 API 通过 OpenAIClient.ImagesEndpoint 访问。

创建图像

根据提示创建图像。

var api = new OpenAIClient();
var request = new ImageGenerationRequest("一只骑着迅猛龙的房子", Models.Model.DallE_3);
var imageResults = await api.ImagesEndPoint.GenerateImageAsync(request);

foreach (var result in imageResults)
{
    Debug.Log(result.ToString());
    Assert.IsNotNull(result.Texture);
}

编辑图像

根据原始图像和提示创建编辑或扩展后的图像。

var api = new OpenAIClient();
var request = new ImageEditRequest(Path.GetFullPath(imageAssetPath), Path.GetFullPath(maskAssetPath), "一个阳光明媚的室内休息区，池塘里有一只火烈鸟", size: ImageSize.Small);
var imageResults = await api.ImagesEndPoint.CreateImageEditAsync(request);

foreach (var result in imageResults)
{
    Debug.Log(result.ToString());
    Assert.IsNotNull(result.Texture);
}

创建图像变体

根据给定图像创建变体。

var api = new OpenAIClient();
var request = new ImageVariationRequest(imageTexture, size: ImageSize.Small);
var imageResults = await api.ImagesEndPoint.CreateImageVariationAsync(request);

foreach (var result in imageResults)
{
    Debug.Log(result.ToString());
    Assert.IsNotNull(result.Texture);
}

或者，该端点可以直接接受启用了读写权限且压缩设置为“无”的 Texture2D。

var api = new OpenAIClient();
var request = new ImageVariationRequest(imageTexture, size: ImageSize.Small);
var imageResults = await api.ImagesEndPoint.CreateImageVariationAsync(request);

foreach (var result in imageResults)
{
    Debug.Log(result.ToString());
    Assert.IsNotNull(result.Texture);
}

---

文件

文件用于上传文档，这些文档可以与诸如微调等功能一起使用。

文件 API 通过 OpenAIClient.FilesEndpoint 访问。

列出文件

返回属于用户组织的文件列表。

var api = new OpenAIClient();
var fileList = await api.FilesEndpoint.ListFilesAsync();

foreach (var file in fileList)
{
    Debug.Log($"{file.Id} -> {file.Object}: {file.FileName} | {file.Size} bytes");
}

上传文件

上传可在多个端点使用的文件。单个组织上传的所有文件大小上限为 100 GB。

单个文件的最大大小为 512 MB。有关支持的文件类型，请参阅助手工具指南。微调 API 仅支持 .jsonl 文件。

var api = new OpenAIClient();
var file = await api.FilesEndpoint.UploadFileAsync("path/to/your/file.jsonl", FilePurpose.FineTune);
Debug.Log(file.Id);

删除文件

删除文件。

var api = new OpenAIClient();
var isDeleted = await api.FilesEndpoint.DeleteFileAsync(fileId);
Assert.IsTrue(isDeleted);

获取文件信息

返回特定文件的信息。

var api = new OpenAIClient();
var file = await api.FilesEndpoint.GetFileInfoAsync(fileId);
Debug.Log($"{file.Id} -> {file.Object}: {file.FileName} | {file.Size} bytes");

下载文件内容

将文件内容下载到指定目录。

var api = new OpenAIClient();
var downloadedFilePath = await api.FilesEndpoint.DownloadFileAsync(fileId);
Debug.Log(downloadedFilePath);
Assert.IsTrue(File.Exists(downloadedFilePath));

---

微调

管理微调任务，以根据您的特定训练数据定制模型。

相关指南：微调模型

文件 API 通过 OpenAIClient.FineTuningEndpoint 访问。

创建微调任务

从给定数据集创建一个微调指定模型的任务。

响应包括已加入队列的任务详细信息，包括任务状态以及完成后的微调模型名称。

var api = new OpenAIClient();
var fileId = "file-abc123";
var request = new CreateFineTuneRequest(fileId);
var job = await api.FineTuningEndpoint.CreateJobAsync(Model.GPT3_5_Turbo, request);
Debug.Log($"已启动 {job.Id} | 状态: {job.Status}");

列出微调任务

列出您组织的微调任务。

var api = new OpenAIClient();
var jobList = await api.FineTuningEndpoint.ListJobsAsync();

foreach (var job in jobList.Items.OrderByDescending(job => job.CreatedAt))
{
    Debug.Log($"{job.Id} -> {job.CreatedAt} | {job.Status}");
}

获取微调任务信息

获取微调任务的信息。

var api = new OpenAIClient();
var job = await api.FineTuningEndpoint.GetJobInfoAsync(fineTuneJob);
Debug.Log($"{job.Id} -> {job.CreatedAt} | {job.Status}");

取消微调任务

立即取消微调任务。

var api = new OpenAIClient();
var isCancelled = await api.FineTuningEndpoint.CancelFineTuneJobAsync(fineTuneJob);
Assert.IsTrue(isCancelled);

列出微调任务事件

获取微调任务的状态更新。

var api = new OpenAIClient();
var eventList = await api.FineTuningEndpoint.ListJobEventsAsync(fineTuneJob);
Debug.Log(`${fineTuneJob.Id} -> 状态: ${fineTuneJob.Status} | 事件数量: ${eventList.Events.Count}`);

foreach (var @event in eventList.Items.OrderByDescending(@event => @event.CreatedAt))
{
    Debug.Log($"  {@event.CreatedAt} [{@event.Level}] {@event.Message}");
}

---

批处理

创建大量异步处理的 API 请求批次。批处理 API 可在 24 小时内返回结果，并享受 50% 的折扣。

• 批处理指南

批处理 API 通过 OpenAIClient.BatchesEndpoint 访问。

列出批处理

列出您组织的批处理。

var api = new OpenAIClient();
var batches = await api.BatchEndpoint.ListBatchesAsync();

foreach (var batch in listResponse.Items)
{
    Debug.Log(batch);
}

创建批处理

从上传的请求文件创建并执行批处理。

var api = new OpenAIClient();
var batchRequest = new CreateBatchRequest("file-id", Endpoint.ChatCompletions);
var batch = await api.BatchEndpoint.CreateBatchAsync(batchRequest);

获取批处理

获取批处理。

var api = new OpenAIClient();
var batch = await api.BatchEndpoint.RetrieveBatchAsync("batch-id");
// 您也可以使用便捷方法！
batch = await batch.UpdateAsync();
batch = await batch.WaitForStatusChangeAsync();

取消批处理

取消正在进行的批处理。批处理将在“取消中”状态持续最多 10 分钟，随后变为“已取消”，此时输出文件中将包含部分结果（如有）。

var api = new OpenAIClient();
var isCancelled = await api.BatchEndpoint.CancelBatchAsync(batch);
Assert.IsTrue(isCancelled);

---

嵌入

获取给定输入的向量表示，该表示可被机器学习模型和算法轻松使用。

相关指南：嵌入

嵌入 API 通过 OpenAIClient.EmbeddingsEndpoint 访问。

创建嵌入

创建表示输入文本的嵌入向量。

var api = new OpenAIClient();
var response = await api.EmbeddingsEndpoint.CreateEmbeddingAsync("食物非常美味，服务员……", Models.Embedding_Ada_002);
Debug.Log(response);

---

内容审核

给定一段输入文本，该模型会输出该文本是否违反 OpenAI 的内容政策。

相关指南：内容审核

可以通过 OpenAIClient.ModerationsEndpoint 访问内容审核 API。

创建内容审核

判断文本是否违反 OpenAI 的内容政策。

var api = new OpenAIClient();
var isViolation = await api.ModerationsEndpoint.GetModerationAsync("我想杀了他们。");
Assert.IsTrue(isViolation);

此外，你还可以获取给定输入的各项评分。

var api = new OpenAIClient();
var response = await api.ModerationsEndpoint.CreateModerationAsync(new ModerationsRequest("我爱你"));
Assert.IsNotNull(response);
Debug.Log(response.Results?[0]?.Scores?.ToString());

---

com.openai.unity 快速上手指南

环境准备

• Unity 版本：要求 Unity 2021.3 LTS 或更高版本。
• 前置依赖：需要拥有 OpenAI API 账户及有效的 API Key。
• 网络环境：由于 OpenAI 服务在中国大陆地区可能无法直接访问，建议配置代理或使用国内中转服务（如有）。

安装步骤

推荐使用 OpenUPM 进行安装，这是最简便且能自动处理依赖的方式。

方法一：通过终端命令安装（推荐）

在 Unity 项目根目录下打开终端，执行以下命令：

openupm add com.openai.unity

方法二：通过 Unity Package Manager 手动添加

如果未安装 openupm-cli，可在 Unity 编辑器中手动配置：

1. 打开 Edit > Project Settings > Package Manager。
2. 添加新的 Scoped Registry：
   • Name: OpenUPM
   • URL: https://package.openupm.com
   • Scope(s):
     • com.openai
     • com.utilities
3. 打开 Window > Package Manager。
4. 将左上角下拉菜单从 "Unity Registry" 切换为 "My Registries"。
5. 在列表中找到 OpenAI 包并点击 Install。

注意：若选择通过 Git URL 安装，需手动额外安装以下依赖包：com.utilities.async, com.utilities.websockets, com.utilities.extensions, com.utilities.rest, com.utilities.audio, com.utilities.encoder.wav。

基本使用

1. 认证配置

为了安全起见，不建议将 API Key 硬编码在代码中。推荐以下两种方式之一：

方式 A：使用环境变量（推荐用于本地测试）

在系统环境中设置以下变量：

• OPENAI_API_KEY: 你的 API Key
• OPENAI_ORGANIZATION_ID: (可选) 组织 ID
• OPENAI_PROJECT_ID: (可选) 项目 ID

代码初始化：

var api = new OpenAIClient(new OpenAIAuthentication().LoadFromEnvironment());

方式 B：使用配置文件

在项目根目录或用户主目录下创建名为 .openai 的文件，内容如下（JSON 格式）：

{
  "apiKey": "sk-aaaabbbbbccccddddd",
  "organizationId": "org-yourOrganizationId",
  "projectId": "proj_yourProjectId"
}

代码初始化：

var api = new OpenAIClient(); // 会自动加载默认配置文件

2. 调用聊天接口示例

以下是一个最简单的发送消息并获取回复的示例：

using System;
using OpenAI;
using OpenAI.Chat;

public class ChatExample : MonoBehaviour
{
    async void Start()
    {
        // 初始化客户端
        var api = new OpenAIClient(new OpenAIAuthentication().LoadFromEnvironment());
        var chatEndpoint = api.ChatEndpoint;

        // 构建对话请求
        var conversation = new ChatRequest(
            messages: new[] {
                new Message(Role.System, "You are a helpful assistant."),
                new Message(Role.User, "Hello, who are you?")
            },
            model: "gpt-3.5-turbo"
        );

        try
        {
            // 发送请求并获取结果
            var response = await chatEndpoint.GetCompletionAsync(conversation);
            
            if (response.Choices != null && response.Choices.Length > 0)
            {
                Debug.Log($"AI 回复：{response.FirstChoice.Message.Content}");
            }
        }
        catch (Exception e)
        {
            Debug.LogError($"请求失败：{e.Message}");
        }
    }
}

3. 流式输出示例（Streaming）

如果需要实现打字机效果，可以使用流式接口：

var response = await chatEndpoint.StreamCompletionAsync(conversation);

await foreach (var update in response)
{
    if (update.Choices != null && update.Choices.Length > 0)
    {
        string delta = update.FirstChoice.Delta.Content;
        if (!string.IsNullOrEmpty(delta))
        {
            Debug.Log(delta); // 逐字输出
        }
    }
}