我平时有个习惯喜欢把自己常用的工具脚本都攒成一个个独立的小项目Zcode 就是其中之一。这个项目本身是个自用的自动化工作台里面杂七杂八挂了不少小模块而这次说的“GLM 周重置卡”算是我最近实际用到最多的一个功能。先交代一下背景我日常开发大量依赖大模型 APIGLM 系列接口这里代指我手头常用的某个大模型 API 服务的免费调用额度不是按月刷新而是按周重置。也就是说一周之内如果把额度跑满了就得干瞪眼等到下周。以前我全靠手机日历提醒自己“周一早点去后台看一眼”结果经常是周一一忙就忘了等想起来的时候配额早就被某个半夜跑的脚本给烧光了。后来狠下心用 Zcode 这个自用平台写了一个专门盯配额的小模块我叫它“周重置卡”。它会定时去轮询 GLM API 的用量接口算出当前剩余额度、估算能撑到哪天然后到接近重置窗口的时候提醒我重置之后还会自动清理旧会话状态相当于给 API 上了一张会自愈的“复活卡”。整个开发过程里最有意思的不是写代码本身而是我基于“这个功能应该很简单”的假设去问了一圈结果压根没收到实质回复最后只能自己啃文档、抓包、看返回字段把全部细节捋了一通。这篇文章把这些经验完整写出来中间包含可直接复用的代码、几个很容易踩的坑以及一套我认为比较可靠的配额管理思路希望对同样自用大模型 API 的朋友有参考价值。1. 项目概述给 GLM API 装一个“每周提醒闹钟”1.1 这个模块解决的是哪个具体痛点先说大环境。现在的 GLM 类 API 服务普遍采用配额Quota制免费档和低价档通常给一个“每周固定的调用量上限”比如几百万 tokens或者限制每分钟请求数。这里的“周”不是自然周那么简单有的服务按北京时间周一零点到周一零点计算有的按 UTC 时间还有的按你账号开通时间往后推 7 天。这就带来一个非常尴尬的情况你没法用一个简单的日历判断“这周额度还有多少”因为每周的分界线可能落在周三下午三点。如果只是个人偶尔调几下这个配额基本无所谓但像我这样把 API 接到自动化脚本里比如定时生成摘要、批量处理文本、跑一些简单的 Agent 流程那配额消耗就非常快。最难受的不是用超了而是用超之后的情况不对GLM API 在配额耗尽时不会直接报错它会返回一个 429 或者 403 状态码某些接口甚至会降级成低质量模型继续响应这会导致我的自动化任务拿到一堆“看起来正常但其实是降级结果”的数据。所以这个周重置卡的核心目标有三个第一实时掌握配额水位第二在重置窗口到来前做提醒第三在确认重置完成后自动恢复任务调度避免我手动登录控制台去点刷新。1.2 为什么命名成“Zcode 自用 GLM 周重置卡”Zcode 是我给自己那套脚本工作台起的名字没有特别含义就是代码和“Z”打头的个人标记。之所以叫“周重置卡”而不是“配额监控器”是因为它不只做监控还会主动参与“重置”这件事。这里解释一下有些 API 平台的重置逻辑是后台自动发生的不需要你做什么但有的平台会提供一个 refresh 或 reset 接口或者要求你在过期重置前主动更新 API Key 的权限范围如果你不操作重置就不会发生。这个模块把“主动触发重置”也封装进去了所以叫卡像一张游戏里每周刷新领取的签到卡。整个项目本质上是“轮询 状态机 提醒”的组合。轮询负责采集数据状态机负责判断当前属于“正常期 / 预警期 / 耗尽期 / 已重置”中的哪个状态提醒负责在状态切换时通知我。整个过程不需要人为介入这也是我自己用下来的最大感受机器提醒永远比人肉记日历靠谱。2. 整体设计拆解周重置卡的四个核心模块2.1 配额状态采集模块这个模块的工作是定期调用 GLM API 的用量查询接口把返回的数据整理成几条固定字段。不同版本的 API 接口字段名不一样比较常见的是total_limit、used、remaining、reset_time这几个。有的平台还会返回rate_limit和burst_limit分别是每分钟和每秒钟的并发限制。我强烈建议不要只记录剩余额度要把原始响应完整存一份哪怕是存到本地 SQLite 里都行。因为平台的返回结构偶尔会变你只保留剩余数字的话字段名一变你都看不出哪里坏了。我实际遇到过平台在某个版本把remaining改成了remaining_quota因为我的模块只认老字段结果那个星期所有数据都读成了零直接触发了一连串误报。采集频率也有讲究。按我的经验五分钟一次足够不需要每秒钟去打接口否则很容易触发平台侧的单账号限流。如果你同时管理多个 API Key建议给每把 Key 设置独立的请求间隔。我的做法是维护一个字典key 是 Key 的别名value 是下一次允许请求的时间戳不到时间就跳过本轮采集。2.2 重置时间计算模块这部分是整个项目里最容易被低估的模块。很多人觉得重置时间不就是一个时间戳嘛直接拿数据库里的reset_time展示就行。问题是许多接口返回的reset_time并不准确它可能是一个区间也可能根据账号等级动态变化更常见的是它只精确到天没有精确到小时。我的处理方式是同时维护三个时间源接口返回的reset_time、本地根据账号创建时间推算的周期时间、以及手动配置的“预期重置时间”。每次采集后把三个时间放在一起对比如果偏差超过 12 小时就触发日志记录。这样做的原因很简单一旦接口字段开始迟报或漏报我能第一时间发现而不是傻等到重置之后才发现模块全程都没动作。时区问题在这里尤其值得提。如果你和我一样机器部署在境外云主机上API 账号是国内的那一定不要想当然地用服务器本地时间去做“周一零点”判断。我建议所有时间统一换算成 UTC8 再计算。具体实现时我会在配置里写死一个TIMEZONE_OFFSET 8然后所有计算都基于带时区信息的 datetime 对象避免因为夏令时或者服务器时区漂移出现重置时间差一小时的问题。2.3 提醒与展示层提醒渠道我试过很多种最终固定为“推送 本地文件”双通道。推送用的是现成的通知服务本地文件则是把最近一次采集结果写成一个quota_status.json方便我在终端随时查看。这个设计是被一次事故逼出来的有次推送服务整个挂了我的模块还以为一切正常直到任务跑挂了才发现配额早就清零。从那之后本地状态文件就成了“最后的真相”不管外部渠道通不通文件里永远有最新数据。展示层不需要做得多炫酷一个简单的表格就够用了。我自己的终端卡片长这样维度数值备注API Key 别名default-总配额500,000 tokens本周已用312,500 tokens62.5%剩余187,500 tokens37.5%预计消耗速率2,100 tokens/min近 24 小时平均预计可用时长89 分钟基于当前速率重置时间2026-05-25 00:00:00 (UTC8)来自接口 校验表格里最重要的是“预计可用时长”这一列因为它不是接口给的是自己算出来的。计算方式是用过去 24 小时的平均消耗速率除以剩余量这个值比光看百分比要直观得多——比如剩余 37.5%听起来还挺多但如果按当前速率只能跑 89 分钟那就应该立刻降低任务频率了。2.4 自恢复与容错设计写这种常驻脚本最忌讳的就是“单点崩溃”。我的自恢复策略有三层第一层是失败重试。轮询接口如果返回 5xx 或超时不立刻报错而是按指数退避重试三次间隔分别是 10 秒、30 秒、90 秒。第二层是状态文件校验。每次采集前先读取上次的quota_status.json如果当前采集失败就基于旧数据继续展示但会打上一个stale: true标记提醒我数据不是实时的。第三层是看门狗。因为模块部署在服务器上我会额外开一个简单的 systemd 服务来监控主脚本进程如果进程异常退出自动拉起并把重启事件推送给我。这三层设计听起来复杂其实代码量很小但带来的稳定性收益非常大。自用工具最大的敌人不是功能少而是“你完全不知道它什么时候悄悄挂了”。3. 实操过程与核心实现3.1 环境准备与依赖清单整个周重置卡对运行环境要求不高我用的就是一台普通的 Linux 云主机配置 1 核 1G 就够了。Python 版本建议 3.10 以上推荐 3.11因为tomllib可以直接解析 TOML 配置文件少装一个第三方库。依赖库只有三个requests负责 API 请求。apscheduler负责定时任务的调度。pytz处理时区计算虽然 Python 3.9 之后内置了 zoneinfo但 pytz 的兼容性更好我这里选择了更稳的方案。不需要引入数据库SQLite 文件就足够存这些状态数据。我项目里的文件结构是这样的zcode_glm_reset/ ├── config.toml # 配置文件API Key、时区、轮询间隔等 ├── main.py # 主入口 ├── quota_collector.py # 采集模块 ├── reset_calculator.py # 重置时间计算模块 ├── notifier.py # 推送模块 ├── state_store.py # 状态读写模块 └── quota_status.json # 运行后生成的状态文件3.2 配置文件这样写配置文件用 TOML 格式好处是可读性好不会发生 JSON 转义问题。下面是一个完整的配置示例[api] base_url https://api.example-llm.dev/v1 api_key sk-your-key-here timeout 10 poll_interval_minutes 5 [quota] total_limit 500000 warning_threshold 0.2 alert_threshold 0.05 timezone_offset 8 [reset] # 可选值auto / manual mode auto manual_reset_hour 0 manual_reset_minute 0 [notify] webhook_url https://your-notify-service.example/hook这里重点说warning_threshold和alert_threshold。warning_threshold 0.2意味着剩余额度低于 20% 时会推送一条“配额预警”alert_threshold 0.05意味着低于 5% 时会推送第二级别的“危险告警”。两个阈值分开设是为了避免预警信息过于频繁导致自己把它当普通通知忽略掉。3.3 核心代码实现思路采集模块的核心逻辑可以拆成三步请求接口、解析字段、写入状态文件。下面这段代码是我理顺后的简化版保留了最重要的骨架# quota_collector.py import json import time import requests def collect_quota(config, storer): url config[api][base_url] /usage headers {Authorization: fBearer {config[api][api_key]}} try: resp requests.get(url, headersheaders, timeoutconfig[api][timeout]) resp.raise_for_status() data resp.json() except requests.RequestException as exc: # 失败时不直接抛错而是标记数据过期交给上层重试逻辑处理 storer.mark_stale() raise RuntimeError(fquota API request failed: {exc}) from exc parsed parse_usage_payload(data) storer.update(parsed) return parsed def parse_usage_payload(data: dict) - dict: # 兼容性处理优先找 remaining找不到就用 total - used remaining data.get(remaining_quota, data.get(remaining)) if remaining is None and total in data and used in data: remaining data[total] - data[used] total data.get(total_limit, data.get(total)) used data.get(used) reset_time data.get(reset_time) return { total: total, used: used, remaining: remaining, reset_time: reset_time, collected_at: time.time(), }这里的容错逻辑就是前面说的——针对接口字段发生过变化的情况优先用多个字段名去猜。别觉得这样很丑在实际生产环境里这恰恰是活下来的关键。重置计算模块会稍微复杂一点。它需要把“接口给的重置时间”和“按周期推算的时间”做对比# reset_calculator.py from datetime import datetime, timedelta, timezone def compute_reset_window(config, api_reset_time): offset_hours config[quota][timezone_offset] tz timezone(timedelta(hoursoffset_hours)) # 推算如果按固定 7 天周期从账号创建时间算 account_created datetime.fromisoformat(config[reset][account_created]) projected_reset account_created now_local datetime.now(tz) while projected_reset now_local: projected_reset timedelta(days7) # 如果接口时间缺失就用推算时间 if api_reset_time is None: return projected_reset.isoformat() api_dt datetime.fromisoformat(api_reset_time).astimezone(tz) diff abs((api_dt - projected_reset).total_seconds()) if diff 12 * 3600: # 偏差过大记日志但优先相信接口返回时间 print(f[warn] reset_time drift detected: {api_dt} vs {projected_reset}) return api_dt.isoformat()这段代码里最难理解的部分可能是“按账号创建时间算周期”这个逻辑。之所以保留它是因为我有一次发现接口连续两周返回的reset_time都是同一时刻由此判断出平台后台有 bug重置实际上没发生。后来我加了本地推算作为校验才避免了那次配额乌龙。调度模块就很简单了# main.py from apscheduler.schedulers.blocking import BlockingScheduler scheduler BlockingScheduler(timezoneAsia/Shanghai) scheduler.add_job( routine_check, interval, minutesconfig[api][poll_interval_minutes], max_instances1, coalesceTrue, ) scheduler.start()max_instances1和coalesceTrue是两个很容易被忽略但作用很大的参数。前者保证同一时刻只有一次轮询在跑防止上一轮还没结束下一轮就启动后者表示如果因为某些原因错过了这一轮那么攒到下一轮再执行而不是堆积一堆任务阻塞队列。3.4 部署方式与运行效果部署这块我没有用 Docker因为整个服务太轻了直接用 systemd 做成一个常驻服务反而是最省事的。服务文件大致如下[Unit] DescriptionZcode GLM Quota Reset Card Afternetwork-online.target [Service] ExecStart/usr/bin/python3 /opt/zcode_glm_reset/main.py WorkingDirectory/opt/zcode_glm_reset Restartalways RestartSec15 Userzcode [Install] WantedBymulti-user.target注意我特意设置了Restartalways和RestartSec15——如果进程意外退出15 秒后自动拉起来。这个参数我没有放在主脚本内部实现而是直接交给 systemd 去管稳定性比自己写看门狗强得多。部署完成后日常我基本不看这个工具的输出只在推送通知到达的时候扫一眼。实际用下来的感受是它很快让我形成了“配额焦虑免疫”我不再需要每周一记着去后台查看因为模块自己会在该看的时候提醒我。4. 问题排查与经验实录4.1 为什么说“未获实质回复”一次求助无效的复盘这个模块开发过程中我遇到过一个比较诡异的现象重置时间明明到了但是实际可用的配额却还是 0。我当时很自然地往社区提问描述了自己的配置、API 版本、复现步骤结果等来的回复要么是“你重启一下试试”要么是“你是不是 key 用错了”没有一条真正触及问题核心。整个求助过程大概花了 3 天最后有一大半问题还是靠自己 debug 解决的。这里我想给同样做自用工具的朋友一个建议如果你遇到问题不要把所有希望都寄托在社区提问上。更好的做法是提问的同时自己同步排查把精力重点放在抓接口响应、看日志、复现最小案例上。社区回复往往是基于“通用经验”而你的问题大概率是“特定场景”只有自己能真正摸清上下文。后来发现我的问题出在平台侧对“重置窗口”的定义是“当前请求到达时动态计算的”而我的本地时间判断逻辑和它差了 30 分钟。这种问题靠别人隔空诊断确实很难定位出来。4.2 踩过的三个坑和对应的排查思路第一个坑是时区偏差导致的误判。我的服务器跑在 UTC 时区但是 API 账号是基于 UTC8 计算的。最开始我用datetime.now()做判断导致“重置时刻”整整偏移了 8 小时。排查方式很简单把每次计算后的判定样式完整打印出来和接口返回的时间戳人工对比一次。这里建议大家所有时区相关的地方都统一用一个工具函数不要散落在多个文件里。第二个坑是接口返回的“重置时间”格式不统一。有时候是带时区的 ISO 字符串有时候是一个纯数字时间戳有时候甚至是个日期字符串。我一开始只处理了 ISO 格式结果某天凌晨突然收到一堆误报才发现全部是因为时间解析失败代码走了异常分支把剩余额度当成了零。解决办法是在解析层做一个format_detector根据字符特征自动选择解析方式。第三个坑是多 Key 并发采样的限流问题。我手头有两个 API Key一个是主 key一个是备用 key。最开始我为两个 key 各自起了线程去轮询结果发现平台的限流是“按账号维度”计算的两个 key 同时请求等于双倍消耗直接把速率限制触发了。后来我改成串行采样两个 key 的请求间隔至少 3 秒这个问题就消失了。4.3 实用避坑清单根据这段开发经历我整理了一份清单适合所有做 API 配额管理工具的人参考不要只依赖接口返回的剩余额度尽量同时保存原始响应原文方便后续排查字段变动。重置时间计算必须显式指定时区不要在代码里依赖操作系统默认时区。预警阈值和告警阈值建议拉开差距至少 3 倍以上否则通知会变得不敏感。轮询接口请求间隔不要小于 60 秒尤其是免费档很容易触发限流。任何外部推送渠道都可能故障必须有一个本地可用状态副本兜底。代码里所有时间戳最好统一用 ISO 格式字符串存储避免数字时间戳在精度上出问题。配置文件和代码严格分离不要把 API Key 直接写进 py 文件避免在分享代码时泄露。定时任务一定要用带持久化的调度器保证进程重启后任务不会丢失。部署完成后至少观察一个完整重置周期一周再放手不管确保跨天、跨周逻辑都正确。4.4 常见问题速查表问题现象可能原因处理方式剩余额度突然显示为零接口字段变动 / 解析失败查看完整响应确认字段名是否变化重置时间到了但额度未恢复平台重置逻辑有延迟增加本地推算作为兜底等待 10 分钟后重新拉取通知频繁轰炸阈值梯度太小 / 状态没有去重加大阈值间隔并记录上次通知状态状态不变不重复推送轮询任务堆积上一轮请求超时未结束调度器开启max_instances1和coalesceAPI Key 被限流请求频率过高拉长请求间隔多 Key 改为串行轮询服务器重启后任务丢失调度器没有持久化改用 systemd 管进程或使用持久化数据库存储 job推送服务挂了没有感知外部依赖单点增加本地状态文件并定时检查推送服务健康状态5. 写在最后的几个经验补充这个周重置卡目前已经在我的 Zcode 环境里跑了好几周没有出过大问题我自己对它的定位也从“监控工具”变成了“顺手用的小基础设施”。这段经历让我对大模型 API 的配额管理有了不少新的认识。限于篇幅没法把全部代码贴出来但我认为最有价值的部分已经都在上文里了。最后分享两个小技巧都是实际踩出来的经验。第一个是状态输出要坚持用纯文本文件。我之前试过用 Redis 存状态也试过直接推到数据库但最终发现最简单的quota_status.json反而是最好用的。因为它不仅可以被 Python 读取还可以用cat或jq直接在终端查看排查问题时极其方便。对于个人项目不要为了看似“正规”而引入不必要的复杂度。第二个是不要把“提醒”做成“打扰”。刚开始我把阈值拉得很高结果隔半小时就推一条消息很快我连真正的危险告警都不看了。后来我把预警阈值调整到 20%并且让模块在剩余额度高于 50% 时完全闭嘴体验才正常。做自用工具最高原则不是功能多而是“该响的时候一定响不该响的时候绝对安静”。这个度需要在实际使用中慢慢找。