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"

---

相关链接

• MinerU 官网：https://mineru.net
• LlamaIndex 官网：https://www.llamaindex.ai
• MinerU Python SDK：https://github.com/opendatalab/MinerU-Ecosystem/tree/main/sdk/python
• API 文档：https://mineru.net/apiManage/docs
• Token 申请：https://mineru.net/apiManage/token
• GitHub Stars：56.9K+