MinerU API接口详解：RESTful接口完整文档

概述

MinerU是一款高质量的开源PDF转Markdown和JSON工具，提供强大的RESTful API接口，支持批量处理、多格式输出和灵活的配置选项。本文档详细介绍了MinerU的API接口使用方法、参数说明和最佳实践。

快速开始

启动API服务

# 安装MinerU
pip install mineru

# 启动API服务
mineru-api --host 0.0.0.0 --port 8000

服务启动后，可通过以下地址访问API文档：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

基础请求示例

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

API端点详解

POST /file_parse

PDF文档解析接口，支持单文件或批量文件处理。

请求参数

参数名	类型	必填	默认值	描述
files	List[UploadFile]	是	-	上传的PDF或图像文件列表
output_dir	str	否	"./output"	输出目录路径
lang_list	List[str]	否	["ch"]	语言列表（支持多语言）
backend	str	否	"pipeline"	解析后端类型
parse_method	str	否	"auto"	解析方法（auto/txt/ocr）
formula_enable	bool	否	True	是否启用公式解析
table_enable	bool	否	True	是否启用表格解析
server_url	str	否	None	SGLang服务器地址
return_md	bool	否	True	是否返回Markdown格式
return_middle_json	bool	否	False	是否返回中间JSON格式
return_model_output	bool	否	False	是否返回模型原始输出
return_content_list	bool	否	False	是否返回内容列表
return_images	bool	否	False	是否返回图像base64编码
start_page_id	int	否	0	起始页码（从0开始）
end_page_id	int	否	99999	结束页码

后端类型（backend）选项

graph TD
    A[后端类型] --> B[pipeline]
    A --> C[vlm-transformers]
    A --> D[vlm-sglang-engine]
    A --> E[vlm-sglang-client]
    
    B --> F[传统流水线模式]
    C --> G[基于Transformers的VLM]
    D --> H[本地SGLang引擎]
    E --> I[远程SGLang客户端]
    
    F --> J[支持多语言OCR]
    F --> K[支持批量处理]
    G --> L[端到端文档理解]
    H --> M[高性能推理]
    I --> N[分布式部署]

语言支持列表

语言代码	语言名称	支持的后端
ch	中文（默认）	pipeline
ch_server	中文服务器版	pipeline
ch_lite	中文轻量版	pipeline
en	英文	pipeline
korean	韩文	pipeline
japan	日文	pipeline
chinese_cht	繁体中文	pipeline
auto	自动检测	pipeline

响应格式

{
  "backend": "pipeline",
  "version": "2.1.11",
  "results": {
    "document_name": {
      "md_content": "提取的Markdown内容",
      "middle_json": { "pdf_info": {...} },
      "model_output": "模型原始输出",
      "content_list": ["内容列表"],
      "images": {
        "image1.jpg": "data:image/jpeg;base64,..."
      }
    }
  }
}

高级用法

批量文件处理

# 批量处理多个文件
curl -X POST "http://localhost:8000/file_parse" \
  -F "files=@doc1.pdf" \
  -F "files=@doc2.pdf" \
  -F "files=@doc3.png" \
  -F "lang_list=ch" \
  -F "lang_list=en" \
  -F "lang_list=ch" \
  -F "backend=pipeline"

自定义输出格式

# 仅获取Markdown内容
curl -X POST "http://localhost:8000/file_parse" \
  -F "files=@document.pdf" \
  -F "return_md=true" \
  -F "return_middle_json=false" \
  -F "return_model_output=false"

# 获取完整解析结果
curl -X POST "http://localhost:8000/file_parse" \
  -F "files=@document.pdf" \
  -F "return_md=true" \
  -F "return_middle_json=true" \
  -F "return_model_output=true" \
  -F "return_content_list=true" \
  -F "return_images=true"

页面范围控制

# 仅解析前10页
curl -X POST "http://localhost:8000/file_parse" \
  -F "files=@document.pdf" \
  -F "start_page_id=0" \
  -F "end_page_id=9"

# 解析特定页面范围
curl -X POST "http://localhost:8000/file_parse" \
  -F "files=@document.pdf" \
  -F "start_page_id=5" \
  -F "end_page_id=15"

性能优化配置

环境变量配置

# 设置推理设备（CPU/GPU）
export MINERU_DEVICE_MODE=cuda

# 设置显存限制（GB）
export MINERU_VIRTUAL_VRAM_SIZE=8

# 设置模型来源
export MINERU_MODEL_SOURCE=modelscope

# 禁用公式解析
export MINERU_FORMULA_ENABLE=false

# 禁用表格解析
export MINERU_TABLE_ENABLE=false

后端性能对比

后端类型	处理速度	显存需求	精度	适用场景
pipeline	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	通用文档处理
vlm-transformers	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐	高质量解析
vlm-sglang-engine	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐⭐⭐⭐	高性能推理
vlm-sglang-client	⭐⭐⭐⭐	⭐	⭐⭐⭐⭐⭐	分布式部署

错误处理

常见错误码

