Songhaoz666andClaude Opus 4.8
e4a120b715
回应 @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>
112 lines
6.1 KiB
Markdown
112 lines
6.1 KiB
Markdown
# 用量与计费 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`](./event-schema.md)（`budget.alert`）；安全见 [`security-boundary.md`](./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 §五`：
|
||
|
||
```jsonc
|
||
"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`，已实现）
|
||
```jsonc
|
||
"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 含）：
|
||
```jsonc
|
||
{
|
||
"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 给出的运行时用量回传目标：
|
||
```jsonc
|
||
{
|
||
"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 决定。
|