Привет, Хабр!

Базовые RAG-системы уже научились неплохо справляться с прямыми вопросами по тексту. Но только если ответ лежит в одном конкретном абзаце, а вопрос сформулирован почти так же, как сам исходный документ. Попробуйте заставить систему связать факты из трёх разных источников или сделать банальный логический вывод. В большинстве случаев результат будет неутешительным. А уж про поиск скрытых связей я даже спрашивать боюсь.

Сегодня рассмотрим open-source RAG-фреймворк HippoRAG 2. В сфере RAG главным преимуществом данного фреймворка является качество ответов, потому что принципы его работы основаны на реальном человеческом мозге. Давайте разберёмся, откуда он взялся, как устроен изнутри и как его запустить.

Принципы работы

Префикс «Hippo» в названии — это отсылка к гиппокампу, структуре мозга, которая отвечает за формирование и извлечение долговременных воспоминаний. 

Разработчики из Ohio State University взяли за основу теорию гиппокампального индексирования Тейлера и Дисченна. Согласно ей, мозг хранит не сами воспоминания целиком, а лишь некоторые связи между ними, и при запросе восстанавливает полную картину через цепочку ассоциаций. 

В архитектуре HippoRAG каждый компонент соответствует своему нейробиологическому аналогу:

• LLM играет роль неокортекса. Отвечает за извлечение структурированных представлений из текста. 

• Retrieval-энкодер берёт на себя функцию парагиппокампальных областей мозга, обнаруживая семантические связи. 

• Knowledge граф вместе с алгоритмом PPR (Personalized PageRank) имитирует сам гиппокамп. Он хранит сеть знаний и фактов и умеет строить в ней ассоциативные цепочки при поиске.

В HippoRAG подобный механизм долговременной памяти позволяет выявить скрытые связи между фактами. Речь идёт о многошаговом рассуждении (multi-hop reasoning). Это процесс, при котором система последовательно сопоставляет факты из разных источников по контексту и выстраивает цепочку связей, чтобы ответить на абстрактный вопрос.

Факты внутри системы называются триплетами. Это структурированное представление знаний в виде «субъект — отношение — объект». 

К примеру:

• (Оливер Бэдмен, является, политик).

  Или:

•  (Монтебелло, часть округа, Рокленд Каунти).

За извлечение триплетов отвечает OpenIE (Open Information Extraction) с помощью LLM. При индексации фреймворк отправляет каждый чанк документа в языковую модель с инструкцией извлечь все структурированные утверждения в виде троек. Результаты кэшируются в openie_cache/, чтобы при повторном запуске не тратить токены снова.

Зачем это нужно? Потому что для многошагового вопроса вроде: «В каком округе родился политик, который…» — обычный RAG просто найдёт документ про политика и отдельно про округ, а связь не уловит. А HippoRAG 2 склеивает два триплета через общую сущность (политик → место рождения → округ). Это и есть так называемая «скрытая связь».

Из всех извлечённых триплетов строится knowledge граф. Не такой огромный, как в GraphRAG, а более компактный(HippoRAG на датасете MuSiQue использует около 9 млн токенов — против 115 млн у GraphRAG).

При загрузке документов помимо создания эмбеддингов для чанков проводится извлечение упомянутых триплетов. Из извлечённых фактов строится knowledge-граф. Соответственно, при ответе на вопрос используется как стандартный проход по эмбеддированным документам с косинусным подобием, так и ранжирование фактов по графу. В этот момент задействуется PPR алгоритм. PPR — это вариация PageRank, где вместо случайного блуждания по всему графу, релевантность узлов измеряется относительно конкретного набора начальных (seed) узлов.

Установка и первый запуск

Установить фреймворк можно через pip или клонировав репозиторий.

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

Далее — пара экспортов (API-ключи и пути к кэшу) из env:

export OPENAI_API_KEY="sk-..."
export HF_HOME="/путь/к/кэшу"

Допустим, у нас есть три документа:

from hipporag import HippoRAG

docs = [
    "Oliver Badman is a politician.",
    "Montebello is a part of Rockland County.",
    "Erik Hort's birthplace is Montebello."
]

