GraphRAG 实战指南：图结构 RAG 系统的初始化、索引构建、多方式查询与版本升级

GraphRAG 是微软研究院开源的、基于图结构的检索增强生成（RAG）系统，核心是用 LLM 从非结构化文本中抽取实体、关系与社区结构，再以此构建"目标化上下文"来回答私有数据上的问题。本文以仓库根目录的 README.md 为主线，结合 CLI 源码、配置默认值 等实现细节，完整讲清环境搭建、graphrag init/index/query 全流程操作、Prompt 调优与版本升级策略，读完即可独立完成从建索引到问答的全链路，并安全地跟随版本演进。

一、项目定位与现状：研究性项目与"维护模式"

README 对 GraphRAG 的定义非常明确：它是一个数据管道与转换套件（data pipeline and transformation suite），设计目标是利用 LLM 的强大能力，从非结构化文本中提取有意义、结构化的数据。从 docs/index/overview.md 可以进一步看到，标准索引管道的设计目标是：

• 从原始文本中抽取实体（entities）、关系（relationships）和断言（claims）；
• 在实体上执行社区检测（community detection）；
• 在多个粒度层级上生成社区摘要与报告（community reports）；
• 将文本嵌入到向量空间（embeddings）。

管道产出默认以 Parquet 表形式落盘，嵌入则写入你配置的向量库。

有两点必须在动手前认清（均来自 README.md 原文）：

1. 维护模式声明：GraphRAG 是一个研究项目，自 2024 年 7 月首次发布以来，前沿模型能力已发生巨大变化，该项目目前主要处于维护模式，不接受新的 PR 和新功能，只会按需做 bug 修复与依赖更新（尤其是 CVE）。因此它更适合作为方法论参考与生产级索引工具，而不是持续演进的框架。
2. 成本警告：README 明确提示"GraphRAG indexing can be an expensive operation"——索引过程会大量调用 LLM，官方强烈建议先通读文档、从小数据集开始（官方教程数据集是 Operation Dulce，见 docs/data/operation_dulce/ABOUT.md）。

此外 README 强调：仓库代码是方法论演示（demonstration），不是微软官方支持的产品。

二、仓库结构：Monorepo 与模块化包划分

从 根 pyproject.toml 的 tool.uv.workspace 配置可以看到，这是一个 monorepo，核心能力被拆分为多个独立包：

包	职责（从包名与目录结构看）
packages/graphrag	主包：CLI、索引管道、查询引擎、配置模型、提示词
packages/graphrag-llm	LLM 层：补全/嵌入工厂、缓存、重试、限流、指标
packages/graphrag-storage	存储抽象：file/azure blob/cosmos、Parquet/CSV/Cosmos 表
packages/graphrag-vectors	向量库抽象：LanceDB、Azure AI Search、CosmosDB
packages/graphrag-input	输入读取：text、csv、jsonl、parquet、markitdown 等
packages/graphrag-chunking	文本切块：token/sentence 策略
packages/graphrag-cache	LLM 响应缓存：memory/noop/json
packages/graphrag-common	配置加载、工厂、哈希等公共工具

从源码结构看，这种"CLI/API 在上、能力包在下"的划分，正好对应了项目对破坏性变更的分层承诺（见第六节）：CLI 与 API 层遵循语义化版本，而内部实现包可以随时演进。

三、快速上手：环境与安装

依据 docs/get_started.md（README"Quickstart"一节指向的官方入门文档），安装步骤如下：

环境要求：面向 PyPI 安装版本的入门文档要求 Python 3.10–3.12；而用于本地开发源码的 根 pyproject.toml 声明 requires-python = ">=3.11,<3.14"，两者按使用场景分别满足即可。

# 1. 创建项目空间与虚拟环境
mkdir graphrag_quickstart
cd graphrag_quickstart
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# 2. 安装
python -m pip install graphrag

官方同样警告：GraphRAG 会消耗大量 LLM 资源，建议先跑教程数据集、先尝试快速/廉价的模型，再启动大规模索引任务。

安装完成后，graphrag 可执行入口来自 packages/graphrag/graphrag/main.py，它直接调用 cli/main.py 中基于 Typer 构建的 app。从该文件的命令注册可以看到当前 CLI 共提供五个子命令：init、index、update、prompt-tune、query。

四、项目初始化：graphrag init 生成了什么

graphrag init

交互式提示中指定默认 chat 模型与 embedding 模型后，命令会在当前目录生成三类产物。这一点可以从实现代码 cli/initialize.py 中逐一印证：

1. settings.yaml：管道设置文件。initialize_project_at() 用 config/init_content.py 中的 INIT_YAML 模板，替换 <DEFAULT_COMPLETION_MODEL> 与 <DEFAULT_EMBEDDING_MODEL> 占位符后写入；
2. .env：环境变量文件，默认仅包含 GRAPHRAG_API_KEY=<API_KEY>，替换为你自己的 OpenAI 或 Azure API Key；
3. input/ 目录：待处理文本文件的放置位置（目录名可由配置中的 input_storage.base_dir 覆盖，默认即 input）；
4. prompts/ 目录：写入 13 个默认提示词文件，覆盖索引侧（extract_graph、summarize_descriptions、extract_claims、community_report_graph、community_report_text）与查询侧（local_search_system_prompt、global_search_map_system_prompt、global_search_reduce_system_prompt、drift_search_system_prompt、drift_reduce_prompt、basic_search_system_prompt、question_gen_system_prompt 等）。

