MinerU Python API：编程接口完整文档-优快云博客

MinerU Python API：编程接口完整文档

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

概述

MinerU是一个强大的开源PDF文档解析工具，能够将PDF文档高质量地转换为Markdown和JSON格式。本文档详细介绍了MinerU的Python编程接口，帮助开发者灵活集成PDF解析功能到自己的应用中。

核心API函数

主要解析函数

`do_parse()` - 同步解析函数

def do_parse(
    output_dir: str,
    pdf_file_names: list[str],
    pdf_bytes_list: list[bytes],
    p_lang_list: list[str],
    backend: str = "pipeline",
    parse_method: str = "auto",
    formula_enable: bool = True,
    table_enable: bool = True,
    server_url: Optional[str] = None,
    f_draw_layout_bbox: bool = True,
    f_draw_span_bbox: bool = True,
    f_dump_md: bool = True,
    f_dump_middle_json: bool = True,
    f_dump_model_output: bool = True,
    f_dump_orig_pdf: bool = True,
    f_dump_content_list: bool = True,
    f_make_md_mode: str = MakeMode.MM_MD,
    start_page_id: int = 0,
    end_page_id: Optional[int] = None,
    **kwargs
) -> None

`aio_do_parse()` - 异步解析函数

async def aio_do_parse(
    output_dir: str,
    pdf_file_names: list[str],
    pdf_bytes_list: list[bytes],
    p_lang_list: list[str],
    backend: str = "pipeline",
    parse_method: str = "auto",
    formula_enable: bool = True,
    table_enable: bool = True,
    server_url: Optional[str] = None,
    f_draw_layout_bbox: bool = True,
    f_draw_span_bbox: bool = True,
    f_dump_md: bool = True,
    f_dump_middle_json: bool = True,
    f_dump_model_output: bool = True,
    f_dump_orig_pdf: bool = True,
    f_dump_content_list: bool = True,
    f_make_md_mode: str = MakeMode.MM_MD,
    start_page_id: int = 0,
    end_page_id: Optional[int] = None,
    **kwargs
) -> None

参数详解

必需参数

参数名	类型	描述	示例
`output_dir`	`str`	输出目录路径	`"./output"`
`pdf_file_names`	`list[str]`	PDF文件名列表	`["document1", "report2"]`
`pdf_bytes_list`	`list[bytes]`	PDF字节数据列表	`[b'%PDF-1.4...', b'%PDF-1.5...']`
`p_lang_list`	`list[str]`	语言列表	`["ch", "en"]`

可选参数

后端配置参数

参数名	类型	默认值	可选值	描述
`backend`	`str`	`"pipeline"`	`"pipeline"`, `"vlm-transformers"`, `"vlm-sglang-engine"`, `"vlm-sglang-client"`	解析后端引擎
`parse_method`	`str`	`"auto"`	`"auto"`, `"txt"`, `"ocr"`	解析方法（仅pipeline后端）
`formula_enable`	`bool`	`True`	`True`/`False`	是否启用公式解析
`table_enable`	`bool`	`True`	`True`/`False`	是否启用表格解析
`server_url`	`str`	`None`	URL字符串	VLM客户端模式服务器地址

输出控制参数

参数名	类型	默认值	描述
`f_draw_layout_bbox`	`bool`	`True`	是否绘制布局边界框
`f_draw_span_bbox`	`bool`	`True`	是否绘制文本跨度边界框
`f_dump_md`	`bool`	`True`	是否输出Markdown文件
`f_dump_middle_json`	`bool`	`True`	是否输出中间JSON文件
`f_dump_model_output`	`bool`	`True`	是否输出模型原始输出
`f_dump_orig_pdf`	`bool`	`True`	是否输出原始PDF文件
`f_dump_content_list`	`bool`	`True`	是否输出内容列表JSON

页面范围参数

参数名	类型	默认值	描述
`start_page_id`	`int`	`0`	起始页码（从0开始）
`end_page_id`	`int`	`None`	结束页码（None表示到文档末尾）

输出格式参数

class MakeMode:
    MM_MD = 'mm_markdown'      # 多模态Markdown格式
    NLP_MD = 'nlp_markdown'    # NLP优化Markdown格式  
    CONTENT_LIST = 'content_list'  # 内容列表格式

语言支持

MinerU支持多种语言，适用于不同语言的文档解析：

语言代码	语言名称	描述
`ch`	中文	简体中文
`ch_server`	中文服务器版	优化的中文识别
`ch_lite`	中文轻量版	快速中文识别
`en`	英文	英语
`korean`	韩文	韩语
`japan`	日文	日语
`chinese_cht`	繁体中文	繁体中文
`ta`	泰米尔语	泰米尔语
`te`	泰卢固语	泰卢固语
`ka`	卡纳达语	卡纳达语
`latin`	拉丁语系	拉丁字母语言
`arabic`	阿拉伯语	阿拉伯语
`east_slavic`	东斯拉夫语	俄语等
`cyrillic`	西里尔字母	斯拉夫语言
`devanagari`	天城文	印地语等

