PDF Craft Converter

将扫描版书籍 PDF 高质量转换为 Markdown 或 EPUB 格式。纯本地运行，零 API 依赖，UV 管理环境。

能力一览

文件结构

scanned-pdf-to-ebook/
├── SKILL.md                 # 本文件 (使用说明)
├── pyproject.toml           # UV 项目配置 + 依赖声明
├── .python-version          # Python 版本锁定 (3.12)
├── .gitignore
└── scripts/
    ├── check_env.py         # 环境检查 (UV/Poppler/GPU/后端)
    ├── pdf_craft_cli.py     # 核心转换 (单文件)
    └── batch_convert.py     # 批量转换

安装指南

平台支持总览

> macOS Apple Silicon 指的是 M1/M2/M3/M4 系列芯片。三平台命令相同，区别仅在 PyTorch 和个别后端的安装方式上。

第一步: 安装 UV

UV 是 Rust 写的超快 Python 包管理器，替代 pip + venv。

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux (含 ARM)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 通用: 用 pip 装也行
pip install uv

验证: uv --version

安装后重启终端，确保 uv 命令可用。

第二步: 安装 Poppler

Poppler 是 PDF 渲染工具，pdf-craft 和 Marker 后端都需要它。

# --- Windows ---
choco install poppler          # 推荐 (需要先装 Chocolatey)
# 或
scoop install poppler          # Scoop
# 安装后重启终端!

# --- macOS ---
brew install poppler

# --- Linux (Debian / Ubuntu) ---
sudo apt update && sudo apt install -y poppler-utils

# --- Linux (Fedora / RHEL) ---
sudo dnf install -y poppler-utils

# --- Linux (Arch / Manjaro) ---
sudo pacman -S poppler

# --- Linux (openSUSE) ---
sudo zypper install poppler-tools

# --- Linux (Alpine) ---
sudo apk add poppler-utils

验证: pdftoppm -v

> Windows 安装后必须重启终端。如果 pdftoppm 还是找不到，尝试用完整路径，通常是 C:\Program Files\poppler\Library\bin\pdftoppm.exe。

第三步: 安装依赖和 OCR 后端

进入 Skill 目录，安装基础依赖:

cd <SKILL_DIR>
uv sync                # 安装 pypdf, pdf2image, pillow, tqdm 等基础依赖

然后安装至少一个 OCR 后端。三平台命令相同，区别在 PyTorch 的安装上。

PyTorch 安装 (关键区别在这里)

PyTorch 是 pdf-craft 和 Marker 的底层依赖，不同平台和 GPU 需要装不同版本:

# --- 所有平台通用: CPU 版 (最安全, 约 200MB) ---
uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

# --- Windows / Linux: NVIDIA GPU (CUDA 12.1) ---
uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# --- Windows / Linux: NVIDIA GPU (CUDA 12.4) ---
uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124

# --- macOS (Intel 和 Apple Silicon): 不需要额外操作 ---
# macOS 的 PyTorch 默认支持 Metal (MPS) 加速，装 CPU 版即可自动利用 Apple GPU
# 如果之前装了 CUDA 版需要先卸载:
# uv pip uninstall torch torchvision
# uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

> macOS 用户注意: 不要装 CUDA 版 (装了也用不了)，直接装 CPU 版，PyTorch 会自动通过 MPS 利用 Apple Silicon 的 GPU。

安装 OCR 后端

# --- 方案 A: pdf-craft (推荐, 扫描书籍首选, 支持 EPUB) ---
uv pip install pdf-craft              # 依赖 PyTorch, 请确保先装好
# 安装大小: ~3GB (含模型权重)

# --- 方案 B: Marker (速度快, 显存需求低, 跨平台最好) ---
uv pip install marker-pdf
# 安装大小: ~2GB

# --- 方案 C: MinerU (中文最强, 公式表格极准) ---
# 通用 (Windows / macOS Intel / Linux):
uv pip install "magic-pdf[full]"

# macOS Apple Silicon (M1/M2/M3/M4):
uv pip install "mineru[core]"         # full 版的 sgl-kernel 不支持 ARM
# 安装大小: ~5GB

