郑龙捷
7d5e3e9a50
- 删除模型大类概览和细分银行概览中原型未包含的过渡跳转按钮，保留卡片点击、筛选、指标趋势和详情入口。 - 移除运维系统配置页中的模型平台新增页面依赖、登录角色来源等内部说明，仅保留实际配置内容。 - 将开发工作台访问控制统一收敛到 dashboard:view，业务团队仅保留运维工作台权限；直接访问开发工作台时自动回到运维工作台。 - 补充架构实现基线、外部写入协议、运维 API 清单、三角色权限验收说明和首条纵向链路联调手册。 - 按当前实现更新架构变更记录和本周目标完成情况。
145 lines
5.5 KiB
Markdown
145 lines
5.5 KiB
Markdown
# A 卡模型运维模块数据库外部写入协议 V0.1
|
||
|
||
> 状态：模型方评估稿；首条接口链路按本协议准备数据
|
||
> 日期：2026-09-02
|
||
> 目标：明确模型方写入哪些表，运维平台读取哪些字段，哪些字段由运维平台自行生成
|
||
|
||
## 一、当前首条链路的实际数据来源
|
||
|
||
当前后端首条链路不是读取 `ops_banks/ops_model_instances/ops_model_versions`，而是：
|
||
|
||
1. 模型部署和版本信息从 `model_deploy` 库读取。
|
||
2. 月度监控批次和监控结果从 `model_operations` 库读取。
|
||
3. 判级、复核和处理快照从 `model_operations` 库读取。
|
||
|
||
因此，模型方需要先按现有部署库表写入模型基础信息，再按运维库监控源表写入月度结果。`ops_banks`、`ops_model_instances`、`ops_model_versions` 如继续保留，应在后续确认后再接入，不能与当前链路同时作为模型主源。
|
||
|
||
## 二、模型方负责写入的部署库表
|
||
|
||
### 2.1 `model_deploy`
|
||
|
||
至少需要提供：
|
||
|
||
- `id`：部署实例主键。
|
||
- `code`：业务模型 ID，建议 Workspace 内唯一。
|
||
- `name`：模型名称。
|
||
- `modelType`：模型类型。
|
||
- `status`：部署状态；当前接口映射为正常/下线。
|
||
- `role`：部署角色；陪跑状态需要与现有枚举确认。
|
||
- `currentVersion`：当前版本号。
|
||
- `group_code`：Workspace 或模型大类映射信息。
|
||
- `space_id`：关联 `sys_project_space.id`。
|
||
- `gmtCreated`、`gmtModified`：创建和最后变更时间。
|
||
|
||
### 2.2 `model_bank`
|
||
|
||
- `bankNo`：银行编码。
|
||
- `bankName`：银行名称。
|
||
- `isWuji`：是否无极银行。
|
||
- `status`：银行是否有效。
|
||
|
||
### 2.3 `model_deploy_bank_map`
|
||
|
||
- `deployId`：对应 `model_deploy.id`。
|
||
- `bankNo`：对应 `model_bank.bankNo`。
|
||
- `status`：关系是否有效。
|
||
|
||
### 2.4 `model_version`
|
||
|
||
- `id`：版本主键。
|
||
- `deployId`：对应部署实例。
|
||
- `version`：版本号。
|
||
- `versionName`：版本展示名称。
|
||
- `isCurrent`：是否当前版本。
|
||
- `gmtCreated`、`gmtModified`：版本时间。
|
||
|
||
### 2.5 Workspace 映射
|
||
|
||
模型部署记录至少需要满足以下一种映射：
|
||
|
||
- `sys_project_space.name = 认证 Workspace 名称`；
|
||
- `sys_project_space.name = 认证 Workspace code`；
|
||
- `model_deploy.group_code = 认证 Workspace code`。
|
||
|
||
最终映射方式需要模型方和运维方共同确认。
|
||
|
||
## 三、模型方负责写入的运维库源表
|
||
|
||
### 3.1 `ops_monitor_batches`
|
||
|
||
模型方每次生成一个月度批次，至少写入：
|
||
|
||
- `batch_id`：批次 ID。
|
||
- `workspace_id`：认证 Workspace ID。
|
||
- `source_system`：来源系统。
|
||
- `source_batch_no`：来源批次号，必须幂等。
|
||
- `monitor_month`：监控月份，保存为该月第一天。
|
||
- `revision_no`：同月修订号，从 1 开始递增。
|
||
- `batch_status`：先写 `writing`，校验完成后改为 `published`。
|
||
- `expected_model_count`、`written_model_count`：模型数量校验。
|
||
- `feature_row_count`、`distribution_row_count`：明细行数校验。
|
||
- `checksum_sha256`、`generated_at`、`published_at`。
|
||
|
||
只有 `published` 批次对运维页面可见。
|
||
|
||
### 3.2 `ops_monitor_results`
|
||
|
||
每个模型每个月一行，至少写入：
|
||
|
||
- `monitor_result_id`：结果 ID。
|
||
- `workspace_id`：必须与批次和认证 Workspace 一致。
|
||
- `batch_id`：所属批次。
|
||
- `model_instance_id`：建议写 `model_deploy.id`，以便当前接口直接关联。
|
||
- `model_version_id`：对应 `model_version.id`。
|
||
- `monitor_month`：监控月份。
|
||
- `source_result_ref`：来源结果编号，可辅助追溯。
|
||
- `ranking_result`：`matched`、`unmatched` 或 `not_applicable`。
|
||
- `ks_value`、`psi_value`：数据库保存 0～1 比率。
|
||
- `sample_count`、`good_count`、`bad_count`。
|
||
- `source_result_json`、`source_calculated_at`：可选追溯字段。
|
||
|
||
当前查询服务兼容用 `model_deploy.id`、`model_deploy.code` 或版本 ID 作为关联标识，但生产环境必须固定一种主规则。
|
||
|
||
### 3.3 `ops_monitor_feature_metrics`
|
||
|
||
后续特征级页面需要时写入：特征编码、名称、IV、CSI、前期值、变化率以及来源 JSON。该表不用于首条三页面链路的最低验收。
|
||
|
||
### 3.4 `ops_monitor_distributions`
|
||
|
||
后续评分分布和特征分布页面需要时写入：分箱顺序、分箱标签、基准期/当期账户数和占比、好坏账户数、坏账率、PSI/CSI 分量。该表不用于首条三页面链路的最低验收。
|
||
|
||
## 四、运维平台自行生成的数据
|
||
|
||
以下数据不由模型方写入：
|
||
|
||
1. A/B/C 监控结果等级。
|
||
2. 一级/二级/三级异常等级。
|
||
3. 命中原因、处理建议和阈值解释。
|
||
4. 模型团队初审、业务团队终审和默认不处理记录。
|
||
5. 报告正文、报告版本、Prompt 版本和发送状态。
|
||
6. 流程进度、材料确认、知识库索引和平台使用统计。
|
||
|
||
模型方只负责提供原始指标及其追溯信息，不能直接写入判级和处理结果字段。
|
||
|
||
## 五、发布协议
|
||
|
||
1. 创建 `writing` 批次。
|
||
2. 写入模型月度结果和后续明细。
|
||
3. 校验模型数量、结果数量、指标范围、Workspace 和关联 ID。
|
||
4. 完成校验后将批次改为 `published`。
|
||
5. 同月旧批次改为 `superseded`，不覆盖历史数据。
|
||
6. 失败批次保留 `failed` 状态并记录原因。
|
||
|
||
## 六、最小联调数据
|
||
|
||
首条链路只需要：
|
||
|
||
- 1 条有效银行。
|
||
- 1 条有效模型部署。
|
||
- 1 条有效银行关系。
|
||
- 1 条有效模型版本。
|
||
- 1 条 `published` 监控批次。
|
||
- 1 条对应月份的监控结果。
|
||
|
||
如果需要展示等级和处理状态，再补 1 条当前判级记录及对应复核记录。
|