HippoRAG 2：从 RAG 到记忆

HippoRAG 2 是一个强大的 LLM 记忆框架，能够增强模型识别和利用新知识中关联的能力——这正是人类长期记忆的核心功能。

我们的实验表明，即使在最先进的 RAG 系统中，HippoRAG 2 也能提升联想能力（多跳检索）和意义构建能力（整合庞大复杂上下文的过程），同时不会降低其在简单任务上的表现。

与前代产品类似，HippoRAG 2 在在线处理过程中保持了较低的成本和延迟，而在离线索引方面，相比 GraphRAG、RAPTOR 和 LightRAG 等基于图的解决方案，所需资源则显著减少。

图 1： 对持续学习能力的评估涵盖三个关键维度：事实记忆（NaturalQuestions、PopQA）、意义构建（NarrativeQA）以及联想能力（MuSiQue、2Wiki、HotpotQA 和 LV-Eval）。HippoRAG 2 在所有类别中均优于其他方法，使其距离真正的长期记忆更近一步。

图 2： HippoRAG 2 的方法论。

更多信息请参阅我们的论文：

• HippoRAG：受神经生物学启发的大语言模型长期记忆 [NeurIPS '24]。
• 从 RAG 到记忆：大语言模型的非参数化持续学习 [ICML '25]。

---

安装

conda create -n hipporag python=3.10
conda activate hipporag
pip install hipporag

初始化环境变量并激活环境：

export CUDA_VISIBLE_DEVICES=0,1,2,3
export HF_HOME=<Huggingface 主目录路径>
export OPENAI_API_KEY=<您的 OpenAI API 密钥>   # 如果您想使用 OpenAI 模型

conda activate hipporag

快速入门

OpenAI 模型

以下示例将展示如何使用任何 OpenAI 模型来运行 hipporag：

from hipporag import HippoRAG

# 准备数据集和评估
docs = [
    "奥利弗·巴德曼是一位政治家。",
    "乔治·兰金是一位政治家。",
    "托马斯·马维克是一位政治家。",
    "灰姑娘参加了王室舞会。",
    "王子用丢失的玻璃鞋在整个王国寻找。",
    "当鞋子完美契合时，灰姑娘与王子重逢了。",
    "埃里克·霍特的出生地是蒙特贝洛。",
    "玛丽娜出生于明斯克。",
    "蒙特贝洛属于洛克兰县。"
]

save_dir = 'outputs' # 定义 HippoRAG 对象的保存目录（每种 LLM/嵌入模型组合都会创建一个新的子目录）
llm_model_name = 'gpt-4o-mini' # 任何 OpenAI 模型名称
embedding_model_name = 'nvidia/NV-Embed-v2' # 嵌入模型名称（目前支持 NV-Embed、GritLM 或 Contriever）

# 启动一个 HippoRAG 实例
hipporag = HippoRAG(save_dir=save_dir, 
                    llm_model_name=llm_model_name,
                    embedding_model_name=embedding_model_name) 

# 运行索引
hipporag.index(docs=docs)

# 分离式检索与问答
queries = [
    "乔治·兰金的职业是什么？",
    "灰姑娘是如何迎来幸福结局的？",
    "埃里克·霍特的出生地属于哪个县？"
]

retrieval_results = hipporag.retrieve(queries=queries, num_to_retrieve=2)
qa_results = hipporag.rag_qa(retrieval_results)

# 检索与问答一体化
rag_results = hipporag.rag_qa(queries=queries)

# 用于评估
answers = [
    ["政治家"],
    ["通过参加舞会。"],
    ["洛克兰县"]
]

gold_docs = [
    ["乔治·兰金是一位政治家。"],
    ["灰姑娘参加了王室舞会。",
    "王子用丢失的玻璃鞋在整个王国寻找。",
    "当鞋子完美契合时，灰姑娘与王子重逢了。"],
    ["埃里克·霍特的出生地是蒙特贝洛。",
    "蒙特贝洛属于洛克兰县。"]
]

rag_results = hipporag.rag_qa(queries=queries, 
                              gold_docs=gold_docs,
                              gold_answers=answers)

示例（兼容 OpenAI 的嵌入模型）

如果您希望使用与 OpenAI 兼容的 LLM 和嵌入模型，请采用以下方法。

hipporag = HippoRAG(save_dir=save_dir, 
    llm_model_name='您的 LLM 模型名称',
    llm_base_url='您的 LLM 模型 URL',
    embedding_model_name='您的嵌入模型名称',  
    embedding_base_url='您的嵌入模型 URL')

本地部署（vLLM）

以下示例将展示如何使用任何兼容 vLLM 的本地部署 LLM 来运行 hipporag。

1. 使用指定的 GPU 运行一个本地的 兼容 OpenAI 的 vLLM 服务器，并确保为您的嵌入模型留出足够的内存。

export CUDA_VISIBLE_DEVICES=0,1
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export HF_HOME=<Huggingface 主目录路径>

conda activate hipporag  # vllm 应该在此环境中

# 如果出现 OOM 错误，可调整 gpu-memory-utilization 或 max_model_len 以适应您的 GPU 内存
vllm serve meta-llama/Llama-3.3-70B-Instruct --tensor-parallel-size 2 --max_model_len 4096 --gpu-memory-utilization 0.95 

2. 现在您可以使用与上述代码非常相似的方式来运行 hipporag：

save_dir = 'outputs' # 定义 HippoRAG 对象的保存目录（每种 LLM/嵌入模型组合都会创建一个新的子目录）
llm_model_name = # 任何 OpenAI 模型名称
embedding_model_name = # 嵌入模型名称（目前支持 NV-Embed、GritLM 或 Contriever）
llm_base_url= # 您部署的 LLM 的基础 URL（例如 http://localhost:8000/v1）

hipporag = HippoRAG(save_dir=save_dir,
                    llm_model_name=llm_model,
                    embedding_model_name=embedding_model_name,
                    llm_base_url=llm_base_url)

# 索引、检索和问答流程与运行 OpenAI 模型时相同

测试

在向 HippoRAG 贡献代码时，请运行以下脚本，以确保您的更改不会导致我们核心模块出现意外行为。

这些脚本会测试索引构建、图加载、文档删除以及对 HippoRAG 对象的增量更新功能。

OpenAI 测试

要使用 OpenAI 的 LLM 和嵌入模型测试 HippoRAG，只需运行以下命令。此测试的成本可以忽略不计。

export OPENAI_API_KEY=<您的 OpenAI API 密钥> 

conda activate hipporag

python tests_openai.py

本地测试

要在本地进行测试，您需要部署一个 vLLM 实例。为了降低测试成本，我们选择部署较小的 8B 模型 Llama-3.1-8B-Instruct。

export CUDA_VISIBLE_DEVICES=0
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export HF_HOME=<HuggingFace 家目录路径>

conda activate hipporag  # vllm 应该安装在这个环境中

# 如果出现 OOM 错误，请调整 gpu-memory-utilization 或 max_model_len 以适应您的 GPU 内存
vllm serve meta-llama/Llama-3.1-8B-Instruct --tensor-parallel-size 2 --max_model_len 4096 --gpu-memory-utilization 0.95 --port 6578

然后，我们运行以下测试脚本：

CUDA_VISIBLE=1 python tests_local.py

复现我们的实验

要使用我们的代码运行实验，我们建议您克隆此仓库，并按照 main.py 脚本的结构进行操作。

用于复现的数据

我们在论文中评估了多个采样数据集，其中一些已经包含在本仓库的 reproduce/dataset 目录中。完整的数据集请访问我们的 HuggingFace 数据集，并将它们放置在 reproduce/dataset 目录下。我们还提供了针对 musique 样本的 OpenIE 结果，分别使用 gpt-4o-mini 和 Llama-3.3-70B-Instruct 模型，存储在 outputs/musique 目录中。

为了测试您的环境是否正确配置，您可以使用小数据集 reproduce/dataset/sample.json 进行调试，如下所示。

运行索引构建与问答

首先初始化环境变量并激活环境：

export CUDA_VISIBLE_DEVICES=0,1,2,3
export HF_HOME=<HuggingFace 家目录路径>
export OPENAI_API_KEY=<您的 OpenAI API 密钥>   # 如果您想使用 OpenAI 模型

conda activate hipporag

使用 OpenAI 模型运行

dataset=sample  # 或者 `reproduce/dataset` 下的其他数据集

# 运行 OpenAI 模型
python main.py --dataset $dataset --llm_base_url https://api.openai.com/v1 --llm_name gpt-4o-mini --embedding_name nvidia/NV-Embed-v2

使用 vLLM (Llama) 运行

1. 如上所述，启动一个本地的 兼容 OpenAI 的 vLLM 服务器，并指定 GPU。

export CUDA_VISIBLE_DEVICES=0,1
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export HF_HOME=<HuggingFace 家目录路径>

conda activate hipporag  # vllm 应该安装在这个环境中

# 如果出现 OOM 错误，请调整 gpu-memory-utilization 或 max_model_len 以适应您的 GPU 内存
vllm serve meta-llama/Llama-3.3-70B-Instruct --tensor-parallel-size 2 --max_model_len 4096 --gpu-memory-utilization 0.95 

2. 在另一个终端中，使用其他 GPU 运行主程序。

export CUDA_VISIBLE_DEVICES=2,3  # 设置其他 GPU，同时 vLLM 服务器正在运行
export HF_HOME=<HuggingFace 家目录路径>
dataset=sample

python main.py --dataset $dataset --llm_base_url http://localhost:8000/v1 --llm_name meta-llama/Llama-3.3-70B-Instruct --embedding_name nvidia/NV-Embed-v2

高级：使用 vLLM 离线批处理模式

vLLM 提供了 离线批处理模式，可以实现更快的推理速度，相比在线 vLLM 服务器，索引构建速度可提升 3 倍以上。

1. 使用以下命令以 vLLM 离线批处理模式运行主程序。

export CUDA_VISIBLE_DEVICES=0,1,2,3 # 使用所有 GPU 加速离线索引
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export HF_HOME=<HuggingFace 家目录路径>
export OPENAI_API_KEY=''
dataset=sample

python main.py --dataset $dataset --llm_name meta-llama/Llama-3.3-70B-Instruct --openie_mode offline --skip_graph

2. 第一步完成后，OpenIE 结果将保存到文件中。随后按照“使用 vLLM (Llama) 运行”部分的说明，重新启动 vLLM 在线服务器和主程序。

调试注意事项

• /reproduce/dataset/sample.json 是专门用于调试的小数据集。
• 在调试 vLLM 离线模式时，请将 hipporag/llm/vllm_offline.py 中的 tensor_parallel_size 设置为 1。
• 如果您想重新运行某个实验，请务必清除已保存的文件，包括 OpenIE 结果和知识图谱，例如：

rm reproduce/dataset/openie_results/openie_sample_results_ner_meta-llama_Llama-3.3-70B-Instruct_3.json
rm -rf outputs/sample/sample_meta-llama_Llama-3.3-70B-Instruct_nvidia_NV-Embed-v2

自定义数据集

要设置您自己的自定义数据集进行评估，请遵循 reproduce/dataset/sample_corpus.json 中显示的格式和命名规范（您的数据集名称后应加上 _corpus.json）。如果要运行带有预定义问题的实验，应根据查询文件 reproduce/dataset/sample.json 组织您的查询语料库，并确保也遵循我们的命名规范。

语料库和可选的查询 JSON 文件应具有以下格式：

检索语料库 JSON

[
  {
    "title": "第一条文档标题",
    "text": "第一条文档内容",
    "idx": 0
  },
  {
    "title": "第二条文档标题",
    "text": "第二条文档内容",
    "idx": 1
  }
]

（可选）查询 JSON

[
  {
    "id": "sample/question_1.json",
    "question": "问题内容",
    "answer": [
      "答案内容"
    ],
    "answerable": true,
    "paragraphs": [
      {
        "title": "{第一支持文档标题}",
        "text": "{第一支持文档内容}",
        "is_supporting": true,
        "idx": 0
      },
      {
        "title": "{第二支持文档标题}",
        "text": "{第二支持文档内容}",
        "is_supporting": true,
        "idx": 1
      }
    ]
  }
]

（可选）语料分块

在准备数据时，您可能需要对每条文档进行分块，因为较长的文档可能会使 OpenIE 处理变得过于复杂。

代码结构

📦 .
│-- 📂 src/hipporag
│   ├── 📂 embedding_model          # 所有嵌入模型的实现
│   │   ├── __init__.py             # 获取特定嵌入模型类的工厂函数
|   |   ├── base.py                 # 嵌入模型基类 `BaseEmbeddingModel` 及其配置类 `EmbeddingConfig`
|   |   ├── NVEmbedV2.py            # NV-Embed-v2 模型的实现
|   |   ├── ...
│   ├── 📂 evaluation               # 所有评估指标的实现
│   │   ├── __init__.py
|   |   ├── base.py                 # 评估指标基类 `BaseMetric`
│   │   ├── qa_eval.py              # 问答任务的评估指标
│   │   ├── retrieval_eval.py       # 检索任务的评估指标
│   ├── 📂 information_extraction  # 所有信息抽取模型的实现
│   │   ├── __init__.py
|   |   ├── openie_openai_gpt.py    # 使用 OpenAI GPT 的 OpenIE 模型
|   |   ├── openie_vllm_offline.py  # 使用本地部署的 vLLM 模型进行 OpenIE
│   ├── 📂 llm                      # 大语言模型推理相关的类
│   │   ├── __init__.py             # 工厂函数
|   |   ├── base.py                 # 大语言模型推理的配置类及基类
|   |   ├── openai_gpt.py           # 使用 OpenAI GPT 进行推理的类
|   |   ├── vllm_llama.py           # 使用本地 vLLM 服务器进行推理的类
|   |   ├── vllm_offline.py         # 直接使用 vLLM API 进行推理的类
│   ├── 📂 prompts                  # 提示模板及提示模板管理器类
|   │   ├── 📂 dspy_prompts         # 过滤相关的提示
|   │   │   ├── ...
|   │   ├── 📂 templates            # 提示模板管理器可加载的所有提示模板
|   │   │   ├── README.md           # 提示模板管理器及提示模板文件的使用说明
|   │   │   ├── __init__.py
|   │   │   ├── triple_extraction.py
|   │   │   ├── ...
│   │   ├── __init__.py
|   |   ├── linking.py              # 链接相关的指令
|   |   ├── prompt_template_manager.py  # 提示模板管理器的实现
│   ├── 📂 utils                    # 本仓库中通用的工具函数（文件名表明其用途）
│   │   ├── config_utils.py         # 所有模块共用一个配置，此处定义其设置
|   |   ├── ...
│   ├── __init__.py
│   ├── HippoRAG.py          # 最高层次的类，用于启动检索、问答和评估流程
│   ├── embedding_store.py   # 存储库，用于加载、管理和保存段落、实体和事实的嵌入向量。
│   ├── rerank.py            # 重排序和过滤方法
│-- 📂 examples
│   ├── ...
│   ├── ...
│-- 📜 README.md
│-- 📜 requirements.txt   # 依赖列表
│-- 📜 .gitignore         # 需要从 Git 中排除的文件

联系方式

如有任何问题或疑问，请提交 issue 或联系以下人员：

Bernal Jiménez Gutiérrez、
Yiheng Shu、
Yu Su，
俄亥俄州立大学

引用

如果您觉得这项工作对您有所帮助，请考虑引用我们的论文：

HippoRAG 2

@misc{gutiérrez2025ragmemorynonparametriccontinual,
      title={从 RAG 到记忆：大语言模型的非参数持续学习}, 
      author={Bernal Jiménez Gutiérrez、Yiheng Shu、Weijian Qi、Sizhe Zhou、Yu Su},
      year={2025},
      eprint={2502.14802},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2502.14802}, 
}

HippoRAG

@inproceedings{gutiérrez2024hipporag,
      title={HippoRAG：受神经生物学启发的大语言模型长期记忆}, 
      author={Bernal Jiménez Gutiérrez、Yiheng Shu、Yu Gu、Michihiro Yasunaga、Yu Su},
      booktitle={第三十八届神经信息处理系统年会},
      year={2024},
      url={https://openreview.net/forum?id=hkujvAPVsg}

待办事项：

• 增加对更多嵌入模型的支持
• 增加对嵌入端点的支持
• 增加对向量数据库集成的支持

如果您有任何问题或建议，欢迎随时提交 issue 或 pull request。

HippoRAG 2 快速上手指南

HippoRAG 2 是一个强大的大语言模型（LLM）记忆框架，旨在增强模型识别和利用新知识之间关联的能力。相比传统的 RAG 系统，它在多跳检索（associativity）和复杂上下文整合（sense-making）方面表现更佳，同时保持了高效的索引速度和较低的资源消耗。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐) 或 macOS
• Python 版本: 3.10
• GPU: 推荐使用 NVIDIA GPU（用于加速嵌入模型和本地 LLM 部署），需安装 CUDA 驱动。
• API Key: 如果使用 OpenAI 模型，需准备 OPENAI_API_KEY。
• Hugging Face: 建议配置 HF_HOME 环境变量以缓存模型文件。

国内开发者提示：

• 下载 Hugging Face 模型时，如遇网络问题，可设置镜像加速：

  export HF_ENDPOINT=https://hf-mirror.com
  

• 安装 Python 包时，可使用清华或阿里镜像源加速 pip 安装。

安装步骤

1. 创建并激活 Conda 环境

conda create -n hipporag python=3.10
conda activate hipporag

2. 安装 HippoRAG

pip install hipporag

(注：如需加速，可添加 -i https://pypi.tuna.tsinghua.edu.cn/simple)

3. 配置环境变量

根据您的使用场景（OpenAI API 或本地部署），设置以下变量：

# 指定可用的 GPU 设备
export CUDA_VISIBLE_DEVICES=0,1,2,3

# 设置 Hugging Face 缓存目录 (可选)
export HF_HOME=<path to Huggingface home directory>

# 如果使用 OpenAI 模型，填入您的 API Key
export OPENAI_API_KEY=<your openai api key>

# 重新激活环境以确保变量生效
conda activate hipporag

基本使用

以下示例展示如何使用 HippoRAG 进行文档索引、检索和问答。

场景一：使用 OpenAI 模型

这是最简单的上手方式，适用于快速验证功能。

from hipporag import HippoRAG

# 1. 准备数据
docs = [
    "Oliver Badman is a politician.",
    "George Rankin is a politician.",
    "Thomas Marwick is a politician.",
    "Cinderella attended the royal ball.",
    "The prince used the lost glass slipper to search the kingdom.",
    "When the slipper fit perfectly, Cinderella was reunited with the prince.",
    "Erik Hort's birthplace is Montebello.",
    "Marina is bom in Minsk.",
    "Montebello is a part of Rockland County."
]

save_dir = 'outputs' # 保存目录
llm_model_name = 'gpt-4o-mini' # LLM 模型名称
embedding_model_name = 'nvidia/NV-Embed-v2' # 嵌入模型名称

# 2. 初始化 HippoRAG 实例
hipporag = HippoRAG(save_dir=save_dir, 
                    llm_model_name=llm_model_name,
                    embedding_model_name=embedding_model_name) 

# 3. 执行索引 (Indexing)
hipporag.index(docs=docs)

# 4. 执行检索与问答 (Retrieval & QA)
queries = [
    "What is George Rankin's occupation?",
    "How did Cinderella reach her happy ending?",
    "What county is Erik Hort's birthplace a part of?"
]

# 方式 A: 分步执行 (先检索，后问答)
retrieval_results = hipporag.retrieve(queries=queries, num_to_retrieve=2)
qa_results = hipporag.rag_qa(retrieval_results)

# 方式 B: 一步执行 (直接获取最终答案)
rag_results = hipporag.rag_qa(queries=queries)

print(rag_results)

场景二：使用兼容 OpenAI 格式的本地/第三方模型

如果您使用的是本地部署的 vLLM 或其他兼容 OpenAI API 的服务，请按以下方式初始化：

hipporag = HippoRAG(save_dir=save_dir, 
    llm_model_name='Your LLM Model name',
    llm_base_url='Your LLM Model url',       # 例如：http://localhost:8000/v1
    embedding_model_name='Your Embedding model name',  
    embedding_base_url='Your Embedding model url') # 如果嵌入模型也是 API 服务

场景三：本地部署 (vLLM + Llama)

对于需要数据隐私或离线运行的场景，可以使用 vLLM 部署本地模型。

第一步：启动 vLLM 服务 在终端中运行以下命令启动本地 LLM 服务器（确保显存充足）：

export CUDA_VISIBLE_DEVICES=0,1
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export HF_HOME=<path to Huggingface home directory>

conda activate hipporag

# 启动服务，根据显存调整 --gpu-memory-utilization
vllm serve meta-llama/Llama-3.3-70B-Instruct --tensor-parallel-size 2 --max_model_len 4096 --gpu-memory-utilization 0.95 

第二步：运行 Python 代码 在另一个终端或脚本中，指向本地服务地址：

save_dir = 'outputs'
llm_model_name = 'meta-llama/Llama-3.3-70B-Instruct'
embedding_model_name = 'nvidia/NV-Embed-v2'
llm_base_url = 'http://localhost:8000/v1' # 本地 vLLM 地址

hipporag = HippoRAG(save_dir=save_dir,
                    llm_model_name=llm_model_name,
                    embedding_model_name=embedding_model_name,
                    llm_base_url=llm_base_url)

# 后续操作与 OpenAI 示例相同
hipporag.index(docs=docs)
rag_results = hipporag.rag_qa(queries=queries)