Как интегрировать GraphRAG для поиска по документам

После выполнения этой инструкции у вас будет рабочий каркас интеграции GraphRAG для поиска по документам: установлен пакет, инициализирован проект, настроены .env и settings.yaml, подготовлен корпус, построен индекс и выбран режим поиска по completed index.

Практический вердикт: официальный путь у GraphRAG простой по последовательности, но не дешёвый по вычислениям: python -m pip install graphrag → graphrag init → настройка провайдера модели → загрузка документов → graphrag index → поиск через Query Engine в режимах local, global, drift или basic.

• Время: зависит от объёма корпуса, выбранных моделей и провайдера; точное время в источниках не фиксируется.
• Сложность: средний.
• Стоимость: фиксированной цены у GraphRAG нет; расход зависит от OpenAI или Azure OpenAI, а также от настроенного storage/vector store.
• Что потребуется: Python 3.10–3.12, доступ к OpenAI или Azure OpenAI, корпус документов в поддерживаемом формате, возможность сохранить выходные артефакты индексации.
• Актуальная версия: GraphRAG 3.1.1 по changelog и истории коммитов, проверка по состоянию на 2026-08-15.

Редакционное ограничение: в этом наборе источников есть подтверждение последовательности установки, индексации и режимов Query Engine, но нет готового канонического примера команды graphrag query с флагами для вашей конкретной конфигурации. Поэтому ниже дан воспроизводимый путь до готового индекса и критерии выбора режима поиска; точный вызов Query CLI сверяйте со страницей CLI для вашей версии.

Что именно интегрирует GraphRAG

GraphRAG (графовый RAG) — это не просто векторный поиск. По официальному описанию, система строит knowledge graph из исходного корпуса, формирует иерархию сообществ и сводки, а затем использует их для retrieval-based ответов. На практике это означает, что вы интегрируете не только слой embeddings, но и графовые сущности, связи, community detection и summaries.

Это важно для выбора режима поиска. Если вам нужен ответ по конкретным сущностям и фрагментам, чаще подходит local. Если нужен обзор по всему корпусу, полезнее global. Если вы хотите baseline без графовых преимуществ, есть basic. Режим drift поддерживается Query Engine, но его внутренняя механика в данном source pack подробно не раскрыта.

Пошаговая интеграция GraphRAG

1. Подготовьте среду с Python 3.10–3.12.

   Официальный quickstart указывает именно этот диапазон версий Python. Если ваша целевая среда отличается, не начинайте прод-внедрение без дополнительной проверки: в supplied sources отдельно отмечено, что пакетная metadata в экосистеме может отличаться по минимальной версии Python.

   Ожидаемый результат: у вас есть рабочая локальная среда, в которой можно устанавливать пакет GraphRAG.

2. Установите пакет GraphRAG.

   python -m pip install graphrag

   Это официальный способ установки из quickstart. На этом шаге вы не настраиваете модели и не подключаете документы — только ставите CLI и библиотеку.

   Ожидаемый результат: команда установки завершается без ошибки, а пакет GraphRAG доступен в вашей среде Python.

3. Инициализируйте проект GraphRAG.

   graphrag init

   Официальная команда инициализации создаёт .env, settings.yaml и папку prompts/. Если вы повторно запускаете инициализацию на существующем проекте и хотите перезаписать конфигурацию, документация указывает опцию --force.

   Ожидаемый результат: в каталоге проекта появились .env, settings.yaml и prompts/.

4. Настройте провайдера модели в .env и settings.yaml.

   Quickstart прямо говорит, что после graphrag init нужно настроить .env и settings.yaml для OpenAI или Azure OpenAI. GraphRAG использует LiteLLM; OpenAI поддерживается по умолчанию, а Azure OpenAI и managed identity auth документированы в официальных настройках моделей. В settings.yaml вы редактируете параметры моделей и связанные настройки проекта.

   Не копируйте старый YAML из прошлых версий без проверки. Для minor-обновлений GraphRAG рекомендует заново запускать graphrag init, потому что схема конфигурации и модель данных могут меняться.

   Ожидаемый результат: проект знает, к какому LLM-провайдеру обращаться и какие параметры использовать при индексации.

5. Подготовьте корпус документов в поддерживаемом формате.

   GraphRAG официально поддерживает plain text, CSV, JSON, JSON Lines, Parquet и MarkItDown. Все эти форматы загружаются во внутренний documents DataFrame. Если вы интегрируете GraphRAG впервые, документация советует начинать с tutorial dataset и более дешёвых или быстрых моделей, а не с большого прод-корпуса.

   Практический совет: сначала прогоните небольшой набор документов в одном формате, чтобы проверить весь конвейер индексации, а уже потом подключайте реальный архив.

   Ожидаемый результат: ваш корпус приведён к одному из официально поддерживаемых форматов и готов к индексации.

6. Постройте индекс.

   graphrag index

   Во время индексации GraphRAG извлекает сущности, связи и claims, выполняет community detection, генерирует community summaries и reports, а затем по умолчанию сохраняет результат как Parquet-таблицы. Embeddings записываются в настроенный vector store.

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

   Ожидаемый результат: у вас появляется completed index, пригодный для Query Engine.

7. Выберите режим поиска поверх completed index.

   Query Engine работает только по completed indexes и поддерживает local, global, drift и basic. Для поиска по конкретным сущностям и фрагментам берите local. Для вопросов вида «что в целом происходит в корпусе» — global. Если нужен минимальный baseline для сравнения с обычным векторным поиском — basic. Режим drift тоже доступен, но в этом source pack нет детального разбора его механики.

   Ожидаемый результат: вы понимаете, какой режим нужен вашему сценарию и запускаете поиск только после успешной индексации.

