# OmniDocBench AMD Windows — 交接文档

> **目标读者：** 接手的新 AI agent session
> **状态：** 全链路搭建完成，四项指标均达标，Overall 偏低需排查
> **日期：** 2026-07-07

## 一、已完成的全部工作

### 1.1 环境搭建（Step 0-4）

所有脚本按 `AGENTS.md` 顺序执行完毕：

| 步骤 | 内容 | 状态 |
|---|---|---|
| Step 0a | `detect-mirrors.ps1` → `mirrors.env` | ✅ |
| Step 0b | WSL Ubuntu2204 就绪 | ✅ |
| Step 1 | OmniDocBench 代码 clone + 1651 页数据集 + .venv (Python 3.11) | ✅ |
| Step 2 | CDM 环境 (TeX Live 2026 + IM7 + gs + CJK) | ✅ |
| Step 3a | llama.cpp HIP (b9884) + GGUF 模型下载 + llama-server 启动 | ✅ |
| Step 3b | PP-DocLayoutV3 ONNX 版面模型 | ✅ |
| Step 3c | paddleocr_vl_rocm 安装 + adapter 推理 | ✅ |
| Step 4a | Edit_dist + TEDS 评分 (Windows) | ✅ |
| Step 4b | CDM 评分 (WSL) | ✅ |
| Step 4c | verify.ps1 通过 | ✅ |

### 1.2 Benchmark 模块（eval-infra/04-benchmark/）

12/13 任务完成，已推送到 GitHub：
- `monitor.py` — 后台资源采集器（1 Hz，GPU/RAM）
- `report.py` — Markdown 能力报告生成器（含 ASCII 图表、溯源链、稳定性章）
- `run.ps1` — 编排器
- `verify.ps1` — 五重检查验证网关
- 14 个 pytest 全部通过

Task 13（参考基准数据）待环境修复后执行。

### 1.3 修复的 6 个坑

| # | 问题 | 修复位置 | 提交 |
|---|---|---|---|
| 1 | CDM F1=0：TL2026 scheme-medium 缺 standalone/upgreek | `02-cdm-environment/setup.sh` Step 2b | `c94cf67` |
| 2 | CDM 找不到 TL2026 bin（PREFERRED 只列 2025） | `02-cdm-environment/setup.sh` Step 8 | `c94cf67` |
| 3 | 版面模型 URL 死链 (AlexTransformer → PaddlePaddle) | `detect-mirrors.ps1` + `setup.ps1` | `df172ac` |
| 4 | ONNX 布局 CPU 推理 → 自动检测 DirectML | `PaddleOCR-VL-ROCm` 仓库 | `bd0b20f` |
| 5 | `.sh` CRLF 行尾 → WSL 脚本崩溃 | `.gitattributes` | `9fe67a2` |
| 6 | modelscope 不在 PATH → 改用 venv Python | `01-vlm-server/setup.ps1`, `02-layout-model/setup.ps1` | `936bbb4` |

## 二、最终评分结果

### 2.1 与论文对比

| 指标 | 方向 | 我们的跑分 | 论文官方 | 差距 | 门槛 | 达标 |
|---|---|---|---|---|---|---|
| Overall | ↑ | **94.63** | 96.33 | **-1.70** | — | — |
| Text Edit-dist | ↓ | **0.035** | 0.033 | +0.002 | < 0.10 | ✅ |
| Formula CDM | ↑ | **0.944** | 0.975 | -0.031 | > 0.85 | ✅ |
| Table TEDS | ↑ | **0.930** | 0.948 | -0.018 | > 0.85 | ✅ |
| Reading Order | ↓ | **0.130** | 0.127 | +0.003 | < 0.20 | ✅ |

### 2.2 Overall 公式

```
Overall = (文本准确率 + CDM准确率 + TEDS准确率) / 3

其中:
  文本准确率 = (1 − Text Edit-dist) × 100
  CDM准确率  = Formula CDM × 100
  TEDS准确率 = Table TEDS × 100
```

- **验证：** (96.7 + 97.49 + 94.76) / 3 = 96.32 ≈ 96.33 ✅
- **我们的：** (96.5 + 94.4 + 93.0) / 3 = 94.63

## 三、精度差距分析（待排查）

### 3.1 差距分解

| 因子 | 贡献 | 说明 |
|---|---|---|
| Text Edit | -0.2 pt | 0.035 vs 0.033，文本提取本身接近官方 |
| Formula CDM | **-3.05 pt** | 0.944 vs 0.975，最大差距来源（占 Overall 差距 60%） |
| Table TEDS | **-1.76 pt** | 0.930 vs 0.948（占 Overall 差距 35%） |
| Reading Order | -0.3 pt | 0.130 vs 0.127，差距最小 |

**结论：Overall 偏低的主要原因是 CDM 和 TEDS 差距叠加。**

### 3.2 已知假设（按可能性排序）

**假设 A：llama.cpp 版本差异（最可能）**
- 我们用了 b9884（用户手动下载），原计划是 b9637
- 不同 llama.cpp 版本可能有不同的推理行为
- 测试：用 b9637 重新跑 adapter，对比评分

**假设 B：GGUF 量化差异**
- 我们用的是从 ModelScope 下载的 GGUF（Q4_K_M 量化？）
- 官方 PaddleOCR-VL-1.6 用的是 BF16 未量化模型
- 量化会导致精度损失，尤其对公式和表格影响大
- 测试：检查 GGUF 量化级别，尝试更高精度的量化

