MinerU LlamaIndex 集成深度指南：一键打通复杂文档与大模型数据索引架构

原创

用户12386590

发布于 2026-04-16 16:05:56

1810

MinerU 是什么

MinerU 是上海人工智能实验室开源的一站式文档解析工具，基于视觉语言模型（VLM）架构，能够将 PDF、图片、Word、PPT、Excel 等任意格式的文档转换为结构化的 Markdown 输出。最新版本 MinerU2.5-Pro 仅用 1.2B 参数即在 OmniDocBench v1.6 基准上取得 95.69 分，大幅超越 GPT-4o、Qwen2.5-VL-72B 等数十倍参数规模的模型，稳居当前文档解析榜首。

MinerU 的核心能力包括：

PDF 转 Markdown：保留原始版式、标题层级、段落结构
公式识别：复杂 LaTeX 公式准确率高达 98%
表格提取：复杂表格识别准确率 92%
多语言 OCR：支持 109 种语言的文档识别
图片提取：将文档内嵌图片独立导出
网页抓取：将任意 URL 网页转换为 Markdown

MinerU 生态包含六大模块：CLI 命令行工具、SDK 多语言开发包、API 云端服务、RAG 知识检索、MCP 协议支持，以及 SKILL 跨语言知识 API。其中 RAG 模块与主流索引框架深度集成，LlamaIndex 正是其中最重要的伙伴之一。

LlamaIndex 是什么

LlamaIndex 是当前最流行的 LLM 数据框架之一，拥有超过 370 万周下载量。它提供数百个数据连接器（Readers），帮助开发者从 Notion、Slack、Google Drive 等各类数据源提取内容，转换为统一的 Document 对象，再经由索引和检索流程注入 LLM 上下文。

llama-index-readers-mineru 是 MinerU 官方维护的 LlamaIndex 连接器。它将 MinerU 的高精度文档解析能力无缝桥接到 LlamaIndex 生态——只需一行代码，即可将 PDF、DOC、PPT、图片等复杂文档转换为结构化的 Markdown，并立即投入 RAG 检索链路。

核心优势：

零门槛接入 LlamaIndex 生态，替换任意现有 Reader 无需改写业务逻辑
继承 MinerU 的高精度版面分析、公式识别和表格提取能力
支持 Flash（免 Token）和 Precision（需 Token）两种解析模式
PDF 可按页拆分，适配需要 page-level 粒度的 RAG 场景
支持本地路径与远程 URL 混合批量加载

安装与环境要求

环境要求

Python >= 3.10
pip 或 uv 包管理器

安装

pip install llama-index-readers-mineru

或使用 uv：

uv add llama-index-readers-mineru

快速上手

一行代码加载 PDF

from llama_index.readers.mineru import MinerUReader

reader = MinerUReader()
documents = reader.load_data("https://cdn-mineru.openxlab.org.cn/demo/example.pdf")

print(documents[0].text[:500])

load_data() 返回一个 List[Document]，每个 Document 的 .text 字段即为 MinerU 解析出的 Markdown 内容，可直接交给后续的索引流程。

两种解析模式对比

特性	Flash（默认）	Precision
身份认证	免登录	需 API Token
速度	极速	标准
文件大小上限	10 MB	200 MB
页数上限	20 页	600 页
支持格式	PDF、图片、DOCX、PPTX、XLS、XLSX	PDF、图片、DOC、DOCX、PPT、PPTX、HTML

注意：当前集成返回内容均为 Markdown 格式。如需图片/JSON/DOCX/HTML/LaTeX 等多元输出，请使用 MinerU Python SDK。

Flash 模式（默认，无需 Token）

from llama_index.readers.mineru import MinerUReader

reader = MinerUReader()
documents = reader.load_data("/path/to/local.pdf")

Precision 模式（需 Token）

Token 可在 MinerU API 管理平台免费申请。

from llama_index.readers.mineru import MinerUReader

reader = MinerUReader(
    mode="precision",
    token="your-api-token",  # 或设置环境变量 MINERU_TOKEN
    language="en",
    pages="1-20",
)

documents = reader.load_data("/path/to/scanned_paper.pdf")

进阶用法

批量加载：本地文件 + URL 混合

from llama_index.readers.mineru import MinerUReader

