> ## Documentation Index
> Fetch the complete documentation index at: https://docs.somark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 运行评测

> 安装 DocParsingBench CLI，批量评测 Markdown，查看逐页结果并生成交互榜单。

## 安装和配置

下面以 Python 3.12 为例，在虚拟环境中安装 `dpb`，安装时会一并安装 FastCDM。

```bash theme={null}
git clone https://github.com/SoMarkAI/DocParsingBench.git docparsingbench
cd docparsingbench
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install .
cp config.example.yaml config.yaml
```

## 先评测一页

在仓库根目录创建两份纯文本 Markdown。参考页写着 `120 USD`，预测页把金额识别成了 `100 USD`。这个示例可以直接使用刚复制的配置文件。

```bash theme={null}
printf '%s\n' 'Total: 120 USD' > reference.md
printf '%s\n' 'Total: 100 USD' > prediction.md

dpb eval \
  --gt reference.md \
  --pred prediction.md \
  --config config.yaml \
  --out single-page.result.json
```

终端摘要包含 `Files=1`、`DPB=0.9286` 和 `Text=0.9286`。这页只包含文本，所以总体分与文本分相同。单页结果 `single-page.result.json` 的 `summary` 保存分数，`matches` 保存匹配明细。

## 准备参考标注和模型输出

使用安装时提供的 Hugging Face CLI 下载数据集。`images/` 存放原页图片，`markdowns/` 存放同名的参考 Markdown。

```bash theme={null}
hf download SoMarkAI/DocParsingBench --repo-type dataset \
  --local-dir data/DocParsingBench
```

用待评测的模型解析 `images/` 中的页面，把每页的 Markdown 直接保存到 `predictions/model-a/` 下。例如，`education_chemistry_00001.png` 的预测文件应为 `predictions/model-a/education_chemistry_00001.md`。评测器只会配对两个目录顶层同名的 `.md` 文件。

## 运行评测并检查结果

使用默认的公式指标 CDM 前，请准备 Node.js、Chrome 和兼容版本的 ChromeDriver，并把 `config.yaml` 中的 `chromedriver_path` 改为本机驱动的路径。[ChromeDriver 安装说明](https://github.com/SoMarkAI/FastCDM/blob/main/docs/chromedriver_installation.md)

```bash theme={null}
dpb eval \
  --gt data/DocParsingBench/markdowns \
  --pred predictions/model-a \
  --config config.yaml \
  --out results/model-a.result.json
```

批量运行时，终端会显示 `Files`、`DPB`、`Text`、`Formula`、`Table` 和 `FormulaRenderFailures`。JSON 结果中的 `summary` 存放汇总分，`reports` 存放逐页分数和片段匹配明细。

比较模型时，使用相同的页面清单和评分配置。核对实际计分页数 `Files`、逐页报告和公式渲染失败数，确认各模型的评测覆盖一致。默认配置会跳过参考标注中含 `\smiles{...}` 的页面。

## 用 FastCDM 单独评估公式

在已安装 DocParsingBench 的环境中，可以直接使用下面的 Python 示例。只需要评估公式时，也可以在虚拟环境中运行 `python -m pip install fastcdm`，并使用上面的浏览器和驱动配置。运行前，将示例中的路径换成本机的 ChromeDriver 路径。

```python theme={null}
from fastcdm import FastCDM

evaluator = FastCDM(chromedriver="/path/to/chromedriver")
try:
    f1, recall, precision = evaluator.compute(
        gt="x^{2} + y^{2} = z^{2}",
        pred="x^{2} + y = z^{2}",
    )
    print(f"F1={f1:.4f}, recall={recall:.4f}, precision={precision:.4f}")
finally:
    evaluator.close()
```

召回率表示参考公式中的字符有多少被匹配，精确率表示预测公式中的字符有多少与参考匹配，F1 综合这两项。需要查看字符匹配图时，将 `visualize` 设为 `True`，并接收第四个返回值。[FastCDM 用法](https://github.com/SoMarkAI/FastCDM/blob/main/README-CN.md)

## 查看逐页差异

看到某页分数偏低时，用 `dpb segment-report` 导出该页的参考标注、预测 Markdown、归一化结果和分段对照。将最后一行替换为你要检查的文件名。

```bash theme={null}
dpb segment-report \
  --gt data/DocParsingBench/markdowns \
  --pred predictions/model-a \
  --out results/segment-report.md \
  education_chemistry_00001.md
```

> [!NOTE]
>
> 在仓库版本 `90bf1fb` 中，`dpb visualize` 调用了 Gradio 4.x 不支持的 `css` 启动参数。遇到这类报错时，可以用逐页 JSON 和分段报告查看差异。[可视化启动代码](https://github.com/SoMarkAI/DocParsingBench/blob/90bf1fbccc6d9967a9f9981bd5589eb5a8d9d6cd/docparsingbench/visualize/vis_result.py#L347)

## 生成交互榜单

将每个模型的批量结果保存为 `results/` 下的 `*.result.json`，用以下命令生成 HTML。打开 `results/leaderboard.html`，即可按行业筛选，并按 DPB 或分项分数排序。

```bash theme={null}
dpb leaderboard-html \
  --gt data/DocParsingBench/markdowns \
  --results results \
  --output results/leaderboard.html
```

分段检查、汇总柱状图和高级配置见[项目文档](https://github.com/SoMarkAI/DocParsingBench/blob/main/README_zh.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.