# https://github.com/OSU-NLP-Group/HippoRAG 项目说明书
生成时间：2026-05-16 23:14:33 UTC
## 目录
- [项目介绍](#p1)
- [快速入门指南](#p2)
- [系统架构设计](#p3)
- [知识图谱构建](#p4)
- [LLM模型集成](#p5)
- [Embedding模型集成](#p6)
- [OpenIE信息抽取](#p7)
- [Prompt模板管理](#p8)
- [实验复现指南](#p9)
- [评估与测试](#p10)
## 项目介绍
### 相关页面
相关主题：[快速入门指南](#p2), [系统架构设计](#p3)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
- [setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)
- [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)
- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)
- [CONTRIBUTING.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/CONTRIBUTING.md)
- [requirements.txt](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/requirements.txt)
# 项目介绍
## 1 项目概述
HippoRAG（海马体RAG）是一个受神经生物学启发的强大图结构RAG框架，能够使大型语言模型（LLM）识别并利用新知识中的关联信息，从而改进检索效果。资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
当前版本为 **HippoRAG 2**，该版本实现了从传统RAG到记忆系统的跨越，引入非参数持续学习（Non-Parametric Continual Learning）能力。资料来源：[README.md:1](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md#L1)
### 1.1 项目版本信息
| 属性 | 值 |
|------|-----|
| 包名称 | hipporag |
| 当前版本 | 2.0.0-alpha.4 |
| Python版本要求 | >=3.10 |
| 许可证 | 开源 |
| 官方仓库 | https://github.com/OSU-NLP-Group/HippoRAG |
资料来源：[setup.py:1-12](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py#L1-L12)
## 2 项目背景与动机
### 2.1 传统RAG的局限性
传统检索增强生成（RAG）系统在处理需要跨段落关联推理的问题时存在明显不足。当用户查询需要关联多个分散的知识片段时，传统方法往往难以有效整合相关信息。
### 2.2 HippoRAG的解决方案
HippoRAG从人类海马体的记忆机制中汲取灵感，构建了一个能够模拟人类长期记忆关联特性的图结构知识库。该系统能够：
- 在新知识中识别和利用关联信息
- 改进跨段落的事实检索能力
- 支持多跳推理和关联问答
资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
## 3 系统架构
### 3.1 整体架构图
```mermaid
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](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
| 模块目录 | 功能描述 |
|---------|---------|
| `embedding_model/` | 各类嵌入模型的实现 |
| `evaluation/` | 评估指标实现 |
| `information_extraction/` | 信息抽取模型实现 |
| `llm/` | 大语言模型推理类 |
| `passage/` | 文档处理相关 |
| `graph/` | 图结构相关 |
| `retrieval/` | 检索相关 |
| `config/` | 配置管理 |
资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
## 4 核心功能特性
### 4.1 支持的模型类型
HippoRAG支持多种LLM和嵌入模型部署方式：资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
| 模型类型 | 支持方式 | 示例 |
|---------|---------|------|
| OpenAI模型 | API调用 | GPT-4o-mini |
| OpenAI兼容嵌入 | API调用 + 自定义端点 | NVIDIA NV-Embed-v2 |
| 本地vLLM部署 | 自托管推理 | Llama-3.1-8B-Instruct |
| Azure OpenAI | Azure云部署 | gpt-4o-mini |
### 4.2 支持的嵌入模型
- **NV-Embed-v2**：NVIDIA开发的嵌入模型
- **GritLM**：专门用于检索的嵌入模型
- **Contriever**：基于对比学习的检索模型
- **OpenAI兼容模型**：支持自定义嵌入端点
资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
### 4.3 知识图谱构建
系统支持构建多种类型的知识图谱：
```mermaid
graph LR
A[事实节点] --> B[相似段落节点]
B --> C[单向/双向关联]
A --> C
```
**图结构类型**：
- `facts_and_sim_passage_node_unidirectional`：事实节点与相似段落节点单向关联
- 支持自定义图结构类型
资料来源：[main.py:1-15](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py#L1-L15)
## 5 关键配置参数
### 5.1 索引构建参数
| 参数名 | 默认值 | 说明 |
|--------|--------|------|
| `openie_mode` | - | OpenIE模式（OpenAI/Transformers-offline/vllm） |
| `information_extraction_model_name` | - | 信息抽取模型名称 |
| `synonymy_edge_topk` | 2047 | 构建同义词边时的KNN检索参数 |
| `synonymy_edge_sim_threshold` | 0.8 | 同义词边相似度阈值 |
| `is_directed_graph` | False | 是否为有向图 |
资料来源：[src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)
### 5.2 检索参数
| 参数名 | 默认值 | 说明 |
|--------|--------|------|
| `linking_top_k` | 5 | 每次检索步骤链接的节点数 |
| `retrieval_top_k` | 200 | 每次步骤检索的文档数 |
| `damping` | 0.5 | PPR算法的阻尼因子 |
资料来源：[src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)
### 5.3 问答参数
| 参数名 | 默认值 | 说明 |
|--------|--------|------|
| `max_qa_steps` | 1 | 单个问题的最大推理步骤数 |
| `qa_top_k` | 5 | 输入给QA模型的顶部K个文档 |
资料来源：[src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)
## 6 依赖环境
### 6.1 核心依赖
| 依赖包 | 版本 | 用途 |
|--------|------|------|
| torch | 2.5.1 | 深度学习框架 |
| transformers | 4.45.2 | 模型加载与推理 |
| vllm | 0.6.6.post1 | 高效LLM推理 |
| openai | 1.91.1 | OpenAI API调用 |
| litellm | 1.73.1 | 多模型统一接口 |
| gritlm | 1.0.2 | 检索嵌入模型 |
资料来源：[setup.py:17-29](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py#L17-L29)
### 6.2 辅助依赖
| 依赖包 | 版本 | 用途 |
|--------|------|------|
| networkx | 3.4.2 | 图结构处理 |
| python_igraph | 0.11.8 | 图算法实现 |
| tiktoken | 0.7.0 | 分词器 |
| pydantic | 2.10.4 | 数据验证 |
| tenacity | 8.5.0 | 重试机制 |
| einops | - | 张量操作 |
| tqdm | - | 进度条 |
资料来源：[requirements.txt](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/requirements.txt)
## 7 数据格式规范
### 7.1 检索语料库格式
```json
[
{
"title": "FIRST PASSAGE TITLE",
"text": "FIRST PASSAGE TEXT",
"idx": 0
},
{
"title": "SECOND PASSAGE TITLE",
"text": "SECOND PASSAGE TEXT",
"idx": 1
}
]
```
资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
### 7.2 查询数据格式（可选）
```json
[
{
"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](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
## 8 使用方式
### 8.1 快速开始流程
```mermaid
graph TD
A[初始化HippoRAG实例] --> B[准备文档数据]
B --> C[执行索引构建]
C --> D[执行问答查询]
D --> E[获取评估结果]
```
### 8.2 OpenAI模型使用示例
```python
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](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
### 8.3 本地vLLM部署
1. 启动vLLM服务器：
```sh
vllm serve meta-llama/Llama-3.1-8B-Instruct \
--tensor-parallel-size 2 \
--max_model_len 4096 \
--gpu-memory-utilization 0.95 \
--port 6578
```
2. 使用HippoRAG：
```python
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](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/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](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/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 测试要求
| 测试类型 | 测试命令 | 适用场景 |
|---------|---------|---------|
| OpenAI测试 | `python tests_openai.py` | 使用OpenAI LLM和嵌入模型 |
| 本地测试 | `python tests_local.py` | 使用vLLM本地部署 |
资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
## 11 环境变量配置
| 变量名 | 说明 | 示例 |
|--------|------|------|
| `CUDA_VISIBLE_DEVICES` | 可用GPU设备编号 | 0,1,2,3 |
| `HF_HOME` | HuggingFace缓存目录路径 | /path/to/huggingface |
| `OPENAI_API_KEY` | OpenAI API密钥 | sk-xxxx |
资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
## 12 TODOs与未来规划
- [x] 添加更多嵌入模型支持
- [x] 添加嵌入端点支持
- [ ] 添加向量数据库集成支持
资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
## 13 致谢
本项目由俄亥俄州立大学（The Ohio State University）NLP研究组开发维护。
**主要联系人**：
- Bernal Jiménez Gutiérrez（jimenezgutierrez.1@osu.edu）
- Yiheng Shu（shu.251@osu.edu）
- Yu Su（su.809@osu.edu）
资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
---
## 快速入门指南
### 相关页面
相关主题：[项目介绍](#p1), [实验复现指南](#p9)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
- [setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)
- [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)
- [demo_openai.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/demo_openai.py)
- [demo_local.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/demo_local.py)
- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)
# 快速入门指南
HippoRAG 是一个基于图的 RAG（检索增强生成）框架，能够使大型语言模型识别并利用新知识中的关联信息来改进检索效果。本文档将帮助用户在最短时间内完成环境配置和基本功能验证。
## 环境要求
### 系统依赖
| 组件 | 版本要求 | 说明 |
|------|----------|------|
| Python | ≥ 3.10 | 项目必需的 Python 版本 |
| CUDA | 兼容 | 用于 GPU 加速推理 |
| conda | 任意稳定版本 | 建议使用 conda 管理虚拟环境 |
资料来源：[setup.py:8]()
### 核心依赖包
项目安装后会自动引入以下核心依赖：
| 包名 | 版本 | 用途 |
|------|------|------|
| torch | 2.5.1 | 深度学习框架 |
| transformers | 4.45.2 | 模型推理 |
| vllm | 0.6.6.post1 | 本地 LLM 部署 |
| openai | 1.91.1 | OpenAI API 调用 |
| networkx | 3.4.2 | 图数据结构 |
| pydantic | 2.10.4 | 配置管理 |
资料来源：[setup.py:14-27]()
## 安装步骤
### 方法一：使用 pip 直接安装（推荐）
```sh
conda create -n hipporag python=3.10
conda activate hipporag
pip install hipporag
```
资料来源：[README.md:67-70]()
### 方法二：从源码安装
```sh
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 .
```
## 环境变量配置
在运行项目之前，需要配置以下环境变量：
```sh
export CUDA_VISIBLE_DEVICES=0,1,2,3
export HF_HOME=
export OPENAI_API_KEY= # 仅在使用 OpenAI 模型时需要
```
| 环境变量 | 必填 | 说明 |
|----------|------|------|
| CUDA_VISIBLE_DEVICES | 是 | 指定使用的 GPU 编号 |
| HF_HOME | 是 | Hugging Face 模型缓存目录 |
| OPENAI_API_KEY | 否 | OpenAI API 密钥（使用 OpenAI 模型时必填） |
资料来源：[README.md:72-76]()
## 快速使用流程
HippoRAG 的核心使用流程分为三个阶段：初始化、索引构建、检索与问答。
```mermaid
graph TD
A[初始化 HippoRAG 实例] --> B[调用 index 方法构建索引]
B --> C[调用 rag_qa 方法进行检索问答]
C --> D[获取检索结果和生成答案]
```
资料来源：[README.md:78-97]()
### 使用 OpenAI 模型
以下示例展示如何使用 OpenAI 模型进行索引构建和问答检索：
```python
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 服务器
```sh
export CUDA_VISIBLE_DEVICES=0,1
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export HF_HOME=
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]()
#### 第二步：运行主程序
```sh
export CUDA_VISIBLE_DEVICES=2,3
export HF_HOME=
export 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 服务：
```python
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
```python
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` 类包含所有可配置参数，以下是常用参数说明：
| 参数名 | 默认值 | 类型 | 说明 |
|--------|--------|------|------|
| llm_model_name | - | str | LLM 模型名称 |
| embedding_model_name | nvidia/NV-Embed-v2 | str | Embedding 模型名称 |
| llm_base_url | - | str | LLM API 端点 URL |
| embedding_base_url | - | str | Embedding API 端点 URL |
| linking_top_k | 5 | int | 每次检索步骤链接的节点数 |
| retrieval_top_k | 200 | int | 每次检索的文档数量 |
| qa_top_k | 5 | int | 输入给 QA 模型的 Top-K 文档数 |
| max_qa_steps | 1 | int | 最大问答迭代步数 |
| openie_mode | online | str | OpenIE 模型模式（online/offline） |
| embedding_batch_size | 16 | int | Embedding 模型批处理大小 |
资料来源：[src/hipporag/utils/config_utils.py:1-50]()
## 数据集格式
### 检索语料库格式
```json
[
{
"title": "FIRST PASSAGE TITLE",
"text": "FIRST PASSAGE TEXT",
"idx": 0
},
{
"title": "SECOND PASSAGE TITLE",
"text": "SECOND PASSAGE TEXT",
"idx": 1
}
]
```
资料来源：[README.md:141-151]()
### 查询文件格式（可选）
```json
[
{
"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 模型验证
```sh
export OPENAI_API_KEY=
conda activate hipporag
python tests_openai.py
```
资料来源：[README.md:124-128]()
### 使用本地模型验证
```sh
export CUDA_VISIBLE_DEVICES=0
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export HF_HOME=
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` 的实现方式运行论文中的实验
---
## 系统架构设计
### 相关页面
相关主题：[项目介绍](#p1), [知识图谱构建](#p4), [LLM模型集成](#p5)
相关源码文件
以下源码文件用于生成本页说明：
- [src/hipporag/HippoRAG.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/HippoRAG.py)
- [src/hipporag/StandardRAG.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/StandardRAG.py)
- [src/hipporag/embedding_store.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_store.py)
- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)
- [setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)
- [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)
- [README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
# 系统架构设计
## 概述
HippoRAG是一个受神经生物学启发的图基RAG（检索增强生成）框架，旨在使大型语言模型能够识别并利用新知识中的关联信息以改进检索效果。该系统通过模拟海马体的记忆索引机制，实现高效的持久化知识管理和关联推理能力。
HippoRAG的核心架构围绕三个主要阶段设计：**索引（Indexing）**、**检索（Retrieval）** 和 **问答（QA）**。系统支持多种LLM后端（OpenAI、vLLM、Azure OpenAI）和嵌入模型（NV-Embed-v2、GritLM、Contriever等），提供了灵活的部署选项。
## 核心模块架构
### 模块层次结构
HippoRAG项目采用清晰的模块化设计，各组件职责明确：
| 模块路径 | 功能描述 | 核心类/文件 |
|---------|---------|------------|
| `hipporag/embedding_model/` | 嵌入模型实现 | `BaseEmbeddingModel`, `NVEmbedV2` |
| `hipporag/evaluation/` | 评估指标 | `BaseMetric`, `qa_eval.py`, `retrieval_eval.py` |
| `hipporag/information_extraction/` | 信息抽取 | `openie_openai_gpt.py`, `openie_vllm_offline.py` |
| `hipporag/llm/` | 大语言模型推理 | 各类LLM调用封装 |
| `hipporag/utils/` | 工具函数 | `config_utils.py` |
资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
### 主要类层次
HippoRAG中存在两种主要的RAG实现类：
```mermaid
classDiagram
class BaseRAG {
<>
+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`类作为配置基础，提供类型安全的配置管理：
```python
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](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)
### 关键配置参数
#### OpenIE模式配置
| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `openie_mode` | str | - | 信息抽取模式：OpenAI/vLLM-offline/Transformers-offline |
| `information_extraction_model_name` | str | - | 信息抽取使用的模型名称 |
#### 嵌入模型配置
| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `embedding_model_name` | str | - | 嵌入模型名称（nvidia/NV-Embed-v2等） |
| `embedding_batch_size` | int | 16 | 嵌入调用批次大小 |
| `embedding_return_as_normalized` | bool | True | 是否返回归一化嵌入 |
| `embedding_max_seq_len` | int | 2048 | 嵌入模型最大序列长度 |
| `embedding_model_dtype` | str | "auto" | 模型数据类型 |
#### 图构建配置
| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `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 | 同义边相似度阈值 |
| `is_directed_graph` | bool | False | 图是否是有向图 |
#### 检索与QA配置
| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `linking_top_k` | int | 5 | 每次检索步骤关联的节点数 |
| `retrieval_top_k` | int | 200 | 初始检索文档数 |
| `damping` | float | 0.5 | PageRank阻尼因子 |
| `max_qa_steps` | int | 1 | QA最大迭代步数 |
| `qa_top_k` | int | 5 | 输入QA模型的顶部文档数 |
## 索引流程架构
### 索引阶段工作流
HippoRAG的索引阶段将文档转化为知识图谱，实现与海马体记忆索引类似的持久化存储：
```mermaid
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. **相似度计算**：支持归一化和非归一化嵌入的相似度计算
索引过程的关键调用示例：
```python
# main.py中的索引调用
hipporag = HippoRAG(global_config=config)
hipporag.index(docs)
```
资料来源：[main.py:1-30](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)
## 检索流程架构
### Personalized PageRank检索
HippoRAG采用Personalized PageRank（PPR）算法进行关联检索，区别于传统的向量相似度检索：
```mermaid
graph LR
A[查询] --> B[向量相似度检索]
B --> C[获取初始候选节点]
C --> D[构建查询图]
D --> E[PPR迭代计算]
E --> F[节点重要性排序]
F --> G[返回关联段落]
```
### 检索配置参数
| 参数 | 说明 | 影响 |
|------|------|------|
| `retrieval_top_k` | 初始向量检索返回的文档数 | 候选集大小，影响PPR计算范围 |
| `linking_top_k` | 每步关联的节点数 | 检索的深度和广度 |
| `damping` | PPR阻尼因子 | 随机跳转概率，影响收敛速度 |
| `synonymy_edge_sim_threshold` | 同义边相似度阈值 | 控制哪些实体被视为同义 |
检索过程中，系统通过同义边（synonymy edges）建立实体间的语义关联，实现跨段落的事实关联发现。
## 问答流程架构
### 多步推理问答
HippoRAG支持迭代式问答，通过多步检索-推理交替提升答案质量：
```mermaid
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配置参数
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `max_qa_steps` | 1 | 最大问答迭代步数 |
| `qa_top_k` | 5 | 输入LLM的顶部文档数 |
调用示例：
```python
rag_results = hipporag.rag_qa(
queries=queries,
gold_docs=gold_docs,
gold_answers=answers
)
```
资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
## 部署架构
### 多后端支持
HippoRAG支持多种LLM和嵌入模型部署方式：
#### OpenAI模型部署
```python
hipporag = HippoRAG(
save_dir=save_dir,
llm_model_name='gpt-4o-mini',
embedding_model_name='nvidia/NV-Embed-v2'
)
```
#### Azure OpenAI部署
```python
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本地部署
```bash
vllm serve meta-llama/Llama-3.1-8B-Instruct \
--tensor-parallel-size 2 \
--max_model_len 4096 \
--gpu-memory-utilization 0.95 \
--port 6578
```
```python
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的核心依赖层次：
| 依赖层级 | 库 | 版本 | 用途 |
|---------|-----|------|------|
| 深度学习框架 | torch | 2.5.1 | Tensor计算 |
| 推理框架 | vLLM | 0.6.6.post1 | 本地LLM推理 |
| 嵌入模型 | transformers | 4.45.2 | 模型加载 |
| 图计算 | networkx | 3.4.2 | 图结构操作 |
| 图算法 | python_igraph | 0.11.8 | 图算法实现 |
| API调用 | openai | 1.91.1 | OpenAI API |
| 向量嵌入 | gritlm | 1.0.2 | GritLM嵌入模型 |
| 数据验证 | pydantic | 2.10.4 | 配置管理 |
| 重试机制 | tenacity | 8.5.0 | 容错处理 |
| 分词 | tiktoken | 0.7.0 | Token计数 |
资料来源：[setup.py:1-30](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)
## 数据流架构
### 完整RAG流程
```mermaid
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](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
## 总结
HippoRAG的系统架构设计体现了以下核心原则：
1. **模块化设计**：各功能模块（嵌入模型、信息抽取、图构建、检索、QA）职责清晰，便于扩展和维护
2. **配置驱动**：通过`BaseConfig`类实现类型安全的配置管理，支持多种部署场景
3. **海马体启发的持久化索引**：通过OpenIE抽取事实知识并构建异构图，实现长期记忆的持久化存储
4. **PPR关联检索**：采用Personalized PageRank算法挖掘实体间的语义关联，克服传统向量检索的局限性
5. **多后端兼容**：统一接口支持OpenAI、vLLM、Azure等多种部署方式，提高系统灵活性
---
## 知识图谱构建
### 相关页面
相关主题：[系统架构设计](#p3), [OpenIE信息抽取](#p7)
相关源码文件
以下源码文件用于生成本页说明：
- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)
- [src/hipporag/HippoRAG.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/HippoRAG.py) (README.md中的代码结构引用)
- [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py) (使用示例)
- [setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py) (依赖声明)
# 知识图谱构建
HippoRAG的知识图谱构建是整个框架的核心组件，负责将原始文档语料转化为结构化的图知识表示。该模块整合了开放信息抽取（OpenIE）、嵌入向量计算和图连接构建等技术，实现了类似人类海马体的知识组织和关联机制。
## 核心配置参数
知识图谱构建通过`BaseConfig`类进行配置管理，主要涉及以下关键参数：
| 参数名称 | 默认值 | 说明 |
|---------|--------|------|
| `graph_type` | `facts_and_sim_passage_node_unidirectional` | 图类型，定义节点和边的组织方式 |
| `openie_mode` | `openai-gpt` | 开放信息抽取模式 |
| `information_extraction_model_name` | `gpt-4o-mini` | 信息抽取使用的模型名称 |
| `synonymy_edge_topk` | `2047` | 构建同义词边时KNN检索的K值 |
| `synonymy_edge_sim_threshold` | `0.8` | 同义词边的相似度阈值 |
| `is_directed_graph` | `False` | 图是否为有向图 |
资料来源：[config_utils.py:参数定义](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)
## 图谱构建流程
知识图谱的构建遵循以下标准化流程：
```mermaid
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:代码结构](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
## 图类型配置
HippoRAG支持多种图谱拓扑结构，通过`graph_type`参数进行选择：
| 图类型 | 描述 | 适用场景 |
|-------|------|---------|
| `facts_and_sim_passage_node_unidirectional` | 事实节点与段落节点单向连接，含同义词边 | 默认配置，适合大多数问答场景 |
| `facts_and_sim_passage_node_bidirectional` | 事实节点与段落节点双向连接 | 需要更密集的信息流动 |
| `facts_passage_node` | 仅含事实边和段落节点 | 轻量级图谱，减少计算开销 |
同义词边的构建采用KNN（K近邻）算法，在嵌入向量空间中寻找语义相似的节点对：
```python
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:图构建参数](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)
## 开放信息抽取模式
HippoRAG支持两种OpenIE实现方式：
| 模式 | 说明 | 依赖 |
|------|------|------|
| `openai-gpt` | 使用OpenAI GPT模型进行信息抽取 | `OPENAI_API_KEY`环境变量 |
| `vllm-offline` | 使用本地vLLM部署的模型 | vLLM服务配置 |
| `Transformers-offline` | 使用Transformers库本地加载模型 | GPU显存充足 |
信息抽取模块位于`src/hipporag/information_extraction/`目录，包含以下实现：
- `openie_openai_gpt.py`：OpenAI GPT模型的OpenIE实现
- `openie_vllm_offline.py`：vLLM离线部署模型的OpenIE实现
资料来源：[README.md:信息抽取模块](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
## 索引构建接口
HippoRAG通过`HippoRAG`类提供统一的索引构建接口：
```python
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`或构造函数直接传入：
```python
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:索引配置](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)
## 嵌入模型配置
图谱构建过程中的向量计算支持多种嵌入模型：
| 模型类型 | 模型名称示例 | 配置方式 |
|---------|-------------|---------|
| NVIDIA | `nvidia/NV-Embed-v2` | 直接指定模型名 |
| GritLM | `GritLM` | 通过`embedding_model_name`指定 |
| Contriever | `Contriever` | 通过`embedding_model_name`指定 |
| OpenAI兼容 | 自定义模型 | `embedding_base_url`指定端点 |
| Azure OpenAI | `text-embedding-3-small` | `azure_embedding_endpoint`配置 |
嵌入相关配置参数：
| 参数 | 默认值 | 说明 |
|-----|--------|------|
| `embedding_batch_size` | 16 | 嵌入计算的批次大小 |
| `embedding_return_as_normalized` | True | 是否返回归一化向量 |
| `embedding_max_seq_len` | 2048 | 最大序列长度 |
| `embedding_model_dtype` | `auto` | 数据类型（float16/float32/bfloat16/auto） |
资料来源：[config_utils.py:嵌入配置](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)
## 依赖组件
知识图谱构建依赖以下核心库：
| 依赖库 | 版本 | 用途 |
|-------|------|------|
| `networkx` | 3.4.2 | 图数据结构与算法实现 |
| `python_igraph` | 0.11.8 | 图可视化与分析 |
| `torch` | 2.5.1 | 深度学习张量计算 |
| `transformers` | 4.45.2 | 预训练模型加载 |
| `gritlm` | 1.0.2 | GritLM嵌入模型支持 |
| `tiktoken` | 0.7.0 | Tokenization |
| `pydantic` | 2.10.4 | 配置数据验证 |
资料来源：[setup.py:依赖声明](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)
## 增量更新与删除
HippoRAG支持对已构建的图谱进行增量操作：
```python
# 添加新文档
hipporag.index(docs=["新文档内容..."])
# 删除指定文档
hipporag.delete(docs_to_delete=["要删除的文档..."])
# 验证更新效果
result = hipporag.rag_qa(queries=queries,
gold_docs=gold_docs,
gold_answers=answers)
```
增量更新会重新计算相关节点的嵌入向量，并更新图中的连接关系。
资料来源：[tests_openai.py:增量操作](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/tests_openai.py)
## 环境变量配置
图谱构建前需正确配置以下环境变量：
```bash
export CUDA_VISIBLE_DEVICES=0,1,2,3 # GPU设备选择
export HF_HOME= # HuggingFace模型缓存目录
export OPENAI_API_KEY= # OpenAI API密钥（使用OpenAI模式时）
```
资料来源：[README.md:环境配置](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
---
## LLM模型集成
### 相关页面
相关主题：[系统架构设计](#p3), [Embedding模型集成](#p6)
相关源码文件
以下源码文件用于生成本页说明：
- [src/hipporag/llm/base.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/base.py)
- [src/hipporag/llm/openai_gpt.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/openai_gpt.py)
- [src/hipporag/llm/vllm_offline.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/vllm_offline.py)
- [src/hipporag/llm/bedrock_llm.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/bedrock_llm.py)
- [src/hipporag/llm/transformers_llm.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/transformers_llm.py)
# LLM模型集成
## 概述
HippoRAG的LLM模型集成模块提供了一套统一的接口，用于对接多种大语言模型提供商。该模块位于`src/hipporag/llm/`目录下，通过抽象基类`LLMInterface`定义标准接口，各具体实现类继承该基类以支持不同的模型服务。
主要支持以下模型服务：
| 提供商 | 实现类 | 特点 |
|--------|--------|------|
| OpenAI | `OpenAIGPT` | 云端API调用，支持自定义endpoint |
| vLLM | `VLLMOffline` | 本地离线推理，高吞吐量 |
| AWS Bedrock | `BedrockLLM` | 云端托管，支持Claude等模型 |
| HuggingFace Transformers | `TransformersLLM` | 本地transformers库推理 |
资料来源：[base.py:1-20](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/base.py)
## 架构设计
### 类层次结构
HippoRAG采用面向对象设计模式，通过抽象基类定义统一接口规范：
```mermaid
graph TD
A[LLMInterface
抽象基类] --> B[OpenAIGPT]
A --> C[VLLMOffline]
A --> D[BedrockLLM]
A --> E[TransformersLLM]
F[调用方] --> A
```
### 接口规范
`LLMInterface`定义了所有LLM实现必须遵循的核心方法：
| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `__call__` | `prompt`, `system_prompt`, `keyword` | `str` | 同步调用接口 |
| `batch_call` | `prompts`, `system_prompts`, `keywords` | `List[str]` | 批量调用接口 |
| `_call` | `prompt`, `system_prompt`, `keyword` | `str` | 具体实现方法 |
| `_batch_call` | `prompts`, `system_prompts`, `keywords` | `List[str]` | 批量实现方法 |
资料来源：[base.py:10-60](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/base.py)
## 核心实现
### 基础抽象类
基础类`LLMInterface`位于`base.py`，采用ABC抽象基类模式：
```python
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
):
```
关键配置参数说明：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `model_name` | `str` | 必填 | 模型标识符 |
| `api_key` | `str` | `None` | API密钥 |
| `api_base` | `str` | `None` | API服务端点 |
| `timeout` | `int` | `120` | 超时时间（秒） |
| `max_tokens` | `int` | `256` | 最大生成token数 |
| `temperature` | `float` | `0.0` | 采样温度 |
| `request_timeout` | `int` | `120` | 请求超时 |
| `top_p` | `float` | `1.0` | 核采样概率 |
资料来源：[base.py:10-25](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/base.py)
### OpenAI GPT集成
`OpenAIGPT`类封装了OpenAI API的调用逻辑：
```python
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](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/openai_gpt.py)
### vLLM离线推理
`VLLMOffline`类支持本地vLLM服务器推理，适用于需要离线或私有化部署的场景：
```python
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](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/vllm_offline.py)
### AWS Bedrock集成
`BedrockLLM`类提供对AWS Bedrock平台模型的支持：
```python
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特定配置：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `aws_access_key` | `str` | `None` | AWS访问密钥 |
| `aws_secret_key` | `str` | `None` | AWS秘密密钥 |
| `aws_region_name` | `str` | `"us-east-1"` | AWS区域 |
支持的Bedrock模型：
- Claude系列（通过Anthropic）
- Titan系列
- Llama系列
资料来源：[bedrock_llm.py:1-60](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/bedrock_llm.py)
### HuggingFace Transformers
`TransformersLLM`类支持直接使用HuggingFace transformers库进行本地推理：
```python
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特定配置：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `model_name` | `str` | 必填 | HuggingFace模型标识 |
| `model_path` | `str` | `None` | 本地模型路径 |
| `auth_token` | `str` | `None` | HuggingFace认证令牌 |
| `device` | `str` | `"cuda"` | 运行设备（cuda/cpu） |
资料来源：[transformers_llm.py:1-60](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/transformers_llm.py)
## 使用流程
### 初始化与调用流程
```mermaid
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[返回生成结果]
```
### 代码示例
```python
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("你的问题")
```
## 配置选项汇总
| 配置项 | 适用类 | 说明 |
|--------|--------|------|
| `model_name` | 所有 | 模型名称或路径 |
| `api_key` | OpenAI/Bedrock/vLLM | 认证密钥 |
| `api_base` | OpenAI/vLLM | API服务端点 |
| `aws_access_key` | Bedrock | AWS访问密钥 |
| `aws_secret_key` | Bedrock | AWS秘密密钥 |
| `aws_region_name` | Bedrock | AWS区域 |
| `auth_token` | Transformers | HuggingFace令牌 |
| `model_path` | Transformers | 本地模型路径 |
| `device` | Transformers | 计算设备 |
| `timeout` | 所有 | 超时时间（秒） |
| `max_tokens` | 所有 | 最大生成长度 |
| `temperature` | 所有 | 采样温度 |
| `top_p` | 所有 | 核采样参数 |
| `request_timeout` | 所有 | 请求超时 |
## 扩展开发
如需添加新的LLM提供商，可按以下步骤扩展：
1. 创建新文件如`src/hipporag/llm/custom_llm.py`
2. 继承`LLMInterface`抽象基类
3. 实现`_call`和`_batch_call`抽象方法
4. 在模块`__init__.py`中导出新类
```python
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凭证和区域信息
---
## Embedding模型集成
### 相关页面
相关主题：[系统架构设计](#p3), [LLM模型集成](#p5)
相关源码文件
以下源码文件用于生成本页说明：
- [src/hipporag/embedding_model/base.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/base.py)
- [src/hipporag/embedding_model/NVEmbedV2.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/NVEmbedV2.py)
- [src/hipporag/embedding_model/GritLM.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/GritLM.py)
- [src/hipporag/embedding_model/Transformers.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/Transformers.py)
- [src/hipporag/embedding_model/VLLM.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/VLLM.py)
- [src/hipporag/embedding_model/__init__.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/__init__.py)
- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)
- [src/hipporag/HippoRAG.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/HippoRAG.py)
# Embedding模型集成
## 概述
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]()
### 类层次结构
```mermaid
graph TD
A[BaseEmbeddingModel] --> B[NVEmbedV2Model]
A --> C[GritLMModel]
A --> D[TransformersEmbeddingModel]
A --> E[VLLMEmbeddingModel]
F[HippoRAG] --> A
G[EmbeddingStore] --> A
```
### 嵌入模型选择流程
```mermaid
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` 是所有嵌入模型的基类，定义了统一的接口规范。所有具体实现必须继承此类并实现核心方法。
#### 核心属性
| 属性名 | 类型 | 说明 |
|--------|------|------|
| `embedding_type` | str | 嵌入向量的数据类型标识，如 "float" |
| `batch_size` | int | 默认批处理大小 |
| `search_query_instr` | set | 查询指令集合，用于区分不同检索任务 |
资料来源：[src/hipporag/embedding_model/base.py:1-30]()
#### 核心方法
| 方法名 | 参数 | 返回值 | 说明 |
|--------|------|--------|------|
| `encode` | texts: List[str] | np.array | 单次调用编码单个文本批次 |
| `batch_encode` | texts: List[str], **kwargs | np.array | 分批编码大量文本，支持进度显示 |
```python
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是高性能嵌入模型，支持本地部署和量化推理。
#### 初始化参数
| 参数 | 来源配置 | 默认值 | 说明 |
|------|----------|--------|------|
| `global_config` | 必填 | - | 全局配置对象 |
| `embedding_model_name` | 必填 | - | 模型名称，格式为 "nvidia/NV-Embed-v2" |
#### 关键实现
```python
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 是专门用于检索和生成的统一嵌入模型。
#### 初始化参数
| 参数 | 来源配置 | 默认值 | 说明 |
|------|----------|--------|------|
| `global_config` | 必填 | - | 全局配置对象 |
| `embedding_model_name` | 必填 | - | 模型名称，格式为 "GritLM/..." |
#### 关键实现
```python
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 模型。
#### 初始化参数
| 参数 | 来源配置 | 默认值 | 说明 |
|------|----------|--------|------|
| `global_config` | 必填 | - | 全局配置对象 |
| `embedding_model_name` | 必填 | - | 模型名称，格式为 "Transformers/模型ID" |
#### 关键实现
```python
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 嵌入服务端点。
#### 初始化参数
| 参数 | 来源配置 | 默认值 | 说明 |
|------|----------|--------|------|
| `global_config` | 必填 | - | 全局配置对象，需包含 `embedding_base_url` |
| `embedding_model_name` | 必填 | - | 模型名称，格式为 "VLLM/模型名" |
#### 关键实现
```python
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` 类管理。
### 嵌入模型配置项
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `embedding_batch_size` | int | 16 | 调用嵌入模型的批次大小 |
| `embedding_return_as_normalized` | bool | True | 是否返回归一化嵌入向量 |
| `embedding_max_seq_len` | int | 2048 | 嵌入模型的最大序列长度 |
| `embedding_model_dtype` | str | "auto" | 数据类型，可选 float16/float32/bfloat16/auto |
| `synonymy_edge_topk` | int | 2047 | 构建同义词边时的 KNN 检索数量 |
| `synonymy_edge_query_batch_size` | int | 1000 | 同义词边构建的查询批次大小 |
| `synonymy_edge_key_batch_size` | int | 10000 | 同义词边构建的键批次大小 |
| `synonymy_edge_sim_threshold` | float | 0.8 | 同义词相似度阈值 |
资料来源：[src/hipporag/utils/config_utils.py:1-50]()
## 使用方式
### 模型选择器
通过前缀自动选择对应的嵌入模型实现：
```python
from hipporag.embedding_model import get_embedding_model
# 获取嵌入模型实例
embedding_model = get_embedding_model(
global_config=config,
embedding_model_name="nvidia/NV-Embed-v2"
)
```
#### 前缀映射表
| 前缀 | 模型类 | 用途 |
|------|--------|------|
| `nvidia/NV-Embed` | NVEmbedV2Model | NVIDIA 高性能嵌入 |
| `GritLM/` | GritLMModel | 检索生成统一模型 |
| `Transformers/` | TransformersEmbeddingModel | HuggingFace 模型 |
| `VLLM/` | VLLMEmbeddingModel | vLLM 远程服务 |
资料来源：[src/hipporag/embedding_model/__init__.py:1-30]()
### 完整使用示例
#### OpenAI 兼容模型
```python
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 模型
```bash
# 启动 vLLM 嵌入服务
vllm serve nvidia/NV-Embed-v2 --port 8080
```
```python
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集成
### 初始化流程
```mermaid
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包依赖
| 包名 | 版本 | 用途 |
|------|------|------|
| `torch` | 2.5.1 | 张量计算和CUDA支持 |
| `transformers` | 4.45.2 | 模型加载和推理 |
| `sentence-transformers` | - | SentenceTransformer模型支持 |
| `gritlm` | 1.0.2 | GritLM模型支持 |
| `vllm` | 0.6.6.post1 | vLLM服务端支持 |
| `numpy` | - | 向量数据处理 |
资料来源：[setup.py:1-30]()
## 扩展开发
### 添加新的嵌入模型
1. 继承 `BaseEmbeddingModel` 基类
2. 实现 `encode()` 方法
3. 在 `__init__.py` 的 `get_embedding_model()` 中添加模型选择逻辑
```python
# 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
```
```python
# 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)
# ... 其他模型
```
## 性能优化建议
| 优化项 | 说明 |
|--------|------|
| 批处理大小 | 根据GPU显存调整 `embedding_batch_size`，默认16 |
| 序列长度 | 确保 `embedding_max_seq_len` 匹配模型能力 |
| 归一化 | 启用 `embedding_return_as_normalized=True` 可加速相似度计算 |
| 混合部署 | 将嵌入模型与LLM部署在不同GPU上避免显存竞争 |
资料来源：[README.md - Quick Start]()
---
## OpenIE信息抽取
### 相关页面
相关主题：[知识图谱构建](#p4), [Prompt模板管理](#p8)
相关源码文件
以下源码文件用于生成本页说明：
- [src/hipporag/information_extraction/openie_openai_gpt.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/information_extraction/openie_openai_gpt.py)
- [src/hipporag/information_extraction/openie_vllm_offline.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/information_extraction/openie_vllm_offline.py)
- [src/hipporag/information_extraction/openie_transformers_offline.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/information_extraction/openie_transformers_offline.py)
- [src/hipporag/prompts/templates/triple_extraction.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/prompts/templates/triple_extraction.py)
- [src/hipporag/prompts/templates/ner.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/prompts/templates/ner.py)
- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)
# OpenIE信息抽取
## 概述
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信息抽取模块采用模块化设计，主要包含以下核心组件：
```mermaid
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`进行选择：
| 模式 | 配置值 | 描述 | 适用场景 |
|------|--------|------|----------|
| 在线模式 | `online` | 使用OpenAI GPT API进行实时抽取 | 快速原型开发、小规模数据集 |
| vLLM离线模式 | `offline` | 使用本地部署的vLLM服务进行批量抽取 | 大规模生产环境、降低成本 |
| Transformers离线模式 | `Transformers-offline` | 使用本地Transformers模型进行抽取 | 完全离线环境、特定模型需求 |
### 在线模式（OpenAI GPT）
在线模式使用OpenAI GPT模型进行信息抽取，是默认的运行模式。该模式配置简单，适合快速验证和小型数据集场景。
```python
# 配置示例
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推理服务进行批量信息抽取，是生产环境推荐的方式。
```python
# 配置示例
config = BaseConfig(
openie_mode='offline',
information_extraction_model_name='openie_openai_gpt' # 使用OpenIE格式
)
```
**部署要求：**
```bash
# 启动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库直接加载模型进行推理，适合完全离线或需要使用特定模型的场景。
```python
# 配置示例
config = BaseConfig(
openie_mode='Transformers-offline',
information_extraction_model_name='Transformers/Qwen/Qwen2.5-7B-Instruct'
)
```
使用示例（来自`test_transformers.py`）：
```python
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,
)
```
## 抽取流程
### 整体工作流
```mermaid
graph LR
A[文档集合] --> B[文档分块
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格式）
- 示例输入输出对
- 边界情况处理指南
**输出格式示例：**
```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相关配置选项：
| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `information_extraction_model_name` | Literal | `openie_openai_gpt` | 信息抽取模型类名 |
| `openie_mode` | Literal | `online` | OpenIE运行模式：`online`、`offline`或`Transformers-offline` |
| `skip_graph` | bool | `False` | 是否跳过图构建（首次离线索引时设为True） |
| `save_openie` | bool | `True` | 是否保存OpenIE结果到磁盘 |
### 高级配置
| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `preprocess_encoder_name` | str | `gpt-4o` | 预处理编码器名称（用于文档分块） |
| `preprocess_chunk_max_token_size` | int | `None` | 每个chunk的最大token数，`None`表示整个文档作为单一chunk |
| `preprocess_chunk_overlap_token_size` | int | `128` | 相邻chunk之间的重叠token数 |
资料来源：[src/hipporag/utils/config_utils.py:28-72]()
## 使用指南
### 快速开始
#### 1. 环境配置
```bash
# 设置环境变量
export CUDA_VISIBLE_DEVICES=0,1,2,3
export HF_HOME=
export OPENAI_API_KEY=
# 激活环境
conda activate hipporag
```
#### 2. 基础使用示例
```python
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服务
```bash
export CUDA_VISIBLE_DEVICES=0,1
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export HF_HOME=
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：运行主程序
```bash
export CUDA_VISIBLE_DEVICES=2,3
export HF_HOME=
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结果会保存到文件。第二次运行时去掉该参数即可完成图构建：
```bash
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`是专门用于调试的小数据集
2. **清理缓存**：重新运行实验时，记得清除保存的文件：
```bash
rm reproduce/dataset/openie_results/openie_sample_results_*.json
rm -rf outputs/sample/
```
3. **vLLM离线模式调试**：当遇到问题时，将`hipporag/llm/vllm_offline.py`中的`tensor_parallel_size`设为1
4. **查看保存的OpenIE结果**：OpenIE结果默认保存，可直接检查输出格式是否正确
## 输出与存储
### OpenIE结果保存
OpenIE抽取结果默认保存到指定目录，文件命名格式包含模型和数据集信息：
```
outputs//_/openie_results/
└── openie__results_.json
```
### 结果格式
```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的知识图谱：
```mermaid
graph LR
A[三元组] --> B[实体节点]
A --> C[关系边]
B --> D[知识图谱]
C --> D
D --> E[个性化PageRank检索]
E --> F[LLM问答生成]
```
## 性能优化建议
### 1. 批量处理
离线模式支持批量调用，可显著提升处理速度：
```python
# 批量文档索引
hipporag.index(docs=large_documents_list)
```
### 2. GPU资源分配
- **vLLM服务**：分配专用GPU（如0,1）
- **主程序**：使用另一组GPU（如2,3）
- 通过`CUDA_VISIBLE_DEVICES`环境变量控制
### 3. 内存优化
```bash
# 调整最大序列长度
--max_model_len 4096
# 调整GPU内存利用率
--gpu-memory-utilization 0.95
```
### 4. 并行配置
```bash
export VLLM_WORKER_MULTIPROC_METHOD=spawn
```
## 常见问题
### Q1: 首次运行vLLM离线模式需要设置什么参数？
需要设置`--skip_graph`参数，因为首次运行时图尚未构建：
```bash
python main.py --openie_mode offline --skip_graph
```
### Q2: 如何切换不同的OpenIE模型？
通过修改`information_extraction_model_name`配置：
```python
# 使用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: 如何处理长文档？
对于过长的文档，建议先进行分块处理：
```python
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/
---
## Prompt模板管理
### 相关页面
相关主题：[OpenIE信息抽取](#p7), [LLM模型集成](#p5)
相关源码文件
以下源码文件用于生成本页说明：
- [src/hipporag/prompts/templates/README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/prompts/templates/README.md)
- [src/hipporag/HippoRAG.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/HippoRAG.py)
- [src/hipporag/StandardRAG.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/StandardRAG.py)
- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)
- [setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)
# Prompt模板管理
## 概述
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](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)
## 模板定义规范
### 文件命名规则
模板文件夹 `templates/` 被作为 `hipporag` 项目下的子模块处理。每个 `*.py` 文件（除 `__init__.py` 外）对应一个提示词模板，文件名（不含文件扩展名）将作为访问该模板的键名。
| 规则 | 说明 |
|------|------|
| 文件扩展名 | 必须为 `.py` |
| 排除文件 | `__init__.py` 不被视为模板 |
| 命名规范 | 使用下划线连接，如 `rag_qa_musique.py` |
| 访问键名 | 文件名去掉 `.py` 后缀，如 `rag_qa_musique` |
资料来源：[src/hipporag/prompts/templates/README.md:5-8]()
### 模板变量规范
每个模板文件必须定义一个名为 `prompt_template` 的变量来存储提示词内容。该变量可以是以下三种形式之一：
```python
# 形式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}"}
]
```
| 形式 | 数据类型 | 占位符格式 | 适用场景 |
|------|----------|------------|----------|
| 字符串 | `str` | `${variable}` | 简单模板 |
| Template对象 | `Template` | `$variable` 或 `${variable}` | 需要转义的场景 |
| 聊天历史 | `List[dict]` | `${variable}` | 多轮对话模板 |
资料来源：[src/hipporag/prompts/templates/README.md:10-17]()
## 模板渲染机制
### PromptTemplateManager
`PromptTemplateManager` 是模板系统的核心管理类，负责模板的加载、验证和渲染。
#### 模板选择逻辑
HippoRAG在执行检索和QA任务时，会根据当前数据集选择对应的提示词模板。核心逻辑如下：
```python
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]()
#### 模板渲染流程
```mermaid
graph TD
A[开始渲染] --> B{数据集模板是否存在?}
B -->|是| C[使用数据集特定模板]
B -->|否| D[使用musique通用模板]
C --> E[调用render方法]
D --> E
E --> F[替换prompt_user占位符]
F --> G[返回渲染后的消息]
```
### 模板渲染示例
HippoRAG在QA阶段将检索到的文档传入模板进行渲染：
```python
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的默认提示词模板，用于多跳问答场景。
```python
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` 类管理模板相关的配置参数：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `dataset` | `str` | `None` | 当前数据集名称，用于选择对应模板 |
| `max_qa_steps` | `int` | `1` | 单问题最大迭代推理步数 |
| `qa_top_k` | `int` | `5` | 输入QA模型的文档数量 |
```python
# 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]()
## 使用示例
### 基本使用流程
```python
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. 使用 `${}` 占位符标记需替换的位置
```python
# 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` 方法时调用模板管理器：
```python
# 位置: 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` 类使用完全相同的模板管理逻辑：
```python
# 位置: 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模板管理系统具有以下特点：
| 特性 | 描述 |
|------|------|
| **模块化设计** | 模板按数据集组织，便于维护和扩展 |
| **灵活格式** | 支持字符串、Template对象和聊天历史三种格式 |
| **自动回退** | 未知数据集自动回退到MuSiQue通用模板 |
| **统一接口** | 为HippoRAG和StandardRAG提供一致的模板访问 |
| **易于扩展** | 仅需创建新的 `.py` 文件即可添加模板 |
该设计使得HippoRAG能够优雅地处理不同数据集的提示词需求，同时保持代码的简洁性和可维护性。
---
## 实验复现指南
### 相关页面
相关主题：[快速入门指南](#p2), [评估与测试](#p10)
相关源码文件
以下源码文件用于生成本页说明：
- [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)
- [main_azure.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main_azure.py)
- [main_dpr.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main_dpr.py)
- [reproduce/README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/reproduce/README.md)
- [reproduce/dataset/sample_corpus.json](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/reproduce/dataset/sample_corpus.json)
# 实验复现指南
本页面详细说明如何基于 HippoRAG 仓库复现论文中的实验结果。指南涵盖环境配置、数据准备、索引构建、检索与问答等完整流程。
## 1. 环境准备
### 1.1 系统要求
HippoRAG 对运行环境有明确的依赖要求，需确保满足以下条件：
| 组件 | 版本要求 | 说明 |
|------|----------|------|
| Python | >= 3.10 | 必须使用 Python 3.10 或更高版本 |
| CUDA | 兼容 | 需要 GPU 支持进行模型推理 |
| GPU 显存 | 视模型而定 | 建议多卡以支持大型模型 |
### 1.2 依赖安装
首先创建独立的 conda 环境并安装核心依赖：
```bash
conda create -n hipporag python=3.10
conda activate hipporag
pip install hipporag
```
资料来源：[README.md:1]()
### 1.3 环境变量配置
启动 HippoRAG 前需配置以下环境变量：
```bash
# GPU 配置
export CUDA_VISIBLE_DEVICES=0,1,2,3
# HuggingFace 模型缓存路径
export HF_HOME=
# OpenAI API 密钥（使用 OpenAI 模型时必需）
export OPENAI_API_KEY=
# 激活环境
conda activate hipporag
```
资料来源：[README.md:1]()
### 1.4 vLLM 本地部署环境
如需使用本地 vLLM 部署，需额外配置：
```bash
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export HF_HOME=
```
## 2. 数据准备
### 2.1 数据集来源
实验所需数据集可从以下渠道获取：
| 数据集类型 | 来源 | 说明 |
|------------|------|------|
| 预定义数据集 | `reproduce/dataset/` 目录 | 仓库已包含部分采样数据集 |
| 完整数据集 | [HuggingFace HippoRAG_v2](https://huggingface.co/datasets/osunlp/HippoRAG_v2) | 包含完整的评估数据集 |
| OpenIE 结果 | `outputs/musique/` 目录 | 已预处理的信息抽取结果 |
资料来源：[README.md:1]()
### 2.2 数据目录结构
推荐将数据集统一放置在 `reproduce/dataset/` 目录下：
```
reproduce/
└── dataset/
├── sample_corpus.json # 语料库文件
├── sample.json # 查询文件（含答案）
└── _corpus.json
```
### 2.3 语料库 JSON 格式
语料库文件需遵循特定的 JSON 数组格式：
```json
[
{
"title": "FIRST PASSAGE TITLE",
"text": "FIRST PASSAGE TEXT",
"idx": 0
},
{
"title": "SECOND PASSAGE TITLE",
"text": "SECOND PASSAGE TEXT",
"idx": 1
}
]
```
**字段说明：**
| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| title | string | 是 | 段落标题 |
| text | string | 是 | 段落正文内容 |
| idx | integer | 是 | 段落唯一索引 |
资料来源：[reproduce/README.md]()
### 2.4 查询 JSON 格式（可选）
如需进行评估，需准备包含问题和标准答案的查询文件：
```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
}
]
}
]
```
**字段说明：**
| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| id | string | 是 | 问题唯一标识 |
| question | string | 是 | 查询问题文本 |
| answer | array | 是 | 标准答案列表 |
| answerable | boolean | 是 | 问题是否可答 |
| paragraphs | array | 是 | 支持段落列表 |
### 2.5 长文本分块
对于过长的段落，可能需要在 OpenIE 处理前进行分块：
> 当准备数据时，可能需要对每个段落进行分块，因为较长的段落可能对 OpenIE 过程过于复杂。
资料来源：[README.md:1]()
## 3. 实验运行流程
### 3.1 整体工作流
```mermaid
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` 支持多种命令行参数配置：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| --dataset | string | 必需 | 数据集名称 |
| --llm_name | string | 必需 | LLM 模型名称 |
| --llm_base_url | string | 必需 | LLM API 端点 |
| --embedding_name | string | 必需 | 嵌入模型名称 |
| --openie_mode | string | 'gpt-4o-mini' | OpenIE 运行模式 |
资料来源：[main.py:1]()
### 3.3 配置类参数
HippoRAG 使用 `BaseConfig` 类管理核心配置参数：
| 参数 | 说明 | 默认值 |
|------|------|--------|
| graph_type | 图类型 | facts_and_sim_passage_node_unidirectional |
| embedding_batch_size | 嵌入批处理大小 | 8 |
| max_new_tokens | 最大生成 token 数 | None |
| retrieval_top_k | 检索返回文档数 | 200 |
| linking_top_k | 每步链接节点数 | 5 |
| max_qa_steps | QA 最大推理步数 | 3 |
| qa_top_k | QA 输入 top k 文档数 | 5 |
| damping | PPR 算法阻尼因子 | 0.5 |
资料来源：[src/hipporag/utils/config_utils.py:1]()
## 4. 使用 OpenAI 模型
### 4.1 快速启动流程
使用 OpenAI 模型进行实验的标准流程：
```bash
# 设置数据集
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 端点时需指定额外参数：
```python
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 兼容的本地推理服务，启动步骤如下：
```bash
# 使用指定 GPU 启动服务（留足显存给嵌入模型）
export CUDA_VISIBLE_DEVICES=0,1
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export HF_HOME=
# 启动模型服务
vllm serve meta-llama/Llama-3.3-70B-Instruct \
--tensor-parallel-size 2 \
--max_model_len 4096 \
--gpu-memory-utilization 0.95 \
--port 6578
```
**参数调整建议：**
| 参数 | 说明 | 调整建议 |
|------|------|----------|
| tensor-parallel-size | 并行 GPU 数量 | 根据可用 GPU 调整 |
| max_model_len | 最大模型上下文长度 | 根据显存调整，显存不足时减小 |
| gpu-memory-utilization | GPU 显存利用率 | 默认为 0.95，OOM 时减小 |
资料来源：[README.md:1]()
### 5.2 运行主程序
vLLM 服务启动后，使用另一组 GPU 运行主程序：
```bash
# 设置另一组 GPU
export CUDA_VISIBLE_DEVICES=2,3
export HF_HOME=
# 运行实验
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 轻量级测试配置
为节省测试成本，可使用较小的模型：
```bash
# 测试用 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 模型测试
验证环境配置正确性的快速测试：
```bash
export OPENAI_API_KEY=
conda activate hipporag
python tests_openai.py
```
该测试成本可忽略不计，可用于验证基本功能。
### 6.2 本地模型测试
使用本地部署模型进行完整功能测试：
```bash
export CUDA_VISIBLE_DEVICES=0
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export HF_HOME=
# 启动 vLLM 服务后
CUDA_VISIBLE=1 python tests_local.py
```
### 6.3 测试覆盖范围
测试脚本验证以下核心模块功能：
- 索引构建（Indexing）
- 图加载（Graph Loading）
- 文档删除（Document Deletion）
- 增量更新（Incremental Updates）
资料来源：[README.md:1]()
## 7. 完整示例代码
### 7.1 基本使用流程
以下代码展示了完整的 HippoRAG 使用流程：
```python
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 兼容端点
```python
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 核心逻辑
```python
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 2 论文 | [arXiv:2502.14802](https://arxiv.org/abs/2502.14802) |
| HippoRAG 1 论文 | [arXiv:2405.14831](https://arxiv.org/abs/2405.14831) |
| HuggingFace 数据集 | [osunlp/HippoRAG_v2](https://huggingface.co/datasets/osunlp/HippoRAG_v2) |
| vLLM 文档 | [docs.vllm.ai](https://docs.vllm.ai/en/latest/getting_started/quickstart.html) |
| GitHub 仓库 | [OSU-NLP-Group/HippoRAG](https://github.com/OSU-NLP-Group/HippoRAG) |
---
## 评估与测试
### 相关页面
相关主题：[实验复现指南](#p9), [Prompt模板管理](#p8)
相关源码文件
以下源码文件用于生成本页说明：
- [src/hipporag/evaluation/qa_eval.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/evaluation/qa_eval.py)
- [src/hipporag/evaluation/retrieval_eval.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/evaluation/retrieval_eval.py)
- [src/hipporag/evaluation/base.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/evaluation/base.py)
- [tests_openai.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/tests_openai.py)
- [tests_local.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/tests_local.py)
- [tests_azure.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/tests_azure.py)
# 评估与测试
## 概述
HippoRAG 提供了完整的评估与测试框架，用于验证系统的索引构建、检索质量和问答能力。评估模块位于 `src/hipporag/evaluation/` 目录下，分为问答评估（QA Evaluation）和检索评估（Retrieval Evaluation）两个核心组件。资料来源：[README.md:代码结构]()
该框架支持多种部署方式的测试，包括 OpenAI API、Azure OpenAI Service 和本地 vLLM 部署。通过统一的测试接口，开发者可以验证核心模块的功能完整性，包括索引构建、图加载、文档删除和增量更新等关键能力。
---
## 评估模块架构
### 模块结构
HippoRAG 的评估系统采用分层设计，包含基础评估类和具体评估实现。
| 模块 | 文件路径 | 功能描述 |
|------|----------|----------|
| 基础评估类 | `src/hipporag/evaluation/base.py` | 定义 `BaseMetric` 基类，供所有评估指标继承 |
| 问答评估 | `src/hipporag/evaluation/qa_eval.py` | 实现问答任务的评估指标 |
| 检索评估 | `src/hipporag/evaluation/retrieval_eval.py` | 实现检索任务的评估指标 |
资料来源：[README.md:代码结构]()
### 评估流程
```mermaid
graph TD
A[输入查询] --> B[检索阶段]
B --> C[文档排序]
C --> D[Top-K 文档]
D --> E[QA 模型回答]
E --> F[评估结果]
G[黄金标准] --> F
D --> G
E --> G
```
评估系统通过对比系统输出与黄金标准（gold standard）来计算性能指标。在 `rag_qa` 方法中，系统接收查询、黄金文档和黄金答案，并返回包含评估指标的完整结果。资料来源：[tests_openai.py:测试流程]()
---
## 核心评估指标
### 问答评估（QA Evaluation）
问答评估模块负责衡量 HippoRAG 生成答案的质量。评估过程接收以下输入参数：
| 参数名 | 类型 | 描述 |
|--------|------|------|
| queries | List[str] | 查询问题列表 |
| gold_docs | List[List[str]] | 每个查询对应的黄金文档 |
| gold_answers | List[List[str]] | 每个查询对应的黄金答案 |
资料来源：[tests_openai.py:评估参数]()
```python
# 典型评估调用示例
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..."],
["Erik Hort's birthplace is Montebello.",
"Montebello is a part of Rockland County."]
]
result = hipporag.rag_qa(queries=queries,
gold_docs=gold_docs,
gold_answers=answers)
```
### 检索评估（Retrieval Evaluation）
检索评估模块衡量文档检索的准确性和相关性。该模块评估系统是否能正确识别与查询相关的文档，支持多跳推理场景下的关联检索评估。
---
## 测试框架
### 测试类型概览
HippoRAG 提供了三种测试方式以适应不同的部署环境：
| 测试类型 | 测试文件 | 适用场景 |
|----------|----------|----------|
| OpenAI 测试 | `tests_openai.py` | 使用 OpenAI API 进行测试 |
| 本地测试 | `tests_local.py` | 使用本地 vLLM 部署进行测试 |
| Azure 测试 | `tests_azure.py` | 使用 Azure OpenAI Service 进行测试 |
资料来源：[README.md:Testing](), [tests_openai.py](), [tests_local.py]()
### 测试环境配置
#### OpenAI 测试
OpenAI 测试是最简单的方式，无需本地部署 LLM。只需配置 API 密钥即可运行：
```bash
export OPENAI_API_KEY=
conda activate hipporag
python tests_openai.py
```
资料来源：[README.md:OpenAI Test]()
#### 本地测试（vLLM）
本地测试需要先部署 vLLM 服务器，然后运行测试脚本：
```bash
# 步骤 1：部署 vLLM 服务器
export CUDA_VISIBLE_DEVICES=0
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export HF_HOME=
vllm serve meta-llama/Llama-3.1-8B-Instruct \
--tensor-parallel-size 2 \
--max_model_len 4096 \
--gpu-memory-utilization 0.95 \
--port 6578
# 步骤 2：运行测试
CUDA_VISIBLE=1 python tests_local.py
```
资料来源：[README.md:Local Test]()
#### Azure 测试
Azure 测试使用 Azure OpenAI Service 的部署端点进行测试，配置方式如下：
```python
hipporag = HippoRAG(save_dir=save_dir,
llm_model_name=llm_model_name,
embedding_model_name=embedding_model_name,
azure_endpoint="https://[ENDPOINT].openai.azure.com/...",
azure_embedding_endpoint="https://[ENDPOINT].openai.azure.com/...")
```
### 测试覆盖范围
HippoRAG 的测试套件覆盖以下核心功能：
| 测试场景 | 描述 |
|----------|------|
| 索引构建 | 验证文档索引的完整性和正确性 |
| 图加载 | 验证知识图谱的加载和解析 |
| 文档删除 | 验证从索引中删除文档的功能 |
| 增量更新 | 验证向现有索引添加新文档的能力 |
资料来源：[README.md:Testing]()
### 测试执行流程
```mermaid
graph LR
A[准备测试数据] --> B[初始化 HippoRAG]
B --> C[执行索引构建]
C --> D[运行 RAG QA]
D --> E[验证评估结果]
E --> F{测试通过?}
F -->|是| G[输出结果]
F -->|否| H[报告错误]
```
---
## HippoRAG 类测试方法
### 主要测试方法
HippoRAG 类提供了 `rag_qa` 方法用于执行检索增强问答并返回评估结果：
```python
def rag_qa(queries: List[str],
gold_docs: List[List[str]],
gold_answers: List[List[str]]) -> Any
```
返回值包含评估指标和系统输出，可通过切片 `[-2:]` 获取最终的评估结果。
资料来源：[tests_openai.py:rag_qa调用](), [tests_local.py:rag_qa调用]()
### 端到端测试示例
以下是一个完整的端到端测试流程：
```python
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 = [
"George Rankin is a politician.",
"Cinderella attended the royal ball.",
"Erik Hort's birthplace is Montebello.",
"Montebello is a part of Rockland County."
]
# 执行索引
hipporag.index(docs=docs)
# 执行评估
queries = ["What is George Rankin's occupation?"]
answers = [["Politician"]]
gold_docs = [["George Rankin is a politician."]]
result = hipporag.rag_qa(queries=queries,
gold_docs=gold_docs,
gold_answers=answers)
print(result[-2:])
```
---
## 配置参数
### 全局配置（BaseConfig）
评估相关的配置参数位于 `BaseConfig` 类中：
| 参数名 | 默认值 | 描述 |
|--------|--------|------|
| retrieval_top_k | 200 | 每步检索的文档数量 |
| linking_top_k | 5 | 每个检索步骤的链接节点数 |
| max_qa_steps | 3 | 问答最大迭代步数 |
| qa_top_k | 5 | 输入 QA 模型的顶部文档数 |
| damping | 0.5 | PPR 算法的阻尼因子 |
| graph_type | facts_and_sim_passage_node_unidirectional | 图结构类型 |
资料来源：[src/hipporag/utils/config_utils.py:配置参数]()
---
## 最佳实践
### 测试建议
1. **环境验证**：首次使用前，使用 `sample` 数据集进行环境验证
2. **成本控制**：开发测试优先使用 OpenAI 测试，成本最低
3. **模型选择**：本地测试推荐使用较小的 8B 模型（如 Llama-3.1-8B-Instruct）以节省 GPU 内存
4. **资源调优**：如遇 GPU 内存溢出，可调整 `gpu-memory-utilization` 或 `max_model_len` 参数
### 调试建议
测试失败时，按以下顺序排查：
1. 确认 API 密钥或本地服务是否正常
2. 检查数据集格式是否符合规范（JSON 结构）
3. 验证环境变量配置是否正确
4. 检查 GPU 内存是否充足
---
---
## Doramagic 踩坑日志
项目：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