GraphRAGをAzureで動かす方法｜graphrag 3.3の設定とAccelerator終了後の選択肢【2026年10月】

AzureでGraphRAGを動かす方法として長く紹介されてきたGraphRAG Acceleratorは、2025年5月27日にアーカイブされました。2026年10月時点で現実的な方法は、Microsoftのgraphragライブラリ（最新は2026年10月8日公開の3.3.0）をAzure OpenAIへつなぐ構成です。ただし、このライブラリもREADMEで「保守モード」と宣言されています。さらに3.0で設定ファイルの形式が変わったため、ネット上の設定例の多くはそのままでは動きません。本記事では、graphrag 3.3.0をコンテナに入れて設定とインデックス処理を実際に走らせた結果をもとに、仕組み・Azure側の選択肢・動く設定・つまずく箇所を順に説明します。

まとめ｜Azure版GraphRAGの採用条件と設定上の制約

• Acceleratorは使わない。2025年5月27日にアーカイブされ、読み取り専用です。いま組むならgraphragライブラリ＋Azure OpenAIを使います。
• 本体は保守モード。3.3.0のREADMEは、新しいPRも新機能も受け付けず、バグ修正と依存更新（CVE対応を含む）だけを続けると明記しています。長く使う基盤として採用する場合は、この前提を判断材料に入れてください。
• 設定はcompletion_modelsとembedding_modelsに書く。2.x形式のmodels:はエラーにならず無視され、インデックス処理の途中で止まります。
• モデルは構造化出力に対応したものを選ぶ。graphrag initの既定はgpt-4.1ですが、Azureではバージョン2025-04-14がDeprecated（2027年4月14日に退役予定）で、過去にデプロイしたことのないサブスクリプションでは新しく使えません。
• 増分更新はファイル名で差分を判定する。同じ名前のまま内容を書き換えた文書は取り込まれず、消した文書も索引に残ります。日本語文書でfastインデックスを使う場合は、抽出器を日本語モデルに切り替える必要があります。

GraphRAGとは｜知識グラフとコミュニティ要約で答えるRAG

GraphRAGは、文書から知識グラフを抽出し、そのグラフを要約した結果を使って回答を組み立てるRAGの手法です。Microsoft Researchが2024年4月24日に論文From Local to Global: A Graph RAG Approach to Query-Focused Summarizationで提案し、2024年7月にOSSとして公開しました。読み方は「グラフラグ」です。「graph RAG」は知識グラフを使うRAG全般を指す総称としても使われますが、本記事で扱うのはMicrosoftの実装microsoft/graphragです。

graphrag 3.3.0の初期設定では、文書を最大1,200トークンのチャンク（重なり100トークン）に分けます。これらの値はchunking設定で変更できます。LLMがチャンクごとにエンティティと関係を抽出し、Leidenアルゴリズムで階層的なコミュニティにまとめます。最後に、コミュニティごとの要約（コミュニティレポート）を先に作っておきます。通常のベクトル検索型RAGは質問に近い断片を数件渡すだけなので、「この文書群の主要な論点は何か」のように全体を横断する質問には答えの材料が足りません。GraphRAGが論文で示した改善は、この全体把握型の質問で出たものです。ベクトル検索そのものの守備範囲はベクトル検索とセマンティック検索の違い：包含関係・仕組み・pgvectorでの実装と使い分けで整理しています。

成果物の実体はparquetファイル（エンティティ・関係・コミュニティ・レポート）とベクトルストアです。グラフデータベースを立てて、質問のたびに経路を探索する仕組みではありません。グラフDBとベクトルDBの役割分担はベクトルデータベースとグラフデータベースの違い｜比較表・ナレッジグラフとの関係・3つのDBで実測【2026年版】で比べています。

Azureで選べる5つの構成｜Accelerator終了後の現状

「AzureでGraphRAG」と言っても、2026年10月時点で中身の異なる構成が5つあります。

GraphRAG Accelerator｜2025年5月27日にアーカイブ

