很多人第一次在项目里碰 token,是被报错推着走的:要么 401 弹出来,要么月底账单对不上,要么被限速卡住。这时候再去翻文档,容易把 access token、计费 token、临时凭证混成一件事。这篇不解释 token 的字面定义,只讲你在实际应用里到底拿它办哪件事,怎么按需求挑,选错会在哪一步返工。
很多人头一回在项目里碰 token,都是被报错推着走的。要么半夜收到一条 401,要么月底对账发现数字差了一截,要么压测时突然被限速卡住。到这一步再去翻文档,越翻越乱,因为 access token、计费 token、临时凭证这几个词在不同平台指的根本不是一件事。这篇不解释 token 的字面定义,只讲一件事:你在应用里拿它到底办哪件事,按需求怎么挑,挑错了会在哪一步返工。
说白了一个 token 在请求里出现,通常只是为了回答三个问题之一:你是谁、你用了多少、你还能不能用。听着简单,实际做的时候最容易混的地方就在这。今天就按这三条线拆开讲,最后给一张能直接拿去对的清单。
先分清三条线:鉴权、计量、限额
这三件事在系统里是三个不同的东西,出现位置也完全不同。鉴权 token 一般待在请求头里,服务端拿它查你是谁;计量 token 是模型切出来的东西,藏在响应体或者日志里;限额 token 更偏概念,是你的账户额度、余额、速率这几个数凑在一起形成的边界。同一个词被好几家平台拿去指三件不同的事,所以你搜出来的教程经常对不上,多半就是这一层没分。
有个特别好用的判断方法:看它过期会不会让请求直接失败。会失败、报 401 的,那是鉴权;过期了请求照跑、只是后台账单数字变了的,那是计量。这个方法我在排查线上问题时反复用过,比记参数名靠谱。
| 这条线管什么 | 通常出现在哪 | 出错时的典型表现 | 先看哪里 |
|---|---|---|---|
| 鉴权:你是谁 | 请求头里的凭证字段 | 请求直接被拒,401 或 403 | 请求头拼写、凭证有效期 |
| 计量:用了多少 | 响应体用量字段、网关日志 | 请求成功但账单对不上 | 输入侧长度、缓存是否命中 |
| 限额:还能不能用 | 账户后台、网关限流层 | 充了钱还是报错、偶发被卡 | 报错码、额度与速率分别核对 |
鉴权这条路:什么时候该用短期凭证
服务端和服务端之间互调、脚本定时跑批,这种场景用长期 key 最省事。代码不进仓库、机器就你自己用、不对外暴露,硬要上一套短期凭证加刷新流程,纯粹是给自己加故障点。我见过一个 5 人小团队,本地跑数据清洗的脚本,非要照着网上教程搞刷新,结果刷新逻辑自己写挂了,脚本隔一天就失败一次,排查了两天才发现是并发刷新把旧凭证顶掉了。
但只要有浏览器、移动端、多人共用这几个条件里的任何一个,就必须换短期 token 加刷新。原因很简单:前端打包产物里藏着的东西,用户翻一下就能看到,你没法收回来。
- 先把 key 挪出代码把硬编码的 key 换成读环境变量,验证方式很简单:把代码推到仓库,搜一遍有没有那串字符。搜得到就是没挪干净。
- 再判断要不要上刷新问自己一个问题:这个凭证会出现在用户能打开的文件或网络请求里吗?不会就到此为止,会就继续往下做刷新链路。
- 刷新逻辑单独抽出来别把刷新写在每个请求里。做一个统一的取凭证入口,并发请求排队等同一次刷新结果,验证方法是并发压一下,看会不会出现随机 401。
计量这条路:真正决定账单的是输入那一侧
算钱的是模型切出来的 token,跟鉴权那个 token 完全是两码事。排查账单的时候老有人拿着请求头里的凭证去对用量,方向从一开始就偏了。同一段中文、同一张图、同一份 PDF 折算出来的量都不一样,具体口径到 /ai-dict/category/basics 对照着看,别凭感觉估。要算具体额度,用 /tools/token-price-calculator 填进去跑一遍,比拍脑袋准。
我的判断标准是:先看你的请求里有没有大段重复的前缀。有的话,先去看缓存命中情况,而不是急着换个便宜的模型。换个模型可能把效果拉下来了,重复前缀那部分钱却一分没省。这件事的顺序很关键,反着做经常白忙。
限额这条路:额度、余额、速率是三笔账
这三个词经常在报错文案里被写成一句话,但它们是三笔完全独立的账。余额是账户里还剩多少,额度是这一层允许你用的上限,速率是每秒或者每分钟能发多少条。你充了钱还报错,多半是撞了额度或速率,而不是余额不够。这时候再充一次钱,问题还在。
排查顺序建议固定下来:先看报错码定位到哪一层,再决定动作。是额度就调上限或者找管理员,是速率就拆请求或者加退避,是余额才去充值。这个顺序别乱,我吃过亏,先把钱充上了,结果报错根本没变。
- 报错里带速率字样,先看是不是瞬时并发太高,别急着改架构
- 报错指向额度,先确认是账户级还是单 key 级,两处上限可能不一样
- 只是偶尔超一次,加个重试和退避就够,改架构反而引入新问题
- 同一时刻多个服务共用一个 key,把额度分散到几个 key 上更好定位
- 余额和额度都对得上还报错,去看网关层的限流配置
按场景挑:四类需求对着看
别看概念了,直接对着场景挑。下面这四类覆盖了大部分实际情况,对不上的话就按最接近的那一类往上靠。
- 个人脚本跑批
- 长期 key 加环境变量,别写进代码,够用了
- 对外的小程序或网页
- 短期 token 加刷新,key 绝对不能出现在前端产物里
- 多人共用的内部工具
- 按人发 token,出问题时才能定位是谁在烧量
- 要统计成本的团队
- 鉴权和计量分开记录,请求日志两个字段都留,不然对账永远对不上
有一种情况要单独说:如果你既对外、又要统计成本,别指望一套 token 全解决。鉴权那侧按人发,计量那侧在网关层单独记,两边用请求 id 串起来,这是最少返工的做法。
选错之后,通常卡在这几处
把 key 写进前端打包产物,通常要到第一次上线才被发现。这时候改起来不是换个变量那么简单,整个请求链路都要动,因为调用关系已经按旧方式长出来了。所以一开始就把它挪进环境变量,顺手的事。
另一个高频误判是把额度当成余额,充了钱还报错,在那儿白等一天。还有就是刷新逻辑写在并发请求里,多个请求同时刷新,把还有效的旧凭证顶掉,表现是随机 401,日志里看着像偶发,其实是并发撞的。这几种我建议在动手前就对着清单过一遍,而不是等报错来了再回头补。
动手前对一遍这张清单
- 这个 token 会不会出现在用户能看到的地方,会的话就必须走短期凭证
- 过期之后谁来换,换了之后正在跑的请求怎么处理,想清楚再动手
- 用量按什么口径统计,能不能和账单对得上,对不上就先确认口径
- 出错时先看报错码还是先翻日志,顺序定下来,别每次都重新想
- 有没有几个服务共用一个 key,共用了就先把额度拆开再排查
清单过完还有拿不准的,去站内把对应资料翻一遍,比你现搜教程靠谱。价格和用量口径这些数字会变,别记死,用的时候现查。
下一步先看你手上这几个 token 分别在哪一层,再去模型资料库和计价工具把口径对一遍,账单对不上的问题通常在这一步就有答案。→常见问题
接口里那个 token 和我充值时看到的 token 是一回事吗
不是。鉴权 token 是通行证,计量 token 是计费单位,只是中文都译成 token。报 401 去看前者,账单对不上去看后者,混着查会一直查不到点上。
小项目有必要上短期 token 加刷新吗
看你这个 key 会不会离开你的机器。只在本机跑、代码不进仓库,长期 key 加环境变量就够;一旦代码要给别人、要上服务器、要发到浏览器,就该换成短期凭证,不然泄漏只是时间问题。
额度还有,为什么还是报错
可能是速率限制,跟额度不是一回事。先看报错码属于哪一类,再决定是等窗口、拆请求还是换通道,具体口径可以到 /models 对照各家的限制说明。
怎么估自己一个月大概用多少
先抓一周的真实请求,按输入和输出分开统计,再用 /tools/model-cost-calculator 折算。别拿官网标价直接乘次数,你实际用量里输入那侧通常占大头。
团队里几个人共用一个 key 行不行
能跑,但出问题定位不了是谁在烧量,也没法单独停掉某个人。人一多就按人发,多花的配置时间比后面查账省事。