RAG-Anything 深度实战：港大开源全模态 RAG 框架，让知识库真正「看懂」图片、表格和公式

当传统 RAG 遇到多模态文档

如果你做过企业级 RAG 系统，一定踩过这个坑：PDF 文档里的图表、公式、表格全部变成了乱码或空白，知识库查出来的内容永远只有纯文本部分。一份 50 页的技术报告，真正有价值的架构图、性能对比表、数学推导公式，传统 RAG 全部视而不见。

这不是小问题。现实世界的文档从来就不是纯文本——学术论文有公式和实验图表，金融报告有数据表格和趋势图，技术文档有架构图和代码流程图，医疗文献有影像和诊断表格。据统计，专业文档中非文本内容占比通常超过 40%，而传统 RAG 对这 40% 的信息几乎完全丢失。

2025 年，香港大学数据科学实验室（HKUDS）开源了 RAG-Anything——一个基于 LightRAG 构建的全模态 RAG 框架，GitHub 星标迅速突破 17000+，登顶多周 Trending 榜单。它不是又一个 RAG 封装库，而是从架构层面重新设计了多模态文档的理解、索引和检索流程。

本文将从架构设计、核心模块、代码实战到性能优化，完整拆解 RAG-Anything，帮你搞清楚它到底怎么做到「看懂」一切。

一、核心问题：为什么传统 RAG 处理不了多模态

1.1 传统 RAG 的文本幻觉

传统 RAG 的工作流程很简单：

文档 → 纯文本提取 → 分块(Chunking) → 向量化 → 向量数据库
                                                         ↓
用户查询 → 向量化 → 相似度检索 → 拼接上下文 → LLM 生成回答

这个流程的前提假设是：文档内容都是文本。但现实世界不是这样的。

一份典型的技术 PDF 可能包含：

• 文字段落：描述系统设计和实现细节
• 架构图：展示组件间调用关系
• 性能对比表：不同方法的精度和速度对比
• 数学公式：损失函数、梯度推导
• 代码片段：算法实现

传统 RAG 用 PyPDF2 或 pdfplumber 提取文本时，这些非文本内容要么被丢弃，要么变成乱码。更关键的是，即使你用 OCR 把图片转成了文字，也丢失了视觉语义——一张架构图的信息密度远超几行 OCR 文字。

1.2 多模态 RAG 的三大挑战

要让 RAG 真正理解多模态文档，需要解决三个核心问题：

挑战一：内容分离与保真

文档中的文本、图片、表格、公式是交织在一起的。一个段落引用了「如图 3 所示」，图 3 就在段落下方。传统提取方式会把这段关系打断——文本分块到 chunk A，图片被丢弃或分块到 chunk B，上下文关系完全丢失。

挑战二：跨模态语义对齐

用户问「这个模型的准确率是多少」，答案可能在一张表格里。传统文本检索根本无法匹配这种跨模态查询——文本嵌入模型无法理解表格的视觉结构，也无法把「准确率」这个文本查询映射到表格的行列交叉点。

挑战三：结构化知识表示

图片和表格不是孤立的信息点，它们之间有语义关系。一张架构图描述了 A 调用 B，一个表格列出了 B 的性能指标，一段文字解释了为什么 A 选择调用 B。这些跨模态的语义关联需要被显式建模，而不是简单地拼在一起。

RAG-Anything 就是为了系统性地解决这三个问题而设计的。

二、架构设计：从文档到知识的全链路

2.1 四阶段流水线

RAG-Anything 的核心架构是一个四阶段流水线：

📄 Document Parsing → 🧠 Content Analysis → 🔗 Knowledge Graph → 🎯 Intelligent Retrieval

每一阶段都有专门的多模态处理逻辑，不是简单地把 OCR 结果拼进文本流。

2.2 阶段一：文档解析（Document Parsing）

文档解析是整个系统的入口，RAG-Anything 集成了 MinerU 作为核心解析引擎。MinerU 是上海人工智能实验室开源的高保真文档结构提取工具，它不是简单的 OCR，而是能理解文档版面结构的智能解析器。

关键能力：

• 版面分析：识别文档中的标题、正文、图片区域、表格区域、公式区域，保持原始布局
• 阅读顺序还原：多栏排版、插入表格、浮动图片等复杂版面的正确阅读顺序
• 高保真提取：公式保留 LaTeX 源码，表格保留行列结构，图片保留原始分辨率