hipporag = HippoRAG(
    save_dir="my_rag_memory",    # сюда упадёт всё: эмбеддинги, граф, кэш
    llm_model_name="gpt-4o-mini",    
    llm_api_key = OPENAI_API_KEY,
    llm_base_url = OPENAI_BASE_URL,
    embedding_model_name="nvidia/NV-Embed-v2",
    embedding_api_key = EMBEDDING_API_KEY,
    embedding_base_url = EMBEDDING_BASE_URL     
)

Кстати говоря, фреймворк позволяет переопределять base_url для работы с локальными серверами. То есть ничто не мешает поднять собственные FastAPI-серверы с локальными LLM и моделями эмбеддингов или в Google Colab, используя библиотеку transformers, и затем просто указать эндпоинты с их выводом в openai-совместимом формате.

Пример эмбеддинг-модели

Ниже — самописный FastAPI-сервер для эмбеддингов.

import torch
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from transformers import AutoTokenizer, AutoModel
from typing import List
import uvicorn

class EmbeddingRequest(BaseModel):
    input: List[str] | str          
    model: str                     
    encoding_format: str = "float"  

class EmbeddingResponse(BaseModel):
    object: str = "list"
    data: List[dict]
    model: str
    usage: dict

MODEL_NAME = "название вашей модели"  
device = "cuda" if torch.cuda.is_available() else "cpu"

tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME)
model = AutoModel.from_pretrained(MODEL_NAME).to(device)
model.eval()

def embed_texts(texts: List[str]) -> List[List[float]]:
    inputs = tokenizer(
        texts,
        padding=True,
        truncation=True,
        return_tensors="pt",
        max_length=512
    ).to(device)

    with torch.no_grad():
        outputs = model(**inputs)
        embeddings = outputs.last_hidden_state.mean(dim=1) 
    return embeddings.cpu().numpy().tolist()

app = FastAPI(title="Local Embedding Server (OpenAI-compatible)")

@app.get("/v1/models")
async def list_models():
    return {
        "object": "list",
        "data": [
            {
                "id": MODEL_NAME,
                "object": "model",
                "owned_by": "local",
                "permission": []
            }
        ]
    }

@app.post("/v1/embeddings")
async def create_embedding(request: EmbeddingRequest):
    texts = [request.input] if isinstance(request.input, str) else request.input

    if not texts:
        raise HTTPException(status_code=400, detail="Input text list is empty")

    try:
        embeddings = embed_texts(texts)
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Embedding failed: {str(e)}")

    response_data = []
    for idx, emb in enumerate(embeddings):
        response_data.append({
            "object": "embedding",
            "index": idx,
            "embedding": emb
        })

    return EmbeddingResponse(
        data=response_data,
        model=MODEL_NAME,
        usage={
            "prompt_tokens": sum(len(t) for t in texts),
            "total_tokens": sum(len(t) for t in texts)
        }
    )

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8001)

Теперь этот сервер можно передать в embedding_base_url="http://localhost:8001/v1".

Более простой и производительный вариант — использовать SentenceTransformer. Сервер остаётся полностью совместимым с OpenAI API.

import asyncio
from contextlib import asynccontextmanager
from typing import List, Union

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from sentence_transformers import SentenceTransformer
import uvicorn

class EmbeddingRequest(BaseModel):
    input: Union[str, List[str]]  
    model: str  
    encoding_format: str = "float"

class EmbeddingResponse(BaseModel):
    object: str = "list"
    data: List[dict]
    model: str
    usage: dict

@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.model = SentenceTransformer("intfloat/e5-large-v2", device="cuda")
    yield
    app.state.model = None

app = FastAPI(title="Local Embedding Server (OpenAI-compatible)", lifespan=lifespan)

@app.get("/v1/models")
async def list_models():
    return {
        "object": "list",
        "data": [
            {
                "id": "local-embedding-model",
                "object": "model",
                "owned_by": "local",
                "permission": []
            }
        ]
    }

