feat: add ai trace admin console

2026-06-23 00:32:32 +08:00
parent c75f0b646a
commit 81977ead8f
15 changed files with 651 additions and 10 deletions
@@ -0,0 +1,52 @@
+# V2 AI Trace 管理后台闭环记录
+
+日期：2026-06-23
+
+## 本轮目标
+
+让管理员能在 V2 管理区直接查看 AI 调用 Trace，定位每次法律问答或后续 AI 能力调用的模型、Prompt、知识命中、token、费用、错误和耗时。
+
+## 已落地内容
+
+1. AI run 审计字段增强。
+   - `AiRunAudit.prompt_preview`
+   - `ai_run_audits.prompt_preview`
+   - 新增迁移 `20260623_0006_add_ai_run_prompt_preview.py`
+
+2. 法律问答调用写入 Prompt 摘要。
+   - 每次 `/api/v1/legal/qa` 会把渲染后的 Prompt 截取前 4000 字符写入审计。
+   - 保留 provider、model、provider_status、provider_error、token、费用、耗时、检索来源等既有 trace 字段。
+
+3. 契约和 SDK 同步。
+   - OpenAPI `AiRun` 新增 `prompt_preview`。
+   - Python SDK `AiRunAudit` 新增 `prompt_preview`。
+
+4. 前端管理区新增 AI Trace 可视化。
+   - 新增 `/admin/ai-traces`。
+   - 管理侧边栏新增 `AI Trace`。
+   - 管理首页新增 `AI 调用 Trace` 入口。
+   - 页面支持：
+     - 最近调用数、总 token、平均耗时、异常调用数。
+     - 按状态筛选。
+     - 按问题、模型、错误、法条来源搜索。
+     - 展开查看 Prompt、回答、知识命中、token、费用、错误、Trace ID。
+
+5. 前端同源代理。
+   - 新增 `/api/ai-platform/audit/ai-runs`。
+   - 服务端读取：
+     - `AI_PLATFORM_API_BASE_URL`
+     - `NEXT_PUBLIC_AI_PLATFORM_API_BASE_URL`
+     - 默认 `http://localhost:8101`
+
+## 验收重点
+
+- AI Platform 执行一次法律问答后，`GET /api/v1/audit/ai-runs` 返回 `prompt_preview`。
+- 合同 Web 打开 `/admin/ai-traces` 能看到列表、筛选、指标和详情。
+- AI Platform 不可用时，页面显示清晰错误状态，不影响管理区其他页面。
+
+## 建议下一步
+
+进入 AI 质量评测 MVP：
+
+- 把一次回答是否带来源、是否引用足够、是否出现 provider fallback、是否 token/耗时异常形成质量标签。
+- 在 AI Trace 页给每次调用加“质量判定”和“可复盘原因”。