只需 4 步搞定！开源文档解析服务 MinerU-API 最新安装指南

于是，我开发了 MinerU-API 这个项目，可以便捷地部署和使用 MinerU 解析服务。

MinerU-API 项目已经开源。

这两天，我发现之前给出的使用方式，还不是那么简洁明了。

我更新了一版，增加了自动化脚本，把 MinerU-API 的安装和使用流程简化到了极致，只需 4 步就能启动。

今天就把新版指南分享给大家。

在 AI 时代，文档解析是很多应用的基础能力。无论是知识库构建、文档检索，还是智能问答，都需要将 PDF、Word 等文档转换为结构化数据。

MinerU-API 是一个基于 Celery 的异步文档解析服务，具有以下优势：

1. 异步处理：基于分布式任务队列，支持高并发。这意味着你可以同时处理多个文档，而不用担心性能问题。

2. 多格式支持：PDF、Office、图片等多种文档格式。不管你是处理论文、报告，还是图片中的文字，MinerU-API 都能搞定。我们用它处理过数万份 PDF 学术文献，又快又好。

3. 高可用性：支持任务重试和故障恢复。即使某个任务失败了，系统也会自动重试，确保你的任务能够完成。

4. 实时监控：任务状态跟踪和队列统计。你可以随时查看任务的进度和状态，了解系统的运行情况。

5. 易于扩展：模块化设计，易于添加新的解析引擎。如果你需要处理新的文档格式，只需要添加一个新的解析引擎即可。

最新版本最大的改进就是大幅简化了安装和配置流程。以前安装 MinerU-API，你可能会需要摸索一阵子，手动配置一些参数。现在，这些都不需要了。

1. 智能自动选择：build.sh 脚本会根据环境变量自动选择构建 CPU 或 GPU Worker，无需手动指定。

2. 一键启动：配置好 COMPOSE_PROFILES 后，直接运行 docker compose up -d 即可启动所有服务。

3. 默认服务自动启动：API 和 Cleanup 服务会自动启动，无需额外配置。

4. 更清晰的文档：所有配置说明都更加清晰明了。以前的文档可能会让你感到困惑，现在的文档会告诉你每一步该怎么做，以及为什么要这么做。

Part 03｜仅需 4 步快速安装

前置准备

在安装MinerU-API之前，你需要准备以下环境：

Docker 和 Docker Compose：MinerU-API 是基于 Docker 部署的。如果你还没有安装，可以参考 Docker 官方文档进行安装。

NVIDIA GPU（可选）：如果你需要使用 GPU Worker，那么你需要安装 GPU。GPU Worker 的性能比 CPU Worker 更好，尤其是在处理大量文档的时候。我测试过，GPU Worker 的速度比 CPU Worker 几乎要快 10 倍。

第 1 步：复制配置文件

首先，你需要克隆项目并复制配置文件。如果你还没有克隆项目，可以使用以下命令：

git clone https://github.com/wzdavid/mineru-api.gitcd mineru-api

然后，复制配置文件：

cp .env.example .envcd docker && cp .env.example .env

第 2 步：配置服务选择

接下来，你需要编辑 docker/.env 文件，设置 COMPOSE_PROFILES，选择要启动的服务。

有两种方式可以设置：

方式 1: GPU Worker + 内部 Redis（默认值，需要 GPU）

COMPOSE_PROFILES=redis,mineru-gpu

方式 2: CPU Worker + 内部 Redis（推荐开发环境）

COMPOSE_PROFILES=redis,mineru-cpu

需要注意的是，默认值是 COMPOSE_PROFILES=redis,mineru-gpu（GPU Worker）。如果你没有 GPU，那么你需要使用方式 2。

第 3 步：构建镜像

配置好 COMPOSE_PROFILES 后，你需要构建镜像。你可以使用以下命令构建镜像：

sh build.sh

sh build.sh --api --worker-gpu

sh build.sh --api --worker-cpu

新特性：build.sh 脚本会自动读取 COMPOSE_PROFILES 配置，智能选择构建对应的 Worker，无需手动指定参数！

第 4 步：启动服务

构建好镜像后，你可以使用以下命令启动服务：

docker compose up -d

如果你需要手动指定启动的服务，可以使用以下命令：

