OpenAI Usage API 企业版用量监控配置教程：completion_tokens_details 字段解析与 budget_alert 接入

阅读前说明：本文部分内容涉及 OpenAI API 的较新特性（包括推理模型的 completion_tokens_details 字段、Spend Controls 的 budget_alert 功能等），相关接口行为、字段结构及功能开放范围以 OpenAI 官方文档 为准。文中提及的具体模型名称、版本号、价格及第三方平台费率请在使用前自行核实最新信息。

最近我们团队的 GPT API 调用费突然比预期多了 40%，老板让我查原因。打开 OpenAI Dashboard 看了半天，只有按天的粗粒度图表，根本定位不到是哪个服务、哪个时段把 token 烧掉的。正好 OpenAI 更新了企业版的 Usage Analytics API 和 Spend Controls，我花了两天把监控链路搭起来了——过程中踩了两个格式兼容的坑，这里一并记录。

OpenAI 企业版用量分析接口的核心变化是 completion_tokens_details 返回对象新增了 reasoning_tokens 子字段（主要用于 o1、o3 等推理模型），与旧版 usage 对象的扁平结构不兼容；同时 Spend Controls 新增了 budget_alert webhook 配置，可以在消费达到阈值时主动推送通知。本文介绍如何接入这两个功能。

注意：cached_tokens 信息通常出现在 prompt_tokens_details 下，而非 completion_tokens_details 下，本文后续示例以实际 API 返回结构为准，请以官方文档核实。

这篇适合谁

• 已经在调用 OpenAI 推理模型 API 的企业开发者，想把 token 消耗接入自有监控（Grafana / DataDog）
• 团队里多个服务共用一个 org，需要按 project 拆分成本归因
• 之前用旧版 /v1/usage 接口，升级后发现返回字段解析报错的
• 想配 budget_alert 但不确定 webhook payload 格式的后端同学

整体流程

1. 确认账户权限（Enterprise + Admin API Key）
2. 调用推理模型并理解 completion_tokens_details 新结构
3. 处理新旧字段兼容问题（两个坑）
4. 配置 Spend Controls 的 budget_alert
5. 接入监控系统做可视化

graph LR
    A[推理模型调用] --> B[响应 usage 对象]
    B --> C{是否含 details?}
    C -->|有| D[completion_tokens_details<br/>含 reasoning_tokens]
    C -->|无| E[扁平 completion_tokens]
    D --> F[写入监控]
    E --> F
    G[Spend Controls] --> H[budget_alert webhook]
    H --> I[Slack/飞书通知]

先说结论

第一步：确认权限和 SDK 版本

Enterprise 账户的 Admin Key 才能调用组织级用量接口。先确认你的 key 类型：

import openai
client = openai.OpenAI(api_key="sk-...")
models = client.models.list()
print([m.id for m in models.data[:5]])

如果返回列表里有你需要的推理模型，说明你的 org 已经有访问权限。没有的话会报类似这样的错：

openai.BadRequestError: Error code: 400 - {
  'error': {'message': 'The model does not exist
  or you do not have access to it.',
  'type': 'invalid_request_error', 'code': 'model_not_found'}
}

SDK 版本建议使用 Python openai>=1.35.0（TypeScript 用户请参考 npm openai 包 的最新稳定版本，截至本文写作为 4.x 系列）。旧版 SDK 可能不会解析 completion_tokens_details 字段。

注意：具体 SDK 版本对字段解析行为的影响，建议以官方 Changelog 为准。

第二步：调用推理模型并解析新 usage 结构

以 o3 为例（请替换为你实际有权限访问的推理模型）：

resp = client.chat.completions.create(
    model="o3",  # 替换为你实际使用的推理模型
    messages=[{"role": "user", "content": "解释量子纠缠"}]
)
print(resp.usage)

推理模型的返回示例（字段结构以实际 API 返回为准）：

{
  "prompt_tokens": 14,
  "completion_tokens": 387,
  "total_tokens": 401,
  "completion_tokens_details": {
    "reasoning_tokens": 128
  },
  "prompt_tokens_details": {
    "cached_tokens": 0
  }
}

关键变化：completion_tokens 还是 387 没变，但 completion_tokens_details 告诉你其中有 128 个是内部推理 token（chain-of-thought 开销）。这个数字以前是看不到的，只能猜。

第三步：处理兼容性（两个坑）

坑 1：旧代码直接取 usage["completion_tokens_details"] 会 KeyError

如果你的监控脚本同时处理推理模型和非推理模型（如 gpt-4o-mini）的响应，非推理模型目前还是旧格式，没有 completion_tokens_details 字段。

details = resp.usage.completion_tokens_details
reasoning = getattr(details, 'reasoning_tokens', 0) if details else 0

不要用 resp.usage["completion_tokens_details"]["reasoning_tokens"] 这种硬取法，模型不同返回结构不一样，会报错。

坑 2：Usage API 的聚合接口返回格式也有变化

重要提示：/v1/organization/usage/completions 端点的可用性、权限要求及返回字段，请以 OpenAI 官方文档 为准。以下代码仅供参考。

import requests

headers = {
    'Authorization': 'Bearer sk-...',
    'OpenAI-Organization': 'org-...'
}
params = {'start_time': 1718668800, 'group_by': 'project_id'}

resp = requests.get(
    'https://api.openai.com/v1/organization/usage/completions',
    headers=headers,
    params=params
)
buckets = resp.json()['data']

