122 lines
2.7 KiB
Markdown
122 lines
2.7 KiB
Markdown
# 审计模块详细设计
|
||
|
||
## 1. 模块目标
|
||
|
||
Audit 模块记录 Agent 执行过程，使演示者能够解释一次输出的来源、工具调用和模型结果。它是系统从“普通问答页面”变成“可追踪业务 Agent”的关键。
|
||
|
||
## 2. 职责边界
|
||
|
||
负责：
|
||
|
||
- `AgentAuditLog` 模型。
|
||
- 审计写入服务。
|
||
- 审计列表页。
|
||
- 审计详情页。
|
||
- 敏感信息过滤。
|
||
|
||
不负责：
|
||
|
||
- 不执行 Agent。
|
||
- 不执行 RAG。
|
||
- 不执行工具。
|
||
- 不调用模型。
|
||
|
||
## 3. 数据模型设计
|
||
|
||
模型：`AgentAuditLog`
|
||
|
||
字段见 `docs/设计文档/3.数据库设计.md`。
|
||
|
||
JSON 字段默认值必须使用函数，例如 `default=list`、`default=dict`，避免多实例共享同一对象。
|
||
|
||
## 4. 日志写入流程
|
||
|
||
服务函数：
|
||
|
||
```python
|
||
def create_audit_log(
|
||
scenario_id: str,
|
||
scenario_name: str,
|
||
user_input: str,
|
||
agent_result: AgentResult,
|
||
) -> AgentAuditLog:
|
||
"""将 AgentResult 映射为 AgentAuditLog，并在保存前做敏感信息脱敏。"""
|
||
```
|
||
|
||
写入映射：
|
||
|
||
- `agent_result.references` -> `retrieved_chunks`
|
||
- `agent_result.tool_calls` -> `tool_calls`
|
||
- `agent_result.structured_output` -> `structured_output`
|
||
- `agent_result.answer` -> `final_answer`
|
||
- `agent_result.raw_output` -> `raw_output`
|
||
- `agent_result.model_name` -> `model_name`
|
||
- `agent_result.latency_ms` -> `latency_ms`
|
||
- `agent_result.status` -> `status`
|
||
- `agent_result.error` -> `error_message`
|
||
|
||
## 5. 日志列表页设计
|
||
|
||
路径：`/audit/`
|
||
|
||
查询：
|
||
|
||
- 默认按创建时间倒序。
|
||
- V1 可不做分页，若日志较多再加 Django Paginator。
|
||
|
||
展示：
|
||
|
||
- ID。
|
||
- 场景名称。
|
||
- 用户输入前 80 字。
|
||
- 状态。
|
||
- 模型名。
|
||
- 耗时。
|
||
- 创建时间。
|
||
- 详情链接。
|
||
|
||
## 6. 日志详情页设计
|
||
|
||
路径：`/audit/<log_id>/`
|
||
|
||
展示：
|
||
|
||
- 基础信息。
|
||
- 用户输入。
|
||
- 最终回答。
|
||
- 结构化输出。
|
||
- RAG 检索片段。
|
||
- 工具调用。
|
||
- 原始输出。
|
||
- 错误信息。
|
||
|
||
JSON 可用格式化后的 `<pre>` 展示。
|
||
|
||
## 7. 敏感信息处理
|
||
|
||
不得保存：
|
||
|
||
- `LLM_API_KEY`
|
||
- 完整环境变量 dump
|
||
- 用户机器上的敏感绝对路径
|
||
- Docker secret 或 token
|
||
|
||
如错误信息来自异常对象，应在保存前做简单脱敏，至少替换 API Key 值。
|
||
|
||
## 8. 异常处理
|
||
|
||
| 异常 | 处理 |
|
||
|---|---|
|
||
| AgentResult 字段缺失 | 使用默认空值 |
|
||
| JSON 不可序列化 | 转为字符串或空对象 |
|
||
| 日志不存在 | 返回 404 |
|
||
| 写入失败 | 抛给 Chat，由 Chat 展示审计失败提示 |
|
||
|
||
## 9. 验收标准
|
||
|
||
- 每次对话成功后有审计日志。
|
||
- Agent 失败也有失败日志。
|
||
- 列表页可查看日志摘要。
|
||
- 详情页可查看输入、输出、引用和工具调用。
|
||
- 日志不包含 API Key。
|