313 lines
7.8 KiB
Markdown
313 lines
7.8 KiB
Markdown
# 数据模型总览
|
||
|
||
**更新日期**：2026-07-08
|
||
**状态**：当前可运行架构
|
||
|
||
## 1. 定位
|
||
|
||
本文从架构角度说明当前 MVP 的核心数据模型。详细字段仍以 Flyway migration 和 `mvp/tables/` 为准。
|
||
|
||
核心数据分三组：
|
||
|
||
- 诊断 Trace：`diagnosis_session`、`agent_step`、`tool_invocation`
|
||
- 知识库：`api_document`、`knowledge_domain`、Milvus/Zilliz metadata
|
||
- 反馈沉淀：`case_library`
|
||
|
||
## 2. 总体关系
|
||
|
||
```mermaid
|
||
erDiagram
|
||
diagnosis_session ||--o{ agent_step : has
|
||
diagnosis_session ||--o{ tool_invocation : has
|
||
diagnosis_session ||--o| case_library : creates_when_useful
|
||
api_document ||--o{ milvus_chunk : indexed_as
|
||
knowledge_domain ||--o{ api_document : groups
|
||
|
||
diagnosis_session {
|
||
bigint id
|
||
varchar session_id
|
||
text query
|
||
varchar status
|
||
varchar agent_flow
|
||
longtext answer
|
||
json self_evaluation
|
||
varchar feedback
|
||
}
|
||
|
||
agent_step {
|
||
bigint id
|
||
varchar session_id
|
||
int step_index
|
||
varchar agent_name
|
||
text model_input
|
||
text model_output
|
||
text thought
|
||
boolean has_tool_call
|
||
}
|
||
|
||
tool_invocation {
|
||
bigint id
|
||
varchar session_id
|
||
varchar tool_name
|
||
json input_params
|
||
text output_preview
|
||
varchar retrieval_layer
|
||
json retrieval_details
|
||
varchar relevance_level
|
||
varchar dedup_reason
|
||
}
|
||
|
||
api_document {
|
||
bigint id
|
||
varchar doc_id
|
||
varchar file_name
|
||
varchar file_path
|
||
varchar status
|
||
int chunk_count
|
||
text metadata
|
||
}
|
||
|
||
knowledge_domain {
|
||
bigint id
|
||
varchar domain_id
|
||
varchar description
|
||
text when_to_retrieve
|
||
int document_count
|
||
}
|
||
|
||
case_library {
|
||
bigint id
|
||
varchar case_id
|
||
varchar diagnosis_id
|
||
varchar source_type
|
||
varchar fault_category
|
||
text root_cause
|
||
text solution
|
||
}
|
||
|
||
milvus_chunk {
|
||
varchar id
|
||
text content
|
||
json metadata
|
||
vector vector
|
||
}
|
||
```
|
||
|
||
说明：Milvus/Zilliz collection 不是 MySQL 表，图中的 `milvus_chunk` 是逻辑模型。
|
||
|
||
## 3. 诊断 Trace 模型
|
||
|
||
### diagnosis_session
|
||
|
||
会话级主记录。
|
||
|
||
关键字段：
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `session_id` | 外部关联键，Trace 和 Feedback 都使用它 |
|
||
| `query` | 用户原始问题或 AIOps 输入摘要 |
|
||
| `status` | 执行状态 |
|
||
| `agent_flow` | `CHAT` / `AI_OPS` |
|
||
| `answer` | 最终答复或告警报告 |
|
||
| `self_evaluation` | rule/verifier/aiops 自评估容器 |
|
||
| `feedback` | 用户反馈 |
|
||
|
||
### agent_step
|
||
|
||
记录模型调用步骤。
|
||
|
||
用途：
|
||
|
||
- 回放 Agent 推理过程。
|
||
- 查看 Planner / Executor / Verifier 的输入输出摘要。
|
||
- 统计 step count、duration、token count。
|
||
|
||
### tool_invocation
|
||
|
||
记录工具调用事实。
|
||
|
||
用途：
|
||
|
||
- 给 Trace API 展示证据。
|
||
- 给 Gatekeeper 提供 `retrieval_details.evidence_refs` 引用验真源。
|
||
- 给 Verifier 构造 `tool_trace_summary` 审计导航。
|
||
- 给 `EvaluationService` 计算 evidence score。
|
||
- 给 RAG eval 和人工排查提供检索细节。
|
||
|
||
`retrieval_details.evidence_refs` 是当前 Chat 证据链路的关键字段：
|
||
|
||
```json
|
||
{
|
||
"evidence_status": "supported",
|
||
"evidence_refs": [
|
||
{
|
||
"raw_path": "$.logs[0]",
|
||
"text": "2026-07-08 23:05:28 ERROR order-service HikariPool-1 - Connection is not available..."
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
字段边界：
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `evidence_status` | 工具证据状态，例如 `supported`、`no_evidence`、`deduped`、`failed` |
|
||
| `evidence_refs[].raw_path` | Executor 可引用的稳定路径，例如 `$.logs[0]`、`$.alerts[0]`、`$.evidence_blocks[0]`、`$.no_evidence` |
|
||
| `evidence_refs[].text` | 系统抽取的最小证据文本，Gatekeeper 用它核对 `evidence_excerpt` |
|
||
|
||
`$.no_evidence` 只表示“本次工具查询未检索到匹配证据”，不能被解释为“问题不存在”或“根因已排除”。
|
||
|
||
## 4. 知识库模型
|
||
|
||
### api_document
|
||
|
||
MySQL 中的文档元数据表。
|
||
|
||
职责：
|
||
|
||
- 管理上传文件。
|
||
- 保存 file hash，用于去重。
|
||
- 记录索引状态和 chunk 数量。
|
||
- 保存 frontmatter JSON。
|
||
|
||
### knowledge_domain
|
||
|
||
领域级元数据。
|
||
|
||
职责：
|
||
|
||
- 按 category 聚合文档。
|
||
- 存储领域描述。
|
||
- 存储 `when_to_retrieve`，辅助 Planner/Executor 判断什么时候检索该领域。
|
||
|
||
### Milvus/Zilliz metadata
|
||
|
||
向量 collection 中每个 chunk 的 metadata 主要包括：
|
||
|
||
```text
|
||
docId
|
||
_source
|
||
chunkIndex
|
||
totalChunks
|
||
title
|
||
breadcrumb
|
||
category
|
||
```
|
||
|
||
这些字段支撑：
|
||
|
||
- category filter。
|
||
- source 展示。
|
||
- breadcrumb 上下文。
|
||
- docId 删除和重建索引。
|
||
- evidence block 构造。
|
||
|
||
## 5. 反馈沉淀模型
|
||
|
||
### case_library
|
||
|
||
`useful` 反馈会触发 `CaseLibraryService.createFromSession`。
|
||
|
||
当前自动映射：
|
||
|
||
| 字段 | 来源 |
|
||
|---|---|
|
||
| `case_id` | UUID |
|
||
| `diagnosis_id` | `diagnosis_session.session_id` |
|
||
| `source_type` | `AUTO` |
|
||
| `fault_category` | 当前默认 `GENERAL` |
|
||
| `title` | session query 前 100 字符 |
|
||
| `root_cause` | session answer |
|
||
| `solution` | session answer |
|
||
| `created_by` | `system` |
|
||
|
||
## 6. self_evaluation 结构
|
||
|
||
`diagnosis_session.self_evaluation` 是 JSON 容器：
|
||
|
||
```json
|
||
{
|
||
"rule_evaluation": {},
|
||
"verifier_evaluation": {},
|
||
"aiops_rule_evaluation": {}
|
||
}
|
||
```
|
||
|
||
边界：
|
||
|
||
- `rule_evaluation` 评估证据收集充分度。
|
||
- `verifier_evaluation` 评估 Chat 结构化 claims 是否能由已验真证据推出，并保存 Gatekeeper、Verifier、Composer 的审计数据。
|
||
- `aiops_rule_evaluation` 评估 AIOps 报告是否聚焦告警并使用证据。
|
||
|
||
当前 `verifier_evaluation` 关键结构：
|
||
|
||
```json
|
||
{
|
||
"verdict": "PASS",
|
||
"groundedness_score": 1.0,
|
||
"critical_fact_count": 1,
|
||
"claim_checks": [],
|
||
"facts_checked": [],
|
||
"rationale": "...",
|
||
"round": 1,
|
||
"traceability_version": "v1",
|
||
"executor_output_parse_status": {},
|
||
"executor_structured_output": {},
|
||
"gatekeeper_result": {},
|
||
"composer_output": {},
|
||
"tool_trace_summary": []
|
||
}
|
||
```
|
||
|
||
必要审计字段：
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `executor_output_parse_status` | Executor 输出是否能解析为 `executor_evidence_v2` |
|
||
| `executor_structured_output` | Executor 结构化 claims、hypotheses、recommended_actions、missing_info |
|
||
| `gatekeeper_result` | 引用真实性校验结果，包括 checked bindings、failed rules、warnings、errors |
|
||
| `composer_output` | Composer 最终表达及解析状态 |
|
||
| `tool_trace_summary` | Verifier 调用时使用的工具调用导航索引，不是唯一证据源 |
|
||
|
||
## 7. 数据写入时序
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
autonumber
|
||
participant API as API
|
||
participant Svc as ChatService/AiOpsService
|
||
participant Session as diagnosis_session
|
||
participant Agent as Agent
|
||
participant Step as agent_step
|
||
participant Tool as tool_invocation
|
||
participant Eval as self_evaluation
|
||
participant Feedback as case_library
|
||
|
||
API->>Svc: request
|
||
Svc->>Session: create/update RUNNING
|
||
Agent->>Step: before/after model
|
||
Agent->>Tool: tool call record
|
||
Svc->>Session: SUCCESS/FAILED + answer
|
||
Svc->>Eval: merge evaluation
|
||
API->>Svc: feedback useful
|
||
Svc->>Feedback: create case
|
||
```
|
||
|
||
## 8. 当前边界和后续
|
||
|
||
当前边界：
|
||
|
||
- `agent_step.session_id` 和 `tool_invocation.session_id` 通过 sessionId 关联，不强制外键。
|
||
- `tool_invocation.step_id` 可为空。
|
||
- Milvus chunk 与 `api_document` 通过 metadata.docId 逻辑关联。
|
||
- `case_library` 与 session 通过 `diagnosis_id=session_id` 关联。
|
||
|
||
后续可增强：
|
||
|
||
1. 增加 run id，支持同 session 多次独立诊断。
|
||
2. 强化 `tool_invocation.step_id` 关联。
|
||
3. 将 Gatekeeper 规则配置化时的规则元数据保存为可审计版本。
|
||
4. 将 `case_library` 的 rootCause/solution 从完整 answer 中结构化抽取。
|