1 项目概述

HippoRAG（海马体RAG）是一个受神经生物学启发的强大图结构RAG框架，能够使大型语言模型（LLM）识别并利用新知识中的关联信息，从而改进检索效果。资料来源：README.md

当前版本为 HippoRAG 2，该版本实现了从传统RAG到记忆系统的跨越，引入非参数持续学习（Non-Parametric Continual Learning）能力。资料来源：README.md:1

1.1 项目版本信息

资料来源：setup.py:1-12

2 项目背景与动机

2.1 传统RAG的局限性

传统检索增强生成（RAG）系统在处理需要跨段落关联推理的问题时存在明显不足。当用户查询需要关联多个分散的知识片段时，传统方法往往难以有效整合相关信息。

2.2 HippoRAG的解决方案

HippoRAG从人类海马体的记忆机制中汲取灵感，构建了一个能够模拟人类长期记忆关联特性的图结构知识库。该系统能够：

• 在新知识中识别和利用关联信息
• 改进跨段落的事实检索能力
• 支持多跳推理和关联问答

资料来源：README.md

3 系统架构

3.1 整体架构图

graph TD
    subgraph 输入层
        A[文档输入] --> B[OpenIE信息抽取]
        B --> C[知识图谱构建]
    end
    
    subgraph 处理层
        C --> D[嵌入模型编码]
        D --> E[向量索引]
    end
    
    subgraph 检索层
        E --> F[Personalized PageRank检索]
        F --> G[关联节点链接]
    end
    
    subgraph 问答层
        G --> H[LLM问答]
        H --> I[答案输出]
    end

3.2 核心模块说明

HippoRAG项目采用模块化设计，核心代码位于src/hipporag目录下。资料来源：README.md

资料来源：README.md

4 核心功能特性

4.1 支持的模型类型

HippoRAG支持多种LLM和嵌入模型部署方式：资料来源：README.md

4.2 支持的嵌入模型

• NV-Embed-v2：NVIDIA开发的嵌入模型
• GritLM：专门用于检索的嵌入模型
• Contriever：基于对比学习的检索模型
• OpenAI兼容模型：支持自定义嵌入端点

资料来源：README.md

4.3 知识图谱构建

系统支持构建多种类型的知识图谱：

graph LR
    A[事实节点] --> B[相似段落节点]
    B --> C[单向/双向关联]
    A --> C

图结构类型：

• facts_and_sim_passage_node_unidirectional：事实节点与相似段落节点单向关联
• 支持自定义图结构类型

资料来源：main.py:1-15

5 关键配置参数

5.1 索引构建参数

资料来源：src/hipporag/utils/config_utils.py

5.2 检索参数

资料来源：src/hipporag/utils/config_utils.py

5.3 问答参数

资料来源：src/hipporag/utils/config_utils.py

6 依赖环境

6.1 核心依赖

资料来源：setup.py:17-29

6.2 辅助依赖

资料来源：requirements.txt

7 数据格式规范

7.1 检索语料库格式

[
  {
    "title": "FIRST PASSAGE TITLE",
    "text": "FIRST PASSAGE TEXT",
    "idx": 0
  },
  {
    "title": "SECOND PASSAGE TITLE",
    "text": "SECOND PASSAGE TEXT",
    "idx": 1
  }
]

资料来源：README.md

7.2 查询数据格式（可选）

[
  {
    "id": "sample/question_1.json",
    "question": "QUESTION",
    "answer": ["ANSWER"],
    "answerable": true,
    "paragraphs": [
      {
        "title": "{SUPPORTING PASSAGE TITLE}",
        "text": "{SUPPORTING PASSAGE TEXT}",
        "is_supporting": true,
        "idx": 0
      }
    ]
  }
]

资料来源：README.md

8 使用方式

8.1 快速开始流程

graph TD
    A[初始化HippoRAG实例] --> B[准备文档数据]
    B --> C[执行索引构建]
    C --> D[执行问答查询]
    D --> E[获取评估结果]

8.2 OpenAI模型使用示例

from hipporag import HippoRAG

# 准备数据
docs = [
    "Oliver Badman is a politician.",
    "George Rankin is a politician.",
    "Erik Hort's birthplace is Montebello."
]

# 初始化实例
hipporag = HippoRAG(
    save_dir='outputs',
    llm_model_name='gpt-4o-mini',
    embedding_model_name='nvidia/NV-Embed-v2'
)

# 索引构建
hipporag.index(docs)

# 问答查询
queries = ["What is George Rankin's occupation?"]
results = hipporag.rag_qa(queries=queries)

资料来源：README.md

8.3 本地vLLM部署

1. 启动vLLM服务器：

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --tensor-parallel-size 2 \
    --max_model_len 4096 \
    --gpu-memory-utilization 0.95 \
    --port 6578

1. 使用HippoRAG：

hipporag = HippoRAG(
    save_dir=save_dir,
    llm_model_name='meta-llama/Llama-3.1-8B-Instruct',
    llm_base_url='http://localhost:6578/v1'
)

资料来源：README.md

9 相关论文

9.1 HippoRAG 2（ICML '25）

From RAG to Memory: Non-Parametric Continual Learning for Large Language Models

• 作者：Bernal Jiménez Gutiérrez, Yiheng Shu, Weijian Qi, Sizhe Zhou, Yu Su
• arXiv：2502.14802

9.2 HippoRAG（NeurIPS '24）

HippoRAG: Neurobiologically Inspired Long-Term Memory for Large Language Models

• 作者：Bernal Jiménez Gutiérrez, Yiheng Shu, Yu Gu, Michihiro Yasunaga, Yu Su
• OpenReview：hkujvAPVsg

资料来源：README.md

10 项目贡献

10.1 贡献流程

1. Fork仓库并克隆到本地
2. 创建新分支：git checkout -b my-contribution
3. 进行修改并运行测试脚本
4. 提交更改：git commit -m "Add my contribution"
5. 推送分支：git push origin my-contribution
6. 提交Pull Request

10.2 测试要求

资料来源：README.md

11 环境变量配置

资料来源：README.md

12 TODOs与未来规划

• [x] 添加更多嵌入模型支持
• [x] 添加嵌入端点支持
• [ ] 添加向量数据库集成支持

资料来源：README.md

13 致谢

本项目由俄亥俄州立大学（The Ohio State University）NLP研究组开发维护。

主要联系人：

• Bernal Jiménez Gutiérrez（[email protected]）
• Yiheng Shu（[email protected]）
• Yu Su（[email protected]）

资料来源：README.md

环境要求

系统依赖

资料来源：setup.py:8

核心依赖包

项目安装后会自动引入以下核心依赖：

资料来源：setup.py:14-27

安装步骤

方法一：使用 pip 直接安装（推荐）

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

资料来源：README.md:67-70

方法二：从源码安装

git clone https://github.com/OSU-NLP-Group/HippoRAG.git
cd HippoRAG
conda create -n hipporag python=3.10
conda activate hipporag
pip install -e .

环境变量配置

在运行项目之前，需要配置以下环境变量：

export CUDA_VISIBLE_DEVICES=0,1,2,3
export HF_HOME=<path to Huggingface home directory>
export OPENAI_API_KEY=<your openai api key>   # 仅在使用 OpenAI 模型时需要

资料来源：README.md:72-76

快速使用流程

HippoRAG 的核心使用流程分为三个阶段：初始化、索引构建、检索与问答。

graph TD
    A[初始化 HippoRAG 实例] --> B[调用 index 方法构建索引]
    B --> C[调用 rag_qa 方法进行检索问答]
    C --> D[获取检索结果和生成答案]

资料来源：README.md:78-97

使用 OpenAI 模型

以下示例展示如何使用 OpenAI 模型进行索引构建和问答检索：

from hipporag import HippoRAG

# 准备文档数据
docs = [
    "Oliver Badman is a politician.",
    "George Rankin is a politician.",
    "Cinderella attended the royal ball.",
    "The prince used the lost glass slipper to search the kingdom.",
    "Erik Hort's birthplace is Montebello.",
    "Montebello is a part of Rockland County."
]

# 定义保存目录
save_dir = 'outputs'

# 设置模型配置
llm_model_name = 'gpt-4o-mini'
embedding_model_name = 'nvidia/NV-Embed-v2'

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

# 构建索引
hipporag.index(docs=docs)

# 准备查询和评估数据
queries = [
    "What is George Rankin's occupation?",
    "How did Cinderella reach her happy ending?",
    "What county is Erik Hort's birthplace a part of?"
]

answers = [
    ["Politician"],
    ["By going to the ball."],
    ["Rockland County"]
]

gold_docs = [
    ["George Rankin 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.",
     "Montebello is a part of Rockland County."]
]

# 执行检索和问答
rag_results = hipporag.rag_qa(queries=queries, 
                              gold_docs=gold_docs,
                              gold_answers=answers)

资料来源：README.md:78-97

