PDF Craft Converter

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

能力一览

| 功能 | 说明 |

|------|------|

| PDF -> Markdown | 保留标题层级、图片、表格、公式 |

| PDF -> EPUB | 自动生成目录，表格渲染为 HTML，公式渲染为 MathML |

| 多 OCR 后端 | pdf-craft (DeepSeek OCR 2) / Marker (Surya) / MinerU |

| 文本层检测 | 自动判断 PDF 是否需要 OCR，有文本层的直接提取 |

| GPU/CPU 自适应 | 有 GPU 用大模型，无 GPU 自动降级 |

| 批量处理 | 目录级批量转换，自动跳过已处理文件 |

文件结构

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     # 批量转换

安装指南

平台支持总览

|------|---------|---------------|----------------------|----------------|-------------|

| pdf-craft | OK | OK | OK (MPS 加速) | OK | CPU only |

| Marker | OK | OK | OK (MPS 加速) | OK | CPU only |

| MinerU | OK | OK | 需装 mineru[core] | OK | 未测试 |

> 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)

通用参数

| 参数 | 默认值 | 说明 |

|------|--------|------|

| -b, --backend | pdf-craft | OCR 后端: pdf-craft / marker / minera / auto |

markdown 子命令

| 参数 | 默认值 | 说明 |

|------|--------|------|

| input | (必填) | 输入 PDF 路径 |

| output | (必填) | 输出 .md 文件路径 |

| --assets-dir | 与 md 同目录的 images/ | 图片资源保存目录 |

| --ocr-size | 自动 (GPU=gundam, CPU=base) | OCR 模型大小, 仅 pdf-craft 后端有效 |

| --dpi | 300 | PDF 渲染分辨率, 越高越清晰但越慢 |

| --cover | 否 | 是否包含封面页 |

| --no-footnotes | 否 | 是否排除脚注 |

epub 子命令

| 参数 | 默认值 | 说明 |

|------|--------|------|

| input | (必填) | 输入 PDF 路径 |

| output | (必填) | 输出 .epub 文件路径 |

| --title | PDF 文件名 | 书名 |

| --author | Unknown | 作者 |

| --language | zh | 语言代码 (影响排版) |

| --ocr-size | 自动 | 同上 |

| --dpi | 300 | 同上 |

detect 子命令

| 参数 | 默认值 | 说明 |

|------|--------|------|

| input | (必填) | 要检测的 PDF 文件路径 |

download-models 子命令

| 参数 | 默认值 | 说明 |

|------|--------|------|

| --backend | pdf-craft | 要预下载的后端 |

| --cache-dir | models | 模型缓存目录 |

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

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

批量转换 (batch_convert.py)

| 参数 | 默认值 | 说明 |

|------|--------|------|

| input_dir | (必填) | PDF 所在目录 |

| output_dir | (必填) | 输出目录 |

| -f, --format | markdown | 输出格式: markdown / epub |

| -b, --backend | pdf-craft | OCR 后端 |

| --recursive | 否 | 递归搜索子目录 |

| --force | 否 | 覆盖已有输出文件 |

| --ocr-size | 自动 | OCR 模型大小 |

| --dpi | 300 | 渲染分辨率 |

| --author | 无 | EPUB 作者 (批量转 EPUB 时使用) |

后端选择指南

|------|-----------|--------|--------|

| 中文质量 | 优秀 | 良好 | 极佳 |

| 英文质量 | 好 | 优秀 | 优秀 |

| 速度 | 中 | 快 | 中偏慢 |

| CPU 模式 | 支持 (慢) | 支持 | 不推荐 |

| 安装大小 | ~3GB | ~2GB | ~5GB |

如何选择:

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

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

| 模型 | 速度 | 质量 | 显存需求 | 适用场景 |

|------|------|------|----------|----------|

| tiny | 最快 | 一般 | ~2GB | 快速预览, 文字清晰的 PDF |

| small | 快 | 较好 | ~4GB | 日常使用 |

| base | 中 | 好 | ~6GB | CPU 模式首选 |

| large | 慢 | 很好 | ~10GB | GPU 模式, 高质量需求 |

| gundam | 最慢 | 最好 | ~14GB | GPU 模式, 出版级质量 |

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

手动指定: --ocr-size large

性能参考

| 配置 | 速度 (约) | 300 页书籍 | 适用 |

|------|-----------|------------|------|

| CPU + base | 3-5 秒/页 | 15-25 分钟 | 无 GPU 时 |

| NVIDIA GPU (8GB) + large | 1-2 秒/页 | 5-10 分钟 | 中端显卡 |

| NVIDIA GPU (16GB+) + gundam | 0.5-1 秒/页 | 2-5 分钟 | 高端显卡 |

| Mac M2 Pro (16GB) + large | 1-2 秒/页 | 5-10 分钟 | Apple Silicon |

| Mac M1 (8GB) + base | 3-5 秒/页 | 15-25 分钟 | 入门 Mac |

常见问题

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 系统占一部分后可用的有限。建议:

用小模型: --ocr-size tiny 或 --ocr-size small
降低 DPI: --dpi 200
转换前关掉浏览器和其他占内存的应用
或使用 Marker 后端 (显存需求最低)

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

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

Q: 转换后文字质量差?

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

Q: 内存不足 (OOM)?

用更小模型: --ocr-size tiny 或 --ocr-size small
降低 DPI: --dpi 200
关闭其他占用 GPU 的程序
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
# 根据结果决定用什么参数

扫描PDF转ebook

概述

PDF Craft Converter

能力一览

文件结构

安装指南

平台支持总览

第一步: 安装 UV

第二步: 安装 Poppler

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

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

安装 OCR 后端

第四步: 验证环境

macOS Apple Silicon 专题

Linux 专题

环境检查输出说明

使用指南

命令格式

第一步: 检测 PDF

第二步: 单文件转换

转 Markdown

转 EPUB

选择 OCR 后端

第三步: 批量转换

参数速查

单文件转换 (pdf_craft_cli.py)

通用参数

markdown 子命令

epub 子命令

detect 子命令

download-models 子命令

批量转换 (batch_convert.py)

后端选择指南

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

性能参考

常见问题

完整使用示例

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

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

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

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

示例 5: 只检测不转换

版本历史

安全检测

腾讯云安全 (Keen)

腾讯云安全 (Sanbu)

🔗 相关推荐

Word / DOCX

Nano Pdf

Gog