SpendGuard — LLM 成本管家

独立审计 + 预算控制 + 成本优化的本地优先工具。不把你的 API key 或调用数据交给任何第三方——数据不出你的机器。

定位：主流 LLM 观测工具（Helicone / Langfuse / LangSmith）只告诉你「花了多少」，我们做的是「别被多收 + 别花冤枉钱」。

安装

# 本地安装（开发模式）
pip install -e .

# 可选：本地 token 重数（推荐）
pip install -e ".[tokenize]"

tokenize 可选依赖装 tiktoken（官方 BPE），用于「本地 token 重数」。若网络受限， 可预下载词表到 ~/.cache/tiktoken/（见文末 FAQ）。

三个子命令

1. spendguard audit — 审计，抓「被多收」

spendguard audit --demo              # 用内置样例演示
spendguard audit usage.csv           # 审计自己的用量 CSV

输出「实测 vs provider 账单」的差异 + 归因（缓存双计 / token 多报 / 未知模型等）。

CSV 列：date,model,input_tokens,output_tokens,cached_input_tokens,provider_billed,note

2. spendguard optimize — 优化，主动省钱

spendguard optimize --demo
spendguard optimize usage.csv --json

输出模型降级 / 缓存优化 / 输出浪费三类建议 + 预估节省。

3. spendguard proxy — 控制，本地代理 + 预算硬熔断

spendguard proxy --mock --budget 10        # 无 key 演示
spendguard proxy --budget 50 --real        # 真实转发（需 OPENAI_API_KEY / ANTHROPIC_API_KEY）

把客户端 baseURL 改成 http://127.0.0.1:8787/v1，每条调用自动采集 usage、独立核算、 累计支出；超预算时直接 429 硬熔断（不是事后告警）。仪表盘：curl http://127.0.0.1:8787/

核心特性

• 版本化定价登记表：每个 receipt 带定价版本号 + 来源，价格缺失显式 pricing_unknown，绝不静默记 $0。
• 缓存双价正确分离：缓存 token 用 cache 价（约原价 10%），捕获 Langfuse #12306 那类缓存双计 bug。
• 本地 token 重数：用官方 tiktoken 对原始文本重数，与 provider 报告数比对。
• 预算硬熔断：超预算直接拒请求（429），「能拦住」比「能看见」值钱。

FAQ

tiktoken 词表被墙下载失败？ tiktoken 首次使用会从 openaipublic.blob.core.windows.net 下载 BPE 词表，网络受限时可手动：

mkdir -p ~/.cache/tiktoken
# 对每个编码，下载后放到 sha1(url) 命名的文件
# cl100k_base / o200k_base 两个常用

详见 spendguard/engine.py 的 MODEL_ENCODING 映射。

开发

pip install -e ".[tokenize]"   # 安装（含本地重数）
pip install pytest
pytest -v                      # 13 个单元测试
uv build                       # 打 sdist + wheel 到 dist/

目录

spendguard/
├── cli.py        # 命令行入口（audit / optimize / proxy）
├── engine.py     # 独立对账引擎（定价登记表 + cache 双价 + 本地重数）
├── optimize.py   # 优化建议层（模型降级 / 缓存 / 输出浪费）
├── proxy.py      # 本地反向代理（采集 + 熔断 + 仪表盘）
└── audit.py      # 账单审计
tests/
├── test_engine.py
└── test_optimize.py

License

MIT © OppRadar