使用本地 vLLM 部署

#### 第一步：启动 vLLM 服务器

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

conda activate hipporag

# 根据 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

资料来源：README.md:106-113

#### 第二步：运行主程序

export CUDA_VISIBLE_DEVICES=2,3
export HF_HOME=<path to Huggingface home directory>
export OPENAI_API_KEY=<your openai api key>

python main.py --dataset sample --llm_base_url http://localhost:6578/v1 \
    --llm_name meta-llama/Llama-3.1-8B-Instruct \
    --embedding_name nvidia/NV-Embed-v2

资料来源：README.md:115-120

使用 OpenAI 兼容端点

如果使用第三方 OpenAI 兼容的 LLM 和 Embedding 服务：

hipporag = HippoRAG(save_dir=save_dir, 
    llm_model_name='Your LLM Model name',
    llm_base_url='Your LLM Model url',
    embedding_model_name='Your Embedding model name',  
    embedding_base_url='Your Embedding model url')

资料来源：README.md:100-103

使用 Azure OpenAI

hipporag = HippoRAG(save_dir=save_dir,
                    llm_model_name=llm_model_name,
                    embedding_model_name=embedding_model_name,
                    azure_endpoint="https://[ENDPOINT NAME].openai.azure.com/openai/deployments/gpt-4o-mini/chat/completions?api-version=2025-01-01-preview",
                    azure_embedding_endpoint="https://[ENDPOINT NAME].openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2023-05-15")

资料来源：demo_openai.py:1-5

核心配置参数

BaseConfig 类包含所有可配置参数，以下是常用参数说明：

资料来源：src/hipporag/utils/config_utils.py:1-50

数据集格式

检索语料库格式

[
  {
    "title": "FIRST PASSAGE TITLE",
    "text": "FIRST PASSAGE TEXT",
    "idx": 0
  },
  {
    "title": "SECOND PASSAGE TITLE",
    "text": "SECOND PASSAGE TEXT",
    "idx": 1
  }
]

资料来源：README.md:141-151

查询文件格式（可选）

[
  {
    "id": "sample/question_1.json",
    "question": "QUESTION",
    "answer": ["ANSWER"],
    "answerable": true,
    "paragraphs": [
      {
        "title": "{SUPPORTING PASSAGE TITLE}",
        "text": "{SUPPORTING PASSAGE TEXT}",
        "is_supporting": true,
        "idx": 0
      }
    ]
  }
]

资料来源：README.md:153-170

验证安装

使用 OpenAI 模型验证

export OPENAI_API_KEY=<your openai api key> 
conda activate hipporag
python tests_openai.py

资料来源：README.md:124-128

使用本地模型验证

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

conda activate hipporag

# 启动 vLLM 服务器
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

资料来源：README.md:130-144

常见问题排查

GPU 内存不足

如果遇到 OOM（内存溢出）错误，可以调整以下参数：

• 降低 gpu-memory-utilization 值（建议从 0.95 逐步下调）
• 减小 max_model_len 参数
• 减少 CUDA_VISIBLE_DEVICES 中指定的 GPU 数量

资料来源：README.md:109-112

索引构建缓慢

建议增加 embedding_batch_size 参数的值，默认值为 16，可根据 GPU 显存调整为 32 或更高。

资料来源：main.py:12

后续步骤

完成快速入门后，建议进一步阅读以下内容：

• 高级配置：调整 BaseConfig 中的参数以优化检索效果
• 增量更新：使用 index 方法对新增文档进行增量索引
• 实验复现：参考 main.py 的实现方式运行论文中的实验

概述

HippoRAG是一个受神经生物学启发的图基RAG（检索增强生成）框架，旨在使大型语言模型能够识别并利用新知识中的关联信息以改进检索效果。该系统通过模拟海马体的记忆索引机制，实现高效的持久化知识管理和关联推理能力。

HippoRAG的核心架构围绕三个主要阶段设计：索引（Indexing）、检索（Retrieval） 和 问答（QA）。系统支持多种LLM后端（OpenAI、vLLM、Azure OpenAI）和嵌入模型（NV-Embed-v2、GritLM、Contriever等），提供了灵活的部署选项。

核心模块架构

模块层次结构

HippoRAG项目采用清晰的模块化设计，各组件职责明确：

资料来源：README.md

主要类层次

HippoRAG中存在两种主要的RAG实现类：

classDiagram
    class BaseRAG {
        <<abstract>>
        +index(docs)
        +rag_qa(queries, gold_docs, gold_answers)
        +delete(docs)
    }
    class HippoRAG {
        +index(docs)
        +rag_qa(queries, gold_docs, gold_answers)
        +delete(docs)
    }
    class StandardRAG {
        +index(docs)
        +rag_qa(queries, gold_docs, gold_answers)
    }
    
    BaseRAG <|-- HippoRAG
    BaseRAG <|-- StandardRAG

HippoRAG 类提供完整的图基索引和Personalized PageRank检索能力，而 StandardRAG 类实现传统的密集检索方法。

配置系统

配置架构

HippoRAG使用Pydantic的BaseConfig类作为配置基础，提供类型安全的配置管理：

class BaseConfig(BaseModel):
    # OpenIE配置
    openie_mode: Literal['OpenAI', 'vLLM-offline', 'Transformers-offline']
    information_extraction_model_name: str
    
    # Embedding模型配置
    embedding_model_name: str
    embedding_batch_size: int = 16
    embedding_return_as_normalized: bool = True
    embedding_max_seq_len: int = 2048
    embedding_model_dtype: Literal["float16", "float32", "bfloat16", "auto"]
    
    # 图构建配置
    synonymy_edge_topk: int = 2047
    synonymy_edge_query_batch_size: int = 1000
    synonymy_edge_key_batch_size: int = 10000
    synonymy_edge_sim_threshold: float = 0.8
    
    # 检索配置
    linking_top_k: int = 5
    retrieval_top_k: int = 200
    damping: float = 0.5
    
    # QA配置
    max_qa_steps: int = 1
    qa_top_k: int = 5
    
    # 保存路径
    save_dir: str = "outputs"

资料来源：src/hipporag/utils/config_utils.py:1-100

关键配置参数

#### OpenIE模式配置

#### 嵌入模型配置

#### 图构建配置

#### 检索与QA配置

索引流程架构

索引阶段工作流

HippoRAG的索引阶段将文档转化为知识图谱，实现与海马体记忆索引类似的持久化存储：

graph TD
    A[输入文档列表] --> B[文本分割]
    B --> C[OpenIE信息抽取]
    C --> D[生成事实三元组]
    D --> E[实体节点提取]
    E --> F[构建段落节点]
    F --> G[生成实体-段落边]
    G --> H[KNN同义边构建]
    H --> I[段落相似边构建]
    I --> J[持久化图结构存储]
    
    C --> K[文档嵌入生成]
    K --> L[向量存储]

核心索引组件

HippoRAG使用embedding_store模块管理向量存储，该模块负责：

1. 文档嵌入：使用配置的嵌入模型对文档进行向量化
2. 向量索引：构建高效的向量检索索引
3. 相似度计算：支持归一化和非归一化嵌入的相似度计算

索引过程的关键调用示例：

# main.py中的索引调用
hipporag = HippoRAG(global_config=config)
hipporag.index(docs)

资料来源：main.py:1-30

检索流程架构

Personalized PageRank检索

HippoRAG采用Personalized PageRank（PPR）算法进行关联检索，区别于传统的向量相似度检索：

graph LR
    A[查询] --> B[向量相似度检索]
    B --> C[获取初始候选节点]
    C --> D[构建查询图]
    D --> E[PPR迭代计算]
    E --> F[节点重要性排序]
    F --> G[返回关联段落]

检索配置参数

检索过程中，系统通过同义边（synonymy edges）建立实体间的语义关联，实现跨段落的事实关联发现。

问答流程架构

多步推理问答

HippoRAG支持迭代式问答，通过多步检索-推理交替提升答案质量：

graph TD
    A[问题输入] --> B[Step 1: 检索相关段落]
    B --> C[Step 1: LLM推理]
    C --> D{达到最大步数?}
    D -->|否| E[基于推理结果重检索]
    E --> B
    D -->|是| F[生成最终答案]
    B --> G[Top-K段落收集]
    G --> F

QA配置参数

调用示例：

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

资料来源：README.md

部署架构

多后端支持

HippoRAG支持多种LLM和嵌入模型部署方式：

#### OpenAI模型部署

hipporag = HippoRAG(
    save_dir=save_dir,
    llm_model_name='gpt-4o-mini',
    embedding_model_name='nvidia/NV-Embed-v2'
)

#### Azure OpenAI部署

hipporag = HippoRAG(
    save_dir=save_dir,
    llm_model_name='gpt-4o-mini',
    embedding_model_name='nvidia/NV-Embed-v2',
    azure_endpoint="https://[ENDPOINT].openai.azure.com/...",
    azure_embedding_endpoint="https://[ENDPOINT].openai.azure.com/..."
)

