WuYongJie/ESP32

Fork 0

Codex eda6d6a211 补充智谱token采集文档

2026-06-23 22:46:48 +08:00

5.8 KiB

Raw Permalink Blame History

智谱 token 用量采集方案

本文档记录当前 ESP32-S3-RLCD 小屏项目中，智谱 GLM Coding Plan 的 token 用量采集方式、数据字段、刷新策略和安全边界。

结论

当前方案使用 Windows 本机的一个采集进程统一采集数据：

电脑性能数据
Codex 用量数据
智谱额度与 token 用量数据

智谱密钥只保留在 Windows 本机环境变量 ZHIPU_API_KEY 中，不写入 Git、不写入固件、不通过 BLE 发送给开发板。ESP32 只接收已经简化后的数字。

数据来源

智谱数据分两类接口采集。

quota/limit（额度百分比接口）

用途：读取 5H / 周额度窗口的百分比和重置时间。

请求：

GET https://open.bigmodel.cn/api/monitor/usage/quota/limit
Authorization: <ZHIPU_API_KEY>
Content-Type: application/json
Accept-Language: en-US,en

注意：

Authorization 直接放 API Key，不加 Bearer 前缀。
type == "TOKENS_LIMIT" 才是 token 限额。
unit == 3 表示 5H token 窗口。
unit == 6 表示周 token 窗口；部分套餐不会返回。
TIME_LIMIT 不是 token 用量，当前屏幕不使用它。

当前项目显示：

zhipu_5h_percent
zhipu_5h_reset_mins
zhipu_week_percent
zhipu_week_reset_mins

model-usage（模型用量接口）

用途：读取真实 token 消耗，用于显示今日 token 和最近 14 天每日柱状图。

请求：

GET https://open.bigmodel.cn/api/monitor/usage/model-usage?startTime=<yyyy-MM-dd HH:mm:ss>&endTime=<yyyy-MM-dd HH:mm:ss>
Authorization: <ZHIPU_API_KEY>
Content-Type: application/json
Accept-Language: en-US,en

当前项目查询窗口：

起始时间：最近 14 天第一天的 00:00:00
结束时间：当前本机时间

实测返回的关键字段：

{
  "success": true,
  "data": {
    "x_time": ["2026-06-23 00:00"],
    "tokensUsage": [0],
    "totalUsage": {
      "totalModelCallCount": 700,
      "totalTokensUsage": 129053626,
      "modelSummaryList": [
        {
          "modelName": "GLM-5.2",
          "totalTokens": 123456,
          "sortOrder": 1
        }
      ]
    },
    "modelDataList": [
      {
        "modelName": "GLM-5.2",
        "tokensUsage": [0],
        "totalTokens": 123456
      }
    ],
    "modelSummaryList": [
      {
        "modelName": "GLM-5.2",
        "totalTokens": 123456,
        "sortOrder": 1
      }
    ],
    "granularity": "hourly"
  }
}

当前项目只使用：

x_time
tokensUsage

处理方式：

按 x_time 的日期部分聚合 tokensUsage。
得到最近 14 天每天 token 总量。
今日 token 转为屏幕紧凑单位。
以最近 14 天最大值为 100，生成每日柱状图百分比。

显示单位

电脑端会把 token 转成 m10 整数发送：

m10 = round(tokens / 100000)

固件端再显示为：

< 1000：显示为 x.xM
>= 1000：显示为 xxxM
>= 10000：显示为 x.xB

示例：

1455 -> 146M
10000 -> 1.0B

刷新策略

当前实现：

quota/limit 默认 60 秒刷新一次。
model-usage 默认 600 秒刷新一次。
BLE 仍然每秒推送一次完整 SYS8 数据，但智谱 token 部分使用缓存值。

建议后续：

quota/limit 可以调整为 2-5 分钟。
model-usage 可以保持 10-15 分钟。
不建议秒级请求智谱接口。

协议字段

当前 BLE 协议为 SYS8。

智谱相关字段位置：

..., zhipu_status,
zhipu_5h,
zhipu_week,
zhipu_5h_reset,
zhipu_week_reset,
zhipu_today_tokens_m10,
zhipu_daily_bars,
cpu_core_text,
disk_text

其中：

zhipu_status：0=WAIT，1=OK，2=ERR
zhipu_5h：5H token 使用百分比
zhipu_week：周 token 使用百分比，没有则为 -1
zhipu_5h_reset：5H 重置剩余分钟数
zhipu_week_reset：周重置剩余分钟数，没有则为 -1
zhipu_today_tokens_m10：今日 token，单位为 100000 token
zhipu_daily_bars：最近 14 天每日柱状图百分比，使用冒号分隔，例如 0:0:24:78:100

固件仍保留 SYS7 解析，方便旧采集端短时间兼容。

代码位置

电脑端采集：

tools/pc-metrics/push-metrics-ble.py
ZhipuStatusReader
_query_quota()
_query_usage()
_usage_to_daily_snapshot()

固件端协议解析：

main/metrics_protocol.c
parse_sys8_line()
parse_zhipu_daily_bars()

固件端 UI：

main/ui_screen.h
main/ui_screen.c
update_zhipu_panel()

安全边界

必须遵守：

不把 ZHIPU_API_KEY 写入代码。
不把 ZHIPU_API_KEY 写入文档。
不把 ZHIPU_API_KEY 写入固件。
不把 ZHIPU_API_KEY 发送给 ESP32。
不把原始接口返回完整转发给 ESP32。
ESP32 只接收数字化后的结果。

当前推荐启动方式：

$env:ZHIPU_API_KEY="<your-zhipu-api-key>"
& "D:\AI Code\ESP-32\tools\pc-metrics\start-ble-metrics.ps1" -IntervalSeconds 1
Remove-Item Env:\ZHIPU_API_KEY -ErrorAction SilentlyContinue

注意：这种方式只让启动后的采集进程持有密钥，不会把密钥持久写入系统环境变量。电脑重启后需要重新启动采集进程。

性能开销

本机实测结果：

接口	中位耗时	返回大小
`quota/limit`	约 257 ms	约 443 B
`model-usage`，近 7 天	约 348 ms	约 7.1 KB
`tool-usage`，近 7 天	约 272 ms	约 5.9 KB

当前项目暂不使用 tool-usage。

按 10 分钟查询一次 model-usage 计算，一天只有约 144 次请求，数据量很小，对电脑和网络影响可以忽略。

官方性说明

model-usage 属于智谱官方用量查询插件实际使用的接口，风险低于社区逆向 Cookie 方案。

但它不是普通开放 API 文档中明确列出的长期稳定业务 API，所以当前项目采用低频、本机、自用、只读查询方式，不做公开服务和高频轮询。

5.8 KiB Raw Permalink Blame History Unescape Escape