# 按结果收费时，计数器就是发票

> 账单在周期末才对账，配额却要逐个事件检查，所以两者必须拆成两套系统、各按各的节奏运行。

原文: https://fdetimes.net/zh/guides/usage-metering-entitlements-outcome-billing/

设想计费周期的最后一周。客户发来一张仪表盘截图：你部署的客服 Agent“解决”的对话数，远少于发票上写的数字。客户问的不是模型，也不是提示词，而是为什么发票上的解决数比他们自己数出来的多。

对前线部署工程师（FDE）来说，计费从这一刻起就不再只是财务团队的事。客户按 token 或按结果付费时，代码发出的每个事件都是钱。计数器错了，发票就错了，客户信任的流失速度比任何技术 bug 都快。

你的任务是把客户系统接入计费，让计数准确、配额生效。客户提出异议时，你还要能说清每个数字从哪里来。

## 计费和权益回答的是不同问题

计费回答“收多少钱”，权益回答“这个客户还能不能继续用”。两个问题听起来相近，运行节奏却完全不同。

Stripe 文档明确写道，基础版按用量计费只在开票时对账。周期进行中，客户和你的团队都看不到实时的额度余额或累计用量。

Stripe 还提醒，基础模式下使用预付额度时，客户可能在周期中途超额消耗余额。对于需要实时余额和额度扣减的新集成，Stripe 建议改用 Metronome。

后果很具体。假如合同写的是“每月 1000 万 token”（这是 OpenMeter 用来说明计量型权益的例子），你不能等到开票才发现客户已经超额。你需要在请求路径上加一道检查，为每个客户单独维护余额。

**要点:** 计费可以事后收钱；权益必须对每个事件当场做出判断。

OpenMeter 通过“主体键”（subject key）把用量事件和权益关联起来，主体键就是事件中标明“谁使用了该功能”的字段。这看似细节，很多集成却恰恰在这里出错：如果主体键是用户 ID，而配额按工作区设置，余额永远对不上。

## 一次对话，三个动作，一次收费

看一个具体案例。假设客户按 Agent 解决的对话数付费，采用类似 Intercom Fin 的模式。Intercom 对可计费的解决有两种定义：客户确认问题已解决；或者客户离开对话，没有再寻求帮助。第二种称为“推定解决”（assumed resolution）。

Intercom 还有一条规则：即使 Agent 执行了多个动作，每个对话也只算一个结果。比如在一次对话中，Agent 查询了订单、修改了收货地址、发送了优惠码。如果代码每个动作发一个事件，本该收一次费的事情，客户会被收三次。

所以计费单位必须是对话，而不是动作。下面的示意代码展示了如何构造事件：

```python
def build_resolution_event(conv):
    # 只有对话已关闭且符合合同定义时才计费
    if conv.status != "closed":
        return None
    confirmed = conv.customer_confirmed
    assumed = conv.customer_left and not conv.asked_for_more_help
    if not (confirmed or assumed):
        return None
    return {
        "event_name": "resolution",           # 必须与计量器上配置的名称一致
        "customer_id": conv.billing_customer_id,
        "value": 1,                           # 每个对话一个结果
        "identifier": f"resolution:{conv.id}",  # 稳定的幂等键
        "timestamp": conv.closed_at,
        "trace": {"conversation_id": conv.id, "rule": "confirmed" if confirmed else "assumed"},
    }
```

每个字段都有用处。Stripe 要求先配置计量器（meter），之后计量事件必须带上事件名称、客户 ID、数值和时间戳（可选）。标识符用对话 ID 生成，而不是用发送时间，所以无论重发多少次，都只算一个结果。

`trace` 字段是很多人会跳过的部分。定价基础设施服务商 Stigg 认为，每个结果事件都必须能从产品追溯到发票。客户像开头那样发来仪表盘截图时，`trace` 能告诉你每一次解决是按哪条规则计费的。

值得提前检查的是“推定”这一类：这些结果是从客户离开推断出来的，客户自己的仪表盘可能不会把它们记为解决。

## 计数器要扛得住重试、延迟事件和峰值负载

Stigg 指出，用量数据管道的设计是对每个事件“至少投递一次”。换句话说，重复一定会发生，只是早晚问题。

Stripe 也建议使用幂等键，避免因网络延迟或其他错误导致同一事件上报两次。两端都要去重：在你自己的 outbox 表里去重，同时通过发给服务商的标识符去重。