如果你的 Grafana dashboard 之前只汇总了生成 token 总量，现在要注意 reasoning_tokens 包含在 completion_tokens 里，但需要单独关注其占比——推理 token 按 output 价格收费，且推理模型的推理链越长，这部分开销越显著。

以 o3 为例（价格以 OpenAI 定价页 为准），若某模型 output 定价为 $10.00/M tokens，128 个 reasoning tokens 的单次成本约为 $0.00000128。若一天跑 10 万次请求，reasoning 部分成本约为：128 × 100,000 / 1,000,000 × $10.00 = $128，按当前汇率折算约 ¥920 左右（请以实际汇率和官方定价计算）。

第四步：配置 budget_alert

Spend Controls 里的 budget_alert 支持设定月度预算阈值和 webhook 回调。在 Dashboard → Organization → Billing → Spend Controls 里配置，或者尝试用 API（注意：API 配置方式的可用性因账户类型而异，部分账户可能只支持 UI 操作）：

# 目前 budget_alert 配置建议通过 Dashboard UI 操作
# API 端点的可用性请以官方文档为准

UI 里的配置项：

• Monthly budget：设一个美元数（示例：$2000）
• Alert thresholds：50% / 80% / 100% 三档，每档触发 webhook
• Webhook URL：填你的接收端点，payload 是 JSON

webhook 推过来的格式示例（实际字段以官方文档为准）：

{
  "type": "budget_alert",
  "threshold_percent": 80,
  "current_spend_usd": 1612.34,
  "budget_usd": 2000,
  "org_id": "org-xxx"
}

收到之后转发到 Slack 或者飞书就行。可以写一个简单的 Cloudflare Worker 做转发。

第五步：接入监控

我的做法是每小时跑一次 cron job 拉 Usage API 数据，写入 InfluxDB，Grafana 出图。

如果你们团队用的是多模型混合调用，可以考虑用聚合 API 网关统一管理——像 OpenRouter 这类平台本身就带按 Model / User / API Key 维度的用量和费用管理后台，每一笔 token 消耗和费用支出直接可视化，省得自己搭监控链路。

费率说明：OpenRouter 及其他聚合网关的加价比例因模型而异，请以各平台官网公示的最新费率为准，不同模型的实际加价比例可能有所不同。其他第三方平台（如 ofox.io 等）的费率声明同样建议以官网为准，本文不作背书。

不过如果你只用 OpenAI 一家，自建监控更灵活。核心就是把 Usage API 的 group_by=project_id 用起来，按服务拆分成本。

不同场景怎么选

场景 A：单团队只用 OpenAI 推理模型
→ 直接用 OpenAI 原生 Usage API + budget_alert webhook，够用了。自己写个 cron 拉数据。

场景 B：多模型混合（OpenAI + Anthropic + 开源模型）
→ 用聚合网关统一管理更省事。自建的话要对接多套不同格式的用量接口，维护成本高。

场景 C：需要精确到每个请求的成本归因
→ 在每次请求的 metadata 里塞 project tag，然后 Usage API 按 project_id group_by 查询。reasoning_tokens 的占比一定要算进去。

场景 D：预算敏感，需要硬限制而非告警
→ budget_alert 只是通知，不会自动断流。要硬限制的话得在自己的网关层做 token 计数 + 熔断。

常见问题 FAQ

Q: completion_tokens_details 在 streaming 模式下能拿到吗？

需要设置 stream_options={"include_usage": True} 才能在最后一个 chunk 里拿到 usage 字段。streaming 场景下 completion_tokens_details 的具体返回行为（是否为 null）请以实际测试和官方文档为准，不同版本可能有差异。

Q: reasoning_tokens 的计费和普通 output tokens 一样吗？

根据 OpenAI 官方文档，reasoning_tokens 按 output token 价格计费。具体定价请以 OpenAI 定价页 为准。这也是为什么同样的 prompt，推理模型比非推理模型贵——它内部推理链更长。

Q: 旧版 /v1/usage 接口还能用吗？

可以查询，但返回数据不含 reasoning_tokens 拆分。如果你只需要总量不需要细分，旧接口暂时没问题。建议关注官方文档中的 deprecation 通知，及时迁移。

Q: budget_alert 的 webhook 支持重试吗？

官方文档中对重试策略的描述请以最新文档为准。建议让你的 webhook endpoint 做好幂等处理，避免重复通知带来的问题。

Q: 429 RateLimitError 和 budget_alert 有什么关系？

没关系。429 是 tokens per minute 的速率限制，budget_alert 是月度消费总额的告警。两个维度完全独立。429 的报错长这样：

RateLimitError: Rate limit reached for model in organization org-xxx
on tokens per min. Limit: 800000, Used: 800000, Requested: 2000.

处理 429 要做指数退避重试 + 监控响应头 x-ratelimit-remaining-tokens，跟 budget 没关系。

小结

把监控链路搭起来之后，核心收获是：completion_tokens_details 里的 reasoning_tokens 是推理模型成本比预期高的主要原因——我们的场景平均每次请求有相当比例的 token 花在了内部推理上，以前完全看不到这部分开销。budget_alert 配起来倒是很快，就是目前 API 配置方式的开放程度因账户类型而异，UI 操作是最稳妥的方式。

最后提示：本文涉及的 API 端点、字段结构、模型名称、定价信息均可能随 OpenAI 产品迭代而变化，建议以 OpenAI 官方文档 和 定价页 为最终参考。