#### vLLM本地部署

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --tensor-parallel-size 2 \
    --max_model_len 4096 \
    --gpu-memory-utilization 0.95 \
    --port 6578

hipporag = HippoRAG(
    save_dir=save_dir,
    llm_model_name='meta-llama/Llama-3.1-8B-Instruct',
    llm_model_port=6578,
    embedding_model_name='nvidia/NV-Embed-v2'
)

依赖架构

HippoRAG的核心依赖层次：

资料来源：setup.py:1-30

数据流架构

完整RAG流程

flowchart TB
    subgraph 索引阶段["索引阶段"]
        I1[加载配置] --> I2[文档预处理]
        I2 --> I3[OpenIE抽取]
        I3 --> I4[构建事实图谱]
        I4 --> I5[向量索引]
        I5 --> I6[持久化存储]
    end
    
    subgraph 检索阶段["检索阶段"]
        Q1[用户查询] --> Q2[查询向量化]
        Q2 --> Q3[向量相似度检索]
        Q3 --> Q4[初始候选集]
        Q4 --> Q5[PPR图遍历]
        Q5 --> Q6[关联段落排序]
    end
    
    subgraph QA阶段["问答阶段"]
        QA1[相关段落] --> QA2[Prompt构建]
        QA2 --> QA3[LLM推理]
        QA3 --> QA4{迭代判断}
        QA4 -->|继续| QA5[重检索]
        QA5 --> QA2
        QA4 -->|完成| QA6[答案生成]
    end
    
    I6 --> Q1
    Q6 --> QA1

项目结构

src/hipporag/
├── HippoRAG.py              # 核心HippoRAG类实现
├── StandardRAG.py           # 标准RAG实现
├── embedding_store.py       # 向量存储管理
├── __init__.py
├── embedding_model/         # 嵌入模型模块
│   ├── __init__.py
│   ├── base.py              # 基类定义
│   └── NVEmbedV2.py         # NV-Embed-v2实现
├── evaluation/              # 评估模块
│   ├── __init__.py
│   ├── base.py              # 评估基类
│   ├── qa_eval.py           # QA评估
│   └── retrieval_eval.py    # 检索评估
├── information_extraction/  # 信息抽取模块
│   ├── __init__.py
│   ├── openie_openai_gpt.py
│   └── openie_vllm_offline.py
├── llm/                     # LLM推理模块
└── utils/
    ├── __init__.py
    └── config_utils.py      # 配置工具

资料来源：README.md

总结

HippoRAG的系统架构设计体现了以下核心原则：

1. 模块化设计：各功能模块（嵌入模型、信息抽取、图构建、检索、QA）职责清晰，便于扩展和维护

1. 配置驱动：通过BaseConfig类实现类型安全的配置管理，支持多种部署场景

1. 海马体启发的持久化索引：通过OpenIE抽取事实知识并构建异构图，实现长期记忆的持久化存储

1. PPR关联检索：采用Personalized PageRank算法挖掘实体间的语义关联，克服传统向量检索的局限性

1. 多后端兼容：统一接口支持OpenAI、vLLM、Azure等多种部署方式，提高系统灵活性

核心配置参数

知识图谱构建通过BaseConfig类进行配置管理，主要涉及以下关键参数：

资料来源：config_utils.py:参数定义

图谱构建流程

知识图谱的构建遵循以下标准化流程：

graph TD
    A[原始文档输入] --> B[分块与预处理]
    B --> C[开放信息抽取 OpenIE]
    C --> D[事实三元组提取]
    C --> E[段落节点创建]
    D --> F[事实节点与段落节点连接]
    E --> F
    F --> G[嵌入向量计算]
    G --> H[同义词边构建 KNN]
    H --> I[个性化PageRank检索准备]
    I --> J[知识图谱输出]

1. 文档输入与预处理：接收原始文本语料，按照配置进行必要的分块处理
2. 开放信息抽取：使用OpenIE模型从文本中提取事实三元组（主语-谓词-宾语）
3. 节点创建：生成两类核心节点——事实节点（Fact Node）和段落节点（Passage Node）
4. 边构建：基于语义相似度和实体关联建立节点间的连接关系
5. 图谱索引：完成图结构的持久化存储，为后续检索做好准备

资料来源：README.md:代码结构

图类型配置

HippoRAG支持多种图谱拓扑结构，通过graph_type参数进行选择：

同义词边的构建采用KNN（K近邻）算法，在嵌入向量空间中寻找语义相似的节点对：

synonymy_edge_topk: int = 2047          # KNN检索的K值
synonymy_edge_query_batch_size: int = 1000   # 查询嵌入批次大小
synonymy_edge_key_batch_size: int = 10000    # 键嵌入批次大小
synonymy_edge_sim_threshold: float = 0.8    # 相似度阈值

资料来源：config_utils.py:图构建参数

开放信息抽取模式

HippoRAG支持两种OpenIE实现方式：

信息抽取模块位于src/hipporag/information_extraction/目录，包含以下实现：

• openie_openai_gpt.py：OpenAI GPT模型的OpenIE实现
• openie_vllm_offline.py：vLLM离线部署模型的OpenIE实现

资料来源：README.md:信息抽取模块

索引构建接口

HippoRAG通过HippoRAG类提供统一的索引构建接口：

from hipporag import HippoRAG

hipporag = HippoRAG(
    save_dir='outputs',
    llm_model_name='gpt-4o-mini',
    embedding_model_name='nvidia/NV-Embed-v2'
)

# 文档索引构建
hipporag.index(docs=[
    "Oliver Badman is a politician.",
    "George Rankin is a politician.",
    "Erik Hort's birthplace is Montebello."
])

配置参数可通过global_config或构造函数直接传入：

config = BaseConfig(
    graph_type="facts_and_sim_passage_node_unidirectional",
    synonymy_edge_topk=2047,
    synonymy_edge_sim_threshold=0.8,
    embedding_batch_size=8,
    openie_mode='openai-gpt',
    information_extraction_model_name='gpt-4o-mini'
)

hipporag = HippoRAG(global_config=config, ...)

资料来源：main.py:索引配置

嵌入模型配置

图谱构建过程中的向量计算支持多种嵌入模型：

嵌入相关配置参数：

资料来源：config_utils.py:嵌入配置

依赖组件

知识图谱构建依赖以下核心库：

资料来源：setup.py:依赖声明

增量更新与删除

HippoRAG支持对已构建的图谱进行增量操作：

# 添加新文档
hipporag.index(docs=["新文档内容..."])

# 删除指定文档
hipporag.delete(docs_to_delete=["要删除的文档..."])

# 验证更新效果
result = hipporag.rag_qa(queries=queries, 
                         gold_docs=gold_docs, 
                         gold_answers=answers)

增量更新会重新计算相关节点的嵌入向量，并更新图中的连接关系。

资料来源：tests_openai.py:增量操作

环境变量配置

图谱构建前需正确配置以下环境变量：

export CUDA_VISIBLE_DEVICES=0,1,2,3  # GPU设备选择
export HF_HOME=<path-to-huggingface> # HuggingFace模型缓存目录
export OPENAI_API_KEY=<your-api-key> # OpenAI API密钥（使用OpenAI模式时）

资料来源：README.md:环境配置

概述

HippoRAG的LLM模型集成模块提供了一套统一的接口，用于对接多种大语言模型提供商。该模块位于src/hipporag/llm/目录下，通过抽象基类LLMInterface定义标准接口，各具体实现类继承该基类以支持不同的模型服务。

主要支持以下模型服务：

资料来源：base.py:1-20

架构设计

类层次结构

HippoRAG采用面向对象设计模式，通过抽象基类定义统一接口规范：

graph TD
    A[LLMInterface<br/>抽象基类] --> B[OpenAIGPT]
    A --> C[VLLMOffline]
    A --> D[BedrockLLM]
    A --> E[TransformersLLM]
    
    F[调用方] --> A

接口规范

LLMInterface定义了所有LLM实现必须遵循的核心方法：

资料来源：base.py:10-60

核心实现

基础抽象类

基础类LLMInterface位于base.py，采用ABC抽象基类模式：

class LLMInterface(ABC):
    def __init__(
        self,
        model_name: str,
        api_key: str = None,
        api_base: str = None,
        timeout: int = 120,
        max_tokens: int = 256,
        temperature: float = 0.0,
        request_timeout: int = 120,
        top_p: float = 1.0,
        **kwargs
    ):

关键配置参数说明：

资料来源：base.py:10-25

OpenAI GPT集成

OpenAIGPT类封装了OpenAI API的调用逻辑：

class OpenAIGPT(LiteLLM):
    def __init__(
        self,
        model_name: str = "gpt-3.5-turbo",
        api_key: str = None,
        api_base: str = None,
        timeout: float = 120,
        max_tokens: int = 256,
        temperature: float = 0.0,
        request_timeout: int = 120,
        top_p: float = 1.0,
        **kwargs
    ):

