siemens_ragas/docs/superpowers/specs/2026-06-16-optimization-advisor-design.md

# 优化顾问模块设计 Spec

- 日期：2026-06-16
- 状态：已确认，进入实现。

## 1. 目标

在现有 RAG 评测流程结束后，新增一个**优化顾问模块**（Optimization Advisor），根据本次评测的多项指标分数与低分样本，自动诊断指标偏低的原因并给出针对性的优化建议，输出为中文 Markdown 报告 + 日志摘要。

对应架构设计 §11（优化策略）：将"指标到动作的映射"（§11.2）从文档形式落地为代码自动执行。

---

## 2. 决策摘要

| 决策点 | 选择 |
|---|---|
| 输出形式 | `optimization_advice.md`（文件）+ 控制台/日志摘要（双输出） |
| 生成机制 | 规则引擎定位异常指标 → LLM 结合低分样本二次解读（两层） |
| 触发方式 | YAML 场景文件显式声明 `optimization_advisor: true`，默认关闭 |
| LLM 实例 | 复用 `build_models()` 已创建的 `llm` 实例，不重建 client |
| 包位置 | `rag_eval/advisor/`（独立包，对外暴露 `run_advisor()` 单一入口） |

---

## 3. 架构

### 3.1 执行链路

```
run_scenario()
  → load_scenario()           # 读 YAML，解析 optimization_advisor 字段
  → build_models()            # 已有：创建 llm, embeddings
  → build_metric_pipeline()   # 已有
  → Evaluator.evaluate()      # 已有：打分 → EvaluationResult
  → write_run_artifacts()     # 已有：scores.csv / summary.md / ...
  → run_advisor(              # 新增（3 行）
        result, scenario, llm, artifact_paths
    )
      → rules.diagnose(score_rows)           # 规则引擎：返回 Diagnosis 列表
      → llm_analyzer.analyze(diags, samples) # LLM：生成中文 Markdown 建议
      → writer.write(advice, paths)          # 写文件 + 打日志
```

### 3.2 新增文件

```
rag_eval/advisor/
  __init__.py          ← 暴露 run_advisor()，外部唯一入口
  rules.py             ← 纯函数规则引擎，无 LLM，可单独单测
  llm_analyzer.py      ← 接收 llm 实例 + 诊断结构 → 中文 Markdown
  writer.py            ← 写 optimization_advice.md，打日志摘要
```

### 3.3 修改文件（最小改动）

| 文件 | 改动 |
|---|---|
| `rag_eval/shared/models.py` | `Scenario` 加 `optimization_advisor: bool = False` 字段 |
| `rag_eval/config/schema.py` | `ScenarioModel` 加同名字段 + 透传到 `Scenario` |
| `rag_eval/config/loader.py` | 透传 `optimization_advisor` 到 `Scenario` 构造 |
| `rag_eval/reporting/artifacts.py` | `RunArtifactPaths` 加 `advice_md: Path` 字段 + `build_artifact_paths()` 加赋值 |
| `rag_eval/execution/runner.py` | `run_scenario()` 末尾：`build_models` 返回 llm 传入，条件调用 `run_advisor()` |

### 3.4 输出产物

```
outputs/online/siemens-pdf-question-bank/<run_id>/
  scenario.snapshot.yaml
  scores.csv
  invalid.csv
  summary.md
  metadata.json
  optimization_advice.md    ← 新增（optimization_advisor: true 时生成）
```

---

## 4. 规则引擎（rules.py）

### 4.1 数据结构

```python
@dataclass
class Diagnosis:
    metric: str           # 指标名
    mean_score: float     # 本次均值
    threshold: float      # 警戒阈值
    severity: str         # "warning" | "critical"
    root_causes: list[str]  # 可能原因（来自架构设计 §11.2）
    suggested_actions: list[str]  # 对应可调阶段
    low_samples: list[dict]  # 分数最低的 N 条样本（含 question/answer/ground_truth）
```

### 4.2 七条指标诊断规则

阈值参考 RAG 评测最佳实践，分 warning / critical 两档：

| 指标 | warning | critical | 根因方向 | 对应优化阶段（§11.2） |
|---|---|---|---|---|
| `faithfulness` | < 0.7 | < 0.5 | 生成未严格基于检索片段 / 幻觉 | 生成 prompt grounding、开启校验 |
| `answer_relevancy` | < 0.7 | < 0.5 | 回答偏离问题 / 格式冗余 | 查询改写、生成 prompt 格式 |
| `context_recall` | < 0.7 | < 0.5 | 检索遗漏关键信息 | 多查询、问题分解、Step-back、加大过召回 |
| `context_precision` | < 0.6 | < 0.4 | 检索引入过多噪声 / 排序差 | 后检索重排、压缩、相关性过滤 |
| `noise_sensitivity` | > 0.3 | > 0.5 | 回答被噪声片段干扰（越低越好） | 后检索相关性过滤、重排 |
| `factual_correctness` | < 0.6 | < 0.4 | 回答事实与标准答案偏差大 | 检索与生成综合优化 |
| `semantic_similarity` | < 0.7 | < 0.5 | 回答语义与标准答案差距大 | 生成 prompt、检索质量 |