Azure-Samples/graphrag-acceleratorは、graphragをAPIとしてAzureに載せる参考実装でした。AKS・API Management・Azure AI Search・Cosmos DB・Storageをまとめてデプロイする構成です。リポジトリには「This repository was archived by the owner on May 27, 2025. It is now read-only.」と表示され、READMEにも「This repository is no longer maintained.」とあります。2024年に書かれた構築記事には、このAcceleratorを前提に、GPT-4oとtext-embedding-ada-002をデプロイする手順のものが残っています。いまから新しく組む土台にはなりません。

graphragライブラリ｜3.3.0は保守モード

PyPIのgraphragは2026年9月に3.2.0、10月8日に3.3.0が出ています。CHANGELOGに載っている主な機能追加は、SQLiteキャッシュの並行アクセス対応と一括読み取りです。3.2.0には、依存パッケージの更新に加えて、ドキュメントのリンク切れとdocstringの引数不一致の修正も含まれます。対応するPythonは3.11以上3.14未満、ライセンスはMITです。一方、3.3.0のREADMEには「This project is largely in maintenance mode, and won’t be accepting new PRs or implementing new features.」とあります。社内のナレッジ検索に数年使う前提なら、更新が止まっても自分たちで保守できる範囲（CLIとparquetの成果物）に設計をとどめるのが安全です。

PostgreSQL・Microsoft Discovery・Foundry Local｜ライブラリ以外の受け皿

Azure Database for PostgreSQLのリリースノートでは、2024年12月にGraphRAG Solution Acceleratorが公開プレビューとして案内されました。これはgraphragライブラリの置き換えではありません。表に格納した文書をApache AGEのプロパティグラフで関係づけ、pgvectorの類似度とopenCypherで計算したグラフ上のスコアを順位融合する、SQL完結の構成です。Azure上のグラフDBの選び方はAzureのグラフDBはどれを使う？Gremlin・Fabric Graph・Apache AGEとCosmos AI Graphの正体にまとめました。

LazyGraphRAGの技術は、Microsoft Discoveryの知識ベース（Bookshelf）のインデックスとして提供されています。Microsoft ResearchのLazyGraphRAGの発表記事にも、2025年6月6日付の編集注で、Microsoft DiscoveryとAzure Localのサービス（パブリックプレビュー）に統合したと追記されています。Microsoft Learnの比較表（2026年9月16日更新）ではAzure版がGenerally available、ローカルアプリがIn previewです。ただし利用には、Discoveryへのアクセスを許可されたサブスクリプションが要ります。汎用のRAG基盤ではなく研究開発向けのエージェント基盤です。詳細はMicrosoft Discoveryとは｜科学研究を加速するエージェント型AI基盤の仕組みと使い方【GA・2026年版】で扱っています。

オンプレミスの文書を対象にするなら、Azure ArcのAgentic Retrieval in Foundry Localも候補です。Azure Local上のArc対応Kubernetesで動き、切断環境での運用もプレビューで用意されています。Ingestion APIのリファレンスには「LazyGraphRAGの構築に失敗してもジョブをFAILEDにしない」ためのパラメーターexcludeLgrFailureUpdateがあり、文書の取り込み時にLazyGraphRAGが構築されることがわかります。2026年10月時点ではプレビュー提供です。

graphrag 3.3をAzure OpenAIにつなぐ手順

ここからは、graphrag 3.3.0をpython:3.12-slimコンテナに入れ、initの出力と設定の検証結果を確かめた内容です。Azure OpenAIへの実接続はしていません。設定のエラーは--dry-runで、インデックス処理はgraphrag同梱のモックLLMで再現しました。

インストールとinit｜settings.yamlと.envの生成

python -m pip install graphrag==3.3.0
graphrag init --root ./ragtest --model gpt-4.1 --embedding text-embedding-3-large

initはsettings.yaml・.env・prompts/・input/を作ります。--modelと--embeddingを省くと対話で尋ねられ（既定値はgpt-4.1とtext-embedding-3-large）、CIのような非対話の環境ではAborted.で止まるので、2つとも明示してください。生成される.envの中身はGRAPHRAG_API_KEY=<API_KEY>の1行だけです。model_providerはopenaiになっているので、Azure向けには書き換える必要があります。

settings.yamlのAzure OpenAI設定｜completion_modelsとembedding_models

