yuqei
a3bb78e06b
Security Quality Gate / npm audit, Bandit, pip-audit, detect-secrets (pull_request) Failing after 16m35s
68 lines
3.8 KiB
Markdown
68 lines
3.8 KiB
Markdown
# 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 中的低分、过滤原因、未命中词带入改进项，减少管理员排查成本。
|