ai-contract-platform/project-docs/V2-ai-quality-root-cause-attribution-2026-06-23.md

V2 AI 质量问题归因闭环记录

日期：2026-06-23

本轮目标

在 AI 质量运营看板基础上，继续把异常按模型、Prompt 模板、知识库和标签类型聚合，帮助管理员找出最常见的质量失败来源。

已落地内容

1. 后端质量看板增加归因聚合。

   • 返回字段：attribution
   • 维度：
     • by_model
     • by_prompt_template
     • by_knowledge_base
     • by_label_code

2. 每个归因项包含：

   • total_runs：该来源涉及的总调用数。
   • affected_runs：其中带 warning/error 质量标签的调用数。
   • warning_labels / error_labels
   • pending_labels
   • fallback_runs
   • average_quality_score
   • top_label_codes
   • root_cause_hint

3. 归因提示。

   • 模型维度：提示检查 Provider 配置、模型延迟、fallback。
   • Prompt 维度：提示检查 token、引用约束、模板版本。
   • 知识库维度：提示检查文档覆盖、索引质量、来源定位。
   • 标签维度：针对 source_limited、fallback_used、token_high、latency_high 等给出处理方向。

4. 契约和 SDK 同步。

   • OpenAPI 新增 AiQualityAttribution 和 AiQualityAttributionItem。
   • Python SDK 新增对应模型并导出。
   • get_quality_dashboard() 可直接解析归因结果。

5. 前端看板增强。

   • /admin/ai-quality-dashboard 新增四个归因区块：
     • 模型归因
     • Prompt 归因
     • 知识库归因
     • 标签归因
   • 每个区块展示 Top 来源、异常占比、待处理数、常见标签和建议。

验收重点

• 访问 /admin/ai-quality-dashboard 能看到四组归因区块。
• 当存在 warning/error 标签时，归因区块展示 affected runs、pending labels 和 top label codes。
• 后端 GET /api/v1/audit/quality-dashboard 返回 attribution。
• SDK get_quality_dashboard() 能解析 dashboard.attribution.by_model 和 dashboard.attribution.by_label_code。

下一步建议

进入 AI 质量改进动作闭环：

• 给每个归因项增加“创建改进任务”入口。
• 将问题归因转成待办，例如“补知识库”“调整 Prompt”“切换模型”“修复 Provider 配置”。
• 在看板中追踪改进任务完成后，对应异常率是否下降。