GraphRAG: установка и настройка Knowledge Graph RAG от Microsoft — полное руководство 2026

Что такое GraphRAG

GraphRAG — это система retrieval-augmented generation, построенная на knowledge graph вместо плоского векторного поиска.

Обычный RAG (Naive RAG) работает просто: разбить документы на куски по 512 токенов, превратить каждый в вектор, найти K ближайших по косинусной близости к запросу, скормить LLM. Этого хватает, когда вопрос звучит как «Что написано в договоре про форс-мажор?». Но если спросить «Какие общие темы прослеживаются в годовых отчётах всех трёх дивизионов за последние два года?» — Naive RAG провалится: ни один чанк не содержит целостного ответа.

Бенчмарки 2025–2026 показывают: GraphRAG даёт +30–70% точности на задачах multi-source synthesis — там, где ответ надо собрать из нескольких разрозненных документов. Исследование Microsoft (июль 2024) на наборе из 1M текстов показало, что GraphRAG нашёл на 42% больше правильных ответов в тесте MultiHopQA, чем стандартный RAG с тем же LLM.

Как это работает

GraphRAG состоит из двух больших фаз, и понимать обе важно, потому что основная сложность — в первой.

Фаза индексации — самая затратная часть. GraphRAG берёт каждый документ, разбивает на блоки (по умолчанию 300 токенов) и для каждого блока выполняет LLM-запрос с примерно таким промптом: «Извлеки все сущности (люди, организации, локации, даты, события) и связи между ними из этого текста». LLM возвращает структурированные триплеты: (Entity-A, relation, Entity-B).

Из этих триплетов строится взвешенный граф. Дальше — самое интересное: алгоритм community detection (Leiden clustering) разбивает граф на сообщества — группы тесно связанных сущностей. Для каждого сообщества LLM пишет текстовую сводку. Эти сводки — ключ к быстрым ответам. Когда приходит глобальный вопрос («о чём вообще эти документы?»), GraphRAG не перебирает миллион ребер — он пробегается по сводкам сообществ.

На этапе запроса GraphRAG поддерживает два режима. Local search — обычный RAG-поход: ищет ближайшие к запросу сущности, их соседей, присоединяет исходные чанки документов, коктейль скормить LLM. Global search — проходит по сводкам сообществ, собирает из них ответ на обобщающий запрос. Начиная с версии 1.3 появился DRIFT search (Dynamic Retrieval of Information via Focused Traversal) — итеративный обход графа, который стартует с одной сущности и расширяется по мере запросов к LLM. DRIFT отлично справляется с вопросами, где ответ «спрятан» на глубине двух-трёх шагов от исходной точки.

На практике: local search — для вопросов по конкретному документу («Какой бюджет заложен на IT в 2026 году?»), global search — для междокументных («Где в этих отчётах упоминается риск-менеджмент и какие меры предлагаются?»), DRIFT — для исследовательских сценариев («Расскажи про цепочку поставок между Азией и Европой на основе этих данных»).

Установка GraphRAG

GraphRAG ставится как Python-пакет. Минимальные требования: Python 3.10–3.12, 4 CPU, 8 GB RAM для небольших наборов (до 100 документов). Для тысяч документов понадобится 16+ GB и GPU для эмбеддингов.

# 1. Создать окружение
python3 -m venv graphrag-env
source graphrag-env/bin/activate

# 2. Установить graphrag
pip install graphrag

# 3. Инициализировать проект
graphrag init --root ./myproject

# 4. Настроить .env
#    GRAPHRAG_API_KEY=*** ключ OpenAI или Azure>
#    GRAPHRAG_API_BASE=https://api.openai.com/v1

