Files

T

Songhaoz666andClaude Opus 4.8 e4a120b715 /metrics 暴露 run 级 cost_by_phase{initial,review_retry}（Refs #16 #37）

回应 @Mem0ried 在 PR #37 的对接问题：除逐条 budget.alert 事件的 cost_phase 外，详情
聚合也需能拆 initial/review_retry。build_runtime_metrics 新增 cost_by_phase 滚动汇总
（按 swarm_id，从各任务 usage.model_cost_usd/model_tokens 按 rework_attributions 归类），
GET …/{id}/metrics 返回 {initial,review_retry}:{cost_usd,model_tokens}。HM 详情聚合 /
客户端 08 用量抽屉可直接展示拆分，无需从事件推导。

测试 test-usage-cost-phase.py 增 /metrics 断言（reworked→review_retry、非 reworked→initial）；
usage-billing §5 记录该字段。

Refs #16
Refs #37

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-11 14:36:07 +08:00

6.1 KiB

Raw Blame History

用量与计费 Schema（Usage / Billing）

状态：已对齐既有边界（依据 heicode-mananger/docs/heicode.md §八、docs/heicode-runtime-auth-newapi-secret-design.md §四/五、docs/integration/Heicode-Manager-PayPal支付接入与计费关系说明.md §3/§5）。

配套：事件载体见 event-schema.md（budget.alert）；安全见 security-boundary.md。

1. 计费主线原则（不可破坏）

NewAPI 是计费账本：模型调用费用在 HM 模型网关 /v1/* 处按请求计量并扣费（NewAPI 的 user / token / group / quota / usage）。Swarm 不是账本，也不重算扣费。
Swarm 的职责 = 用量上报与预算约束，用于归因、观测与预算告警，不作为扣费依据。
归因主轴 = user.id / channelId / NewAPI user/token/group，不是 tenant/project。heicode-runtime-auth §六 明确：当前不引入 tenant/project 作为计费主轴。
Agent 基础设施成本（CPU/内存/Pod）当前未形成用户账本（PayPal 说明 §5）。

⚠️ 与工单口径的差异：工单要求「tenant attribution」；按 Manager 标准应改为 user/channelId 归因。如未来确需租户账本，需作为独立产品决策，不在本仓暗自添加。

2. 计费归因上下文（HM 下发，Swarm 透传）

来自 heicode-runtime-auth §五：

"billing_context": {
  "provider": "newapi",
  "newapi_user_ref": "newapi_user_123",
  "newapi_group": "development",
  "quota_ref": "newapi_token_or_group_quota_ref"
}

Agent 调模型走 HM /v1，用 HM 为该用户现签的 OPENAI_API_KEY（sk-），扣费即记在该用户名下；删 agent 时吊销。
Swarm 的 task_executor 随模型请求带 X-Agent-* / X-Agnet-* 归因头（manager_deployment_id、swarm_id、task_id、agent_role、correlation_id、model_id），供 HM/NewAPI 关联归因。

3. 预算约束（orchestration_plan.budget）

来自 PayPal 说明 §5：

字段	含义
`budget.max_tokens` / `token_limit`	本次部署 token 上限
`budget.max_cost_usd`	本次部署美元成本上限
`budget.duration_seconds` / `max_duration_seconds`	运行时长上限

Swarm 在运行中按时长/成本比例发 budget.alert（默认 80% 阈值），并在 metrics 返回预算占比。这是约束与告警，不是扣费。

4. 用量上报 Schema

4.1 Agent 单任务用量（task 结果 `usage`，已实现）

"usage": {
  "model_id": "gpt-4o-mini",
  "model_tokens": 0,
  "prompt_tokens": 0,
  "completion_tokens": 0,
  "model_cost_usd": 0.0,
  "runtime_seconds": 0.0,
  "billing_source": "newapi | unknown"
}

4.2 运行级用量事件（orchestrator，已实现）

通过 budget.alert 事件上报（payload 含）：

{
  "model_id": "...", "model_tokens": 0, "prompt_tokens": 0, "completion_tokens": 0,
  "model_cost_usd": 0.0, "runtime_seconds": 0.0, "billing_source": "...",
  "cost_phase": "initial | review_retry",   // #16：返工再执行的用量标 review_retry，供成本归属
  "attempt": 0,                              // 该任务的重做次数（retry_count）
  "manager_deployment_id": "...", "swarm_id": "...", "task_id": "...",
  "agent_role": "...", "correlation_id": "...",
  "budget": { "max_tokens": null, "max_cost_usd": null, "consumed_usd": 0.0, "remaining_usd": null }
}

4.3 目标完整回传形态（对齐 AM，部分待实现）

PayPal 说明 §5 给出的运行时用量回传目标：

{
  "deployment_id": "dep_xxx", "agent_instance_id": "agi_backend_001",
  "usage": {
    "model_tokens": 32000, "model_cost_usd": 4.21, "runtime_seconds": 930,
    "cpu_core_seconds": 1200, "memory_mb_seconds": 2048000
  },
  "billing_source": "newapi", "correlation_id": "corr_xxx"
}

5. 多 Agent / 评审重做成本聚合

一次 swarm 请求拆成多 task / 多 agent / 多评审轮；每个 task 的 usage 可按 swarm_id 聚合得到运行级合计（观测用途）。
评审重做成本（#16，已打标）：每轮重做重新执行任务并累计 usage，且其用量事件带 cost_phase="review_retry"（cross-review 已把该任务记入 rework_attributions 之后的再执行）；初次执行为 cost_phase="initial"。计费/采集侧按 swarm_id 聚合时，可用 cost_phase 拆分 initial vs review_retry 成本——「review retry 成本可归属」由此满足，无需从 retry_count 反推。
详情聚合（#37）：除逐条事件的 cost_phase 外，GET …/{id}/metrics 另返回 run 级滚动汇总 cost_by_phase: { initial: {cost_usd, model_tokens}, review_retry: {cost_usd, model_tokens} }，供 HM 详情用量聚合 / 客户端用量抽屉直接展示「初次 vs 返工」拆分，无需从事件流推导。

6. 字段覆盖与缺口

字段	状态
`model_tokens` / `prompt_tokens` / `completion_tokens`	✅ 已采集
`model_cost_usd`、`runtime_seconds`、`billing_source`	✅ 已采集
归因：`manager_deployment_id`/`swarm_id`/`task_id`/`agent_role`/`correlation_id`	✅ 已采集
`reasoning_tokens` / `cache_tokens`	🔴 未采集（取决于 provider usage 返回）
`tool_cost`（工具调用成本）	🔴 未采集（无 SK 工具计量）
`cpu_core_seconds` / `memory_mb_seconds`（基础设施）	🔴 未采集（K8s 指标未接入账本）
`review_retry` 成本单独打标	✅ 已打标（usage 事件 `cost_phase=review_retry`，#16）
provider 成本拆分	🟡 由 NewAPI/账本侧负责，非本仓
tenant 归因	❌ 按标准不使用（见 §1）

7. 待对齐项

运行级用量是否需独立 usage.report 事件类型（当前借 budget.alert 载体）；与 HM/Billing Team 确认（HM 注册表暂无 usage 事件）。
budget.alert 需补 threshold_pct（见 event-schema.md §6）。
若需基础设施计费，接入 K8s 用量（cpu/memory）并由 Billing Team 定义资源计价。
review_retry 成本是否需单独打标，由 Billing Team 决定。

6.1 KiB Raw Blame History Unescape Escape