HippoRAG 2 — 架构与原理

30 秒导读： HippoRAG 2 是给大模型用的"长期记忆"框架。它把你喂进去的文档离线抽成一张知识图谱（节点=实体和段落，边=文档里的事实关系 + 同义词关系）；提问时，先让检索模型和大模型挑出几条最相关的"事实"当种子，再在图上跑个性化 PageRank（PPR）让相关性顺着边扩散，最终排出该读哪些段落。一句话：用图上的"联想"补足普通向量检索抓不到的多跳关联。

本项目较复杂（离线建图 + 在线图检索两大子系统，多种模型后端），故拆成多文件。本页是 Layer 0/1：先讲"这是什么"，再给顶层全景和阅读地图。深入细节见各章节。

1. 这是什么（零基础也能懂）

一句话定义

HippoRAG 2 是一个 RAG（检索增强生成）框架：在普通"向量检索"之外，额外建一张 知识图谱，让检索能沿着实体之间的关系"联想"，从而回答需要跨多篇文档拼接的问题。

它要解决谁的什么问题

普通 RAG（把每段文字编码成向量、按相似度取最近的几段）在一类问题上很吃亏——多跳问题（multi-hop）：

问："斯坦福大学创始人的妻子叫什么？"

答案往往分散在两篇文档里：一篇说"斯坦福由 Leland Stanford 创办"，另一篇说"Leland Stanford 的妻子是 Jane Stanford"。问题本身和第二篇几乎没有词面相似度，普通向量检索抓不到它。HippoRAG 2 的图谱能从"斯坦福"这个实体出发，顺着边走到"Leland Stanford"，再走到"Jane Stanford"，把两篇都捞上来。

它面向的是**要给大模型装"能联想的长期记忆"**的人：做知识库问答、企业内文档助手、需要把大量零散资料整合起来回答的场景。

它能做什么

建索引（index）：把一批文档抽成三元组、连成知识图谱并存好。
检索（retrieve）：给一个问题，返回排好序的相关段落。
问答（rag_qa）：检索 + 让大模型基于检索到的段落生成答案，可选算 EM/F1 指标。
多步检索（IRCoT）：检索一轮 → 让大模型想一步 → 再检索，循环逼近多跳答案。
增量维护：支持往图里增删文档（index / delete），无需全量重建。

用起来什么样

最小可运行流程（来自 README.md Quick Start）：

from hipporag import HippoRAG

docs = ["George Rankin is a politician."]
queries = ["What is George Rankin's occupation?"]

hipporag = HippoRAG(
    save_dir="outputs",
    llm_model_name="gpt-4o-mini",
    embedding_model_name="text-embedding-3-small",
)
hipporag.index(docs=docs)                 # 离线：抽三元组、建图
results = hipporag.rag_qa(queries=queries) # 在线：检索 + 生成答案

对外就两步：index() 喂文档，rag_qa() 提问。图谱、向量库、缓存都落在 save_dir 下，第二次跑会自动复用。

一句话直觉 / 类比

项目名来自大脑的海马体（hippocampus）——人类形成新记忆、并把相关记忆"串联联想"的关键器官。把 HippoRAG 的组件对应到这套神经学隐喻（这是论文和代码共用的心智模型）：

HippoRAG 组件	大脑类比	干的事
知识图谱（实体+段落节点）	海马体索引	记住"谁和谁有关系"
段落语料 / 大模型	新皮层	存原始知识、做语言理解
检索编码器（linking）	海马旁回	把问题对上图里的入口
事实过滤器（识别记忆）	海马体识别记忆	判断"这条事实和问题真的相关吗"
个性化 PageRank	记忆的"扩散激活"	从种子实体出发，让相关性顺着关系蔓延

本节不碰底层代码。记住一件事：HippoRAG = 向量检索 + 一张能"联想"的图。

2. 顶层全景（它大概怎么转）

系统分离线和在线两条主线。离线把文档变成图，在线拿图回答问题。