# --- 方案 D: 全装 (一次性搞定) ---
uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
uv pip install pdf-craft marker-pdf
# MinerU 根据平台选:
uv pip install "magic-pdf[full]"      # Windows / Linux / macOS Intel
# uv pip install "mineru[core]"       # macOS Apple Silicon

第四步: 验证环境

uv run python scripts/check_env.py

如果输出显示 "环境就绪!" 就可以开始使用了。

macOS Apple Silicon 专题

Apple Silicon Mac (M1/M2/M3/M4) 使用统一内存架构，没有独立的"显存"，GPU 和 CPU 共享内存。这带来一些特殊的行为:

内存换算: Mac 的 16GB 统一内存 = 约 10-12GB 可用于模型推理 (系统占一部分)。推荐 16GB 或以上内存的 Mac 使用大模型。

GPU 加速: PyTorch 通过 MPS (Metal Performance Shaders) 自动利用 Apple GPU。装好 PyTorch CPU 版后，check_env.py 如果只显示 "CPU only" 但你有 Apple Silicon Mac，这不是问题 -- pdf-craft 和 Marker 内部会检测 MPS 并自动使用。

环境变量: Marker 需要设置 PYTORCH_ENABLE_MPS_FALLBACK=1，Marker 内部会自动设置，无需手动操作。

性能参考: M2 Pro 16GB + pdf-craft large 模型，约 1-2 秒/页；M1 8GB 只能用 base 或 small 模型。

Linux 专题

发行版覆盖: 核心脚本没有 Linux 发行版相关的代码，所有 Python 操作都是跨平台的。只要 Poppler 能装上就行 (见第二步)。

CUDA: Linux 服务器通常有 NVIDIA GPU。确认 CUDA 驱动已安装:
- nvidia-smi 能输出 GPU 信息说明驱动正常
- CUDA Toolkit 版本需 >= 12.1 (匹配 PyTorch 的 cu121)
- 用 nvcc --version 查看具体 CUDA 版本，然后选对应的 PyTorch

无桌面环境: 如果在无 GUI 的 Linux 服务器上运行，PDF 渲染依赖 Poppler 的命令行工具 (不依赖 GUI)，可以正常工作。

环境检查输出说明

运行 uv run python scripts/check_env.py 后:

============================================================
  scanned-pdf-to-ebook 环境检查
============================================================

  [OK]   UV: uv 0.6.x
  [OK]   Python 3.12.x
  [OK]   Poppler: /usr/bin/pdftoppm; /usr/bin/pdftotext
  [WARN] GPU: CPU only                          # 有 GPU 会显示 [OK]

  --- OCR 后端 ---
  [OK]   pdf-craft: v1.0.12                    # DeepSeek OCR 2
         专注扫描书籍, 支持 EPUB 输出
  [--]   marker: 未安装
         Surya OCR, 速度快, 适合批量处理
         安装: uv pip install marker-pdf
  [--]   minera: 未安装
         上海AI Lab, 中文最强, 公式表格极准
         安装: uv pip install "magic-pdf[full]"

============================================================
  可用后端: pdf-craft

  环境就绪!
============================================================

关键点: Python + Poppler + 至少一个 OCR 后端 = 环境就绪。GPU 是加分项，没有也能用。

使用指南

命令格式

所有命令都通过 uv run python 在 Skill 的虚拟环境中执行:

uv run python scripts/pdf_craft_cli.py <命令> [选项] <输入> <输出>
uv run python scripts/batch_convert.py <输入目录> <输出目录> [选项]

第一步: 检测 PDF

转换前先看看 PDF 是什么类型:

uv run python scripts/pdf_craft_cli.py detect "D:/books/mybook.pdf"

输出:

  PDF: D:/books/mybook.pdf
  文本层: False           # True = 有文本层, False = 纯扫描件
  每页字符: 3             # 每页平均字符数, <50 是扫描件
  总页数: 256
  说明: 纯扫描件, 需要 OCR

这一步是可选的，转换脚本内部会自动判断。但先看看有助于选择合适的参数。

第二步: 单文件转换

转 Markdown

uv run python scripts/pdf_craft_cli.py markdown "input.pdf" "output.md"

