这是 Nougat 的官方仓库。Nougat 是一款能够理解 LaTeX 数学公式和表格的学术 PDF 文档解析器。

项目主页：https://facebookresearch.github.io/nougat/

安装

通过 pip 安装：

pip install nougat-ocr

通过仓库安装：

pip install git+https://github.com/facebookresearch/nougat

注意（Windows 用户）：如需使用 GPU，请先安装正确的 PyTorch 版本。请参考 此处说明

若需通过 API 调用模型或生成数据集，还需安装额外依赖项。 可通过以下命令安装：

pip install "nougat-ocr[api]" 或 pip install "nougat-ocr[dataset]"

对 PDF 进行预测

命令行界面 (CLI)

对单个 PDF 文件进行预测：

$ nougat path/to/file.pdf -o output_directory

也可传入目录路径，或包含每行一个 PDF 路径的文件：

$ nougat path/to/directory -o output_directory

用法: nougat [-h] [--batchsize BATCHSIZE] [--checkpoint CHECKPOINT] [--model MODEL] [--out OUT]
              [--recompute] [--markdown] [--no-skipping] pdf [pdf ...]

位置参数:
  pdf                   待处理的 PDF 文件。

选项:
  -h, --help            显示帮助信息并退出
  --batchsize BATCHSIZE, -b BATCHSIZE
                        使用的批处理大小。
  --checkpoint CHECKPOINT, -c CHECKPOINT
                        检查点目录路径。
  --model MODEL_TAG, -m MODEL_TAG
                        使用的模型标签。
  --out OUT, -o OUT     输出目录。
  --recompute           重新计算已处理过的 PDF，丢弃之前的预测结果。
  --full-precision      使用 float32 而非 bfloat16。在某些配置下可加速 CPU 转换。
  --no-markdown         不添加为兼容 markdown 的后处理步骤。
  --markdown            添加为兼容 markdown 的后处理步骤（默认）。
  --no-skipping         不应用失败检测启发式方法。
  --pages PAGES, -p PAGES
                        指定页码范围，如 '1-4,7' 表示第 1 至 4 页及第 7 页。仅适用于单个 PDF。

默认模型标签为 0.1.0-small。如需使用基础模型，请使用 0.1.0-base：

$ nougat path/to/file.pdf -o output_directory -m 0.1.0-base

输出目录中每个 PDF 将保存为 .mmd 文件（轻量级标记语言），基本兼容 Mathpix Markdown（我们利用了其中的 LaTeX 表格功能）。

注意：在某些设备上，失败检测启发式方法可能无法正常工作。如果遇到大量 [MISSING_PAGE] 响应，请尝试使用 --no-skipping 参数运行。相关问题：#11，#67

API

安装额外依赖后，可通过 app.py 启动 API。执行：

$ nougat_api

向 http://127.0.0.1:8503/predict/ 发送 POST 请求即可获取 PDF 文件的预测结果。请求支持 start 和 stop 参数，用于限定计算的页码范围（含边界）。

响应内容为文档的 markdown 文本字符串。

curl -X 'POST' \
  'http://127.0.0.1:8503/predict/' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@<PDFFILE.pdf>;type=application/pdf'

如需将转换限制在第 1 至 5 页，请在请求 URL 中加入 start/stop 参数：http://127.0.0.1:8503/predict/?start=1&stop=5

数据集

生成数据集

生成数据集需要：

1. 包含 PDF 文件的目录
2. 包含 .html 文件的目录（由 LaTeXML 处理 .tex 文件生成），且目录结构与 PDF 目录一致
3. pdffigures2 的二进制文件，并设置环境变量 export PDFFIGURES_PATH="/path/to/binary.jar"

接着运行：

python -m nougat.dataset.split_htmls_to_pages --html path/html/root --pdfs path/pdf/root --out path/paired/output --figure path/pdffigures/outputs

其他参数包括：

参数	描述
--recompute	重新计算所有分割
--markdown MARKDOWN	Markdown 输出目录
--workers WORKERS	使用的进程数
--dpi DPI	页面保存时的分辨率
--timeout TIMEOUT	每篇论文的最大处理时间（秒）
--tesseract	对每页进行 Tesseract OCR 预测

