GraphRAG 概述与系统架构

一、项目定位与目标

GraphRAG 是一个由 Microsoft 开源的数据管道与转换套件，专注于使用大语言模型（LLM）从非结构化文本中抽取有意义的、结构化的数据，特别是构建知识图谱以增强 LLM 对私有数据进行推理的能力。官方仓库说明中明确指出：*"GraphRAG project is a data pipeline and transformation suite that is designed to extract meaningful, structured data from unstructured text using the power of LLLM"* 资料来源：README.md:1-3。

项目的核心思路是：将知识图谱记忆结构与 LLM 相结合，使模型能够在私有领域语料上进行全局性的、跨实体的发现与问答。Microsoft Research Blog Post 中进一步阐述了 GraphRAG 在叙事性私有数据上的应用价值。资料来源：packages/graphrag/README.md:9-11。

⚠️ 使用提示：项目文档反复警告 *"GraphRAG indexing can be an expensive operation, please read all of the documentation to understand the process and costs involved, and start small"*，因此建议新用户从小型数据集入手。资料来源：README.md:18-20。

二、整体系统架构

GraphRAG 采用模块化 monorepo 架构，将不同职责拆分为独立的 Python 包，每个包都包含独立的 README 与示例 notebook，方便按需使用与扩展。

包结构概览

资料来源：packages/graphrag-chunking/README.md:1-5、packages/graphrag-common/README.md:1-7、packages/graphrag-input/README.md:5-9、packages/graphrag-llm/graphrag_llm/README.md:1-3、packages/graphrag-storage/README.md:3-5。

端到端数据流

flowchart LR
    A[原始文档<br/>CSV/JSON/TXT/PDF] --> B[graphrag-input<br/>输入加载]
    B --> C[graphrag-chunking<br/>文本分块]
    C --> D[graphrag-llm<br/>LLM 抽取三元组/实体/关系]
    D --> E[知识图谱<br/>实体+关系+社区报告]
    E --> F[graphrag-storage<br/>持久化]
    E --> G[查询引擎<br/>global/local/drift/basic]
    G --> H[用户响应]

    classDef pkg fill:#e1f5fe,stroke:#01579b,color:#000;
    class B,C,D,F,G pkg;

整个流程通过 graphrag 核心包对外暴露的三个主要 API（索引、查询、提示调优）进行编排，使用者既可通过 CLI 也可通过 Python API 调用。资料来源：packages/graphrag/graphrag/api/__init__.py:11-37。

三、核心 API 与编程入口

1. 索引 API（Indexing API）

build_index 函数是构建知识图谱的主入口，签名支持传入 GraphRagConfig、索引方法（默认 IndexingMethod.Standard）、是否为更新运行（is_update_run）、回调函数链以及可选的输入文档 DataFrame。资料来源：packages/graphrag/graphrag/api/index.py:31-58。底层通过 run_pipeline 配合 PipelineFactory 装配工作流，支持自定义扩展。资料来源：packages/graphrag/graphrag/api/index.py:21-28。

2. 查询 API（Query API）

查询层通过 query.py 模块对外暴露 8 个函数，对应 4 种搜索模式 × 流式/非流式：

• global_search / global_search_streaming：跨社区的全局检索
• local_search / local_search_streaming：基于实体的局部检索
• drift_search / drift_search_streaming：DRIFT 推理检索
• basic_search / basic_search_streaming：基础向量检索

资料来源：packages/graphrag/graphrag/api/query.py:12-20、packages/graphrag/graphrag/api/__init__.py:21-28。

3. 提示调优 API（Prompt Tuning API）

官方明确建议在默认配置下 *"may not yield the best possible results"*，因此提供 generate_indexing_prompts 函数用于基于自有数据自动生成提示词，包括领域（domain）、角色（persona）、实体类型、报告角色等多个生成器。资料来源：packages/graphrag/graphrag/api/prompt_tune.py:11-25、README.md:30-35。

四、社区关注与已知限制

GitHub Issues 中关注度较高的需求与限制与系统架构密切相关：

