荒天帝炼大模型网关-第14境-至尊境-金璇波纹功-计量成本归一
# 标准化 Usage 与 Cost:让一次请求从用量到账单全链可追溯 > 上游给了用量却不给账单,账单来了又对不上明细。 ```text [读者] 正在自建 LLM Gateway 的 Java 后端工程师 [痛点] 上游 usage 时有时无,价格散落在代码里,月账单永远对不上 [现在读] 网关已能路由、重试、熔断,下一步必须把成本算清楚 [读完] 能落一条 usage 归一 → 定价快照 → 微美元计价 → 日聚合的可追溯链路 ``` ```text [旧方案] 各 Provider Adapter 自己读 usage,cost 用 double 现算现丢 | v [新需求] 按 Project/Key/LogicalModel/Provider/Deployment/Date 六个维度出账 | v [冲突] usage 是可选字段、价格会变、浮点会漂、流式默认不给用量 | v [后果] 报表看着有数,对账时一笔都说不清,预算控制形同虚设 ``` 我是老李。前面十三境,我们基于 litellmgateway 的 open-api.zip Demo 一路换骨:改包名、立本体七模型、固化 OpenAI 兼容协议、编排 Pipeline、接多 Provider、做路由与熔断、再上 Project 与 VirtualKey 的限流预算,最后把配置持久化到库里。网关在功能上已经能跑,但运营上还是一条腿。 周一早上老板问了一句话:上个月三家上游一共花了多少钱,A 项目和 B 项目各占多少?我打开控制台,能看到请求数、错误率、P95 延迟,唯独看不到钱。再把上游账单拉出来一对,差得离谱——不是多算就是少算,而且说不清差在哪一笔。 有人会说,推理服务返回体里不是带了 usage 吗,直接存下来不就行了?问题是流式请求默认不返回 usage,不同厂商字段名还不一样,有的只给总数不给拆分。 那要不要干脆自己分词算 token?还是老老实实把上游 usage 当唯一事实源? 如果这两个问题选错,会怎样:报表上是一堆看起来对的数字,预算告警永远不触发,等到月底财务拿着账单来对,你连一句这笔为什么贵都答不上来。计量这条链一旦建歪,后面所有成本治理都建在沙子上。 # 01、故事 网关这一版长这样:入口是 OpenAI 兼容的 /v1/chat/completions,中间是 GatewayPipeline,依次过鉴权、限流、预算检查、路由选 Deployment、调 Provider Adapter,失败按轮回策略重试与降级,出站前经过熔断器记账。配置、Project、VirtualKey、Deployment 都入库,重启不丢。 任务是:在不改协议、不加新上游的前提下,给这条流水线补上计量与成本这一段,并且要做到一次请求从 usage 到 cost 到报表全链可追溯。 当前方案很朴素。Provider Adapter 拿到上游响应后,顺手把 usage 塞进一个 Map,网关层再取 prompt_tokens 和 completion_tokens 写日志。价格呢?写在一个 application.yml 的注释旁边,或者干脆写在某个 Service 的常量里。算出来的 cost 用 double 存,跟着日志一起滚。 变化来了。第一,项目从 1 个变成 6 个,每个项目一个 VirtualKey,谁花的钱要能分得开。第二,同一个 LogicalModel 底下挂了 3 个 Deployment,价格各不相同,甚至同一 Deployment 的促销价一个月调整一次。第三,老板要的是日粒度趋势加占比加预算消耗,不是一行行日志。 冲突就出在这里:日志是给排查用的,账单是给钱用的。日志丢一行没人管,账丢一行就是钱。原来那套顺手记一下的做法,撑不起六个维度的聚合,也撑不起价格变更后的历史追溯。 > 网关初立骨 > 账目始成篇 > 不识上游数 > 何以问成本 # 02、问题 旧方案失效的第一个点,是它假设上游一定给 usage。事实上,流式响应默认不带 usage;有些兼容上游压根不实现 usage 字段;有些只返回 total_tokens。一旦字段缺失,代码里就是 null 拆箱或者干脆记为 0,报表上的数字凭空少一截。 第二个点,是它假设价格是常量。价格写死在常量或配置文件里,遇到调价,要么历史被改写(重算时用新价),要么新单用旧价。两种都错,只是一个错得难看,一个错得隐蔽。 业务影响是连锁的。预算控制依赖 cost,cost 不准,预算告警不触发,超额请求照跑;项目分摊依赖维度标签,标签缺一个,分摊表就平不了账;调优决策依赖哪个 LogicalModel 最贵,数字不准,优化方向直接跑偏。 技术表现上,能观察到的是这几类:usage_record 里根本没有来源字段,无法区分真实值和估算值;cost 字段是浮点,日聚合后和明细累加对不上;Deployment 调价后,上个月的报表数字跟着变了;流式请求的 token 数明显低于非流式同类请求。 完成标准必须是可验证的,我给自己定了四条。第一,任意一条 usage_record 都能反查到它的 request_id、命中的 deployment_id、当时生效的 priceVersion。第二,同一时间段内,六个维度任意切分,明细累加与日聚合结果分毫不差。第三,上游返回真实 usage 时来源必须是 REAL,缺失时必须是 ESTIMATED,且估算口径写进代码注释与文档。第四,调价后重跑历史报表,历史数字不变。 > 旧册记不全 > 新需问六维 > 边界先画定 > 计数才有凭 # 03、原理 本篇只讲三件事的原理,但它们决定了后面所有代码的形状。 第一件事,usage 是上游的善意,不是契约。/v1/chat/completions 的响应里 usage 是可选字段,流式场景默认不返回。所以计量链路的输入端必须是可能为空的,任何 response.getUsage().getPromptTokens() 这种写法都是把可选当必选。正确姿势是先归一化成一个内部结构,再决定这一笔是 REAL 还是 ESTIMATED。 反直觉判断:允许估算,比坚持精确更重要。很多人第一反应是估算就是不准,不准的数据宁可不记。但真实情况是:宁可记一个标注了 ESTIMATED 的近似值,也不要留一个空洞。空洞会让整条链路断掉——你无法解释为什么这天少了 300 次请求的账。而带标签的估算值,至少能在对账时被人一眼识别、单独核算。 第二件事,钱不能用浮点存。微小的舍入误差在单条记录上无所谓,但日聚合、月汇总、跨维度切分时会被反复累加,最后变成明细加起来和总数差几块钱的经典事故。做法很简单:以微美元(micro-USD,1 美元等于 1,000,000 微美元)为最小单位,全程 long 运算。 第三件事,价格是时间的函数,不是空间的属性。今天给 Deployment 配的价格,只对今天之后产生的请求生效。所以每一笔账必须把当时生效的价格版本号一起落库。这不只是审计需求,更是重算的前提——没有价格快照,你连重算一遍都做不到,因为旧价已经不存在了。 理解了这三点,架构就没什么悬念了:入口归一化、中间用整数算钱、出口带版本落账。 > 用量非契约 > 估算是常态 > 钱须整数计 > 价必快照留 # 04、架构 ```text [输入] OpenAI 兼容请求 + 上游响应中的原始 usage | v [模块] UsageNormalizer → CostCalculator → UsageLedger | v [数据/状态] usage_record(usage_source, price_version) + deployment_price 快照 | v [处理] 字段归一 → 价格快照 → 微美元计价 → 按日落库与聚合 | v [输出] 报表 API / 控制台趋势与占比 / 预算消耗 ``` 边界:这一段只在 GatewayPipeline 的出站位置介入,不参与路由决策,也不改任何请求与响应报文(除流式注入 stream_options.include_usage 外)。它读 Provider 响应、读 Deployment 定价、写两张表,对外只暴露只读报表接口。 收益:六维度可切分、明细与聚合可对账、调价可追溯、估算与真实可区分。 代价:每次请求多一次落库(可异步化,但异步就有丢账窗口);需要为不支持 usage 的上游维护估算口径;需要一套价格版本管理,运营改价必须走这条路径,不能直接 UPDATE。 适用条件:只要网关自己做末级记账(而不是完全依赖上游账单)就适用。如果上游能提供逐请求账单且你只做月结,那本篇是过度设计。 > 入则归一化 > 出则计毫厘 > 账落六维上 > 报表自此生 # 05、实战一次 环境与版本:JDK 17、Spring Boot 3.x(延续 Demo 基线)、MySQL 8(延续上一境的持久化方案,若你的环境仍是 H2,SQL 只需去掉 AUTO_INCREMENT 语法差异)。本轮代码落在换骨后的包 com.litellmgateway.metering 下。 未在当前环境实测,以下为预期结果;示例输出仅作格式说明,不代表任何真实测量值。 先定义本体对象。 ```java package com.litellmgateway.metering; public enum UsageSource { /** 上游返回了可用的 usage 字段 */ REAL, /** 上游未返回 usage,由网关按字符数口径估算 */ ESTIMATED } ``` ```java package com.litellmgateway.metering; public record Usage(long inputTokens, long outputTokens, long totalTokens, UsageSource source) { public static Usage of(long input, long output, UsageSource source) { return new Usage(input, output, input + output, source); } } ``` 归一化器:把 OpenAI 风格的 prompt_tokens/completion_tokens 与 Anthropic 风格的 input_tokens/output_tokens 统一到一套字段,缺字段时估算。 ```java package com.litellmgateway.metering; import java.util.Map; public final class UsageNormalizer { /** 估算口径:约 4 个字符折合 1 token,仅在字段缺失时兜底 */ private static final long CHARS_PER_TOKEN = 4L; public Usage normalize(Map raw, String requestText, String responseText) { Long input = firstLong(raw, "prompt_tokens", "input_tokens"); Long output = firstLong(raw, "completion_tokens", "output_tokens"); if (input != null && output != null) { return Usage.of(input, output, UsageSource.REAL); } return Usage.of(estimate(requestText), estimate(responseText), UsageSource.ESTIMATED); } private Long firstLong(Map raw, String... keys) { if (raw == null) { return null; } for (String key : keys) { Object value = raw.get(key); if (value instanceof Number number) { return number.longValue(); } } return null; } private long estimate(String text) { if (text == null || text.isEmpty()) { return 0L; } return Math.max(1L, text.length() / CHARS_PER_TOKEN); } } ``` 定价与计价:价格挂在 Deployment 上,单位是微美元每 1K tokens,全程 long。 ```java package com.litellmgateway.metering; public record DeploymentPrice(long inputMicroPer1k, long outputMicroPer1k, String priceVersion) { } ``` ```java package com.litellmgateway.metering; public final class CostCalculator { /** 先乘后加最后除一次,减少整数截断误差 */ public long costMicroUsd(Usage usage, DeploymentPrice price) { long numerator = usage.inputTokens() * price.inputMicroPer1k() + usage.outputTokens() * price.outputMicroPer1k(); return (numerator + 500L) / 1000L; } } ``` 落库表结构(MySQL 语法): ```sql CREATE TABLE usage_record ( id BIGINT NOT NULL AUTO_INCREMENT, request_id VARCHAR(64) NOT NULL, stat_date DATE NOT NULL, project_id BIGINT NOT NULL, virtual_key_id BIGINT NOT NULL, logical_model_id BIGINT NOT NULL, provider_id BIGINT NOT NULL, deployment_id BIGINT NOT NULL, input_tokens BIGINT NOT NULL, output_tokens BIGINT NOT NULL, total_tokens BIGINT NOT NULL, usage_source VARCHAR(16) NOT NULL, price_version VARCHAR(64) NOT NULL, cost_micro_usd BIGINT NOT NULL, latency_ms INT NOT NULL, ttft_ms INT NULL, status VARCHAR(16) NOT NULL, fallback_count INT NOT NULL DEFAULT 0, retry_count INT NOT NULL DEFAULT 0, created_at DATETIME NOT NULL, PRIMARY KEY (id), UNIQUE KEY uk_usage_request (request_id), KEY idx_usage_date_project (stat_date, project_id) ); CREATE TABLE usage_daily ( stat_date DATE NOT NULL, project_id BIGINT NOT NULL, virtual_key_id BIGINT NOT NULL, logical_model_id BIGINT NOT NULL, provider_id BIGINT NOT NULL, deployment_id BIGINT NOT NULL, request_count BIGINT NOT NULL, error_count BIGINT NOT NULL, fallback_count BIGINT NOT NULL, estimated_count BIGINT NOT NULL, input_tokens BIGINT NOT NULL, output_tokens BIGINT NOT NULL, total_tokens BIGINT NOT NULL, cost_micro_usd BIGINT NOT NULL, PRIMARY KEY (stat_date, project_id, virtual_key_id, logical_model_id, provider_id, deployment_id) ); ``` 聚合用幂等 upsert,靠唯一键保证重复跑不会翻倍: ```sql INSERT INTO usage_daily (stat_date, project_id, virtual_key_id, logical_model_id, provider_id, deployment_id, request_count, error_count, fallback_count, estimated_count, input_tokens, output_tokens, total_tokens, cost_micro_usd) SELECT stat_date, project_id, virtual_key_id, logical_model_id, provider_id, deployment_id, COUNT(*), SUM(CASE WHEN status <> 'SUCCESS' THEN 1 ELSE 0 END), SUM(fallback_count), SUM(CASE WHEN usage_source = 'ESTIMATED' THEN 1 ELSE 0 END), SUM(input_tokens), SUM(output_tokens), SUM(total_tokens), SUM(cost_micro_usd) FROM usage_record WHERE stat_date = ? GROUP BY stat_date, project_id, virtual_key_id, logical_model_id, provider_id, deployment_id ON DUPLICATE KEY UPDATE request_count = VALUES(request_count), error_count = VALUES(error_count), fallback_count = VALUES(fallback_count), estimated_count = VALUES(estimated_count), input_tokens = VALUES(input_tokens), output_tokens = VALUES(output_tokens), total_tokens = VALUES(total_tokens), cost_micro_usd = VALUES(cost_micro_usd); ``` 启动与请求: ```bash mvn -q spring-boot:run -Dspring-boot.run.profiles=dev curl -s http://localhost:8080/v1/chat/completions \ -H "Authorization: Bearer vk_dev_demo" \ -H "Content-Type: application/json" \ -d '{"model":"logical-gpt-4o-mini","messages":[{"role":"user","content":"ping"}]}' ``` 验证这一步才是可追溯的落点: ```sql SELECT request_id, deployment_id, usage_source, total_tokens, price_version, cost_micro_usd, latency_ms, status, fallback_count FROM usage_record ORDER BY id DESC LIMIT 5; ``` 示例输出: ```log req_7f3a... | deploy_3 | REAL | 128 | price-2025-06-01 | 2190 | 812 | SUCCESS | 0 req_7f3b... | deploy_1 | ESTIMATED | 96 | price-2025-05-20 | 1180 | 640 | SUCCESS | 1 ``` V1 到这里跑通了:一笔请求能落一条带 usage_source 和 price_version 的账。遗留问题也很明确:异步落库的丢账窗口、估算口径在中文场景偏保守、以及聚合任务还没有调度。 > 先跑一条链 > 再谈规模化 > 一请求到底 > 可溯才算通 # 06、排查 诊断链一。现象:报表里所有流式请求的 total_tokens 明显低于同类非流式请求,且 usage_source 全是 ESTIMATED。怀疑:是不是估算器坏了,还是流式响应根本没拿到完整文本?检查:在 Provider Adapter 里把流式最后一个 SSE chunk 原样打出来(脱敏后),确认是否含 usage 字段。证据:最后一个 chunk 只有 finish_reason,没有 usage;对照上游文档,流式要拿 usage 必须显式传 stream_options: {"include_usage": true},而我们在拼请求体时根本没带这个字段。所以在 Adapter 眼里原始 usage 一直是 null,归一化器永远走估算分支。根因:不是估算器的问题,是请求侧没把要不要返回 usage 这件事打开,计量链路的输入缺失被下游兜底逻辑掩盖成了看起来有数。修复:在流式请求转发时统一注入 stream_options.include_usage=true,并对不支持该参数的上游做能力探测,探测失败则保留 ESTIMATED 但打点告警。 诊断链二。现象:按天汇总的 cost 与当天所有明细 cost 直接相加对不上,差的量级不大,但每天都差。怀疑:聚合 SQL 写错了,或者有明细没进聚合?检查:先跑一次明细的 SUM(cost_micro_usd),再跑一次日表的 SUM(cost_micro_usd),对比两者;同时检查 Deployment 的价格字段类型。证据:两个数确实不等;进一步发现价格在配置里是 double,计价时又乘了 1_000_000 转成微美元,浮点尾差在乘除之间被放大;更糟的是,Deployment 调价时直接 UPDATE 了价格字段,历史记录里的 price_version 只是文本,重算逻辑用的却是当前价。根因:两个独立问题叠加,浮点计价加缺价格快照。修复:价格改为 long(微美元每 1K tokens)入库,usage_record 落 price_version 即意味着这笔账不再自动重算,重算只在明确指令下按快照价执行。 诊断链三。现象:网关重启后,重启前最后几十秒的请求在 usage_record 里找不到。怀疑:落库失败?还是被回滚了?检查:对比应用日志里的请求 id 和库里的 request_id,确认是有日志无记录。证据:V1 里写账走的是内存队列加定时 flush,进程退出时队列里未 flush 的记录直接丢了。上一境的配置持久化已经解决了配置重启不丢,但账目走的是另一条路,没享受到那套机制。根因:账目比配置更接近事实,事实不能有丢失窗口。修复:写账改为同步落库加异步聚合,单条 INSERT 的成本远低于一次 LLM 推理,不值得为它冒丢账风险。 **错误尝试:** 我最初把成本计算直接写进了每个 Provider Adapter,让 OpenAI Adapter、Anthropic Adapter 各自读自己的 usage 字段、各自乘自己知道的价格,然后吐一个 cost 出来。为什么错:定价是 Deployment 的运营属性,不是 Provider 的协议属性。这么写之后,同一个 Deployment 换价格要改 N 个 Adapter;新增一个 Provider 就要复制一份计价逻辑;更致命的是,路由层做了 fallback 之后,一笔请求可能被两个 Adapter 先后处理过,谁该记账、记几次,Adapter 根本无从判断。事实是 Adapter 不应该知道钱,它只该把原始 usage 原样透传上来。 > 现象即入口 > 证据定根因 > 错试须记下 > 免得再回头 # 07、优化 根因来自第 06 章的三条证据,V2 逐条对应。 第一,输入缺失问题。修改:在请求转发层统一注入 stream_options.include_usage=true,并把它做成 Provider 能力开关(capabilities 表里一个布尔位)。原因:计量链路的输入不能依赖调用方自觉。新行为:支持的上游返回真实 usage,来源为 REAL;不支持的上游走估算,来源为 ESTIMATED 且被单独计数。验证:同一网关实例下,分别对支持与不支持的上游各发一次流式请求,检查两条记录的 usage_source 是否符合预期。 第二,计价问题。修改:Deployment 的价格字段改为 long 微美元每 1K tokens,并在 usage_record 上落 price_version 快照。原因:整数运算消除累加误差,快照保证历史不可变。新行为:调价只影响调价之后产生的请求,历史重算按快照执行。验证:手工改一次 Deployment 价格,再查前一天记录,cost_micro_usd 与 price_version 应保持不变。 第三,丢账问题。修改:写账改为同步 INSERT,聚合与报表读取走异步。原因:账目是事实,事实优先于吞吐。新行为:请求返回前账已落库。验证:压入若干请求后立即结束进程,重启后按 request_id 全部可查。 第四,可追溯问题。修改:给 usage_record 增加 request_id 唯一索引,并在 Pipeline 里把 request_id 贯穿到日志、Trace、usage_record 三处。原因:没有统一 id,全链可追溯就只是一句口号。新行为:拿着任意一个 request_id,可以查到它属于哪个 Project、哪个 Key、哪个 LogicalModel、落到哪个 Provider 的哪个 Deployment、当时的单价版本、以及是否经过 fallback。验证:随机抽 10 条记录,逐条反查链路字段是否齐全。 本轮不虚构任何验证数据,以上均为可执行动作描述。 > 根因既已明 > 改则改其本 > 不快不乱试 > 新行验旧证 # 08、演进 ```text [同一输入] | +--[V1] Adapter 各算各的 cost,double 计价,异步落账 | 代价:调价即改写历史,账有丢失窗口,缺字段被兜底掩盖 | +--[V2] 出站统一归一 + 价格快照 + 微美元整数计价 + 同步落账 | 代价:多一次 DB 写入,多一套价格版本管理流程 | [Trade-off] 得到什么:六维度可切分、明细与聚合可对账、调价可追溯、真实与估算可区分 失去什么:写账路径变长(同步 INSERT),运营改价不能再直接改库 适用边界:需要自己出账、需要按项目分摊、需要预算告警的网关 ``` 正确性上,V2 把可能缺字段和价格会变这两个现实约束显式建模进了数据结构,而不是靠代码里的 if 兜住。这是正确性的本质提升,不是精度提升。 稳定性上,同步落账牺牲了一点写路径延迟,换来的是不丢账。丢账是不可恢复的错误,延迟是可优化的成本,两者不在一个量级。 复杂度上,V2 多了两张表、一个价格版本概念、一个聚合任务。这是必要的复杂度,因为它对应的是真实世界的两个变化源:上游能力不一致、价格随时间变化。 成本上,多一次 INSERT 和多一份聚合存储。相比一次 LLM 调用的开销,这部分可以忽略;真正需要控制的是 usage_daily 的维度爆炸,六个维度全组合在某些流量形态下会产生大量稀疏行,必要时得按维度裁剪或做物化视图。 适用范围上,这套方案适合网关即计费点的场景。如果企业已有独立计费系统,网关只需要把归一化后的 usage 打出去,不必自己聚合。 遗留问题:估算口径目前是字符数近似,中文场景偏保守;预算消耗目前是事后统计,还不能做事前拦截,那属于后面的高级策略;TTFT 在非流式请求里记 null,报表侧需要额外处理。 > 一路分两岔 > 各有其代价 > 取舍得其宜 > 方为长久计 # 09、洞见 ## 9.1 计量链路的输入端,永远是可选字段 反直觉判断:越是想算准,越要先承认自己算不准。usage 缺失不是异常路径,而是正常路径的一种。凡是把上游一定会给 usage 写进代码假设的地方,早晚都会在流式、兼容层或降级上游上翻车。正确的做法是:把 ESTIMATED 当成一等公民写进枚举、写进表结构、写进报表界面,而不是当成抛异常之前的最后一根稻草。一个人能一眼看出这 300 条是估算的,比报表看起来全绿重要得多。 ## 9.2 钱的精度问题,本质是聚合顺序问题 单条记录上极小的浮点误差无关痛痒,但一旦进入按天、按项目、按模型的多层聚合,误差会被反复累加和重新分配。用 long 微美元不是一个更严谨的编码习惯,而是把聚合这个动作从浮点世界搬回整数世界的必要前提。反直觉判断:成本核算里最重要的从来不是单次计价的精度,而是聚合后能不能对得上;能在明细和汇总之间画等号的方案,就是好方案。 ## 9.3 价格是时间的函数,不是 Deployment 的属性 把价格当成 Deployment 的一个字段,是最自然的建模方式,也是最容易出事的方式。一旦运营改价,历史报表就面临要么变、要么解释不清的二选一。加一个 priceVersion 并把价格快照写进每一笔账,本质上是在做时态建模。这件事在数据量小的时候看起来多余,等到第一次有人问上个月为什么贵的时候,你会庆幸当初多写了一个字段。 ## 9.4 账目应该同步写,报表可以异步算 写账和聚合看起来是同一件事的两个步骤,但它们的可靠性要求完全不同。账目是事实,丢了不可恢复;聚合是派生,算错了重跑一遍就行。把两者拆开,用同步保证事实、用异步承担派生,可以用极小的写路径代价换到完整的数据。很多网关栽在这一步,不是算法不对,而是把事实和派生放进了同一个内存队列。 > 反直觉常在 > 顺常识易偏 > 数字不说谎 > 但需人来问 # 10、系统落地 原来有什么:一条能跑的网关主链——OpenAI 兼容协议、GatewayPipeline、Provider 与 LogicalModel 与 Deployment 三层模型、路由与重试降级、熔断恢复、Project 与 VirtualKey 的限流预算、配置持久化。 本篇新增了什么:一套计量内核(Usage 归一、UsageSource 标注、DeploymentPrice 快照、CostCalculator 微美元计价)、两张表(usage_record 明细、usage_daily 聚合)、一组只读报表接口、以及写账路径上的同步保证。 现在能做什么:任意一笔请求,拿 request_id 就能反查出它属于哪个项目、哪个 Key、走了哪个模型、落到哪个 Provider 的哪个 Deployment、用的是哪一版价格、花了多少微美元、耗时多少、有没有 fallback、是真值还是估算值。按六个维度任意切分,明细与日聚合对得上。 还缺什么:预算仍是事后统计而非事前拦截;估算口径还是字符近似;报表页只有趋势和占比,还没有到 Deployment 的钻取;聚合任务没有调度与补偿机制;成本数据还没有和上一境的可观测数据打通,Trace 里看不到 cost span。 下一步如何演进:把 cost 作为 span 属性打进 Trace,让贵在哪一段能在链路图上直接看出来;把预算从事后统计提升为事前拦截,与限流共用计数器;再多实例并行写账时,日聚合需要幂等的调度与补偿,而不是单机定时任务。 > 原有路由骨 > 今添计量魂 > 能答多少钱 > 方谈可控本 # 11、小结 ```text Q1 → 能不能直接信上游 usage? 不能当必选项,要归一化;有真值用真值(REAL),缺失走估算(ESTIMATED)并标注 Q2 → 要不要自己分词算 token? 不作为主口径;只在缺失时用字符近似兜底,且必须与真值在数据上可区分 Q3 → 选错会怎样? 报表看起来有数但对不上账,预算不触发,成本优化方向跑偏 状态 → 一次请求从 usage 到 cost 到报表全链可追溯,六维度可切分 ``` > 三问皆有答 > 一链已可追 > 状态落在此 > 下境再纵深 # 12、作业 ## 12.1 理解题:为什么 usage_source 必须落库,而不能只写日志? 参考答案:日志会滚动、会被采样、会在排查时被忽略,而 usage_source 是账目属性。对账时最常见的争议就是这个数字准不准,如果 REAL 和 ESTIMATED 混在同一列里无法区分,那么所有成本数据的可信度都要打问号。落库之后,报表可以按来源切片,估算值可以单独核算,也不会因为日志生命周期结束而失去追溯能力。 ## 12.2 实战题:给 Deployment 加一个价格版本字段,并证明调价不改写历史。 参考答案:在 Deployment 表上增加 input_price_micro_per_1k、output_price_micro_per_1k(均为 BIGINT)和 price_version(VARCHAR);计价时把这三个字段一起快照进 usage_record。验证方法是:改价后查改价前的记录,cost_micro_usd 与 price_version 均不变;再发一笔新请求,新记录的 price_version 应当是新的。若你的实现里改了价历史数字跟着变,说明快照没有真正落地。 ## 12.3 排障题:报表显示某天 total_tokens 明显偏低,但请求数正常,从哪查起? 参考答案:先按 usage_source 分组统计,确认是整批 ESTIMATED 还是个别异常。如果是整批 ESTIMATED,往请求侧看,流式请求是否开启了 stream_options.include_usage;如果只有个别,检查该 Deployment 对应的 Provider 是否在特定形态(长上下文、工具调用)下不返回 usage。核心是先分清是输入缺失还是计算错误,两条路的修法完全不同。 ## 12.4 架构判断题:成本计算应该放在 Provider Adapter 里,还是放在网关出站层? 参考答案:放在出站层。Adapter 的职责是协议适配,它只应把原始 usage 原样透传;成本属于运营属性,依赖 Deployment 定价、priceVersion、以及路由层的 fallback 事实。放在 Adapter 里会导致调价要改多处、新增 Provider 要复制逻辑,而且 fallback 场景下无人能判断一笔请求该记几次。判断标准很简单:如果一段逻辑需要知道这属于谁的钱,它就不该待在协议层。 > 理解须入骨 > 实战要见血 > 排障凭证据 > 判断见取舍 # 13、思考 回到最开始那个冲突:日志是给排查用的,账单是给钱用的。我们在第 05 章做的最小可用版本,本质上就是把这两件事分开了——usage_record 负责事实,usage_daily 负责结论,price_version 负责时间。 三个可以带走的判断。第一,凡是要出账的数字,先问它的来源标签是什么;没有来源标签的数字,等于没有数字。第二,凡是要聚合的量,先问它的存储类型是不是整数最小单位;浮点进入聚合链路,就是在给自己埋一颗延时炸弹。第三,凡是要追溯的历史,先问它依赖的配置有没有快照;没有快照的追溯,只是在用今天的规则解释昨天的账。 计量这件事的难点从来不在算法,而在愿不愿意承认世界是不完整的。上游可能不给 usage,价格会变,进程会挂,并发会乱序。把这些不完整显式建模成枚举、字段和版本号,网关就从能跑变成了能算账。 > 一念辨边界 > 一证定根因 > 一改知取舍 > 一役见真章