ai-contract-platform/project-docs/archive/implementation-history/V2-ai-trace-rag-explain-snapshot-2026-06-24.md

V2 AI Trace RAG Explain 快照闭环记录

日期：2026-06-24

目标

把 RAG explain 摘要接入 AI Trace 详情页，让每次法律问答、合同审查都能回看“为什么引用这些依据”，继续遵循《AI 合同平台 V2 重构版开发方案》里的“AI 中台负责检索、RAG、法条引用、AI 审计；合同系统只消费能力”的边界。

本轮完成

1. AI 运行审计新增 RAG explain 快照持久化字段。

   • 新增迁移：20260624_0017_add_ai_run_rag_explain.py
   • ai_run_audits 增加 rag_explain_json
   • AiRunAudit 增加 rag_explain

2. 法律问答和合同审查执行后自动保存 explain 摘要。

   • 保存检索词、策略、后端、HNSW/search_vector 使用情况、候选数、入选数、命中 chunk、分数和排序原因
   • explain 生成失败时不阻断主回答，只保留为空，避免审计增强影响用户主流程

3. AI Trace 管理后台增加“RAG 解释”区块。

   • 在 Trace 详情展示检索后端、向量后端、关键词后端、候选数、入选数、Embedding 信息
   • 展示 Top 入选依据、keyword/vector/hybrid 分数、命中词、排序原因
   • Trace 列表搜索纳入 explain 关键词、后端和排序说明

4. OpenAPI 契约同步。

   • AiRun.rag_explain 指向 KnowledgeSearchExplain
   • KnowledgeSearchExplain 补齐 vector_backend、keyword_backend、used_hnsw、used_search_vector 和候选数
   • KnowledgeSearchExplainItem 补齐 candidate_source、ranking_reason

5. Smoke 过程中补齐合同状态口径。

   • 远端 worker 暴露历史数据存在 returned 状态，但合同主状态只接受 rejected
   • 新增 contract-api 迁移 20260624_0010_normalize_returned_contract_status.py
   • 读取层把 returned 兼容归一为 rejected，避免旧数据导致合同详情和审查 worker 500

6. 部署 smoke 判定补强。

   • deploy-v2-smoke-docker.ps1 不再只看 review_worker --run-once 命令退出码
   • worker 返回 failed > 0 时直接判定 smoke 失败
   • smoke 前清理遗留 queued/running 审查任务，降低历史测试数据对本轮验证的干扰

验证

• python -m pytest yuqei-ai-platform\services\ai-platform-api\tests -q：通过，41 passed
• python -m pytest yuqei-contract-platform\services\contract-api\tests -q：通过，25 passed
• python -m compileall：通过
• npm run web:typecheck：通过
• npm run web:build：通过
• V2 smoke 部署：project-docs/qa-artifacts/v2-smoke-docker-deploy/2026-06-24T22-45-36 通过
• 远端迁移版本：AI Platform 20260624_0017，Contract API 20260624_0010
• 远端法律问答 Trace 验证：最新 AI Run 返回 rag_explain，retrieval_backend=postgres-pgvector，vector_backend=pgvector-hnsw，keyword_backend=search_vector，并返回 ranking_reason
• 远端合同审查 worker 验证：创建 Smoke Review Contract，审查任务 review-4a875acd8e77 状态为 succeeded，回写 ai_audit_run_id=run-fa1bc2e1b4df，风险项 2 条
• 远端合同审查 Trace 验证：run-fa1bc2e1b4df 的 rag_explain 存在，included_count=3，记录 HNSW/search_vector 和排序原因

当前效果

管理员打开 AI Trace 详情时，不再只能看到最终回答和引用来源，还能看到：

• 本次检索是 keyword、vector 还是 hybrid
• 是否使用 pgvector HNSW
• 是否使用 search_vector
• 向量候选、关键词候选、合并候选数量
• 每条依据为什么被排到前面

这让法律问答和合同审查具备可追溯依据链，后续可以继续把 explain 信息用于质量评测、Prompt 调优和知识库补全。

下一步建议

继续把 Trace 详情里的 RAG explain 与质量改进项打通：当出现“来源不足 / 缺少引用 / fallback”标签时，一键把 explain 中的低分、过滤原因、未命中词带入改进项，减少管理员排查成本。