# RAG-Anything 的配置中指定解析器
from raganything import RAGAnything, RAGAnythingConfig

config = RAGAnythingConfig(
    working_dir="./rag_storage",
    parser="mineru",           # 解析器选择：mineru, docling, paddleocr
    parse_method="auto",       # 解析方法：auto, ocr, txt
    enable_image_processing=True,
    enable_table_processing=True,
    enable_equation_processing=True,
)

parse_method 的选择策略：

2.3 阶段二：内容分析（Content Analysis）

这是 RAG-Anything 的核心创新——模态感知处理流水线（Modality-Aware Processing Pipeline）。

解析后的文档被分解为不同类型的内容元素，每个元素根据其模态被路由到专门的分析器：

文档内容 → 内容分类器
              ├── 文本块 → 文本处理器（语义标注）
              ├── 图片 → 视觉内容分析器（VLM 描述 + 空间关系提取）
              ├── 表格 → 结构化数据解释器（统计模式识别 + 语义关系提取）
              ├── 公式 → 数学表达式解析器（LaTeX 解析 + 概念映射）
              └── 自定义 → 可扩展模态处理器（插件架构）

视觉内容分析器的工作流程：

1. 用视觉语言模型（VLM，如 GPT-4o）对图片生成上下文感知的描述性标题
2. 提取图片中的空间关系和层次结构
3. 将图片描述与其所在文档段落建立语义关联

结构化数据解释器的工作流程：

1. 解析表格的行列结构，识别表头、数据区域
2. 执行统计模式识别——发现数据趋势（上升、下降、异常值）
3. 识别多个表格之间的语义关系和依赖

数学表达式解析器的工作流程：

1. 解析 LaTeX 公式，识别变量、运算符、函数
2. 将公式中的变量映射到文档上下文中的概念
3. 建立公式与其物理含义的语义连接

看一段实际的处理代码：

from raganything.modalprocessors import ImageModalProcessor, TableModalProcessor

# 初始化图片处理器
image_processor = ImageModalProcessor(
    lightrag=rag,
    modal_caption_func=vision_model_func  # VLM 模型函数
)

# 处理一张图片
image_content = {
    "img_path": "path/to/architecture_diagram.jpg",
    "image_caption": ["Figure 1: System Architecture Overview"],
    "image_footnote": ["Microservices design with API Gateway"]
}

description, entity_info = await image_processor.process_multimodal_content(
    modal_content=image_content,
    content_type="image",
    file_path="system_design_doc.pdf",
    entity_name="System Architecture Diagram"
)

description 会包含 VLM 对图片的深度理解——不仅是「这是一张架构图」，而是「该系统采用微服务架构，API Gateway 作为统一入口，下游连接用户服务、订单服务和支付服务，服务间通过 gRPC 通信」。

entity_info 则将图片转化为知识图谱实体，可以与其他实体（文本段落、表格数据）建立语义关系。

2.4 阶段三：多模态知识图谱（Knowledge Graph）

这是 RAG-Anything 区别于所有其他 RAG 框架的关键——它不是把多模态内容简单拼接后做向量检索，而是构建了一个跨模态知识图谱。

知识图谱的构建包括四个核心操作：

1. 多模态实体提取

将文档中的每个重要多模态元素转化为知识图谱实体。例如：

Entity: "System Architecture Diagram"
  - Type: image
  - Description: "微服务架构，API Gateway 统一入口..."
  - Source: system_design_doc.pdf, Page 3
  - Metadata: {format: "jpg", resolution: "1920x1080"}

Entity: "Performance Comparison Table"
  - Type: table
  - Description: "对比了三种方法的准确率和推理速度..."
  - Source: system_design_doc.pdf, Page 5
  - Metadata: {rows: 8, cols: 4}

2. 跨模态关系映射

建立不同模态实体之间的语义连接。例如：

(System Architecture Diagram) --[illustrates]--> (Microservice Design Section)
(Performance Comparison Table) --[evaluates]--> (System Architecture Diagram)
(Loss Function Formula) --[optimizes]--> (Training Algorithm Section)

3. 层次结构保持

保持原始文档的组织结构，通过 belongs_to 关系链：