最后，创建一个包含所有图像路径、markdown 文本和元信息的 jsonl 文件：

python -m nougat.dataset.create_index --dir path/paired/output --out index.jsonl

对于每个 jsonl 文件，还需生成 seek map 以加快数据加载速度：

python -m nougat.dataset.gen_seek file.jsonl

最终目录结构示例如下：

root/
├── images
├── train.jsonl
├── train.seek.map
├── test.jsonl
├── test.seek.map
├── validation.jsonl
└── validation.seek.map

注意：path/paired/output（此处为 images）中的 .mmd 和 .json 文件不再需要。 这在上传至 S3 存储桶时非常有用，可减少一半文件数量。

训练

要训练或微调 Nougat 模型，请运行：

python train.py --config config/train_nougat.yaml

评估

运行：

python test.py --checkpoint path/to/checkpoint --dataset path/to/test.jsonl --save_path path/to/results.json

要获取不同文本模态的结果，请运行：

python -m nougat.metrics path/to/results.json

常见问题（FAQ）

• 为什么我只得到 [MISSING_PAGE]？

  Nougat 是在 arXiv 和 PMC 上的科学论文数据集上训练的。你正在处理的文档是否与此类似？ 文档使用的是什么语言？Nougat 对英文论文效果最佳，其他基于拉丁字母的语言可能也能工作。中文、俄文、日文等将无法正常工作。 如果满足上述条件，仍出现此问题，可能是由于在 CPU 或较旧 GPU 上运行时失败检测出现了误报（#11）。目前可尝试传入 --no-skipping 参数。

• 我可以从哪里下载模型检查点（model checkpoint）？

  模型已上传至 GitHub 的发布（release）页面。你也可以在首次运行程序时自动下载。通过传入 --model 0.1.0-{base,small} 来选择你偏好的模型版本。

引用（Citation）

@misc{blecher2023nougat,
      title={Nougat: Neural Optical Understanding for Academic Documents}, 
      author={Lukas Blecher and Guillem Cucurull and Thomas Scialom and Robert Stojnic},
      year={2023},
      eprint={2308.13418},
      archivePrefix={arXiv},
      primaryClass={cs.LG}
}

致谢（Acknowledgments）

本代码库基于 Donut 项目构建。

许可证（License）

Nougat 代码库采用 MIT 许可证。

Nougat 模型权重采用 CC-BY-NC 许可证。

# Nougat 快速上手指南

## 环境准备

- **Python 版本**：3.9 或更高版本
- **操作系统**：支持 Linux、macOS 和 Windows
- **GPU 支持（可选）**：
  - 若需使用 GPU 加速，请先安装对应版本的 PyTorch（推荐使用官方命令安装）：
    ```bash
    pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
    ```
  - 国内用户可考虑使用清华源加速：
    ```bash
    pip3 install torch torchvision torchaudio -i https://pypi.tuna.tsinghua.edu.cn/simple
    ```

## 安装步骤

### 基础安装（推荐）

```bash
pip install nougat-ocr

从 GitHub 源码安装（获取最新版）

pip install git+https://github.com/facebookresearch/nougat

扩展功能安装（按需选择）

• 如需启动 API 服务：

  pip install "nougat-ocr[api]"
  

• 如需生成训练数据集：

  pip install "nougat-ocr[dataset]"
  

基本使用

1. 命令行解析 PDF

将单个 PDF 转换为 .mmd 格式（兼容 Mathpix Markdown）：

nougat path/to/file.pdf -o output_directory

批量处理整个目录中的 PDF：

nougat path/to/directory -o output_directory

默认使用小型模型 0.1.0-small，如需更高精度可指定基础模型：

nougat path/to/file.pdf -o output_directory -m 0.1.0-base

2. 启动 API 服务（需安装 nougat-ocr[api]）

启动本地服务：

nougat_api

通过 curl 请求预测结果（默认监听 http://127.0.0.1:8503/predict/）：

curl -X 'POST' \
  'http://127.0.0.1:8503/predict/' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@<PDFFILE.pdf>;type=application/pdf'

指定页码范围（例如第1到第5页）：

curl -X 'POST' 'http://127.0.0.1:8503/predict/?start=1&stop=5' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@<PDFFILE.pdf>;type=application/pdf'