3.xの公式手順Getting Startedに沿うと、Azure OpenAIの設定は次の形になります。modelはモデル名、azure_deployment_nameはAzure側で付けたデプロイ名です。実装を読むと、LiteLLMに渡すモデル指定はazure/<azure_deployment_name>で組み立てられ、デプロイ名を省いたときだけmodelの値が使われます。

completion_models:
  default_completion_model:
    model_provider: azure
    model: gpt-4.1
    azure_deployment_name: chat-gpt41
    api_base: https://<リソース名>.openai.azure.com
    api_version: "2025-04-01-preview"   # 引用符を付ける
    auth_method: api_key
    api_key: ${GRAPHRAG_API_KEY}
    retry:
      type: exponential_backoff

embedding_models:
  default_embedding_model:
    model_provider: azure
    model: text-embedding-3-large
    azure_deployment_name: emb-3-large
    api_base: https://<リソース名>.openai.azure.com
    api_version: "2025-04-01-preview"
    auth_method: api_key
    api_key: ${GRAPHRAG_API_KEY}

api_versionは構造化出力に対応した版を指定します。graphragはコミュニティレポートの生成などで応答形式をresponse_formatで指定しており、Azure OpenAIのドキュメントでは構造化出力に最初に対応したAPI版を2024-08-01-previewとしています。Getting Startedの例に残っている2024-02-15-previewはこれより古いので、そのまま写さないでください。

APIキーを使わずにマネージドIDで認証する場合は、auth_method: azure_managed_identityにしてapi_keyの行を消します。ローカルではaz loginした資格情報が使われ、トークンの取得先はhttps://cognitiveservices.azure.com/.defaultです。キーレス認証の考え方はLangChainとAzure OpenAIの連携手順｜初期化の差分とキーレス認証と共通です。

モデル選定｜gpt-4.1は2027年4月14日に退役予定

Azure OpenAIのモデル退役スケジュール（2026年9月23日更新）では、gpt-4.1（2025-04-14）・gpt-4.1-miniはいずれもDeprecatedで、退役日は2027年4月14日です。埋め込みのtext-embedding-3-largeとtext-embedding-3-smallはGAで、退役日は2028年2月9日です。gpt-4o系も2024-08-06とgpt-4o-mini（2024-07-18）がDeprecated、2024-11-20がLegacyです。チャットモデルは差し替える前提で設計しておき、埋め込みは当面そのまま使えます。

注意したいのは、Deprecatedのモデルを新しく使えるのは既存の顧客だけという点です。モデルのライフサイクルの説明では、Deprecatedの段階で新規の顧客はデプロイを作れず、既存の顧客かどうかは「そのAzureサブスクリプションがそのモデルバージョンを過去にデプロイしたことがあるか」で判定されます。同じテナントでも新しいサブスクリプションには引き継がれません。initの既定どおりgpt-4.1で始めると、新しく用意したサブスクリプションではデプロイの段階で止まります。上の設定例のgpt-4.1は利用資格がある場合の例として読み、無い場合はGAのモデルを選んでmodelとazure_deployment_nameを置き換えてください。

差し替え先を選ぶ条件は2つです。公式のLanguage Model Selectionは、モデルがJSONスキーマに沿った構造化出力を返せることを必須とし、最も検証されているのはgpt-4系（gpt-4o・gpt-4o-mini等）だとしています。推論モデルは2.2.0から対応していますが、同じページで「遅く高価」「プロンプトの書き直しが要る場合がある」と注意しています。ところが、その最も検証されたgpt-4系は、Azureでは前述のとおりDeprecatedかLegacyです。退役スケジュールでGAのまま残っているのはgpt-5以降の系列（例：gpt-5.4-miniは退役予定2027年9月21日）で、これらは推論モデルにあたります。後継を選ぶときは、小さなコーパスで抽出結果と処理時間を比べてから全量に切り替えてください。退役日と移行手順の一覧はAzure OpenAIのモデル廃止予定と対応手順｜引退日一覧・自動アップグレード・移行【2026年10月】にあります。

入力文書の配置とインデックス・クエリの実行

