GraphRAG 版本演进与发布机制详解：基于 CHANGELOG 的完整升级与回溯指南

本文以 GraphRAG 仓库根目录下的 CHANGELOG.md 为主体，完整梳理该模块化图 RAG 系统从 0.1.0 初始版本到当前 3.1.1 的全部版本演进脉络，并结合仓库中的 RELEASE.md、breaking-changes.md、pyproject.toml 及发布脚本源码，深入讲解 GraphRAG 如何借助 semversioner 实现语义化版本管理、各版本间的破坏性变更迁移策略（graphrag init --force 与迁移 Notebook），以及单仓库多包（monorepo）架构下版本号的同步机制。读完本文，你可以准确判断某个功能（如增量索引、DRIFT 检索、LiteLLM 支持、TableProvider 抽象）在哪个版本引入、升级跨大版本时如何避免重建索引，并在参与贡献时正确触发版本变更。

一、版本策略总览：0.x 时代的宽松语义化版本

CHANGELOG.md 开头即有一条重要提示：

Note: version releases in the 0.x.y range may introduce breaking changes.

即 0.x.y 区间的版本发布可能引入破坏性变更。这与仓库中 breaking-changes.md 的说明相互印证：自 1.0 版本起，项目开始更严格地遵循标准语义化版本（SemVer）实践，但作为仍在快速迭代的研究型项目，团队并不保证在每一次发布中完美遵守规范。breaking-changes.md 进一步将受版本影响的面划分为五类，并明确了各自的兼容性承诺：

• CLI：面向终端用户的主界面，变更遵循标准 SemVer；
• API（packages/graphrag/graphrag/api）：作为库使用者应使用的主要接口层，变更遵循标准 SemVer；
• 内部实现：CLI 与 API 之外的模块属于"内部实现"，可能随时变化而不严格遵守 SemVer，若直接引用 index 或 query API 之外的内部模块，存在跨版本断裂的可能；
• settings.yaml 配置：配置格式变更会触发 minor 版本提升，官方建议在跨 minor 版本升级时运行 graphrag init 重新生成兼容的起始配置；
• 数据模型（输出表）：遵循 SemVer，跨大版本的输出表变更会提供向后兼容的"垫片"，并附带迁移 Notebook，使用户无需重建索引即可升级。

该文档给出的实践要点（TL;DR）是：跨 minor 版本升级时始终运行 graphrag init --path [path] --force 以确保获得最新配置格式；跨 major 版本升级时运行官方迁移 Notebook 以避免重建索引。需要留意 --force 会覆盖现有配置与提示词，升级前建议先备份。

从 CHANGELOG.md 的整体结构看，版本号演进可分为四个阶段：0.x 快速原型期（0.1.0 ~ 0.9.0）、1.0 语义化版本对齐期、2.x 功能成熟期（2.0.0 ~ 2.7.1）与 3.x 模块化重构期（3.0.0 ~ 3.1.1，当前版本）。下面按阶段逐版本展开。

二、3.x 系列：Monorepo 重构与当前稳定版本（3.0.0 ~ 3.1.1）

3.x 系列是 GraphRAG 从单一包走向模块化单仓库（monorepo）的架构转折点。当前仓库 packages/graphrag/pyproject.toml 中标注的版本为 3.1.1，且其对全部七个子包（graphrag-cache、graphrag-chunking、graphrag-common、graphrag-input、graphrag-llm、graphrag-storage、graphrag-vectors）的依赖均精确锁定为 ==3.1.1，这正是 3.0.0 "Monorepo restructure" 之后各包统一发版的直接体现。

2.1 3.1.1：当前版本，聚焦缺陷修复

3.1.1 为纯补丁版本，条目全部为 patch，包括：

