Token 治理

「Token 治理」从用户应付视角展示大模型调用的费用、请求量、Token 消耗与服务质量。它覆盖私有化部署模型与外部 API 渠道两种来源，帮助平台管理员、运营和租户快速定位异常消费、核对账单并配置模型单价。

入口路径：左侧菜单 计量计费 > Token 治理，页面路由 /admin/billing/governance。

页面菜单

页面	路由	说明
总览	/admin/billing/governance/overview	核心 KPI、趋势图、消费突增突降识别
模型分布	/admin/billing/governance/models	按模型聚合调用量、Token、账单
模型调用记录	/admin/billing/governance/calls	单笔调用明细、链路追踪、计费拆解
用户与工作区	/admin/billing/governance/consumers	按用户或工作区聚合消费排行
API 密钥	/admin/billing/governance/keys	Key 维度用量、启用/停用/锁定管理
API 密钥详情	/admin/billing/governance/key/:uuid	单个 Key 的趋势、模型分布、调用日志
模型计费策略	/admin/billing/governance/strategy	配置模型输入/输出/缓存等五段单价

---

总览：先看懂消费大盘

1. 进入 Token 治理 > 总览。
2. 在页面顶部选择时间范围（如最近 7 天/30 天）与 来源类型：
   • 全部：私有化模型 + API 渠道。
   • 私有化模型：只统计部署在本平台的推理服务。
   • API 渠道：只统计外部渠道转发的调用。
3. 查看 KPI 卡片：
   • 总费用 / 总请求数 / 总 Token / 活跃密钥数
   • 平均延迟 / 总错误率
4. 查看趋势图：Token 消耗、调用次数、延迟（含 P95）、错误率随时间变化。
5. 查看 Top Movers / Droppers：
   • 切换维度：模型 / 渠道 / API Key。
   • 切换周期：日 / 周 / 月 / 季。
   • 系统会按环比涨幅/跌幅排序，快速发现消费突增或骤降的对象。
6. 查看 Top 8 模型排行 与 API Key 排行，点击可下钻到对应明细页。

建议每天早上先看 Top Movers，发现异常消费后再去「模型调用记录」定位具体调用。

---

模型分布：按模型看用量

1. 进入 Token 治理 > 模型分布。
2. 选择时间范围与来源类型。
3. 页面展示：
   • 模型数量、总 Token、用户账单、平均延迟。
   • 「调用次数分布」与「账单分布」双饼图。
   • 模型聚合表格：来源类型、调用模型、调用次数、总 Token、用户账单、平均延迟、错误率。
4. 表格支持：
   • 点击列头排序。
   • 点击行操作「查看」下钻到该模型的调用记录。
   • 导出 CSV、调整列显隐。

---

模型调用记录：逐笔核对账单

1. 进入 Token 治理 > 模型调用记录。
2. 使用顶部搜索区组合筛选：
   • 时间范围
   • 调用模型 / 上游模型（支持手动输入）
   • API Key
   • 用户名 / 工作空间
   • 状态码 / 来源类型
3. 点击「展开/收起」可显示更多筛选项。
4. 列表展示每笔调用的基本信息：时间、状态码、调用模型、用户、工作区、总 Token、用户账单、总耗时、首 Token 时延等。
5. 点击某一行或「查看」打开调用详情抽屉：
   • 调用链路：客户端 → 网关 → 上游 → 完成，失败步骤会标红并展示错误大类。
   • 基本信息：Request ID、调用模型、上游模型、来源 IP、错误类别等关键字段可复制。
   • 计费明细：展开后展示输入/输出/缓存/缓存写入 5m/1h 各段的 Token 用量 × 单价，并与账单金额对账；不匹配时会高亮提示。
   • Token 用量：输入、输出、缓存、推理等细分。
   • 性能指标：总耗时、首 Token 时延、首字节时延。
   • 输入/输出原文：多模态内容以标签计数展示，可切换查看原始内容。

如果某条记录金额显示「计算中」，说明后台尚未完成定价处理；真正免费的调用会明确标注。

---

用户与工作区：看谁花了多少

1. 进入 Token 治理 > 用户与工作区。
2. 选择时间范围与来源类型。
3. 点击维度切换按钮：按 用户 或按 工作区 聚合。
4. 查看聚合表格：
   • 用户/工作区名称
   • 调用次数
   • 私有化 / API 渠道占比条形图
   • 总 Token、用户账单、平均延迟、错误率