@app.post("/v1/embeddings")
async def create_embedding(request: EmbeddingRequest):
    texts = [request.input] if isinstance(request.input, str) else request.input

    if not texts:
        raise HTTPException(status_code=400, detail="Input text list is empty")

    model: SentenceTransformer = app.state.model
    try:
        embeddings = model.encode(texts, normalize_embeddings=True)
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Embedding failed: {str(e)}")

    response_data = [
        {
            "object": "embedding",
            "index": idx,
            "embedding": emb.tolist()
        }
        for idx, emb in enumerate(embeddings)
    ]

    return EmbeddingResponse(
        data=response_data,
        model=request.model,
        usage={
            "prompt_tokens": sum(len(text.split()) for text in texts),
            "total_tokens": sum(len(text.split()) for text in texts)
        }
    )

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8001)

Индексация документов

Индексация запускается одной командой:

hipporag.index(docs=docs)

Что происходит внутри? 

• Документы режутся на чанки (стандартно — по предложениям).

• Каждый чанк эмбеддится.

• Одновременно LLM обрабатывает каждый чанк через OpenIE и извлекает из него все смысловые триплеты.

• Триплеты превращаются в узлы и рёбра knowledge-графа.

• Эмбеддинги узлов графа тоже вычисляются (чтобы потом искать похожие факты). 

Где хранится?

В папке my_rag_memory (которую мы передали в save_dir) создаётся структура: 

• embeddings/ — плоские файлы с эмбеддингами чанков и узлов графа (обычно .npy или через faiss индекс). 

• graph/ — сериализованный граф (узлы, рёбра, веса). 

• openie_cache/ — результаты извлечения триплетов, чтобы при повторном запуске не жечь токены заново.

На данном этапе фреймворк хранит эмбеддинги в формате .parquet. Но ничего не мешает дописать совместимость с векторными БД, особенно в наше время.

Важный нюанс: если вы перезапускаете индекс с теми же документами, HippoRAG 2 не будет заново дёргать OpenIE и LLM, а проверит кэш по хешу текста. Так что за токены, хотя бы тут, можете не переживать.

Что возвращает каждая функция?

retrieve — поиск без генерации ответа:

results = hipporag.retrieve(
    queries=["What county is Erik Hort's birthplace a part of?"],
    num_to_retrieve=2
)
print(results)

На выходе — список списков. Для каждого запроса: 

[
    [ 
        {"text": "Montebello is a part of Rockland County.", "score": 0.92, "type": "chunk"},
        {"text": "Erik Hort's birthplace is Montebello.", "score": 0.87, "type": "chunk"}
    ]
]

Важный момент: type может быть "chunk" (найденный чанк) или "fact" (найденный триплет из графа) — зависит от того, что победило в ранжировании.

rag_qa — выполняет полный цикл: поиск → передача найденного контекста в LLM → генерация ответа

answers = hipporag.rag_qa(
    queries=["What county is Erik Hort's birthplace a part of?"]
)
print(answers)

Вернёт список строк с ответами, например: ["Rockland County"]. В ответе также возвращается список использованных чанков.

Оценка с gold-данными

Один из самых приятных моментов, это когда у вас есть золотые ответы и поддерживающие документы для оценки:

gold_answers = [["Rockland County"]]
gold_docs = [
    ["Montebello is a part of Rockland County.",
     "Erik Hort's birthplace is Montebello."]
]

eval_results = hipporag.rag_qa(
    queries=queries,
    gold_docs=gold_docs,
    gold_answers=gold_answers
)

Тогда в eval_results упадёт словарь с метриками: 

• "retrieval_hit_rate" (попали ли нужные чанки в топ-N), 

• "answer_accuracy" (точность ответа, часто через F1 или EM), 

• "latency_seconds" — чтобы потом бенчмаркать.

Удаление и добавление документов

Если понадобится удалить документ, есть hipporag.delete_docs(doc_indices=[0,2]).

Граф перестраивается инкрементально, не с нуля. Для добавления новых данных вызывается hipporag.index(docs=new_docs). Система сама определит, что уже проиндексировано, а что нет.

Заключение

Признаюсь, я обожаю HippoRAG 2. Для меня это максимально удобный инструмент, который ещё и справляется лучше своих аналогов. Естественно, он не универсальная затычка для любой проблемы, но в задачах контекста, рассыпанного по множеству документов, ему нет равных.

Я советую обратить внимание на фреймворк уже за то, что авторам удалось решить задачу ассоциативного рассуждения без многократного роста стоимости запросов. Это ли не чудо?

© 2026 ООО «МТ ФИНАНС»