docker compose --profile redis --profile mineru-gpu up -d

docker compose --profile redis --profile mineru-cpu up -d

我测试过，从启动到服务正常运行，只需要不到 1 分钟的时间。

验证服务

启动服务后，你可以使用以下命令验证服务是否正常运行：

curl http://localhost:8000/api/v1/health

如果返回以下信息：

{  "success": true,  "status": "healthy",  "service": "MinerU API Server",  "version": "1.0.0",  "workers": {    "active": 1,    "available": true  },  "timestamp": "2026-01-22T13:03:35.831782"}

这说明 API 服务启动成功！

Part 04｜API使用示例

MinerU-API提供了两种API接口，适应不同的使用场景：

1. MinerU官方API（同步）

适用于简单集成、需要立即获取结果的场景。你可以使用以下命令调用MinerU官方API：

curl -X POST "http://localhost:8000/file_parse" \  -F "files=@document.pdf" \  -F "backend=pipeline" \  -F "lang_list=ch" \  -F "parse_method=auto" \  -F "return_md=true"

2. 异步队列API（异步）

适用于生产环境部署、批量处理、长时间运行的任务。你可以使用以下命令调用异步队列API：

提交任务：

curl -X POST "http://localhost:8000/api/v1/tasks/submit" \  -F "file=@document.pdf" \  -F "backend=pipeline" \  -F "lang=ch"

查询任务状态：

curl "http://localhost:8000/api/v1/tasks/{task_id}"

Python 客户端示例

以下是一个 Python 客户端示例：

import requests# 提交任务files = {'file': open('document.pdf', 'rb')}data = {  'backend': 'pipeline',  'lang': 'ch',  'method': 'auto'}response = requests.post('http://localhost:8000/api/v1/tasks/submit', files=files, data=data)task_id = response.json()['task_id']# 查询任务状态status_response = requests.get(f'http://localhost:8000/api/v1/tasks/{task_id}')print(status_response.json())

后续，我计划做成 Python SDK，这样就更容易使用了。

Part 05｜查看 API 文档

你可以访问以下网址查看 API 文档： 

http://localhost:8000/docs 

API 文档会告诉你每个 API 接口的参数、返回值和使用示例。这个自动生成的 API 文档很清晰，很容易上手。

Part 06｜核心配置说明

MinerU-API 提供了一些配置选项，以下是一些最重要的配置选项：

# Redis配置REDIS_URL=redis://redis:6379/0# 存储类型：local或s3MINERU_STORAGE_TYPE=local# S3存储配置（分布式部署）MINERU_S3_ENDPOINT=http://minio:9000MINERU_S3_ACCESS_KEY=minioadminMINERU_S3_SECRET_KEY=minioadmin# CORS配置（生产环境）CORS_ALLOWED_ORIGINS=http://localhost:3000ENVIRONMENT=production# 文件上传限制MAX_FILE_SIZE=104857600 # 100MB

Part 07｜架构说明

MinerU-API 采用完全解耦的 API / Worker架构，这种架构设计使得系统具有更好的可扩展性和可维护性。

1. API 服务：处理任务提交和状态查询。API服务是系统的入口，用户通过 API 服务提交任务和查询任务状态。

2. Worker 服务：使用 MinerU / MarkItDown 处理文档。Worker 服务是系统的核心，负责处理文档解析任务。

3. Redis：消息队列和结果存储。Redis 用于存储任务队列和任务结果。

4. Cleanup 服务：自动清理过期文件。Cleanup服务用于清理过期的文件，确保系统的存储空间不会被浪费。

Part 08｜总结一下

MinerU-API 最新版本通过以下改进，让安装和使用变得更加简单：

1. 智能自动选择：build.sh 根据配置自动选择安装 CPU / GPU Worker。

2. 一键启动：配置好环境变量后，直接 docker compose up -d，即可启动各个服务。

3. 默认服务自动启动：API 和 Cleanup 服务无需额外配置。

4. 更清晰的文档：所有配置说明都更加清晰明了。

无论是个人开发者还是企业团队，都可以快速上手使用 MinerU-API 构建自己的文档解析服务。

我从零开始做了测试，从安装到使用，非常顺利。