初期化したプロジェクトのragtest/input/に、検索対象のUTF-8テキストファイル（.txt）を配置してください。APIキー認証の場合は、ragtest/.envのGRAPHRAG_API_KEYをAzure OpenAIの実際のキーに置き換えてから、次のコマンドを実行します。

graphrag index --root ./ragtest --dry-run        # 設定の検証と接続テスト
graphrag index --root ./ragtest                  # 既定は --method standard
graphrag query "この文書群の主要な論点は？" --root ./ragtest --method global
graphrag query "A社とB社の関係は？" --root ./ragtest --method local

--dry-runは、設定を読み込んだうえでチャットモデルと埋め込みモデルに1回ずつテスト呼び出しを送ります。デプロイ名やapi_baseの誤りをここで検出できます（実在しないエンドポイントではAzureException APIConnectionError - Connection error.で止まりました）。埋め込みのテストで返ってきたベクトルの次元数がvector_sizeと違う場合は、実際の次元数で上書きされます。質問文は位置引数で渡します。3.3.0のCLIに--queryオプションはありません。

2.x時代の設定例が3.3で動かない7つの症状｜コンテナで実測

3.0で設定のレイアウトが変わったため、ネット上の設定例をそのまま使うと次のどれかに当たります。いずれもgraphrag 3.3.0で再現した結果です。

最も気づきにくいのは1つ目です。models:は未知のキーとして無視され、completion_modelsが空のまま処理が進みます。--dry-runの接続テストも、検証対象のモデルが0件なので素通りします。実際にインデックスを流すと、文書の読み込みとチャンク分割まで終わった後で次のエラーが出ます。

Pipeline error: Model ID default_completion_model not found in completion_models. Please rerun `graphrag init` and set the completion_models configuration.

3.3.0タグのドキュメント（Language Model Selection）にも、複数のモデルを「modelsブロック」に定義するという2.x時代の説明が残っています。これが混乱の原因のひとつです。モデル定義の中の旧キー名も同じように黙って無視されます。deployment_name: chat-gpt41と書いた場合、LiteLLMに渡るモデル指定はazure/gpt-4.1で、デプロイ名が使われません。デプロイ名とモデル名が違う環境では、--dry-runの接続テストで初めて失敗に気づきます。auth_type: azure_managed_identityと書いた場合は認証方式が既定のapi_keyのまま残り、api_key must be set when auth_method=api_key.で止まります。api_versionは、引用符なしの2024-10-21がYAMLの日付型として読まれ、Input should be a valid string [type=string_type, input_value=datetime.date(2024, 10, 21)]になります。2024-02-15-previewのように接尾辞が付く版は文字列として読まれるので、このエラーは出ません。GA版の日付だけの指定で起きるエラーです。

Azureのストレージとベクトルストア設定｜Blob・AI Search・Cosmos DB

入力・出力・キャッシュの置き場所は、input_storage・output_storage・cache.storageごとにfile・blob・cosmosdbから選べます。ベクトルストアはlancedb（既定）・azure_ai_search・cosmosdbの3種類です。Azure Blob Storageはconnection_stringかaccount_urlのどちらか一方を指定します。両方を書くとエラーで、account_urlだけを書いた場合はDefaultAzureCredentialで認証されます。コンテナが無ければ自動で作られます。

output_storage:
  type: blob
  account_url: https://<ストレージ名>.blob.core.windows.net
  container_name: graphrag-output
  base_dir: output

vector_store:
  type: azure_ai_search
  url: https://<検索サービス名>.search.windows.net
  # api_key を書かなければ DefaultAzureCredential で接続

Azure AI Searchを選ぶと、graphragはHNSW（コサイン類似度）のベクトル項目を持つインデックスを作ります。Cosmos DBのcosmosdbはNoSQL APIのデータベースとして使われ、Gremlin APIのグラフとして経路を探索する仕組みではありません。既存の検索基盤に載せるならAI Search、PoCなら既定のLanceDBで足ります。グラフを構築せずにAI Searchへ直接つなぐマネージド構成との違いはAzure OpenAI On Your Dataとは？廃止予定までの構成と移行の判断で扱っています。

クエリ方式の使い分け｜global・local・drift・basic

