LightRAG/docs/mineru_integration_zh.md

MinerU 集成指南

关于 MinerU

MinerU 是一个强大的开源工具，用于从 PDF、图像和 Office 文档中提取高质量的结构化数据。它提供以下功能：

• 保留文档结构（标题、段落、列表等）的文本提取
• 处理包括多列格式在内的复杂布局
• 自动识别并将公式转换为 LaTeX 格式
• 提取图像、表格和脚注
• 自动检测扫描文档并应用 OCR
• 支持多种输出格式（Markdown、JSON）

安装

安装 MinerU 依赖

如果您已经安装了 LightRAG，但没有 MinerU 支持，您可以通过安装 magic-pdf 包来直接添加 MinerU 支持：

pip install "magic-pdf[full]>=1.2.2" huggingface_hub

这些是 LightRAG 所需的 MinerU 相关依赖项。

MinerU 模型权重

MinerU 需要模型权重文件才能正常运行。安装后，您需要下载所需的模型权重。您可以使用 Hugging Face 或 ModelScope 下载模型。

选项 1：从 Hugging Face 下载

pip install huggingface_hub
wget https://github.com/opendatalab/MinerU/raw/master/scripts/download_models_hf.py -O download_models_hf.py
python download_models_hf.py

选项 2：从 ModelScope 下载（推荐中国用户使用）

pip install modelscope
wget https://github.com/opendatalab/MinerU/raw/master/scripts/download_models.py -O download_models.py
python download_models.py

两种方法都会自动下载模型文件并在配置文件中配置模型目录。配置文件位于用户目录中，名为 magic-pdf.json。

Windows 用户注意：用户目录位于 C:\Users\用户名 Linux 用户注意：用户目录位于 /home/用户名 macOS 用户注意：用户目录位于 /Users/用户名

可选：安装 LibreOffice

要处理 Office 文档（DOC、DOCX、PPT、PPTX），您需要安装 LibreOffice：

Linux/macOS：

apt-get/yum/brew install libreoffice

Windows：

1. 安装 LibreOffice
2. 将安装目录添加到 PATH 环境变量：安装目录\LibreOffice\program

使用 MinerU 解析器

基本用法

from lightrag.mineru_parser import MineruParser

# 解析 PDF 文档
content_list, md_content = MineruParser.parse_pdf('path/to/document.pdf', 'output_dir')

# 解析图像
content_list, md_content = MineruParser.parse_image('path/to/image.jpg', 'output_dir')

# 解析 Office 文档
content_list, md_content = MineruParser.parse_office_doc('path/to/document.docx', 'output_dir')

# 自动检测并解析任何支持的文档类型
content_list, md_content = MineruParser.parse_document('path/to/file', 'auto', 'output_dir')

RAGAnything 集成

在 RAGAnything 中，您可以直接使用文件路径作为 process_document_complete 方法的输入来处理文档。以下是一个完整的配置示例：

from lightrag.llm.openai import openai_complete_if_cache, openai_embed
from lightrag.raganything import RAGAnything


# 初始化 RAGAnything
rag = RAGAnything(
    working_dir="./rag_storage",  # 工作目录
    llm_model_func=lambda prompt, system_prompt=None, history_messages=[], **kwargs: openai_complete_if_cache(
        "gpt-4o-mini",  # 使用的模型
        prompt,
        system_prompt=system_prompt,
        history_messages=history_messages,
        api_key="your-api-key",  # 替换为您的 API 密钥
        base_url="your-base-url",  # 替换为您的 API 基础 URL
        **kwargs,
    ),
    vision_model_func=lambda prompt, system_prompt=None, history_messages=[], image_data=None, **kwargs: openai_complete_if_cache(
        "gpt-4o",  # 视觉模型
        "",
        system_prompt=None,
        history_messages=[],
        messages=[
            {"role": "system", "content": system_prompt} if system_prompt else None,
            {"role": "user", "content": [
                {"type": "text", "text": prompt},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{image_data}"
                    }
                }
            ]} if image_data else {"role": "user", "content": prompt}
        ],
        api_key="your-api-key",  # 替换为您的 API 密钥
        base_url="your-base-url",  # 替换为您的 API 基础 URL
        **kwargs,
    ) if image_data else openai_complete_if_cache(
        "gpt-4o-mini",
        prompt,
        system_prompt=system_prompt,
        history_messages=history_messages,
        api_key="your-api-key",  # 替换为您的 API 密钥
        base_url="your-base-url",  # 替换为您的 API 基础 URL
        **kwargs,
    ),
    embedding_func=lambda texts: openai_embed(
        texts,
        model="text-embedding-3-large",
        api_key="your-api-key",  # 替换为您的 API 密钥
        base_url="your-base-url",  # 替换为您的 API 基础 URL
    ),
    embedding_dim=3072,
    max_token_size=8192
)

