控制平面

控制平面是平台的管理接口面，前缀 /api/v1，资源化 REST 风格。控制台上"看数据、管配置"的全部功能都经由控制平面接口完成。同一套接口同时服务客户 Portal 与运营控制台，视角由登录会话注入——运营专属口径只在运营视角返回，客户视角一律不返回该类字段。

认证统一为控制台会话凭证（下文示例以 Cookie: <控制台会话凭证> 表示）。分页、错误结构、通用查询参数见 API 参考通用约定。

下表按功能域列出端点分组，可见侧 取 客户 / 运营 / 双视角同源（同一端点按视角返回不同口径）：

1. 概览

客户进入平台第一屏的汇总展板。四类汇总指标与趋势数据单请求返回，整页渲染。

概览的数字是用量、账单、服务质量、额度各明细端点的汇总，与各明细端点同源，跨页面比对一致。

2. 请求监控

查询路由运行监控。聚合视图与路由轨迹明细两类。

运营视角下，请求监控聚合可按上游分组下钻；监控指标与计量明细取自同一份用量底座。

3. 用量与计量明细

统一计价词元的六档汇总与逐条调用记录查询，是计量与计费的事实层。

逐条调用记录响应含顶部汇总与逐条数组（字段语义如下，数值仅为占位）：

{
  "total": 0,
  "page": 1,
  "page_size": 20,
  "summary": {
    "total_input_tokens": 0,
    "total_output_tokens": 0,
    "total_amount": "<筛选范围金额合计（含税）>"
  },
  "items": [
    {
      "call_id": "<调用唯一标识>",
      "api_key_id": "<所属子账户>",
      "timestamp": "<调用时间 YYYY-MM-DD HH:mm:ss>",
      "call_hash": "<调用信息哈希（脱敏，不含原文）>",
      "routed_model": "<本次路由选定的上游模型中性名>",
      "complexity": "<复杂度研判结果（简单 / 复杂）>",
      "cache_hit": false,
      "thinking": false,
      "input_tokens": 0,
      "output_tokens": 0,
      "price_tier": "<适用单价档（六档之一）>",
      "training_discount": "<训练期折扣标识（折扣计价 / 全额计价）>",
      "charge_amount": "<该次折算金额（含税）>",
      "guardrail_result": "<护栏处置结果（通过 / 拦截 / 脱敏 / 误拒）>"
    }
  ]
}

同源与可核验。 逐条之和等于按子账户分项之和、等于用量总览汇总。逐条记录中的 input_tokens / output_tokens 可经数据平面 POST /v1/token-count（见 数据平面）对相应文本复算核对。training_discount 标明训练期内的折扣计价情形，标识口径以服务协议与控制台为准。

4. 账单与结算

月度服务费用结算单视图与确认。

结算单详情响应（字段语义；数值与税率以服务协议与控制台为准）：

{
  "billing_month": "<结算月 YYYY-MM>",
  "title": "<结算单抬头>",
  "line_items": [
    {
      "api_key_id": "<子账户标识>",
      "amount": "<该子账户应付（含税）>"
    }
  ],
  "total_amount": "<含税合计>",
  "metering_version": "<计量口径版本号>",
  "confirm_status": "<确认状态（待确认 / 已确认）>"
}

结算单口径。 结算单数字等于用量明细汇总、等于概览展板对应卡片，同源。结算单为产品化账单视图，仅含计量与金额信息，不含任何当事方签署栏或结论栏。结算月、含税率、确认默认期等以服务协议与控制台为准；逾期未确认按服务协议约定默认视为确认。

5. 信用额度

汇总信用额度查询、变更记录与提额工单。额度为单层汇总，约束全部子账户密钥。

额度查询响应（字段语义；额度与阈值以服务协议与控制台为准）：

{
  "monthly_limit": "<月度额度上限>",
  "used_this_month": "<当月已用>",
  "usage_rate": "<使用率>",
  "status": "<状态（正常 / 预警 / 暂停）>",
  "contract_cap": "<首个服务期合同金额上限>"
}

达额暂停。 额度为单层汇总，无逐密钥子额度。当月已用达额度上限时，全部子账户密钥一并暂停；接近上限时进入预警态。提额按书面 / 邮件 / 正式方式提交工单，生效后记入额度变更记录。提额工单是信用额度域内的能力，平台不另设独立工单或工作流系统。