支持的模型包括：

• gpt-4
• gpt-4-turbo
• gpt-4o
• gpt-3.5-turbo
• gpt-3.5-turbo-16k

资料来源：openai_gpt.py:15-40

vLLM离线推理

VLLMOffline类支持本地vLLM服务器推理，适用于需要离线或私有化部署的场景：

class VLLMOffline(LiteLLM):
    def __init__(
        self,
        model_name: str,
        api_base: str,
        api_key: str = "EMPTY",
        timeout: float = 120,
        max_tokens: int = 256,
        temperature: float = 0.0,
        request_timeout: int = 120,
        top_p: float = 1.0,
        **kwargs
    ):

特点：

• 默认使用api_key = "EMPTY"简化本地部署认证
• 支持批量请求提升吞吐量
• 可对接任何兼容OpenAI API格式的vLLM服务端

资料来源：vllm_offline.py:1-50

AWS Bedrock集成

BedrockLLM类提供对AWS Bedrock平台模型的支持：

class BedrockLLM(LiteLLM):
    def __init__(
        self,
        model_name: str,
        aws_access_key: str = None,
        aws_secret_key: str = None,
        aws_region_name: str = "us-east-1",
        timeout: float = 120,
        max_tokens: int = 256,
        temperature: float = 0.0,
        request_timeout: int = 120,
        top_p: float = 1.0,
        **kwargs
    ):

AWS特定配置：

支持的Bedrock模型：

• Claude系列（通过Anthropic）
• Titan系列
• Llama系列

资料来源：bedrock_llm.py:1-60

HuggingFace Transformers

TransformersLLM类支持直接使用HuggingFace transformers库进行本地推理：

class TransformersLLM(LiteLLM):
    def __init__(
        self,
        model_name: str,
        model_path: str = None,
        auth_token: str = None,
        device: str = "cuda",
        timeout: float = 120,
        max_tokens: int = 256,
        temperature: float = 0.0,
        request_timeout: int = 120,
        top_p: float = 1.0,
        **kwargs
    ):

HuggingFace特定配置：

资料来源：transformers_llm.py:1-60

使用流程

初始化与调用流程

graph TD
    A[选择LLM类型] --> B{场景需求}
    B -->|云端API| C[OpenAIGPT / BedrockLLM]
    B -->|本地推理| D{vLLM or Transformers}
    D -->|批量高吞吐| E[VLLMOffline]
    D -->|灵活部署| F[TransformersLLM]
    
    C --> G[配置API密钥和端点]
    E --> H[启动vLLM服务]
    F --> I[下载/加载模型]
    
    G --> J[实例化LLM对象]
    H --> J
    I --> J
    
    J --> K[调用__call__方法]
    K --> L[返回生成结果]

代码示例

from hipporag.llm import OpenAIGPT, VLLMOffline, TransformersLLM

# OpenAI API调用
llm = OpenAIGPT(
    model_name="gpt-4",
    api_key="your-api-key",
    temperature=0.0,
    max_tokens=256
)
response = llm("你的问题", system_prompt="你是一个助手")

# vLLM离线调用
llm_offline = VLLMOffline(
    model_name="meta-llama/Llama-2-7b-chat-hf",
    api_base="http://localhost:8000/v1",
    temperature=0.0
)
response = llm_offline("你的问题")

配置选项汇总

扩展开发

如需添加新的LLM提供商，可按以下步骤扩展：

1. 创建新文件如src/hipporag/llm/custom_llm.py
2. 继承LLMInterface抽象基类
3. 实现_call和_batch_call抽象方法
4. 在模块__init__.py中导出新类

from hipporag.llm.base import LLMInterface

class CustomLLM(LLMInterface):
    def _call(self, prompt, system_prompt, keyword):
        # 实现具体的模型调用逻辑
        pass
    
    def _batch_call(self, prompts, system_prompts, keywords):
        # 实现批量调用逻辑
        pass

注意事项

• 所有LLM实现类都继承自LiteLLM，其底层封装了lite-llm库以提供统一的调用方式
• temperature和top_p参数影响生成多样性，通常RAG场景使用temperature=0.0以获得确定性结果
• vLLM和Transformers适合需要数据隐私或控制推理环境的场景
• AWS Bedrock需要正确配置AWS凭证和区域信息

概述

HippoRAG的Embedding模型集成模块负责将文本转换为高维向量表示，以便在知识图谱构建和检索过程中进行语义相似度计算。该模块采用策略模式设计，通过抽象基类 BaseEmbeddingModel 定义统一接口，支持多种嵌入模型后端的灵活切换。资料来源：src/hipporag/embedding_model/base.py:1-20

Embedding模型在HippoRAG系统中承担三项核心职责：

• 文档编码：将输入文档、段落和实体转换为向量表示，用于构建向量存储
• 查询编码：将用户查询转换为向量，以便进行语义检索
• KNN检索：基于向量相似度进行最近邻搜索，支持同义词边构建和实体链接

架构设计

模块结构

📦 src/hipporag/embedding_model/
├── __init__.py              # 模型选择器，提供 get_embedding_model 函数
├── base.py                  # 基类 BaseEmbeddingModel 和 EmbeddingConfig
├── NVEmbedV2.py             # NVIDIA NV-Embed-v2 模型实现
├── GritLM.py                # GritLM 模型实现
├── Transformers.py          # HuggingFace Transformers 模型实现
└── VLLM.py                  # vLLM 服务嵌入模型实现

资料来源：README.md - Code Structure

类层次结构

graph TD
    A[BaseEmbeddingModel] --> B[NVEmbedV2Model]
    A --> C[GritLMModel]
    A --> D[TransformersEmbeddingModel]
    A --> E[VLLMEmbeddingModel]
    
    F[HippoRAG] --> A
    G[EmbeddingStore] --> A

嵌入模型选择流程

graph TD
    A[初始化 HippoRAG] --> B{embedding_model_name 前缀判断}
    B -->|"nvidia/NV-Embed"| C[NVEmbedV2Model]
    B -->|"GritLM/"| D[GritLMModel]
    B -->|"Transformers/"| E[TransformersEmbeddingModel]
    B -->|"VLLM/"| F[VLLMEmbeddingModel]
    B -->|其他| G[默认模型]
    
    C --> H[加载本地模型]
    D --> I[加载 GritLM]
    E --> J[加载 SentenceTransformer]
    F --> K[连接 vLLM 服务]

基础抽象类

BaseEmbeddingModel

BaseEmbeddingModel 是所有嵌入模型的基类，定义了统一的接口规范。所有具体实现必须继承此类并实现核心方法。

#### 核心属性

资料来源：src/hipporag/embedding_model/base.py:1-30

#### 核心方法

class BaseEmbeddingModel(ABC):
    @abstractmethod
    def encode(self, texts: List[str]) -> np.array:
        """将文本列表编码为嵌入向量"""
        pass
    
    def batch_encode(self, texts: List[str], **kwargs) -> np.array:
        """分批编码，默认实现为循环调用 encode"""
        pass

支持的嵌入模型

1. NV-Embed-v2

NVIDIA的NV-Embed-v2是高性能嵌入模型，支持本地部署和量化推理。

#### 初始化参数

#### 关键实现

class NVEmbedV2Model(BaseEmbeddingModel):
    def __init__(self, global_config, embedding_model_name):
        super().__init__(global_config)
        self.model_id = embedding_model_name
        self.model = AutoModel.from_pretrained(
            self.model_id,
            trust_remote_code=True,
            device_map="cuda"
        )
        self.batch_size = 32

#### 特性

• 支持 HuggingFace AutoModel 接口
• 自动设备映射到 CUDA
• 使用 trust_remote_code=True 加载自定义模型代码
• 支持批处理编码，默认批次大小为32

资料来源：src/hipporag/embedding_model/NVEmbedV2.py:1-40

2. GritLM

GritLM 是专门用于检索和生成的统一嵌入模型。

#### 初始化参数

#### 关键实现

class GritLMModel(BaseEmbeddingModel):
    def __init__(self, global_config, embedding_model_name):
        super().__init__(global_config)
        self.model_id = embedding_model_name[len("GritLM/"):]
        self.model = GritLM(model_id=self.model_id)

#### 特性

• 使用 gritlm 库实现
• 支持检索和生成双重任务
• 继承 GritLM 库的默认优化设置

资料来源：src/hipporag/embedding_model/GritLM.py:1-25

3. Transformers (HuggingFace)

通过 SentenceTransformer 支持所有 HuggingFace 模型。

#### 初始化参数

#### 关键实现

class TransformersEmbeddingModel(BaseEmbeddingModel):
    def __init__(self, global_config, embedding_model_name):
        super().__init__(global_config)
        self.model_id = embedding_model_name[len("Transformers/"):]
        self.model = SentenceTransformer(
            self.model_id,
            device="cuda" if torch.cuda.is_available() else "cpu"
        )
        self.batch_size = 64

