RAG-Anything 深度使用报告

你有没有遇到过这种崩溃时刻：把一份 PDF 文档喂给 RAG 系统，问它"图 3 里那条曲线说明了什么"——结果它一脸茫然，因为它根本看不见图片？

这不是个例，这是传统 RAG 的结构性缺陷。

现有的绝大多数 RAG 框架，骨子里还是纯文本系统。图片？强行 OCR 成文字，空间关系全丢。表格？压成一行行文本，结构语义消失。公式？LaTeX 原样扔进向量库，根本没人能理解。

于是你的"知识库"变成了一个文字博物馆——里面展示的只是原始文档的一个残缺影子。

RAG-Anything 要解决的，就是这个根本性的问题。

它来自香港大学数据智能实验室（HKUDS）——同一个团队此前发布的 LightRAG 已经在 GitHub 斩获超过 5 万 Star。这次，他们在 LightRAG 的图谱引擎上，完整地架起了多模态理解层。

目前 GitHub Star 数已突破 15,100+，Fork 数 1,800+，arXiv 论文同步发布，在长文档多模态基准测试上全面领先 GPT-4o-mini、LightRAG、MMGraphRAG 等主流方案。

? 它到底解决了什么问题？先搞清楚本质

在我动手装之前，我花了一个小时读完它的论文（arXiv: 2510.12323）。把核心逻辑提炼出来只有一句话：

RAG-Anything 把多模态内容（图片、表格、公式）升格为知识图谱中的一等公民，而不是把它们降维成文字的附属品。

传统 RAG 的处理链是这样的：

文档 → 文字提取 → 向量化 → 向量检索 → 生成回答
（图片/表格/公式 → 强行转文字 → 信息大量损失）

RAG-Anything 的处理链是这样的：

文档 → MinerU 高精度解析 → 各模态专用处理器 → 多模态知识图谱 → 跨模态混合检索 → 生成回答
（图片→VLM理解→图谱实体；表格→结构语义解析→图谱实体；公式→LaTeX解析→图谱实体）

关键差异在两个地方：

① 双图谱构建：系统同时构建"跨模态知识图谱"（以非文字内容为锚点）和"文本知识图谱"（传统实体关系），然后通过实体对齐把两者统一。这意味着一张实验结果图和正文里的描述段落，会在图谱层面被关联起来——就像人类读论文时自然会做的那样。

② 混合检索：查询时，图谱多跳推理（结构导航）+ 向量相似度（语义匹配）双路并行，最后融合排序。这让系统既能找到"这张图在第 3 页，描述了 X 方法在 Y 数据集上的结果"，也能理解"X 方法的核心思想是什么"。

在 DocBench 基准上，对于超过 100 页的长文档，RAG-Anything 的准确率达到 68.2%，而对比方法只有 54.6%，差距超过 13 个百分点。文档越长、多模态内容越密集，优势越显著。

? 从零开始：第一次上手的完整操作流程

我以一个完全没用过这个项目的人身份，记录下整个部署过程。

第一步：环境准备

系统要求：Python 3.10+，Linux/macOS/Windows 均可。

建议先创建一个干净的虚拟环境，避免依赖冲突：

# 创建虚拟环境（推荐用 uv，速度更快）
curl -LsSf https://astral.sh/uv/install.sh | sh
mkdir rag-anything-demo && cd rag-anything-demo
uv init
uv venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

第二步：安装 RAG-Anything

最简单的方式是直接 pip 安装：

# 基础安装
pip install raganything

# 推荐安装完整版（含图片格式、文本格式支持）
pip install 'raganything[all]'

如果需要处理 Office 文档（.docx / .pptx / .xlsx），还需要额外安装 LibreOffice：

# Ubuntu/Debian
sudo apt-get install libreoffice

# macOS
brew install --cask libreoffice

? 新手踩坑提醒：LibreOffice 这一步很多人会跳过，结果处理 Word 文档时报错"找不到转换器"。别省这一步。

第三步：验证解析器安装

RAG-Anything 默认使用 MinerU 作为文档解析引擎，安装完成后验证一下：

mineru --version

python -c "
from raganything import RAGAnything
rag = RAGAnything()
if rag.check_parser_installation():
    print('✅ MinerU 安装正常，可以开始使用')
else:
    print('❌ 安装有问题，请检查')
"

如果显示 ✅ MinerU 安装正常，说明核心解析层已就绪。

第四步：配置 API Key

在项目根目录创建 .env 文件：

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
OPENAI_BASE_URL=https://your-api-base-url  # 如果使用转发地址
OUTPUT_DIR=./output
PARSER=mineru
PARSE_METHOD=auto

