MiniRAG：香港大学开源的轻量级检索增强生成（RAG）框架

一、MiniRAG是什么

MiniRAG是由香港大学数据科学学院开发的开源轻量级检索增强生成（RAG）框架，专为资源受限场景下的小型语言模型（SLM）优化设计。该框架通过语义感知异构图索引机制和轻量级拓扑增强检索方法两大核心创新，解决了小模型在传统RAG架构中性能骤降的问题，使Phi-3.5-mini-instruct、GLM-Edge-1.5B-Chat等小模型能实现媲美大模型的RAG效果，同时仅需传统方案25%的存储空间。MiniRAG支持10+异构图/数据库，提供API和Docker部署方式，内置面向端侧复杂查询的LiHua-World基准数据集，适用于嵌入式设备、低算力服务器等轻量化部署场景，助力开发者快速实现高效、低成本的RAG系统搭建与落地。

MiniRAG的核心定位是极致简单、高效轻量的RAG框架，其设计初衷是让小语言模型在资源受限的端侧、边缘侧场景中，也能实现与大模型相当的RAG性能。该框架摒弃了传统RAG对复杂语义理解和大算力的依赖，通过创新的异构图索引和轻量级检索策略，将存储需求降低至传统方案的25%，同时兼容多种主流图数据库和AI平台，提供便捷的部署和集成方式。此外，MiniRAG还贡献了专门面向端侧轻量级RAG评估的LiHua-World基准数据集，填补了资源受限场景下RAG系统评测的空白，推动了轻量级RAG技术的标准化发展。

作为开源项目，MiniRAG的代码仓库托管于GitHub，遵循MIT开源许可证，开发者可自由使用、修改和分发，同时项目提供了中、英、日多语言文档，降低了不同地区开发者的使用门槛。

二、功能特色

MiniRAG围绕“轻量、高效、易用、兼容”四大核心目标设计，相较于传统RAG框架和其他轻量级RAG方案（如LightRAG），具备以下六大突出功能特色：

（一）小模型媲美大模型的RAG性能

这是MiniRAG最核心的特色。传统RAG框架中，小模型因语义理解、文本处理能力有限，在单跳、多跳检索任务中性能远不及大模型，而MiniRAG通过创新的技术架构，让参数量仅为1.5B左右的小模型（如GLM-Edge-1.5B-Chat、Phi-3.5-mini-instruct），在LiHua-World数据集的多轮检索任务中，性能达到甚至接近基于GPT-3.5、Claude等大模型的RAG效果。在复杂的多约束查询场景（如餐厅识别、故障诊断）中，MiniRAG的表现也显著优于LightRAG等同类轻量级方案。

（二）极致轻量化的存储与计算设计

MiniRAG针对资源受限场景做了深度优化，仅需传统RAG方案25%的存储空间，同时大幅降低了计算资源消耗。框架的核心代码精简，整体代码量不超过1万行，无需复杂的环境配置，甚至支持“双击启动”的便捷使用方式。此外，MiniRAG还支持模型参数压缩，可将模型压缩至1.5B量级，在智能电表、嵌入式设备等边缘终端中实现本地实时推理，响应延迟可控制在200ms以内。

（三）创新的语义感知异构图索引机制

区别于传统RAG的向量索引方式，MiniRAG采用语义感知异构图索引，将文本块和命名实体整合到统一的图结构中，无需依赖模型的高级语义理解能力即可实现精准检索。这种索引方式不仅提升了检索的准确性，还能更好地捕捉文本中的语义关系和逻辑关联，尤其适合多跳推理类查询任务。

（四）广泛的生态兼容能力

MiniRAG具备极强的兼容性，覆盖了数据库、AI平台、部署方式三大维度，无需大幅修改代码即可快速集成到现有系统中：

1. 数据库兼容：支持Neo4j、PostgreSQL、TiDB、MongoDB、Redis、Weaviate、AGE等10+种异构图数据库和传统数据库；

2. AI平台兼容：适配OpenAI、Gitee AI、百度千帆、腾讯云LKE、阿里云百炼、字节火山引擎等主流AI平台，其中Gitee AI还提供每天100次的免费调用额度；

3. 部署方式兼容：支持源码部署、PyPI包安装、API部署和Docker容器部署，满足本地测试、云端服务、端侧集成等不同部署需求。

（五）内置专业的基准评估数据集