• 依赖版本升级（Bump dependencies）；
• 修复 #2265：当文档向量长度与配置的 vector_size 不匹配时快速失败（fail fast）；
• 修复 #2330：为 batched() 与 chunk_text() 生成器添加显式返回类型注解；
• 修复 #2389：将 service_tier 类型放宽为 str | None，提高服务层级表示的灵活性；
• 修复 .strip 调用缺陷（#2381）；
• 修复 #2170：Blob 日志器中"释放未获取锁"的问题；
• 修复 JSONL 输入加载器：跳过空行并忽略无效 JSON 行；
• 修复一处日志缺陷。

这些条目集中反映了输入加载（JSONL 容错）、向量存储（维度校验）与遥测/日志（Blob logger）三类路径上的稳健性增强。

2.2 3.1.0：原生 CosmosTableProvider 落地

3.1.0 引入 minor 级特性：原生 CosmosTableProvider，支持命名空间分区（namespace partitioning）与事务性批量写入，并简化了 AzureCosmosStorage 的实现；同时升级 litellm 依赖。仓库中对应的实现位于 packages/graphrag-storage/graphrag_storage/tables/cosmos_table.py 与 cosmos_table_provider.py，其设计背景说明可见同目录的 COSMOS_TABLE_PROVIDER_DESIGN.md。

2.3 3.0.9 ~ 3.0.7：输入读取与向量维度治理

• 3.0.9：支持客户端 JSON 校验（client side json validation）、修复文档站断链、实现 parquet 读取器。parquet 输入读取器对应 packages/graphrag-input/graphrag_input/parquet.py。
• 3.0.8：升级 nltk 以解决 CVE-2025-14009 安全通告。
• 3.0.7：锁定 litellm 依赖版本；支持按嵌入模型重新配置向量存储维度（reconfigure vector store size by embedding model）。

2.4 3.0.6 ~ 3.0.3：流式工作流与向量存储 API 成型

• 3.0.6：extract_graph_nlp 流式化；过滤图中的"幽灵关系"（phantom relationships）。
• 3.0.5：修复 CSV 读取器；向量存储 load_documents 分批加载。
• 3.0.4：修复版本发布流程问题。
• 3.0.3 是 3.x 早期的一次小集合版本，信息密度很高：
  • 向量存储 API 新增过滤、时间戳爆炸（timestamp explosion）、insert/count/remove/update 操作，并在 VectorStoreConfig 顶层新增 vector_size 配置项；这些能力对应 packages/graphrag-vectors/graphrag_vectors/ 下的 filtering.py、timestamp.py 与 vector_store_config.py 等模块；
  • 新增 CSV 表冒烟测试；
  • 补充手动发布说明（即后来沉淀为 RELEASE.md 的内容）；
  • 前两个工作流（load_input_documents、create_base_text_units 等）加入流式支持；
  • 增加 CosmosDB 输出支持；
  • create_communities、create_final_documents、create_final_text_units、finalize_graph、generate_text_embeddings 全部工作流流式化；
  • 每个工作流写出 stats.json 统计文件。

2.5 3.0.2：TableProvider 抽象与去 NetworkX 化

3.0.2 是一次基础设施大版本：

• 新增 CSVTableProvider 与 TableProvider 抽象，为基于表的存储操作提供统一接口；
• 新增 DataReader 类，在索引工作流与查询 CLI 中统一完成带类型 DataFrame 的加载；
• InputReader 增加异步迭代器支持，并被 load_input_documents、load_update_documents 工作流采用；
• 新增 TableProvider 工厂（table provider factory）；
• 将图工具从 NetworkX 依赖中剥离，迁移到基于 DataFrame 的实现（graphrag.graphs 包），仓库中 packages/graphrag/graphrag/graphs/ 目录下的 connected_components.py、compute_degree.py、hierarchical_leiden.py、stable_lcc.py 等即为该迁移产物，配套测试见 tests/unit/graphs/；
• 文档 ID、human_readable_id 与 raw_data 的初始化从 create_final_documents 前移到 load_input_documents / load_update_documents；
• 移除对 py 3.13 的遗漏支持、移除不必要的响应格式检查（#2203）、新增内存使用剖析（profiling）。

2.6 3.0.1 与 3.0.0：Monorepo 重构里程碑