? 国内用户注意：OPENAI_BASE_URL 填你的转发服务地址即可，OpenAI 原生地址、第三方兼容 API（如 DeepSeek、Qwen）都支持，只要接口兼容 OpenAI 格式。

第五步：写第一个处理脚本

把一个文档（PDF/Word/PPT 均可）丢进去跑一遍，感受一下完整流程：

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_key = "your-api-key"
    base_url = "your-base-url"  # 可选

    config = RAGAnythingConfig(
        working_dir="./rag_storage",
        enable_image_processing=True,    # 开启图片理解
        enable_table_processing=True,    # 开启表格理解
        enable_equation_processing=True, # 开启公式理解
    )

    # 文字模型（gpt-4o-mini 足够）
    def llm_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)

    # 视觉模型（处理图片需要 gpt-4o 级别）
    def vision_func(prompt, system_prompt=None, history_messages=[],
                    image_data=None, messages=None, **kwargs):
        if messages:
            return openai_complete_if_cache("gpt-4o", "",
                messages=messages, api_key=api_key, base_url=base_url, **kwargs)
        elif image_data:
            return openai_complete_if_cache("gpt-4o", "", messages=[
                {"role": "user", "content": [
                    {"type": "text", "text": prompt},
                    {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{image_data}"}}
                ]}
            ], api_key=api_key, base_url=base_url, **kwargs)
        return llm_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 = RAGAnything(config=config, llm_model_func=llm_func,
                      vision_model_func=vision_func, embedding_func=embedding_func)

    # 处理文档（支持 PDF、Word、PPT、图片等）
    await rag.process_document_complete(
        file_path="your_document.pdf",
        output_dir="./output",
        parse_method="auto"  # auto / ocr / txt
    )

    # 查询
    result = await rag.aquery(
        "文档中的实验结果图说明了什么？",
        mode="hybrid"  # hybrid / local / global / naive
    )
    print(result)

asyncio.run(main())

第六步：批量处理整个文件夹

如果你有一批文档需要处理，一行代码搞定：

await rag.process_folder_complete(
    folder_path="./documents",
    output_dir="./output",
    file_extensions=[".pdf", ".docx", ".pptx"],
    recursive=True,
    max_workers=4   # 并发数，根据机器配置调整
)

这个功能我用来批量处理了公司 3 年的技术方案文档，共 47 份、合计约 2,300 页，跑了大概 40 分钟。之后问任何一个历史技术决策，都能精准溯源到具体文档的具体段落。

? 三种查询模式，怎么选？

RAG-Anything 继承了 LightRAG 的查询模式设计，但加入了多模态查询能力：

① 纯文本查询（最常用）

result = await rag.aquery("这份报告的核心结论是什么？", mode="hybrid")

hybrid 模式同时走图谱多跳 + 向量检索，绝大多数场景首选这个。

② VLM 增强查询（文档含图片时自动触发）

当检索上下文包含图片时，系统会自动加载图片、编码成 base64，连同文字上下文一起发给视觉模型分析。你不需要做任何额外操作，提供了 vision_model_func 就会自动启用。

③ 多模态内容查询（带着具体内容去问）

# 拿着一个公式去问文档
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"
)

? 三个真实应用场景

场景一：学术论文知识库

痛点：读论文时，图 5 是实验结果，第 3 节是方法描述，表 2 是消融实验——三者分散在文档不同位置，传统 RAG 无法联合理解。

用法：把 20 篇领域论文全部 process 进去，建一个专属知识图谱。之后问：

• • "哪几篇论文用了相同的数据集，结果有什么差异？"
• • "表 2 中消融实验去掉图谱模块后，性能下降了多少？"
• • "图 3 展示的注意力热图说明了什么问题？"

系统会跨文档联合检索，把分散在不同论文的证据整合起来回答。

场景二：企业财务报告分析

痛点：年报里大量财务数据以表格形式呈现，配以折线图、柱状图，传统 RAG 对这些内容几乎是盲的。

用法：批量导入 3-5 年的财务年报，然后问：

• • "近三年营收增速趋势如何？图表数据和文字说明是否一致？"
• • "对比表 8 和表 12，两个业务板块的毛利率差异是什么原因？"

由于 RAG-Anything 对表格做了结构语义解析，它能理解表格的行列关系、统计模式，而不是把它当成一坨文字。

场景三：技术文档 + 代码联合检索

痛点：技术手册里的架构图、流程图是理解系统的关键，但传统 RAG 看不见。

用法：把系统架构文档、API 手册、设计说明一起导入：

• • "这张架构图里，模块 A 和模块 B 是什么关系？"
• • "设计文档第 4 章的流程图对应代码中的哪个接口？"

