API 余额监控系统 — 方案设计

一、背景与目标

1. 问题

2. 目标

• 统一展示 DeepSeek 和火山引擎的 API 余额
• 支持历史余额趋势图（类似 K 线的可视化）
• 支持火山引擎消费明细查询（按天、按产品）
• 自动每日快照，积累历史数据
• 集成到现有网站（unified_server.py）

3. 范围

• 包含：余额查询、历史趋势、消费统计、每日自动快照
• 不包含：充值管理、发票管理、子账号管理等后台复杂功能

二、一句话结论

通过「火山引擎费用中心 API 直接拉历史账单 + DeepSeek 每日快照余额」的混合方案，可以实现双平台余额监控与趋势图展示。火山引擎有完整的按天成本 API（最多 24 个月历史），DeepSeek 没有公开用量 API，通过每日余额快照差值推算消耗。

三、整体架构

四、数据来源分析

1. 火山引擎（最丰富）

可用 API（费用中心 OpenAPI）：

• QueryBalanceAcct — 查询当前账户余额
• ListAmortizedCostBillDaily — 查询按天成本账单（核心！）
• ListBillDetail — 分页查询账单明细
• ListBillOverviewByProd — 按产品汇总账单

数据能力：

• 历史范围：最多 24 个月
• 粒度：按天（DailyAmortizedPayableAmount）
• 维度：按产品、按计费模式、按实例
• 字段：原价、优惠价、应付金额、实付金额、代金券抵扣等

限制：

• 单账号 5 QPS
• 按天接口建议用 AmortizedDay 单日查询提升性能

2. DeepSeek（最有限）

可用 API：

• GET https://api.deepseek.com/user/balance — 查询当前余额

数据能力：

• 当前总余额（按币种）
• 代金券/充值金分开
• 是否可用状态

限制：

• ❌ 无历史余额查询 API
• ❌ 无消费明细 API
• ❌ 无 Token 用量统计 API

应对方案：

• 每日快照余额到数据库
• 通过前后两天余额差值计算当日消耗
• 从接入日开始积累数据，无历史回溯能力

五、数据库设计

1. api_balance_daily — 余额日快照表

记录每个平台每日的余额快照，用于绘制余额趋势图。

> 联合主键：(date, platform)

2. api_cost_daily — 消费明细表

记录每日消费明细（主要来自火山引擎）。

> 索引：(date, platform)、(date, platform, product)

3. 设计原则

• 遵循项目现有规范：表名前缀 api_、使用 INSERT OR REPLACE 幂等写入
• 放在统一的 quant.db 中，不新建数据库
• 原始数据完整保留（raw_data 字段），方便后续扩展

六、模块设计

1. 核心模块 api_balance_monitor.py

现有功能（已实现）：

• get_deepseek_balance() — DeepSeek 当前余额查询
• get_volcengine_balance() — 火山引擎当前余额查询
• get_all_balances() — 全部余额汇总（带 1 小时内存缓存）

新增功能：

A. 火山引擎历史账单

• get_volcengine_daily_cost(date) — 获取指定日期的按天成本账单
• get_volcengine_cost_range(start_date, end_date) — 获取日期范围内的按天成本
• backfill_volcengine_cost(days=90) — 回填历史账单数据（默认最近 90 天）

B. 余额快照

• save_daily_snapshot(date=None) — 保存当前余额为日快照
• get_balance_history(days=30, platform=None) — 查询余额历史
• get_daily_cost_history(days=30, platform=None) — 查询日消耗历史
• get_cost_by_product(days=30, platform=None) — 按产品汇总消费

C. 定时任务

• start_scheduler() — 启动后台定时任务线程
• 每日凌晨 2:00 自动执行：

1. 拉取前一天火山引擎账单并存入 DB 2. 对 DeepSeek 和火山引擎做余额快照

2. 数据库模块 db/api_balance.py

按照项目现有 DB 规范，新建 api_balance.py 管理余额相关表：

