ai-contract-platform/project-docs/V2-ai-trace-rag-explain-quality-action-closure-2026-06-24.md

AI Trace RAG explain 与质量改进项闭环记录

日期：2026-06-24

背景

按照《AI 合同平台 V2 重构版开发方案》，AI 中台需要做到“回答可追溯、问题可处理、处理后可回看”。上一轮已经把 RAG explain 快照写入 AI Trace，本轮继续把 Trace 详情里的 RAG explain 与质量改进项打通。

本轮目标

• 在 Trace 详情中，对“来源不足、缺少引用、使用 fallback”等质量标签，一键生成质量改进项时自动带入 RAG explain 上下文。
• 改进项中保留低分依据、过滤原因、未命中词、候选统计、入选依据、fallback 错误等信息。
• 管理员打开质量改进项详情页后，可以直接看到问题上下文，不需要再来回翻 Trace。
• 保持简单主线：不新增复杂流程，不扩展后端表结构，只复用已有 description 和 root_cause_hint 字段。

已完成内容

Trace 详情生成改进项增强

文件：

• yuqei-contract-platform/apps/contract-web/src/app/admin/ai-traces/page.tsx

完成点：

• missing_citation、source_limited、source_insufficient、fallback_used 生成改进项时，自动附带 RAG explain 摘要。
• 摘要内容包括：
  • 检索词
  • 检索策略与后端
  • HNSW / search_vector 使用情况
  • vector / keyword / merged / included 候选统计
  • embedding provider / model / dimension
  • 未命中词
  • 入选依据
  • 低分或被过滤候选
  • filter_reason / ranking_reason
  • fallback/provider 错误
• “缺少引用”如果已经有入选依据，会自动归为 tune_prompt，避免误判成知识库缺失。
• “缺少引用/来源不足”仍会尽量关联知识库，便于后续补知识库或检查索引。
• Trace 详情里已关联改进项可直接打开改进项详情页。

改进项详情页可读性增强

文件：

• yuqei-contract-platform/apps/contract-web/src/app/admin/ai-quality-dashboard/[actionId]/quality-action-detail-client.tsx
• yuqei-contract-platform/apps/contract-web/src/app/globals.css

完成点：

• 改进项详情页新增“问题上下文”区块。
• root_cause_hint 作为简短结论展示。
• description 作为等宽文本块展示，保留换行和候选明细。
• 质量看板列表仅展示截断摘要，避免长 RAG 上下文撑乱列表。

验证结果

已通过：

npm run web:typecheck
npm run web:build

结果：

• TypeScript 类型检查通过。
• Next.js 生产构建通过。

当前闭环

现在路径为：

1. AI 调用生成 Trace。
2. Trace 保存 RAG explain 快照。
3. 质量规则识别来源不足、缺少引用、fallback 等标签。
4. 管理员在 Trace 详情一键生成质量改进项。
5. 改进项自动携带 RAG explain 的关键上下文。
6. 管理员在改进项详情页直接处理 Prompt、知识库或模型配置。

这条链路符合 V2 方案中“AI 中台负责模型网关、知识库、RAG、AI 审计、质量评测；合同系统只消费能力”的边界。