• 增量索引（Incremental indexing）：Issue #741 显示有大量用户希望在不重新执行整个流程的前提下向已有索引追加新内容，这是当前架构中的"高优先级设计课题"。资料来源：Issue #741（社区反馈）。
• 多模型供应商支持：Issue #657 与 #345 表明用户希望在 OpenAI/Azure 之外支持 Ollama 等本地模型；当前 graphrag-llm 主要通过统一抽象层 create_completion + ModelConfig 适配，但官方明言研究团队带宽有限。资料来源：packages/graphrag-llm/graphrag_llm/README.md:9-23、Issue #657。
• 更便宜的三元组抽取：Issue #632 提议集成 Triplex 模型以降低抽取成本，这要求未来在 graphrag-llm 之上扩展模型适配层。资料来源：Issue #632。
• LazyGraphRAG 路线：Issue #1512 是评论数最多的讨论之一，反映了用户对低成本、增量式图谱构建方法的期待。资料来源：Issue #1512。

最新发布版本 v3.1.0 重点改进了 AzureCosmosStorage，引入 CosmosTableProvider 命名空间分区与事务批写入；同时更新了 litellm 依赖，这从侧面体现了存储与 LLM 调用层在架构中的活跃演进。资料来源：Release v3.1.0 变更说明。

五、版本与配置建议

由于 API 仍处于演进阶段，文档提示 *"WARNING: This API is under development and may undergo changes in future releases. Backwards compatibility is not guaranteed at this time."*。资料来源：packages/graphrag/graphrag/api/__init__.py:7-9。

升级建议：

1. 在小版本升级之间执行 graphrag init --root [path] --force 以获取最新配置格式；
2. 在大版本升级之间运行迁移 notebook 以避免重新索引既有数据集；
3. 务必先备份自定义配置与提示词。

资料来源：README.md:42-44。

See Also

• Microsoft Research Blog Post
• GraphRAG 官方文档
• GraphRAG Arxiv 论文
• 相关 wiki 页面：Prompt Tuning、Query Engine、Storage Backends、Chunking Strategies、LLM Providers

概述

GraphRAG 是一套数据管道与转换套件，旨在利用大语言模型（LLM）从非结构化文本中抽取有意义的结构化数据 README.md:1-10。索引（Indexing）是系统的核心环节，它将原始文档处理为知识图谱及社区报告，从而支撑后续的本地搜索、全局搜索与流式查询 packages/graphrag/graphrag/api/query.py:1-50。

索引管道由若干可组合的 Workflow（工作流）构成，遵循统一的工厂模式与配置驱动设计 packages/graphrag-common/README.md:1-20。每个工作流负责数据处理流水线中的一个明确阶段，运行入口位于 run_pipeline.py，并通过 workflows/factory.py 注册与实例化 packages/graphrag/graphrag/index/run/run_pipeline.py:1-30。

整体数据流

下图展示了从原始输入到可查询产物的主要数据流向：

flowchart LR
    A[Input Documents<br/>load_input_documents] --> B[Text Chunking<br/>graphrag-chunking]
    B --> C[Graph Extraction<br/>extract_graph / extract_graph_nlp]
    C --> D[Community Detection<br/>create_communities]
    D --> E[Community Reports]
    E --> F[Parquet Artifacts<br/>entities / relationships / reports]
    F --> G[Query API<br/>local / global search]

核心工作流阶段

1. 输入加载（load_input_documents）

该工作流负责将各种格式的源文档加载为统一的内部表示。graphrag-input 包支持多类输入源，例如基于 markitdown 的 PDF 处理（需安装 markitdown[pdf]）以及基于文件系统的目录读取 packages/graphrag-input/README.md:1-30。YAML 配置中的 input.type 与 input.file_pattern 字段用于指定输入源类型与文件匹配规则。

2. 文本分块（Chunking）

加载后的文档通过 graphrag-chunking 包进行切分，常见策略包括基于 NLTK 的句子分块（SentenceChunker）与基于 token 计数的定长分块（TokenChunker）packages/graphrag-chunking/README.md:1-15。工厂函数 create_chunker 接受 ChunkingConfig 对象，根据 strategy 字段动态实例化对应分块器，实现配置与实现的解耦。

3. 图谱抽取（extract_graph / extract_graph_nlp）

此阶段是 GraphRAG 的核心。系统提供两条抽取路径：

• LLM 抽取（extract_graph.py）：利用 LLM 执行实体、关系与协变量的识别，需配合 prompt_tune 生成或人工编写的 prompt 模板 packages/graphrag/graphrag/index/workflows/extract_graph.py:1-30。
• NLP 抽取（extract_graph_nlp.py）：作为不依赖 LLM 的替代方案，可在受限或离线环境下使用 packages/graphrag/graphrag/index/workflows/extract_graph_nlp.py:1-20。

