144 lines
3.2 KiB
Markdown
144 lines
3.2 KiB
Markdown
# Audit 模块需求文档
|
|
|
|
## 1. 模块定位
|
|
|
|
Audit 模块负责记录和展示 Agent 执行过程，是项目体现企业级能力的重要模块。
|
|
|
|
复试演示时，审计日志用于证明系统不是黑盒问答，而是可以追踪输入、检索、工具调用、模型输出和执行耗时。
|
|
|
|
## 2. 模块目标
|
|
|
|
- 记录每次 Agent 对话。
|
|
- 记录 RAG 检索片段。
|
|
- 记录工具调用详情。
|
|
- 记录模型输出和结构化结果。
|
|
- 提供审计日志列表和详情页。
|
|
- 支持按场景查看日志。
|
|
|
|
## 3. 职责边界
|
|
|
|
### 3.1 负责
|
|
|
|
- 审计日志数据模型。
|
|
- 日志写入服务。
|
|
- 日志列表页面。
|
|
- 日志详情页面。
|
|
- 工具调用记录展示。
|
|
- RAG 引用记录展示。
|
|
|
|
### 3.2 不负责
|
|
|
|
- 不执行 Agent。
|
|
- 不执行工具调用。
|
|
- 不执行 RAG 检索。
|
|
- 不参与模型生成。
|
|
- 不做复杂权限控制。
|
|
|
|
## 4. 数据模型需求
|
|
|
|
建议模型：`AgentAuditLog`
|
|
|
|
字段：
|
|
|
|
| 字段 | 类型 | 说明 |
|
|
|---|---|---|
|
|
| `id` | int | 主键 |
|
|
| `scenario_id` | string | 场景 ID |
|
|
| `scenario_name` | string | 场景名称 |
|
|
| `user_input` | text | 用户输入 |
|
|
| `retrieved_chunks` | JSON | 检索片段 |
|
|
| `tool_calls` | JSON | 工具调用记录 |
|
|
| `structured_output` | JSON | 结构化输出 |
|
|
| `final_answer` | text | 最终回答 |
|
|
| `raw_output` | text | 模型原始输出 |
|
|
| `model_name` | string | 模型名称 |
|
|
| `latency_ms` | int | 执行耗时 |
|
|
| `status` | string | `success` / `failed` |
|
|
| `error_message` | text | 错误信息 |
|
|
| `created_at` | datetime | 创建时间 |
|
|
|
|
## 5. 日志写入需求
|
|
|
|
Audit 模块需要提供服务函数：
|
|
|
|
```text
|
|
create_audit_log(
|
|
scenario_id,
|
|
scenario_name,
|
|
user_input,
|
|
agent_result
|
|
) -> AgentAuditLog
|
|
```
|
|
|
|
写入规则：
|
|
|
|
- Agent 成功时，记录完整结果。
|
|
- Agent 失败时，也要记录用户输入、场景和错误信息。
|
|
- RAG 片段和工具调用使用 JSON 保存。
|
|
- 不记录 API Key 等敏感配置。
|
|
|
|
## 6. 页面需求
|
|
|
|
### 6.1 审计日志列表页
|
|
|
|
路径：`/audit/`
|
|
|
|
展示字段：
|
|
|
|
- 日志 ID。
|
|
- 场景名称。
|
|
- 用户输入摘要。
|
|
- 状态。
|
|
- 模型名称。
|
|
- 执行耗时。
|
|
- 创建时间。
|
|
- 详情入口。
|
|
|
|
### 6.2 审计日志详情页
|
|
|
|
路径：`/audit/<log_id>/`
|
|
|
|
展示内容：
|
|
|
|
- 用户输入。
|
|
- 最终回答。
|
|
- 结构化输出。
|
|
- RAG 检索片段。
|
|
- 工具调用记录。
|
|
- 模型名称。
|
|
- 执行耗时。
|
|
- 错误信息。
|
|
|
|
## 7. 检索片段展示需求
|
|
|
|
每个引用片段建议包含：
|
|
|
|
| 字段 | 说明 |
|
|
|---|---|
|
|
| `source` | 来源文件名 |
|
|
| `chunk_id` | 片段 ID |
|
|
| `content` | 片段内容 |
|
|
| `score` | 相似度分数 |
|
|
|
|
## 8. 工具调用展示需求
|
|
|
|
每次工具调用建议包含：
|
|
|
|
| 字段 | 说明 |
|
|
|---|---|
|
|
| `tool_name` | 工具名称 |
|
|
| `arguments` | 调用参数 |
|
|
| `result` | 工具结果 |
|
|
| `success` | 是否成功 |
|
|
| `error` | 错误信息 |
|
|
|
|
## 9. 验收标准
|
|
|
|
- 每次对话成功后都会生成审计日志。
|
|
- Agent 执行失败时也会生成失败日志。
|
|
- 审计列表可以查看所有日志。
|
|
- 审计详情可以查看用户输入、检索片段、工具调用和最终输出。
|
|
- 日志中不保存 API Key。
|
|
- 可以根据日志解释一次 Agent 输出的依据。
|
|
|