MiniRAG内置了LiHua-World基准数据集，这是专门为端侧轻量级RAG系统设计的评测数据集，基于虚拟用户LiHua一年的聊天记录构建，包含单跳查询、多跳查询、摘要类查询三大类问题，每个问题都配有人工标注的标准答案和支持文档。开发者可直接使用该数据集进行模型训练、性能测试和效果验证，无需自行构建评测数据集，大幅提升了开发效率。

（六）多语言支持与友好的开发体验

项目提供英文、中文、日文多语言技术文档，解决了非英语开发者的阅读障碍；代码结构清晰，模块化设计便于二次开发和功能扩展；同时项目维护团队会及时更新版本，修复已知问题，并提供详细的使用教程和复现脚本，降低了RAG技术的入门门槛，即使是初级开发者也能快速上手。

三、技术细节

MiniRAG的核心技术创新体现在语义感知异构图索引机制和轻量级拓扑增强检索方法两大模块，这两个模块共同构成了MiniRAG的技术核心，也是其能让小模型实现高性能RAG的关键。此外，框架的整体工作流程和数据集设计也具备鲜明的技术特点，以下从核心技术、工作流程、数据集设计三个方面详细解析：

（一）核心技术一：语义感知异构图索引机制

传统RAG框架主要依赖向量索引，通过计算文本嵌入的相似度进行检索，这种方式对模型的语义理解能力要求较高，小模型难以胜任。MiniRAG提出的语义感知异构图索引机制，将文本信息转化为“节点+边”的异构图结构，通过捕捉文本中的实体关系实现精准检索，大幅降低了对模型语义理解能力的依赖。该机制的核心组成包括4类核心元素，具体说明如下表所示：

此外，异构图中的每条“边”都配有基于语言模型生成的语义描述，为节点间的连接提供明确的关系上下文，进一步提升了检索的精准度和可解释性。例如，在“LiHua在2024年10月去北京旅游，参观了故宫”这段文本中，会生成“LiHua”“北京”“故宫”“2024年10月”等实体节点，以及“LiHua-旅游-北京”“LiHua-参观-故宫”“故宫-位于-北京”等实体间连接，同时为每条连接添加语义描述。

（二）核心技术二：轻量级拓扑增强检索方法

在构建好异构图索引后，MiniRAG通过轻量级拓扑增强检索方法实现用户查询的处理和相关信息的检索，该方法全程无需依赖大模型的高级语言能力，仅通过小模型和轻量级算法即可完成，分为5个核心步骤，流程如下：

1. 查询语义映射：使用实体提取工具和轻量级句子嵌入模型（如all-MiniLM-L6-v2），将用户的自然语言查询转化为异构图中的实体节点和向量表示，实现查询与图索引数据的对齐。例如，用户查询“LiHua在2024年10月去了哪里旅游？”，会被提取出“LiHua”“2024年10月”“旅游”等实体，并生成对应的向量。

2. 查询驱动的推理路径发现：基于智能查询引导机制，以查询中的实体节点为起点，在异构图中沿着实体-实体连接（Eα）构建推理路径，挖掘与查询相关的实体关联。例如，从“LiHua”和“2024年10月”出发，找到“旅游”“北京”等关联实体，形成推理路径。

3. 拓扑增强的图检索：结合基于嵌入的相似性搜索和图结构的拓扑信息，对推理路径中的实体-实体连接进行打分和筛选，识别出与查询最相关的高质量连接，剔除无关或低相关的信息，提升检索效率。

4. 查询相关文本块的检索：基于筛选后的实体-实体连接，通过实体-文本块连接（Eβ），收集与推理路径相关的文本块节点（Vc），这些文本块即为支撑答案生成的核心上下文信息。

5. 融合增强生成：将检索到的关键实体关系、推理路径和最优文本块整合，构建结构化的输入表示，传递给小语言模型进行答案生成，确保生成的答案既符合查询意图，又有精准的知识支撑。

（三）MiniRAG整体工作流程

结合上述两大核心技术，MiniRAG的整体工作流程可分为索引构建阶段和问答推理阶段，两个阶段相互独立，便于分步部署和优化：

1. 索引构建阶段：输入原始文档数据集（如LiHua-World），通过文本分块、实体提取、关系挖掘等步骤，构建语义感知异构图索引，并将索引数据存储到支持的图数据库中，该阶段仅需执行一次，后续可重复使用索引；

2. 问答推理阶段：接收用户的自然语言查询，通过轻量级拓扑增强检索方法从异构图索引中检索相关信息，再将检索结果传递给小语言模型，最终生成精准、可追溯的答案。

（四）LiHua-World数据集技术设计