• 3.0.1：修复缺失依赖。
• 3.0.0（major）：Monorepo 重构。新增七个包：graphrag-cache、graphrag-chunking、graphrag-common、graphrag-input、graphrag-llm、graphrag-storage、graphrag-vectors，对应仓库中 packages/ 目录下的独立子目录，每个包均有自己的 pyproject.toml 与 README。变更说明要求用户运行 graphrag init --force 以新布局与新选项重新初始化配置。

这一重构同时体现在根 pyproject.toml 的 uv workspace 声明中：[tool.uv.workspace] members = ["packages/*"]，并通过 [tool.uv.sources] 将各子包标记为 { workspace = true }，实现工作区内源码级依赖解析。

三、2.x 系列：功能成熟期（2.0.0 ~ 2.7.1）

2.x 系列见证了 GraphRAG 从"工作流集合"走向"平台化能力"：自定义流水线、LiteLLM 多供应商、日志工厂、向量存储自定义等能力相继落地。

3.1 2.0.0：工作流重命名与 API 回调化

2.0.0 是 2.x 的基石，包含三项 major 变更：

• 社区（communities）增加 children 字段以避免重算；
• 重组并重命名全部工作流及其输出——当前 packages/graphrag/graphrag/index/workflows/ 下 create_base_text_units.py、create_final_documents.py、update_entities_relationships.py 等模块命名即源于此；
• API 重构为接受回调（callbacks），对应 packages/graphrag/graphrag/callbacks/ 中的 workflow_callbacks.py、llm_callbacks.py 等实现。

minor 级变更包括：LLM Manager 与工厂（支持 provider 注册）、NLP 图抽取（extract_graph_nlp）、pipeline_start / pipeline_end 回调、嵌入快照移入工作流运行器、移除配置继承/水合/环境变量自动叠加、更新输出存储结构重组。patch 级变更覆盖 NLP 抽取器缓存、嵌入配置的向量存储 id 引用、多索引查询（API 层与 CLI 均支持）、document_attribute_columns 重命名为 metadata、动态重试逻辑、chunk 前置元数据选项等。

3.2 2.1.0 ~ 2.3.0：输入格式、提示词调优与重试策略

• 2.1.0：支持 JSON 输入文件（对应 packages/graphrag-input/graphrag_input/json.py）；提示词调优客户端支持 csv-metadata 注入并更新输出文件命名约定；新增通用流水线运行状态对象（pipeline run state object，对应 packages/graphrag/graphrag/index/typing/pipeline_run_result.py 等类型定义）；配置加载时增加自定义模型类型检查。
• 2.2.0：支持 OpenAI 推理模型（reasoning models）；新增原始抽取图快照选项；提示词调优自动选择嵌入工作流加入批处理逻辑；修复基础检索（basic search）与漂移检索的 n_depth 使用。
• 2.2.1：修复社区报告提示词调优响应、图创建缺失边权、工作流化改造收尾。
• 2.3.0：移除 Dynamic Max Retries 支持并重构 CLI 的 typer 类型注解；更新 fnllm 与默认配置；LLM 输出中附带完整响应体；升级 pyarrow 至 >=17.0.0 修复 CVE-2024-52338；修复全局搜索提示词缺失格式键与 Drift Reduce 非流式调用问题。

3.3 2.4.0 ~ 2.6.0：注册式工厂与 LiteLLM 接入

• 2.4.0：支持注入自定义流水线（custom pipelines）；StorageFactory 重构为注册式（registration-based）方式（对应 packages/graphrag-storage/graphrag_storage/storage_factory.py 的工厂注册模式）；修复嵌入 tpm/rpm 限流器默认值；清理日志以符合 Python 标准。
• 2.5.0：构建索引签名增加额外上下文变量以支持自定义参数袋；包管理从 Poetry 切换到 UV——这与当前仓库使用 uv workspace + lockfile（uv.lock）的现状一致。
• 2.6.0 是 2.x 中特性最密集的版本：
  • 新增 LiteLLM chat 与 embedding 模型供应商；
  • 新增 LoggerFactory 并清理相关 API（对应 packages/graphrag/graphrag/logger/factory.py）；
  • NLP 异步模式配置、索引 API 可选输入文档、向量存储自定义化；
  • 更新 fnllm 依赖以获得 gpt-5 支持；
  • 统一 cache、storage、vector_store 工厂的注册支持；
  • generate_text_embeddings 仅在指定嵌入字段时加载对应表等修复。
