OCRFlux：将PDF和图像转换为Markdown的轻量工具

OCRFlux 是一个开源的轻量工具，专注于将 PDF 文件和图像转换为清晰的 Markdown 格式。它由 ChatDOC 团队开发，基于 3B 参数的多模态大模型构建，能在普通硬件如 GTX 3090 上运行。工具擅长处理复杂文档布局，精准解析多列格式、复杂表格，并支持跨页内容的自动合并。相比其他开源 OCR 模型，OCRFlux 在准确率上表现优异，特别是在表格和段落处理方面。它提供简单易用的命令行操作，适合开发者、研究人员和需要将文档转为 Markdown 格式的用户。项目在 GitHub 上开源，拥有 Apache 2.0 许可证，社区活跃，获得 1.7k 星标。

功能列表

• 将 PDF 和图像转换为 Markdown 格式，保留自然阅读顺序。
• 支持复杂布局处理，包括多列文档、插图和嵌入内容。
• 自动解析复杂表格，支持 rowspan 和 colspan 的 HTML 表格输出。
• 跨页内容合并，自动检测并整合跨页的表格和段落。
• 提供高精度文本识别，Edit Distance Similarity (EDS) 达 0.967。
• 基于 3B 参数多模态模型，兼容普通 GPU 运行。
• 开源免费，代码和文档在 GitHub 上公开，支持社区贡献。

使用帮助

安装流程

OCRFlux 是一个基于 Docker 的工具，安装和运行需要 Docker 环境。以下是详细的安装步骤：

1. 安装 Docker
   确保你的系统已安装 Docker。如果没有，请访问 Docker 官网 下载并安装适合你操作系统的版本。安装完成后，运行以下命令验证：

   docker --version
   

2. 拉取 OCRFlux 镜像
   在终端运行以下命令，从 Docker Hub 拉取最新 OCRFlux 镜像：

   docker pull chatdoc/ocrflux:latest
   

3. 准备文件路径
   创建本地工作目录（例如 /path/to/localworkspace）用于存储输入和输出文件。确保你有以下目录：
   • 输入 PDF 文件目录（例如 /path/to/test_pdf_dir）。
   • OCRFlux 模型文件目录（例如 /path/to/OCRFlux-3B）。模型文件需从官方 GitHub 仓库或 ChatDOC 提供的链接下载。
4. 运行 OCRFlux
   使用以下命令启动 OCRFlux 容器，挂载本地目录并指定输入 PDF 和模型路径：

   docker run -it --gpus all \
   -v /path/to/localworkspace:/localworkspace \
   -v /path/to/test_pdf_dir:/test_pdf_dir \
   -v /path/to/OCRFlux-3B:/OCRFlux-3B \
   chatdoc/ocrflux:latest /localworkspace --data /test_pdf_dir/* --model /OCRFlux-3B/
   

   • --gpus all：启用 GPU 加速（如果无 GPU，可删除此参数）。
   • -v：挂载本地目录到容器内。
   • --data：指定输入 PDF 文件路径。
   • --model：指定模型文件路径。
5. 生成 Markdown 文件
   运行完成后，Markdown 输出文件会保存在 ./localworkspace/markdowns/DOCUMENT_NAME 目录下。使用以下命令将 JSONL 格式转换为 Markdown：

   python -m ocrflux.jsonl_to_markdown ./localworkspace
   

使用流程

OCRFlux 的核心功能是将 PDF 或图像转换为 Markdown。以下是具体操作步骤：

1. 准备输入文件
   将需要转换的 PDF 文件或图像放入 /path/to/test_pdf_dir 目录。支持常见 PDF 格式和图像格式（如 PNG、JPG）。
2. 运行转换任务
   使用上述 Docker 命令启动转换。OCRFlux 会自动分析文档布局，识别文本、表格和跨页内容。转换过程可能需要几分钟，具体时间取决于文件大小和硬件性能。
3. 检查输出结果
   转换完成后，打开 ./localworkspace/markdowns/DOCUMENT_NAME 目录查看生成的 Markdown 文件。文件会保留文档的自然阅读顺序，表格以 Markdown 或 HTML 格式呈现。
4. 处理复杂表格
   OCRFlux 能处理包含 rowspan 和 colspan 的复杂表格。生成的 Markdown 文件会将表格结构化为清晰的格式，适合直接编辑或导入其他工具。
5. 跨页内容合并
   对于跨页的表格或段落，OCRFlux 会自动检测并合并内容。例如，跨两页的表格会被整合为一个完整表格，段落也会按逻辑顺序拼接。

特色功能操作

• 复杂布局处理：OCRFlux 支持多列文档和嵌入插图的解析。运行时无需额外配置，工具会自动识别文档结构。
• 高精度识别：在 OCRFlux-bench-single 测试中，工具的 EDS 得分达 0.967，优于 olmOCR-7B（0.872）、Nanonets-OCR-s（0.858）和 MonkeyOCR（0.780）。
• 跨页合并：这是 OCRFlux 的独特功能。工具会分析连续页面，检测需要合并的表格或段落，并输出完整内容。

注意事项

• 确保输入 PDF 文件清晰，扫描件分辨率建议高于 300 DPI。
• 如果 GPU 不可用，转换速度可能较慢，建议使用高性能 CPU。
• 检查模型文件完整性，缺失文件可能导致转换失败。
• 定期访问 GitHub 仓库 获取最新版本和更新说明。

应用场景

1. 学术研究
   研究人员可以将学术论文 PDF 转换为 Markdown，方便编辑和分享。OCRFlux 能处理多列布局和复杂表格，确保公式和参考文献格式清晰。
2. 技术文档整理
   开发者可将技术手册或 API 文档从 PDF 转为 Markdown，导入知识库或博客。跨页合并功能避免内容碎片化。
3. 发票和表单处理
   财务人员可将发票或表单 PDF 转为 Markdown，提取关键信息如购买方、单价和价税合计，方便数据分析。
4. 内容创作者
   创作者可将扫描的书籍或笔记转为 Markdown Jellybean 格式，整理成可发布的 Markdown 文件，适合直接用于网站或文档。

QA

1. OCRFlux 支持哪些文件格式？
   它支持 PDF 和常见图像格式（如 PNG、JPG）。输入文件需为清晰的文档或扫描件。
2. 需要高性能硬件吗？
   不需要。OCRFlux 基于 3B 参数模型，普通 GPU（如 GTX 3090）或高性能 CPU 即可运行。
3. 如何处理跨页表格？
   OCRFlux 自动检测跨页的表格和段落，合并后输出完整的 Markdown 格式，无需手动干预。
4. 转换结果不准确怎么办？
   检查输入文件的分辨率（建议 300 DPI 以上）。若问题仍存在，可在 GitHub 提交 issue 寻求社区帮助。
5. 是否需要联网运行？
   无需联网。OCRFlux 在本地 Docker 环境中运行，模型和数据均离线处理。