• init_api_balance_tables() — 初始化表
• save_balance_snapshot(data) — 保存余额快照
• get_balance_history(days, platform) — 查询余额历史
• save_daily_cost(data_list) — 批量保存日消费数据
• get_cost_history(days, platform) — 查询消费历史
• get_cost_by_product(days, platform) — 按产品汇总消费

3. 网页模块 unified_server.py

新增路由：

4. 前端展示（/balance 页面）

新增图表（Plotly）：

A. 余额趋势图

• 双 Y 轴或分图：DeepSeek 余额 + 火山引擎余额
• 支持时间范围选择（7天/30天/90天/全部）
• 悬停显示当日余额和消耗

B. 每日消耗柱状图

• 每日总消耗
• 堆叠柱状图：按平台/按产品
• 支持时间范围选择

C. 产品消费占比饼图

• 火山引擎各产品消费占比
• 时间范围可切换

D. 预估可用天数

• 按近 7 天平均消耗估算
• 按近 30 天平均消耗估算
• 分别计算每个平台的预估

七、实施步骤

1. 数据库层

• 新建 db/api_balance.py，定义两张表的 DDL 和 CRUD 函数
• 在 db/core.py 的 init_all_tables() 中注册
• 运行测试验证表创建成功

2. 监控模块扩展

• 在 api_balance_monitor.py 中新增火山引擎按天成本查询
• 新增余额快照保存与查询函数
• 新增历史回填函数
• 新增定时任务线程

3. 测试回填

• 回填火山引擎最近 90 天账单
• 验证数据完整性
• 验证余额快照逻辑

4. API 层

• 在 unified_server.py 中新增历史数据 API 路由
• 测试 API 返回格式

5. 前端展示

• /balance 页面嵌入 Plotly 图表
• 余额趋势图
• 日消耗柱状图
• 产品占比饼图
• 预估可用天数

6. 文档更新

• 更新本文档（实现细节）
• CLAUDE.md 中概览保持不变

八、关键技术点

1. 火山引擎 SDK 调用注意事项

• SDK 的 get() 方法返回的是 JSON 字符串，不是 dict，需要 json.loads()
• host 必须设为 open.volcengineapi.com，scheme 设为 https
• IAM 用户需要有费用中心的读取权限
• 按天账单接口 ListAmortizedCostBillDaily 的 Version 也是 2022-01-01

2. DeepSeek 消耗推算

• 无历史数据，从接入日开始积累
• 日消耗 = 当日余额 - 前日余额（注意：充值时会跳变，需标记）
• 余额下降为消耗，上升为充值/调账

3. 定时任务实现

• 使用 threading.Thread + while True + time.sleep 实现
• 启动时检查今天是否已快照，未快照则立即补拍
• 写入失败不阻断主流程（try/except 包裹）

4. Plotly 图表

• 使用 plotly.graph_objects 生成图表 HTML
• 嵌入到 /balance 页面中
• 支持响应式布局

九、风险与限制

1. 数据不完整风险

• DeepSeek 只能从接入日开始记录，无历史数据
• 火山引擎账单可能有延迟（T+1 或更晚）

2. API 限流风险

• 火山引擎费用中心 5 QPS，回填时注意控制频率
• DeepSeek 余额接口限流未知，不要频繁调用

3. 权限风险

• IAM 用户的 AK/SK 需要有费用中心读取权限
• 如果权限不足，接口会返回 403

4. 数据准确性

• DeepSeek 通过余额差值推算消耗，可能因充值、调账、过期等产生误差
• 火山引擎账单有分摊逻辑，与实时扣费可能有时间差

十、后续可扩展方向

• 告警功能 — 余额低于阈值时自动推送 Server酱 消息
• 更多平台 — 接入 OpenAI、Anthropic、阿里云百炼等
• Token 级统计 — 如果某个平台提供了 Token 用量 API，接入展示
• 预算管理 — 设置月度预算，超支预警
• 多账号管理 — 支持多个 API Key 分别统计