状态码	错误信息	解决方案
400	Unsupported file type	检查文件格式，支持PDF/PNG/JPG
400	Failed to load file	检查文件完整性和权限
500	Failed to process file	检查系统资源和模型配置

错误响应示例

{
  "error": "Failed to process file: Model initialization failed"
}

最佳实践

生产环境部署

# 使用Docker部署
docker run -d \
  -p 8000:8000 \
  -v ./output:/app/output \
  -v ./models:/root/.cache/mineru \
  --gpus all \
  mineru:latest \
  mineru-api --host 0.0.0.0 --port 8000

监控和日志

# 启用详细日志
export MINERU_LOG_LEVEL=DEBUG

# 监控API性能
# 使用Prometheus + Grafana监控接口响应时间和资源使用

安全配置

# 启用HTTPS
uvicorn mineru.cli.fast_api:app \
  --host 0.0.0.0 \
  --port 8443 \
  --ssl-keyfile key.pem \
  --ssl-certfile cert.pem

# 配置API密钥认证（需要自定义中间件）

客户端代码示例

Python客户端

import requests
import json

def parse_pdf_with_mineru(api_url, file_path, output_dir="./output"):
    """使用MinerU API解析PDF文档"""
    
    with open(file_path, 'rb') as f:
        files = {'files': (file_path.name, f, 'application/pdf')}
        
        data = {
            'output_dir': output_dir,
            'lang_list': 'ch',
            'backend': 'pipeline',
            'return_md': 'true',
            'return_middle_json': 'true'
        }
        
        response = requests.post(
            f"{api_url}/file_parse",
            files=files,
            data=data
        )
        
        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"API请求失败: {response.text}")

# 使用示例
result = parse_pdf_with_mineru(
    "http://localhost:8000",
    "document.pdf"
)
print(json.dumps(result, indent=2, ensure_ascii=False))

JavaScript客户端

async function parsePDF(apiUrl, file) {
    const formData = new FormData();
    formData.append('files', file);
    formData.append('output_dir', './output');
    formData.append('lang_list', 'ch');
    formData.append('backend', 'pipeline');
    formData.append('return_md', 'true');
    
    const response = await fetch(`${apiUrl}/file_parse`, {
        method: 'POST',
        body: formData
    });
    
    if (response.ok) {
        return await response.json();
    } else {
        throw new Error(`API请求失败: ${response.statusText}`);
    }
}

// 使用示例
const fileInput = document.getElementById('pdf-file');
fileInput.addEventListener('change', async (event) => {
    const file = event.target.files[0];
    try {
        const result = await parsePDF('http://localhost:8000', file);
        console.log('解析结果:', result);
    } catch (error) {
        console.error('解析失败:', error);
    }
});

性能调优指南

内存优化配置

# 针对低内存环境的配置
export MINERU_VIRTUAL_VRAM_SIZE=4
export MINERU_DEVICE_MODE=cpu
export MINERU_FORMULA_ENABLE=false
export MINERU_TABLE_ENABLE=false

批量处理优化

flowchart TD
    A[开始批量处理] --> B[初始化模型]
    B --> C{选择最优后端}
    C -->|小文件| D[pipeline批量模式]
    C -->|大文件| E[vlm-sglang-client]
    
    D --> F[并行处理]
    E --> G[分布式处理]
    
    F --> H[内存优化]
    G --> I[负载均衡]
    
    H --> J[完成处理]
    I --> J

监控指标

指标	正常范围	告警阈值	优化建议
响应时间	< 30s	> 60s	调整后端类型或增加资源
内存使用	< 80%	> 90%	降低批量大小或优化配置
CPU使用率	< 70%	> 90%	考虑使用GPU加速
并发连接数	< 100	> 200	增加实例或负载均衡

常见问题解答

Q: API响应时间过长怎么办？

A: 可以尝试以下优化措施：

• 使用 vlm-sglang-engine 后端
• 禁用公式和表格解析（如不需要）
• 增加系统资源（内存、GPU）
• 使用批量处理而不是单文件处理

Q: 如何处理大文件？

A: 对于大文件（>100页），建议：

• 使用页面范围控制，分批次处理
• 使用 vlm-sglang-client 连接远程高性能服务器
• 增加JVM内存分配（如果使用Java客户端）

Q: 如何提高解析精度？

A: 可以尝试：

• 使用 vlm-transformers 或 vlm-sglang-engine 后端
• 确保提供正确的语言参数
• 检查输入文件质量，低质量扫描件可能影响效果

版本兼容性

MinerU版本	API兼容性	主要特性
2.1.x	✅ 完全兼容	最新功能和性能优化
2.0.x	✅ 向后兼容	架构重构和模型更新
1.x.x	⚠️ 部分兼容	传统功能，建议升级

总结

MinerU的RESTful API提供了强大而灵活的文档解析能力，支持多种输出格式、批量处理和性能优化。通过合理的配置和使用最佳实践，可以在生产环境中实现高效的文档处理流水线。

建议定期关注项目更新，以获取最新的性能优化和功能增强。如有问题或建议，欢迎通过项目Issue反馈。