• 2.7.0：init_content 中默认设置为 LiteLLM（即 graphrag init 生成的配置默认走 LiteLLM 路径）；修复 LiteLLM 的 Azure 认证 scope 问题。
• 2.7.1：锁定 pandas==2.3.3。

值得注意，breaking-changes.md 的 v3 章节解释了 LiteLLM 接入在配置层面的延续影响：v3 移除 fnllm 作为底层模型管理器后，openai_chat、azure_openai_chat、openai_embedding、azure_openai_embedding 等模型类型均变为无效，应改用 chat / embedding，并为 LiteLLM 显式指定 model_provider（如 openai、azure）。

四、1.x 系列：走向语义化版本对齐（1.0.0 ~ 1.2.0）

1.0 版本标志着项目开始"更紧密地对齐标准语义化版本实践"（见 breaking-changes.md），并引入了数据模型 v1 迁移。

• 1.0.0：communities 数据模型增加 Parent id；新增迁移 Notebook（docs/examples_notebooks/index_migration_to_v1.ipynb）；独立出社区工作流并合并子流程；工厂类清理与重构；依赖更新。该版本同时是数据模型重大调整点：统一各表的 id 与 human_readable_id、entity.name 重命名为 entity.title、document.raw_content 重命名为 document.text、rank 重命名为 combined_degree、社区表改用规范 UUID、parquet 中的嵌入列被移除转为直接写入向量存储等，均记录于 breaking-changes.md 的 v1 章节，且 v1 起向量存储成为所有检索方式的默认必需项（默认为本地 LanceDB）。
• 1.0.1：修复编码模型配置解析、错误回调异常、LLM 实例缓存单例管理、encoding_model 选项生效问题。
• 1.1.0：gleanings 抽取与编码解耦；移除 DataShaper 的第一步；移除旧流水线运行器；新检索实现为 API 新选项；CosmosDB 存储用于缓存与输出；回调模型简化；配置输入模型移除。
• 1.1.1：修复动态检索中社区层级创建缺陷；LOCAL_SEARCH_COMMUNITY_PROP 提升至 15%。
• 1.2.0：增加 Drift Reduce 响应与流式端点；新增 cosmosdb 向量存储；示例 Notebook 修复；默认速率限制；text_splitting 单元测试（对应 packages/graphrag/graphrag/index/text_splitting/ 模块）。从 CHANGELOG.md 的排版看，文件中存在两个 "1.2.0" 标题段落——前一段为上述 minor 特性集合，后一段仅一条 "Basic Rag minor fix" 的 patch 记录，属于早期变更日志的重复版本号遗留。

1.x 系列还引入了迁移 Notebook 的完整说明：v1 迁移建议重新生成 settings.yml（graphrag init），复制 LLM 设置后再运行迁移，并确保配置了向量存储，否则索引会失败（见 docs/examples_notebooks/index_migration_to_v1.ipynb 内的提示）。

五、0.x 系列：从初始发布到增量索引与 DRIFT（0.1.0 ~ 0.9.0）

0.x 区间允许破坏性变更，也是核心能力快速成型的阶段。

5.1 0.1.0 ~ 0.3.x：查询引擎、提示词调优与增量索引入口