使用示例

基础使用示例

from pathlib import Path
from mineru.cli.common import do_parse, read_fn

# 单个PDF文件解析
pdf_path = "document.pdf"
output_dir = "./output"

do_parse(
    output_dir=output_dir,
    pdf_file_names=[Path(pdf_path).stem],
    pdf_bytes_list=[read_fn(pdf_path)],
    p_lang_list=["ch"],
    backend="pipeline"
)

批量处理示例

from pathlib import Path
from mineru.cli.common import do_parse, read_fn

# 批量处理目录中的PDF文件
input_dir = "./documents"
output_dir = "./output"

pdf_files = list(Path(input_dir).glob("*.pdf"))
pdf_names = [f.stem for f in pdf_files]
pdf_bytes = [read_fn(f) for f in pdf_files]

do_parse(
    output_dir=output_dir,
    pdf_file_names=pdf_names,
    pdf_bytes_list=pdf_bytes,
    p_lang_list=["ch"] * len(pdf_files),
    backend="vlm-transformers",
    start_page_id=0,
    end_page_id=10  # 只处理前10页
)

高级配置示例

from mineru.cli.common import do_parse, read_fn
from mineru.utils.enum_class import MakeMode

# 高级配置示例
do_parse(
    output_dir="./advanced_output",
    pdf_file_names=["technical_document"],
    pdf_bytes_list=[read_fn("tech_doc.pdf")],
    p_lang_list=["en"],
    backend="pipeline",
    parse_method="auto",
    formula_enable=True,
    table_enable=True,
    f_draw_layout_bbox=False,  # 不绘制布局框
    f_draw_span_bbox=False,    # 不绘制文本跨度框
    f_dump_md=True,
    f_dump_middle_json=True,
    f_dump_model_output=False, # 不输出模型原始数据
    f_dump_orig_pdf=False,
    f_dump_content_list=True,
    f_make_md_mode=MakeMode.NLP_MD,  # 使用NLP优化格式
    start_page_id=5,           # 从第6页开始
    end_page_id=20             # 到第21页结束
)

异步处理示例

import asyncio
from mineru.cli.common import aio_do_parse, read_fn

async def process_documents_async():
    pdf_files = ["doc1.pdf", "doc2.pdf", "doc3.pdf"]
    
    await aio_do_parse(
        output_dir="./async_output",
        pdf_file_names=[Path(f).stem for f in pdf_files],
        pdf_bytes_list=[read_fn(f) for f in pdf_files],
        p_lang_list=["ch"] * len(pdf_files),
        backend="vlm-sglang-client",
        server_url="http://127.0.0.1:30000"
    )

# 运行异步任务
asyncio.run(process_documents_async())

输出文件结构

解析完成后，输出目录结构如下：

output/
├── document_name/           # 文档名称目录
│   ├── auto/               # 解析方法目录（auto/txt/ocr/vlm）
│   │   ├── images/         # 提取的图片
│   │   │   ├── page0_image0.jpg
│   │   │   └── page1_image1.jpg
│   │   ├── document_name.md              # Markdown文件
│   │   ├── document_name_middle.json     # 中间JSON数据
│   │   ├── document_name_content_list.json # 内容列表
│   │   ├── document_name_model.json      # 模型输出（pipeline）
│   │   ├── document_name_model_output.txt # 模型输出（VLM）
│   │   ├── document_name_origin.pdf      # 原始PDF（可选）
│   │   ├── document_name_layout.pdf      # 布局可视化（可选）
│   │   └── document_name_span.pdf        # 文本跨度可视化（可选）
│   └── vlm/                # VLM后端输出目录
└── another_document/       # 另一个文档

中间JSON格式说明

中间JSON文件包含丰富的文档结构信息：

{
  "pdf_info": {
    "pages": [
      {
        "page_id": 0,
        "width": 595.0,
        "height": 842.0,
        "blocks": [
          {
            "block_id": "0_0",
            "type": "title",
            "bbox": [50, 50, 545, 100],
            "text": "文档标题",
            "confidence": 0.95
          },
          {
            "block_id": "0_1", 
            "type": "text",
            "bbox": [50, 120, 545, 200],
            "text": "正文内容...",
            "confidence": 0.92
          }
        ]
      }
    ],
    "metadata": {
      "title": "文档标题",
      "author": "作者",
      "creation_date": "2024-01-01"
    }
  }
}

错误处理

MinerU API提供完善的错误处理机制：

from loguru import logger
from mineru.cli.common import do_parse

try:
    do_parse(
        output_dir="./output",
        pdf_file_names=["test"],
        pdf_bytes_list=[b"invalid_pdf_data"],
        p_lang_list=["ch"]
    )