(Section 3.2) --[belongs_to]--> (Chapter 3)
(Figure 3.1) --[belongs_to]--> (Section 3.2)
(Table 3.1) --[belongs_to]--> (Section 3.2)

这保证了检索时能恢复文档的上下文层次，而不是返回孤立的碎片。

4. 加权关系评分

不同类型的关系有不同的重要性权重。illustrates（图示说明）比 belongs_to（属于）在语义检索中的权重更高，因为它直接反映了两个实体间的语义关联。

2.5 阶段四：智能检索（Intelligent Retrieval）

RAG-Anything 的检索系统融合了三种检索机制：

向量-图融合检索（Vector-Graph Fusion）

用户查询 → 文本向量化 → 向量相似度搜索（找到语义相关实体）
                      ↓
         同时 → 图遍历搜索（沿关系边发现关联实体）
                      ↓
              合并去重 → 排序 → 返回结果

纯向量检索能找到语义相似的文本，但无法发现跨模态的隐式关联。纯图遍历能发现结构关系，但覆盖面有限。两者融合才能既保证语义相关性，又保持结构完整性。

模态感知排序（Modality-Aware Ranking）

系统会根据查询意图自动调整不同模态结果的权重。例如：

• 查询「系统的架构是什么」→ 提升图片类型实体的排序权重
• 查询「模型准确率是多少」→ 提升表格类型实体的排序权重
• 查询「损失函数怎么推导」→ 提升公式类型实体的排序权重

关系一致性维护（Relational Coherence Maintenance）

检索结果不是返回孤立的实体，而是维护实体间的关系。如果返回了一张架构图，同时也会返回描述该架构的文字段落和评估其性能的表格数据，确保返回的信息是上下文完整的。

三、代码实战：从零构建多模态知识库

3.1 环境搭建

# 基础安装
pip install raganything

# 完整安装（包含所有可选依赖）
pip install 'raganything[all]'

# 或者用 uv 管理虚拟环境（推荐）
git clone https://github.com/HKUDS/RAG-Anything.git
cd RAG-Anything
uv sync

如果需要处理 Office 文档，还需要安装 LibreOffice：

# macOS
brew install --cask libreoffice

# Ubuntu/Debian
sudo apt-get install libreoffice

# 验证 MinerU 安装
mineru --version

3.2 完整的初始化与配置

import asyncio
from raganything import RAGAnything, RAGAnythingConfig
from lightrag.llm.openai import openai_complete_if_cache, openai_embed
from lightrag.utils import EmbeddingFunc

async def main():
    # API 配置
    api_key = "your-api-key"
    base_url = "https://api.openai.com/v1"  # 或你的代理地址

    # 创建配置
    config = RAGAnythingConfig(
        working_dir="./rag_storage",
        parser="mineru",
        parse_method="auto",
        enable_image_processing=True,    # 启用图片处理
        enable_table_processing=True,    # 启用表格处理
        enable_equation_processing=True, # 启用公式处理
    )

    # LLM 模型函数
    def llm_model_func(prompt, system_prompt=None, history_messages=[], **kwargs):
        return openai_complete_if_cache(
            "gpt-4o-mini",
            prompt,
            system_prompt=system_prompt,
            history_messages=history_messages,
            api_key=api_key,
            base_url=base_url,
            **kwargs,
        )

    # 视觉模型函数（用于图片理解和 VLM 增强查询）
    def vision_model_func(
        prompt, system_prompt=None, history_messages=[],
        image_data=None, messages=None, **kwargs
    ):
        # VLM 增强查询模式：直接使用 messages 格式
        if messages:
            return openai_complete_if_cache(
                "gpt-4o",
                "",
                system_prompt=None,
                history_messages=[],
                messages=messages,
                api_key=api_key,
                base_url=base_url,
                **kwargs,
            )
        # 单图片模式
        elif image_data:
            return 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=api_key,
                base_url=base_url,
                **kwargs,
            )
        else:
            return llm_model_func(prompt, system_prompt, history_messages, **kwargs)

    # 嵌入函数
    embedding_func = EmbeddingFunc(
        embedding_dim=3072,
        max_token_size=8192,
        func=lambda texts: openai_embed.func(
            texts,
            model="text-embedding-3-large",
            api_key=api_key,
            base_url=base_url,
        ),
    )

    # 初始化 RAG-Anything
    rag = RAGAnything(
        config=config,
        llm_model_func=llm_model_func,
        vision_model_func=vision_model_func,
        embedding_func=embedding_func,
    )

    # 处理单个文档
    await rag.process_document_complete(
        file_path="./documents/technical_report.pdf",
        output_dir="./output",
        parse_method="auto"
    )

    # 批量处理文件夹
    await rag.process_folder_complete(
        folder_path="./documents",
        output_dir="./output",
        file_extensions=[".pdf", ".docx", ".pptx"],
        recursive=True,
        max_workers=4  # 并行处理数
    )