#### 特性

• 使用 sentence-transformers 库
• 自动检测 CUDA 可用性
• 默认批处理大小为64
• 支持数千种 SentenceTransformer 模型

资料来源：src/hipporag/embedding_model/Transformers.py:1-30

4. VLLM (远程服务)

支持连接 OpenAI 兼容的 vLLM 嵌入服务端点。

#### 初始化参数

#### 关键实现

class VLLMEmbeddingModel(BaseEmbeddingModel):
    def __init__(self, global_config, embedding_model_name):
        super().__init__(global_config)
        self.model_id = embedding_model_name[len("VLLM/"):]
        self.url = global_config.embedding_base_url
    
    def call_model(self, input_text):
        payload = {
            "model": self.model_id,
            "input": input_text,
        }
        response = requests.post(self.url, json=payload)
        return np.array([response["data"][i]["embedding"] 
                        for i in range(len(response["data"]))])

#### 特性

• 通过 REST API 连接远程服务
• 使用 OpenAI 兼容的 /v1/embeddings 接口
• 支持自定义服务端点配置

资料来源：src/hipporag/embedding_model/VLLM.py:1-40

配置参数

嵌入模型相关的配置通过 BaseConfig 类管理。

嵌入模型配置项

资料来源：src/hipporag/utils/config_utils.py:1-50

使用方式

模型选择器

通过前缀自动选择对应的嵌入模型实现：

from hipporag.embedding_model import get_embedding_model

# 获取嵌入模型实例
embedding_model = get_embedding_model(
    global_config=config,
    embedding_model_name="nvidia/NV-Embed-v2"
)

#### 前缀映射表

资料来源：src/hipporag/embedding_model/__init__.py:1-30

完整使用示例

#### OpenAI 兼容模型

from hipporag import HippoRAG

hipporag = HippoRAG(
    save_dir="outputs",
    llm_model_name="gpt-4o-mini",
    llm_base_url="https://api.openai.com/v1",
    embedding_model_name="nvidia/NV-Embed-v2",
    embedding_base_url="https://api.openai.com/v1"
)

# 执行索引和检索
hipporag.index(docs=documents)
results = hipporag.rag_qa(queries=queries)

#### 本地 vLLM 模型

# 启动 vLLM 嵌入服务
vllm serve nvidia/NV-Embed-v2 --port 8080

hipporag = HippoRAG(
    save_dir="outputs",
    llm_model_name="meta-llama/Llama-3.1-8B-Instruct",
    llm_base_url="http://localhost:6578/v1",
    embedding_model_name="VLLM/nvidia/NV-Embed-v2",
    embedding_base_url="http://localhost:8080/v1/embeddings"
)

与HippoRAG集成

初始化流程

sequenceDiagram
    participant User
    participant HippoRAG
    participant EmbeddingModel
    participant EmbeddingStore
    
    User->>HippoRAG: __init__(embedding_model_name)
    HippoRAG->>EmbeddingModel: get_embedding_model()
    HippoRAG->>EmbeddingStore: 创建向量存储
    EmbeddingStore->>EmbeddingModel: 关联嵌入模型

在索引过程中的作用

1. 文档编码：将原始文档分块后，使用嵌入模型编码为向量
2. 实体编码：从OpenIE提取的实体编码为向量
3. 事实编码：从OpenIE提取的事实三元组编码为向量
4. KNN检索：基于向量相似度构建知识图谱的同义词边

资料来源：src/hipporag/HippoRAG.py:1-50

依赖组件

Python包依赖

资料来源：setup.py:1-30

扩展开发

添加新的嵌入模型

1. 继承 BaseEmbeddingModel 基类
2. 实现 encode() 方法
3. 在 __init__.py 的 get_embedding_model() 中添加模型选择逻辑

# src/hipporag/embedding_model/CustomModel.py
from .base import BaseEmbeddingModel

class CustomEmbeddingModel(BaseEmbeddingModel):
    def __init__(self, global_config, embedding_model_name):
        super().__init__(global_config)
        self.model_id = embedding_model_name
        # 初始化自定义模型
    
    def encode(self, texts):
        # 实现编码逻辑
        pass

# src/hipporag/embedding_model/__init__.py
def get_embedding_model(global_config, embedding_model_name):
    if embedding_model_name.startswith("CustomModel/"):
        return CustomEmbeddingModel(global_config, embedding_model_name)
    # ... 其他模型

性能优化建议

资料来源：README.md - Quick Start

概述

OpenIE（Open Information Extraction，开放信息抽取）是HippoRAG框架中的核心组件，负责从文本语料中自动提取结构化的知识三元组。这些三元组构成了HippoRAG知识图谱的基础节点和边，使得大型语言模型能够识别和利用文档之间的语义关联，从而显著提升检索增强生成（RAG）的效果。

在HippoRAG系统中，OpenIE信息抽取的主要职责包括：

• 三元组抽取：从原始文本中提取形如(主语, 谓词, 宾语)的结构化知识表示
• 实体识别：识别文本中的命名实体及其类型
• 知识图谱构建：为后续的图检索和个性化PageRank算法提供基础结构

HippoRAG支持多种OpenIE运行模式，开发者可根据实际需求选择使用在线API（如OpenAI GPT）或离线部署（如vLLM、Transformers）的方式进行信息抽取。资料来源：src/hipporag/utils/config_utils.py:28-35

架构设计

组件结构

HippoRAG的OpenIE信息抽取模块采用模块化设计，主要包含以下核心组件：

graph TD
    A[文本输入] --> B[文本预处理]
    B --> C[OpenIE信息抽取模块]
    C --> D{运行模式选择}
    D -->|online| E[OpenAI GPT抽取器]
    D -->|offline| F[vLLM离线抽取器]
    D -->|Transformers-offline| G[Transformers离线抽取器]
    E --> H[三元组输出]
    F --> H
    G --> H
    H --> I[知识图谱构建]

文件组织

src/hipporag/
├── information_extraction/          # OpenIE信息抽取模块
│   ├── __init__.py                  # 模块初始化与导出
│   ├── base.py                      # 基类定义
│   ├── openie_openai_gpt.py        # OpenAI GPT在线抽取实现
│   ├── openie_vllm_offline.py       # vLLM离线批量抽取实现
│   └── openie_transformers_offline.py # Transformers离线抽取实现
└── prompts/
    └── templates/
        ├── triple_extraction.py     # 三元组抽取提示模板
        └── ner.py                   # 命名实体识别提示模板

运行模式

HippoRAG的OpenIE模块支持三种运行模式，通过配置参数openie_mode进行选择：

在线模式（OpenAI GPT）

在线模式使用OpenAI GPT模型进行信息抽取，是默认的运行模式。该模式配置简单，适合快速验证和小型数据集场景。

# 配置示例
config = BaseConfig(
    openie_mode='online',
    information_extraction_model_name='openie_openai_gpt'
)

主要特点：

• 配置简便，无需本地部署模型
• 依赖OpenAI API，需要有效的API密钥
• 适合开发和测试阶段
• 支持的模型：gpt-4o、gpt-4o-mini等

资料来源：src/hipporag/utils/config_utils.py:28-35

vLLM离线模式

vLLM离线模式使用本地部署的vLLM推理服务进行批量信息抽取，是生产环境推荐的方式。

# 配置示例
config = BaseConfig(
    openie_mode='offline',
    information_extraction_model_name='openie_openai_gpt'  # 使用OpenIE格式
)

部署要求：

# 启动vLLM服务
export CUDA_VISIBLE_DEVICES=0,1
export VLLM_WORKER_MULTIPROC_METHOD=spawn
vllm serve meta-llama/Llama-3.3-70B-Instruct \
    --tensor-parallel-size 2 \
    --max_model_len 4096 \
    --gpu-memory-utilization 0.95 \
    --port 6578

主要优势：

• 成本效益：无需支付API调用费用
• 性能优化：支持张量并行，加速批量处理
• 隐私保护：数据完全在本地处理
• 可扩展性：支持更大规模的语料处理

资料来源：README.md - Local Deployment (vLLM)

Transformers离线模式

该模式使用HuggingFace Transformers库直接加载模型进行推理，适合完全离线或需要使用特定模型的场景。

# 配置示例
config = BaseConfig(
    openie_mode='Transformers-offline',
    information_extraction_model_name='Transformers/Qwen/Qwen2.5-7B-Instruct'
)

使用示例（来自test_transformers.py）：

global_config = BaseConfig(
    openie_mode='Transformers-offline',
    information_extraction_model_name='Transformers/Qwen/Qwen2.5-7B-Instruct'
)

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

抽取流程

整体工作流