6. API 密钥

按部门 / 业务线 / 成本中心的子账户密钥生命周期管理与分账。

新建密钥的本体仅在创建时返回一次，请妥善保存。单密钥用量与用量明细同源，是用量明细按密钥维度的切片。达汇总信用额度时全部密钥一并暂停（无逐密钥子额度）。

7. 安全防护

护栏策略配置、正反样本调优、拦截统计与能力基线。六类护栏能力的说明见 安全护栏。

护栏分类为注入防护 / 脱敏 / 应拒答拦截 / 访问控制；能力基线以应拒答拦截率与误拒率、对抗拦阻率与良性误拦率等成对呈现。策略配置与样本调优仅运营视角可见；具体基线阈值以服务协议与控制台为准。

8. 模型评测

护栏能力基线与通用能力评测报告。

报告含护栏能力基线与通用能力多项指标，按目标基线与实测值对照呈现通过态，附评测快照日与重放均值口径。评测维度、目标线与快照口径的读法以服务协议与控制台为准。

9. 服务质量（SLA）

平台对客户的服务质量月度达成报表。

报表给出各服务质量指标的目标值、实测值与达成态，以及违约阈值、统计排除项与未达情形处理。指标口径与阈值以服务协议与控制台为准。

10. 中间件管道

中间件管道编排配置与扩展点。编排模型详见 中间件管道与扩展点 SDK。

编排接口仅运营视角可见。段间顺序（前置 → 内建 → 后置）固定，/api/v1/pipeline/order 只接受段位内重排。扩展点能力边界标注须明确"中间件仅施加治理面处置，不实质性生成或加工内容"。

11. 模型接入

多上游模型聚合接入与模型池准入。

自有供应模型对应自托管上游，第三方对应 OpenAI / Anthropic / Gemini 兼容接入。模型池准入门槛以智能水平指数判定，门槛值以服务协议与控制台为准。批发价等成本口径仅运营视角可见，客户侧模型仅以中性名出现。

12. 模型微调

路由小模型微调工具链。

路由小模型权属归客户、在客户部署实例内训练；训练期、删除窗口与数据隔离口径以服务协议与控制台为准。正反样本训练接口为说明性呈现。

13. 上游 SLA 监控

供应商对平台的服务质量月度达成报表。

报表给出平台可用率、故障响应、恢复、扩展点稳定性、模型供应支撑等指标的目标值、实测值与达成态。本组为运营内部口径，与第 9 节"平台对客户服务质量"是两套独立的指标集与数据集，分别承载，不靠视角切换。

14. 部署与许可

双部署模式状态与许可有效期。

部署状态响应（字段语义）：

{
  "deploy_mode": "<部署模式（private 私有化 / saas SaaS·VM 级逻辑隔离）>",
  "deploy_status": "<部署可用性（ready 已部署·正常可用 / 其他）>",
  "license": {
    "valid_until": "<许可失效日>",
    "kill_switch": false
  }
}

平台支持私有化（部署于客户控制环境）与 SaaS（部署于供应方环境，VM 级逻辑隔离）双部署模式，二者功能一致。许可失效开关一旦置位，数据平面停止受理新请求。月度可用率等速率指标归上游 SLA 监控（第 13 节），本端点只取部署状态二值与许可有效期。

15. 数据安全

数据合规策略、退出导出与清理任务。

退出导出物（中间件、编排脚本、策略配置、路由小模型）权属归客户。数据留存与个人信息策略口径以服务协议为准。

16. 会话与账户设置

支撑两控制台进入与视角注入的最小必要会话接口，以及账户设置。

登录成功后下发会话凭证，视角由平台按账户归属注入，无需在请求中声明。账户设置承载最简账户信息与接入参数；客户侧呈现为「账户设置」，运营侧同形为「平台设置 · 接入参数」。密钥认证说明并入登录与账户设置，不单设接口。

端点覆盖小结

控制平面按 16 个功能域组织端点，覆盖客户 Portal 与运营控制台的全部管理能力；其余周边支撑（组织成员、通知、独立操作日志、主题偏好、工作流等）不在平台范围内，相应不设端点。数据平面端点见 数据平面，通用接口约定见 API 参考通用约定。