init 的完整参数（摘自 cli/main.py 中 init 命令定义）：

参数	默认值	说明
--root, -r	当前目录	项目根目录
--model, -m	gpt-4.1	默认 chat 模型（会交互式提示）
--embedding, -e	text-embedding-3-large	默认 embedding 模型
--force, -f	False	项目已存在时强制重新初始化

默认模型与 Provider 来自 config/defaults.py：DEFAULT_COMPLETION_MODEL = "gpt-4.1"、DEFAULT_EMBEDDING_MODEL = "text-embedding-3-large"、DEFAULT_MODEL_PROVIDER = "openai"。

配置 Azure OpenAI 与托管身份认证

如果你使用 Azure OpenAI，需要在 settings.yaml 的 models: 根配置下找到默认 chat 与 embedding 两个 section，补充如下内容（引自 docs/get_started.md）：

type: chat
model_provider: azure
model: gpt-4.1
azure_deployment_name: <AZURE_DEPLOYMENT_NAME>
api_base: https://<instance>.openai.azure.com
api_version: 2024-02-15-preview # You can customize this for other versions

若要使用托管身份（Managed Identity）认证，将 auth_method 改为 azure_managed_identity 并删除 api_key 行，然后用 az login 登录并选择拥有端点的订阅：

auth_method: azure_managed_identity # Default auth_method is api_key

更多配置项语义（models、embeddings、storage、vector_store 等）详见 docs/config/overview.md 与 docs/config/init.md。

五、索引构建：graphrag index

准备好输入文本（官方快速上手示例下载了《A Christmas Carol》放入 input/）后，执行：

graphrag index

通常几分钟内完成。管道结束后会生成 ./output 目录，其中是 documents.parquet、entities.parquet、relationships.parquet、text_units.parquet、communities.parquet、community_reports.parquet、covariates.parquet、embeddings.*.parquet 等一系列 Parquet 文件（可对照 docs/examples_notebooks/inputs/operation dulce/ 下 Operation Dulce 教程集的产物结构）。

index 命令的完整参数（摘自 cli/main.py）：

参数	默认值	说明
--root, -r	当前目录	项目根目录
--method, -m	standard	索引方法，取值见 config/enums.py 的 IndexingMethod：standard（全 LLM 建图）、fast（NLP 建图 + LLM 摘要）、standard-update / fast-update（增量更新）
--verbose, -v	False	详细日志
--dry-run	False	不执行任何步骤，仅检查与校验配置
--cache/--no-cache	开启	是否使用 LLM 缓存（对成本敏感的场景非常关键，缓存默认存于 cache/ 目录）
--skip-validation	False	跳过预检校验，适用于不含 LLM 步骤的运行

几个与成本直接相关的默认值（均来自 config/defaults.py）值得注意：文本切块 chunking.size = 1200 tokens、overlap = 100；实体抽取默认类型 ["organization", "person", "geo", "event"] 且 max_gleanings = 1（额外补抽取一轮）；默认并发 concurrent_requests = 25。向量库默认是本地 LanceDB，库位置为 output/lancedb（VectorStoreDefaults），这也是 v1 起"向量必须写入向量库"这一破坏性变更的默认落地方式。

六、知识问答：graphrag query 与四种检索方法

索引完成后，即可用 graphrag query 提问。README 与入门文档给出的两个典型用法：

# Global search：适合高层级、跨文档的主题性问题
graphrag query "What are the top themes in this story?"

# Local search：适合针对特定实体（如某个人物）的具体问题
graphrag query \
  "Who is Scrooge and what are his main relationships?" \
  --method local

query 命令的完整参数（摘自 cli/main.py，方法取值来自 config/enums.py 的 SearchMethod）：

参数	默认值	说明
query（位置参数）	必填	要执行的自然语言问题
--root, -r	当前目录	项目根目录
--method, -m	global	检索算法：local / global / drift / basic
--data, -d	无	指定索引产物目录（含 parquet 文件），默认读 output
--community-level	2	加载社区报告的 Leiden 层级，数值越大社区越小
--dynamic-community-selection	False	global search 下启用动态社区选择
--response-type	Multiple Paragraphs	自由描述期望的回答格式，如 Single Sentence
--streaming	False	流式打印回答

从 cli/main.py 中 match method 的分发逻辑可以看到，四种方法分别路由到 run_local_search、run_global_search、run_drift_search、run_basic_search。结合各方法的默认配置（config/defaults.py）可以推断其定位差异：local 围绕实体邻域构建上下文（text_unit_prop=0.5、community_prop=0.15、top_k_entities=10）；global 走 map-reduce 社区报告路线（data_max_tokens=12000、map_max_length=1000、reduce_max_length=2000）；drift 在两者间动态折中；basic 则退化为纯向量检索（k=10、max_context_tokens=12000），不依赖图结构。各方法的详细原理可深入 docs/query/overview.md、docs/query/local_search.md、docs/query/global_search.md 与 docs/query/drift_search.md。