? X 平台真实评价：社区怎么看这个项目？

我在 X（推特）上检索了 #RAGAnything#HKUDS 和 RAG-Anything 相关讨论，整理了有代表性的声音：

? 来自作者团队的里程碑公告

HKUDS 实验室 Chao Huang 教授是 LightRAG 的核心作者，他在 X 上发布了几条关键公告，反映了项目的成长轨迹：

发布当月（2025年6月）：项目上线即登上 GitHub Trending 第一名，Chao Huang 称"多模态 RAG 的需求比我们预想的大得多"。

两个月后（2025年8月）：已突破 2k Star，下载量超 10,000 次，社区问题响应积极，团队承诺持续维护。

三个月后（2025年9月）：5k+ Star，60,000+ 次帖子展示量，团队表示将持续推出功能更新。

技术报告发布（2025年10月）：Star 数达 8,300+，正式 arXiv 论文同步发出，团队特别感谢开源社区的反馈与贡献。

?️ 开发者社区的真实声音

AI 博主 Rohan Paul（@rohanpaul_ai）转发并评论道：

"7,600 Stars，你可以通过一个统一界面查询包含交叉文字、视觉图表、结构表格和数学公式的文档——这才是文档智能应该有的样子。"该帖获得 950+ 转发、1,100+ 收藏。

Sumanth（@Sumanth_077）的介绍帖获得大量关注：

"100% 开源。一个统一框架，通过多阶段多模态流水线扩展了传统 RAG 架构……与传统 RAG 系统不同，RAG-Anything 在一个集成框架中提供端到端的多模态处理和检索。"

? 社区讨论中的典型声音（整理自 GitHub Issues 和 Discord）

正面反馈集中在这几点：

• • 装起来比想象的简单，pip install raganything 之后几十行代码就能跑起来
• • MinerU 解析质量远超市面上的 OCR 方案，特别是对复杂布局的 PDF
• • 多模态知识图谱的联合检索能力，是它和普通 RAG 最本质的区别
• • 社区活跃，Issues 回复速度快，版本迭代频繁（目前已更新至 v1.2.10）

客观存在的局限性（社区和研究评测均有提及）：

• • 处理图片和公式需要 GPT-4o 级别的视觉模型，API 成本相对较高，不适合极端成本敏感场景
• • 手写内容、低分辨率扫描件的解析效果会有明显下降
• • 大批量文档并发处理时，对内存和 API 速率有一定要求，建议合理设置 max_workers
• • 目前对实时性要求极高的场景（毫秒级响应）还不太适合，知识图谱构建需要时间

? 深度使用后的核心心得

用了两个月，踩了不少坑，总结几条真正有用的经验：

① 文档质量决定上限

MinerU 解析的前提是文档本身质量过关。数字原生 PDF（不是扫描件）效果最好；带密码的 PDF 需要先解密；低分辨率扫描件建议先用 upscale 工具处理。

② 善用 parse_method 参数

auto 模式适合大多数情况；数学公式密集的文档推荐 ocr 模式；纯文字文档用 txt 模式速度更快成本更低。

③ 查询模式的选择逻辑

• • 问具体细节（某个数字、某个定义）→ local 模式
• • 问全局趋势（整体结论、综合评价）→ global 模式
• • 不确定 → hybrid 模式（稍慢但最全面）
• • 快速原型验证 → naive 模式（不走图谱，最快）

④ 已有 LightRAG 知识库可以直接接入

如果你之前已经建了 LightRAG 的知识库，不需要重新导入，直接把已有的 LightRAG 实例传给 RAGAnything(lightrag=existing_instance) 即可，多模态能力无缝叠加在已有数据上。

⑤ 直接内容插入是隐藏大杀器

如果你有自己的解析流程（比如已经用其他工具把文档结构化了），可以用 insert_content_list() 直接插入结构化内容，绕过 MinerU 解析，速度提升 3-5 倍，成本大幅降低。

写在最后

RAG 这条路已经走了两年多。从最早的"把文档切片塞向量库"到现在，真正的突破不是谁的 embedding 维度更高、谁的检索速度更快——而是能不能真正理解文档里那些不是文字的内容。

RAG-Anything 给出的答案，是把多模态内容升格为知识图谱的一等公民，让图片、表格、公式和文字站在同等地位上，一起参与检索和推理。

这不是什么遥远的 AGI 想象，这是今天就能部署在你的技术栈里的工程现实。

如果你手头有一批混合了图表和文字的复杂文档，还在用纯文本 RAG 勉强对付——是时候试试这个了。

? 快速开始：pip install raganything[all]
? 项目地址：github.com/HKUDS/RAG-Anything
? 技术论文：arxiv.org/abs/2510.12323