LiHua-World数据集是MiniRAG的重要技术贡献之一，其设计充分考虑了端侧轻量级RAG的实际应用场景，具备以下技术特点：

1. 场景真实性：基于虚拟用户LiHua一年的聊天记录构建，涵盖生活、工作、学习、旅游等多个真实场景，查询问题贴近实际使用需求；

2. 查询类型多样性：包含单跳查询（如“LiHua的生日是哪天？”）、多跳查询（如“LiHua在2024年旅游的城市中有哪些有历史古迹？”）、摘要类查询（如“总结LiHua2024年的旅游经历？”）三大类，全面评估RAG系统的综合能力；

3. 标注精细化：每个查询都配有人工标注的标准答案、支持文档和检索路径，便于开发者验证模型的检索准确性和生成质量；

4. 轻量化设计：数据集的规模和数据量适配端侧设备的存储和计算能力，无需大算力即可完成评测。

四、应用场景

MiniRAG凭借轻量级、高性能、易部署的特点，可广泛应用于资源受限的端侧、边缘侧场景，同时也能适配企业级的轻量化知识管理需求，结合实际落地案例和技术特性，其核心应用场景主要包括以下六大类：

（一）边缘终端智能推理

MiniRAG支持模型参数压缩至1.5B量级，可部署在智能电表、工业传感器、智能家居设备等边缘终端中，实现本地实时推理。例如，在智能电表中部署MiniRAG，可结合电表的运行数据和故障知识库，实现本地实时故障诊断，响应延迟可控制在200ms以内，无需依赖云端服务器，提升了设备的智能化水平和响应效率。此外，该场景还可延伸至智能摄像头、工业机器人等边缘设备，用于本地的知识检索和智能决策。

（二）低算力服务器知识助手

对于中小企业、创业团队等算力资源有限的主体，无需投入高额成本采购大算力服务器，即可通过MiniRAG搭建企业内部知识助手。例如，将企业的产品文档、员工手册、客户咨询记录等数据导入MiniRAG，搭建智能客服系统，处理客户的常见咨询；或搭建内部知识库检索系统，帮助员工快速查找所需的知识内容，提升工作效率。该场景的核心优势是低成本、易部署，仅需普通的低算力服务器即可运行，且性能能满足企业的日常使用需求。

（三）嵌入式设备本地化服务

在手机、平板、车载终端等嵌入式设备中，MiniRAG可实现本地化的RAG服务，保护用户数据隐私。例如，在车载终端中部署MiniRAG，结合车辆的使用手册、维修记录等数据，为车主提供本地化的车辆使用咨询和故障排查建议，无需将数据上传至云端，既提升了响应速度，又保障了数据安全。此外，在手机端部署MiniRAG，可搭建本地化的智能笔记检索助手，快速查找笔记中的关键信息。

（四）制造业设备故障诊断

制造业中存在大量的低算力工业终端和设备，MiniRAG可结合设备的维修记录、运行参数、故障知识库等数据，搭建轻量化的故障诊断系统。例如，三一重工将类似的RAG系统接入30万台工程机械的维修记录，故障修复效率提升50%，而MiniRAG的轻量级特性可进一步降低该系统的部署成本和算力需求，适配更多中小型制造企业的设备管理需求。此外，在汽车生产线中，MiniRAG可结合生产线传感器数据和维修记录，减少设备停机时间，降低维护成本。

（五）金融行业轻量化智能咨询

在金融行业，MiniRAG可搭建轻量化的智能财富管家、金融知识咨询系统，适配中小银行、证券机构的算力资源需求。例如，招商银行的“智能财富管家”RAG系统处理客户咨询量占比达45%，客户满意度提升18%，而MiniRAG可在更低算力的服务器上实现类似的功能，为中小金融机构提供高性价比的智能化解决方案。该场景中，MiniRAG可结合金融产品文档、行业资讯、客户咨询记录等数据，为客户提供精准的金融知识解答和产品推荐。

（六）医疗领域本地化知识服务

在医疗领域，MiniRAG可部署在医院的本地终端中，结合药品说明书、临床指南、患者病历等数据，为医护人员提供本地化的知识检索服务。例如，香港某医疗机构的多语言RAG系统为老年患者提供用药提醒，用药依从性提升30%，而MiniRAG的多语言支持和轻量级特性，可进一步适配不同地区医疗机构的需求，尤其适合基层医院、社区卫生服务中心等算力资源有限的医疗场景。此外，MiniRAG还可用于医疗AI制药的轻量化知识检索，关联基因表达数据和临床前实验结果，提升研发效率。

五、使用方法