graph LR
    A[文档集合] --> B[文档分块<br/>Chunking]
    B --> C[分块文本]
    C --> D{openie_mode}
    D -->|online| E[调用OpenAI API]
    D -->|offline| F[调用vLLM服务]
    D -->|Transformers| G[本地模型推理]
    E --> H[三元组解析]
    F --> H
    G --> H
    H --> I[结果存储]
    I --> J[知识图谱构建]

三元组抽取

三元组抽取是OpenIE的核心功能，将非结构化文本转换为(主语, 谓词, 宾语)形式的知识表示。

抽取提示模板（triple_extraction.py）：

系统使用精心设计的提示模板引导语言模型输出结构化的三元组信息。提示模板通常包含：

• 抽取任务的明确定义
• 输出格式规范（如JSON格式）
• 示例输入输出对
• 边界情况处理指南

输出格式示例：

[
  {
    "subject": "Oliver Badman",
    "predicate": "is a",
    "object": "politician"
  },
  {
    "subject": "The prince",
    "predicate": "used",
    "object": "the lost glass slipper"
  }
]

命名实体识别

NER模块（ner.py）负责识别文本中的命名实体，包括人名、地点、组织等。识别的实体用于：

• 增强知识图谱的节点信息
• 辅助实体链接和消歧
• 提供更丰富的检索特征

配置参数

全局配置项

HippoRAG的BaseConfig类提供了丰富的OpenIE相关配置选项：

高级配置

资料来源：src/hipporag/utils/config_utils.py:28-72

使用指南

快速开始

#### 1. 环境配置

# 设置环境变量
export CUDA_VISIBLE_DEVICES=0,1,2,3
export HF_HOME=<Huggingface home目录路径>
export OPENAI_API_KEY=<your openai api key>

# 激活环境
conda activate hipporag

#### 2. 基础使用示例

from hipporag import HippoRAG

# 准备文档
docs = [
    "Oliver Badman is a politician.",
    "George Rankin is a politician.",
    "Erik Hort's birthplace is Montebello.",
    "Montebello is a part of Rockland County."
]

# 初始化HippoRAG
hipporag = HippoRAG(
    save_dir='outputs',
    llm_model_name='gpt-4o-mini',
    embedding_model_name='nvidia/NV-Embed-v2'
)

# 执行索引（包括OpenIE抽取）
hipporag.index(docs=docs)

# 执行问答检索
queries = ["What is George Rankin's occupation?"]
gold_docs = [["George Rankin is a politician."]]
answers = [["Politician"]]

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

vLLM离线模式完整流程

#### 步骤1：启动vLLM服务

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

vllm serve meta-llama/Llama-3.3-70B-Instruct \
    --tensor-parallel-size 2 \
    --max_model_len 4096 \
    --gpu-memory-utilization 0.95 \
    --port 6578

#### 步骤2：运行主程序

export CUDA_VISIBLE_DEVICES=2,3
export HF_HOME=<path to Huggingface home directory>
export OPENAI_API_KEY=''

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

#### 步骤3：完成索引和问答

首次运行使用--skip_graph参数后，OpenIE结果会保存到文件。第二次运行时去掉该参数即可完成图构建：

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

资料来源：README.md - Reproducing our Experiments

调试技巧

1. 使用小数据集调试：项目提供的/reproduce/dataset/sample.json是专门用于调试的小数据集

``bash rm reproduce/dataset/openie_results/openie_sample_results_*.json rm -rf outputs/sample/ ``

1. 清理缓存：重新运行实验时，记得清除保存的文件：

1. vLLM离线模式调试：当遇到问题时，将hipporag/llm/vllm_offline.py中的tensor_parallel_size设为1

1. 查看保存的OpenIE结果：OpenIE结果默认保存，可直接检查输出格式是否正确

输出与存储

OpenIE结果保存

OpenIE抽取结果默认保存到指定目录，文件命名格式包含模型和数据集信息：

outputs/<dataset>/<llm>_<embedding>/openie_results/
└── openie_<dataset>_results_<model>.json

结果格式

{
  "doc_id": 0,
  "doc_text": "Oliver Badman is a politician.",
  "triples": [
    {
      "subject": "Oliver Badman",
      "predicate": "is a",
      "object": "politician"
    }
  ],
  "entities": [
    {"text": "Oliver Badman", "type": "PERSON"}
  ]
}

与知识图谱的集成

OpenIE抽取的三元组直接用于构建HippoRAG的知识图谱：

graph LR
    A[三元组] --> B[实体节点]
    A --> C[关系边]
    B --> D[知识图谱]
    C --> D
    D --> E[个性化PageRank检索]
    E --> F[LLM问答生成]

性能优化建议

1. 批量处理

离线模式支持批量调用，可显著提升处理速度：

# 批量文档索引
hipporag.index(docs=large_documents_list)

2. GPU资源分配

• vLLM服务：分配专用GPU（如0,1）
• 主程序：使用另一组GPU（如2,3）
• 通过CUDA_VISIBLE_DEVICES环境变量控制

3. 内存优化

# 调整最大序列长度
--max_model_len 4096

# 调整GPU内存利用率
--gpu-memory-utilization 0.95

4. 并行配置

export VLLM_WORKER_MULTIPROC_METHOD=spawn

常见问题

Q1: 首次运行vLLM离线模式需要设置什么参数？

需要设置--skip_graph参数，因为首次运行时图尚未构建：

python main.py --openie_mode offline --skip_graph

Q2: 如何切换不同的OpenIE模型？

通过修改information_extraction_model_name配置：

# 使用OpenAI GPT
config = BaseConfig(information_extraction_model_name='openie_openai_gpt')

# 使用Transformers模型
config = BaseConfig(
    information_extraction_model_name='Transformers/Qwen/Qwen2.5-7B-Instruct',
    openie_mode='Transformers-offline'
)

Q3: OpenIE结果支持增量更新吗？

是的，HippoRAG支持增量更新。删除文档后重新索引，已保存的OpenIE结果会被重用。

Q4: 如何处理长文档？

对于过长的文档，建议先进行分块处理：

config = BaseConfig(
    preprocess_chunk_max_token_size=512,
    preprocess_chunk_overlap_token_size=64
)

参考链接

• HippoRAG官方仓库：https://github.com/OSU-NLP-Group/HippoRAG
• HippoRAG 2论文：https://arxiv.org/abs/2502.14802
• HippoRAG 1论文：https://arxiv.org/abs/2405.14831
• vLLM文档：https://docs.vllm.ai/

概述

HippoRAG框架中的Prompt模板管理模块负责组织和调用系统中各类LLM推理所需的提示词模板。该模块位于 src/hipporag/prompts/ 目录下，采用模块化的设计思想，将不同功能场景的提示词模板分别存放于独立文件中，便于维护和扩展。

Prompt模板管理系统的核心作用包括：

• 模板存储与加载：通过文件系统组织提示词模板，支持动态加载
• 模板渲染：使用 prompt_template_manager 将占位符替换为实际数据
• 数据集适配：根据不同数据集选择对应的提示词模板
• 统一接口：为HippoRAG和StandardRAG等组件提供一致的模板访问方式

资料来源：src/hipporag/prompts/templates/README.md:1-18

目录结构

src/hipporag/prompts/
├── __init__.py
├── prompt_template_manager.py    # 模板管理器核心实现
├── linking.py                    # 图谱链接相关提示词
├── filter_default_prompt.py      # 过滤模块默认提示词
├── templates/
│   ├── __init__.py
│   ├── rag_qa_musique.py         # MuSiQue数据集QA模板
│   ├── ircot_hotpotqa.py         # HotpotQA多跳问答模板
│   └── ...                       # 其他数据集模板

资料来源：README.md

模板定义规范

文件命名规则

模板文件夹 templates/ 被作为 hipporag 项目下的子模块处理。每个 *.py 文件（除 __init__.py 外）对应一个提示词模板，文件名（不含文件扩展名）将作为访问该模板的键名。

资料来源：src/hipporag/prompts/templates/README.md:5-8

模板变量规范

每个模板文件必须定义一个名为 prompt_template 的变量来存储提示词内容。该变量可以是以下三种形式之一：

# 形式1: 字符串（支持 ${} 占位符）
prompt_template = "Question: ${question}\nAnswer:"

# 形式2: Template对象实例
from string import Template
prompt_template = Template("Wikipedia Title: ${title}\n\n${text}")

# 形式3: 聊天历史格式（List[dict]）
prompt_template = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Question: ${question}"}
]

资料来源：src/hipporag/prompts/templates/README.md:10-17

模板渲染机制

PromptTemplateManager

PromptTemplateManager 是模板系统的核心管理类，负责模板的加载、验证和渲染。

#### 模板选择逻辑

HippoRAG在执行检索和QA任务时，会根据当前数据集选择对应的提示词模板。核心逻辑如下：

if self.prompt_template_manager.is_template_name_valid(name=f'rag_qa_{self.global_config.dataset}'):
    # 查找该数据集对应的自定义提示词
    prompt_dataset_name = self.global_config.dataset