图片会自动提取到 images/ 子目录，Markdown 中通过相对路径引用。

转 EPUB

uv run python scripts/pdf_craft_cli.py epub "input.pdf" "output.epub" \
  --title "书名" --author "作者"

EPUB 输出仅 pdf-craft 后端 支持。会自动生成目录结构，表格渲染为 HTML，公式渲染为 MathML。

选择 OCR 后端

# 用 Marker (速度快, 显存低)
uv run python scripts/pdf_craft_cli.py -b marker markdown "input.pdf" "output.md"

# 用 MinerU (中文最强, 公式表格极准)
uv run python scripts/pdf_craft_cli.py -b minera markdown "input.pdf" "output.md"

# 自动选择 (按优先级: pdf-craft -> marker -> minera)
uv run python scripts/pdf_craft_cli.py -b auto markdown "input.pdf" "output.md"

第三步: 批量转换

# 批量转 Markdown (只处理目录下一层的 PDF)
uv run python scripts/batch_convert.py "D:/books/" "D:/books-md/" -f markdown

# 递归处理子目录
uv run python scripts/batch_convert.py "D:/books/" "D:/books-md/" -f markdown --recursive

# 批量转 EPUB (指定作者)
uv run python scripts/batch_convert.py "D:/books/" "D:/books-epub/" -f epub --author "合集作者"

# 用 MinerU 后端批量处理
uv run python scripts/batch_convert.py "D:/books/" "D:/books-md/" -b minera --recursive

# 强制覆盖已有文件 (默认跳过)
uv run python scripts/batch_convert.py "D:/books/" "D:/books-md/" --force

批量处理的输出文件名 = 原始 PDF 文件名 + 对应扩展名。如果输出文件已存在会自动跳过，中断后重新运行可以续跑。

参数速查

单文件转换 (pdf_craft_cli.py)

通用参数

markdown 子命令

epub 子命令

detect 子命令

download-models 子命令

首次转换时模型会自动下载。如果希望提前下载 (比如离线环境), 用这个命令:

uv run python scripts/pdf_craft_cli.py download-models --cache-dir ./models

批量转换 (batch_convert.py)

后端选择指南

如何选择:

• 扫描书籍做电子书 -> pdf-craft (唯一支持 EPUB, 章节识别好)
• 中文论文/技术文档 -> minera (公式、表格、代码块识别最强)
• 大量文档批量处理 -> marker (速度快, 显存占用低)
• 不确定 -> -b auto (自动检测已安装的后端, 按 pdf-craft > marker > minera 优先)

OCR 模型大小 (pdf-craft 后端专属)

自动选择逻辑: 有 GPU -> gundam, 无 GPU -> base

手动指定: --ocr-size large

性能参考

常见问题

Q: uv sync 报错?

确保 UV 已安装且终端已重启。访问 https://docs.astral.sh/uv/getting-started/installation/ 查看安装方式。

Q: Poppler 找不到?

Windows 和 macOS 用户安装 Poppler 后需要重启终端才能生效。验证: pdftoppm -v。Windows 用户如果重启终端后仍找不到，检查 Poppler 的 bin 目录是否在 PATH 中 (通常是 C:\Program Files\poppler\Library\bin)。

Q: pdf-craft 安装失败?

pdf-craft 依赖 PyTorch, 需要先装:

# CPU 版 (所有平台通用, 约 200MB)
uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

# 然后再装 pdf-craft
uv pip install pdf-craft

Q: macOS 上 MinerU 安装失败, 报 sgl-kernel 缺少预编译包?

Apple Silicon Mac 上 magic-pdf[full] 的 sgl-kernel 依赖没有 ARM 预编译版本。改用核心版本:

uv pip install "mineru[core]"

核心版本包含 PDF 解析的所有核心功能，不影响使用。完整版 (full) 的额外功能依赖 sglang 推理框架，目前不支持 ARM。

Q: macOS 上 GPU 加速没生效?

确认你装的是 PyTorch CPU 版 (不是 CUDA 版)。macOS 不支持 CUDA，PyTorch CPU 版会自动通过 MPS 利用 Apple GPU。如果 check_env.py 显示 "CPU only" 但你有 Apple Silicon Mac，这不影响 -- pdf-craft 和 Marker 内部会独立检测 MPS。