MiniRAG提供了源码安装和PyPI包安装两种核心安装方式，同时提供了详细的快速运行脚本，便于开发者快速上手。以下从安装准备、安装步骤、快速运行、自定义数据使用四个方面，详细介绍MiniRAG的使用方法，步骤通俗易懂，适配初级开发者：

（一）安装准备

在安装MiniRAG之前，需完成以下基础准备工作，确保运行环境符合要求：

1. 硬件要求：无需高算力显卡，普通CPU服务器（如8核16G内存）或个人电脑即可运行，边缘终端需保证至少1G可用内存；

2. 软件要求：操作系统支持Windows、Linux、macOS；Python版本需≥3.8；

3. 网络要求：安装过程中需要从PyPI和Hugging Face下载依赖包和模型权重，需保证网络通畅，若网络受限，可提前下载相关模型权重至本地。

（二）安装步骤

MiniRAG推荐使用源码安装方式，便于后续二次开发和功能扩展，同时也提供了更便捷的PyPI包安装方式，开发者可根据需求选择：

方式一：源码安装（推荐）

1. 克隆代码仓库：打开终端，执行以下命令，将MiniRAG的代码仓库克隆到本地：

  git clone https://github.com/HKUDS/MiniRAG.git
  cd MiniRAG

2. 安装依赖包：执行以下命令，以可编辑模式安装MiniRAG及其依赖包，修改代码后无需重新安装即可生效：

  pip install -e .

方式二：PyPI包安装（便捷）

若仅需使用MiniRAG的核心功能，无需二次开发，可直接通过PyPI安装，执行以下命令即可：

pip install minirag-hku

注意：MiniRAG的底层依赖LightRAG，若安装失败，可先安装LightRAG再安装MiniRAG，命令为：pip install lightrag-hku。

（三）快速运行

MiniRAG内置了LiHua-World数据集和复现脚本，开发者无需准备额外数据，即可快速体验框架的核心功能，步骤如下：

1. 进入项目目录：若为源码安装，确保终端当前目录为MiniRAG的根目录；若为PyPI安装，需创建新的工作目录，并将项目中的reproduce文件夹复制到该目录中；

2. 构建图索引：执行以下命令，基于LiHua-World数据集构建语义感知异构图索引，该步骤为首次运行时的必要步骤，索引构建完成后可重复使用：

  python ./reproduce/Step_0_index.py

运行成功后，终端会输出向量数据库的初始化信息，例如加载的实体数量、向量维度等，首次运行时出现“data是正常的”提示属于正常现象，因尚未构建向量数据库；
3. 执行问答推理：索引构建完成后，执行以下命令，基于构建的索引进行问答推理，体验MiniRAG的检索和生成功能：

  python ./reproduce/Step_1_QA.py

运行成功后，终端会输出用户查询、检索到的相关文本块和生成的答案，开发者可直观看到MiniRAG的运行效果。

（四）使用自定义数据

若需将MiniRAG应用于实际业务场景，使用自定义的业务数据，可按照以下步骤操作：

1. 数据准备：将自定义的文档数据（如产品手册、知识库、聊天记录等）整理为TXT、MD、PDF等格式，放入项目的dataset目录下，建议将大文档分割为若干个小文本块（每块500字左右），提升检索效率；

2. 修改配置文件：打开reproduce/Step_0_index.py文件，修改其中的数据集路径参数，将默认的LiHua-World数据集路径改为自定义数据的路径；

3. 重新构建索引：执行python ./reproduce/Step_0_index.py命令，基于自定义数据构建新的异构图索引；

4. 执行自定义查询：打开reproduce/Step_1_QA.py文件，修改其中的查询语句，替换为实际的业务查询问题，然后执行该脚本，即可得到基于自定义数据的检索和生成结果。

温馨提示：若直接使用main.py文件进行测试，无需横向对比不同模型的性能，执行python main.py即可完成基础的检索和生成测试。

六、常见问题解答

问题1：执行Step_0_index.py时，出现ImportError错误，提示“cannot import name 'gpt_4o_mini_complete' from 'minirag.llm'”

问题原因：minirag.llm模块的__init__.py文件中未导入所需的函数，导致脚本无法找到对应的方法。
解决方法：打开minirag/llm/__init__.py文件，在文件开头添加以下导入语句，保存后重新运行脚本即可：

# Step_0_index.py所需的导入
from .openai import gpt_4o_mini_complete
from .hf import hf_embed
# Step_1_QA.py所需的导入（提前添加可避免后续报错）
from .hf import hf_model_complete

