- roles/ 与 skills/ 迁移到 .agents/ 下,AGENTS.md 引用同步 - 收录 8 篇决策笔记到 .agents/notes/ - .rgignore 排除 archived 历史快照
3.6 KiB
3.6 KiB
Agent Note: AI 用量口径——null 不等于 0,计价在 lpt-ai 侧冻结
Status: implemented
Problem
lpt-ai 的调用会把 token 用量报回 lpt-be,供白名单管理员看总量与费用。这里有三个容易写错、写错还不会报错的地方:
- 上游有时候根本不返回
usage。如果把「没上报」记成 0,用量面板会把一批未知消耗显示成「这几次调用没花钱」, 账单与面板永远对不上,而且没人能发现差了。 - 价格会变。若聚合时按当期价目回算历史,改一次价历史账全部重写,月度对账失去意义。
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的排除。