2.1 全景图

           离线（index，建一次，复用多次）
  文档 ──► OpenIE 抽取 ──► 实体/段落/事实 三种向量 ──► 连边成图 ──► 存盘
         (NER+三元组)      (分开编码存储)         (事实边/段落边/同义边)  (graph.pickle)

  ─────────────────────────────────────────────────────────────────────

           在线（retrieve / rag_qa，每个问题跑一遍）
  问题 ──► ① 事实打分 ──► ② 识别记忆过滤 ──► ③ 图上跑 PPR ──► ④ 排段落 ──► 大模型答
         (query vs 事实)  (大模型挑≤5条)     (种子扩散激活)   (top-k)     (读段落生成)
                                │
                        没挑到事实 → 退回纯向量检索(DPR)

怎么读这张图：从左到右是数据流。上半是离线一次性建图；下半是每次提问都走的四步检索。第②步挑不出事实时，系统"降级"成普通向量检索，保证不会比普通 RAG 更差（这是它"不牺牲简单任务"的设计）。

2.2 部件一句话职责

部件	干什么	在哪个文件
`HippoRAG`	最高层门面：index / retrieve / rag_qa 全在这	`src/hipporag/HippoRAG.py`
`OpenIE`	对每段文字做 NER + 三元组抽取	`src/hipporag/information_extraction/openie_openai.py`
`EmbeddingStore`	存段落/实体/事实三类向量（默认 Parquet 文件）	`src/hipporag/embedding_store.py`
`igraph.Graph`	骨干知识图谱，跑 PPR 的地方	`HippoRAG.py`（`initialize_graph` / `run_ppr`）
`DSPyFilter`	识别记忆：用大模型过滤候选事实	`src/hipporag/rerank.py`
`BaseConfig`	唯一的全局配置（所有超参在这）	`src/hipporag/utils/config_utils.py`
`BaseEmbeddingModel` / `BaseLLM`	可插拔的向量模型 / 大模型后端	`src/hipporag/embedding_model/` · `src/hipporag/llm/`

2.3 主线走一遍（高层，不进代码）

离线：index(docs) → 切块 → 每块抽实体和三元组 → 把"段落文本 / 实体名 / 事实字符串"分别编码成向量 → 三元组的两个实体互相连边（事实边）、段落连到它含的实体（段落边）、语义相近的实体互连（同义边）→ 存成 graph.pickle（HippoRAG.py:262 index）。

在线：retrieve(query) → 问题编码 → 和所有"事实"向量算相似度打分 → 取分最高的几条候选事实、交给大模型过滤留下真正相关的 → 用这些事实里的实体当"种子"给图上节点赋权、叠加向量检索给段落的权重 → 跑个性化 PageRank 让权重扩散 → 按 PPR 分数排段落返回（HippoRAG.py:418 retrieve）。

看懂这张"大盘"后，去各章看每一步的原理与代码。

3. 阅读地图（建议顺序）

本子库按"由浅入深"拆成三章，建议顺序读：

01-indexing-openie-graph.md — 离线建索引。 讲清"文档怎么变成一张图"：OpenIE 抽三元组、三种节点/三种边的含义、同义边和增量更新的技巧。想知道"图长什么样、边的权重怎么来"看这章。
02-online-retrieval-ppr.md — 在线检索。 HippoRAG 的心脏：事实打分 → 识别记忆过滤 → 个性化 PageRank 扩散 → 出段落，以及"没事实就退回向量检索"的降级逻辑。想知道"多跳到底怎么实现的"看这章。
03-deep-dive-and-map.md — 深入与导航。 PPR 种子权重的 IDF 式设计、识别记忆的 DSPy 提示、边界与已知坑、和普通向量 RAG / GraphRAG 的取舍对比，末尾是代码地图（symbol 级跳转表）。

如果你只想要一句话结论：HippoRAG 2 的独特价值在第 2 章的"事实种子 + PPR 扩散"——这是它区别于普通向量 RAG 的全部秘密。

1. 这是什么（零基础也能懂）​

一句话定义​

它要解决谁的什么问题​

它能做什么​

用起来什么样​

一句话直觉 / 类比​

2. 顶层全景（它大概怎么转）​

2.1 全景图​

2.2 部件一句话职责​

2.3 主线走一遍（高层，不进代码）​

3. 阅读地图（建议顺序）​