Q: Mac M1 (8GB) 内存不够用?

8GB 统一内存的 Mac 系统占一部分后可用的有限。建议:
1. 用小模型: --ocr-size tiny 或 --ocr-size small
2. 降低 DPI: --dpi 200
3. 转换前关掉浏览器和其他占内存的应用
4. 或使用 Marker 后端 (显存需求最低)

Q: Linux 服务器上 (无 GUI) 能用吗?

可以。本工具的 PDF 渲染依赖 Poppler 命令行工具 (pdftoppm, pdftotext)，不需要图形界面。只要有 Poppler 和 Python 环境就行。

Q: 转换后文字质量差?

1. 提高 DPI: --dpi 400 (默认 300)
2. 用更大 OCR 模型: --ocr-size large 或 --ocr-size gundam
3. 换后端试试: MinerU 对中文论文通常更好

Q: 内存不足 (OOM)?

1. 用更小模型: --ocr-size tiny 或 --ocr-size small
2. 降低 DPI: --dpi 200
3. 关闭其他占用 GPU 的程序
4. Mac 用户: 关掉浏览器等占内存的应用 (统一内存被多个进程共享)

Q: 批量转换中途中断了?

直接重新运行同样的命令。已存在的输出文件会自动跳过，从断点续跑。

Q: EPUB 转换报 "backend not supported"?

EPUB 输出目前只有 pdf-craft 后端支持。确保安装了 pdf-craft 且没有用 -b marker 或 -b minera。

Q: 想对比不同后端效果?

同一个 PDF 用不同后端分别转换, 然后对比输出质量:

uv run python scripts/pdf_craft_cli.py -b pdf-craft markdown "test.pdf" "test_pdfcraft.md"
uv run python scripts/pdf_craft_cli.py -b marker markdown "test.pdf" "test_marker.md"
uv run python scripts/pdf_craft_cli.py -b minera markdown "test.pdf" "test_minera.md"

Q: 可以处理非扫描的 PDF 吗?

可以。脚本会自动检测 PDF 文本层。如果文本层质量好 (每页 > 200 字符), 会直接提取文本, 不走 OCR, 速度快很多。

Q: 支持哪些语言?

主要针对中文和英文优化。pdf-craft 后端对日文、韩文也有不错的效果。其他语言可能需要额外测试。

完整使用示例

示例 1: 一本中文扫描书转 EPUB

# 检测 PDF
uv run python scripts/pdf_craft_cli.py detect "D:/books/三体.pdf"
# macOS: detect "/Users/you/Downloads/三体.pdf"
# Linux: detect "/home/you/books/三体.pdf"

# 转 EPUB
uv run python scripts/pdf_craft_cli.py epub "D:/books/三体.pdf" "D:/output/三体.epub" \
  --title "三体" --author "刘慈欣"

# 输出: D:/output/三体.epub (可直接导入到微信读书、Apple Books 等阅读器)

示例 2: 多篇中文论文批量转 Markdown

uv run python scripts/batch_convert.py \
  "D:/papers/" "D:/papers-md/" \
  -b minera -f markdown --recursive

# macOS:
# uv run python scripts/batch_convert.py \
#   "/Users/you/papers/" "/Users/you/papers-md/" \
#   -b minera -f markdown --recursive

示例 3: 快速处理一堆英文 PDF

uv run python scripts/batch_convert.py \
  "D:/docs/" "D:/docs-md/" \
  -b marker -f markdown --recursive --force

示例 4: GPU 模式高质量转换

# NVIDIA GPU
uv run python scripts/pdf_craft_cli.py markdown "input.pdf" "output.md" \
  --ocr-size gundam --dpi 400

# Mac Apple Silicon (MPS 自动生效, 无需额外配置)
uv run python scripts/pdf_craft_cli.py markdown "input.pdf" "output.md" \
  --ocr-size large --dpi 400

示例 5: 只检测不转换

uv run python scripts/pdf_craft_cli.py detect "D:/books/big-book.pdf"
# 输出: 文本层信息 + 页数 + 是否需要 OCR
# 根据结果决定用什么参数