if __name__ == "__main__":
    asyncio.run(main())

3.3 多模态查询的三种模式

RAG-Anything 支持三种查询方式，覆盖不同场景：

模式一：纯文本查询

最基本的查询方式，类似传统 RAG，但检索范围覆盖了所有模态的知识图谱实体：

# 四种检索模式
result_hybrid = await rag.aquery("系统的架构设计是什么？", mode="hybrid")
result_local = await rag.aquery("系统的架构设计是什么？", mode="local")
result_global = await rag.aquery("系统的架构设计是什么？", mode="global")
result_naive = await rag.aquery("系统的架构设计是什么？", mode="naive")

四种模式的区别：

模式二：VLM 增强查询

这是 RAG-Anything 的一大亮点——检索到包含图片的结果后，自动调用 VLM 对图片进行视觉分析：

# VLM 增强查询（配置了 vision_model_func 后自动启用）
vlm_result = await rag.aquery(
    "文档中的架构图展示了什么设计模式？",
    mode="hybrid"
    # vlm_enhanced=True 已自动设置
)

# 手动控制 VLM 增强
vlm_enabled = await rag.aquery(
    "这些图表说明了什么趋势？",
    mode="hybrid",
    vlm_enhanced=True  # 强制启用
)

# 禁用 VLM 增强（省 token）
text_only = await rag.aquery(
    "项目的背景和目标是什么？",
    mode="hybrid",
    vlm_enhanced=False
)

VLM 增强的工作原理：

用户查询 → 检索到包含图片的知识图谱实体
                              ↓
         提取图片数据 + 周围文本上下文
                              ↓
         构造多模态 prompt → VLM 分析图片内容
                              ↓
         VLM 输出（图片理解） + 原始检索结果 → 合并生成最终答案

这意味着你不需要单独调用图片理解 API，系统会自动识别检索结果中包含的图片并调用 VLM 进行深度分析。

模式三：多模态内容查询

最强大的查询方式——用户可以在查询中直接携带多模态内容：

# 携带公式进行查询
multimodal_result = await rag.aquery_with_multimodal(
    "解释这个公式与文档内容的关系",
    multimodal_content=[{
        "type": "equation",
        "latex": "P(d|q) = \\frac{P(q|d) \\cdot P(d)}{P(q)}",
        "equation_caption": "文档相关性概率"
    }],
    mode="hybrid"
)

# 携带图片进行查询
image_result = await rag.aquery_with_multimodal(
    "这个图表与文档中哪个部分相关？",
    multimodal_content=[{
        "type": "image",
        "image_url": "https://example.com/chart.png",
        "image_caption": "用户上传的参考图表"
    }],
    mode="hybrid"
)

这个功能在学术研究场景特别有用——你可以拿一个公式去问「这个公式在文档中的变体是什么」，或者拿一张图去问「文档中有没有类似的架构设计」。

四、自定义模态处理器：扩展 RAG-Anything 的能力边界

RAG-Anything 内置了图片、表格、公式三种模态处理器，但它的架构是可扩展的。你可以通过继承 GenericModalProcessor 来添加自定义模态的处理逻辑。

4.1 实战：添加代码片段处理器

假设你的文档包含大量代码片段，你希望 RAG 能理解代码的语义和功能，而不仅仅是把它当文本处理：

from raganything.modalprocessors import GenericModalProcessor
import ast

