# https://github.com/HKUDS/MiniRAG 项目说明书 生成时间：2026-06-25 09:27:23 UTC ## 目录 - [项目概述、安装与快速开始](#page-1) - [核心架构、异构图索引与检索算法](#page-2) - [异构存储后端与 LLM/Embedding 绑定](#page-3) - [API 服务、Docker 部署与社区常见问题](#page-4) ## 项目概述、安装与快速开始 ### 相关页面 相关主题：[核心架构、异构图索引与检索算法](#page-2), [API 服务、Docker 部署与社区常见问题](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/HKUDS/MiniRAG/blob/main/README.md) - [README_CN.md](https://github.com/HKUDS/MiniRAG/blob/main/README_CN.md) - [setup.py](https://github.com/HKUDS/MiniRAG/blob/main/setup.py) - [requirements.txt](https://github.com/HKUDS/MiniRAG/blob/main/requirements.txt) - [main.py](https://github.com/HKUDS/MiniRAG/blob/main/main.py) - [reproduce/Step_0_index.py](https://github.com/HKUDS/MiniRAG/blob/main/reproduce/Step_0_index.py) - [reproduce/Step_1_QA.py](https://github.com/HKUDS/MiniRAG/blob/main/reproduce/Step_1_QA.py) - [dataset/LiHua-World/README.md](https://github.com/HKUDS/MiniRAG/blob/main/dataset/LiHua-World/README.md)
# 项目概述、安装与快速开始 ## 1. 项目概述 MiniRAG 是一个面向小型语言模型（SLM）优化的极简检索增强生成（RAG）框架，由香港大学数据智能（HKUDS）实验室开源。其核心目标是解决现有 RAG 框架在资源受限的端侧设备上部署时面临的性能退化问题。 框架的两大核心技术创新包括： - **语义感知异构图索引机制**：在统一结构中融合文本块与命名实体，降低对复杂语义理解的依赖。 - **轻量级拓扑增强检索方法**：利用图结构实现高效知识发现，无需高级语言能力支撑。 实验数据显示，MiniRAG 仅需 25% 的存储空间即可在使用 SLM 时达到与基于大语言模型方法相当的性能。资料来源：[README.md:1-50]()。 项目还配套发布了 LiHua-World 数据集，模拟虚拟用户"李华"一年份的聊天记录，涵盖单跳、多跳、总结三类问题，并附带人工标注的答案与支持文档，专为端侧 RAG 场景设计。资料来源：[dataset/LiHua-World/README.md:1-20]()。 ## 2. 安装方式 ### 2.1 源码安装（推荐） ```bash cd MiniRAG pip install -e . ``` 资料来源：[README.md:1-50]()。 ### 2.2 通过 PyPI 安装 ```bash pip install minirag-hku ``` 此外，由于项目代码基于 LightRAG，亦可直接安装： ```bash pip install lightrag-hku ``` 资料来源：[README.md:1-50]()。 ### 2.3 Python 版本要求 > ⚠️ **社区提示**：Issue #1 反馈指出，依赖项对 Python 版本敏感，使用 `Python 3.10.13` 时可能出现兼容性问题。建议安装前确认 `requirements.txt` 中各依赖的版本范围，并优先使用官方 README 推荐的 Python 版本。资料来源：[requirements.txt:1-20]()。 ## 3. 快速开始 ### 3.1 数据准备 项目仓库已在 `./dataset/LiHua-World/data/` 目录中预置了 `LiHuaWorld.zip` 压缩包。解压后即可将聊天记录用作知识库。若使用其他数据集，请将文件放入 `./dataset/xxx` 目录中。资料来源：[README.md:1-50]()、[dataset/LiHua-World/README.md:30-50]()。 ### 3.2 索引构建 使用以下命令对数据集进行索引： ```bash python ./reproduce/Step_0_index.py ``` ### 3.3 问答测试 索引完成后执行问答脚本： ```bash python ./reproduce/Step_1_QA.py ``` 亦可直接通过 `main.py` 初始化 MiniRAG 实例。资料来源：[README.md:1-50]()。 ### 3.4 API 与 Docker 部署 项目从 v0.0.2 版本起支持 API 与 Docker 部署方式，详细说明参见 `minirag/api/README.md`。可通过以下命令启动开发模式服务： ```bash uvicorn ollama_minirag_server:app --reload --port 9721 ``` 资料来源：[minirag/api/README.md:1-100]()。 ## 4. 常见问题与故障排除 ### 4.1 索引速度过慢 Issue #82 反馈使用 `gpt-4o-mini` 处理 150 个 txt 文件耗时一整天，且处理时间随已处理文件增加而线性增长。这通常与以下因素相关： - **API 调用频率限制**：持续高频调用触发服务降速； - **重复处理已索引文档**：Issue #96 指出 `ainsert` 在多次调用时可能重新处理状态为 `processed` 的 chunk，导致实体抽取重复执行； - **嵌入模型选择**：可考虑切换至本地嵌入以减少网络依赖。 > 💡 建议每次 `ainsert` 调用前检查 `inserting_chunks` 状态，避免对已处理内容重复抽取实体。资料来源：[minirag/api/minirag_server.py:1-100]()。 ### 4.2 Phi-3 模型兼容性问题 Issue #69 报告 `'DynamicCache' object has no attribute 'get_max_length'` 错误。解决方案： 1. 替换为其他模型；或 2. 在 HuggingFace 缓存目录（如 `C:\Users\用户名\.cache\huggingface`）中找到 `modeling_phi3.py`，将 `get_max_length` 全局替换为 `get_max_cache_shape`。资料来源：[minirag/api/minirag_server.py:1-100]()。 ### 4.3 路径选择逻辑疑问 Issue #90 询问 `path2chunk` 函数中为何使用 `count_dict.most_common(max_chunks)` 而非直接使用累计的 `node_chunk_id`。此为有意的设计选择：前者基于全局频次排序，后者仅基于当前路径的累计权重。资料来源：[reproduce/Step_0_index.py:1-50]()。 ## 5. 整体工作流概览 ```mermaid flowchart LR A[解压数据集] --> B[Step_0_index.py] B --> C[异构图索引] C --> D[Step_1_QA.py] D --> E[检索与生成] E --> F[返回答案] ``` ## See Also - 核心模块架构与 API 参考 - LiHua-World 数据集详细说明 - 异构图索引与拓扑检索实现原理 --- ## 核心架构、异构图索引与检索算法 ### 相关页面 相关主题：[项目概述、安装与快速开始](#page-1), [异构存储后端与 LLM/Embedding 绑定](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [minirag/minirag.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/minirag.py) - [minirag/operate.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/operate.py) - [minirag/base.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/base.py) - [minirag/prompt.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/prompt.py) - [minirag/utils.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/utils.py) - [minirag/llm.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/llm.py) - [minirag/storage.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/storage.py) - [minirag/exceptions.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/exceptions.py) - [README.md](https://github.com/HKUDS/MiniRAG/blob/main/README.md) - [reproduce/Step_0_index.py](https://github.com/HKUDS/MiniRAG/blob/main/reproduce/Step_0_index.py) - [reproduce/Step_1_QA.py](https://github.com/HKUDS/MiniRAG/blob/main/reproduce/Step_1_QA.py)
# 核心架构、异构图索引与检索算法 ## 一、整体架构概览 MiniRAG 是一个面向小型语言模型（SLM）设计的极简检索增强生成（RAG）框架，其核心理念是**以最简架构实现与基于 LLM 的 RAG 系统相当的检索效果**。项目源自论文 *MiniRAG: Towards Extremely Simple Retrieval-Augmented Generation* ([arXiv:2501.06713](https://arxiv.org/abs/2501.06713))，由 HKUDS 团队于 2025 年初开源。 MiniRAG 的代码建立在 [LightRAG](https://github.com/HKUDS/LightRAG) 之上，主要模块组织如下 [资料来源：[README.md](https://github.com/HKUDS/MiniRAG/blob/main/README.md)]： | 模块文件 | 职责 | |---|---| | `minirag.py` | 核心类 `MiniRAG`，封装 `ainsert` / `aquery` 等高层 API | | `operate.py` | 实现图谱抽取、合并、检索等具体操作 | | `base.py` | 定义数据结构（如 `TextChunkSchema`、图节点/边 schema） | | `prompt.py` | 集中存放用于实体/关系抽取与答案生成的提示词 | | `storage.py` | 图与向量存储后端抽象（支持 Neo4j、PostgreSQL、TiDB 等 10+ 异构库） | | `llm.py` | LLM 与 Embedding 函数的统一封装 | | `utils.py` | 分块、编码、相似度计算等工具函数 | > 该架构在 2025-02-14 的更新中扩展了对 10 余种异构图数据库的支持 [资料来源：[README.md](https://github.com/HKUDS/MiniRAG/blob/main/README.md)]。 ## 二、异构图索引机制（Heterogeneous Graph Indexing） MiniRAG 的关键创新之一是**语义感知的异构图索引**。与 GraphRAG / LightRAG 单纯依赖 LLM 抽取实体与关系不同，MiniRAG 将两类异构节点统一纳入同一张图： - **文本块节点（chunk 节点）**：由 `utils.py` 中的分块函数产生，每一块带有原始内容与向量嵌入。 - **命名实体节点（entity 节点）**：通过 LLM 从 chunk 中抽取而来，由 `operate.py` 中的抽取函数维护。 两类节点之间通过 "包含" 边相互连接，从而形成 **chunk–entity 异构图**。这种结构带来两点收益 [资料来源：[README.md](https://github.com/HKUDS/MiniRAG/blob/main/README.md)]： 1. 减少对复杂语义理解的依赖——小型模型只需完成局部实体抽取，不必承担全局主题聚合。 2. 显著压缩存储开销——论文报告存储空间仅需传统方案的 **25%**。 索引的入口在 [reproduce/Step_0_index.py](https://github.com/HKUDS/MiniRAG/blob/main/reproduce/Step_0_index.py)，其内部调用 `MiniRAG.ainsert()`，再由 `operate.py` 完成 chunking → embedding → entity extraction → graph merge 的完整流水线。 ### 索引流程示意 ```mermaid flowchart LR A[原始文档] --> B[分块
utils.chunking] B --> C[向量嵌入
llm.embedding] C --> D[实体抽取
operate.extract_entities] D --> E[写入异构图
storage.upsert] E --> F[(异构图存储
Neo4j / PG / TiDB / ...)] ``` ## 三、轻量级拓扑增强检索（Topology-Enhanced Retrieval） 检索阶段，MiniRAG 采用**轻量级图拓扑增强**策略：在向量召回的基础上，沿 chunk–entity 异构图的边进行一跳或多跳扩展，从而发现向量空间之外的关联。 具体过程由 `MiniRAG.aquery()` 驱动，主要步骤包括 [资料来源：[minirag/minirag.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/minirag.py)]： 1. **向量召回**：用查询的 embedding 与 chunk 节点计算相似度，召回 top-k 候选。 2. **实体桥接**：将候选 chunk 关联的实体节点并入上下文。 3. **路径回填**（`path2chunk`）：根据实体在多个 chunk 中出现的频次，使用 `count_dict.most_common(max_chunks)` 选取被多个相关 chunk 同时引用的实体，进而把它们所属的 chunk 回填到 `v['Path']`，实现多跳推理。 4. **LLM 生成**：将上述拓扑增强后的上下文与提示词（定义于 [minirag/prompt.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/prompt.py)）一并送入 LLM，得到最终答案。 > 关于 `path2chunk` 中 `count_dict.most_common()` 的设计，社区 Issue #90 提出了与直接使用 `node_chunk_id.most_common()` 的差异讨论 [资料来源：Issue #90](https://github.com/HKUDS/MiniRAG/issues/90)，目前实现以 `count_dict` 为准。 ## 四、社区反馈与常见问题 ### 4.1 索引性能问题 社区 Issue #82 报告在使用 `gpt-4o-mini` 进行 `reproduce/Step_0_index.py` 索引时，处理 150 个 txt 文件耗时超过一天，且越到后期越慢，单个文件超过 20 分钟 [资料来源：Issue #82](https://github.com/HKUDS/MiniRAG/issues/82)。常见根因包括： - API 限流导致重试； - 后端图数据库写入未分批，事务体积过大； - 未关闭 LLM 缓存，重复实体抽取。 ### 4.2 重复处理已索引文档 Issue #96 指出 `ainsert` 在多次调用时，会把状态为 `processed` 的 chunk 再次送入实体抽取流程，导致索引越来越慢 [资料来源：Issue #96](https://github.com/HKUDS/MiniRAG/issues/96)。规避方式是在调用前对 `inserting_chunks` 做去重，或在批处理时整体传入新文档而非多次追加。 ### 4.3 模型兼容性问题 使用 Phi-3 等微软模型时，可能抛出 `'DynamicCache' object has no attribute 'get_max_length'` 错误（Issue #69）。临时解决方案是定位到 Hugging Face 缓存中的 `modeling_phi3.py`，将 `get_max_length` 替换为 `get_max_cache_shape` [资料来源：Issue #69](https://github.com/HKUDS/MiniRAG/issues/69)。 ### 4.4 Python 版本依赖 Issue #1 提示项目未在 `setup.py` 中固定 Python 版本，部分依赖与 `Python 3.10.13` 不兼容 [资料来源：Issue #1](https://github.com/HKUDS/MiniRAG/issues/1)。建议使用官方 [requirements.txt](https://github.com/HKUDS/MiniRAG/blob/main/requirements.txt) 中标注的兼容版本进行安装。 ## See Also - [项目概览与快速开始](./README.md) - [API 服务（FastAPI / Ollama 模拟）](./minirag/api/README.md) - [LiHua-World 数据集说明](./dataset/LiHua-World/README.md) - [LightRAG 上游项目](https://github.com/HKUDS/LightRAG) --- ## 异构存储后端与 LLM/Embedding 绑定 ### 相关页面 相关主题：[核心架构、异构图索引与检索算法](#page-2), [API 服务、Docker 部署与社区常见问题](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/HKUDS/MiniRAG/blob/main/README.md) - [minirag/api/README.md](https://github.com/HKUDS/MiniRAG/blob/main/minirag/api/README.md) - [minirag/api/minirag_server.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/api/minirag_server.py) - [minirag/kg/__init__.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/kg/__init__.py) - [minirag/kg/neo4j_impl.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/kg/neo4j_impl.py) - [minirag/kg/oracle_impl.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/kg/oracle_impl.py) - [minirag/kg/postgres_impl.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/kg/postgres_impl.py) - [minirag/kg/redis_impl.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/kg/redis_impl.py) - [minirag/kg/milvus_impl.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/kg/milvus_impl.py)
# 异构存储后端与 LLM/Embedding 绑定 ## 概述 MiniRAG 在设计上强调"极简"与"可插拔"，其核心抽象之一就是将底层的知识图谱、向量、键值与文档状态等存储介质与上层的大语言模型（LLM）和嵌入模型（Embedding）解耦。通过统一的工厂接口，用户可以按需切换不同的后端实现，而无需修改调用层代码。仓库根目录下的 README 指出，MiniRAG 已支持 10 余种异构图数据库（Neo4j、PostgreSQL、TiDB 等），同时提供 API 与 Docker 部署形态，使不同规模与硬件条件的部署场景都能找到合适的绑定方案。资料来源：[README.md]()。 ## 异构存储后端架构 MiniRAG 的存储层被划分为四种逻辑角色，源码中通过常量分别指明：键值存储（`KV_STORAGE`）、文档状态存储（`DOC_STATUS_STORAGE`）、图存储（`GRAPH_STORAGE`）与向量存储（`VECTOR_STORAGE`）。在 `minirag_server.py` 中可以看到这些常量被直接注入到服务配置字典中。资料来源：[minirag/api/minirag_server.py]()。 每一种角色都可以绑定到不同的物理后端： | 存储角色 | 默认后端 | 可选后端（节选） | 主要实现文件 | |---------|---------|-----------------|-------------| | 图存储（GRAPH_STORAGE） | NetworkX | Neo4j、Oracle、PostgreSQL、TiDB | `minirag/kg/neo4j_impl.py`、`minirag/kg/oracle_impl.py`、`minirag/kg/postgres_impl.py` | | 向量存储（VECTOR_STORAGE） | NanoVectorDB | Milvus | `minirag/kg/milvus_impl.py` | | 键值存储（KV_STORAGE） | JSON | Redis | `minirag/kg/redis_impl.py` | | 文档状态存储（DOC_STATUS_STORAGE） | JSON | Redis | `minirag/kg/redis_impl.py` | 这些实现统一通过 `minirag/kg/__init__.py` 暴露的工厂接口进行注册与解析，从而屏蔽底层差异。资料来源：[minirag/kg/__init__.py]()。 ```mermaid flowchart LR Caller[调用层: MiniRAG API] --> Factory[存储工厂
kg/__init__.py] Factory --> KV[KV_STORAGE] Factory --> Doc[DOC_STATUS_STORAGE] Factory --> Graph[GRAPH_STORAGE] Factory --> Vec[VECTOR_STORAGE] KV --> JSON1[JSON] & Redis1[Redis] Doc --> JSON2[JSON] & Redis2[Redis] Graph --> NX[NetworkX] & Neo4j[Neo4j] & PG[PostgreSQL] & Oracle[Oracle] & TiDB[TiDB] Vec --> Nano[NanoVectorDB] & Milvus[Milvus] ``` ## LLM 绑定配置 MiniRAG 通过命令行参数和环境变量同时支持多种 LLM 后端绑定，定义在 `minirag_server.py` 的 `parse_args` 中。支持的绑定类型包括 `lollms`、`ollama`、`openai-ollama`、`openai` 与 `azure_openai`，每种绑定都对应一个 `model_complete` 异步函数实现（例如 `ollama_model_complete`、`azure_openai_model_complete`），最终在 `MiniRAG(...)` 构造时通过 `llm_model_func` 参数注入。资料来源：[minirag/api/minirag_server.py]()。 社区问题 #82 反馈了 `reproduce/Step_0_index.py` 在切换至 `gpt-4o-mini` API 后索引速度极慢、单文件耗时超过 20 分钟的现象，这通常与 LLM 绑定的 `max_async` 并发度以及 `chunk_size` 默认值（1200）相关，需要在启动参数中适度上调并发并减小单次请求负载。资料来源：[README.md]()。 ## Embedding 绑定配置 Embedding 绑定与 LLM 绑定共享同一套命令行参数结构，但通过 `--embedding-binding` 独立指定，可选项为 `lollms`、`ollama`、`azure_openai` 和 `openai`。`EmbeddingFunc` 的 `func` 字段会根据绑定类型路由到 `lollms_embed`、`ollama_embed`、`azure_openai_embed` 或 `openai_embed` 等实现。默认模型为 `bge-m3:latest`，默认维度由 `--embedding-dim` 控制。资料来源：[minirag/api/minirag_server.py]()。 需要特别注意的是，绑定类型与对应的 host/模型必须匹配，否则会在初始化阶段抛出绑定异常；此外，Embedding 调用会与图谱构建流程深度耦合，因此后端切换往往需要清空 `working_dir` 下的旧数据再重新执行 `Step_0_index.py`。 ## See Also - 项目主介绍与快速开始：[README.md](https://github.com/HKUDS/MiniRAG/blob/main/README.md) - API 服务端点与 Ollama 仿真接口：[minirag/api/README.md](https://github.com/HKUDS/MiniRAG/blob/main/minirag/api/README.md) - 服务端启动、参数解析与绑定工厂实现：[minirag/api/minirag_server.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/api/minirag_server.py) - 论文：MiniRAG: Towards Extremely Simple Retrieval-Augmented Generation（arXiv:2501.06713） - 配套基准数据集：[dataset/LiHua-World/README.md](https://github.com/HKUDS/MiniRAG/blob/main/dataset/LiHua-World/README.md) --- ## API 服务、Docker 部署与社区常见问题 ### 相关页面 相关主题：[项目概述、安装与快速开始](#page-1), [异构存储后端与 LLM/Embedding 绑定](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [minirag/api/minirag_server.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/api/minirag_server.py) - [minirag/api/README.md](https://github.com/HKUDS/MiniRAG/blob/main/minirag/api/README.md) - [minirag/api/__init__.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/api/__init__.py) - [README.md](https://github.com/HKUDS/MiniRAG/blob/main/README.md) - [dataset/LiHua-World/README.md](https://github.com/HKUDS/MiniRAG/blob/main/dataset/LiHua-World/README.md)
# API 服务、Docker 部署与社区常见问题 ## 一、API 服务定位与组件构成 MiniRAG 自 v0.0.2 起提供了基于 FastAPI 的可选 API 服务，其核心定位是"为已有 LLM 后端服务原地添加 RAG 能力"。服务实现集中在 [`minirag/api/minirag_server.py`](https://github.com/HKUDS/MiniRAG/blob/main/minirag/api/minirag_server.py) 中，入口通过 `create_app(args)` 工厂函数构建，可注册的 llm binding 包括 `lollms`、`ollama`、`openai`、`openai-ollama`、`azure_openai`，embedding binding 支持 `lollms`、`ollama`、`openai`、`azure_openai`。资料来源：[minirag/api/minirag_server.py:create_app](https://github.com/HKUDS/MiniRAG/blob/main/minirag/api/minirag_server.py) 模块版本号定义在 [`minirag/api/__init__.py`](https://github.com/HKUDS/MiniRAG/blob/main/minirag/api/__init__.py) 中，当前为 `__api_version__ = "1.0.3"`，可作为兼容性检查的参考。资料来源：[minirag/api/__init__.py:1](https://github.com/HKUDS/MiniRAG/blob/main/minirag/api/__init__.py) ```mermaid flowchart LR Client[Client / Ollama 客户端] -->|HTTP| Server[FastAPI: minirag_server.py] Server -->|rag.ainsert / aquery| MiniRAG[MiniRAG Core] Server -->|LLM 调用| LLMBackend[LLM Backend: Ollama / LoLLMs / OpenAI / Azure] Server -->|Embedding 调用| EmbedBackend[Embedding Backend] MiniRAG -->|heterogeneous graph| Storage[KV / Vector / Graph Storage] ``` ## 二、安装与启动方式 API 服务需要显式启用可选依赖，README 中给出两种方式：通过 PyPI 安装 `pip install "lightrag-huku[api]"`，或从源码 `pip install -e ".[api]"`。资料来源：[minirag/api/README.md:1-30](https://github.com/HKUDS/MiniRAG/blob/main/minirag/api/README.md) 启动不同后端对应的开发命令在 [`minirag/api/README.md`](https://github.com/HKUDS/MiniRAG/blob/main/minirag/api/README.md) 中列出，例如 Ollama 后端使用 `uvicorn ollama_minirag_server:app --reload --port 9721`。所有参数（如 `--llm-binding-host`、`--embedding-binding-api-key`、`--chunk_size`、`--chunk-overlap-size`、`--timeout`）既支持命令行也可通过环境变量 `LLM_BINDING`、`EMBEDDING_MODEL` 等覆盖，缺省 embedding 模型为 `bge-m3:latest`，缺省 chunk size 为 1200。资料来源：[minirag/api/minirag_server.py:parse_args](https://github.com/HKUDS/MiniRAG/blob/main/minirag/api/minirag_server.py) ## 三、API 端点参考 API 服务同时提供文档管理与 Ollama 模拟两类接口，使得现有 Ollama 客户端可直接通过 `http://localhost:9721` 接入带 RAG 的模型。资料来源：[minirag/api/README.md:35-100](https://github.com/HKUDS/MiniRAG/blob/main/minirag/api/README.md) | 端点 | 方法 | 用途 | 关键参数 | |------|------|------|---------| | `/documents/text` | POST | 直接插入文本 | `text`, `description` | | `/documents/file` | POST | 上传单文件（txt/md/pdf/docx/pptx） | `file`, `description` | | `/documents/batch` | POST | 批量上传 | `files` | | `/documents/scan` | POST | 扫描 Input 目录 | `--max-time` | | `/documents` | DELETE | 清空文档 | — | | `/api/version` | GET | 模拟 Ollama 版本 | — | | `/api/tags` | GET | 模拟模型列表 | — | | `/api/chat` | POST | 模拟 Ollama chat（流式） | `model`, `messages`, `stream` | | `/query` | POST | 通用 RAG 查询 | `query`, `mode`, `stream`, `only_need_context` | | `/health` | GET | 健康检查 | — | `/api/chat` 与 `/query` 端点内部会调用 `rag.ainsert` 与 `rag.aquery`；查询参数 `mode` 通过 `parse_query_mode` 解析前缀 `/light `、`/naive `、`/mini ` 切换检索模式。资料来源：[minirag/api/minirag_server.py:parse_query_mode](https://github.com/HKUDS/MiniRAG/blob/main/minirag/api/minirag_server.py)。`/documents/file` 端点按扩展名分发到 `PdfReader`、`docx.Document`、`pptx.Presentation` 等解析器，缺失依赖时通过 `pm.install` 即时安装。资料来源：[minirag/api/minirag_server.py:insert_file](https://github.com/HKUDS/MiniRAG/blob/main/minirag/api/minirag_server.py) ## 四、社区常见问题与排查 以下问题源自仓库公开 issue，按主题归类。 **1. 索引极慢**（参考 Issue #82）。`reproduce/Step_0_index.py` 使用 `gpt-4o_mini` API 索引 150 个 txt 文件耗时一整天。常见根因是网络限流、chunk token 长度过长导致 prompt 膨胀、以及未对 `chunk_size`/`chunk_overlap_size` 进行调优。建议：先减小 `chunk_size`（API 模式常取 500–800），降低 prompt 模板中的 `max_gleaning` 次数，并启用 embedding 缓存。 **2. `DynamicCache' object has no attribute 'get_max_length'`**（参考 Issue #69）。该错误由微软 Phi-3 模型在 `transformers` 新版本中将属性更名为 `get_max_cache_shape` 导致。两种解法：换用其他 embedding/语言模型；或在 HuggingFace 缓存目录（如 `~/.cache/huggingface`）中搜索 `modeling_phi3.py`，将 `get_max_length` 全局替换为 `get_max_cache_shape`。 **3. Python 版本不匹配**（参考 Issue #1）。项目依赖（如部分 LLM binding）要求特定 Python 版本。可在 [`README.md`](https://github.com/HKUDS/MiniRAG/blob/main/README.md) 的 `requirements.txt` 与 `setup.py` 中核对，建议使用 `python -m venv .venv` 隔离环境并按提示安装对应 Python。 **4. `ainsert` 重复处理已处理 chunk**（参考 Issue #96）。官方示例中多次调用 `rag.ainsert` 时，会把状态为 `processed` 的 chunk 再次取出并重新抽取实体，导致处理时间不断累积。建议每次启动只调用一次 `ainsert`，或在使用增量入库前先过滤 `inserting_chunks`，避免重复触发 LLM 实体抽取。 **5. `path2chunk` 中 `count_dict.most_common()` 与 `node_chunk_id.most_common()` 的差异**（参考 Issue #90）。`node_chunk_id` 是按节点聚合的临时累加器，而 `count_dict` 才是最终用于排序写入 `v['Path']` 的全局频次表，二者语义不同，源码中的写法是有意为之。 ## 五、Docker 部署与运行建议 API 服务可通过仓库根目录的 `Dockerfile` 进行容器化部署（README 中提到 2025.02.01 起 MiniRAG 已支持 API & Docker 部署）。典型流程为：构建镜像后挂载 `dataset/` 与 `inputs/` 目录，使用环境变量注入 `LLM_BINDING`、`EMBEDDING_BINDING`、`EMBEDDING_MODEL` 等参数，再以 `uvicorn ... --host 0.0.0.0 --port 9721` 暴露服务。`/health` 端点可用于容器存活探针。资料来源：[minirag/api/README.md:1-200](https://github.com/HKUDS/MiniRAG/blob/main/minirag/api/README.md)、[README.md](https://github.com/HKUDS/MiniRAG/blob/main/README.md) ## 另请参阅 - [项目主页与安装指南](#) - [LiHua-World 数据集说明](https://github.com/HKUDS/MiniRAG/blob/main/dataset/LiHua-World/README.md) - [API 服务源码：minirag_server.py](https://github.com/HKUDS/MiniRAG/blob/main/minirag/api/minirag_server.py) --- --- ## Doramagic 踩坑日志 项目：HKUDS/MiniRAG 摘要：发现 13 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：MiniRAG re-runs entity extraction on existing chunks without cache checks。 ## 1. 安全/权限坑 · 来源证据：MiniRAG re-runs entity extraction on existing chunks without cache checks - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：MiniRAG re-runs entity extraction on existing chunks without cache checks - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/HKUDS/MiniRAG/issues/104 | 来源类型 github_issue 暴露的待验证使用条件。 ## 2. 安全/权限坑 · 来源证据：[bug] In hybrid mode, the context is excessively long and fails to be truncated correctly. - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug] In hybrid mode, the context is excessively long and fails to be truncated correctly. - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/HKUDS/MiniRAG/issues/108 | 来源类型 github_issue 暴露的待验证使用条件。 ## 3. 安装坑 · 来源证据：New project. Missing one dependency not listed in requirements.txt - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：New project. Missing one dependency not listed in requirements.txt - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/HKUDS/MiniRAG/issues/97 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 4. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/HKUDS/MiniRAG | README/documentation is current enough for a first validation pass. ## 5. 运行坑 · 来源证据：发现了一个bug，导致无法获取type_pool - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：发现了一个bug，导致无法获取type_pool - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/HKUDS/MiniRAG/issues/95 | 来源类型 github_issue 暴露的待验证使用条件。 ## 6. 维护坑 · 来源证据：Indicate explicitly minimum or recommended python version - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Indicate explicitly minimum or recommended python version - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/HKUDS/MiniRAG/issues/102 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 7. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/HKUDS/MiniRAG | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/HKUDS/MiniRAG | no_demo; severity=medium ## 9. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/HKUDS/MiniRAG | no_demo; severity=medium ## 10. 安全/权限坑 · 来源证据：[Performance] MiniRAG underperforms NaiveRAG significantly with Phi-3.5-mini（MiniRAG 在 Phi-3.5-mini 模型上的表现显著不如 NaiveRAG） - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Performance] MiniRAG underperforms NaiveRAG significantly with Phi-3.5-mini（MiniRAG 在 Phi-3.5-mini 模型上的表现显著不如 NaiveRAG） - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/HKUDS/MiniRAG/issues/109 | 来源类型 github_issue 暴露的待验证使用条件。 ## 11. 安全/权限坑 · 来源证据：transformers 4.53.2 throws this error - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：transformers 4.53.2 throws this error - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/HKUDS/MiniRAG/issues/98 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 12. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/HKUDS/MiniRAG | issue_or_pr_quality=unknown ## 13. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/HKUDS/MiniRAG | release_recency=unknown