第二个风险是时间。Stripe 异步处理计量事件，因此待开发票上的用量总数未必能立刻反映你刚发送的事件。

时间戳也必须离当前时间足够近。最关键的是，用量必须在当期发票定稿前上报；否则事件可能仍被接受，却永远不会计费。

第三个风险是吞吐量。Stripe v1 计量事件接口的上限是每个 Stripe 账户每秒 1,000 次调用。设想客户让 Agent 并行处理成千上万个对话，而你每次 LLM 调用都发一个事件。

上限很快就会碰到。有两条出路：按客户和时间窗口预聚合后发送总数，或者使用 v2 API 的流式接口（streams）。

最后是格式错误的事件。Stripe 通过错误 webhook 报告无效事件，并要求你修正后重发。如果没人监听这个 webhook，出错的事件会悄无声息地消失。收入就这样流失，直到周期末对账时才被发现。

## 在客户现场的工作顺序

第一步不是写代码。先和客户以及定价负责人坐下来，把“一个计费单位”的定义写成一句可以测试的话。

例如：“对话已关闭，客户确认解决，或离开且未再求助，每个对话最多计一次。”Intercom 的定义说明，识别结果的规则就写在定义本身里，每条规则都会变成代码里的一个 `if` 分支。

接下来，选择一个与合同配额层级一致的主体键：工作区、组织或客户。然后搭建 outbox：事件先连同幂等键写入你的数据库，再由一个 worker 推送到计费系统。这个 worker 需要知道发票定稿日期，以便在临近截止时队列积压的情况下发出告警。

权益层并行运行。Stigg 把基于结果的权益描述为一个额度余额：每确认一个结果就扣减一次，每个事件都重新校验。这道检查要放在请求路径上，读取实时余额来源，而不是去问一个只在周期末对账的计费系统。

最后是每日对账任务：在你的系统里按 `trace` 计数，与计费端的总数比对。差距小而稳定，通常是延迟事件；差距不断扩大，通常是没有幂等键的重试。

## 导致发票出错的常见错误

最常见的错误是用发送时间生成标识符，或者每次重试都重新生成 UUID，幂等键因此形同虚设。第二个错误是把待开发票当作拦截客户的余额来源。正如 Stripe 所警告的，这个数字是滞后的，客户可能在周期中途超额消耗。

第三个错误是合同按结果计费，代码却按动作发事件。第四个错误是没人监听错误 webhook。第五个更难察觉：没有保存导致事件计费的那条规则。客户对发票提出异议时，你拿不出任何依据。

从职业发展看，这项技能值得用具体细节来证明。阅读按用量销售的 AI 公司的 FDE 招聘信息时，留意“usage-based billing”“metering”或“entitlements”这些词。

在简历上，“设计了幂等的用量数据管道，每日与发票对账，实时执行配额”这样一行，比“集成了 Stripe”有分量得多。

## 本周练习

挑一个你正在做的产品流程，用恰好一句话写出它“一个计费单位”的定义。然后写一个测试，模拟一次包含三个动作和两次重试的对话。只有当系统恰好记录一个事件，并且附带外人也能读懂的 `trace` 时，测试才算通过。

如果能在客户发问之前做到这一点，周期末的那通电话会短得多：打开对账表给他们看就行。

**本周动手试试:**

- 在你的系统里选一个按用量计费的功能，写下它的幂等键。如果写不出一个在重试中保持不变的键，这就是第一个要修的 bug。
- 找到某个客户计费周期的发票定稿日期，测量你的数据管道中最慢的事件相对这个日期晚到多久。
- 重读你想申请的 FDE 招聘信息，划出“usage-based billing”“metering”和“entitlements”这些词。然后写一条简历要点，描述你做过的类似工作。

## 信源

- [Record usage for billing with the API](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage-api)

- [How usage-based billing works](https://docs.stripe.com/billing/subscriptions/usage-based/how-it-works)

- [Overview | OpenMeter by Kong (Entitlements & Limits)](https://openmeter.io/docs/billing/entitlements/overview)

- [Outcome-Based Pricing: How It Works](https://www.stigg.io/blog-posts/outcome-based-pricing)

- [Fin AI Agent outcomes | Intercom Help](https://www.intercom.com/help/en/articles/8205718-fin-ai-agent-pricing)
