Files
lpt-be/.agents/notes/implemented/architecture/2026-10-10-ai-usage-accounting-rules.md
T
cat-shark 27ddf8be5a docs: 规则与技能迁入 .agents/,并接入决策笔记
- roles/ 与 skills/ 迁移到 .agents/ 下,AGENTS.md 引用同步
- 收录 8 篇决策笔记到 .agents/notes/
- .rgignore 排除 archived 历史快照
2026-11-18 15:01:05 +08:00

3.6 KiB
Raw Blame History

Agent Note: AI 用量口径——null 不等于 0,计价在 lpt-ai 侧冻结

Status: implemented

Problem

lpt-ai 的调用会把 token 用量报回 lpt-be,供白名单管理员看总量与费用。这里有三个容易写错、写错还不会报错的地方:

  1. 上游有时候根本不返回 usage。如果把「没上报」记成 0,用量面板会把一批未知消耗显示成「这几次调用没花钱」, 账单与面板永远对不上,而且没人能发现差了。
  2. 价格会变。若聚合时按当期价目回算历史,改一次价历史账全部重写,月度对账失去意义。
  3. ai_usage_records 里还有 /fetch-title 这类不消耗 LLM 的记录,混进统计会把「调用次数」和「模型成本」搅在一起。

Decision

  • null 与 0 严格区分:prompt_tokens / completion_tokens 等列为 NULL 表示上游未上报,0 表示上游 明确上报为 0。不得用 0 顶替 null。unreported_usage_calls 正是靠这个区分统计出来的。
  • 计价在 lpt-ai 侧冻结:cost_usd 在任务结算时按当期价目算好随记录落库,lpt-be 只做聚合与汇率换算 (lpt.ai-usage.usd-to-cny),改价不重写历史账。
  • 统计口径只看 is_llm_call = 1:不消耗 LLM 的调用照常落库(用于调用量排查),但不进用量面板。
  • user_id 只是分组维度,不是租户列:本表在 EXCLUDE_TABLES 中,user_id 用于按用户分组与筛选; 若改成租户过滤,管理员只能看到自己触发的调用,面板等于永远是空的。
  • 上报幂等交给出库方:POST /internal/ai-usage/records 以 record_id 唯一索引去重,因此「推送成功但响应 丢失」的重复推送是安全的;失败重试由 lpt-ai 侧 outbox 负责,4xx 属确定性拒绝,丢弃该批并计数,不无限重试。

Alternatives considered

  • 在 lpt-be 侧按当期价目聚合时现算成本 — 少存一列,改价立刻全局生效。放弃是因为它把历史账变成了易变量: 一次调价会让过去几个月的报表同时变化,月初对账没有稳定基线,而账本该是只读的。
  • 把「未上报」压成 0,只留一个总数 — 面板实现最简单,表结构也少一列。放弃是因为它抹掉了「我们不知道花了多少」 这个事实:额度异常时无法区分「真的没用量」和「上游没给 usage」。
  • 让 lpt-be 反查 lpt-ai 面板取历史用量 — 不用落库,也不必设计上报协议。但面板只是最近若干条的环形缓冲, 进程重启即丢,「长期账本」这个诉求直接落空。

Consequences

  • 收益:用量面板的数字可以对账——已知消耗、未知消耗、非 LLM 调用分得开;改价不动历史。
  • 代价与已知上限:lpt-be 必须相信 lpt-ai 报来的 cost_usd,价目正确性完全取决于 lpt-ai 的 admin/pricing.ts 与节假日表(每年需更新)。出现「面板金额与上游账单对不上」时,先核 lpt-ai 的价目与峰谷窗口,再怀疑聚合逻辑。

Verification

  • 表结构与索引:lpt-be/src/main/resources/db/migration/V20261010_4__add_ai_usage_records.sql、 V20261010_5__add_user_id_to_ai_usage_records.sql。
  • 口径与 null 处理:src/main/resources/mapper/AiUsageRecordMapper.xml(is_llm_call = 1 过滤、 unreported_usage_calls 用 CASE WHEN prompt_tokens IS NULL),AiUsageServiceImpl 的聚合。
  • 白名单与令牌:AiUsageProperties、WebMvcConfig 对 POST /internal/ai-usage/records 的排除。