PDF Craft完整安装指南：从零搭建本地PDF转换环境

【免费下载链接】pdf-craft PDF craft can convert PDF files into various other formats. This project will focus on processing PDF files of scanned books. The project has just started. 项目地址: https://gitcode.com/gh_mirrors/pd/pdf-craft

PDF Craft是一款强大的本地PDF转换工具，专注于将扫描书籍PDF文件转换为Markdown和EPUB格式。本文将为您提供从零开始的完整安装指南，帮助您快速搭建PDF Craft本地转换环境。🚀

为什么选择PDF Craft？🤔

PDF Craft基于DeepSeek OCR模型，能够在本地完成从PDF到Markdown或EPUB的完整转换过程。与传统的在线转换工具不同，PDF Craft完全在本地运行，保护您的隐私安全，同时支持复杂的学术文档处理，包括表格、公式、脚注等元素的准确识别和保留。

系统要求与环境准备📋

在开始安装之前，请确保您的系统满足以下要求：

硬件要求

• NVIDIA GPU：支持CUDA 11.8或12.1
• 显存：16GB以上（推荐24GB或更高）
• 存储空间：至少10GB可用空间

软件要求

• Python：>= 3.10, < 3.14（推荐Python 3.11.16）
• Poppler：用于PDF解析和渲染
• CUDA环境：必须配置NVIDIA驱动和CUDA

第一步：验证CUDA环境🔧

首先检查您的系统是否已安装CUDA：

nvidia-smi

如果命令成功执行并显示CUDA版本信息，说明CUDA环境已就绪。如果未安装，请访问NVIDIA官网下载并安装适合您系统的CUDA版本。

第二步：安装PyTorch（CUDA版本）⚙️

根据您的CUDA版本选择合适的PyTorch安装命令。访问PyTorch官网获取最新安装指令。

CUDA 12.1安装示例：

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

CUDA 11.8安装示例：

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

第三步：安装PDF Craft📦

安装PDF Craft包非常简单：

pip install pdf-craft

第四步：安装Poppler（PDF解析工具）📄

PDF Craft使用Poppler进行PDF解析和渲染，这是必须安装的依赖项：

Ubuntu/Debian系统：

sudo apt-get install poppler-utils

macOS系统：

brew install poppler

Windows系统：

1. 从Poppler Windows版本下载最新二进制文件
2. 解压后将bin/目录添加到系统PATH环境变量
3. 或者在使用PDF Craft时指定Poppler路径

第五步：验证安装✅

安装完成后，运行以下命令验证环境：

# 验证CUDA
python -c "import torch; print('CUDA可用:', torch.cuda.is_available())"

# 验证Poppler
pdfinfo -v

如果一切正常，您应该看到：

• CUDA可用: True
• Poppler版本信息

第六步：创建Python虚拟环境（可选但推荐）🐍

为避免依赖冲突，建议使用虚拟环境：

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境（Linux/Mac）
source venv/bin/activate

# 激活虚拟环境（Windows）
venv\Scripts\activate

# 在虚拟环境中重新安装PDF Craft
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
pip install pdf-craft

第七步：测试PDF转换功能🔄

现在让我们测试PDF Craft的基本功能。创建一个简单的Python脚本：

from pdf_craft import transform_markdown

# 将PDF转换为Markdown
transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    markdown_assets_path="images",
    ocr_size="gundam",  # 使用最大的OCR模型，质量最高
)

print("PDF转换完成！🎉")

第八步：高级配置与优化⚡

模型管理

PDF Craft依赖DeepSeek OCR模型，首次运行时会自动下载。您可以预下载模型以提高首次使用体验：

from pdf_craft import predownload_models

predownload_models(
    models_cache_path="models",  # 指定模型缓存目录
)

自定义PDF处理器

如果Poppler不在系统PATH中，可以指定自定义路径：

from pdf_craft import transform_markdown, DefaultPDFHandler

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    pdf_handler=DefaultPDFHandler(poppler_path="/path/to/poppler/bin"),
)

转换到EPUB格式

PDF Craft同样支持转换为EPUB电子书格式：

from pdf_craft import transform_epub, BookMeta

transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    book_meta=BookMeta(
        title="书名",
        authors=["作者"],
        publisher="出版社",
        language="zh",
    ),
)

常见问题与解决方案🔍

问题1：Poppler未找到错误

症状：运行PDF Craft时出现"Poppler not found in PATH"错误 解决方案：

1. 确保已正确安装poppler-utils（Linux）或Poppler（Windows/macOS）
2. Windows用户需将Poppler的bin目录添加到系统PATH
3. 或使用pdf_handler参数指定Poppler路径

问题2：CUDA不可用警告

症状：出现"CUDA is not available!"警告 解决方案：

1. 确认安装了CUDA版本的PyTorch，而非CPU版本
2. 更新NVIDIA驱动程序
3. 运行nvidia-smi检查GPU状态

问题3：依赖冲突

解决方案：使用虚拟环境隔离依赖

性能优化建议🚀

选择合适的OCR模型

PDF Craft提供多种OCR模型大小，根据您的需求选择：

• tiny - 最小模型，速度最快
• small - 小型模型
• base - 基础模型
• large - 大型模型
• gundam - 最大模型，质量最高（默认）

调整DPI设置

对于高分辨率PDF，可以降低DPI以加快处理速度：

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    dpi=150,  # 降低DPI，加快处理速度
)

开始您的PDF转换之旅🎯

现在您已经成功安装了PDF Craft！接下来可以：

1. 探索官方示例：查看项目中的示例脚本和示例脚本
2. 阅读完整文档：参考官方文档获取更多配置选项
3. 尝试不同格式：体验PDF到Markdown和EPUB的转换
4. 处理复杂文档：尝试处理包含表格、公式和脚注的学术PDF

PDF Craft的强大功能让您能够轻松处理扫描书籍PDF，保留原始文档的完整结构和格式。无论您是学术研究者、文档管理员还是电子书爱好者，PDF Craft都能为您提供专业的PDF转换解决方案。

提示：对于生产环境，建议预先下载模型文件，并确保有足够的GPU显存来处理大型PDF文件。祝您使用愉快！✨

【免费下载链接】pdf-craft PDF craft can convert PDF files into various other formats. This project will focus on processing PDF files of scanned books. The project has just started. 项目地址: https://gitcode.com/gh_mirrors/pd/pdf-craft