AI 使用情况分析 API 为开发人员提供了一种编程方式来回答普通提供商仪表板很少能完全回答的问题：哪个 API 键、模型、客户、工作流程、功能或团队推动了使用和成本？应该向客户或项目分配多少资金？哪些记录可以导出到仓库、仪表板、财务系统或经销商门户中？这些数字是否与提供商成本 API、网关记录、付款记录和发票一致？

对于单个原型，提供商仪表板可能就足够了。对于使用多个 LLM、托管工具、流响应、图像或音频端点、批处理作业和客户特定的 API 键的生产应用程序，使用情况报告成为数据产品。它需要稳定的标识符、规范化的使用单位、价格上下文、访问控制、导出语义以及分析数据和计费真相之间的清晰界限。

本指南介绍了 AI 使用情况分析 API 应公开的内容、它与仪表板、发票、可观察性跟踪和帐单分类账有何不同，以及如何针对 LLM 成本分析、AI API 使用情况导出、按模型进行支出分析和退款进行设计。 Model Gate 与此工作流程相关，因为它是一个 OpenAI 兼容的多模型 API 网关，具有统一计费、API-密钥管理、使用情况分析、团队控制、Telegram 集成以及用于在网关上构建服务的合作伙伴 API。如果网关已位于应用程序和模型提供商之间，则它可以成为归因和规范化使用数据的重要来源。

AI 使用情况分析 API 是什么

AI 使用情况分析 API 是一个面向读取的接口，用于查询和导出 AI 消费数据。它通常会回答多个维度的问题：时间、模型、提供商、端点、API 键、用户、团队、客户、租户、项目、工作流程、环境、区域、服务层和使用类型。

API 可能会公开原始请求记录、聚合摘要或两者。请求级记录可能描述一次聊天完成、图像生成、嵌入调用、转录、文件搜索调用或托管工具会话。聚合端点可能会按天和模型汇总总输入令牌、输出令牌、缓存令牌、请求、错误、图像、音频秒数或估计成本。

最有用的系统将使用单位与金钱分开。令牌、图像、音频秒、向量存储字节、代码解释器会话、工具调用、文件搜索调用和 Web 搜索调用都可以携带不同的计费语义。然后，成本报告将价格目录、货币、折扣或加价政策、发票期限和结算状态应用于这些使用单位。

为什么信息中心、发票和跟踪还不够

信息中心针对人类进行了优化。它对于检查和趋势发现很有用，但对于自动化来说却远远不够。仪表板可能不会公开客户分配所需的每个维度，可能会使用固定分组，并且可能无法安全重播地导出到您自己的仓库中。

发票针对付款和合法会计进行了优化。它可能对您所欠的金额具有权威性，但通常缺乏应用程序级别的详细信息。如果发票上显示某个提供商模型上个月花费了 742 美元，则它可能不会显示哪个客户、API 键、功能、环境或工作流程导致了支出。

可观测性跟踪针对调试和延迟分析进行了优化。它们可以捕获模型调用、跨度、令牌计数和错误，但它们不会自动计费记录。例如，OpenTelemetry GenAI 约定将计费令牌计数与模型消耗的令牌计数区分开来，并建议在两者都可用时报告计费计数。这种区别很重要，因为用于成本分配的分析应与费用保持一致，而不仅仅是与内部执行细节保持一致。

帐单分类帐针对财务状态进行了优化。它记录贷项、借项、付款、余额、发票、调整、税收、折扣、退款或经销商利润。使用情况分析 API 可以提供帐单分类帐，但不应将其与帐单分类帐混淆。分析解释消费；计费决定欠款、收取、贷记或开具发票。

LLM 成本分析的核心数据模型

持久的 LLM 成本分析 API 从请求级使用分类账开始。即使大多数用户查询聚合，请求记录也会保留协调、退款和事件审核所需的归因和生命周期详细信息。

身份和归因字段

每个使用记录都应携带稳定的标识符，能够在重试、导出和系统迁移后继续存在。常见字段包括请求 ID、提供商请求 ID（如果可用）、网关请求 ID、API 密钥 ID、帐户 ID、团队 ID、用户 ID、客户或租户 ID、项目 ID、工作流程 ID、环境和关联 ID。