else:
    # 数据集尚未定义自定义模板，使用MuSiQue的通用模板作为后备
    logger.debug(
        f"rag_qa_{self.global_config.dataset} does not have a customized prompt template. "
        f"Using MUSIQUE's prompt template instead.")
    prompt_dataset_name = 'musique'

资料来源：src/hipporag/HippoRAG.py:1-20

#### 模板渲染流程

graph TD
    A[开始渲染] --> B{数据集模板是否存在?}
    B -->|是| C[使用数据集特定模板]
    B -->|否| D[使用musique通用模板]
    C --> E[调用render方法]
    D --> E
    E --> F[替换prompt_user占位符]
    F --> G[返回渲染后的消息]

模板渲染示例

HippoRAG在QA阶段将检索到的文档传入模板进行渲染：

prompt_user = ''
for passage in retrieved_passages:
    prompt_user += f'Wikipedia Title: {passage}\n\n'
prompt_user += 'Question: ' + query_solution.question + '\nThought: '

all_qa_messages.append(
    self.prompt_template_manager.render(
        name=f'rag_qa_{prompt_dataset_name}', 
        prompt_user=prompt_user
    )
)

资料来源：src/hipporag/HippoRAG.py:1-15

预置模板

MuSiQue数据集模板

rag_qa_musique.py 是HippoRAG的默认提示词模板，用于多跳问答场景。

prompt_template = """Given the following Wikipedia passages, ...

Thought: The question asks about ...
We need to find passages about ...
...

Question: {question}
Thought: """

该模板采用Chain-of-Thought（思维链）风格，引导LLM逐步推理多跳问题。

资料来源：src/hipporag/prompts/templates/rag_qa_musique.py

HotpotQA模板

ircot_hotpotqa.py 实现基于IRCoT（Iterated Retrieval Chain-of-Thought）的提示词模板，适用于HotpotQA双跳问答数据集。

资料来源：src/hipporag/prompts/templates/ircot_hotpotqa.py

配置参数

HippoRAG通过 BaseConfig 类管理模板相关的配置参数：

# QA特定配置
max_qa_steps: int = field(
    default=1,
    metadata={"help": "For answering a single question, the max steps that we use to interleave retrieval and reasoning."}
)
qa_top_k: int = field(
    default=5,
    metadata={"help": "Feeding top k documents to the QA model for reading."}
)

资料来源：src/hipporag/utils/config_utils.py:1-15

使用示例

基本使用流程

from hipporag import HippoRAG

# 初始化HippoRAG（会自动加载模板管理器）
hipporag = HippoRAG(
    save_dir='outputs',
    llm_model_name='gpt-4o-mini',
    embedding_model_name='nvidia/NV-Embed-v2'
)

# 索引文档
hipporag.index(docs=documents)

# 执行QA（自动使用对应数据集的模板）
results = hipporag.rag_qa(
    queries=questions,
    gold_docs=gold_documents,
    gold_answers=expected_answers
)

自定义模板

如需为新数据集添加模板，需在 src/hipporag/prompts/templates/ 目录下创建新文件：

1. 创建 rag_qa_your_dataset.py
2. 定义 prompt_template 变量
3. 使用 ${} 占位符标记需替换的位置

# rag_qa_your_dataset.py
prompt_template = """Based on the following context...

Context: {prompt_user}

Please answer the question based on the context."""

创建后，系统会自动识别并可使用 rag_qa_your_dataset 作为模板名称。

资料来源：src/hipporag/prompts/templates/README.md:5-12

与其他模块的集成

HippoRAG集成

HippoRAG 类在执行 rag_qa 方法时调用模板管理器：

# 位置: src/hipporag/HippoRAG.py
all_qa_messages.append(
    self.prompt_template_manager.render(
        name=f'rag_qa_{prompt_dataset_name}', 
        prompt_user=prompt_user
    )
)

StandardRAG集成

StandardRAG 类使用完全相同的模板管理逻辑：

# 位置: src/hipporag/StandardRAG.py
all_qa_messages.append(
    self.prompt_template_manager.render(
        name=f'rag_qa_{prompt_dataset_name}', 
        prompt_user=prompt_user
    )
)

两者的模板选择和渲染机制保持一致，确保不同RAG变体之间的行为统一。

资料来源：src/hipporag/StandardRAG.py:1-15

总结

HippoRAG的Prompt模板管理系统具有以下特点：

该设计使得HippoRAG能够优雅地处理不同数据集的提示词需求，同时保持代码的简洁性和可维护性。

1. 环境准备

1.1 系统要求

HippoRAG 对运行环境有明确的依赖要求，需确保满足以下条件：

1.2 依赖安装

首先创建独立的 conda 环境并安装核心依赖：

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

资料来源：README.md:1

1.3 环境变量配置

启动 HippoRAG 前需配置以下环境变量：

# GPU 配置
export CUDA_VISIBLE_DEVICES=0,1,2,3

# HuggingFace 模型缓存路径
export HF_HOME=<path to Huggingface home directory>

# OpenAI API 密钥（使用 OpenAI 模型时必需）
export OPENAI_API_KEY=<your openai api key>

# 激活环境
conda activate hipporag

资料来源：README.md:1

1.4 vLLM 本地部署环境

如需使用本地 vLLM 部署，需额外配置：

export VLLM_WORKER_MULTIPROC_METHOD=spawn
export HF_HOME=<path to Huggingface home directory>

2. 数据准备

2.1 数据集来源

实验所需数据集可从以下渠道获取：

资料来源：README.md:1

2.2 数据目录结构

推荐将数据集统一放置在 reproduce/dataset/ 目录下：

reproduce/
└── dataset/
    ├── sample_corpus.json      # 语料库文件
    ├── sample.json             # 查询文件（含答案）
    └── <dataset_name>_corpus.json

2.3 语料库 JSON 格式

语料库文件需遵循特定的 JSON 数组格式：

[
  {
    "title": "FIRST PASSAGE TITLE",
    "text": "FIRST PASSAGE TEXT",
    "idx": 0
  },
  {
    "title": "SECOND PASSAGE TITLE",
    "text": "SECOND PASSAGE TEXT",
    "idx": 1
  }
]

字段说明：

资料来源：reproduce/README.md

2.4 查询 JSON 格式（可选）

如需进行评估，需准备包含问题和标准答案的查询文件：

[
  {
    "id": "sample/question_1.json",
    "question": "QUESTION",
    "answer": ["ANSWER"],
    "answerable": true,
    "paragraphs": [
      {
        "title": "{FIRST SUPPORTING PASSAGE TITLE}",
        "text": "{FIRST SUPPORTING PASSAGE TEXT}",
        "is_supporting": true,
        "idx": 0
      }
    ]
  }
]

字段说明：

2.5 长文本分块

对于过长的段落，可能需要在 OpenIE 处理前进行分块：

当准备数据时，可能需要对每个段落进行分块，因为较长的段落可能对 OpenIE 过程过于复杂。

资料来源：README.md:1

3. 实验运行流程

3.1 整体工作流

graph TD
    A[准备数据集] --> B[配置环境变量]
    B --> C{选择模型部署方式}
    C -->|OpenAI| D[设置 API 配置]
    C -->|vLLM 本地| E[启动 vLLM 服务]
    D --> F[运行 main.py]
    E --> G[运行 main.py]
    F --> H[索引构建]
    G --> H
    H --> I[检索与问答]
    I --> J[输出评估结果]

3.2 命令行参数说明

main.py 支持多种命令行参数配置：

资料来源：main.py:1

3.3 配置类参数

HippoRAG 使用 BaseConfig 类管理核心配置参数：

资料来源：src/hipporag/utils/config_utils.py:1

4. 使用 OpenAI 模型

4.1 快速启动流程

使用 OpenAI 模型进行实验的标准流程：

# 设置数据集
dataset=sample  # 或其他数据集

# 运行 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

资料来源：README.md:1

4.2 支持的 OpenAI 兼容模型

HippoRAG 支持任何 OpenAI 兼容的 API 端点，包括：

• GPT-4 系列模型
• GPT-3.5 系列模型
• Azure OpenAI 部署模型
• 其他 OpenAI 兼容的第三方 API

4.3 Azure OpenAI 部署

使用 Azure 端点时需指定额外参数：

hipporag = HippoRAG(
    save_dir=save_dir,
    llm_model_name=llm_model_name,
    embedding_model_name=embedding_model_name,
    azure_endpoint="https://[ENDPOINT NAME].openai.azure.com/openai/deployments/gpt-4o-mini/chat/completions?api-version=2025-01-01-preview",
    azure_embedding_endpoint="https://[ENDPOINT NAME].openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2023-05-15"
)

资料来源：main_azure.py:1

5. 使用 vLLM 本地部署

5.1 vLLM 服务启动

vLLM 提供了 OpenAI 兼容的本地推理服务，启动步骤如下：

