补充智谱token采集文档
This commit is contained in:
Codex
parent
991be85b16
commit
eda6d6a211
239
docs/zhipu-token-usage-collection.md
Normal file
239
docs/zhipu-token-usage-collection.md
Normal file
@ -0,0 +1,239 @@
|
||||
# 智谱 token 用量采集方案
|
||||
|
||||
本文档记录当前 ESP32-S3-RLCD 小屏项目中，智谱 GLM Coding Plan 的 token 用量采集方式、数据字段、刷新策略和安全边界。
|
||||
|
||||
## 结论
|
||||
|
||||
当前方案使用 Windows 本机的一个采集进程统一采集数据：
|
||||
|
||||
- 电脑性能数据
|
||||
- Codex 用量数据
|
||||
- 智谱额度与 token 用量数据
|
||||
|
||||
智谱密钥只保留在 Windows 本机环境变量 `ZHIPU_API_KEY` 中，不写入 Git、不写入固件、不通过 BLE 发送给开发板。ESP32 只接收已经简化后的数字。
|
||||
|
||||
## 数据来源
|
||||
|
||||
智谱数据分两类接口采集。
|
||||
|
||||
### quota/limit（额度百分比接口）
|
||||
|
||||
用途：读取 5H / 周额度窗口的百分比和重置时间。
|
||||
|
||||
请求：
|
||||
|
||||
```http
|
||||
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 天每日柱状图。
|
||||
|
||||
请求：
|
||||
|
||||
```http
|
||||
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`
|
||||
- 结束时间：当前本机时间
|
||||
|
||||
实测返回的关键字段：
|
||||
|
||||
```json
|
||||
{
|
||||
"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`
|
||||
|
||||
处理方式：
|
||||
|
||||
1. 按 `x_time` 的日期部分聚合 `tokensUsage`。
|
||||
2. 得到最近 14 天每天 token 总量。
|
||||
3. 今日 token 转为屏幕紧凑单位。
|
||||
4. 以最近 14 天最大值为 100，生成每日柱状图百分比。
|
||||
|
||||
## 显示单位
|
||||
|
||||
电脑端会把 token 转成 `m10` 整数发送：
|
||||
|
||||
```text
|
||||
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`。
|
||||
|
||||
智谱相关字段位置：
|
||||
|
||||
```text
|
||||
..., 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 只接收数字化后的结果。
|
||||
|
||||
当前推荐启动方式：
|
||||
|
||||
```powershell
|
||||
$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，所以当前项目采用低频、本机、自用、只读查询方式，不做公开服务和高频轮询。
|
||||
Loading…
x
Reference in New Issue
Block a user