# MarkItDown 转换评测方法

本项目已经接入 Microsoft MarkItDown，但上线判断不能只看“能不能转”。推荐用一组真实业务样本文档做可重复评测。

## 评测维度

1. 转换成功率：不同格式是否稳定返回 Markdown。
2. 信息保真度：关键字段、价格、日期、地点、人名、产品 ID 是否还在。
3. 结构保留度：标题、表格、列表、链接是否保留为 Markdown 结构。
4. 噪声控制：乱码、超长行、残留 HTML、空文本、重复内容是否明显。
5. 下游效果：把转换后的 Markdown 送入知识抽取后，实体、关系、证据覆盖是否提升。

## 准备样本

把测试文件放到：

```bash
data/markitdown_eval/input/
```

建议每类至少 5 份：

- PDF：普通 PDF、扫描 PDF、复杂表格 PDF
- Word：合同、行程单、产品说明
- Excel：价格表、团期表、资源表
- PPT：介绍资料、图文页
- HTML/Markdown/CSV/JSON/XML
- 图片或截图类资料

## Manifest 示例

创建 `data/markitdown_eval/manifest.json`：

```json
{
  "cases": [
    {
      "case_id": "travel_product_docx_001",
      "file": "travel_product.docx",
      "must_terms": ["产品ID", "成人价", "儿童价", "费用包含", "退费政策"],
      "forbidden_terms": ["�"],
      "expected_headings_min": 2,
      "expected_tables_min": 1,
      "expected_lists_min": 3,
      "expected_links_min": 0,
      "min_chars": 800,
      "notes": "旅行社产品说明 Word"
    }
  ]
}
```

## 运行评测

```bash
python3 scripts/evaluate_markitdown_conversion.py \
  --input-dir data/markitdown_eval/input \
  --manifest data/markitdown_eval/manifest.json \
  --output-dir outputs/markitdown_eval \
  --fail-under 0.70
```

输出：

- `outputs/markitdown_eval/converted/*.markitdown.md`
- `outputs/markitdown_eval/markitdown_eval_report.json`
- `outputs/markitdown_eval/markitdown_eval_report.md`

## 判定建议

- 平均分 `>= 0.85`：可作为默认转换方案，但仍抽检复杂文件。
- `0.70 - 0.85`：可用，但要看缺失字段和结构损失，必要时加 OCR 或人工校正。
- `< 0.70`：不建议直接进入自动知识抽取，应启用替代方案。

## 进一步增强

当前接入是 MarkItDown 本地转换。若样本中大量是扫描 PDF、图片文字、复杂表格、音视频，建议再评估：

- MarkItDown OCR plugin
- Azure Document Intelligence
- Azure Content Understanding
- 针对旅行社/城市知识图谱的自定义后处理规则