except Exception as e:
    logger.error(f"解析失败: {e}")
    # 处理具体错误类型
    if "PDF" in str(e):
        print("PDF文件格式错误")
    elif "memory" in str(e):
        print("内存不足")

性能优化建议

内存优化

# 限制处理页面范围以减少内存使用
do_parse(
    output_dir="./output",
    pdf_file_names=["large_document"],
    pdf_bytes_list=[read_fn("large.pdf")],
    p_lang_list=["ch"],
    start_page_id=0,
    end_page_id=50,  # 只处理前50页
    f_dump_model_output=False  # 不保存模型输出节省空间
)

批量处理优化

# 使用VLM后端进行批量处理
do_parse(
    output_dir="./batch_output",
    pdf_file_names=[f"doc_{i}" for i in range(10)],
    pdf_bytes_list=[read_fn(f"doc_{i}.pdf") for i in range(10)],
    p_lang_list=["ch"] * 10,
    backend="vlm-sglang-engine",  # 使用引擎模式提高性能
    f_draw_layout_bbox=False,
    f_draw_span_bbox=False
)

环境配置

模型下载配置

import os

# 设置模型下载源（解决网络问题）
os.environ['MINERU_MODEL_SOURCE'] = "modelscope"  # 或 "huggingface", "local"

# 设置设备模式
os.environ['MINERU_DEVICE_MODE'] = "cuda"  # 使用GPU加速

# 设置显存限制（MB）
os.environ['MINERU_VIRTUAL_VRAM_SIZE'] = "4096"

后端特定配置

# VLM公式和表格处理配置
os.environ['MINERU_VLM_FORMULA_ENABLE'] = "True"
os.environ['MINERU_VLM_TABLE_ENABLE'] = "True"

最佳实践

1. 生产环境部署

# 生产环境推荐配置
do_parse(
    output_dir="/data/output",
    pdf_file_names=[doc_name],
    pdf_bytes_list=[pdf_data],
    p_lang_list=["ch"],
    backend="vlm-sglang-engine",
    f_draw_layout_bbox=False,
    f_draw_span_bbox=False,
    f_dump_orig_pdf=False,
    f_dump_model_output=False,
    f_make_md_mode=MakeMode.MM_MD
)

2. 开发调试配置

# 开发调试配置
do_parse(
    output_dir="./debug_output",
    pdf_file_names=["debug_doc"],
    pdf_bytes_list=[debug_pdf_data],
    p_lang_list=["ch"],
    backend="pipeline",
    f_draw_layout_bbox=True,
    f_draw_span_bbox=True,
    f_dump_middle_json=True,
    f_dump_model_output=True,
    f_make_md_mode=MakeMode.CONTENT_LIST
)

常见问题解答

Q: 如何处理大型PDF文件？

A: 使用分页处理并限制输出选项：

do_parse(
    start_page_id=0,
    end_page_id=100,  # 分批处理
    f_dump_model_output=False,
    f_dump_orig_pdf=False
)

Q: 如何提高解析精度？

A: 根据文档类型选择合适的后端和语言：

# 中文文档
backend="pipeline", lang="ch_server"

# 英文科技文档  
backend="vlm-transformers", lang="en"

# 多语言混合文档
backend="pipeline", lang="auto"

Q: 如何处理解析失败？

A: 实现重试机制和错误日志：

import time
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10))
def safe_parse(pdf_path, output_dir):
    try:
        do_parse(...)
        return True
    except Exception as e:
        logger.warning(f"解析失败，重试中: {e}")
        raise

总结

MinerU Python API提供了强大而灵活的PDF解析能力，支持多种后端引擎、输出格式和配置选项。通过合理使用API参数和优化配置，可以满足从简单文档转换到复杂生产环境的各种需求。

建议根据具体应用场景选择合适的后端和配置，平衡解析质量、性能和资源消耗。对于生产环境，推荐使用VLM引擎模式以获得最佳性能；对于开发和调试，可以使用pipeline后端以获得更详细的中间结果。

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

MinerU Python API：编程接口完整文档

MinerU Python API：编程接口完整文档

概述

核心API函数

主要解析函数

do_parse() - 同步解析函数

aio_do_parse() - 异步解析函数

参数详解

必需参数

可选参数

后端配置参数

输出控制参数

页面范围参数

输出格式参数

语言支持

使用示例

基础使用示例

批量处理示例

高级配置示例

异步处理示例

输出文件结构

中间JSON格式说明

错误处理

性能优化建议

内存优化

批量处理优化

环境配置

模型下载配置

后端特定配置

最佳实践

1. 生产环境部署

2. 开发调试配置

常见问题解答

Q: 如何处理大型PDF文件？

Q: 如何提高解析精度？

Q: 如何处理解析失败？

总结

`do_parse()` - 同步解析函数

`aio_do_parse()` - 异步解析函数