globalは対象レポートをmap-reduceで処理するため、レポート量に応じてLLM呼び出しが増えます。driftも追加質問とlocal検索を反復するため、呼び出し回数の大小は設定とデータに依存します。--community-level（既定2）はLeiden階層の何層目のレポートを読むかの指定で、値を上げるほど小さなコミュニティまで参照します。basicはグラフを使わない比較用の経路です。精度に不満があるときは、同じ質問をbasicとglobalに投げて切り分けます。

増分更新の制約｜既存文書の改訂・削除が反映されない仕様

graphrag updateは、追加された文書だけを抽出して既存のインデックスにマージします（standard方式なら内部でstandard-updateが走ります）。ところが新しい文書かどうかの判定は、incremental_index.pyで文書のtitleを比べているだけです。テキスト入力のtitleはファイル名なので、同じ名前のまま中身を変えた文書は「新しい文書」になりません。

モックLLMを使ったfastインデックスで確かめました。2文書で作ったインデックスに新しいファイルnorthwind.txtを足してupdateすると、文書は3件、コミュニティレポートは2件から3件になり、新しい人物も取り込まれました。次に既存のcontoso.txtへ「最高リスク責任者が交代した」という文を追記してupdateしたところ、ログにNo new update documents found.という警告が1行出ただけで、終了コードは0でした。追記した人物はエンティティに入っていません。

ファイル名を変えれば取り込まれますが、古い版は消えません。contoso.txtをcontoso_v2.txtに改名して追記してからupdateすると、文書はcontoso.txtを残したまま4件に増え、交代前と交代後の責任者が両方ともエンティティに残りました。入力フォルダから消したファイルも索引からは消えないということです。規程集やマニュアルのように同じ文書を改訂していく用途では、updateに頼らず、改訂のたびに出力先を空にして全量で作り直してください。

日本語文書の抽出設定｜エンティティ型・抽出器・除外語

1つ目はエンティティ型です。initが書き出すentity_typesはorganization・person・geo・eventの4種類だけです。製品名・型番・法令名・業務プロセス名は拾われにくいので、standard方式ではentity_typesを業務語彙に置き換えるか、graphrag prompt-tuneで抽出プロンプトを対象コーパスに合わせてから本番のインデックスを作ります。

2つ目はfastインデックスの名詞句抽出器です。fastはグラフ抽出をLLMではなくNLP処理で行い、既定の抽出器はregex_englishです。日本語2文書をこの既定のまま流すと、NLP Graph Extraction failed. No entities detected during extraction.で止まりました（同じ構成の英文2文書では13件のエンティティが取れました）。抽出器をsyntactic_parserに変え、spaCyの日本語モデルを指定すると13件取れました。

extract_graph_nlp:
  text_analyzer:
    extractor_type: syntactic_parser
    model_name: ja_core_news_md
    word_delimiter: ""

このとき、graphragは未導入のモデルをその場でダウンロードします。ja_core_news_md 3.8.0（42.1MB）と辞書のsudachidict_core（76.9MB）が取得されたので、閉じたネットワークで動かす場合はコンテナイメージのビルド時に入れておいてください。また、word_delimiterを書かないと、取れた名詞句は「コントソ 銀行」「最高 リスク 責任 者」のようにトークンの間に半角スペースが入ります。既定の区切り文字が半角スペースだからで、上のようにword_delimiter: ""を指定すると「コントソ銀行」「最高リスク責任者」と原文どおりの表記で13件取れました。

3つ目は除外語です。名詞句抽出で無視する語の既定値は英語のストップワード集合（EN_STOP_WORDS）なので、「こと」「もの」「ため」のような語は除外されません。fastで日本語を扱うなら、exclude_nounsも日本語の語彙に差し替えてください。

コストと採用判断｜GraphRAGを使うべきでない場面

