安装和稳定性报告 2025: 修复了 pypdfium2、API 崩溃和 Transformers segfault 问题

作者: KylePoe创建于 2025年12月5日更新于 2025年12月5日

pypdfium2 兼容性（关键） 问题: pypdfium2 的新版本（v4.0+）严格要求文件路径为字符串，但 nougat 传递的是 pathlib.Path 对象。 症状: 尝试加载 PDF 文件时会立即发生 TypeError 或 AttributeError 错误。 解决方案: 在传递给文档加载器之前，将文件路径转换为字符串。

python

# 在 nougat/dataset/rasterize.py 中
# 更改:
doc = pdfium.PdfDocument(filepath)
# 为:
doc = pdfium.PdfDocument(str(filepath))

API 并行渲染崩溃 问题: 运行 nougat_api 时，rasterize_paper 函数尝试使用 multiprocessing 来渲染页面。如果输入为字节或临时文件句柄，或者仅仅是由于 API 服务器内的上下文问题，则会导致失败。 症状: API 返回 500 错误，错误为 ValueError: Can only render in parallel with file path input。 解决方案: 在 rasterize.py 中禁用并行执行路径，并强制使用串行渲染循环。
Transformers 栈溢出 问题: 最近版本的 transformers（可能是 4.38+）引入了更改，导致 nougat 在 CUDA 上的推理生成循环中发生栈溢出。 症状: 处理页面时进程会静默退出或发生栈溢出。 解决方案: 固定 transformers==4.37.2。
环境稳定性为了确保可重现性，我发现必须严格固定以下依赖项：

torch==2.5.1
torchvision==0.20.1
torchaudio==2.5.1
pypdfium2==4.0.0
fastapi==0.123.10
uvicorn==0.38.0 解决方案我创建了一个仓库，该仓库自动创建具有这些特定版本的可用的 Conda 环境，并在安装后应用必要的代码修补。 https://GitHub.com/KylePoe/nougat-setup-script 希望这能帮助其他使用这款优秀工具的人。免责声明：我广泛地使用了 LLM 来生成这些更改。其中可能包含不理想的修复（特别是，我对并行渲染修复有所怀疑）。我之所以分享这些，是因为，正如所指出的那样，我无法让它正常工作，而且我认为其他人可能会觉得有用。

内容来源: facebookresearch/nougat