class CodeModalProcessor(GenericModalProcessor):
    """代码片段专用处理器：解析代码语义并建立与文档概念的映射"""

    async def process_multimodal_content(
        self, modal_content, content_type, file_path, entity_name
    ):
        code_text = modal_content.get("code_body", "")
        language = modal_content.get("language", "python")
        caption = modal_content.get("code_caption", [""])[0]

        # 步骤1：用 LLM 分析代码功能
        code_analysis = await self._analyze_code_semantics(
            code_text, language, caption
        )

        # 步骤2：提取代码结构信息
        code_structure = self._extract_code_structure(code_text, language)

        # 步骤3：构建增强描述
        enhanced_description = self._build_enhanced_description(
            code_analysis, code_structure, caption
        )

        # 步骤4：创建知识图谱实体
        entity_info = {
            "entity_name": entity_name,
            "type": "code",
            "language": language,
            "functions": code_structure.get("functions", []),
            "classes": code_structure.get("classes", []),
            "imports": code_structure.get("imports", []),
            "description": enhanced_description,
        }

        return await self._create_entity_and_chunk(
            enhanced_description, entity_info, file_path
        )

    async def _analyze_code_semantics(self, code, language, caption):
        """用 LLM 理解代码的功能和意图"""
        prompt = f"""Analyze this {language} code snippet:
- Caption: {caption}
- Code:

{code}

Provide:
1. Functional description (what it does)
2. Key algorithms or patterns used
3. Dependencies and interfaces
4. Performance characteristics"""

        return await self.modal_caption_func(prompt)

    def _extract_code_structure(self, code, language):
        """提取代码的结构信息（函数、类、导入等）"""
        structure = {"functions": [], "classes": [], "imports": []}

        if language == "python":
            try:
                tree = ast.parse(code)
                for node in ast.walk(tree):
                    if isinstance(node, ast.FunctionDef):
                        args = [arg.arg for arg in node.args.args]
                        structure["functions"].append({
                            "name": node.name,
                            "args": args,
                            "line": node.lineno
                        })
                    elif isinstance(node, ast.ClassDef):
                        methods = [
                            n.name for n in node.body
                            if isinstance(n, ast.FunctionDef)
                        ]
                        structure["classes"].append({
                            "name": node.name,
                            "methods": methods
                        })
            except SyntaxError:
                pass

        return structure

    def _build_enhanced_description(self, analysis, structure, caption):
        """构建增强的代码描述"""
        desc_parts = [f"Code: {caption}"]

        if structure["functions"]:
            func_names = [f["name"] for f in structure["functions"]]
            desc_parts.append(f"Functions: {', '.join(func_names)}")

        if structure["classes"]:
            class_names = [c["name"] for c in structure["classes"]]
            desc_parts.append(f"Classes: {', '.join(class_names)}")

        desc_parts.append(f"Analysis: {analysis}")

        return "\n".join(desc_parts)

4.2 注册自定义处理器

# 在 RAGAnything 初始化后注册自定义处理器
rag = RAGAnything(
    config=config,
    llm_model_func=llm_model_func,
    vision_model_func=vision_model_func,
    embedding_func=embedding_func,
)

# 注册代码处理器
code_processor = CodeModalProcessor(
    lightrag=rag.lightrag,
    modal_caption_func=llm_model_func
)
rag.register_modal_processor("code", code_processor)

这种插件式的架构设计意味着 RAG-Anything 的能力边界可以无限扩展——音频、视频、3D 模型，只要你能写出对应的模态处理器，就能接入系统。

五、知识图谱构建的深层原理

5.1 实体提取的 Prompt 工程

RAG-Anything 的知识图谱构建依赖于精心设计的 Prompt。以图片实体提取为例，VLM 收到的 Prompt 大致如下：

You are analyzing an image from a technical document.

Image Caption: {caption}
Image Footnote: {footnote}
Surrounding Text Context: {context}

Please provide:
1. A detailed description of what this image shows
2. Key entities and their relationships visible in the image
3. How this image relates to the document content
4. Any data, trends, or patterns visible

Format your response as structured JSON.

这个 Prompt 设计的关键点在于：

• 提供了上下文：告诉 VLM 图片在文档中的位置和周围文本
• 要求结构化输出：不是随意描述，而是按实体-关系格式输出
• 强调关联性：强制要求分析图片与文档内容的语义联系

5.2 跨模态关系推理

知识图谱的边不是简单的共现关系，而是通过 LLM 推理得到的语义关系。系统会对每一对实体提问：

Entity A: [图片] 系统架构图 - 微服务设计，API Gateway 统一入口
Entity B: [文本] 3.2节 系统设计原则 - 采用微服务架构实现服务解耦