GraphRAGの費用は、コーパスの量で決まるインデックス費用と、質問のたびにかかるクエリ費用の2つです。重いのは前者で、standard方式ではチャンクごとの抽出とコミュニティごとの要約でLLMを呼ぶため、誰も質問しなくてもインデックス費用がかかります。fast方式はグラフ抽出をNLP処理に置き換えるので、LLMの費用はコミュニティレポートの分だけになります。Microsoft Researchが2024年11月25日に発表したLazyGraphRAGは、事前の要約をやめることで、インデックスのコストをベクトルRAGと同等、フルのGraphRAGの0.1%に抑えたとしています。AzureでLazyGraphRAGを使える公式の経路として確認できたのは、前述のMicrosoft Discovery（GA・許可リスト制）とAgentic Retrieval in Foundry Local（プレビュー）の2つです。

次の条件に当てはまるなら、GraphRAGは見送ってください。

• 質問が「規程の第何条に何が書いてあるか」のような事実照会に偏っている。コミュニティレポートが使われず、インデックス費用だけが残ります。
• 文書を頻繁に改訂する。前章のとおりupdateでは改訂も削除も反映されず、作り直しの費用が改訂のたびにかかります。
• 対象文書の総量がモデルの入力上限に収まる。全文をコンテキストに直接入れるか、通常のRAGで必要な品質が出るなら、グラフを作る費用に見合いません。

見送る場合の代替としては、ベクトルを使わない推論型のPageIndexとは？ベクトル不要の推論型RAGの仕組みと使い方【v0.2.19対応】や、複数の検索結果を統合するRRF（Reciprocal Rank Fusion）とは？計算式とk=60の意味・製品別設定・RAG-Fusionでの使い方があります。質問の意図ごとに検索経路を切り替える設計はOmniRAGとは？意図に応じてDB・ベクトル検索・ナレッジグラフを使い分けるRAG設計パターンで解説しています。回答の誤りを減らすことが目的なら、GraphRAGの前にAIハルシネーション対策｜プロンプト・RAG・検出APIで誤答を減らす実装手順の対策で足りるかを確かめてください。社内文書を対象にしたRAGチャットボットの構成選定から相談したい場合は、AIチャットボット開発で支援しています。

よくある質問

GraphRAG Acceleratorはまだ使えますか？

リポジトリは2025年5月27日にアーカイブされ、読み取り専用です。READMEにも保守を終了したと書かれています。手元でデプロイスクリプトを動かすことはできても修正は入らないので、新しく組む場合はgraphragライブラリを使ってください。

graphragの最新バージョンは？

2026年10月8日公開の3.3.0です。Pythonは3.11以上3.14未満に対応しています。3.0で設定ファイルの形式が変わったため、2.x以前の設定例はcompletion_modelsとembedding_modelsに書き直す必要があります。

Azure AI Searchは必須ですか？

必須ではありません。ベクトルストアの既定はLanceDBで、vector_store.typeをazure_ai_searchにしたときだけAI Searchを使います。APIキーを書かなければDefaultAzureCredentialで接続します。

GraphRAGとベクトルRAGはどう使い分けますか？

文書群全体の傾向や主要な論点を問う質問はGraphRAG（global検索）、特定の事実を引く質問はベクトルRAGで足ります。迷ったら、同じ質問をgraphragのbasic（ベクトル検索のみ）とglobalの両方に投げて、回答の差を見てください。

GraphRAGはAzureのマネージドサービスとして提供されていますか？

LazyGraphRAGを組み込んだAzureのサービスは、Microsoft Discovery（GA・許可リスト制の研究開発向け基盤）と、Azure Local上で動くAgentic Retrieval in Foundry Local（プレビュー）です。graphragライブラリはローカル実行を前提にしたOSSで、公式の手順もCLIで動かす形なので、業務用のRAGでは自前のコンテナやVMで動かすことになります。

関連記事

• ベクトルデータベースとグラフデータベースの違い｜比較表・ナレッジグラフとの関係・3つのDBで実測【2026年版】
• AzureのグラフDBはどれを使う？Gremlin・Fabric Graph・Apache AGEとCosmos AI Graphの正体
• ベクトル検索とセマンティック検索の違い：包含関係・仕組み・pgvectorでの実装と使い分け
• OmniRAGとは？意図に応じてDB・ベクトル検索・ナレッジグラフを使い分けるRAG設計パターン
• Azure OpenAIのモデル廃止予定と対応手順｜引退日一覧・自動アップグレード・移行【2026年10月】