Redis Lua原子预扣：大模型API网关配额防透支实践

做网关层大模型API治理有一段时间了最让我记忆深刻的是某次月底账单事故内部一个测试项目开了每日100万token的配额结果一个压测脚本十几分钟就把当天配额烧穿等发现时账单已经飘红。事后复盘问题不在于没做限流而在于限流逻辑用的是“先调用、后记账”高并发下注定透支。后来我逐步落地了一套基于Redis Lua原子预扣与多租户治理的方案核心解决的是“调用发生之前就把配额锁住”的问题这篇文章把设计思路、Lua脚本、租户模型和踩过的坑全部拆开讲适合正在做AI网关、API平台或者给企业做大模型应用封装的后端同学参考就算只是个人对接某个大模型接口里面预扣的思路也可以直接借鉴。1. 配额透支是怎么发生的从一次超支账单讲起1.1 后记扣减模式的竞态漏洞大多数团队最开始做API配额控制用的都是“后记扣减”。逻辑很简单请求进来计数器加1判断加完之后是否超过阈值超过就拒绝。听起来没问题但在多实例部署下这个流程存在一个经典竞态窗口。两个请求同时到达网关的不同实例它们各自执行“读计数器、判断、加1”三步。假设阈值是1000计数器当前是999请求A读到999请求B也读到999两边都判断“999小于1000可以放行”然后各自把计数器更新为1000。最终计数器变成1000但实际放行了1001个请求。加了Redis的INCR命令也一样INCR本身是原子的但“INCR之后判断是否超限、超限要不要回滚”这两步没法做到整体原子并发一上来照样出问题。单机场景下可以用并发原语串行化但网关是分布式服务计数器放在Redis里跨实例的“读-改-写”必须依赖原子原语。这也是整个防透支问题的起点只要不是原子操作就存在超发可能。1.2 大模型API和普通API在配额控制上的本质差异做过普通REST API限流的人可能觉得大模型API没什么特殊。实际差异非常大。普通API的单次消耗基本可预测一次请求对应一次数据库查询或者一次文件读取资源消耗相对固定。大模型API完全不同上游按token计费一次对话可能消耗几百token也可能因为上下文拉满或者生成长度太长消耗几万token。更麻烦的是输入token在请求发出前还能估算输出token只能等完整响应拿到usage之后才知道。这意味着按请求次数限流完全没意义。用户一个请求可能烧掉你几千token也可能烧掉你几万token次数限制防不住成本失控。只有按token做配额才真正关联系到钱。大模型请求还有一个特点耗时特别长。普通API大多几百毫秒返回大模型流式生成动辄几十秒甚至几分钟。预扣了配额之后中间任何异常——超时、断连、上游500、客户端中途取消——都会让预扣记录迟迟无法清理。所以这套方案不能只做“预扣”还得配套释放流程和补偿任务这是普通限流方案里完全不需要考虑的事情。2. Redis Lua原子预扣的设计逻辑从竞态条件到脚本选型2.1 先读再写为什么一定会出问题要理解Lua脚本的价值先看最直觉的错误做法。用伪代码描述balance redis.get(balance) # 请求A读到100 balance redis.get(balance) # 请求B也读到100 balance balance - 50 # 请求A计算得到50 balance balance - 50 # 请求B计算得到50 redis.set(balance, balance) # 请求A写回50 redis.set(balance, balance) # 请求B也写回50两个请求各消耗50最终余额却是50而不是0。这不是Redis的问题是“读-改-写”不是原子操作的问题。Redis官方其实有WATCH/MULTI/EXEC的乐观锁方案可以解决一部分问题但配额预扣的逻辑不是简单的DECRBY而是“余额够不够、不够就整体中止、够才扣减”的条件操作。WATCH方案每轮失败都要重试高并发下重试风暴带来的开销成倍放大而且代码复杂度很高。2.2 Lua脚本比MULTI事务强在哪Redis的Lua脚本把多条命令打包成一个整体执行脚本运行期间Redis服务器不会处理其他客户端的命令基于单线程调度模型实现真正的原子性。这不只是“一组命令按顺序执行”更重要的是脚本内部可以做条件分支和中间计算。比如这样一段预扣逻辑读余额判断“余额减预估消耗是否小于0”小于0返回失败大于等于0才扣减。MULTI事务做不到这一点它只是把命令排队在EXEC之前不会真正执行没法根据前一条命令的结果决定后面要不要执行。Lua脚本可以因为它在执行时已经拿到了真实的中间值。另外脚本里的命令全部在Redis内存中直接执行不经过网络往返性能比“客户端发多条命令”快得多。一个预扣脚本的耗时通常在微秒级别对Redis单线程的影响可控。这也是我选型时最看重的一点原子性、条件分支、高性能三者同时满足。2.3 为什么不用数据库落库做扣减有人会问配额扣减用MySQL加行锁也能做为什么非要Redis我的经验是两个字路径。配额扣减是网关上的高频写路径。高峰期每秒几千次甚至上万次扣减MySQL的行锁在并发竞争下会成为瓶颈还要考虑连接池、磁盘IO、主从同步延迟。更关键的是配额天然带时间窗口语义——日配额、小时配额、分钟配额Redis的EXPIRE和TTL直接对应这些场景数据库要清理过期窗口还得专门写定时任务。Redis在这里的价值不是把账算得更准而是把这笔账算得更快、更扛并发。最终的账单准确性靠定时对账兜底这个思路要明确。3. 预扣模块落地数据结构、Lua脚本与请求生命周期3.1 Redis键设计与配额字段预扣方案需要一个核心Hash结构我是这样设计的quota:{tenant}:{project}:{apiKey}:{window}字段说明字段含义示例total当前窗口总配额1000000used已实际结算消耗320000pending已预扣但未确认/未释放15000available当前窗口可用总额1000000注意这里有个关键点为什么要有pending而不是在请求前直接把used扣掉因为大模型实际消耗的token数不确定。如果在调用前就扣used预估消耗100但真实消耗80那20个token就永久损失了。有了pending就能做到“调用前锁定预估额度调用后按实际消耗结算”多退少补。可用额度的计算公式是available total - used - pending预扣操作等价于检查available是否大于等于预估消耗是则增加pending确认操作等价于把pending转为used同时抵扣实际消耗。window字段我这里不细讲具体格式实践上我倾向直接用日期做窗口后缀如20250607每天一个key到期自然过期不需要额外清数据。分钟级、小时级的窗口可以并行做多个key各管各的维度。3.2 预扣、确认、释放三段式Lua脚本下面给出三个核心脚本代码是简化版重点演示机制。预扣脚本-- KEYS[1]: quota:{tenant}:{project}:{apiKey}:{window} -- ARGV[1]: reserve_tokens预估消耗含安全系数 local available tonumber(redis.call(HGET, KEYS[1], available) or 0) local used tonumber(redis.call(HGET, KEYS[1], used) or 0) local pending tonumber(redis.call(HGET, KEYS[1], pending) or 0) if available - used - pending tonumber(ARGV[1]) then return -1 end redis.call(HINCRBY, KEYS[1], pending, ARGV[1]) return 1确认结算脚本-- KEYS[1]: 同上 -- ARGV[1]: reserve_tokens预扣时使用的估算值 -- ARGV[2]: actual_tokens上游usage里返回的实际消耗 redis.call(HINCRBY, KEYS[1], used, tonumber(ARGV[2])) redis.call(HINCRBY, KEYS[1], pending, -tonumber(ARGV[1])) return 1释放脚本-- 释放预扣但最终未消耗的配额 -- KEYS[1]: 同上 -- ARGV[1]: reserve_tokens local pending tonumber(redis.call(HGET, KEYS[1], pending) or 0) if pending tonumber(ARGV[1]) then redis.call(HINCRBY, KEYS[1], pending, -tonumber(ARGV[1])) return 1 end return -1Python侧调用示例import redis r redis.Redis(hostlocalhost, port6379, decode_responsesTrue) reserve_script r.register_script( -- 预扣Lua脚本 ) confirm_script r.register_script( -- 确认结算Lua脚本 ) release_script r.register_script( -- 释放Lua脚本 ) reserve_script(keys[quota:tenant1:proj1:key1:20250607], args[1500])调用方必须保证每个请求严格按照“预扣一次最终确认或释放一次”的节奏。确认和释放是互斥的二选一不能两个都做也不能都不做。否则pending字段会越积越多最终把整个配额池撑死。3.3 按token估算预扣而不是按请求次数预扣值怎么来决定了防透支的效果。OpenAI兼容接口里请求体中包含messages或者prompt可以用tokenizer粗略估算输入token数。输出token无法预知但请求参数里通常有max_tokens如果用户没传就按模型上下文上限处理。预扣值建议这样算estimated estimate_input_tokens(messages) max_tokens reserve_tokens estimated * 1.25这个1.25的安全系数很关键。不同模型的tokenizer算法不一样估算存在误差再加上某些代理场景下会往上下文里注入系统提示词实际输入比用户传来的内容更大。系数设太小防不住估算偏差设太大又会导致配额虚占、整体利用率下降。我给自己的项目定的1.25跑了一个季度误差率控制在1%以内算是个经验值。实际消耗的获取依赖上游返回的usage字段。如果你的网关做的是流式转发不用担心流式响应结束时依然能拿到usage可以正常触发确认结算。取usage里的prompt_tokens加completion_tokens作为actual_tokens传给确认脚本。3.4 超时释放与补偿任务预扣成功但请求中途失败比如上游超时、网络断开、连接池满、API Key失效返回401这些场景都必须释放pending。释放分两条路径同步释放在请求结束的finally块里根据本次预扣值调用释放脚本。这条路径覆盖90%的情况。异步补偿进程崩溃、机器宕机、客户端连接一直挂着导致finally不执行pending就会永久占用。必须有一个定时任务扫描“预扣时间超过阈值且仍未确认”的凭证强制释放。实现方式我推荐用Redis ZSet存预扣凭证成员是请求ID分数是预扣时的Unix时间戳。补偿任务用ZRANGEBYSCORE查出超过阈值的凭证——阈值通常设为“模型最长响应时间缓冲”比如10分钟——逐个执行释放脚本并删除凭证。增量扫描的思路对于量大的场景也适用。4. 多租户治理配额如何在租户、项目、密钥之间分配4.1 租户层级模型与配额叠加关系多租户治理不是给每个API Key配个额度就完了。真实平台上的结构通常是三层租户入驻团队或企业有自己的组织ID配额上限最高项目一个租户下多个项目对应不同业务线互相隔离API Key项目下多个key用于开发、测试、生产环境隔离也方便单独吊销。请求进来时要同时过三层配额检查才能放行。租户级总配额决定这个租户最多能烧多少资源项目级配额在租户范围内进一步细分API Key级配额最细。某一层超了就直接拒绝避免一个项目把整个租户的月预算烧光。Redis key设计上建议直接按层级拆开quota:tenant:{tenantId}:{date} quota:tenant:{tenantId}:project:{projectId}:{date} quota:tenant:{tenantId}:project:{projectId}:key:{apiKey}:{date}多key的好处是排查问题很方便出故障时直接看某一层的数据就行。代价是key数量多但对Redis来说不是压力。4.2 流控策略与优先级不只是粗暴拒绝配额防透支解决“能不能用”的问题流控解决“怎么用更平滑”的问题。两者要配合不能互相替代。固定窗口实现简单但会有突刺尤其是每分钟刚开始的前几秒可能瞬间打满。滑动窗口用ZSET记录请求时间戳过滤旧记录后计数平滑很多但每次请求多了几个命令的开销。令牌桶负责平滑速率预扣负责成本封顶这两个配合效果最好。不同租户套餐可以这样配置租户套餐日配额RPS限流超额策略免费50万token5 QPS直接拒绝标准500万token50 QPS排队等待企业5000万token500 QPS排队熔断保护排队等待是比直接拒绝更友好的策略。低优先级租户配额不足时直接拒绝高优先级租户进入等待队列等pending释放后再放行。这样在大促或集中调用场景下核心业务不会被一个测试脚本挤垮。4.3 成本归属、审计日志和密钥轮换多租户治理还要做成本归属。每次调用都要记录租户、项目、API Key、模型、输入token、输出token、估算费用异步写入审计日志这样月底才能按租户分摊账单。我见过不少团队漏掉这一步结果超支了都不知道是哪家租户干的。密钥轮换也不能省。平台上要支持“旧key立即失效、新key无缝切换”避免多个业务共用一个key导致无法追溯。API Key本身也属于租户资源在配额治理里要单独建立一层。配额预警是治理体验的关键。不要等额度烧到0才发通知在剩余10%、5%的时候就应该触发webhook或邮件让租户有时间调整。预警阈值可以做成租户可配置的企业客户通常对成本更敏感。5. 边界条件与可靠性兜底Redis故障、时钟漂移和集群限制5.1 Redis Cluster对Lua脚本的限制hash tag和动态key如果Redis是单机模式上面脚本直接跑没问题。一旦上了集群必须考虑slot分布问题。集群模式下Lua脚本里访问的所有key必须落在同一个hash slot否则运行时报CROSSSLOT错误。解决方案是给key加hash tag例如把quota:tenant1:proj1:key1:20250607改成quota:{tenant1:proj1:key1}:20250607花括号里的内容参与哈希计算这样同一租户下同一个API Key的所有窗口key都会落在同一个slot脚本可以正常跨多个key操作。同时要提醒一点脚本内部不能动态拼接生成key名所有key必须由调用方通过KEYS数组传进来这是集群模式下Redis的要求。5.2 主从切换时预扣记录丢失的补偿策略Redis主从切换总是绕不开的话题。切换期间几秒钟的写入丢失如果刚好丢了预扣记录就会出现“实际烧了但配额没扣”的透支。任何分布式系统都很难做到严格强制配额控制的目标是把透支限制在可接受范围而不是追求永不透支。我的兜底思路是两级网关本地内存缓存一份“本机成功预扣的凭证”定期同步到持久化存储MySQL或ES对账任务每天跑一次“上游账单消耗 vs Redis配额消耗”的对比差值超过阈值就拉日志定位。历史上我们出现过两次主从切换导致的少量透支都是靠对账发现的误差不超过几千token影响可控。5.3 对账Redis计数和上游账单怎么拉平对账的口径要提前定义清楚。上游账单给出的是某租户按模型维度统计的实际消耗token和费用Redis统计给出的是网关视角的消费。两者之间的误差不可避免来自预扣溢出、异常补偿、计费舍入等。实际操作中我们这样处理按“租户模型日期”三个维度做每日对账误差率允许范围定在5%以内。超过5%说明可能存在逻辑bug比如usage解析错误、某个分支漏了确认或释放。误差率本身可以做成监控指标发布新版本之前先观察一天对账数据确认没引入偏差再全量推。6. 真实踩坑记录三个配额治理事故的完整排查链路6.1 事故一pending长期不释放配额被“幽灵占用”现象某个项目的可用额度越来越小但实际请求量并没有增长。排查过程分了三步。先看Redis里的配额Hash发现used不高pending却持续增长。再查网关日志确认请求确实完成、上游返回正常。最后看代码问题出在释放逻辑只放在了成功分支异常分支里漏了finally释放。这个bug很隐蔽因为看起来请求都正常完成了但只要有一次上游连接异常或者客户端半路断开pending就永久挂着。日积月累就成幽灵占用。修复方案是释放逻辑放到泛型finally里覆盖所有分支增加ZSet补偿任务超时强制释放监控pending占available的比例超过20%告警。6.2 事故二分布式压测打热单个配额key现象压测期间Redis某个节点CPU打满整个平台请求变慢不只是压测租户受影响。定位过程先是看到Redis节点监控CPU飙升然后发现所有流量都指向同一个租户的配额key。Redis是单线程模型同一个key的命令全在一个节点排着执行再快也扛不住集中流量。修复思路做了三件事一是把配额Key按分钟窗口拆分让访问分散到不同Key二是热门租户的配额在本地缓存50ms批量更新大幅减少对Redis的读压力三是把这类热点租户的Key分布到集群不同节点。6.3 事故三月底对不上账最后定位到时钟偏差现象某租户的上游账单消耗和Redis统计结果误差超过10%持续了一个月每天都有偏差但方向不定。一开始怀疑usage解析看了代码没有问题。又怀疑确认结算漏执行日志核对也没问题。最后排查到固定窗口的时间戳用了网关机器本地时钟几台服务器时钟漂移不一致导致部分请求被算到了相邻时间窗口日维度对账自然对不上。修复很简单统一用Redis的TIME命令获取服务器时间或者在所有网关机器上做NTP同步同时监控时钟偏移量。这个坑提醒我所有时间相关逻辑必须集中一个时间源分布式系统里最容易忽略的就是机器本地时钟。最后分享几个个人实操心得。预扣系数1.25是个不错的起点但要根据自己业务的实际误差率调整误差率长期偏高就先查tokenizer估算逻辑不要急着调系数。补偿任务的扫描频率别设太短1分钟一次就够了避免连续执行ZRANGEBYSCORE占用Redis主线程。最重要的是超额处理别一刀切拒绝在资源允许范围内留一个排队等待或者降级到替代模型的“软拒绝”路径租户侧的体感会好非常多成本控制和用户体验之间需要做平衡。