Question: What is the semantic relationship between these two entities?
Options: illustrates, elaborates, contradicts, references, evaluates

LLM 会判断这是一对 illustrates（图示说明）关系，权重较高。

5.3 社区检测与层次聚合

构建完知识图谱后，RAG-Anything 继承了 LightRAG 的社区检测算法，将图谱中的节点聚合成社区（Community），形成层次结构：

Level 0: 原始实体（图片、表格、公式、文本段落）
Level 1: 紧密相关的实体组成社区（同一节的内容）
Level 2: 社区聚合为更大的社区（同一章的内容）
Level 3: 顶层社区（整个文档的主题）

这个层次结构让 global 模式的查询能够快速定位到文档的高层概览，而不需要遍历所有底层实体。

六、性能优化实战

6.1 文档解析优化

MinerU 的解析是整个流水线中最耗时的步骤。几个关键优化：

1. 解析方法选择

# 对于纯文本 PDF，使用 txt 模式，速度提升 5-10 倍
config = RAGAnythingConfig(
    parser="mineru",
    parse_method="txt",  # 跳过 OCR，直接提取文本
)

# 对于混合内容 PDF，使用 auto，自动判断每页是否需要 OCR
config = RAGAnythingConfig(
    parser="mineru",
    parse_method="auto",  # 智能判断，平衡速度和精度
)

2. 批量处理并行度

# 根据机器内存和 CPU 核数调整并行度
await rag.process_folder_complete(
    folder_path="./documents",
    output_dir="./output",
    max_workers=8,  # 默认 4，8核机器可以设为 8
)

3. 解析结果缓存

MinerU 的解析结果可以缓存到磁盘，避免重复解析：

# processed_document 的输出目录就是缓存
# 重复运行时会检查 output_dir 中是否已有解析结果
await rag.process_document_complete(
    file_path="./documents/report.pdf",
    output_dir="./output",  # 已有结果则跳过解析
    parse_method="auto"
)

6.2 VLM 调用优化

VLM（如 GPT-4o）的调用是第二大瓶颈。每个图片都需要一次 VLM 调用来生成描述，如果文档有 50 张图片，就是 50 次 API 调用。

1. 批量图片描述

# 自定义 vision_model_func，实现批量处理
async def batch_vision_model_func(images_and_prompts):
    """将多个图片的描述请求合并为一次 API 调用"""
    messages = []
    for img_data, prompt in images_and_prompts:
        messages.append({
            "role": "user",
            "content": [
                {"type": "text", "text": prompt},
                {"type": "image_url", "image_url": {
                    "url": f"data:image/jpeg;base64,{img_data}"
                }},
            ],
        })

    # 一次性发送所有图片
    return await openai_complete_if_cache(
        "gpt-4o", "", messages=messages, ...
    )

2. 条件性 VLM 增强

不是所有查询都需要 VLM 增强。如果查询明显是纯文本性质的（如「项目背景是什么」），可以跳过 VLM：

# 智能判断是否需要 VLM
def should_enable_vlm(query: str) -> bool:
    vlm_keywords = ["图", "图表", "架构", "流程", "展示", "可视化",
                    "chart", "diagram", "figure", "image", "visual"]
    return any(kw in query.lower() for kw in vlm_keywords)

result = await rag.aquery(
    query,
    mode="hybrid",
    vlm_enhanced=should_enable_vlm(query)
)

6.3 知识图谱存储优化

LightRAG 默认使用文件系统存储知识图谱，适合小规模场景。大规模部署时需要优化存储：

1. 向量数据库选择

# LightRAG 支持 NanoVectorDB（默认）和外部向量数据库
# 对于大规模数据，建议使用 Qdrant 或 Milvus
from lightrag.kg.shared_storage import initialize_pipeline_storage

# 配置 Qdrant 作为向量存储
storage_config = {
    "vector_storage": "qdrant",
    "qdrant_url": "localhost:6333",
    "qdrant_collection": "rag_anything",
}

2. 图数据分区

对于超大规模文档集（百万级实体），按主题或时间分区知识图谱：

# 按主题分区处理
topics = ["机器学习", "数据库", "前端框架", "云原生"]