5. 默认按调用次数降序排列，支持点击列头排序。
6. 点击行操作可下钻到该用户/工作区的调用记录。

「无归属」行代表 API 渠道外部调用，无法继续下钻。

---

API 密钥：管理调用凭证

查看 Key 用量

1. 进入 Token 治理 > API 密钥。
2. 选择时间范围与来源类型。
3. 表格展示每个 Key 的：
   • Key 名称、脱敏 Key 值、所有者
   • 状态（启用 / 停用 / 锁定）
   • 调用次数、总 Token、用户账单
4. 支持按状态、Key 名称筛选与排序。
5. 点击某行进入 API 密钥详情页，查看该 Key 的：

• Token / 费用 / 请求 / 延迟统计卡片
• Token 趋势图、调用模型分布饼图、响应延迟分布、错误率趋势
• 调用日志列表

启用、停用与锁定 Key

在 API 密钥详情页右上角点击「更多」按钮：

• 启用：恢复 Key 的调用能力。
• 停用：暂停 Key 的调用能力，已停用的 Key 再次启用即可恢复。
• 锁定：将 Key 锁定，通常用于安全风控场景；锁定后需手动启用才能恢复。

修改状态会立即生效，建议在操作前确认该 Key 是否仍有线上业务在调用。

---

模型计费策略：配置模型单价

模型计费策略用于对平台发布的模型设置输入/输出/缓存等五段单价，是 Token 治理统计用户账单的基础。

新建一条计费规则

1. 进入 Token 治理 > 模型计费策略。
2. 点击「新建规则」。
3. 填写 规则名称。
4. 选择 模型提供方 与 调用模型：
   • 下拉选项来自模型仓库中已启用的模型。
   • 支持手动输入提供方/模型名。
   • 选择「全部模型提供方」+「全部模型」可作为兜底价格。
5. 选择 计费单位：
   • 按 Token（元/1M tokens）：适合文本类 LLM。
   • 按次（元/次）：适合图像、音频、视频等非文本模型。
   • 按千秒 / 按千字符：适合语音等按时长或字符计费的场景。
6. 填写价格：
   • 按 Token 模式：必填 输入 Token 单价；输出、缓存读取、缓存写入 5 分钟/1 小时可通过开关启用并填写。
   • 按次 / 千秒 / 千字符模式：填写单一单价即可。
   • 档位价格表（仅按次模式）：可按模型协议参数设置不同档位的价格，档位名不能重复。
7. 选择 应用范围：
   • 平台级：对全平台生效。
   • 工作区级：选择具体工作空间，仅对该空间生效。
8. 填写 规则说明，便于后续审计。
9. 点击「确定」保存。

建议至少配置一条「全部提供方 + 全部模型」的兜底规则，避免新模型无价格导致计费缺失。

编辑、删除与查看修订记录

1. 在规则列表中找到目标规则。
2. 行操作：
   • 编辑：可修改规则名称、价格、说明；模型与应用范围创建后不可变更，如需调整请新建规则。
   • 删除：删除前会二次确认。
   • 修订记录：查看该规则的历史价格变化，含操作人、操作类型、价格涨跌幅度与说明。
3. 列表支持按规则名称、应用范围、提供方/模型筛选。

---

计费优先级（用户应付）

当一条调用命中多条规则时，平台按以下优先级匹配（越具体越优先）：

1. provider + workspace + model
2. provider + workspace + "*"
3. provider + model
4. provider + "*"
5. workspace + model
6. system + model
7. base 兜底

* 为通配符。配置策略时，可利用通配规则设置基础价，再用具体模型规则覆盖。

---

常见问题

Q：为什么总览里有些费用是 0？ A：可能是该调用未配置计费策略、仍在「计算中」，或被策略显式配置为 0 单价。

Q：如何确认用户账单计算正确？ A：在「模型调用记录」中打开详情抽屉，展开计费明细，逐段核对 Token 用量 × 单价是否与账单金额一致。

Q：为什么 API 渠道来源的调用不在 Token 治理里？ A：Token 治理默认统计用户应付视角。API 渠道成本（平台采购成本）请前往 计量计费 > API 渠道 查看。

Q：按次计费的档位名怎么填？ A：档位名需与模型协议中的参数精确匹配，且仅对异步生成路由生效；具体请参考对应生图/生视频/语音模型的协议文档。

Q：时间范围最大能选多久？ A：Token 治理页面的时间范围选择器会联动 KPI 卡片与图表，最大范围可能受产品限制（如 60 天），具体以页面提示为准。