• 0.1.0：Initial Release（初始发布）。
• 0.2.0：内容型 KNN 选择提示词调优 few-shot 示例；动态社区报告评分进入调优引擎；基于分钟的速率限制；N 参数支持；CLI 覆盖默认值旗标；语言支持进入提示词调优；local/global 检索加入 llm 参数；调整 CHUNK_SIZE、CHUNK_OVERLAP 与 GLEANINGS 默认值以减少 LLM 调用。
• 0.2.1：向量存储默认列；global 检索 map 阶段 JSON 解析错误降级为警告；修复向量配置覆盖行为；LLM 返回异常 JSON 的容错解析；社区报告缺失修复与社区上下文构建器重构；缓存向量数据库被误删的修复；编码模型进入实体/声明抽取与文本分块配置；history-tracking LLM 的缓存键计算纳入 history 参数。
• 0.2.2：local search 上下文无社区记录时的检查；Python 测试独立工作流；文档更新；4o 模型冒烟测试。
• 0.3.0：实现自动模板 API（auto templating API）与查询引擎 API；非 ASCII 字符的 JSON 文件落盘修复；查询上下文构建冒烟测试稳定化。
• 0.3.1：LLM 连通性预检（preflight check）；local/global 检索的 CLI 流式支持；社区报告生成的 float/int schema 校验；实现 Index API；数据目录推断过滤改进；nltk 升级至 3.9.1。
• 0.3.2：查询 API 响应附带上下文数据；提示词调优配置参数文档补全；neo4j 社区 Notebook；实体类型在调优时强制为 str；图抽取权重类型转换修复。
• 0.3.3：增量索引（incremental indexing）入口点加入；运行索引代码清理整理；配置加载一致性（#99、#1049）；提示词调优 API 直接运行的循环依赖修复；local search 的文本单元构建重构；支持从 Azure Blob 查询。
• 0.3.4：local search 深拷贝文本单元以避免竞态；修复摘要包含空描述的问题。
• 0.3.5：复合动词（compound verbs）与测试基建；create_final_communities、create_final_text_units、协变量动词的流程折叠；聚类随机种子修复；静态输出目录。
• 0.3.6：create_final_relationships 折叠；依赖更新与清理。

5.2 0.4.0：DRIFT 检索与增量索引双特性落地

0.4.0 是 0.x 中最具里程碑意义的一次发布，条目超过 40 条，核心包括：

• 增量索引（Incremental Indexing）：计算新增与删除输入、实体合并与值更新、文本单元更新、关系合并、协变量流程折叠、按时间段的朴素社区合并、更新输出存储结构等；当前仓库中 packages/graphrag/graphrag/index/update/ 目录下的 incremental_index.py、entities.py、relationships.py、communities.py 即该能力的实现主体；
• DRIFT 图推理查询模块：新增 DRIFT 检索 CLI 与示例 Notebook（docs/examples_notebooks/drift_search.ipynb），嵌入移入独立工作流，修复小输入集边界情况；
• 大量子流程折叠（create-final-documents、create-base-text-units、entity extraction、entity summarize 等）以精简中间输出；
• 迁移至 mkdocs 文档站点；自动生成 CLI 文档；向量存储 managed identity 支持与向后兼容补丁。

0.4.1 紧随其后：增量索引的 update CLI 入口（graphrag update）、可选协变量更新修复、空 delta 时抛出错误、文档站可视化指南上线。

5.3 0.5.0 ~ 0.9.0：动态社区选择与 fnllm 切换

• 0.5.0：数据模型调整；Parquet 作为默认发射器之一加入；提示词集中管理并全部导出以便注入；动态社区选择进入 global search；默认输出物清理。
• 0.9.0：图创建重构；修复动态社区选择下的全局搜索缺陷与问题生成；优化 Final Community Reports 计算并稳定缓存；以 fnllm 替换 llm 包；哈希从 md5 替换为 sha256/sha512（对应当前 packages/graphrag/graphrag/index/utils/hashing.py 的哈希工具）；API 更新并附演示 Notebook。

六、changelog 背后的发布机制：semversioner + uv workspace

阅读 CHANGELOG.md 时值得了解它是如何被生成和维护的，因为该文件并非手写逐条追加，而是由发布工具链自动产出。

6.1 semversioner 驱动的版本变更

根 pyproject.toml 中定义了两条关键任务：