# 5. Поместить документы (txt, pdf, csv) в ./myproject/input/
cp ~/documents/*.txt ./myproject/input/

Параметр --root создаёт структуру директорий: input/ (исходные документы), output/ (индекс), settings.yaml и .env. По умолчанию GraphRAG использует OpenAI GPT-4o-mini для извлечения сущностей и text-embedding-3-small для эмбеддингов.

Настройка под локальные модели

GraphRAG можно переключить на любую OpenAI-совместимую API, включая локальные запуски Ollama или vLLM. В settings.yaml:

llm:
  model: qwen2.5:32b
  api_base: http://localhost:11434/v1
  api_key: ollama
  max_tokens: 4000

embeddings:
  model: nomic-embed-text-v1.5
  api_base: http://localhost:11434/v1
  api_key: ollama

В документации Microsoft описаны все поддерживаемые провайдеры: Azure OpenAI, OpenAI, Ollama, Azure ML, LlamaCPP и кастомные эндпоинты.

Индексация данных

После настройки запуск индексации — одна команда:

graphrag index --root ./myproject

На 50 документов по 2–3 KB каждый процесс занимает примерно 10–20 минут в зависимости от модели. Что происходит под капотом:

Сначала чанкинг — документы режутся на блоки по CHUNK_SIZE токенов. Затем Entity Extraction: LLM-запрос к каждому блоку на извлечение сущностей и связей. Потом Summarization: LLM генерирует краткие описания каждой сущности. После этого Graph Construction: построение взвешенного графа (NetworkX), вычисление centrality. Затем Community Detection: Leiden clustering — сообщества разных уровней. Финальный этап — Community Summaries: LLM пишет сводку для каждого найденного сообщества. Результаты сохраняются в паракеты в output/.

Каждый этап можно перезапустить отдельно, если упал на середине — индексатор идемпотентен. При повторном запуске он пропускает уже обработанные документы. Это удобно, когда вы добавили 5 новых файлов в коллекцию из 200 — GraphRAG обработает только новые.

Визуализация графа

После индексации в output/artifacts/ лежат паркеты со списком сущностей, связей и сообществ. Их можно загрузить в Neo4j или NetworkX для визуализации:

import pandas as pd
import networkx as nx

entities = pd.read_parquet(
    "output/artifacts/create_final_nodes.parquet"
)
G = nx.Graph()
for _, row in entities.iterrows():
    G.add_node(row["title"],
               type=row.get("type"),
               description=row.get("description"))
print(f"Граф: {G.number_of_nodes()} узлов")

Типы запросов: Local, Global, DRIFT

У GraphRAG три режима запросов. Разница не в API, а в том, какие данные идут в контекст LLM.

Local search — режим по умолчанию. Берёт сущности, ближайшие к запросу по косинусной близости эмбеддингов, их соседей по графу (1–2 шага), когерентные чанки исходных документов и сводки сообществ, в которые входят эти сущности. Итоговый контекст — смесь «сырых» данных из документов и уже обобщённых сводок. python -m graphrag query --root ./myproject --method local "Какой бюджет заложен на R&D в 2026?"

Global search — строится не на сущностях, а на сводках сообществ верхнего уровня. Берёт все сводки, сортирует по релевантности, составляет из них карту ответа, на которой LLM пишет финальный ответ. python -m graphrag query --root ./myproject --method global "Какие стратегические инициативы упоминаются в документах?"

DRIFT search — гибридный итеративный режим. Сначала ищет одну сущность по эмбеддингам, затем «распутывает» окрестности: оценивает, какие соседние сущности релевантны, расширяет контекст, задаёт follow-up вопросы LLM для поиска следующей порции данных. python -m graphrag query --root ./myproject --method drift "Проследи цепочку принятия решений в этом наборе контрактов"

На практике: local — 98% задач, global — аналитические обзоры и executive summaries, DRIFT — исследовательские и аудиторские сценарии. В официальном репозитории есть примеры для каждого режима.

LightRAG vs GraphRAG: что выбрать

LightRAG (37.4K звезд на GitHub, EMNLP 2025) от HKU — прямой конкурент GraphRAG. Обе системы строят граф из текста, но с разной философией.

LightRAG легче: ставится одной строкой pip install lightrag-hku, индексация на 50 документов занимает 2–3 минуты против 10–20 у GraphRAG. Вместо community detection и четырёхуровневого summarization LightRAG строит плоский граф и использует гибридный поиск (entity-level + chunk-level + graph traversal).

GraphRAG мощнее на глобальных аналитических запросах: его community summaries дают +30–70% точности на multi-source synthesis. LightRAG выигрывает на фактологических вопросах к конкретным документам и на операционной скорости.

Продакшен-развёртывание

GraphRAG можно развернуть через REST API. Встроенного сервера нет, но community собрала несколько обёрток.

GraphRAG-Server (community, ~1K звезд) — FastAPI-приложение с эндпоинтами /query/local, /query/global, /query/drift. Запускается через docker compose up, монтирует директорию с индексом.

Nano-GraphRAG (3.9K звезд, gusye1234/nano-graphrag) — минимальная реализация GraphRAG в 500 строках кода. Без паркетов, без сложного пайплайна, без Azure-зависимостей. Идеально, если надо понять, как работает графовый RAG, или встроить его в существующий Python-проект без установки гигантского фреймворка.

Для большого объёма данных — Microsoft рекомендует Apache Spark для распределённой индексации и параллельной обработки. Конфиг settings.yaml поддерживает encoding_model: claude-3-haiku, gpt-4o-mini или любую другую модель через OpenAI API.

# Развёртывание через Docker
git clone https://github.com/Azure-Samples/graphrag-accelerator
cd graphrag-accelerator
docker compose up -d

# API будет доступен на порту 8080
curl -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Какие риски упоминаются в контрактах?",
       "mode": "global"}'

Azure AI Foundry включает GraphRAG как managed service — предварительно просмотренные шаблоны, обновление знаний по расписанию, мониторинг через Azure Monitor. Для продакшна на Azure это самый простой путь.

Коротко

GraphRAG — это не очередная библиотека для RAG. Это другой подход к извлечению знаний: не «похожий текст», а «связанные сущности». На сложных аналитических запросах он даёт +30–70% к точности, но платить за это приходится временем и LLM-токенами на индексацию.

Главное, что надо запомнить: GraphRAG не заменяет классический RAG — он расширяет его. Для фактологических вопросов из одного документа достаточно обычного векторного поиска. Для вопросов, ответ на которые размазан по сотне документов и требует синтеза, — нужен граф.

Nano-GraphRAG (3.9K звезд) — лучшая точка входа, если вы хотите попробовать подход за вечер. Полный Microsoft GraphRAG — если вам нужен production-grade пайплайн на тысячах документов.

Что ещё важно знать