Как проверить, что всё работает

1. Проверьте, что после graphrag index создана папка output с Parquet-файлами. Это базовый признак того, что индексация завершилась и артефакты записаны.

2. Если вы включили параметр snapshots.graphml: true, убедитесь, что появился файл graph.graphml. Его можно импортировать в Gephi для визуальной проверки графа.

3. Убедитесь, что вы не пытаетесь искать по незавершённому индексу. По официальной документации Query Engine работает только с completed index.

4. Сопоставьте режим поиска с задачей. Если вопрос локальный, но вы идёте через global, или наоборот, качество ответа может выглядеть как «ошибка интеграции», хотя проблема в выборе режима.

Минимальный критерий успеха для этой инструкции такой: пакет установлен, проект инициализирован, конфигурация задана, индекс построен, в output есть Parquet-артефакты, а ваш дальнейший поиск запускается только по completed index.

Частые ошибки и исправления

• ❌ Ошибка: вы ставите GraphRAG в среду вне диапазона Python 3.10–3.12.

  ✅ Решение: используйте версию Python, указанную в official quickstart. Если ваша организация стандартизировала другую версию, сначала проверьте совместимость в целевой среде, потому что в источниках есть отдельное замечание о возможном расхождении с ecosystem metadata.

• ❌ Ошибка: после graphrag init вы не заполнили .env и не отредактировали settings.yaml.

  ✅ Решение: настройте OpenAI или Azure OpenAI до индексации. Без корректного провайдера моделей GraphRAG не сможет выполнить LLM-этапы конвейера.

• ❌ Ошибка: вы пытаетесь выполнять поиск до завершения индексации.

  ✅ Решение: сначала завершите graphrag index и проверьте output-артефакты. Query Engine официально работает только поверх completed indexes.

• ❌ Ошибка: первая индексация большого корпуса неожиданно расходует много токенов и времени.

  ✅ Решение: начните с tutorial dataset или небольшого фрагмента корпуса и используйте более дешёвые/быстрые модели, как рекомендует документация.

• ❌ Ошибка: после обновления 3.x старая конфигурация перестаёт вести себя предсказуемо.

  ✅ Решение: перед апгрейдом сверяйте changelog и breaking changes. Для minor-обновлений GraphRAG рекомендует повторно запускать graphrag init, чтобы получить совместимую конфигурацию.

Безопасность и ограничения

• GraphRAG сам по себе не задаёт фиксированную цену и не гарантирует региональную доступность. И стоимость, и доступность зависят от OpenAI, Azure OpenAI и выбранного storage/vector store.

• Индексация может быть ресурсоёмкой. Это официальное предупреждение quickstart, поэтому бюджет на LLM-вызовы нужно планировать заранее.

• Если вы отправляете документы во внешний LLM-провайдер, оцените требования к приватности и хранению данных до запуска индексации на чувствительном корпусе.

• При переходе между 3.x-релизами конфигурация, модель данных и настройки storage могут меняться. Для прод-обновлений всегда сверяйте changelog и breaking changes.

• По этому source pack нельзя надёжно зафиксировать один универсальный пример graphrag query для всех конфигураций. Это практическое ограничение инструкции, а не недостаток самого инструмента.

Что делать дальше

• Если вам нужен теоретический контекст перед тюнингом, откройте GraphRAG (графовый RAG).

• Если следующий шаг — пользовательский интерфейс поверх собственного индекса, посмотрите инструкцию Как сделать чат-бота по своим документам.

• Если вы хотите сравнить самохостируемый подход с готовыми исследовательскими инструментами, изучите Как использовать NotebookLM для исследований и карточку AskYourPDF — AI-инструмент для вопросов по PDF и документам.

Источники

• Local Search – GraphRAG
• Outputs – GraphRAG
• Detailed Configuration – GraphRAG

• Welcome – GraphRAG
• Getting Started – GraphRAG
• Init Command – GraphRAG
• CLI – GraphRAG
• Overview – GraphRAG
• Overview – GraphRAG
• Inputs – GraphRAG
• Language Model Selection – GraphRAG
• Visualization Guide – GraphRAG
• GraphRAG Data Model and Config Breaking Changes
• graphrag/CHANGELOG.md at main · microsoft/graphrag · GitHub
• Commits · microsoft/graphrag · GitHub
• Retrieval-Augmented Generation with Graphs (GraphRAG)

Вопросы и ответы

Можно ли использовать GraphRAG без completed index?

Нет. По официальной документации Query Engine работает только поверх completed indexes. Сначала завершите graphrag index и проверьте output-артефакты.

Какие форматы документов поддерживаются?

Официально поддерживаются plain text, CSV, JSON, JSON Lines, Parquet и MarkItDown. Все они загружаются в documents DataFrame.

Какой режим поиска выбрать для вопросов по конкретному документу?

Начните с local, потому что этот режим объединяет structured graph data с raw document chunks. Для обзорных вопросов по всему корпусу чаще полезнее global.

Сколько стоит внедрение GraphRAG?

У самого GraphRAG нет фиксированной цены в supplied sources. Стоимость определяется выбранным LLM-провайдером, моделями и storage, а также объёмом индексации.

Нужно ли что-то делать при обновлении 3.x?

Да. В официальных breaking changes указано, что между версиями могут меняться config и data model. Для minor-обновлений GraphRAG рекомендует повторно запускать graphrag init для совместимой конфигурации.