Cloud-Tour-to-Libo/docs/markitdown-evaluation.md

MarkItDown 转换评测方法

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

评测维度

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

准备样本

把测试文件放到：

data/markitdown_eval/input/

建议每类至少 5 份：

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

Manifest 示例

创建 data/markitdown_eval/manifest.json：

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

运行评测

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
• 针对旅行社/城市知识图谱的自定义后处理规则