> 注：`noise_sensitivity` 越低越好（0=完全不受噪声影响），其阈值方向与其余相反。

### 4.3 低分样本选取

每个触发诊断的指标，取该指标分数最低的 **top-3** 样本（排除 NaN）附入 `Diagnosis.low_samples`，字段包含 `sample_id / question / answer / ground_truth / <metric_score>`。

---

## 5. LLM 分析器（llm_analyzer.py）

### 5.1 输入

- `diagnoses: list[Diagnosis]` — 规则引擎输出（仅触发阈值的指标）
- `llm` — 已有 RAGAS LLM 实例（scenario 的 judge_model）
- `scenario_name: str` — 用于报告标题

### 5.2 Prompt 设计

使用**一次 LLM 调用**，把所有触发诊断的指标和低分样本一起发送：

```
你是一个 RAG 系统优化专家，正在分析西门子医疗 CT 文档问答系统的评测结果。
请用中文撰写一份优化建议报告，格式为 Markdown。

## 评测诊断摘要
{for each diagnosis: 指标名、均值、阈值、可能原因、建议动作}

## 低分样本示例
{for each diagnosis: top-3 低分样本的 question / answer / ground_truth}

## 要求
1. 按指标分节（## 指标名），先解释"为什么低"，再给出"具体怎么改"
2. "具体怎么改"要结合低分样本的具体内容，而不只是泛泛建议
3. 最后写一节 ## 优先优化次序，按性价比排序（参考：不增加调用次数的优先）
4. 语言简洁，面向工程师，不要废话
```

### 5.3 输出

LLM 返回的 Markdown 字符串，直接写入 `optimization_advice.md`（在报告头部追加运行元信息）。

### 5.4 失败降级

LLM 调用失败（超时/异常）时：降级为**纯规则报告**（只输出规则引擎的诊断结构，不含 LLM 解读），文件照常写出，错误信息写入报告末尾，不阻断整个评测流程。

---

## 6. 写出层（writer.py）

### 6.1 文件写出

`optimization_advice.md` 结构：

```markdown
# 优化建议报告 — <scenario_name>

- run_id: `<run_id>`
- 生成时间: `<timestamp>`
- judge_model: `<model>`

---

<LLM 生成的 Markdown 正文>
```

### 6.2 日志摘要

`run_advisor()` 完成后向 `logger.info` 打印一条精简摘要（单行，适合 `run_eval.bat` 结束后一眼扫到）：

```
[advisor] 触发诊断 3 项: faithfulness(0.42, critical) context_recall(0.58, warning) noise_sensitivity(0.41, critical)
[advisor] 优化建议已写出: outputs/online/.../optimization_advice.md
```

---

## 7. YAML 配置

场景文件新增一个顶层字段：

```yaml
optimization_advisor: true   # 默认 false；true 时评测结束后自动生成优化建议
```

后续若需精细配置（阈值覆盖、top-N 低分样本数），可扩展为：

```yaml
optimization_advisor:
  enabled: true
  top_low_samples: 3          # 每个指标取几条低分样本（默认 3）
  # thresholds:               # 可选：覆盖默认阈值
  #   faithfulness: 0.65
```

本轮实现仅支持 `optimization_advisor: true/false`，扩展接口预留但不实现。

---

## 8. 测试策略

| 测试 | 文件 | 说明 |
|---|---|---|
| 规则引擎单测 | `tests/test_advisor_rules.py` | 纯函数，无 LLM，覆盖每条规则的 warning/critical 触发、NaN 跳过、low_samples 选取 |
| writer 单测 | `tests/test_advisor_writer.py` | mock Diagnosis 列表，验证 md 文件写出格式和日志输出 |
| 集成（可选） | 现有 `tests/test_online_eval.py` | 验证 `optimization_advisor: true` 场景下 advice_md 存在 |

LLM 分析器不写单测（依赖网络），由集成场景覆盖。

---

## 9. 不覆盖（本轮边界）

- 不支持跨版本对比分析（只分析本次 run）
- 不支持批量场景聚合建议
- 不建设 Web UI 展示
- LLM 分析器 prompt 本轮不做多语言适配（直接中文）
- advisor 阈值本轮硬编码在 `rules.py`，不从 YAML 读取