quotaforge

QuotaForge

QuotaForge（QF）是给 Agent 用的大模型网关，用 Go 写成。Agent 和应用经它调用 OpenAI 兼容的上游模型。QF 负责每个账户能用多少、用得多快；重试不重复计费；调用结果不明时，事后能把账对清。

• OpenAI 兼容转发：/v1/chat/completions（含 tools）和 /v1/embeddings。只把模型别名换成上游的模型名，其余字节原样转发；上游的响应原样返回。
• 额度账本：每个账户一个 token 上限。每次调用先在 MySQL 里按估算预留，结束后按上游报的用量结算。额度只以 MySQL 为准：并发预留不会超扣，qfctl verify 随时可以校验账本的不变量。
• 幂等：请求带 Idempotency-Key 时，同一个键的重试不会多扣额度。结算过的调用原样重放；结果未知的调用不会重新执行。
• 未知用量的恢复和对账：上游超时、进程被杀时，用量不补 0，记成“未知”，继续占着预留。后台回收接手卡住的调用；运维拿上游的账单或 QF 的日志结清。
• 共享限流：Key、账户、上游三层，每层限每分钟的请求数和 token 数。令牌桶放在 Redis 里，由 Lua 脚本原子地扣，多个实例共享同一组桶。
• 多个实例：实例之间不共享内存状态，同时跑也不会超扣、不会重复执行同一个键、不会重复回收。附带跨实例的检查脚本和压测数据。
• 嵌入缓存（可选）：同一个账户的相同嵌入请求直接用之前结算过的响应，不调上游、不扣额度，账本里记一条 CACHED。缓存放在单独的 Redis 里；同一个实例里并发的相同请求只回源一次，过期时间加随机抖动；缓存坏了只算没命中。

flowchart LR
    client["Agent / 应用<br/>（例如 QueryShield）"]
    subgraph qf["QuotaForge（一个或多个实例）"]
        direction TB
        check["鉴权、解析、估算"] --> admit["限流准入"] --> cache["嵌入缓存<br/>（命中就记 CACHED、不预留）"] --> reserve["预留额度<br/>（幂等判断）"] --> intent["发送意图"] --> forward["转发<br/>（只换模型名）"] --> settle["收尾结算"]
        bg["后台：回收卡住的调用、<br/>清理过期的幂等记录"]
    end
    client -- "OpenAI 兼容接口<br/>Bearer QF Key" --> check
    forward -- "上游 Key" --> upstream["上游模型<br/>（OpenAI 兼容）"]
    admit --> redis[("Redis<br/>共享令牌桶")]
    cache --> rcache[("Redis（单独的）<br/>嵌入缓存")]
    reserve --> mysql[("MySQL<br/>额度、账本、调用、幂等记录")]
    intent --> mysql
    settle --> mysql
    bg --> mysql
    qfctl["qfctl<br/>迁移、账户、Key、对账"] --> mysql

已经完成

进行中（M6）：流式转发已经可用：SSE 逐个转发、按流里的 usage 结算、中途断开照常结算（流式）。多上游与熔断已经可用：一个别名多个目标、按权重分流（灰度、主备），连不上时换上游，按上游熔断（多个上游）。Embedding 缓存已经可用：按账户隔离的精确缓存、并发的相同请求只回源一次、过期时间加抖动、命中记 CACHED（嵌入缓存）。计划中：用量事件。

快速开始

要 Docker（带 Compose）和 curl。在项目根目录下运行。以下命令起 QF、账本数据库、Redis 和 QF 自己的假上游，不调用任何付费模型：

docker compose up -d --build --wait   # 等到健康为止
docker compose run --rm -T --no-deps qfctl account create -name local -limit 100000
KEY=$(docker compose run --rm -T --no-deps qfctl key issue -account local -models qs-fake-upstream-v1,fake-tool-call | sed -n 's/^key: //p')
curl -sS http://127.0.0.1:8080/healthz
curl -sS -i http://127.0.0.1:8080/v1/chat/completions -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"model":"qs-fake-upstream-v1","messages":[{"role":"user","content":"你好"}],"max_tokens":64}'
docker compose run --rm -T --no-deps qfctl usage -account local   # 已消费就是上面那次调用的 usage
docker compose down -v

• 端口只发布在 127.0.0.1:8080。账本数据库用 deploy/test-only-db/ 下写明“仅测试”的密码；接真实上游时，脚本每次随机生成数据库密码（见运行和运维）。
• 更多请求的写法（带 tools 的聊天、嵌入、PowerShell）见用 curl 调用。

和 QueryShield 的关系

QueryShield（QS）是一个查询 Agent，QF 是它的模型出口：QS 的聊天和嵌入都经 QF 调上游，一次 run 里的调用带上 run 编号（X-Run-Id）和幂等键。两边的联调脚本跑 QS 的整套演示，再拿 QF 的账本逐个 run 核对调用次数和用量，见接 QueryShield。

文档

许可证

MIT