本项目是一个功能强大的 PDF 文档解析服务。它利用 MinerU 的核心能力，能够深度解析 PDF 文件，提取文本、表格、图片等元素，并将其转换为结构化的 Markdown 和 JSON 格式。 需要注意，这里的MinerU还暂时没有假如GPU支持。
如果对项目感兴趣，请fork并且star原项目MinerU
服务采用异步架构，通过 FastAPI 接收请求，使用 Celery 和 Redis 构建分布式任务队列，确保了在高并发和处理大型文件时的稳定性和高性能。整个服务已完全容器化，可通过 Docker Compose 一键部署。
- PDF 到 Markdown: 将 PDF 内容（包括文本和图片）高质量地转换为 Markdown 格式。
- PDF 到 JSON: 提取文档内容并输出为两种结构化的 JSON 格式，便于程序处理。
- OCR 支持: 自动检测扫描版 PDF，并调用 OCR 提取文字。
- 异步处理: 基于 Celery 的任务队列，API 能够立即响应，并在后台处理耗时任务。
- 日志系统: 同时输出到美化的控制台和持久化的文件，便于调试和追踪。
- 容器化部署: 使用 Docker 和 Docker Compose，实现一键启动和环境隔离。
- 可扩展架构: Web 服务与计算任务分离，可以独立扩展 Celery Worker 以应对高负载。
服务采用经典M-M-W模式，由三个核心容器组成：
- FastAPI Web App: 作为Master，接收用户上传的 PDF 文件，创建解析任务并推入 Redis 队列，然后立即返回任务 ID。
- Redis: 作为消息代理（Broker），存储待处理的任务队列，并作为后端（Backend）存储任务结果。
- Celery Worker: 作为Worker，从 Redis 队列中获取任务，调用
magic-pdf库执行繁重的 PDF 解析工作，并将结果写回 Redis。
在开始之前，请确保您的系统已安装以下软件：
- Docker
- Docker Compose (通常随 Docker Desktop 一同安装)
-
克隆仓库
git clone https://github.com/lichman0405/mineru-api.git cd mineru-api -
创建数据目录 服务需要一个
data目录来存放输入、输出和日志文件。请在项目根目录执行：mkdir -p data/input_pdfs data/output data/logs
-
准备测试文件 将一个或多个您想要测试的 PDF 文件放入
./data/input_pdfs/目录中。 -
构建并启动服务 使用 Docker Compose 一键构建并启动所有服务（Web App, Worker, Redis）。
docker-compose up --build -d
-d参数会让服务在后台运行。您可以使用docker-compose logs -f查看实时日志。
我们推荐使用项目提供的客户端脚本与服务进行交互。这大大简化了提交、轮询和下载的流程。请在您的本地电脑（而非容器内）运行这些脚本。
使用 test_single_file.py 脚本，可以完成从提交到下载结果的完整流程。
- 安装依赖:
pip install requests
- 运行脚本:
# 将 test.pdf 的处理结果下载到 ./downloaded_results 目录 python test_single_file.py --file ./data/input_pdfs/test.pdf --download-dir ./downloaded_results - 查看结果:
脚本会自动提交文件、轮询状态，并在任务成功后下载一个包含所有结果的
.zip文件到./downloaded_results目录。
使用 batch_submit.py 脚本，可以高效地将一个目录下的所有PDF文件提交给服务。
-
安装依赖:
pip install requests tqdm
-
运行脚本:
# 使用10个并发线程，提交指定目录下的所有PDF python batch_submit.py --directory ./data/input_pdfs/ --workers 10 -
获取任务ID: 脚本运行结束后，会在当前目录生成一个
submission_log.csv文件。此文件包含了每个文件名与对应的task_id。您可以在稍后根据这些task_id来获取结果。
使用batch_download.py，根据本地submission_log.csv文件中的task_id，批量下载完成转换的任务。下载文件是*.zip。
-
安装依赖
pip install requests tqdm
-
运行脚本
# 使用10个并发线程，下载所有zip python batch_download.py --csv-file /path/to/csv_file -u base_url_of_service -d /path/to/download_directory -w 10 -
解压之后手工处理 脚本目前没有提供自动整理或者归档转制之后的markdown文件的功能，请自行手工处理。
如果您希望自己编写客户端，以下是核心的API端点：
| 方法 | 路径 | 描述 |
|---|---|---|
POST |
/process-pdf/ |
提交一个PDF文件，返回 task_id。 |
GET |
/tasks/status/{task_id} |
查询指定任务的状态和结果（如果已完成）。 |
GET |
/tasks/result/download/{task_id} |
下载指定任务所有结果的 .zip 压缩包。 |
当您通过下载API获取到结果的 .zip 压缩包并解压后，会看到一个以原PDF文件名命名的专属文件夹，其内部结构如下：
data/output/
└── my_document/
├── my_document.md
├── my_document_content_list.json
├── my_document_middle.json
├── my_document_layout.pdf
└── images/
└── ...本项目采用 MIT 许可证。详情请见 LICENSE 文件。
Shibo Li