最重要的设计选择是决定由哪个参与者承担费用。 API-key 归因很简单，通常非常适合个人开发者、代理机构和内部团队。客户级退款需要更强的身份传播。工作流级单元经济性需要应用层的一致标记。如果没有标记规则，分析 API 只能按其实际收到的内容进行分组。

对于基于密钥的归因，当 API-密钥管理和支出报告一起设计时，分析效果最佳。支持密钥级身份的网关可以更轻松地将使用情况分析与LLM API密钥支出限制、配额执行和每个客户报告等控件连接起来。

模型、提供商和端点字段

模型分析应保留公共模型别名和已解析的提供商模型。产品可能会调用通用别名，例如快速聊天模型，而网关出于价格、可用性或政策原因路由到特定的提供商模型。如果分析记录仅保留别名，则以后的发票核对将变得困难。如果仅保留提供程序模型，则产品级分析会变得更加困难。

有用的记录包括提供程序、端点、模型别名、解析模型、模型版本（如果可用）、模式、区域、服务层、路由策略、回退状态，以及调用是否使用流式处理、批处理、异步处理、托管工具或多模式输入。

使用单位字段

不要将 AI 使用量减少到单个令牌柜台。成熟的分析架构可将输入令牌、输出令牌、缓存输入令牌、缓存写入令牌、推理令牌、嵌入令牌、图像计数、图像大小、音频秒数、视频秒数、文件搜索调用、网络搜索调用、向量存储字节、代码执行会话和批处理项（当这些单位很重要时）分开。

提供商原生 API 已经说明了为什么需要这种广度。 OpenAI 跨维度公开组织使用情况和费用报告，例如项目、用户、API 键、模型、订单项、API 来源和特定模式的使用情况。 Anthropic 通过过滤器和分组（例如模型、API 关键 ID、工作区 ID、服务层、上下文窗口、推理地理位置和速度）记录使用情况和成本报告。云计费导出可以添加另一层 SKU、项目、预订和资源元数据。跨提供商分析 API 应规范通用字段，而不丢弃特定于提供商的详细信息。

成本字段

成本字段应明确说明状态和计算。将使用单位与估计成本、结算成本、发票成本、货币、价格目录版本、加价或折扣政策、发票期间和结算时间戳分开存储。货币应使用小数字符串或固定精度小数，而不是浮点值。

这可以防止提供商更新价格时历史报告的含义发生变化。它还可以让您解释为什么实时预算决策与最终发票不同。流式响应可能会提前终止，工具调用可能会在初始响应后增加使用量，或者重试可能会产生应用程序未预期的提供商端成本。

聚合 API 与详细导出

AI 使用情况分析 API 通常需要两个界面：聚合端点和详细导出。

聚合端点针对仪表板和快速决策进行了优化。他们回答诸如过去 30 天按模型划分的总成本、按 API 键划分的每日令牌、按端点划分的错误率或按客户本周的支出等问题。它们应支持常见的分组依据维度、日期存储桶、过滤器和基数较高的分页。

详细信息导出针对仓库、退款、审核和对帐进行了优化。它们提供行级或请求级数据，具有稳定的排序、不可变的事件 ID、游标、updated_at 水印和重放安全分页。良好的 AI API 使用情况导出可以重复摄取，而不会重复收费或丢失更正。

两个表面应该一致，但它们不必由相同的存储路径支持。聚合可能来自预先计算的速度汇总。为了完整性，导出可以从仅附加分类帐或分析仓库中读取。重要的是记录语义：时区、存储桶边界、状态包含、迟到记录、货币以及是否估算或结算成本。

按模型进行使用情况分析

按模型进行 AI 支出分析是团队要求的首要报告之一，但很容易实施不佳。仅模型报告可以显示一个提供程序模型的成本很高，但它可能隐藏了一个事实：单个工作流程、租户或 API 键负责。

模型级报告应支持至少三个视图。首先，显示产品别名，以便构建者可以了解哪些应用程序配置正在推动使用。其次，显示已解决的提供商模型，以便财务和工程部门可以协调提供商费用。第三，显示模型随时间的变化，以便迁移、回退和路由策略不会模糊数字。

对于多模型应用程序，这就是网关数据变得特别有用的地方。 Model Gate 的 OpenAI 兼容多模型网关设计意味着使用可以与网关级 API 密钥和模型路由上下文相关联，同时仍然保持提供者的来源。其统一结算功能还使分析讨论与统一 AI API 结算 相邻，其中多个模型提供商通过更加集中的商业层进行支付。