# 处理单个文件
await rag.process_document_complete(
    file_path="path/to/document.pdf",
    output_dir="./output",
    parse_method="auto"
)

# 查询处理后的文档
result = await rag.query_with_multimodal(
    "What is the main content of the document?",
    mode="hybrid"
)

MinerU 会将文档内容分类为文本、公式、图像和表格，分别使用相应的摄入类型进行处理：

• 文本内容：ingestion_type='text'
• 图像内容：ingestion_type='image'
• 表格内容：ingestion_type='table'
• 公式内容：ingestion_type='equation'

查询示例

以下是一些常见的查询示例：

# 查询文本内容
result = await rag.query_with_multimodal(
    "What is the main topic of the document?",
    mode="hybrid"
)

# 查询图片相关内容
result = await rag.query_with_multimodal(
    "Describe the images and figures in the document",
    mode="hybrid"
)

# 查询表格相关内容
result = await rag.query_with_multimodal(
    "Tell me about the experimental results and data tables",
    mode="hybrid"
)

命令行工具

我们还提供了一个用于文档解析的命令行工具：

python examples/mineru_example.py path/to/document.pdf

可选参数：

• --output 或 -o：指定输出目录
• --method 或 -m：选择解析方法（auto、ocr、txt）
• --stats：显示内容统计信息

输出格式

MinerU 为每个解析的文档生成三个文件：

1. {文件名}.md - 文档的 Markdown 表示
2. {文件名}_content_list.json - 结构化 JSON 内容
3. {文件名}_model.json - 详细的模型解析结果

content_list.json 文件包含从文档中提取的所有结构化内容，包括：

• 文本块（正文、标题等）
• 图像（路径和可选的标题）
• 表格（表格内容和可选的标题）
• 列表
• 公式

疑难解答

如果您在使用 MinerU 时遇到问题：

1. 检查模型权重是否正确下载
2. 确保有足够的内存（建议 16GB+）
3. 对于 CUDA 加速问题，请参阅 MinerU 文档
4. 如果解析 Office 文档失败，请验证 LibreOffice 是否正确安装
5. 如果遇到 pickle.UnpicklingError: invalid load key, 'v'.，可能是因为模型下载不完整。尝试重新下载模型。
6. 对于使用较新显卡（H100 等）并出现 OCR 文本乱码的用户，请尝试升级 Paddle 使用的 CUDA 版本：

   pip install paddlepaddle-gpu==3.0.0b1 -i https://www.paddlepaddle.org.cn/packages/stable/cu123/
   

7. 如果遇到 "文件名太长" 错误，最新版本的 MineruParser 已经包含了自动处理此问题的逻辑。

更新现有模型

如果您之前已经下载了模型并需要更新它们，只需再次运行下载脚本即可。脚本将更新模型目录到最新版本。

高级配置

MinerU 配置文件 magic-pdf.json 支持多种自定义选项，包括：

• 模型目录路径
• OCR 引擎选择
• GPU 加速设置
• 缓存设置

有关完整的配置选项，请参阅 MinerU 官方文档。