OpenAI-DotNet 库中获取嵌入生成时的令牌使用情况

概述

在使用 OpenAI 的嵌入功能时，开发者经常需要了解 API 调用消耗的令牌数量，这对于成本控制和用量监控非常重要。OpenAI-DotNet 库提供了两种不同的方法来生成嵌入，但只有其中一种方法会返回令牌使用信息。

两种嵌入生成方法的区别

OpenAI-DotNet 库提供了两种生成嵌入的方法：

1. GenerateEmbedding（单数形式）：这是一个便捷方法，返回单个 Embedding 对象，但不包含令牌使用信息。

2. GenerateEmbeddings（复数形式）：这个方法更接近 REST API 的原始设计，返回一个 EmbeddingCollection 对象，其中包含了 Usage 属性，可以获取详细的令牌使用情况。

为什么设计两种方法

这种设计源于 OpenAI REST API 的原始设计。在 REST API 中，使用信息（usage）是作为整个响应的一部分返回的，而不是针对每个单独的嵌入。GenerateEmbeddings 方法更忠实地反映了 API 的这一设计，而 GenerateEmbedding 方法则是为了简化常见场景而添加的便捷方法。

如何正确获取令牌使用信息

要获取嵌入生成时的令牌使用情况，开发者应该使用 GenerateEmbeddings 方法。以下是一个典型的使用示例：

EmbeddingClient client = new(embeddingModel, apiKey);
EmbeddingCollection embeddings = await client.GenerateEmbeddingsAsync(text);

// 获取使用信息
EmbeddingTokenUsage usage = embeddings.Usage;
int totalTokens = usage.TotalTokens;
int promptTokens = usage.PromptTokens;

技术实现细节

在底层实现上，GenerateEmbeddings 方法会返回完整的 API 响应，包括：

• 生成的嵌入向量列表
• 模型信息
• 使用统计（令牌数）

而 GenerateEmbedding 方法则只提取响应中的第一个嵌入向量返回给调用者，丢弃了其他元数据信息。

最佳实践建议

1. 如果需要监控令牌使用情况，务必使用 GenerateEmbeddings 方法
2. 在只需要单个嵌入且不关心使用统计的简单场景中，可以使用 GenerateEmbedding 方法简化代码
3. 考虑在应用程序中统一使用 GenerateEmbeddings 方法以保持一致性

总结

OpenAI-DotNet 库通过提供两种不同粒度的方法来满足不同场景的需求。理解这两种方法的区别对于正确获取嵌入生成时的令牌使用信息至关重要。开发者应根据具体需求选择合适的方法，在需要用量监控时使用 GenerateEmbeddings 方法来获取完整的使用统计信息。