206 lines
6.6 KiB
Markdown
206 lines
6.6 KiB
Markdown
# 数据模型总览
|
||
|
||
**更新日期**：2026-07-20
|
||
**状态**：当前可运行架构
|
||
|
||
## 1. 定位
|
||
|
||
本文从架构角度说明当前 MVP 的核心数据模型。详细字段以 Flyway migration、实体类和 `mvp/tables/` 为准。
|
||
|
||
核心数据分三组：
|
||
|
||
- 会话与诊断 Trace：`chat_session`、`diagnosis_run`、`agent_step`、`tool_invocation`
|
||
- 知识库：`api_document`、`knowledge_domain`、Milvus/Zilliz metadata
|
||
- 反馈沉淀：`case_library`
|
||
|
||
当前运行时只使用 `chat_session + diagnosis_run`；旧 `diagnosis_session` 表不属于当前版本契约。
|
||
|
||
## 2. 总体关系
|
||
|
||
```mermaid
|
||
erDiagram
|
||
chat_session ||--o{ diagnosis_run : owns
|
||
diagnosis_run ||--o{ agent_step : has
|
||
diagnosis_run ||--o{ tool_invocation : has
|
||
diagnosis_run ||--o| case_library : creates_when_useful
|
||
api_document ||--o{ milvus_chunk : indexed_as
|
||
knowledge_domain ||--o{ api_document : groups
|
||
|
||
chat_session {
|
||
bigint id
|
||
varchar session_id
|
||
varchar status
|
||
int message_pair_count
|
||
datetime last_active_at
|
||
datetime expires_at
|
||
}
|
||
|
||
diagnosis_run {
|
||
bigint id
|
||
varchar run_id
|
||
varchar session_id
|
||
text query
|
||
varchar status
|
||
varchar agent_flow
|
||
longtext answer
|
||
json self_evaluation
|
||
json orchestration_trace
|
||
varchar feedback
|
||
}
|
||
|
||
agent_step {
|
||
bigint id
|
||
varchar session_id
|
||
varchar run_id
|
||
int step_index
|
||
varchar agent_name
|
||
text model_input
|
||
text model_output
|
||
boolean has_tool_call
|
||
}
|
||
|
||
tool_invocation {
|
||
bigint id
|
||
varchar session_id
|
||
varchar run_id
|
||
bigint step_id
|
||
varchar tool_name
|
||
json input_params
|
||
text output_preview
|
||
json retrieval_details
|
||
}
|
||
|
||
case_library {
|
||
bigint id
|
||
varchar case_id
|
||
varchar diagnosis_id
|
||
varchar source_type
|
||
varchar fault_category
|
||
text root_cause
|
||
text solution
|
||
}
|
||
```
|
||
|
||
说明：Milvus/Zilliz collection 不是 MySQL 表，图中的 `milvus_chunk` 是逻辑模型。
|
||
|
||
## 3. 会话与运行模型
|
||
|
||
### chat_session
|
||
|
||
`chat_session` 是会话目录表，保存 `sessionId` 的元数据：
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `session_id` | 外部会话 ID，用于多轮上下文和 run 列表 |
|
||
| `status` | 会话目录状态 |
|
||
| `message_pair_count` | Redis 对话轮次数快照 |
|
||
| `last_active_at` | 最近活跃时间 |
|
||
| `expires_at` | 可为空的目录 TTL 元数据 |
|
||
|
||
它不保存完整对话历史，正文消息仍由 Redis `SessionContext.messageHistory` 管理。
|
||
|
||
### diagnosis_run
|
||
|
||
`diagnosis_run` 是一次可回放诊断执行的主记录：
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `run_id` | 运行 ID，格式为 `run-` + UUID |
|
||
| `session_id` | 所属 `chat_session.session_id` |
|
||
| `query` | 本次 Chat 问题或 AIOps 告警摘要 |
|
||
| `status` | 本次执行状态 |
|
||
| `agent_flow` | `CHAT` / `AI_OPS` |
|
||
| `answer` | 本次运行最终答复或告警报告 |
|
||
| `self_evaluation` | 本次运行的 rule/verifier/aiops 自评估容器 |
|
||
| `orchestration_trace` | nullable JSON；复杂 Chat 的 StateGraph 路由摘要，非 StateGraph Run 可为空 |
|
||
| `feedback` | 本次运行的用户反馈 |
|
||
|
||
同一个 `sessionId` 可以有多个 `runId`。Trace、反馈、评测和案例沉淀都应优先使用 `runId`，避免多轮同 session 下的数据混合。
|
||
|
||
## 4. Trace 明细模型
|
||
|
||
### agent_step
|
||
|
||
`agent_step` 记录模型调用步骤。新写入同时保留 `session_id` 和 `run_id`，其中 `run_id` 是回放边界。Trace 页面和评测应先按 `run_id` 隔离取数，展示顺序以 Trace API 返回顺序为准。
|
||
|
||
### tool_invocation
|
||
|
||
`tool_invocation` 记录显式工具调用事实。`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..."
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
`$.no_evidence` 只表示“本次工具查询未检索到匹配证据”，不能被解释为“问题不存在”或“根因已排除”。
|
||
|
||
## 5. Run 级审计分层
|
||
|
||
一次 Run 的可审计信息分为三层，不能互相替代：
|
||
|
||
| 层次 | 存储 | 语义 |
|
||
|---|---|---|
|
||
| 执行明细 | `agent_step`、`tool_invocation` | 模型步骤、工具输入输出、检索细节和证据事实 |
|
||
| 质量评估 | `diagnosis_run.self_evaluation` | rule/verifier/aiops 判断、Gatekeeper 审计、Prompt 版本和允许输出材料 |
|
||
| 编排摘要 | `diagnosis_run.orchestration_trace` | StateGraph transitions、final node、termination reason、degraded、evidence retry count |
|
||
|
||
`orchestration_trace` 只通过 exact Run 的 `run.orchestrationTrace` 暴露，Trace 响应不再包含兼容 `session` 投影。Run 状态仍只表达执行生命周期：安全 Fallback 是 `SUCCESS + degraded=true`，只有无法生成安全响应或未处理失败才是 `FAILED`。
|
||
|
||
## 6. 反馈沉淀模型
|
||
|
||
`useful` 反馈会触发 `CaseLibraryService.createFromRun`。
|
||
|
||
当前自动映射：
|
||
|
||
| 字段 | 来源 |
|
||
|---|---|
|
||
| `case_id` | UUID |
|
||
| `diagnosis_id` | `diagnosis_run.run_id` |
|
||
| `source_type` | `AUTO` |
|
||
| `fault_category` | 当前默认 `GENERAL` |
|
||
| `title` | run query 前 100 字符 |
|
||
| `root_cause` | run answer |
|
||
| `solution` | run answer |
|
||
| `created_by` | `system` |
|
||
|
||
## 7. self_evaluation 结构
|
||
|
||
`diagnosis_run.self_evaluation` 是运行级 JSON 容器：
|
||
|
||
```json
|
||
{
|
||
"rule_evaluation": {},
|
||
"verifier_evaluation": {},
|
||
"aiops_rule_evaluation": {}
|
||
}
|
||
```
|
||
|
||
Chat 通常写入 `rule_evaluation` 和 `verifier_evaluation`；AIOps 写入 `aiops_rule_evaluation`。
|
||
|
||
`orchestration_trace` 不放入该 JSON，避免把答案质量和 Graph 路由混成同一审计维度。
|
||
|
||
## 8. 当前边界和后续
|
||
|
||
当前边界：
|
||
|
||
- `chat_session` 只存会话元数据，不存完整正文历史。
|
||
- `diagnosis_run` 存一次运行的长期审计状态。
|
||
- `agent_step.run_id` 和 `tool_invocation.run_id` 是 Trace、Verifier、Eval 的运行边界。
|
||
- `diagnosis_run.orchestration_trace` 是 nullable Run-owned Graph 摘要；非 StateGraph Run 可以为空。
|
||
- 当前实现主要使用逻辑关联，不依赖数据库外键。
|
||
- `case_library.diagnosis_id` 是过渡字段，新值按 `run_id` 解释，旧值可能按 `session_id` 解释。
|
||
- 当前 Java 运行时不存在 `diagnosis_session` entity/repository 或 fallback。
|
||
|
||
后续可增强：
|
||
|
||
1. 强化 `tool_invocation.step_id` 关联。
|
||
2. 将 Gatekeeper 规则配置化时的规则元数据保存为可审计版本。
|
||
3. 将 `case_library` 的 rootCause/solution 从完整 answer 中结构化抽取。
|