退款和展示的使用数据

退款的 AI 使用数据将成本分配给导致成本的客户、团队、项目、经销商、功能或成本中心。 Showback 报告分配情况而不收钱。退款通常会导致实际发票、内部转账、客户余额或经销商对帐单。

核心要求是分配保真度。如果您的应用程序通过一个后端密钥为多个客户提供服务，则仅通过 API 键进行提供商报告是不够的。您需要将客户或租户标识符传递到网关、分类帐或分析管道中。如果您需要功能级别的盈利能力，则需要工作流程或功能标签。如果您需要最终用户报告，则需要用户 ID 以及可供查询的隐私模型。

财务友好型导出通常将 AI 使用情况映射到分配列，例如客户、产品、环境、所有者、工作负载、区域、成本中心、发票周期和单位经济指标。FinOps 开放成本和使用规范可作为参考点，因为它定义了用于分配、基准测试、预算、预测和相关实践的成本和使用数据集。 AI 工作负载仍然需要模型、令牌、缓存行为、工具和模式的扩展字段。

合作伙伴和经销商场景添加了另一层。构建在网关之上的服务可能需要向下游客户公开使用情况，同时在内部保留上游提供商的详细信息。在这些情况下，分析导出和合作伙伴API自动化应共享相同的身份和分配模型，以便经销商报表、客户仪表板和运营报告不会发生偏差。

提供商原生 API、网关分类账和仓库

AI 使用数据有四种常见来源，每种来源都有权衡。

提供商原生使用 API 对此具有权威性提供商对使用和成本的看法。它们对于协调很重要，但它们可能会使用特定于提供商的维度、延迟可用性、不同的时间段和有限的应用程序级别上下文。他们可能知道提供商 API 键，但不知道您的客户、工作流程、内部项目或经销商。

网关拥有的请求分类帐捕获最接近您的应用程序的上下文。他们可以在调度之前记录网关 API 键、模型别名、路由提供商、客户 ID、团队 ID 和相关 ID。它们还可以捕获失败、重试、流状态和部分使用情况。风险在于网关估算必须与提供商结算的成本保持一致。

帐单分类帐跟踪余额、付款、贷项、发票、调整和商业政策。只有在应用明确的定价和结算规则后，他们才应收取基于使用量的费用。将原始使用记录直接混合到结算状态中会使审核变得更加困难。

仓库将这些来源结合起来。持久架构存储标准化网关记录、原始提供商使用详细信息、提供商成本导出、云计费导出、付款记录和发票记录。然后，分析 API 可以公开快速汇总，而详细信息导出则为审核和对账提供足够的来源。

生命周期状态：估计、最终、结算和开具发票

在请求开始时并不总是知道 AI 的使用情况。预算检查可能会使用估算值。在连接关闭之前，流式调用可能会产生部分使用。异步图像或批处理作业可能会稍后完成。托管工具可能会在初始模型调用后生成额外的计费单位。提供商成本 API 可能会在延迟后更新。云发票可能会以不同的粒度进行结算。

因此，分析记录应保留生命周期状态，而不是覆盖历史记录。有用的状态包括估计、部分、最终、provider_reported、调整、已结算、已开具发票、已取消、失败和未知。确切的词汇可能有所不同，但 API 应该能够区分决策时已知的内容和后来计费的内容。

这对于预算执行尤其重要。实时成本估算有助于决定是否分派请求，但最终成本可能会因缓存令牌、重试、提供者端记账、工具调用或流终止而有所不同。保留估计结果和最终结果的分析API可以解释这些差异。

分页和导出设计

导出应设计为自动化，而不是手动下载。对于大容量、不断变化的数据集，Cursor 分页通常比偏移分页更安全。记录应具有稳定的排序、不可变的事件 ID、created_at 和 updated_at 时间戳以及用于增量同步的水印。

良好的导出端点支持幂等摄取。如果客户端在超时后重复请求，则不应在下游创建重复请求。如果迟到的使用更改了记录，updated_at 水印应允许仓库拾取它。如果记录是不可变事件而不是可变行，则调整应表示为引用原始使用记录的新事件。

