
HippoRAG
给 RAG 装上记忆图谱,多跳问答一次串起来
项目预览
项目数据
项目介绍
Star 增长趋势
本站每日记录该项目 GitHub 星标变化,观测越久曲线越完整
数据来源:GitHub API 逐日快照 · 收录于 2026-10-02 · 当前星标 ★ 4125
使用教程
ℹ 本教程由 AI 依据该项目 README 整理,个别步骤可能需要按你的环境微调。
环境要求
- Python 3.10(用 Conda 或 uv 创建环境,推荐项目内 .venv)
- NVIDIA GPU 及可指定的 CUDA_VISIBLE_DEVICES(本地 vLLM 部署需要)
- OpenAI API Key,或 Azure OpenAI 的 API Key 与 endpoint
- 已设置 Hugging Face 缓存目录 HF_HOME
安装与启动步骤
-
1创建虚拟环境
用 Conda 建一个 Python 3.10 环境并激活;开发场景推荐用 uv 建项目内 .venv。
conda create -n hipporag python=3.10 conda activate hipporag -
2安装 HippoRAG
直接用 pip 从包索引安装发布版;如需改源码则改用 uv 可编辑安装。
pip install hipporag -
3获取源码可编辑安装
需要跑 main.py 或在仓库内开发时,克隆仓库后用 uv 做可编辑安装。
git clone https://github.com/OSU-NLP-Group/HippoRAG.git cd HippoRAG uv venv --python 3.10 .venv source .venv/bin/activate uv pip install -e . -
4按需装本地模型支持
只在要用 vLLM 或 GritLM 等本地模型时安装对应可选依赖,否则跳过。
uv pip install -e '.[vllm]' -
5设置环境变量
指定可用 GPU、Hugging Face 缓存目录;用 OpenAI 模型时再配 API Key。
export CUDA_VISIBLE_DEVICES=0,1,2,3 export HF_HOME=<path to Huggingface home directory> export OPENAI_API_KEY=<your openai api key> conda activate hipporag -
6启动vLLM服务
本地部署时先按 vLLM 官方文档起一个 OpenAI 兼容服务,并给嵌入模型留足显存。多卡务必加 spawn 变量。
export CUDA_VISIBLE_DEVICES=0,1 export VLLM_WORKER_MULTIPROC_METHOD=spawn export HF_HOME=<path to Huggingface home directory> -
7运行索引与问答
用 main.py 跑索引和 QA,指定数据集、LLM 接口地址、模型名与嵌入模型名。
python main.py --dataset $dataset --llm_base_url https://api.openai.com/v1 --llm_name gpt-4o-mini --embedding_name nvidia/NV-Embed-v2 -
8Azure或基线运行
Azure OpenAI 走同一入口,改传 azure 系列参数;想跑标准密集检索基线加 --rag_type standard。
python main.py --dataset sample --llm_name gpt-4o-mini --embedding_name text-embedding-3-small \ --azure_endpoint https://<resource>.openai.azure.com --azure_api_version <api-version> \ --azure_chat_deployment <chat-deployment> \ --azure_embedding_endpoint https://<resource>.openai.azure.com \ --azure_embedding_deployment <embedding-deployment> python main.py --dataset sample --rag_type standard --embedding_batch_size 1
关键配置
| 配置项 | 必填 | 说明 | 示例 |
|---|---|---|---|
CUDA_VISIBLE_DEVICES | 是 | 指定参与运行的 GPU 编号,vLLM 与嵌入模型共用 | 0,1,2,3 |
HF_HOME | 是 | Hugging Face 模型与数据缓存目录 | /your/path/hf_home |
OPENAI_API_KEY | 否 | 使用 OpenAI 模型时必须设置 | sk-xxxxxxxx |
VLLM_WORKER_MULTIPROC_METHOD | 否 | 多卡跑 vLLM 时设为 spawn,避免 CUDA 初始化失败 | spawn |
AZURE_OPENAI_API_KEY | 否 | 改用 Azure OpenAI 时替代 OpenAI Key | xxxxxxxxxxxxxxxx |
AZURE_OPENAI_API_VERSION / azure_embeddi | 否 | 嵌入接口版本与对话接口不一致时单独指定 | 2024-02-01 |
如何确认成功
执行 main.py 后能正常加载数据集、完成索引并输出问答/评估结果,且无 CUDA 或鉴权报错,即视为成功。
常见问题
Q:多卡跑 vLLM 时报 CUDA 初始化错误怎么办?
A:确认已导出 VLLM_WORKER_MULTIPROC_METHOD=spawn,它显式指定多进程模式,可避免 fork 出的 worker 引发 CUDA 初始化问题。
Q:如何跑传统向量检索基线做对比?
A:在 main.py 命令后加 --rag_type standard,例如 python main.py --dataset sample --rag_type standard --embedding_batch_size 1,两者共用同一套加载与评估逻辑。
Q:OpenAI SDK 版本兼容性怎么保证?
A:HippoRAG 支持 openai>=3.3.1,<4。可用 uv pip install -r requirements.txt -c constraints/openai-tested.txt 复现最低基线,再跑 unittest tests.test_openai_sdk_compat 验证。
Q:想接自己的本地大模型怎么做?
A:先起一个 OpenAI 兼容的 vLLM 服务,安装 uv pip install -e '.[vllm]',再把 --llm_base_url 指向本地服务地址即可。
Q:Azure OpenAI 能直接用吗?
A:可以,入口相同,改传 --azure_endpoint、--azure_api_version、--azure_chat_deployment 以及嵌入相关的 endpoint 与 deployment 参数。
注意事项
- 多 GPU 运行 vLLM 不要省略 VLLM_WORKER_MULTIPROC_METHOD=spawn。
- 启动 vLLM 时要为嵌入模型预留足够显存。
- 只设置实际使用模型所需的环境变量即可,避免误用计费接口。
- HippoRAG 2 在线检索成本与延迟较低,离线索引资源消耗也显著少于 GraphRAG、RAPTOR、LightRAG 等图方案。
核心亮点
- 用知识图谱+Personalized PageRank 做多跳检索,跨文档整合能力明显强于普通向量 RAG
- 支持持续增量地吸收新文档,无需重新训练模型即可更新知识
- 有 NeurIPS 2024 论文背书,方法有理论依据,代码为 Python 实现便于二次开发
不足之处
- 依赖实体关系抽取构建图谱,抽取质量直接决定效果,构建阶段成本和调参门槛较高
- 项目相对较新,工程化封装、文档完善度和社区生态仍在成长中
适用场景
- 多跳问答:需要串联多个文档中的事实才能回答的问题
- 企业知识库:把分散的内部文档整合成可推理的知识图谱后检索
- 科研文献助手:跨论文整合方法与结论,支持持续新增文献
替代项目
LightRAG、GraphRAG
同类项目推荐
trieve
开源
一个 API 搞定搜索、推荐和 RAG,快速构建智能应用
All-in-one platform for search, recommendations, RAG, and analytics offered via API
cognito-ai-search
开源
开源引擎配上大模型,搜得全又答得明白
Powerful search page powered by LLMs and SearXNG
DataMind
开源
一个框架搞定 RAG、图检索、NL2SQL 和记忆
All-in-one intelligent assistant powered by LlamaIndex — RAG, GraphRAG, NL2SQL, Ski···
EpsteinFiles-RAG
开源
用自然语言检索海量文档,快速获得精准答案
A RAG pipeline implementation built on the 'Epstein Files 20K' dataset from Hugging ···
rag-with-amazon-bedrock-and-pgve···
开源
在AWS上快速搭建生产级RAG应用,用Bedrock和PGVector搞定全套流程。
Opinionated sample on how to build/deploy a RAG web app on AWS powered by Amazon Bed···
mql
开源
说人话,出 SQL,查询数据库不再求人
MQL tool is designed to generate SQL queries directly from natural language inputs.
odoo-expert
开源
把 Odoo 海量文档变成能聊天的专家,问一句秒回答案
RAG-powered documentation assistant that converts, processes, and provides semantic ···
Rankify
开源
一站式搞定检索、重排序和 RAG,快速对比实验
Rankify: A Comprehensive Python Toolkit for Retrieval, Re-Ranking, and Retrieval-Aug···
ragapp
开源
拖拽式搭建企业级智能问答,让 RAG 应用即插即用
The easiest way to use Agentic RAG in any enterprise