241 lines
8.4 KiB
Markdown
241 lines
8.4 KiB
Markdown
# 指标权重 & 文档片段权重功能设计
|
||
|
||
**日期**: 2026-06-18
|
||
**状态**: 已批准，待实现
|
||
**范围**: 在「新建评估」运行评估时，支持为 RAGAS 指标和文档配置权重，计算加权综合得分并在报告中展示。
|
||
|
||
---
|
||
|
||
## 1. 目标
|
||
|
||
1. **指标权重（Metric Weights）**：允许为每个 RAGAS 指标配置浮点权重（如 faithfulness: 0.35），计算每道题的加权综合得分 `weighted_score`。
|
||
2. **文档权重（Doc Weights）**：允许为特定 PDF 文档名称配置权重（如 `"322_双源CT.pdf": 2.0`），该文档的题目在汇总指标均值时按权重放大贡献。
|
||
3. **前端覆盖**：在「新建评估」页面选中场景后，展示可编辑的权重面板，运行前可临时覆盖 YAML 中的权重。
|
||
4. **完全向后兼容**：两个字段均为可选，省略时退化为等权行为，现有场景 YAML 无需修改。
|
||
|
||
---
|
||
|
||
## 2. 数据模型
|
||
|
||
### 2.1 场景 YAML（新增可选字段）
|
||
|
||
```yaml
|
||
# 可选。缺省时所有指标权重 = 1.0
|
||
metric_weights:
|
||
faithfulness: 0.35
|
||
context_recall: 0.25
|
||
context_precision: 0.20
|
||
answer_relevancy: 0.20
|
||
|
||
# 可选。缺省时所有文档权重 = 1.0
|
||
doc_weights:
|
||
"322_双源CT成像技术.pdf": 2.0
|
||
"323_单源CT对比.pdf": 1.5
|
||
```
|
||
|
||
### 2.2 Pydantic Schema（`rag_eval/config/schema.py`）
|
||
|
||
`ScenarioModel` 新增：
|
||
```python
|
||
metric_weights: dict[str, float] = Field(default_factory=dict)
|
||
doc_weights: dict[str, float] = Field(default_factory=dict)
|
||
```
|
||
|
||
`ConfigDict(extra="ignore")` 不变，新字段不影响既有 YAML 的加载。
|
||
|
||
### 2.3 内部 Scenario dataclass（`rag_eval/shared/models.py`）
|
||
|
||
`Scenario` 新增：
|
||
```python
|
||
metric_weights: dict[str, float] = field(default_factory=dict)
|
||
doc_weights: dict[str, float] = field(default_factory=dict)
|
||
```
|
||
|
||
随 `scenario.snapshot()` 序列化，供 `run_reader` / 报告层读取。
|
||
|
||
---
|
||
|
||
## 3. 后端：权重计算逻辑
|
||
|
||
### 3.1 新模块 `rag_eval/metrics/weights.py`
|
||
|
||
纯函数模块，无外部依赖，独立可测：
|
||
|
||
```python
|
||
def resolve_weight(weights: dict[str, float], key: str, default: float = 1.0) -> float:
|
||
"""返回 key 对应的权重，缺失时返回 default。"""
|
||
|
||
def compute_weighted_score(
|
||
scores: dict[str, float | None],
|
||
metric_weights: dict[str, float],
|
||
) -> float | None:
|
||
"""
|
||
给定各指标得分和权重，返回加权综合得分。
|
||
- 忽略 NaN / None 值
|
||
- metric_weights 为空时退化为等权均值
|
||
- 全部 NaN 时返回 None
|
||
公式: Σ(w_i * s_i) / Σ(w_i)，只对非 NaN 项求和
|
||
"""
|
||
|
||
def weighted_metric_means(
|
||
score_rows: list[dict],
|
||
metrics: list[str],
|
||
doc_weights: dict[str, float],
|
||
) -> dict[str, float | None]:
|
||
"""
|
||
对每个指标计算文档加权均值。
|
||
- sample_weight = doc_weights.get(row["doc_name"], 1.0)
|
||
- 公式: Σ(sample_weight_j * score_m_j) / Σ(sample_weight_j)
|
||
- doc_weights 为空时退化为普通算术均值
|
||
"""
|
||
```
|
||
|
||
### 3.2 评估器（`rag_eval/execution/evaluator.py`）
|
||
|
||
`_merge_score()` 新增两列：
|
||
```python
|
||
record["weighted_score"] = compute_weighted_score(
|
||
score.metrics, self.scenario.metric_weights
|
||
)
|
||
record["sample_weight"] = self.scenario.doc_weights.get(
|
||
sample.metadata.get("doc_name", ""), 1.0
|
||
)
|
||
```
|
||
|
||
`scores.csv` 新增 `weighted_score`、`sample_weight` 两列。
|
||
|
||
### 3.3 报告摘要（`rag_eval/reporting/summary.py`）
|
||
|
||
`build_summary_markdown()` 改用 `weighted_metric_means()` 计算各指标均值；
|
||
新增 `weighted_score` 整体均值行：
|
||
|
||
```
|
||
## Metric Means（加权）
|
||
- faithfulness: 0.8123 (w=0.35)
|
||
- context_recall: 0.7654 (w=0.25)
|
||
- context_precision: 0.7200 (w=0.20)
|
||
- answer_relevancy: 0.7400 (w=0.20)
|
||
- **weighted_score: 0.7789**
|
||
```
|
||
|
||
---
|
||
|
||
## 4. yaml_patcher 扩展（`webapp/services/yaml_patcher.py`）
|
||
|
||
`apply_profiles_to_scenario()` 扩展签名，新增可选参数：
|
||
|
||
```python
|
||
def apply_profiles_to_scenario(
|
||
scenario_path: str,
|
||
judge_profile: LLMProfile | None,
|
||
answer_profile: LLMProfile | None,
|
||
dataset_profile: LLMProfile | None,
|
||
metric_weights: dict[str, float] | None = None, # 新增
|
||
doc_weights: dict[str, float] | None = None, # 新增
|
||
_resolve_absolute: bool = False,
|
||
) -> list[str]:
|
||
```
|
||
|
||
- `metric_weights` 非 None 时写入 `data["metric_weights"]`，追加 `"metric_weights"` 到 patched 列表
|
||
- `doc_weights` 非 None 时写入 `data["doc_weights"]`，追加 `"doc_weights"` 到 patched 列表
|
||
|
||
---
|
||
|
||
## 5. Webapp 模型与 API 扩展
|
||
|
||
### 5.1 `webapp/models.py`
|
||
|
||
`ProfileApplyRequest` 新增：
|
||
```python
|
||
metric_weights: dict[str, float] | None = None
|
||
doc_weights: dict[str, float] | None = None
|
||
```
|
||
|
||
`ProfileApplyResponse` 不变（`patched_fields` 已包含新字段名）。
|
||
|
||
### 5.2 `webapp/api/llm_profiles.py` — `apply_profiles()`
|
||
|
||
透传 `metric_weights` / `doc_weights` 给 `apply_profiles_to_scenario()`。
|
||
|
||
---
|
||
|
||
## 6. 前端：权重配置面板
|
||
|
||
### 6.1 HTML（`index.html`）
|
||
|
||
在 `#llm-assignment-panel` 下方新增 `#weight-config-panel`（选中场景后显示）：
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ 权重配置 （可选，留空使用场景原始配置） │
|
||
├─────────────────────────────────────────────┤
|
||
│ 指标权重 │
|
||
│ faithfulness [____1.0____] │
|
||
│ context_recall [____1.0____] │
|
||
│ ...（根据选中场景的 metrics 动态生成） │
|
||
│ │
|
||
│ 文档权重（doc_weights） │
|
||
│ [doc名称_______________] [权重__] [＋] [✕] │
|
||
│ [doc名称_______________] [权重__] [＋] [✕] │
|
||
│ ＋ 添加文档权重规则 │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 6.2 `runner.js`
|
||
|
||
- `renderScenarioItem()` 选中后调用 `Runner._renderWeightPanel(sc)` 动态生成指标行
|
||
- `_applyProfilesIfNeeded()` 同时读取权重输入，追加到 `apply` 请求 body
|
||
- `Runner._collectWeights()` 收集 metric_weights / doc_weights，全部为 1.0 时不发送（跳过）
|
||
|
||
### 6.3 CSS（`app.css`）
|
||
|
||
新增 `.weight-config-panel`、`.weight-row`、`.weight-input` 样式，与现有 `.llm-role-row` 风格一致。
|
||
|
||
---
|
||
|
||
## 7. 报告展示（`webapp/services/report_builder.py`）
|
||
|
||
- `RunSummary.metric_means` 改用 `weighted_metric_means()` 计算（需从 `scenario.snapshot.yaml` 读取 `doc_weights` / `metric_weights`）
|
||
- `RunSummary` 新增 `weighted_score_mean: float | None` 字段
|
||
- 前端 `report.js` 的指标卡片区新增「综合加权得分」卡片，使用 `good/warn/bad` 配色
|
||
|
||
---
|
||
|
||
## 8. 测试计划
|
||
|
||
| 测试文件 | 覆盖内容 |
|
||
|----------|---------|
|
||
| `tests/test_weights.py` | `compute_weighted_score` / `weighted_metric_means` 纯函数，含 NaN 边界、空权重、全 NaN |
|
||
| `tests/test_dataset_build.py` | 无改动（隔离良好） |
|
||
| `tests/test_offline_eval.py` | `_merge_score` 新增 weighted_score / sample_weight 列断言 |
|
||
| `tests/webapp/test_llm_profiles_api.py` | `apply_profiles` 带 metric_weights / doc_weights 的 patching 测试 |
|
||
|
||
---
|
||
|
||
## 9. 改动文件清单
|
||
|
||
| 文件 | 改动类型 |
|
||
|------|---------|
|
||
| `rag_eval/config/schema.py` | 新增字段 |
|
||
| `rag_eval/shared/models.py` | 新增字段 |
|
||
| `rag_eval/config/loader.py` | 透传新字段到 Scenario |
|
||
| `rag_eval/metrics/weights.py` | **新建** |
|
||
| `rag_eval/execution/evaluator.py` | `_merge_score` 新增两列 |
|
||
| `rag_eval/reporting/summary.py` | 改用加权均值 |
|
||
| `webapp/services/yaml_patcher.py` | 新增 metric_weights / doc_weights 参数 |
|
||
| `webapp/models.py` | ProfileApplyRequest 新增字段；RunSummary 新增 weighted_score_mean |
|
||
| `webapp/api/llm_profiles.py` | 透传新参数 |
|
||
| `webapp/services/report_builder.py` | 加权均值计算 |
|
||
| `webapp/static/index.html` | 新增权重配置面板 |
|
||
| `webapp/static/js/runner.js` | 权重面板逻辑 |
|
||
| `webapp/static/css/app.css` | 新增权重面板样式 |
|
||
| `tests/test_weights.py` | **新建** |
|
||
|
||
---
|
||
|
||
## 10. 向后兼容保证
|
||
|
||
- `metric_weights: {}` + `doc_weights: {}` → 所有权重 = 1.0，行为与当前完全一致
|
||
- 现有场景 YAML 不含这两个字段 → Pydantic `default_factory=dict` 填充空字典
|
||
- `scores.csv` 新增两列不影响现有报告读取（`run_reader` 只读已知列）
|