时间过滤器应定义它们是否应用于请求开始、请求结束、提供商结算、发票周期或记录更新时间。这些差异很重要。 12 月的请求可能会在一月得到解决。云账单导出可能会反映全天的使用情况，但会在稍后完成。提供商调整可能会更新历史成本。

隐私和访问控制

大多数分析问题都可以通过元数据来回答。默认情况下存储提示和输出内容会增加隐私、保留和访问控制风险，而不会改善成本报告。仅元数据分析通常应为默认设置：标识符、时间戳、模型、令牌计数、模式、状态和成本字段。

如果调试或质量审核需要提示或输出内容，则应通过显式保留、权限、编辑和审核日志记录对其进行单独管理。分析 API 通常为财务、运营、客户成功、工程和经销商用户提供服务；并非所有人都应该看到敏感内容。

访问控制应遵循读者的边界。团队成员只能看到他们的团队。客户只能看到他们的租户。经销商可能只能看到他们管理的下游帐户。 API 密钥所有者只能看到该密钥。管理员可能需要跨帐户报告，但广泛的访问权限应该是明确的并经过审核。

常见错误

第一个错误是将提供商信息中心视为完整的分析API。仪表板很有用，但它们通常无法在事后回答每个客户、每个工作流程或仓库导出的问题。

第二个错误是仅计算令牌。现代人工智能的使用包括缓存令牌、推理令牌、图像、音频秒、文件搜索、网络搜索、代码执行、存储、批量折扣、服务层和托管工具。仅令牌模型会低估或错误分配实际成本。

第三个错误是丢失提供商来源。规范化有助于仪表板，但应保留原始提供商字段，以应对发票争议、未来结算更改和详细对账。

第四个错误是用最终值覆盖估算值。预算决策、重试、取消、部分流和提供商调整都需要审核跟踪。

第五个错误是使用浮点货币值。使用小数字符串或固定精度小数，并在每个货币金额上保留货币。

第六个错误是弱标记。仅当密钥明确映射到所有者时，通过API密钥进行退款才是可行的。按客户、用户、工作流程或功能进行的退款要求在请求时提供这些标识符。

第七个错误是权限范围不足。与提示内容相比，使用情况分析可能看起来无害，但它可以揭示客户、工作负载、业务量、模型选择和内部成本结构。

如何评估 AI 使用情况分析API

在比较或设计 AI 使用情况分析时API，从它必须回答的问题开始。它可以按模型、提供商、端点、API 键、客户、团队、工作流程和日期存储桶显示支出吗？它可以导出仓库的行级使用情况吗？它能区分原始使用量和成本吗？它可以保留定价版本和货币吗？它可以代表流、异步作业、重试、取消和托管工具吗？它可以与提供商费用 API 和发票进行协调吗？

然后评估运营属性。它支持基于游标的分页和增量导出吗？记录重播安全吗？较晚的更新是否可见？权限边界是否明确？API 是否默认避免存储提示？特定于提供商的字段是否与标准化字段一起保留？

最后，评估它是否适合您的商业模式。个体构建者可能需要简单的关键级别报告和每月导出。 SaaS 产品可能需要客户和功能分配。代理机构或经销商可能需要下游客户报告。使用多个模型的团队可能需要跨提供商的统一可见性，同时又不失去提供商级别的可审核性。

结论

持久的 AI 使用情况分析 API 不仅仅是图表后端。报告层将模型调用连接到成本、密钥、团队、客户、工作流程、财务分配和对账。最佳实施可以保留请求级来源、公开快速聚合、将使用单位与资金分开、保留提供商详细信息，并将隐私和访问控制视为核心产品要求。

对于使用多个 LLM 提供商的团队，网关可以提供提供商仪表板通常缺乏的归因层。 Model Gate 的 OpenAI 兼容多模型网关、统一计费、API-密钥管理、使用情况分析、团队控制、Telegram 集成和合作伙伴 API 使其适合需要 LLM 实用 API 使用情况报告的构建者，而无需重新构建整个成本和分配堆栈。

实际出发点很简单：定义重要的维度、记录稳定的请求级别使用情况、保留原始提供商数据，公开汇总报告和重放安全导出，并定期进行协调。该基础可以支持今天的信息中心、明天的退款以及随着使用量的增长进行金融级 AI 成本分析。