HippoRAG

给 RAG 装上记忆图谱,多跳问答一次串起来

开源 🏷️完全免费 🔧 仅开源项目,无在线服务,需自行部署 搜索知识 🍴 复刻 441 🐛 待处理 9 👀 关注 29
GitHub ↗
GitHub 星标 ★ 4125
维护状态 维护中
是否开源 开源
定价模式 🏷️完全免费 开源免费,论文发表于NeurIPS'24

项目预览

HippoRAG 项目界面预览图
图片来源:GitHub 官方仓库名片

项目数据

分类搜索知识
开发团队OSU-NLP-Group
定价模式🏷️完全免费
价格说明开源免费,论文发表于NeurIPS'24
访问状态🔧 仅开源项目,无在线服务,需自行部署
是否开源是
开源协议MIT
主要语言Python
GitHub 星标★ 4125
上线时间2024-05-23 00:00:00
代码更新2026-10-06
仓库体积85.6 MB
本站数据更新2026-11-15
维护状态维护中
收录时间2026-10-02
浏览次数3

项目介绍

HippoRAG 是 NeurIPS 2024 收录的检索增强生成(RAG)框架,灵感来自人类长期记忆机制。传统 RAG 每次查询只能从外部文档中零散检索片段,难以跨文档整合知识,也无法随新文档持续更新记忆。HippoRAG 将知识图谱与个性化 PageRank 结合:先把文档抽取成实体和关系构成图谱,查询时用 Personalized PageRank 在图谱上扩散激活,找到与问题最相关的多跳证据,再交给 LLM 生成答案。它解决了多跳问答、跨文档知识整合和增量式知识更新问题,在需要串联多个事实才能回答的场景下比朴素向量检索更准。核心能力包括图谱构建、图检索、单步多跳推理,以及无需重训即可持续吸收新文档。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化,观测越久曲线越完整

数据来源:GitHub API 逐日快照 · 收录于 2026-10-02 · 当前星标 ★ 4125

使用教程

ℹ 本教程由 AI 依据该项目 README 整理,个别步骤可能需要按你的环境微调。

难度:进阶 约 20 分钟 部署方式:本地安装 8 步

环境要求

  • 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. 1创建虚拟环境

    用 Conda 建一个 Python 3.10 环境并激活;开发场景推荐用 uv 建项目内 .venv。

    conda create -n hipporag python=3.10
    conda activate hipporag
  2. 2安装 HippoRAG

    直接用 pip 从包索引安装发布版;如需改源码则改用 uv 可编辑安装。

    pip install hipporag
  3. 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. 4按需装本地模型支持

    只在要用 vLLM 或 GritLM 等本地模型时安装对应可选依赖,否则跳过。

    uv pip install -e '.[vllm]'
  5. 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. 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. 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
  8. 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 Keyxxxxxxxxxxxxxxxx
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

上一篇:RAG-Anything

下一篇:rag-postgres-openai-python

同类项目推荐

trieve 开源

一个 API 搞定搜索、推荐和 RAG,快速构建智能应用

All-in-one platform for search, recommendations, RAG, and analytics offered via API

★ 2725 2026-08-09
cognito-ai-search 开源

开源引擎配上大模型,搜得全又答得明白

Powerful search page powered by LLMs and SearXNG

★ 284 2026-08-09
DataMind 开源

一个框架搞定 RAG、图检索、NL2SQL 和记忆

All-in-one intelligent assistant powered by LlamaIndex — RAG, GraphRAG, NL2SQL, Ski···

★ 456 2026-09-18
EpsteinFiles-RAG 开源

用自然语言检索海量文档,快速获得精准答案

A RAG pipeline implementation built on the 'Epstein Files 20K' dataset from Hugging ···

★ 386 2026-08-09
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···

★ 102 2026-08-09
mql 开源

说人话,出 SQL,查询数据库不再求人

MQL tool is designed to generate SQL queries directly from natural language inputs.

★ 215 2026-08-09
odoo-expert 开源

把 Odoo 海量文档变成能聊天的专家,问一句秒回答案

RAG-powered documentation assistant that converts, processes, and provides semantic ···

★ 101 2026-08-09
Rankify 开源

一站式搞定检索、重排序和 RAG,快速对比实验

Rankify: A Comprehensive Python Toolkit for Retrieval, Re-Ranking, and Retrieval-Aug···

★ 683 2026-08-09
ragapp 开源

拖拽式搭建企业级智能问答,让 RAG 应用即插即用

The easiest way to use Agentic RAG in any enterprise

★ 4441 2026-08-09