Token 使用量计费

简介

本指南通过遵循平台的 自定义成本模型 工作流,为 AI Gateway token 使用量定义一个自定义成本模型。其结构与官方 vGPU (Hami) 成本模型 指南一致:先在 Cost Management agent 集群上添加 collection 配置,再在 Cost Management server 集群上添加 display/storage 配置,最后通过平台控制台为成本模型添加价格。

Cost Management 会消费由 Metering Token Usage 收集的 OpenTelemetry GenAI token 指标,并以 user_namespace 标签为键,将其转换为按 namespace 计费的账单。在多集群部署中,Cost Management server 和 Cost Management agent 可能位于不同的集群;下面每一步都会说明必须在哪个集群上执行。

使用场景

  • 按 namespace 或 tenant 对其消耗的 AI Gateway token 进行计费。
  • 按模型设置单价,使更昂贵的模型每个 token 的成本更高。
  • 使用与仪表盘相同的指标生成可审计的分摊计费报表。

前提条件

  1. Metering Token Usage 已配置:PodMonitor 正在采集 token 指标,并且控制器将 x-user-namespace:user_namespace 映射到该序列,使其携带 user_namespace 标签。请确认该指标可以从 agent 集群的平台 Prometheus(或 Thanos)中查询到:

    # In Prometheus, this must return a non-empty vector:
    #   sum by (user_namespace) (increase({__name__="gen_ai.client.token.usage_token_sum"}[1h]))
  2. 已安装 Cost Management:server 集群上安装了 cost-server 和 cost-api,每个需要对其 AI Gateway 流量计费的集群上安装了 cost-agent。请参见 Cost Management 安装。

  3. 具备两个集群的 kubectl 访问权限,并且有权限在 cpaas-system(agent 集群)和 kube-public(server 集群)中写入 ConfigMap。

步骤

添加 collection 配置

集群: Cost Management agent 集群——即运行 AI Gateway 且已安装 cost-agent 的集群。cost-agent 组件作为 slark-agent workload 部署,下面的重启命令会针对它执行。

创建一个 ConfigMap,用于告诉 Cost Management agent 要评估哪个 Prometheus 查询,以及如何将其标签映射到 Cost Management 维度。agent 会发现位于 cpaas-system 中、带有 cpaas.io/slark.collection.config: "true" 标签的配置。

apiVersion: v1
kind: ConfigMap
metadata:
  name: slark-agent-aigateway-config
  namespace: cpaas-system
  labels:
    cpaas.io/slark.collection.config: "true"
data:
  config: |
    - kind: AIGateway
      category: AIGatewayToken
      item: AIGatewayTokenUsage
      period: Hourly
      usage:
        query: |
          sum by (user_namespace, "gen_ai.request.model") (
            increase({__name__="gen_ai.client.token.usage_token_sum"}[5m])
          )
        step: 5m
        mappers:
          name: gen_ai.request.model
          namespace: user_namespace
          cluster: ""
          project: user_namespace

字段说明:

  • kind:Cost Management collector 的种类,同时也是 collector 的名称(在 collection 配置中需保持唯一)。Pod 保留给 OpenCost 输出的 pod 指标,Project 保留给平台内置的 CPU/Memory/Storage 配额 collector。AI Gateway token 使用量使用专用的自定义 kind AIGateway,与 vGPU/NPU/pGPU 自定义 kind 模式一致——该值会在集群上进行验证,以便将 cost.usage 填充为 AIGatewayTokenUsage 行。应用此配置后,请先确认已经出现对应行(见 Troubleshooting 中的 cost.usage 检查),再继续后续步骤。
  • category、item:用于在下一步中将此 collection 配置与其 display/storage 对应项关联的标识符。这两个值必须与 display/storage 配置中的对应字段一致。
  • period:聚合周期。按小时计费时使用 Hourly。
  • usage.query:agent 每次 step 执行的 PromQL 查询。平台会将该指标以其 OpenTelemetry UTF-8 名称存储,并保留点号,因此请使用 {__name__="gen_ai.client.token.usage_token_sum"} 进行选择,并使用带引号的 UTF-8 语法引用带点号的 gen_ai.request.model 标签。通过 header 映射得到的 user_namespace 标签是按 namespace 计费的键。
  • usage.step:查询评估间隔。
  • usage.mappers:将 PromQL 标签映射到 Cost Management 的标准维度(name、namespace、cluster、project)。将 cluster 设为空字符串,使 agent 自动填充自身的集群身份;如果将其设置为某个标签名(例如 cluster),则只有当源指标暴露了该标签时才会生效,否则每一行都会被丢弃且不会留下日志。

应用 YAML 后,重启 slark-agent workload(即 cost-agent 组件)以重新加载配置:

kubectl -n cpaas-system delete pod \
  -l service_name=slark-agent --grace-period=0 --force
kubectl -n cpaas-system rollout status deploy/slark-agent
# if slark-agent is installed as a DaemonSet in your environment, use instead:
#   kubectl -n cpaas-system rollout status daemonset/slark-agent

添加 display 配置

集群: Cost Management server 集群——即安装了 cost-server 的集群(通常是全局 control plane)。cost-server 组件作为 slark-server workload 部署,下面的重启命令会针对它执行。

创建一个 ConfigMap,在平台控制台中注册计费项及其计费方式。server 会发现位于 kube-public 中、带有 cpaas.io/slark.display.config: "true" 标签的配置。