提示词模板通过 prompt_tune API 生成，支持自动发现领域（domain）、语言（language）、实体类型（entity_types）以及示例选择策略（如 random / auto）packages/graphrag/graphrag/api/prompt_tune.py:1-60。CLI 命令 graphrag prompt-tune 进一步封装了该流程 packages/graphrag/graphrag/cli/prompt_tune.py:1-40。

4. 社区构建（create_communities）

抽取得到的实体与关系构成图谱后，由 create_communities 工作流执行社区检测，识别密集子图并生成层级化社区结构。该输出为后续 community_reports 的生成提供分组依据 packages/graphrag/graphrag/index/workflows/create_communities.py:1-20。

5. 输出与查询对接

索引最终产物以 Parquet 文件形式持久化，统一存放在 output/ 目录下。下表列出了关键输出表：

这些产物随后被 api/query.py 中的 local_search、global_search 等查询函数消费 packages/graphrag/graphrag/api/query.py:1-120。unified-search-app 中的 Streamlit 应用也直接读取这些表来渲染引用与社区报告 unified-search-app/app/data_config.py:1-30。

配置、扩展性与已知限制

工厂与依赖注入

graphrag-common 包提供基于字符串策略的工厂机制（Factory），支持 transient 与 singleton 两种作用域，便于在不改代码的前提下替换工作流实现 packages/graphrag-common/README.md:1-20。load_config 函数负责解析 YAML/JSON 配置，并支持环境变量替换与 .env 文件加载。

社区关注的已知限制

• 增量索引（Incremental Indexing）：用户希望在不完全重建的前提下向现有索引追加新内容。社区讨论 #741 指出该功能仍在设计阶段，截至当前版本尚未原生支持。
• 模型提供方：系统目前仅原生支持 OpenAI 与 Azure，社区多次请求添加 Ollama 等本地或第三方模型提供方（#345、#657）；官方建议通过 litellm 等适配层集成。
• 抽取成本：官方 README 明确警告索引可能消耗大量 token，建议先在小规模数据上验证 README.md:1-20。

See Also

• Prompt Tuning API
• Query API and Search Modes
• Chunking Strategies
• Configuration Reference

资料来源：packages/graphrag/graphrag/index/run/run_pipeline.py、packages/graphrag/graphrag/index/workflows/factory.py、packages/graphrag/graphrag/index/workflows/load_input_documents.py、packages/graphrag/graphrag/index/workflows/extract_graph.py、packages/graphrag/graphrag/index/workflows/extract_graph_nlp.py、packages/graphrag/graphrag/index/workflows/create_communities.py、packages/graphrag/graphrag/api/query.py、packages/graphrag/graphrag/api/prompt_tune.py、packages/graphrag/graphrag/cli/prompt_tune.py、packages/graphrag-chunking/README.md、packages/graphrag-input/README.md、packages/graphrag-common/README.md、README.md、unified-search-app/app/data_config.py。

GraphRAG 的查询引擎（Query Engine）是索引流水线完成之后对外提供检索与生成能力的核心子系统。它基于已生成的实体表、关系表、社区表、社区报告表和文本单元表（parquet 产物），在用户提出自然语言问题时，利用 LLM 组合知识图谱上下文，再由 LLM 生成最终回答。该模块既可以以 Python API 形式被嵌入调用，也可以经由 CLI 与统一的 Streamlit Web 应用对外暴露。

1. 总体定位与 API 入口

查询引擎 API 集中在 packages/graphrag/graphrag/api/query.py 中，文件级注释明确指出"该 API 提供对 graphrag 查询引擎的访问，允许外部应用挂接到 graphrag 并对由 graphrag 生成的知识图谱运行查询"。当前内置并暴露以下四类入口函数：

资料来源：packages/graphrag/graphrag/api/query.py:1-15

这些函数在内部通过 graphrag.query.factory 中的工厂方法获得具体的搜索引擎实例，工厂方法列表包括 get_basic_search_engine、get_drift_search_engine、get_global_search_engine 与 get_local_search_engine，分别对应四类不同检索策略。资料来源：packages/graphrag/graphrag/api/query.py:36-40

2. 数据流与上下文组装

查询引擎在执行前需要先由 graphrag.query.indexer_adapters 中的若干 read_indexer_* 函数把 parquet 产物反序列化为 DataFrame，再交由各搜索策略处理：

flowchart LR
    A[parquet 索引产物] --> B[indexer_adapters.read_indexer_*]
    B --> C[DataFrame 集合]
    C --> D[query.factory 构建搜索引擎]
    D --> E[map / reduce / drift / basic 策略]
    E --> F[LLM 生成最终响应]
    F --> G[响应 + context_data]