for topic in topics:
    topic_config = RAGAnythingConfig(
        working_dir=f"./rag_storage/{topic}",
        parser="mineru",
        parse_method="auto",
        enable_image_processing=True,
        enable_table_processing=True,
        enable_equation_processing=True,
    )
    # 每个主题独立的知识图谱
    topic_rag = RAGAnything(config=topic_config, ...)
    await topic_rag.process_folder_complete(
        folder_path=f"./documents/{topic}",
        output_dir=f"./output/{topic}",
    )

6.4 成本估算与控制

以一份 100 页的混合内容技术文档为例，处理成本的估算：

关键结论：首次入库成本约 ¥0.8/100 页，后续查询成本极低（¥0.01/次）。VLM 调用是主要成本来源，约占总成本的 75%。

七、与主流 RAG 框架的对比

7.1 核心差异

7.2 选型建议

• 学术论文 / 技术文档场景：RAG-Anything 是目前最佳选择，公式和图表的原生支持无可替代
• 通用企业知识库：如果文档主要是纯文本（合同、制度、FAQ），LlamaIndex 或 RAGFlow 更轻量
• 高度定制化场景：LangChain 的灵活性更高，但多模态能力需要自己搭建
• 已有 LightRAG 项目：RAG-Anything 是 LightRAG 的超集，可以直接升级

八、生产环境部署指南

8.1 Docker 部署

