# 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 配置”。
- 在看板中追踪改进任务完成后，对应异常率是否下降。