请求前检查
<10msGET /budget/{id}/check — 在 Token 消耗前拦截
开源 · v2.5.0
在账单到来之前 拦住失控的 Agent
在每次 LLM 请求前调用 GET /budget/{id}/check — 亚秒级拦截、可自托管、100 万+ 事件/秒。
<10ms 预算检查 100 万+ eps Full 模式 开放规范 SDK + Schema
bash
git clone https://github.com/10kshuaizhang/fluxmeter.git
cd fluxmeter
make demo传统计费系统不是为 Agent 循环设计的
Token 消耗速度远超传统计量系统的反应能力。
痛点
一个 Agent 循环在不到一分钟内烧掉了约 200 美元的 Token，因为用量只是周期性检查。等系统发现时，预算早已耗尽。
如果你的客户预付费购买 Token，需要在额度耗尽的瞬间立即切断——而不是 30 秒之后——你需要请求前拦截，而不是批量分析。
FluxMeter 的方案
在每次 LLM 调用前检查预算，调用后再上报用量。流式场景下先预留估算额度，流结束后对账。
available = balance − held
有效余额会扣除进行中的流式预留——客户在下次调用前就会被拦截，而不是等延迟的批量查询才发现。
双层预算拦截
请求前检查在 Token 消耗前阻止支出，窗口后扣减保持余额准确。
窗口后扣减
10–15sFlink 聚合 → 原子 Lua 扣减 → 终止信号
| 层级 | 延迟 | 作用 |
|---|---|---|
| 请求前检查 | <10ms | GET /budget/{id}/check — 在 Token 消耗前拦截 |
| 窗口后扣减 | 10–15s | Flink 聚合 → 原子 Lua 扣减 → 终止信号 |
标准流程
- 1.GET /budget/{id}/check
- 2.若允许 → 发起 LLM 调用
- 3.POST /ingest 上报 Token 数量
流式流程
- 1.POST /budget/{id}/reserve
- 2.流式输出 Token
- 3.POST /ingest + POST /reconcile
bash
# Set $50 budget, alert at $5 remaining
curl -X POST localhost:8000/budget/cust_123 \
-H 'Content-Type: application/json' \
-d '{"balance_usd": 50.0, "alert_threshold_usd": 5.0, "max_rpm": 100}'
# Pre-request check — call BEFORE every LLM request
curl "localhost:8000/budget/cust_123/check?estimated_cost_usd=0.05"
# → {"allowed": true, "balance_usd": 47.23, ...}
# → {"allowed": false, "reason": "budget_exhausted"}三条部署路径
Lite 模式一分钟上手，流量增长后再扩展到 Flink。
Lite
默认make demo API → Redis Lua，无需 Flink。适合 side project 和 <10 万 eps。
- <10ms 预算检查
- Rollup worker
- Stripe Meters 导出
Full
高吞吐make demo-full Kafka → Flink → Redis，10 万–100 万 eps，支持 Span 归因。
- 100 万+ eps 突发
- DLQ 重放
- 预算终止信号
SaaS
多租户make start-saas 控制面 :8001，租户 CRUD + 套餐限制脚手架。
- 租户隔离
- API Key
- 套餐限制
三种集成方式
Python SDK、HTTP API 或直接 Kafka — 选择适合你的技术栈。
python
from fluxmeter import FluxMeter
meter = FluxMeter(kafka_brokers="localhost:9094")
meter.track_openai("cust_123", openai_response, latency_ms=1200)完整 API 参考见 GitHub docs OpenAPI 规范见 spec/openapi/openapi.yaml
流式优先架构
增量聚合、原子 Lua 扣减、Exactly-once Sink。
[你的应用] → [Kafka] → [Flink: 聚合] → [Redis] → [API]
│ │ │ │
SDK/HTTP 预算告警 按 (客户,模型) 预算检查
事件上报 ← 终止信号 键聚合 (三层缓存)
10 秒窗口 增量聚合
O(keys) 内存，而非 O(events)
原子 Lua 扣减
微美元精度 — 无浮点累积误差
Sink 幂等
SHA-256 + SET NX — 重放不会重复计费
三层检查
缓存 → Redis → 失败策略 — 不阻塞热路径
设计 rationale 见 docs/DESIGN.md
规模化压测验证
make load-test 从 1 万到 100 万事件/秒的分级基准测试。
本地 docker-compose
1 万 eps 均值 ~9K / 峰值 ~18K
5 万 eps 均值 ~49K / 峰值 ~92K
50 万+ 目标 均值 ~40–45K
参考集群 (2 TM)
1 万 eps 稳定
5 万 eps 稳定
50 万+ 目标 50 万持续；100 万突发
| 环境 | 1 万 eps | 5 万 eps | 50 万+ 目标 |
|---|---|---|---|
| 本地 docker-compose | 均值 ~9K / 峰值 ~18K | 均值 ~49K / 峰值 ~92K | 均值 ~40–45K |
| 参考集群 (2 TM) | 稳定 | 稳定 | 50 万持续；100 万突发 |
方法论与配置见 docs/load-testing.md
OpenCore 布局
Spec 和 SDK 是产品界面，Engine 是参考实现。
Spec
spec/ 事件 Schema、OpenAPI、语义约定
SDKs
sdk/ Python (PyPI) + JS 客户端
Community
contrib/ Provider 映射、定价、连接器
Engine
src/ Flink 参考实现
| 层级 | 路径 | 用途 |
|---|---|---|
| Spec | spec/ | 事件 Schema、OpenAPI、语义约定 |
| SDKs | sdk/ | Python (PyPI) + JS 客户端 |
| Community | contrib/ | Provider 映射、定价、连接器 |
| Engine | src/ | Flink 参考实现 |