资料来源：packages/graphrag/graphrag/api/query.py:42-49, packages/graphrag/graphrag/query/input/loaders/dfs.py:1-50

每个 read_indexer_* 适配器都规定了默认列名，例如实体表期望 id、title、description、human_readable_id、name_embedding、description_embedding、community_ids、text_unit_ids 与 degree 等列。资料来源：packages/graphrag/graphrag/query/input/loaders/dfs.py:9-58

3. 主要搜索方法

3.1 Global Search（全局搜索）

global_search 接收 entities、communities、community_reports 三个 DataFrame 以及 community_level、dynamic_community_selection、response_type 等参数。它的核心思路是"先把社区报告切碎成要点，再 map-reduce 汇总"，适合"数据集整体在讲什么"这种宏观问题。是否启用动态社区选择由 dynamic_community_selection 控制，启用后可结合 community_level 设定最大层级作为上限。资料来源：packages/graphrag/graphrag/api/query.py:117-138

3.2 Local Search（局部搜索）

local_search 需要 entities、communities、community_reports、text_units、relationships、可选的 covariates 以及 community_level 与 response_type。它会围绕与查询最相关的实体抽取邻居关系、文本片段、社区上下文，再让 LLM 基于这些细粒度证据作答，常用于事实型、点对点问题。资料来源：packages/graphrag/graphrag/api/query.py:140-176

3.3 Drift Search 与 Basic Search

工厂层还提供 get_drift_search_engine 与 get_basic_search_engine 两类策略。basic_search_streaming 仅依赖 text_units 一张表就能完成纯文本片段检索，CLI 中 _resolve_output_files(config=config, output_list=["text_units"]) 即为该路径的最小数据需求。资料来源：packages/graphrag/graphrag/cli/query.py:120-180

4. CLI、Web 应用与社区关注点

CLI 在 packages/graphrag/graphrag/cli/query.py 中通过 run_basic_search 等包装函数复用同一个 API 层，先用 load_config 加载 settings.yaml，再调用 api.basic_search_streaming 等接口。资料来源：packages/graphrag/graphrag/cli/query.py:110-150

在 unified-search-app 中，Streamlit 应用通过 app/data_config.py 约定的表名常量（如 community_report_table = "output/community_reports"）加载已经构建好的图谱，再由 app/ui/search.py 中的 display_citations 把 context_data 渲染成引用面板，把 LLM 输出渲染成"响应区"。资料来源：unified-search-app/app/data_config.py:1-25, unified-search-app/app/ui/search.py:1-50

社区方面，与查询体验直接相关的两条高热度议题是：

• #741「Incremental indexing」：希望在现有索引上追加新内容而不重跑整条流水线。查询引擎本身依赖的是索引产物，所以此特性同时影响"输入"与"输出"，是查询模块间接关注的改进方向。
• #1512「LazyGraphRAG」：用户对更轻量、按需的检索方式期待已久，与 drift_search / basic_search 这类更便宜、更聚焦的策略方向一致。

See Also

• 索引流水线与配置：GraphRAG Configuration & Indexing Pipeline
• Prompt 调优入口：packages/graphrag/graphrag/api/prompt_tune.py
• 统一检索 Web 应用：unified-search-app/

概述

GraphRAG 是一个基于知识图谱的检索增强生成（RAG）框架，其核心架构围绕四大可配置支柱展开：配置系统（Configuration）、LLM 提供商（LLM Providers）、存储抽象（Storage）以及扩展性（Extensibility）。整个项目通过模块化的 Python 包结构，将这些关注点解耦，使开发者能够灵活替换底层实现。资料来源：packages/graphrag/README.md。

下图为整体架构的数据流与扩展点概览：

flowchart LR
    A[输入文档] --> B[Input Loader]
    B --> C[Chunking]
    C --> D[Graph Extraction]
    D --> E[LLM Provider]
    E --> F[Storage Layer]
    F --> G[Query Engine]
    G --> H[Search Results]
    I[GraphRagConfig] -.配置.-> B
    I -.配置.-> C
    I -.配置.-> D
    I -.配置.-> E
    I -.配置.-> F

配置系统（Configuration）

GraphRAG 的配置系统以 GraphRagConfig 为根模型，采用 Pydantic 风格的强类型配置模式。配置入口位于 packages/graphrag/graphrag/config/models/__init__.py，该模块声明了所有子配置模型的接口，包括 extract_graph_config、local_search_config、global_search_config 和 drift_search_config 等。资料来源：packages/graphrag/graphrag/config/models/__init__.py。

