以下三家公司与全部数字均为教学假设,用于演示商业化计算,不代表任何真实企业。
计量是收入运营的原始凭证
财务看到的是账单,客户看到的是用量页面,工程看到的是调用日志。这三样东西如果各自独立生成,迟早会对不上。把三者粘在一起的,是计量事件:一条描述「谁、在什么时候、用了什么、用了多少」的不可变记录。
计量事件不是监控日志。监控日志可以采样、可以丢弃、可以只保留七天;计量事件必须完整、唯一、可追溯,因为它的下游是收入。一条丢失的事件意味着少收一笔钱,一条重复的事件意味着多收一笔钱,两者都会在续费季变成争议。
三家教学公司的计量对象完全不同,但结构是同一套:
- LumenDesk 按对话计量,1,920 个席位每月产生 1,190,400 次对话。
- Verba API 按分钟计量,每月 42,000,000 分钟。
- ClausePilot 按案件计量,85 家客户每月 3,230 件,每件平均触发 80 次推理调用,合计 258,400 次调用。
如果只记住一句话:计量事件描述事实,计费规则解释事实。事件里不应该出现价格,价格属于下一章的价格表;事件里也不应该出现「本月合计」,合计属于聚合层。
一次计量要回答四个问题
设计计量系统时,先把四个问题写下来,再谈字段。
第一,计费对象是谁。是租户、席位、账户,还是案件?LumenDesk 的账单按席位出,所以事件必须带 seatId;Verba 按账户出,seatId 可以为空;ClausePilot 按案件出,案件号必须进事件。
第二,计量单位是什么。对话、分钟、案件是三种完全不同的单位,单位一旦混用,后面的单价、额度、毛利全部失真。单位要写进事件,而不是靠上下文推断。
第三,计费时点在哪里。请求发起时、成功返回时、还是人工复核完成时?LumenDesk 选成功返回,Verba 选音频处理完成,ClausePilot 选复核签字。计费时点决定了收入确认的时间,也决定了补录窗口的长度。
第四,成本归属到哪里。一次对话的推理成本、检索成本、存储成本要落到同一条事件上,才能算出单次毛利。如果成本只记在供应商账单里,计量事件就无法独立回答「这次调用赚不赚钱」。
四个问题的答案会直接变成字段。反过来,如果字段设计完还回答不了这四个问题,说明事件模型缺东西。
事件的结构:事实、维度、数量、版本
一条可用的计量事件至少包含四组信息。
| 组别 | 字段示例 | 作用 | 缺失后的后果 |
|---|---|---|---|
| 事实 | eventId、occurredAt | 唯一标识与发生时间 | 无法去重,无法排序 |
| 维度 | tenantId、seatId、unit | 归属与计量单位 | 无法出账单,无法按客户拆成本 |
| 数量 | billableQuantity、costQuantity、costMicros | 计费量与成本量 | 只能按均值估算,长尾失控 |
| 版本 | schemaVersion、source | 模式演进与来源 | 旧事件无法重放,口径漂移 |
eventId 建议由生产端生成,而不是入库时自增。自增 ID 在重投时会变,失去了「同一条事实」的含义。occurredAt 用 UTC,展示时再转本地时区;跨时区客户按自然月结算时,时区错误会直接把月末几个小时算到别的账期。
unit 不要用自由文本。三种单位就写三个枚举值,入库前校验,非法值直接拒绝。自由文本的单位字段迟早会出现「次」「call」「conversation」三种写法混在一起。
costMicros 用 micro-USD 存整数。LumenDesk 单次成本 0.015 美元,用美分会舍入成 2 美分,误差 33%;用 micro-USD 存 15,000,既有整数精度,又能表达 Verba 的 4,200 和 ClausePilot 的 65,000,000。
schemaVersion 是给未来的自己留的退路。模式一定会变,比如新增「缓存命中」维度、把一次对话拆成多轮。没有版本号,旧事件在新代码里只能靠猜。
计费量与成本量必须分开
这是计量设计里最容易被合并、后果也最严重的一对字段。
LumenDesk 的合同写的是「按成功返回的对话计费」,重试和失败不计入客户额度。但重试仍然消耗推理,供应商照常收费。如果事件里只有一个 quantity,团队就只剩两个坏选择:要么把重试算进客户账单,违背合同;要么把重试从事件里删掉,成本凭空消失。
正确做法是一条事件带两个数量:
billableQuantity:进入客户账单的数量,重试为 0,失败为 0。costQuantity:进入成本核算的数量,重试为 1,失败也可能为 1。
重试率 8% 时,名义单次成本 15,000 micro-USD 会被抬高到:
有效单次成本 = 15,000 ÷ (1 − 0.08) = 16,304 micro-USD
也就是 0.0163 美元,与事实表的口径一致。按 620 次/席位算,单席位月成本从 9.30 美元变成 10.11 美元。这 0.81 美元的差额不会出现在客户账单上,但它真实发生,必须被计量系统看见。
ClausePilot 的差距更明显。单案件变动成本 65 美元,重试率 11%,有效成本是:
65 ÷ (1 − 0.11) = 73.03 美元
如果计量事件只记「案件完成」这一个数量,这 8.03 美元的月成本就只能靠财务月末倒推。倒推出来的数无法归因到具体案件,也就无法判断是哪个客户的文档质量差、哪个环节在反复重试。
两个数量分开之后,还有一条纪律:成本量可以大于计费量,但不能小于计费量。小于意味着有计费动作没有对应成本,通常是成本采集漏了,而不是真的免费。
计量单位与事件粒度不是一回事
ClausePilot 是最好的例子。它的计费单位是案件,3,230 件/月;但它的成本事件粒度是推理调用,258,400 次/月,因为每件平均 80 次调用:
3,230 × 80 = 258,400
计费粒度粗、成本粒度细,这是正常的。计费粒度要匹配客户能理解的价值单位,客户买的是「一份审完的合同」,不是「80 次模型调用」;成本粒度要匹配资源实际消耗,否则无法定位成本异常。
反过来也成立。LumenDesk 的计费粒度和成本粒度都是对话,1,190,400 条/月;按 30 天摊,每天 39,680 条,每席位每天约 21 条。这个量级用逐条事件加每日聚合就够,不需要引入流式系统。Verba 是 42,000,000 分钟/月,每天 1,400,000 分钟,事件量高两个数量级,聚合层必须前置。
| 案例 | 计费单位 | 月计费量 | 成本事件粒度 | 月成本事件量 |
|---|---|---|---|---|
| LumenDesk | 对话 | 1,190,400 | 对话 | 1,190,400 |
| Verba API | 分钟 | 42,000,000 | 分钟 | 42,000,000 |
| ClausePilot | 案件 | 3,230 | 推理调用 | 258,400 |
事件粒度还会影响补录成本。粒度越细,晚到事件越多,重算越贵;粒度越粗,单条事件承载的信息越多,更正时越难定位。选择粒度的标准不是「越细越好」,而是「能不能支撑一次可解释的更正」。
判断方法很直接:当客户问「这个月为什么多了 300 次」,系统能不能在不解冻全量原始日志的前提下,指出是哪一批事件、哪一天、哪个席位产生的。如果不能,粒度就太粗;如果为了回答这个问题要扫几千万行,粒度就太细。
计费时点决定收入与成本的错位
计费时点不是一个技术细节,它决定了收入与成本是否落在同一个账期。
LumenDesk 在成功返回时计费。一次对话在 23:59:58 发起、00:00:03 返回,会计入第二天。如果成本按发起时间记、收入按返回时间记,月末就会出现一批「有成本无收入」的事件。单条金额很小,但 1,190,400 条的基数会把任何比例的错位放大成一批需要人工解释的记录。
处理办法是统一时点:收入和成本都按 occurredAt 归属,而 occurredAt 定义为计费时点,不是请求发起时点。这样一条事件只有一个时间,聚合逻辑不需要判断「用哪个时间」。
Verba 的计费时点是音频处理完成,ClausePilot 是人工复核签字。后者的时点更晚,因为复核可能隔天完成。ClausePilot 的 3,230 件里,如果有一部分在月末最后一天进入复核、次月才签字,收入就会推迟一个账期。这不是错误,但必须在合同和账单里写清楚,否则客户会认为「案件做完了却没计费」是系统漏单。
计费时点还要与补录窗口配合。事件在时点之后才产生,晚到是常态;补录窗口的长度应该覆盖「处理时长 + 传输重试」的 P99,而不是拍一个 7 天。
代码:入库前的校验与汇总
下面的实验室代码把事件结构、校验和两个汇总函数放在一起。校验返回 Result,不抛异常,因为计量管道的调用方需要区分「这条事件非法」和「这条事件处理失败」;前者应该进死信队列,后者应该重试。
// file: src/ops/06-1-metering-events.ts
// tier: L1
// verify: node --test test/ops/06-1-metering-events.test.ts
// 计量事件是不可变的用量事实:一次写入同时带计费量与成本量。
import { type Result, ok, fail } from "../core/result.ts";
export type MeterUnit = "conversation" | "minute" | "case";
export type MeterEvent = {
eventId: string;
tenantId: string;
seatId: string | null;
unit: MeterUnit;
occurredAt: string;
billableQuantity: number;
costQuantity: number;
costMicros: number;
schemaVersion: number;
};
export const SCHEMA_VERSION = 1;
export const UNIT_COST_MICROS: Record<MeterUnit, number> = {
conversation: 15_000,
minute: 4_200,
case: 65_000_000,
};
const UNITS: readonly MeterUnit[] = ["conversation", "minute", "case"];
function isQuantity(value: unknown): value is number {
return typeof value === "number" && Number.isInteger(value) && value >= 0;
}
/** 校验并把时间规范化为 UTC;失败返回可读原因,不抛异常。 */
export function validateEvent(input: Partial<MeterEvent>): Result<MeterEvent> {
if (!input.eventId) return fail("eventId 缺失");
if (!input.tenantId) return fail("tenantId 缺失");
if (!input.unit || !UNITS.includes(input.unit)) return fail("unit 非法");
if (!input.occurredAt || Number.isNaN(Date.parse(input.occurredAt))) {
return fail("occurredAt 不是合法时间");
}
if (!isQuantity(input.billableQuantity)) return fail("billableQuantity 非法");
if (!isQuantity(input.costQuantity)) return fail("costQuantity 非法");
if (!isQuantity(input.costMicros)) return fail("costMicros 非法");
if ((input.schemaVersion ?? SCHEMA_VERSION) !== SCHEMA_VERSION) {
return fail("schemaVersion 不匹配");
}
return ok({
eventId: input.eventId,
tenantId: input.tenantId,
seatId: input.seatId ?? null,
unit: input.unit,
occurredAt: new Date(input.occurredAt).toISOString(),
billableQuantity: input.billableQuantity,
costQuantity: input.costQuantity,
costMicros: input.costMicros,
schemaVersion: SCHEMA_VERSION,
});
}
/** 汇总某一计量单位的计费量。 */
export function totalBillable(events: readonly MeterEvent[], unit: MeterUnit): number {
return events
.filter((event) => event.unit === unit)
.reduce((sum, event) => sum + event.billableQuantity, 0);
}
export function totalCostMicros(events: readonly MeterEvent[]): number {
return events.reduce((sum, event) => sum + event.costMicros, 0);
}
/** 每个计费单位的实际成本,单位 micro-USD。 */
export function costPerBillableMicros(events: readonly MeterEvent[]): number {
const billable = events.reduce((sum, event) => sum + event.billableQuantity, 0);
if (billable === 0) return 0;
return Math.round(totalCostMicros(events) / billable);
}
validateEvent 做四件事:检查必填维度、把时间规范化成 UTC、拒绝负数和小数数量、校验模式版本。totalBillable 只汇总计费量,totalCostMicros 汇总成本,两个函数刻意分开,避免调用方顺手把成本量加进账单。
costPerBillableMicros 是给运营看的诊断指标。LumenDesk 的正常值是 15,000;如果某天变成 16,304,说明重试率升到了 8%;如果变成 30,000,说明有事件重复计入或上下文长度异常。这个数不需要和财务系统对账,它只是第一道预警。
事件版本与模式演进
模式演进有三种常见动作,每一种都要付出不同的代价。
只加字段。 新增 cacheHit 布尔值,旧事件缺省为 false。代价最低,但下游必须能处理缺省值,不能把「没有这个字段」当成「缓存未命中」以外的含义。
改语义。 把「一次对话」从「一次请求」改成「一次会话」。这是破坏性变更,旧事件不能直接和新事件相加。正确做法是升 schemaVersion,在聚合层按版本分别计算,再在报表层标注口径变化。
拆事件。 把一条对话事件拆成多轮事件,用于更细的成本归因。拆分会改变事件量级,LumenDesk 的 1,190,400 可能变成几百万。拆分前要先确认聚合层能承受,否则计量系统会成为整个账单链路的瓶颈。
无论哪种动作,都要保留旧版本的读取能力。审计要求通常跨越 12 个月,去年的账单必须能用去年的代码重放。把「重放旧账」当成一个必须通过测试的功能,而不是出事后的临时脚本。
计量质量的四条验收线
计量系统上线前,用四条线验收,每条都能被测试。
完整性。 计费量与实际业务量对得上。LumenDesk 可以用产品侧的对话完成数交叉验证 1,190,400;Verba 可以用音频时长总和验证 42,000,000 分钟;ClausePilot 可以用案件管理系统里的结案数验证 3,230。差异超过 0.1% 就要查,不能等到月末。
唯一性。 同一个 eventId 无论投递多少次,账上只有一条。测试方法不是看代码,而是真的重投一百条,看总额是否变化。
及时性。 95% 的事件在计费时点后多久入库。这个指标决定了补录窗口和月末关账时间。LumenDesk 这种对话型业务应该在分钟级,ClausePilot 这种含人工复核的业务可以放宽到小时级。
可解释性。 任意一条账单行都能下钻到事件列表,任意一条事件都能说明它为什么计费、为什么不计费。做不到这一条,前三条都只是数字好看。
从事件到账单的三层表
计量事件不会直接变成账单。中间至少有两层聚合,每层解决不同的问题。
第一层是原始事件表,只追加,保留全部字段。它是唯一事实源,任何争议都回到这里。
第二层是日聚合表,按租户、席位、单位分组,存 billableQuantity 与 costMicros 的和。它解决查询性能,也固定了「按天可重算」的粒度。LumenDesk 的 39,680 条/天在这里变成每个席位一行。
第三层是账期汇总表,按计费周期汇总,带上价格版本和额度规则。这一层才允许出现金额,前两层只允许出现数量与成本。
三层表的分工要写进数据字典。最常见的错误是让账单直接读原始事件表,短期看少了一层,长期看每次改价都要重扫全量数据,而且无法解释「上个月的账单为什么和现在重算的不一样」。
小结
- 计量事件是收入运营的原始凭证,不是可采样的监控日志,必须完整、唯一、可追溯。
- 设计前先回答计费对象、计量单位、计费时点、成本归属四个问题,答案会直接变成字段。
- LumenDesk 每月 1,190,400 次对话、Verba 每月 42,000,000 分钟、ClausePilot 每月 3,230 件案件,三种单位不能用同一套字段硬套。
- 计费量与成本量必须分开:重试率 8% 让 LumenDesk 的有效单次成本从 15,000 升到 16,304 micro-USD。
- 计费粒度匹配客户理解的价值单位,成本粒度匹配资源消耗;ClausePilot 按案件收费、按 258,400 次调用记成本。
- 计费时点要统一收入与成本的归属,并让补录窗口覆盖处理时长与传输重试的 P99。
- 用完整性、唯一性、及时性、可解释性四条线验收,再用原始事件、日聚合、账期汇总三层表隔离查询与计费。
阅读导航:上一节:5.3 多供应商与切换成本 · 下一节:6.2 幂等、补录与去重 。
常见错误与边界
- 把计量事件当监控日志,设置采样率和七天保留期,结果账单无法复现,审计时拿不出原始记录。
- 只用一个
quantity字段,重试要么被算进客户账单,要么从成本里消失,两种都会让毛利失真。 eventId用数据库自增,重投后 ID 变化,去重逻辑形同虚设。- 计费时点与成本时点不一致,月末出现一批有成本无收入的事件,关账时只能人工调平。
- 事件里直接写单价或金额,改价后历史事件无法重算,价格版本与计量事实纠缠在一起。
- 让账单直接读原始事件表,短期省一层聚合,长期每次改价都要全量重扫,且无法解释重算差异。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。