105 lines
2.8 KiB
Markdown
105 lines
2.8 KiB
Markdown
|
# metadata-governance 技术设计（Design）
|
|||
|
|
|
|||
|
|
## 1. 设计目标
|
|||
|
|
|
|||
|
|
围绕已上线的元数据配置页面，补齐“配置 -> 录入 -> 检索 -> 治理”的闭环：
|
|||
|
|
- 元数据字段生命周期治理（draft/active/deprecated）
|
|||
|
|
- KB/Intent/Flow/Prompt 录入联动与一致性校验
|
|||
|
|
- Intent 路由后 metadata 过滤注入
|
|||
|
|
- 拆解模板版本治理与回溯
|
|||
|
|
|
|||
|
|
## 2. 架构与职责
|
|||
|
|
|
|||
|
|
### 2.1 元数据配置层（Admin）
|
|||
|
|
- 提供字段定义管理：`field_key/type/options/required/scope/status`
|
|||
|
|
- 提供字段状态治理：
|
|||
|
|
- `draft`: 可编辑不可生效
|
|||
|
|
- `active`: 可用于新建与编辑
|
|||
|
|
- `deprecated`: 不可用于新建，历史可读
|
|||
|
|
|
|||
|
|
### 2.2 录入联动层（Admin Forms）
|
|||
|
|
- 在以下录入页统一挂载 metadata 表单组件：
|
|||
|
|
- KB 文档
|
|||
|
|
- Intent Rule
|
|||
|
|
- Script Flow
|
|||
|
|
- Prompt Template
|
|||
|
|
- 联动逻辑：对象类型变化时，根据 `scope` 动态渲染字段
|
|||
|
|
- 校验逻辑：required 字段 + 类型校验 + enum 值校验
|
|||
|
|
|
|||
|
|
### 2.3 检索治理层（Runtime）
|
|||
|
|
- 路由流程：Intent 命中 -> 目标知识库集合 -> metadata filters -> 向量召回
|
|||
|
|
- metadata 注入来源：会话上下文、已提取槽位（grade/subject/scene）
|
|||
|
|
- 兜底策略：无召回时 fallback（指定库或固定话术）并输出原因码
|
|||
|
|
|
|||
|
|
### 2.4 模板治理层（Ops）
|
|||
|
|
- 拆解模板持久化与版本管理
|
|||
|
|
- 提供最新生效版本查询能力
|
|||
|
|
|
|||
|
|
## 3. 数据模型建议
|
|||
|
|
|
|||
|
|
### 3.1 MetadataSchema
|
|||
|
|
- id
|
|||
|
|
- field_key
|
|||
|
|
- label
|
|||
|
|
- type
|
|||
|
|
- required
|
|||
|
|
- options
|
|||
|
|
- default_value
|
|||
|
|
- scope
|
|||
|
|
- is_filterable
|
|||
|
|
- is_rank_feature
|
|||
|
|
- status
|
|||
|
|
- version
|
|||
|
|
- created_at/updated_at
|
|||
|
|
|
|||
|
|
### 3.2 MetadataPayload（挂载到业务对象）
|
|||
|
|
- object_type
|
|||
|
|
- object_id
|
|||
|
|
- metadata: key-value
|
|||
|
|
- schema_version
|
|||
|
|
|
|||
|
|
### 3.3 DecompositionTemplate
|
|||
|
|
- id
|
|||
|
|
- name
|
|||
|
|
- template_content
|
|||
|
|
- version
|
|||
|
|
- status
|
|||
|
|
- created_at/updated_at
|
|||
|
|
|
|||
|
|
## 4. 关键流程
|
|||
|
|
|
|||
|
|
### 4.1 配置到生效流程
|
|||
|
|
1. 管理员创建/编辑字段（draft）
|
|||
|
|
2. 审核后切换 active
|
|||
|
|
3. 录入页拉取 active 字段并动态渲染
|
|||
|
|
4. 字段 deprecated 后，新建不可选，历史只读可见
|
|||
|
|
|
|||
|
|
### 4.2 运行时检索流程
|
|||
|
|
1. Intent Rule 命中 response_type=rag
|
|||
|
|
2. 选择目标知识库（支持多库）
|
|||
|
|
3. 注入 metadata 过滤条件
|
|||
|
|
4. 执行向量检索
|
|||
|
|
5. 无召回走 fallback，并记录原因码
|
|||
|
|
|
|||
|
|
## 5. 错误与降级策略
|
|||
|
|
|
|||
|
|
- 配置异常：字段配置缺失/冲突 -> 使用系统默认字段集
|
|||
|
|
- 过滤异常：metadata 过滤构造失败 -> 降级为不加过滤检索（记录 warning）
|
|||
|
|
- 无召回：返回 fallback 并记录 `no_recall_after_metadata_filter`
|
|||
|
|
|
|||
|
|
## 6. 可观测性
|
|||
|
|
|
|||
|
|
- 关键日志字段：
|
|||
|
|
- `intent_id`
|
|||
|
|
- `target_kbs`
|
|||
|
|
- `applied_metadata_filters`
|
|||
|
|
- `fallback_reason_code`
|
|||
|
|
- `latency_ms`
|
|||
|
|
|
|||
|
|
## 7. 与 AC 对齐
|
|||
|
|
|
|||
|
|
- 字段状态治理：AC-IDSMETA-13~14
|
|||
|
|
- 跨模块录入联动：AC-IDSMETA-15~17
|
|||
|
|
- 路由与检索治理：AC-IDSMETA-18~20
|
|||
|
|
- 模板治理：AC-IDSMETA-21~22
|