# 使用指定 GPU 启动服务（留足显存给嵌入模型）
export CUDA_VISIBLE_DEVICES=0,1
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export HF_HOME=<path to Huggingface home directory>

# 启动模型服务
vllm serve meta-llama/Llama-3.3-70B-Instruct \
    --tensor-parallel-size 2 \
    --max_model_len 4096 \
    --gpu-memory-utilization 0.95 \
    --port 6578

参数调整建议：

资料来源：README.md:1

5.2 运行主程序

vLLM 服务启动后，使用另一组 GPU 运行主程序：

# 设置另一组 GPU
export CUDA_VISIBLE_DEVICES=2,3
export HF_HOME=<path to Huggingface home directory>

# 运行实验
python main.py \
    --dataset $dataset \
    --llm_base_url http://localhost:6578/v1 \
    --llm_name meta-llama/Llama-3.3-70B-Instruct \
    --embedding_name nvidia/NV-Embed-v2

资料来源：README.md:1

5.3 轻量级测试配置

为节省测试成本，可使用较小的模型：

# 测试用 vLLM 启动
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

资料来源：README.md:1

6. 测试验证

6.1 OpenAI 模型测试

验证环境配置正确性的快速测试：

export OPENAI_API_KEY=<your openai api key>
conda activate hipporag
python tests_openai.py

该测试成本可忽略不计，可用于验证基本功能。

6.2 本地模型测试

使用本地部署模型进行完整功能测试：

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

# 启动 vLLM 服务后
CUDA_VISIBLE=1 python tests_local.py

6.3 测试覆盖范围

测试脚本验证以下核心模块功能：

• 索引构建（Indexing）
• 图加载（Graph Loading）
• 文档删除（Document Deletion）
• 增量更新（Incremental Updates）

资料来源：README.md:1

7. 完整示例代码

7.1 基本使用流程

以下代码展示了完整的 HippoRAG 使用流程：

from hipporag import HippoRAG

# 初始化配置
save_dir = 'outputs'
llm_model_name = 'gpt-4o-mini'
embedding_model_name = 'nvidia/NV-Embed-v2'

# 创建实例
hipporag = HippoRAG(
    save_dir=save_dir,
    llm_model_name=llm_model_name,
    embedding_model_name=embedding_model_name
)

# 索引文档
docs = ["文档内容1", "文档内容2", "文档内容3"]
hipporag.index(docs=docs)

# 执行检索与问答
queries = ["查询问题1", "查询问题2"]
gold_docs = [["相关文档1"], ["相关文档2"]]
answers = [["答案1"], ["答案2"]]

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

7.2 OpenAI 兼容端点

hipporag = HippoRAG(
    save_dir=save_dir,
    llm_model_name='Your LLM Model name',
    llm_base_url='Your LLM Model url',
    embedding_model_name='Your Embedding model name',
    embedding_base_url='Your Embedding model url'
)

7.3 main.py 核心逻辑

def main():
    args = parse_args()
    
    # 加载数据集
    corpus, all_queries, gold_docs, gold_answers = load_data(args.dataset)
    
    # 配置参数
    config = BaseConfig(
        dataset=args.dataset,
        openie_mode=args.openie_mode,
        information_extraction_model_name=args.llm_name,
        retrieval_top_k=200,
        linking_top_k=5,
        max_qa_steps=3,
        qa_top_k=5,
        graph_type="facts_and_sim_passage_node_unidirectional",
        embedding_batch_size=8,
        corpus_len=len(corpus)
    )
    
    # 初始化并运行
    hipporag = HippoRAG(global_config=config)
    hipporag.index(corpus)
    hipporag.rag_qa(
        queries=all_queries,
        gold_docs=gold_docs,
        gold_answers=gold_answers
    )

资料来源：main.py:1

8. 常见问题排查

8.1 GPU 显存不足 (OOM)

解决方案：

1. 减小 gpu-memory-utilization 参数（建议从 0.95 逐步降低）
2. 减小 max_model_len 参数
3. 增加 tensor-parallel-size 以分散显存占用

8.2 OpenAI API 调用失败

检查项：

1. 确认 OPENAI_API_KEY 环境变量已正确设置
2. 验证 API 端点 URL 格式正确
3. 检查网络连接和代理设置

8.3 vLLM 服务无响应

排查步骤：

1. 确认 vLLM 服务进程正在运行
2. 检查端口 6578 是否被占用
3. 验证 GPU 可见性配置正确

9. 参考链接

概述

HippoRAG 提供了完整的评估与测试框架，用于验证系统的索引构建、检索质量和问答能力。评估模块位于 src/hipporag/evaluation/ 目录下，分为问答评估（QA Evaluation）和检索评估（Retrieval Evaluation）两个核心组件。资料来源：README.md:代码结构

该框架支持多种部署方式的测试，包括 OpenAI API、Azure OpenAI Service 和本地 vLLM 部署。通过统一的测试接口，开发者可以验证核心模块的功能完整性，包括索引构建、图加载、文档删除和增量更新等关键能力。

Pitfall Log / 踩坑日志

项目：OSU-NLP-Group/HippoRAG

摘要：发现 18 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：add_fact_edges function adds the same edge twice?。

1. 安装坑 · 来源证据：add_fact_edges function adds the same edge twice?

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：add_fact_edges function adds the same edge twice?
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6c7ca8232561460290f1ad50663233af | https://github.com/OSU-NLP-Group/HippoRAG/issues/174 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：pypi hipporag libraries

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：pypi hipporag libraries
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_0da5afa434114138a3c745efba4c9ded | https://github.com/OSU-NLP-Group/HippoRAG/issues/168 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安全/权限坑 · 来源证据：Take the "musique" dataset as an example. The process of constructing an index based on individual paragraphs takes an…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Take the "musique" dataset as an example. The process of constructing an index based on individual paragraphs takes an extremely long time. Is this normal?
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_90b68b1be49048efba510bfd10623d41 | https://github.com/OSU-NLP-Group/HippoRAG/issues/173 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

4. 安装坑 · 来源证据：OpenAI version incompatibility in latest 2.0.0a4 version

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：OpenAI version incompatibility in latest 2.0.0a4 version
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f6679eb5cf884eb9a2d003b39da93c8d | https://github.com/OSU-NLP-Group/HippoRAG/issues/140 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

5. 安装坑 · 来源证据：Windows Compatibility Issues with vLLM dependency

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows Compatibility Issues with vLLM dependency
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_57d57b9365f342db9a5e8ed48727e99e | https://github.com/OSU-NLP-Group/HippoRAG/issues/117 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

6. 配置坑 · 来源证据：How to use local embedding_model_

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：How to use local embedding_model_
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_dd0e2350e55240b3ab754359ca93cb11 | https://github.com/OSU-NLP-Group/HippoRAG/issues/127 | 来源类型 github_issue 暴露的待验证使用条件。

7. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | README/documentation is current enough for a first validation pass.

8. 运行坑 · 来源证据：Inquiry Regarding OpenIE Extraction Results for HippoRAG 2

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Inquiry Regarding OpenIE Extraction Results for HippoRAG 2
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b735fa4a09f942db8f1825092ef8e368 | https://github.com/OSU-NLP-Group/HippoRAG/issues/177 | 来源类型 github_issue 暴露的待验证使用条件。

9. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | last_activity_observed missing

10. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | no_demo; severity=medium

11. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | no_demo; severity=medium

12. 安全/权限坑 · 来源证据：How to distinguish Hipporag1 from Hipporag2

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to distinguish Hipporag1 from Hipporag2
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_7dc27422dd8b4cb8a1384848ddbfa750 | https://github.com/OSU-NLP-Group/HippoRAG/issues/167 | 来源类型 github_issue 暴露的待验证使用条件。

13. 安全/权限坑 · 来源证据：Inquiry on Sample Selection for HippoRAG Experiments

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Inquiry on Sample Selection for HippoRAG Experiments
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6a0069bfedfc4cf28e0cc18e51171a42 | https://github.com/OSU-NLP-Group/HippoRAG/issues/125 | 来源类型 github_issue 暴露的待验证使用条件。

14. 安全/权限坑 · 来源证据：Quadratic runtime during indexing

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Quadratic runtime during indexing
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2681acee71064f72b24098fba0e05227 | https://github.com/OSU-NLP-Group/HippoRAG/issues/170 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

15. 安全/权限坑 · 来源证据：[Discussion] Ablation: multi-component scoring layer over HippoRAG's KG?

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Discussion] Ablation: multi-component scoring layer over HippoRAG's KG?
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b65aca3d12234444b97a67bb7baac278 | https://github.com/OSU-NLP-Group/HippoRAG/issues/178 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

16. 安全/权限坑 · 来源证据：division by zero

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：division by zero
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_49e401ba15b74b5d943336fa0a2dceda | https://github.com/OSU-NLP-Group/HippoRAG/issues/93 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

17. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | issue_or_pr_quality=unknown

18. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | release_recency=unknown