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

最新推荐文章于 2025-10-27 08:49:20 发布
原创 最新推荐文章于 2025-10-27 08:49:20 发布 · 1.5k 阅读 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。

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

【免费下载链接】MinerU A high-quality tool for convert PDF to Markdown and JSON.一站式开源高质量数据提取工具，将PDF转换成Markdown和JSON格式。 【免费下载链接】MinerU 项目地址: https://gitcode.com/gh_mirrors/mi/MinerU

概述

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文档解析接口，支持单文件或批量文件处理。

请求参数
参数名类型必填默认值描述
filesList[UploadFile]是-上传的PDF或图像文件列表
output_dirstr否"./output"输出目录路径
lang_listList[str]否["ch"]语言列表（支持多语言）
backendstr否"pipeline"解析后端类型
parse_methodstr否"auto"解析方法（auto/txt/ocr）
formula_enablebool否True是否启用公式解析
table_enablebool否True是否启用表格解析
server_urlstr否NoneSGLang服务器地址
return_mdbool否True是否返回Markdown格式
return_middle_jsonbool否False是否返回中间JSON格式
return_model_outputbool否False是否返回模型原始输出
return_content_listbool否False是否返回内容列表
return_imagesbool否False是否返回图像base64编码
start_page_idint否0起始页码（从0开始）
end_page_idint否99999结束页码
后端类型（backend）选项

mermaid

语言支持列表
语言代码语言名称支持的后端
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⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐分布式部署

错误处理

常见错误码

状态码错误信息解决方案
400Unsupported file type检查文件格式，支持PDF/PNG/JPG
400Failed to load file检查文件完整性和权限
500Failed 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

批量处理优化

mermaid

监控指标

指标正常范围告警阈值优化建议
响应时间< 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反馈。

【免费下载链接】MinerU A high-quality tool for convert PDF to Markdown and JSON.一站式开源高质量数据提取工具，将PDF转换成Markdown和JSON格式。 【免费下载链接】MinerU 项目地址: https://gitcode.com/gh_mirrors/mi/MinerU

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值