HippoRAG 2는 새로운 지식에서의 연결성을 인식하고 활용하는 능력을 향상시키는 LLM을 위한 강력한 메모리 프레임워크로, 인간의 장기 기억 (Long-term memory)의 핵심 기능을 모방합니다.

우리의 실험에 따르면, HippoRAG 2는 더 단순한 작업에서의 성능을 희생하지 않으면서도, 가장 진보된 RAG 시스템에서 연상성 (Associativity, 멀티홉 검색) 및 의미 파악 (Sense-making, 크고 복잡한 문맥을 통합하는 과정) 능력을 향상시킵니다.

이전 모델과 마찬가지로, HippoRAG 2는 온라인 프로세스에서 비용과 지연 시간 (Latency) 효율성을 유지하는 동시에, GraphRAG, RAPTOR, LightRAG와 같은 다른 그래프 기반 솔루션에 비해 오프라인 인덱싱 (Offline indexing)에 훨씬 적은 리소스를 사용합니다.

Figure 1: 세 가지 핵심 차원에서의 지속적 학습 (Continual learning) 능력 평가: 사실적 기억 (Factual memory; NaturalQuestions, PopQA), 의미 파악 (Sense-making; NarrativeQA), 그리고 연상성 (Associativity; MuSiQue, 2Wiki, HotpotQA, 그리고 LV-Eval). HippoRAG 2는 모든 카테고리에서 다른 방법들을 능가하며, 진정한 장기 기억에 한 걸음 더 다가갔습니다.

Figure 2: HippoRAG 2 방법론.

HippoRAG: Neurobiologically Inspired Long-Term Memory for Large Language Models[NeurIPS '24]. From RAG to Memory: Non-Parametric Continual Learning for Large Language Models[ICML '25].

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

환경 변수를 초기화하고 환경을 활성화합니다:

export CUDA_VISIBLE_DEVICES=0,1,2,3
export HF_HOME=<Huggingface 홈 디렉토리 경로>
export OPENAI_API_KEY=<사용자의 openai api key> # OpenAI 모델을 사용하려는 경우
...

이 간단한 예제는 모든 OpenAI 모델과 함께 hipporag를 사용하는 방법을 보여줍니다:

from hipporag import HippoRAG
# 데이터셋 및 평가 준비
docs = [
...

OpenAI와 호환되는 LLM 및 임베딩 (Embeddings)을 사용하려면 다음 방법을 사용하십시오.

hipporag = HippoRAG(save_dir=save_dir,
llm_model_name='사용자의 LLM 모델 이름',
llm_base_url='사용자의 LLM 모델 url',
...

이 간단한 예제는 vLLM 호환이 가능한 로컬 배포 LLM에서 hipporag를 사용하는 방법을 설명합니다.

• 지정된 GPU를 사용하여 OpenAI 호환 vLLM 서버를 실행합니다 (임베딩 모델 (embedding model)을 위한 메모리를 충분히 남겨두어야 합니다).

export CUDA_VISIBLE_DEVICES=0,1
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export HF_HOME=<Huggingface 홈 디렉토리 경로>
...

• 이제 위와 매우 유사한 코드를 사용하여 hipporag를 사용할 수 있습니다:

save_dir = 'outputs' # HippoRAG 객체를 위한 저장 디렉토리 정의 (각 LLM/임베딩 모델 조합은 새로운 하위 디렉토리를 생성합니다)
ellm_model_name = # 모든 OpenAI 모델 이름
embedding_model_name = # 임베딩 모델 이름 (현재는 NV-Embed, GritLM 또는 Contriever)
...

HippoRAG에 기여(contribution)할 때는, 귀하의 변경 사항이 핵심 모듈에서 예상치 못한 동작을 유발하지 않도록 아래 스크립트들을 실행해 주세요.

이 스크립트들은 인덱싱 (indexing), 그래프 로딩 (graph loading), 문서 삭제 (document deletion) 및 HippoRAG 객체의 점진적 업데이트 (incremental updates)를 테스트합니다.

OpenAI LLM 및 임베딩 모델로 HippoRAG를 테스트하려면 다음을 실행하기만 하면 됩니다. 이 테스트 비용은 무시할 수 있을 정도로 적습니다.

export OPENAI_API_KEY=<귀하의 openai api key>
conda activate hipporag
python tests_openai.py

로컬에서 테스트하려면 vLLM 인스턴스를 배포해야 합니다. 저희는 더 저렴한 테스트를 위해 더 작은 8B 모델인 Llama-3.1-8B-Instruct를 배포하기로 선택했습니다.

export CUDA_VISIBLE_DEVICES=0
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export HF_HOME=<Huggingface 홈 디렉토리 경로>
...

그 다음, 다음 테스트 스크립트를 실행합니다:

CUDA_VISIBLE=1 python tests_local.py

저희의 코드를 사용하여 실험을 수행하려면 이 저장소(repository)를 클론(clone)하고 main.py 스크립트의 구조를 따를 것을 권장합니다.

저희는 논문에서 여러 샘플링된 데이터셋을 평가했으며, 그중 일부는 이미 이 저장소의 reproduce/dataset 디렉토리에 포함되어 있습니다. 전체 데이터셋 세트를 이용하려면 저희의 HuggingFace 데이터셋을 방문하여 reproduce/dataset 아래에 배치해 주세요.

또한 저희는 outputs/musique 아래에 있는 musique 샘플에 대해 gpt-4o-mini와 Llama-3.3-70B-Instruct 모두에 대한 OpenIE (Open Information Extraction) 결과를 제공합니다.

환경이 제대로 설정되었는지 테스트하려면, 아래에 표시된 것처럼 디버깅을 위해 작은 데이터셋인 reproduce/dataset/sample.json을 사용할 수 있습니다.

환경 변수를 초기화하고 환경을 활성화합니다:

export CUDA_VISIBLE_DEVICES=0,1,2,3
export HF_HOME=<Huggingface 홈 디렉토리 경로>
export OPENAI_API_KEY=<사용자의 openai api key> # OpenAI 모델을 사용하려는 경우
...

dataset=sample # 또는 `reproduce/dataset` 아래의 다른 데이터셋
# OpenAI 모델 실행
python main.py --dataset $dataset --llm_base_url https://api.openai.com/v1 --llm_name gpt-4o-mini --embedding_name nvidia/NV-Embed-v2

• 위와 같이, 지정된 GPU로 로컬 OpenAI 호환 vLLM 서버를 실행합니다.

export CUDA_VISIBLE_DEVICES=0,1
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export HF_HOME=<Huggingface 홈 디렉토리 경로>
...

• 다른 터미널에서 다른 GPU를 사용하여 메인 프로그램을 실행합니다.

export CUDA_VISIBLE_DEVICES=2,3 # vLLM 서버가 실행되는 동안 다른 GPU를 설정
export HF_HOME=<Huggingface 홈 디렉토리 경로>
dataset=sample
...

vLLM은 더 빠른 추론을 위한 오프라인 배치 모드 (offline batch mode)를 제공하며, 이는 vLLM 온라인 서버에 비해 3배 이상 빠른 인덱싱 (indexing) 속도를 가져다줄 수 있습니다.

• 다음 명령어를 사용하여 vLLM 오프라인 배치 모드로 메인 프로그램을 실행합니다.

export CUDA_VISIBLE_DEVICES=0,1,2,3 # 더 빠른 오프라인 인덱싱을 위해 모든 GPU 사용
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export HF_HOME=<Huggingface 홈 디렉토리 경로>
...

• 첫 번째 단계 이후, OpenIE 결과가 파일로 저장됩니다. Run with vLLM (Llama) 메인 섹션에 설명된 대로 vLLM 온라인 서버와 메인 프로그램을 다시 실행하십시오.

/reproduce/dataset/sample.json은 디버깅을 위해 특별히 제작된 작은 데이터셋입니다.

• vLLM 오프라인 모드를 디버깅할 때는 hipporag/llm/vllm_offline.py에서 tensor_parallel_size를 1로 설정하십시오.

. - 특정 실험을 다시 실행하려면 OpenIE 결과 및 지식 그래프 (knowledge graph)를 포함하여 저장된 파일들을 삭제해야 함을 기억하십시오. 예시:

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

평가를 위한 사용자 정의 데이터셋 (custom dataset)을 설정하려면 reproduce/dataset/sample_corpus.json에 표시된 형식과 명명 규칙 (naming convention)을 따르십시오.

(데이터셋 이름 뒤에 _corpus.json이 붙어야 합니다).

사전에 정의된 질문들로 실험을 실행하는 경우, 쿼리 파일 reproduce/dataset/sample.json에 따라 쿼리 코퍼스 (query corpus)를 구성하십시오. 이때 반드시 우리의 명명 규칙을 따라야 합니다.

코퍼스 및 선택 사항인 쿼리 JSON 파일은 다음과 같은 형식을 가져야 합니다:

[
{
"title": "첫 번째 구절 제목",
...

[
{
"id": "sample/question_1.json",
...

데이터를 준비할 때 각 구절 (passage)을 청크 (chunk)로 나누어야 할 수도 있습니다. 구절이 너무 길면 OpenIE 프로세스에 너무 복잡할 수 있기 때문입니다.

📦 .
│-- 📂 src/hipporag
│ ├── 📂 embedding_model # 모든 임베딩 모델 (embedding models)의 구현
...

질문이나 문제가 있습니까? 이슈 (issue)를 등록하거나 Bernal Jiménez Gutiérrez, Yiheng Shu, Yu Su (The Ohio State University)에게 연락하십시오.

이 작업이 유용하다고 생각되시면, 저희의 논문을 인용해 주시기 바랍니다:

@misc{gutiérrez2025ragmemorynonparametriccontinual,
title={From RAG to Memory: Non-Parametric Continual Learning for Large Language Models},
author={Bernal Jiménez Gutiérrez and Yiheng Shu and Weijian Qi and Sizhe Zhou and Yu Su},
...

@inproceedings{gutiérrez2024hipporag,
title={HippoRAG: Neurobiologically Inspired Long-Term Memory for Large Language Models},
author={Bernal Jiménez Gutiérrez and Yiheng Shu and Yu Gu and Michihiro Yasunaga and Yu Su},
...

• 더 많은 임베딩 모델 (embedding models) 지원 추가
• 임베딩 엔드포인트 (embedding endpoints) 지원 추가
• 벡터 데이터베이스 (vector database) 통합 지원 추가

질문이나 제안 사항이 있다면 언제든지 이슈 (issue) 또는 PR을 열어주세요.