_semversioner_changelog = "semversioner changelog > CHANGELOG.md"
semversioner_add = "semversioner add-change"

即 CHANGELOG.md 由 semversioner changelog 命令生成，贡献者提交影响 graphrag 包的改动时须运行 semversioner add-change 登记版本意图。这一要求在 DEVELOPING.md 中有明确说明：

uv run semversioner add-change -t patch -d "."

CI 侧由 scripts/semver-check.sh 强制校验：脚本比对 git diff --name-only origin/main，若 PR 触及 graphrag 代码但未更新 .semversioner/next-release 变更文档，则直接失败并提示"Run 'uv run semversioner add-change' to update the next release version"。这解释了 changelog 条目为何统一采用 major: / minor: / patch: 前缀——这些前缀正是 semversioner 的变更类型标记。

6.2 一键发布任务与跨包版本同步

根 pyproject.toml 的 [[tool.poe.tasks.release]] 序列完整定义了发布动作：

1. _semversioner_release：执行版本发布（计算并提升版本号）；
2. _semversioner_changelog：重新生成 CHANGELOG.md；
3. 八个 _semversioner_update_*_toml_version 任务：逐个将 packages/*/pyproject.toml 的 project.version 更新为 semversioner current-version 的结果；
4. _semversioner_update_workspace_dependency_versions：运行 scripts/update_workspace_dependency_versions.py；
5. _sync：uv sync --all-packages 同步工作区。

其中 update_workspace_dependency_versions.py 的实现逻辑清晰可见：先调用 uv run semversioner current-version 取得当前版本，再遍历 packages/* 下所有包的 pyproject.toml，用正则 {包名}\s*==\s*\d+\.\d+\.\d+ 定位并替换所有跨包精确版本依赖。这正是 packages/graphrag/pyproject.toml 中 graphrag-cache==3.1.1 等七条精确锁定能够始终一致的原因——monorepo 内所有包同步升版、同步发版。

6.3 手动发布流程与依赖发布顺序

RELEASE.md 说明当前 CI 自动发布工作流不可用，包必须手动发布到 PyPI，完整流程为：

1. 准备：git checkout main && git pull 后执行 semversioner 发布命令序列（与 poe release 任务等价的手动版本），并运行 uv sync --all-packages；
2. 发布 PR：创建 release/v<VERSION> 分支、打 tag、合并回 main，CI 会运行 semver、lint、测试检查；
3. 发布 PyPI：设置 UV_PUBLISH_TOKEN，uv run poe build 产出 dist/，uv publish 发布。若逐包发布（各包独立 token），必须按依赖顺序：graphrag-common → graphrag-storage → graphrag-chunking → graphrag-vectors → graphrag-input → graphrag-cache → graphrag-llm → graphrag（元包依赖其余全部，必须最后发）。该依赖拓扑与 RELEASE.md 末尾的包依赖图一致；
4. GitHub Release：基于已推送 tag 创建发布说明。

6.4 运行环境前提

版本号与依赖信息还应结合当前仓库事实理解：packages/graphrag/pyproject.toml 声明 requires-python = ">=3.11,<3.14"，classifier 覆盖 Python 3.11/3.12/3.13；构建后端为 hatchling；CLI 入口为 graphrag = "graphrag.cli.main:app"。changelog 中 2.5.0 起"Poetry -> UV"的切换与 3.0.2 中"Fix missed py 3.13"的修复，分别对应了包管理器迁移与 Python 版本支持面的演进。

七、升级实践：如何对照 changelog 安全升级

综合 CHANGELOG.md、breaking-changes.md 与迁移 Notebook，可以归纳出面向使用者的升级决策路径：

升级场景	推荐动作	依据
patch 版本（如 3.1.0 → 3.1.1）	直接升级依赖，关注安全修复（如 3.0.8 的 nltk CVE 修复）	changelog patch 条目
minor 版本	升级后运行 graphrag init --force 重新生成配置，复制原有 endpoint 等自定义	breaking-changes.md 的 TL;DR
跨 v1 / v2 / v3 大版本	先运行对应迁移 Notebook 再升级，避免重建索引；v2 → v3 需先跑 v2 迁移	迁移 Notebook 内说明
跨 3.0.0	运行 graphrag init --force 采用 monorepo 新配置布局与选项	CHANGELOG.md 3.0.0 条目

三个迁移 Notebook 及其适用对象：

• docs/examples_notebooks/index_migration_to_v1.ipynb：pre-1.0 索引 → v1 数据模型（id/human_readable_id 统一、entity.title 命名、向量存储成为必需等）；
• docs/examples_notebooks/index_migration_to_v2.ipynb：pre-2.0 索引 → v2，核心是索引表重命名（去除 DataShaper 遗留命名）；要求先完成 v1 迁移；
• docs/examples_notebooks/index_migration_to_v3.ipynb：pre-3.0 索引 → v3，核心破坏性变更是 text_units 表的 document_ids 列表列收敛为单值 document_id 列；v3 同时移除了 UMAP 生成的实体 x/y 坐标步骤，旧表中残留的 x/y 列不影响运行。

v3 的配置层破坏性变更（详见 breaking-changes.md）包括：模型类型改为 chat/embedding 并需为 LiteLLM 指定 model_provider；限流 auto 设置不再允许，需用 null 或显式 tpm/rpm；vector_store 字典收敛为根级单对象、outputs 块移除；向量存储支持按嵌入字段自定义 index_schema；仅保留 text_unit_text、entity_description、community_full_content 三个可嵌入字段；umap/embed_graph 块移除；文本分块的 groupby 能力移除。

八、changelog 对 Agent 与检索场景的使用建议

对于通过搜索引擎、Agent 或 LLM 检索本仓库的用户，CHANGELOG.md 是回答"某能力何时可用"类问题的权威索引，建议按以下路径交叉验证：

• 增量索引：0.3.3 加入入口点，0.4.0 特性完整落地，实现见 packages/graphrag/graphrag/index/update/；
• DRIFT 检索：0.4.0 引入，2.0.0 修复 n_depth 与 Azure AI Search 问题，1.2.0 增加 Drift Reduce 流式端点；
• LiteLLM：2.6.0 引入 chat/embedding 供应商，2.7.0 成为 init 默认，3.1.x 持续升级依赖；
• TableProvider/DataReader：3.0.2 引入，3.0.3 增加 CSV 冒烟测试，3.1.0 落地原生 CosmosTableProvider；
• Monorepo 与子包拆分：3.0.0，对应 packages/ 目录与 uv workspace 配置。

需要提醒的适用前提：changelog 顶部的"0.x.y 可能引入破坏性变更"注记只覆盖 0.x 区间；1.0 之后的破坏性变更以 breaking-changes.md 的数据模型/API/配置记录为准，且内部实现模块（CLI 与 API 之外）在任意版本间都可能发生不兼容变化，深度集成时应只依赖 index / query API 面。

九、小结

CHANGELOG.md 完整记录了 GraphRAG 约四十个版本的演进：0.x 快速成型（增量索引、DRIFT、动态社区选择），1.0 对齐 SemVer 并确立迁移 Notebook 机制，2.x 完成流水线平台化（自定义注入、注册式工厂、LiteLLM、日志工厂），3.0 以 monorepo 重构划分出七个可独立演进的子包，3.1.x 则聚焦输入容错、向量维度校验与 Cosmos 表存储等稳健性修复。配合 semversioner 强制的变更登记、poe release 任务的自动化版本同步，以及 scripts/semver-check.sh 的 CI 门禁，该项目形成了一条从 PR 变更登记到 CHANGELOG 自动生成、跨包版本锁定、PyPI 顺序发布与 GitHub Release 的完整发布流水线。对于使用者，最实用的两条纪律是：跨 minor 升级先 graphrag init --force，跨 major 升级先跑对应迁移 Notebook，即可在避免重建索引的前提下跟随项目演进。