AI API 网关的版本化定价目录：阻止突破报价和退款带来的价格漂移
提供商价格卡根据模型、令牌类别、缓存行为、工具使用、部署类型、区域和承诺容量计划而变化。网关需要一个版本化的定价目录，以便当这些价格发生变化时，报价、预订、账本、预算和退款仍然可以解释。
AI API 计费会失败。困难的部分不是将代币乘以比率。困难的部分是了解请求时哪个费率有效、哪个 SKU 与实际使用范围匹配、价格是否获得批准以及为什么客户报价与提供商发票不同。
支持多个模型、帐户、区域、缓存模式、批处理作业、托管工具和预配置部署的网关需要定价控制平面。该控制平面应提取提供商价格卡，对每个批准的费率进行版本控制，将提供商的使用情况映射到可计费 SKU，在推出前测试报价，并根据发票协调已结算的账本行。
读者问题：价格漂移比定价页面造成的影响更大
提供商定价可能因应用团队很少直接看到的维度而异：模型版本、输入令牌、缓存输入令牌、输出令牌、推理令牌、缓存写入、托管工具、批量折扣、部署类型、区域、货币和承诺容量计划。如果这些维度被扁平化为一个“每个代币成本”字段，网关最终将错误报价、预留过多预算、低于租户账单或将支出分配到错误的成本中心。
失败通常出现在以下五个位置之一：
- 预检报价：请求被接受，因为网关根据旧的或不完整的费率进行估算。
- 预算预留：租户余额使用一个目录预留，但使用另一个目录结算。
- 使用分类账：缓存的令牌、推理令牌、工具调用或批次单位作为通用总计存储，无法正确重新定价。
- 退款导出：财务部门收到租户总计，但不包含解释差异所需的提供商发票维度。
- 合作伙伴 API：下游产品公开价格，但不知道这些价格是当前价格、估算价格、已弃用价格还是已被屏蔽的价格。
定价设计中需要保留的事实
事实：公共提供商文档通常按模型和令牌类别区分定价。输入、缓存输入和输出令牌可能具有不同的速率。某些使用情况报告会公开缓存输入或推理令牌计数，这意味着网关应保留使用情况子类别，而不是仅存储令牌总数。
事实：定价并不总是纯粹的即用即付代币。一些提供商出售承诺容量、预配置吞吐量或与特定模型容量相关的代币单位。在这些模式中，成本可以基于时间、容量单位或特定于模型的输入/输出比率，而不是简单的每个请求令牌账单。
事实：托管工具和检索功能可能会在正常模型推理之外创建额外的计费事件。搜索基础、文件搜索、网址上下文、代码执行、缓存写入和代理中间步骤可能需要单独的 SKU 映射。
建议：将这些事实视为架构要求，而不是例外。如果使用事件包含目录无法映射的计费维度，网关应暂停计费交易，而不是默默地将其定价为零。
构建版本化定价目录
定价目录应该是一流的表或服务，而不是嵌入在提供商适配器中的常量。该目录的存在是为了回答一个问题：对于此使用事件，此时在此租户和提供商帐户上下文下，应使用哪种批准费率？
核心目录字段
实用的目录行应至少包含以下字段：
catalog_version_id：用于报价、保留、结算和对账的不可变版本。provider：上游提供商或内部提供商适配器。provider_account_scope：全局、组织、项目、工作区、BYOK 租户、转销商帐户或企业合同。model_id_or_alias：提供商可见的模型 ID 或正在定价的内部模型别名。pricing_sku：网关用于结算的规范 SKU。provider_meter_id：可选的上游发票计量器（如果有）。billing_unit：输入令牌、缓存输入令牌、输出令牌、推理令牌、缓存写入、搜索查询、图像令牌、音频秒、批处理单位、PTU 小时或其他显式单位。region_scope：全球、区域、驻留区域、市场或数据驻留类别。deployment_type：无服务器、批量、预配置、专用、微调或内部沙箱。service_tier：标准、优先、批量、快速、配置或其他网关层。currency：加价、税费、抵免或兑换前汇率的币种。rate：精确的十进制比率，绝不是二进制浮点数。minimum_unit：最小计费单位。rounding_rule：每个请求、每个发票行、每个租户周期或提供商定义。source_url：文档、价格卡、合同参考或内部批准票。observed_at：检测或导入价格时。effective_from和effective_to：有效期窗口。approval_state：草稿、已审核、已批准、已弃用、已屏蔽或已取代。
重要的实现细节是目录版本一旦被流量使用就不可更改。更正应创建新版本或调整条目，而不是改变现有分类帐行引用的历史版本。
将型号别名与定价 SKU 分开
chat-default、support-fast 或 reasoning-premium 等内部别名是为了操作方便。它们不应替换账本中提供商可见的模型 ID 或定价 SKU。
使用事件应存储所有三个身份：
requested_model_alias：应用程序要求的内容。upstream_model_id：网关实际调用的内容。pricing_sku：结算引擎用于结算的内容。
这可以防止别名升级重写历史记录。如果 chat-default 指向 8 月的一个模型和 9 月的较新模型，则 8 月的使用情况应与 8 月的上游模型和 8 月的目录版本保持关联。
针对不可变目录版本引用
引号只有在稍后可以解释的情况下才有用。网关应在发货前选择目录版本，将其用于预检报价，将其保留在预算预留中，并进行最终结算。
最小请求生命周期如下所示：
- 将请求标准化为预期的计费维度：模型、服务层、区域、令牌估算、缓存资格、工具、批处理模式和部署类型。
- 为租户和提供商帐户范围选择已批准的有效目录版本。
- 解决每个可能的计费维度的预期 SKU。
- 计算预检估算并预留租户预算。
- 仅当所有必需的 SKU 映射都存在时才分派上游请求。
- 从提供商响应中捕获最终使用情况元数据，包括子类别。
- 除非需要明确的更正工作流程，否则使用相同的目录版本来解决实际使用情况。
- 记录预留金额与结算金额之间的任何差异。
建议：以保守假设进行报价和保留，然后根据回复后的使用情况进行结算。对于流、重试、托管工具、长时间运行的代理和缓存命中行为来说，精确的预调度定价很困难。目标不是完美的预测。目标是控制风险和可解释的结算。
因未知的可计费维度而关闭失败
最危险的定价错误是缺少成为免费使用的 SKU。当提供商响应包含没有批准映射的使用存储桶时，网关应该会失败关闭。
应触发结算暂停的示例：
- 模型响应包括
cached_input_tokens，但目录仅具有通用输入和输出标记率。 - 推理模型返回
reasoning_tokens，但未配置推理 SKU。 - 托管搜索工具按查询计费，但网关仅记录模型令牌。
- 批处理作业会获得折扣，但目录会将其映射到标准无服务器 SKU。
- 配置的部署按小时产生容量费用，但租户分类账预计按令牌结算。
- 区域部署使用活动目录中不存在的驻留修饰符。
计费暂停不应丢失事件。它应保留原始提供商使用情况、规范化使用情况、请求标识符、租户标识符、提供商帐户范围、尝试的目录版本、缺失的 SKU 字段以及结算被阻止的原因。一旦目录更新并获得批准，就可以确定地重播保留队列。
批准前使用价卡差异检查
提供商定价页面和 API 并不总是机器稳定的，合同可能会覆盖公开费率。尽管如此，自动差异检查作为警报还是很有用的。他们应该在客户可见的报价受到影响之前检测到变化。
定价导入管道应将新观察到的价格卡与上次批准的目录和标记进行比较：
- 新型号或退役型号；
- 更改的输入、缓存的输入、输出或推理速率；
- 新的令牌类别或工具计量表；
- 更改了缓存写入或缓存命中乘数；
- 新的区域、居住地或市场修饰符；
- 更改了批量折扣规则；
- 更改了预置容量或承诺容量规则；
- 货币变化；
- 舍入或最小单位更改；
- 公开价卡与特定于帐户的合同费率之间的冲突。
建议：将抓取和导入视为草稿数据。任何影响计费流量、合作伙伴可见定价或融资出口的更改都需要人工批准。内部实验可以使用沙盒目录，但它应该有明确的支出上限，并且绝不能被误认为是已批准的客户结算。
添加报价测试作为定价 CI
定价更改需要进行测试，原因与代码更改相同：一个小的修改可能会影响许多请求形状。只要目录行、SKU 映射、提供商适配器或标记政策发生变化，就应运行报价测试。
使用覆盖定价面的综合请求形状：
- 带有输入和输出标记的标准文本请求；
- 使用缓存输入令牌的请求；
- 具有单独推理用途的大量推理请求；
- 带有搜索、文件或代码执行费用的工具使用请求；
- 包含图像、音频、视频或生成媒体单元的多模式请求；
- 具有折扣率和延迟结算的批量作业；
- 配置具有每小时容量和溢出行为的部署；
- 区域或居住范围内的请求；
- 具有特定于提供商的合同费率的租户；
- 具有加价或折扣政策的合作伙伴租户。
每次测试都应断言超过最终总数。它应断言所选的目录版本、SKU 列表、结算单位、费率、舍入行为、货币、估计总额、预订金额和预期结算行。
报价测试示例
{
"name": "cached_input_plus_reasoning_output_standard_tier",
"request": {
"tenant_id": "tenant_test",
"model_alias": "reasoning-default",
"service_tier": "standard",
"region": "global",
"estimated_usage": {
"input_tokens": 12000,
"cached_input_tokens": 8000,
"output_tokens": 1500,
"reasoning_tokens": 3000
}
},
"expect": {
"catalog_version_id": "2026-09-01-approved",
"required_skus": [
"text_input",
"text_cached_input",
"text_output",
"reasoning_output"
],
"approval_state": "approved",
"unknown_dimensions": []
}
}这种测试可以发现信息中心隐藏的目录错误：缓存令牌 SKU 缺失、推理率陈旧或仅在一个提供商帐户范围内出现的层不匹配。
按提供商发票维度进行调节
退款总额不足以进行对帐。网关应按照提供商发票使用的相同维度聚合账本行，然后将这些总计映射回租户、团队、密钥、用户、产品和工作流程。
调节作业应按提供商、帐户、发票周期、仪表、型号、SKU、区域、部署类型、服务层级、货币和目录版本等字段进行分组。应将差异归入已知原因：
- 汇率时间或货币换算；
- 请求级别与发票行级别的舍入；
- 提供商使用情况报告延迟；
- 缺少托管工具事件；
- 目录版本不匹配；
- 提供商方积分、承诺或企业折扣；
- 税费、市场费用和非使用费用；
- 手动调整或退款。
建议：模型提供商成本费率与客户退款费率分开。提供商发票可能包括信用、承诺、折扣或税收，这些不应自动改变面向客户的定价。干净的系统可以解释这两个数字：提供商收取的费用以及根据批准的网关政策向租户收取的费用。
向财务人员和合作伙伴公开价格来源
定价目录不仅仅是内部结算依赖项。财务团队、平台管理员和合作伙伴需要了解价格是否最新且值得信赖。
通过管理视图和合作伙伴 API 公开出处字段：
- 当前报价和货币；
- 生效日期和计划结束日期；
- 源网址或合同参考；
- 批准状态；
- 提供商帐户范围；
- 加价或折扣政策；
- 价格是否为估算、批准、弃用、屏蔽或取代；
- 上次调节状态。
这有助于下游产品避免在上游价格发生变化后提出过时的“最便宜型号”声明或固定的客户价格。当预算和发票不一致时，它还可以为财务部门提供可靠的线索。
实施清单
- 创建包含生效日期和批准状态的不可变定价目录。
- 明确表示计费单位，而不是仅存储通用令牌总数。
- 在每个使用事件中存储请求的别名、上游型号 ID 和定价 SKU。
- 保留
catalog_version_id报价、保留、分类帐行和对帐记录。 - 当使用情况包含未映射的计费维度时，失败会关闭。
- 使用草稿导入和差异检查来检测提供商价格偏差。
- 目录更改影响计费客户流量之前需要获得批准。
- 为缓存令牌、推理令牌、工具、批处理作业、配置的部署和区域修饰符添加引用测试。
- 将提供商费用费率与客户退款费率分开。
- 在向租户分配差异之前按提供商发票维度进行核对。
权衡
更多的版本控制意味着更多的运营工作。每次价格更改都需要导入、审核、批准、测试和部署。好处是旧的使用量永远不会意外地根据新费率重新计算。
关闭失败可能会延迟新模型的访问。这是计费客户流量的正确默认值。对于内部实验，请使用具有明确支出限制和清晰标签的沙盒目录。
自动价格抓取很有用，但不具有权威性。公共页面可能会更改布局、省略合同折扣或以散文描述定价。使用自动化功能来检测偏差，然后在审核后的目录行影响结算之前批准它们。
完美的预检估计是不现实的。流式传输、重试、代理循环、缓存命中和托管工具可能会改变最终使用情况。网关应将保守的保留与响应后结算和明确的差异报告结合起来。
预测：定价目录将成为网关基础设施
预测：随着 AI 使用在各个团队中传播，定价目录将变得与模型目录一样重要。模型路由回答“这个请求应该去哪里？”定价控制回答“我们可以报价、预订、结算并解释此请求吗？”
预测： 随着提供商添加更多令牌类别、工具计量、缓存规则和容量计划，将定价保留在静态配置文件中的团队将陷入困境。压力将首先来自财务和合作伙伴，而不是来自应用程序开发人员。
结论
多模型网关不能将定价视为边桌。它需要一个包含有效日期、SKU 映射、报价测试、审批工作流程和发票核对的版本化目录。实际规则很简单：每个计费使用量桶都必须映射到批准的费率，每个报价都必须引用不可变的目录版本，并且每个结算的账本行在提供商价格发生变化后都必须保持可解释性。
从已经影响生产流量的维度开始：模型、令牌类别、服务层、区域、部署类型、缓存行为和托管工具。然后添加批准状态、失败关闭行为和调节分组。这一基础可以防止价格漂移成为计费事件。