问题2：安装稳定版本minirag0.0.2后，运行main.py时，出现abstractmethod相关的语法错误

问题原因：base.py文件中未导入Python内置的抽象方法装饰器abstractmethod，导致类定义时出现语法错误。
解决方法：打开MiniRAG-0.0.2/minirag/base.py文件，在文件开头添加以下导入语句，保存后重新运行即可：

from abc import abstractmethod

问题3：运行脚本时，出现OSError错误，提示无法连接到Hugging Face下载all-MiniLM-L6-v2模型

问题原因：网络受限无法从Hugging Face下载模型权重，或本地缓存中未找到该模型。
解决方法：

1. 手动从Hugging Face官网（https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2）下载模型权重；

2. 将下载的模型文件放入本地的Hugging Face缓存目录（默认路径：~/.cache/huggingface/hub）；

3. 重新运行脚本，若仍报错，可在代码中直接指定模型的本地路径。

问题4：使用Qwen模型时，出现模型权重加载失败的问题

问题原因：未下载Qwen模型的权重，或代码中模型路径配置错误。
解决方法：

1. 从Hugging Face官网下载对应的Qwen模型权重（如Qwen3-Embedding-8B、Qwen3-Reranker-8B）；

2. 打开对应的Python脚本（如Step_0_index.py、Step_1_QA.py），找到模型路径配置的代码段，将默认的模型名称改为本地模型的路径，示例如下：

  elif args.model == "qwen":
    LLM_MODEL = "本地模型路径/ Qwen3-Embedding-8B"

问题5：首次运行Step_0_index.py时，终端输出“Loaded document status storage with 0 records”，是否属于正常现象？

问题解答：该提示属于正常现象，无需担心。首次运行时，系统尚未构建向量数据库和文档状态存储，因此记录数为0，当索引构建完成后，再次运行时会显示加载的记录数，说明索引已成功生成。

问题6：切换AI平台（如从Gitee AI切换到百度千帆）后，运行脚本出现API调用失败的问题

问题原因：不同AI平台的base_url和api_key配置格式不同，未按照平台要求正确配置参数。
解决方法：参考MiniRAG的官方文档，根据目标AI平台的要求，正确配置base_url和api_key参数，例如：

1. 百度千帆：base_url填写https://qianfan.baidubce.com/v2，api_key填写永久有效API Key；

2. 腾讯云LKE：base_url填写SecretId，api_key填写SecretKey。

问题7：在边缘终端中部署MiniRAG时，出现内存不足的问题

问题原因：边缘终端的内存资源有限，默认的模型和索引配置占用内存过高。
解决方法：

1. 使用参数压缩后的小模型（如GLM-Edge-1.5B-Chat），替换默认的大模型；

2. 对异构图索引进行轻量化处理，减少索引中实体和连接的数量；

3. 关闭终端中的其他无关程序，释放内存资源。

七、相关链接

1. GitHub代码仓库：https://github.com/HKUDS/MiniRAG

2. 论文地址：https://arxiv.org/abs/2501.06713

3. LiHua-World数据集：https://github.com/HKUDS/MiniRAG/tree/main/dataset/LiHua-World

4. 中文使用文档：

5. 关联项目-LightRAG：https://www.aipuzi.cn/ai-news/lightrag.html

6. 关联项目-VideoRAG：https://www.aipuzi.cn/ai-news/videorag.html

八、总结

MiniRAG是由香港大学数据科学学院开发的一款开源轻量级检索增强生成（RAG）框架，其核心价值在于解决了传统RAG框架依赖大模型、存储和计算成本高、难以在资源受限场景落地的痛点，通过语义感知异构图索引机制和轻量级拓扑增强检索方法两大核心创新，让Phi-3.5-mini-instruct、GLM-Edge-1.5B-Chat等小语言模型实现了媲美大模型的RAG性能，同时将存储需求降低至传统方案的25%。该框架具备广泛的生态兼容性，支持10+种异构图数据库和主流AI平台，提供源码、PyPI、API、Docker等多种部署方式，内置的LiHua-World基准数据集还填补了端侧轻量级RAG系统评测的空白。MiniRAG的使用门槛低，普通开发者可通过简单的步骤完成安装和运行，同时社区也提供了详细的问题解答和技术支持，其应用场景覆盖边缘终端智能推理、低算力服务器知识助手、制造业故障诊断、金融智能咨询、医疗知识服务等多个领域，为资源受限场景下的智能化升级提供了高性价比的RAG解决方案，也推动了轻量级RAG技术的标准化和规模化发展。