apiVersion: v1
kind: ConfigMap
metadata:
  name: slark-display-config-for-aigateway
  namespace: kube-public
  labels:
    cpaas.io/slark.display.config: "true"
data:
  config: |
    - name: AIGatewayToken
      displayname:
        zh: "AI Token"
        en: "AI tokens"
      methods:
        - name: Usage
          displayname:
            zh: "使用量"
            en: "Token Usage"
          item: AIGatewayTokenUsage
          unit:
            zh: "tokens"
            en: "tokens"
          divisor: 1

字段说明:

  • name:在成本模型表单中显示的计费项名称。必须与 collection 配置中的 category 值一致。
  • methods[].name:计费方式,在添加价格时会显示在该计费项下。
  • methods[].item:必须与 collection 配置中的 item 值一致,这样 server 才能将按方法设置的价格与使用量行关联起来。
  • divisor:用于展示使用量时的单位换算因子。token 没有单位,因此设置为 1;对于字节大小的项,使用 1073741824 可显示为 Gi-hours。

下表总结了此配置注册的计费方式:

计费项计费方式源项描述
AI tokensToken UsageAIGatewayTokenUsage每个 namespace、每个模型每小时消耗的输出 + 输入 token
WARNING

请勿修改平台安装的 slark-server-common-config(包含 CPU、Memory 和 Storage 的默认 display 配置)。向其中添加自定义项会导致 server 在启动时校验失败。务必将自定义计费项作为单独的、带有 cpaas.io/slark.display.config: "true" 标签的 ConfigMap 添加。

应用 YAML 后,重启 slark-server workload(即 cost-server 组件)以重新加载配置:

kubectl -n cpaas-system delete pod \
  -l service_name=slark-server --grace-period=0 --force
kubectl -n cpaas-system rollout status deploy/slark-server

为成本模型添加价格

集群: 任意集群——通过由 cost-api 提供的平台控制台操作。

在平台控制台中,进入 Administrator → Metering and Billing → Cost Model,然后创建或编辑一个成本模型。新注册的 AI tokens 计费项现在可以在价格表单中选择了。

  1. Cost Model Name:任意标识符,例如 aml-cost-model。
  2. Linked Clusters:选择此模型应对其 AI Gateway 流量定价的集群。即使不选择任何集群也能成功保存,但不会匹配任何使用数据,因此不会生成任何账单。
  3. Pricing rows:
    • Billing Item:AI tokens
    • Billing Method:Token Usage
    • Default Price:每个 token 的费率,使用平台的货币单位。
    • Price By Label(可选):按模型覆盖价格,例如为 gen_ai.request.model="gpt-4o" 设置更高费率。
  4. 保存。

验证

cost-server worker 每五分钟运行一次。通过 AI Gateway 发起几次带不同 x-user-namespace 值的已认证请求,至少等待一个 worker 周期,然后刷新平台控制台。

  • Cost Details(Administrator → Metering and Billing → Cost Details)会显示按 namespace 列出的 AI tokens 明细项。可按 namespace 或日期过滤以进一步查看。
  • Cost Statistics(Administrator → Metering and Billing → Cost Statistics)会按 cluster、project 和时间范围汇总相同的数据。

在打开 UI 之前,可在 server 集群上直接查询 ClickHouse 进行服务器侧验证:

SELECT namespace, project, date, usage, cost
  FROM cost.bills
 WHERE item = 'AIGatewayTokenUsage'
 ORDER BY date DESC, cost DESC
 LIMIT 10;

预期每个消耗了 token 的(namespace, hour)组合都会有一行。cost 列存储的是平台的微货币单位,因此 usage × default_price × 1_000_000 应与显示值一致。

故障排查

症状可能原因及处理办法
一个 agent 周期后,cost.usage 中没有 AIGatewayTokenUsage 行检查 collection 的 ConfigMap 是否位于 cpaas-system,且带有 cpaas.io/slark.collection.config: "true"。检查在应用后是否已重启 cost-agent。检查 PromQL 在平台 Prometheus 上是否返回非空向量——仅使用下划线形式的指标名(gen_ai_client_token_usage_token_sum)不会匹配任何内容;应使用 {__name__="gen_ai.client.token.usage_token_sum"} 选择器。检查 mappers.cluster: "" 是否确实为空字符串。
AI tokens 计费项未出现在成本模型表单中检查 display/storage ConfigMap 是否位于 kube-public(而不是 cpaas-system),并带有 cpaas.io/slark.display.config: "true"。检查在应用后是否已重启 cost-server。检查 methods[].item 是否与 collection 的 item 完全一致。
cost.usage 有行,但 cost.bills 中没有 AIGatewayTokenUsage在平台控制台中打开成本模型,确认 Linked Clusters 下至少选择了一个集群。worker 还会跳过在 cost.milestones 中已标记为 Done 的分组;如果在模型变更后需要重新计算历史时间窗,请删除 cost.milestones 中的相关行,并等待下一次 worker 周期。
每次 tick 时,worker 日志都显示 Try to skip as no model {"group": "<cluster>/<window>"}成本模型的 Linked Clusters 不包含 agent 报告的那个集群。编辑该模型并添加该集群。

了解更多

下一步

在生成账单后,可在 Price By Label 下设置按模型的价格覆盖项,以反映各模型的相对成本,并安排定期导出 cost.bills 供财务报表使用。