FROM python:3.11-slim

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    libreoffice \
    poppler-utils \
    && rm -rf /var/lib/apt/lists/*

# 安装 RAG-Anything
RUN pip install 'raganything[all]'

# 复制配置
COPY config.py /app/config.py
WORKDIR /app

# 启动 API 服务
CMD ["python", "-m", "raganything.server", "--host", "0.0.0.0", "--port", "8000"]

8.2 API 封装

将 RAG-Anything 封装为 REST API，方便前端调用：

from fastapi import FastAPI, UploadFile, File, Query as QueryParam
from fastapi.responses import JSONResponse
import asyncio

app = FastAPI(title="RAG-Anything API")

# 全局 RAG 实例（启动时初始化）
rag_instance = None

@app.on_event("startup")
async def startup():
    global rag_instance
    rag_instance = RAGAnything(
        config=RAGAnythingConfig(
            working_dir="./rag_storage",
            parser="mineru",
            parse_method="auto",
            enable_image_processing=True,
            enable_table_processing=True,
            enable_equation_processing=True,
        ),
        llm_model_func=llm_model_func,
        vision_model_func=vision_model_func,
        embedding_func=embedding_func,
    )

@app.post("/documents/upload")
async def upload_document(file: UploadFile = File(...)):
    """上传并处理文档"""
    file_path = f"./uploads/{file.filename}"
    with open(file_path, "wb") as f:
        content = await file.read()
        f.write(content)

    # 异步处理文档
    await rag_instance.process_document_complete(
        file_path=file_path,
        output_dir="./output",
    )

    return {"status": "processed", "filename": file.filename}

@app.get("/query")
async def query(
    q: str = QueryParam(..., description="查询内容"),
    mode: str = QueryParam("hybrid", description="检索模式"),
    vlm_enhanced: bool = QueryParam(True, description="是否启用VLM增强")
):
    """查询知识库"""
    result = await rag_instance.aquery(
        q, mode=mode, vlm_enhanced=vlm_enhanced
    )
    return {"query": q, "result": result}

@app.post("/query/multimodal")
async def multimodal_query(
    q: str = QueryParam(..., description="查询内容"),
    content_type: str = QueryParam("equation", description="模态类型"),
    content: str = QueryParam(..., description="多模态内容"),
    mode: str = QueryParam("hybrid", description="检索模式")
):
    """多模态内容查询"""
    multimodal_content = []
    if content_type == "equation":
        multimodal_content.append({
            "type": "equation",
            "latex": content,
        })

    result = await rag_instance.aquery_with_multimodal(
        q, multimodal_content=multimodal_content, mode=mode
    )
    return {"query": q, "type": content_type, "result": result}

8.3 监控与可观测性

import time
import logging
from functools import wraps

logger = logging.getLogger("rag-anything")

def monitor_rag_operation(func):
    """装饰器：监控 RAG 操作的耗时和 token 使用"""
    @wraps(func)
    async def wrapper(*args, **kwargs):
        start_time = time.time()
        try:
            result = await func(*args, **kwargs)
            duration = time.time() - start_time
            logger.info(
                f"{func.__name__} completed in {duration:.2f}s"
            )
            return result
        except Exception as e:
            duration = time.time() - start_time
            logger.error(
                f"{func.__name__} failed after {duration:.2f}s: {e}"
            )
            raise

    return wrapper

# 应用监控装饰器
rag.aquery = monitor_rag_operation(rag.aquery)
rag.process_document_complete = monitor_rag_operation(rag.process_document_complete)

九、踩坑记录与最佳实践

9.1 常见坑与解决方案

坑1：MinerU 安装失败

MinerU 依赖 PaddlePaddle，在某些环境下安装会出错。

# 推荐使用 uv 安装，自动解决依赖冲突
UV_HTTP_TIMEOUT=120 uv sync

# 如果仍然失败，可以单独安装 PaddlePaddle
pip install paddlepaddle  # CPU 版本
pip install paddlepaddle-gpu  # GPU 版本

坑2：大文档处理 OOM

处理 200+ 页的大型 PDF 时，MinerU 可能占用大量内存。

# 解决方案：分页处理
from raganything.utils import split_pdf

# 将大 PDF 拆分为小段
split_pdf("large_report.pdf", pages_per_chunk=50, output_dir="./chunks")

# 逐段处理
for chunk_file in sorted(Path("./chunks").glob("chunk_*.pdf")):
    await rag.process_document_complete(
        file_path=str(chunk_file),
        output_dir="./output",
    )

坑3：VLM 调用超时

处理高清图片时，GPT-4o 的响应可能超过 30 秒。

# 解决方案：压缩图片分辨率 + 增加超时
import httpx

# 配置更长的超时
def vision_model_func_with_timeout(prompt, ..., **kwargs):
    return openai_complete_if_cache(
        "gpt-4o",
        prompt,
        timeout=httpx.Timeout(60.0, connect=10.0),  # 60秒超时
        **kwargs,
    )

9.2 最佳实践

1. 先小后大：先用 10 页的样本文档跑通全流程，再处理完整文档
2. 分离解析和查询：解析是一次性工作，建议离线完成；查询是在线服务
3. 缓存为王：MinerU 解析结果、VLM 描述、知识图谱构建结果都要缓存
4. 成本控制：对于不需要视觉理解的文档，关闭 enable_image_processing 和 VLM 增强
5. 持续更新：文档更新时，用增量模式处理，避免全量重建知识图谱

十、未来展望

RAG-Anything 代表了 RAG 技术从「文本检索」向「全模态理解」的范式转换。从目前的架构演进趋势来看，几个值得关注的方向：

1. 流式多模态理解

当前系统是先解析后查询的两阶段流程，未来可能发展为实时流式处理——边解析边建图边支持查询，缩短文档入库的时间延迟。

2. 更细粒度的模态处理

当前对图片的处理粒度是「整张图片」，未来可能支持图片内部区域级别的理解和索引——比如对架构图中的每个组件单独建模。

3. 多文档跨模态关联

当前的知识图谱是文档级别的，未来可能支持跨文档的多模态关联——A 文档的架构图与 B 文档的性能表格建立关联。

4. 端侧多模态 RAG

随着小模型能力提升，在本地设备上运行多模态 RAG 成为可能。RAG-Anything 的架构已经为此预留了扩展点——自定义模态处理器可以接入本地 VLM（如 LLaVA、Qwen-VL 的量化版本）。

总结

RAG-Anything 解决的不是「RAG 能不能搜到文档」的问题，而是「RAG 能不能理解文档」的问题。它的核心贡献在于：

1. 模态感知流水线：从架构层面支持多种内容类型的并行处理
2. 跨模态知识图谱：将不同模态的信息统一建模为语义关联的图谱结构
3. VLM 增强检索：自动调用视觉模型理解检索到的图片内容
4. 可扩展架构：插件式的模态处理器，能力边界可无限扩展

如果你正在构建一个需要处理复杂文档的企业知识库，RAG-Anything 值得认真评估。它不是万能药——对于纯文本场景它比 LlamaIndex 重，对于简单 QA 它比 LangChain 复杂——但在多模态文档理解这个垂直领域，它目前是最完整的开源方案。

项目地址：https://github.com/HKUDS/RAG-Anything

技术论文：https://arxiv.org/abs/2510.12323