openai agent sdk 返回usage的解释

2026-06-02 16:41:54 阅读:15 编辑
{"usage": {
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "prompt_cache_hit_tokens": 0,
    "completion_tokens": 41,
    "prompt_tokens": 13,
    "total_tokens": 54,
    "completion_tokens_details": {
      "reasoning_tokens": 34
    },
    "prompt_cache_miss_tokens": 13
  }
  }

帮我解释一下各个字段的意思? 这是一个标准的 API 用量(Usage)响应,通常来自 OpenAI 或兼容接口。我来逐一解释每个字段:

顶层字段 字段 含义 示例值 prompt_tokens 输入提示词消耗的 token 总数 13 completion_tokens 模型生成的输出 token 总数 41 total_tokens 总消耗 token 数(输入 + 输出) 54 这是计费的基础。注意:total_tokens = prompt_tokens + completion_tokens,这里 13 + 41 = 54,刚好吻合。

prompt_tokens_details(输入 token 的详细分解) 字段 含义 值 cached_tokens 命中了服务端缓存的 token 数(通常享受 50% 折扣) 0 这里值为 0,表示本次请求没有命中任何缓存,全部 token 都是原价计费。

completion_tokens_details(输出 token 的详细分解) 字段 含义 值 reasoning_tokens 思维链/推理过程消耗的 token 数 34 这是关键信息!说明你调用的是具有内部推理能力的模型(如 o1、o3 系列)。模型在输出最终回答之前,先进行了 34 个 token 的"思考",这部分不展示给用户但会计费。真正的最终回复只有 41 - 34 = 7 个 token。

与缓存相关的字段 你的结果中还出现了这两个不在标准 Usage 结构中的字段:

字段 含义 值 prompt_cache_hit_tokens 命中了缓存的输入 token 数(通常等于 cached_tokens) 0 prompt_cache_miss_tokens 未命中缓存的输入 token 数(通常等于 prompt_tokens - cached_tokens) 13 这两个是缓存命中/未命中的另一种表达形式,它们的关系是:

text prompt_cache_hit_tokens + prompt_cache_miss_tokens = prompt_tokens 0 + 13 = 13 ✓ 总结一下这次调用 项目 数量 说明 你发送的提示词 13 tokens 非常短的输入 模型的内部推理 34 tokens 不显示,但计费 最终回复 7 tokens 实际可见的回答 总消耗 54 tokens 计费依据 缓存命中 0 没有折扣 特别值得注意的是 reasoning_tokens 占了总输出的 83%,这说明推理类模型"思考"的开销可能远大于最终回答本身。如果你把同样的请求发给非推理模型,这 34 个 token 就不会产生。