在 CLI 调用链中，graphrag.cli.prompt_tune 会通过 load_config 加载根目录的 YAML 配置，并允许通过命令行参数动态覆盖 chunking.size 与 chunking.overlap 等字段。这种"配置 + 覆盖"的双层机制既保留了声明式的可复现性，又为实验调试提供了灵活性。资料来源：packages/graphrag/graphrag/cli/prompt_tune.py:23-30。

unified-search-app/app/data_config.py 则演示了另一种轻量级配置模式：使用模块级常量定义数据表名（如 output/communities、output/community_reports）以及 LLM 调用的默认行为（如 default_suggested_questions、default_ttl）。资料来源：unified-search-app/app/data_config.py:8-30。

LLM 提供商（LLM Providers）

GraphRAG 在 API 层通过工厂方法创建语言模型实例。在 packages/graphrag/graphrag/api/prompt_tune.py 中，create_completion(default_llm_settings) 根据配置对象动态实例化 LLM，并支持通过 PROMPT_TUNING_MODEL_ID 常量指定提示词调优所用的模型。资料来源：packages/graphrag/graphrag/api/prompt_tune.py:38-44。

社区反馈显示，当前原生仅支持 OpenAI 与 Azure 托管的模型。Issue #657 与 Issue #345 中，大量用户请求添加对 Ollama 等本地模型以及第三方 API 的支持。官方回应表明，受限于研究团队带宽，短期内不会为更多模型提供商提供原生实现，但模块化的 LLM 工厂层为社区贡献者预留了接入点。资料来源：Issue #657、Issue #345。

此外，Issue #632 提议集成 Triplex 以降低三元组抽取成本，这进一步说明 LLM 抽象层需要支持即插即用的替换能力。资料来源：Issue #632。

存储抽象层（Storage）

packages/graphrag-storage 包提供了统一的存储抽象，通过工厂模式支持多种后端。默认注册的存储提供者包括 FileStorage、AzureBlobStorage、AzureCosmosStorage 与 MemoryStorage，对应 StorageType 枚举中的各个取值。资料来源：packages/graphrag-storage/README.md:25-35。

存储层的注册采用懒加载机制：例如 FileStorage 仅在首次请求 StorageType.File 时才会被导入与注册，从而避免不必要的依赖开销。若需构建纯净的工厂实例，可直接使用 storage_factory 绕过 create_storage 的预注册逻辑。资料来源：packages/graphrag-storage/README.md:36-42。

最新发布版本 v3.1.0 引入了原生 CosmosTableProvider，支持命名空间分区、事务化批量写入，并简化了 AzureCosmosStorage 的使用接口，标志着存储层正在向更高层次的数据操作 API 演进。资料来源：Release v3.1.0。

扩展性（Extensibility）

GraphRAG 通过四个独立 Python 包实现了高度的可扩展架构：graphrag-chunking 提供文本切分策略（句子切分、Token 切分、工厂模式），graphrag-input 提供多格式文档加载器（如 markitdown 用于 PDF 解析），graphrag-storage 提供可插拔的存储后端，主包 graphrag 则负责编排整个索引与查询流水线。资料来源：packages/graphrag-chunking/README.md:1-15、packages/graphrag-input/README.md:10-25。

用户可通过继承 Storage 基类并注册到工厂来添加自定义存储后端。该模式同样适用于 LLM 与切分器——只需实现对应接口并在配置中声明即可生效。unified-search-app 中的 knowledge_loader 模块进一步演示了如何将外部数据源接入统一的知识检索流程。资料来源：unified-search-app/app/knowledge_loader/__init__.py。

值得注意的是，社区高度关注的 LazyGraphRAG（Issue #1512，共 44 条评论）与 增量索引（Issue #741，共 35 条评论）功能仍处于设计与规划阶段，预计未来将通过配置系统与存储抽象层的扩展来实现。资料来源：Issue #1512、Issue #741。

See Also

• GraphRAG 主项目文档
• 存储抽象层详解
• 文本切分策略
• 输入加载器

Pitfall Log / 踩坑日志

项目：microsoft/graphrag

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/microsoft/graphrag | README/documentation is current enough for a first validation pass.

2. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/microsoft/graphrag | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/microsoft/graphrag | no_demo; severity=medium

4. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/microsoft/graphrag | no_demo; severity=medium

5. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/microsoft/graphrag | issue_or_pr_quality=unknown

6. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/microsoft/graphrag | release_recency=unknown