**假设 C：VLM 推理参数差异**
- 当前参数：`--temp 0 --top-k 1 --seed 1 --flash-attn on`
- 官方可能使用不同的采样策略
- 测试：调整 top-k、temperature 等参数

**假设 D：layout 模型在 CPU 上运行**
- 当前运行的 adapter 启动于 DirectML 修复**之前**
- layout 检测在 CPU 上，可能影响版面分割精度
- 影响：layout 不准 → table/formula 定位偏差 → TEDS/CDM 降低
- 测试：修复后重新跑 adapter

**假设 E：`\mathcolor` 渲染覆写（CDM 专项）**
- CDM 代码中 `\DeclareDocumentCommand{\mathcolor}` 覆写了 xcolor 的 mathcolor
- 这个覆写可能改变公式渲染颜色，影响 CDM 颜色匹配算法
- 已确认 CDM F1=1.0（相同公式测试通过），但不同公式可能有细微差异
- 测试：对比官方 Paddle 原生路径的 CDM 输出

### 3.3 排查优先级

1. **先用 DirectML 修复后的 adapter 重新跑**（假设 D）— 零成本，只是重跑
2. **换 b9637 llama.cpp 版本**（假设 A）— 需要下载对应版本
3. **检查 GGUF 量化级别**（假设 B）— 一行命令
4. **调整 VLM 参数**（假设 C）— 可能需要参数扫描

## 四、环境速查

### 4.1 关键路径

```
Repo: C:\Users\rocm\Desktop\omnidocbench-amd-windows
WSL distro: Ubuntu2204
WSL repo path: /mnt/c/Users/rocm/Desktop/omnidocbench-amd-windows

llama-server: adapters/paddleocr-vl-1.6/models/llama.cpp/llama-server.exe
GGUF: adapters/paddleocr-vl-1.6/models/PaddleOCR-VL-1.6-GGUF/
  PaddleOCR-VL-1.6-GGUF.gguf (935 MB)
  PaddleOCR-VL-1.6-GGUF-mmproj.gguf (879 MB)
Layout ONNX: adapters/paddleocr-vl-1.6/models/PP-DocLayoutV3-onnx/inference.onnx
paddleocr_vl_rocm: ../PaddleOCR-VL-ROCm/ (editable install)

venv: .venv/Scripts/python.exe (Python 3.11.15)
Predictions: predictions/paddleocrvl_rocm/ (1649 .md files)
Scores: \\wsl$\Ubuntu2204\root\OmniDocBench\result\
  paddleocrvl_rocm_cdm_quick_match_metric_result.json
```

### 4.2 服务状态

llama-server 需要在 127.0.0.1:8111 运行。启动命令：

```powershell
Start-Process -FilePath 'adapters\paddleocr-vl-1.6\models\llama.cpp\llama-server.exe' `
  -ArgumentList '--host','127.0.0.1','--port','8111',`
    '-m','<full-path-to>\PaddleOCR-VL-1.6-GGUF.gguf',`
    '--mmproj','<full-path-to>\PaddleOCR-VL-1.6-GGUF-mmproj.gguf',`
    '--temp','0','-c','32768','-ngl','999','--flash-attn','on',`
    '--seed','1','--top-k','1','--top-p','1.0',`
    '-np','8','--threads','8','--no-cache-prompt' `
  -WindowStyle Hidden `
  -RedirectStandardError 'adapters\paddleocr-vl-1.6\logs\llama-server.err.log' `
  -RedirectStandardOutput 'adapters\paddleocr-vl-1.6\logs\llama-server.out.log'
```

### 4.3 适配器重跑

```powershell
# 清旧预测
rm -Force predictions\paddleocrvl_rocm\_run_stats.json
rm -Force predictions\paddleocrvl_rocm\_errors.log

# 重跑（server 必须在运行）
.venv\Scripts\python.exe adapters\paddleocr-vl-1.6\run_adapter.py `
    --img-dir eval-infra\01-omnidocbench\data\images `
    --out-dir predictions\paddleocrvl_rocm
```

### 4.4 重新评分

```powershell
# Edit_dist + TEDS
powershell -ExecutionPolicy Bypass -File eval-infra\03-scoring\score.ps1

# CDM (WSL)
wsl -d Ubuntu2204 -- rm -rf /root/OmniDocBench/result/*
cp -r predictions/paddleocrvl_rocm predictions/paddleocrvl_rocm_cdm
wsl -d Ubuntu2204 -- /bin/bash /mnt/c/Users/rocm/Desktop/omnidocbench-amd-windows/eval-infra/03-scoring/score-cdm.sh v16-cdm.yaml

# 验证
powershell -ExecutionPolicy Bypass -File eval-infra\03-scoring\verify.ps1 -SaveName paddleocrvl_rocm_cdm_quick_match
```

## 五、WSL 注意事项

- **路径转换：** 在 Git Bash 中调用 WSL 需要 `MSYS_NO_PATHCONV=1` 前缀
- **PATH 污染：** WSL 内用 `export PATH=/usr/local/texlive/2026/bin/x86_64-linux:/usr/local/bin:/usr/bin:/bin` 避免 Windows PATH 泄漏
- **CRLF：** `.sh` 文件必须 LF 行尾（已在 `.gitattributes` 中配置）

## 六、GitHub

- **仓库：** https://github.com/AIwork4me/omnidocbench-amd-windows
- **当前 HEAD：** `d27f350` (docs: compute and add Overall score)
- **PaddleOCR-VL-ROCm 仓库：** `../PaddleOCR-VL-ROCm/` (commit `7a1fcc8`，含 DirectML 修复)