reader = MinerUReader()
documents = reader.load_data(
    [
        "/path/to/local_a.pdf",
        "/path/to/local_b.docx",
        "https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
    ]
)

for doc in documents:
    print(doc.metadata["source"], "-", doc.text[:100])

PDF 按页拆分（split_pages）

当 split_pages=True 时，每页 PDF 解析为一个独立的 Document，适合需要 page-level 检索粒度的 RAG 场景：

reader = MinerUReader(split_pages=True, pages="1-5")
documents = reader.load_data("/path/to/paper.pdf")

for doc in documents:
    print(f"Page {doc.metadata['page']}: {doc.text[:100]}...")

附加自定义 Metadata

通过 extra_info 向每个 Document 的 metadata 中注入自定义字段（如项目名、租户标识、数据来源类型），不影响解析行为和输出格式：

from llama_index.readers.mineru import MinerUReader

reader = MinerUReader()
documents = reader.load_data(
    "/path/to/paper.pdf",
    extra_info={
        "project": "paper-rag",
        "tenant": "team-a",
        "source_type": "research_pdf",
    },
)

print(documents[0].metadata["project"])      # paper-rag
print(documents[0].metadata["source_type"])  # research_pdf

完整 RAG Pipeline 示例

Flash 模式 + RAG（免 Token，适合快速原型）

from llama_index.readers.mineru import MinerUReader
from llama_index.core import VectorStoreIndex

reader = MinerUReader()
documents = reader.load_data("/path/to/paper.pdf")

index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()

response = query_engine.query("Summarize the key findings")
print(response)

Precision 模式 + RAG（生产环境推荐）

import os
from llama_index.readers.mineru import MinerUReader
from llama_index.core import VectorStoreIndex

os.environ["MINERU_TOKEN"] = "your-token"  # 或直接传入 token 参数

reader = MinerUReader(mode="precision")
documents = reader.load_data("/path/to/manual.pdf")

index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()

response = query_engine.query("How to configure OCR settings?")
print(response)

与 TextSplitter、VectorStore 串联

from llama_index.readers.mineru import MinerUReader
from llama_index.core import VectorStoreIndex
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_openai import OpenAIEmbeddings
from langchain_community.vectorstores import FAISS

# 1. 加载文档
loader = MinerUReader(mode="precision", token="your-token")
docs = loader.load()

# 2. 文本切分
splitter = RecursiveCharacterTextSplitter(chunk_size=1200, chunk_overlap=200)
chunks = splitter.split_documents(docs)

# 3. 向量存储
vs = FAISS.from_documents(chunks, OpenAIEmbeddings())

# 4. 检索
results = vs.similarity_search("What are the core configuration steps?", k=3)
for r in results:
    print(r.page_content[:200])

参数说明

初始化参数

参数	类型	默认值	说明
`mode`	`str`	`"flash"`	解析模式：`"flash"`（快速免 Token）或 `"precision"`（精准需 Token）
`token`	`str \\| None`	`None`	MinerU API Token。precision 模式必填，也可通过 `MINERU_TOKEN` 环境变量提供
`language`	`str`	`"ch"`	文档语言代码，如 `"ch"`（中文）、`"en"`（英文）
`pages`	`str \\| None`	`None`	页码范围，如 `"1-10"`
`timeout`	`int`	`600`	单文件最大等待时间（秒）
`split_pages`	`bool`	`False`	PDF 是否按页拆分为独立 Document
`ocr`	`bool`	`False`	是否强制启用 OCR
`formula`	`bool`	`True`	是否启用公式识别
`table`	`bool`	`True`	是否启用表格识别

load_data 参数

参数	类型	默认值	说明
`sources`	`str \\| Path \\| list[str \\| Path]`	—	单个或多个文件路径/URL
`extra_info`	`dict \\| None`	`None`	自定义 metadata，合并到每个 Document.metadata 中

Document 返回结构

每个返回的 Document 包含以下字段：

字段	说明
`.text`	MinerU 解析出的 Markdown 内容
`.metadata["source"]`	原始文件路径或 URL
`.metadata["page"]`	页码（仅 `split_pages=True` 时存在）
`.metadata["filename"]`	MinerU 返回的原始文件名
`.metadata["loader"]`	固定为 `"mineru"`