七、Prompt 调优：prompt-tune

README 中专设"Prompt Tuning"一节并给出强烈建议：开箱即用的默认提示词在你的数据上未必是最优的，官方强烈推荐按 Prompt Tuning 指南微调提示词（指南见 docs/prompt_tuning/overview.md）。

对应 CLI 子命令为 graphrag prompt-tune，其作用（源码注释原文）是"Generate custom graphrag prompts with your own data (i.e. auto templating)"——即用自己的语料自动生成定制提示词，输出到 prompts/ 目录供后续索引使用。关键参数（摘自 cli/main.py）：

参数	默认值	说明
--domain	无	输入数据的领域（如 "space science"），不指定时从数据推断
--selection-method	random	样本文本块选择方法
--limit	见 prompt_tune.defaults.LIMIT	random/top 方式下加载的文档数
--max-tokens	见 MAX_TOKEN_COUNT	提示词生成的最大 token 数
--chunk-size / --overlap	继承 chunking.size/overlap（1200/100）	示例文本块大小，覆盖配置文件中的切块设置
--min-examples-required	2	实体抽取提示词中要求的最少示例数
--language	无	输入输出提示词使用的主要语言
--discover-entity-types	True	是否自动发现并抽取未指定的实体类型
--output, -o	prompts	提示词输出目录（相对项目根目录）

八、版本管理与破坏性变更：README"Versioning"一节的展开

README 的 Versioning 部分指向 breaking-changes.md，其核心信息是：项目自 v1.0 起向标准语义化版本靠拢，并把可能被发布影响的"表面"分为五类：

1. CLI：最常用接口，遵循标准 semver；
2. API 层（packages/graphrag/graphrag/api/）：作为库集成的主要接口，遵循标准 semver；
3. 内部模块：CLI 与 API 之后的所有代码均为 "internal"，可随任何版本自由变动，不保证兼容——因此建议只使用 index/query 的 API，不要直接依赖内部模块；
4. settings.yaml：配置格式调整会造成次要版本（minor）bump；graphrag init 总会产出兼容的初始配置，官方建议在跨 minor 版本升级时重新运行 init，再把端点等自定义项拷贝回新文件；
5. 数据模型（索引产物表）：遵循 semver，大版本之间会提供迁移 notebook 并做向后兼容垫片（shim），无需重新索引。

README 给出的操作性结论（"Always run..."段落）应作为升级流程记住：

• 跨 minor 版本升级：始终运行 graphrag init --root [path] --force 获取最新配置格式；
• 跨 major 版本升级且不想重新索引：运行仓库提供的迁移 notebook，例如 docs/examples_notebooks/index_migration_to_v3.ipynb、index_migration_to_v2.ipynb、index_migration_to_v1.ipynb。注意 --force 会覆盖你的配置与 prompts 目录，务必先备份。

从 breaking-changes.md 的 v3 条目还可以看到配置模型的具体演进，例如：移除 fnllm 后模型类型统一为 chat / embedding（旧的 openai_chat 等取值已无效，且必须显式提供 model_provider）、vector_store 收敛为单一根级对象、删除 umap / embed_graph 块等——这些正是需要重跑 init 的典型原因。

九、责任 AI、可视化与社区参与

• 责任 AI：README 提供 RAI_TRANSPARENCY.md 的 FAQ 索引，覆盖"GraphRAG 是什么/能做什么、预期用途、评估方式与指标、局限性及其缓解手段、有效且负责任使用的操作因素与配置"六个问题，部署前建议通读；
• 可视化：docs/visualization_guide.md 指导用 Gephi 等工具交互地调试与探索知识图谱（v3 移除了内置 UMAP 坐标后，这成为查看 x/y 布局的官方替代路径）;
• 贡献与开发：贡献规范见 CONTRIBUTING.md，源码开发环境（uv workspace + poethepoet 任务）见 DEVELOPING.md；
• 测试：仓库自带完整的 unit / integration / verbs 测试体系（如 tests/unit/indexing/、tests/verbs/），可作为理解各管道步骤行为的可执行文档。

小结

GraphRAG 的价值链条可以浓缩为一条命令序列：graphrag init（生成 settings.yaml、.env、input/ 与默认 prompts）→ 放入语料 → graphrag index（LLM 抽取实体关系、Leiden 社区检测、社区报告、向量入库）→ graphrag query --method local|global|drift|basic（按问题粒度选择检索策略）。在此基础上，prompt-tune 提升域适配度，LLM 缓存与 --dry-run 控制成本，而 breaking-changes.md 定义的"CLI/API 遵循 semver、minor 升级重跑 init、major 升级跑迁移 notebook"则是跟随该维护模式项目演进的稳妥路径。