GraphRAG核心概念解析：TextUnit、Entity、Community与Claim如何协同

1. 为什么我说 GraphRAG 最难啃的部分不是检索，而是这四兄弟

不少朋友第一次接触 GraphRAG，是从它的名字开始的：把图结构引入 RAG，然后用图去辅助检索。听起来很美好，实际动手搭一版 demo 也不难，随便找个开源仓库，配置好 API Key，跑一遍 indexing 流程，很快就能看到图谱可视化结果。但真到你要用它解决业务问题、调优检索效果、甚至自己改底层逻辑的时候，就会撞上一堵墙：链路里那些概念到底是什么意思？TextUnit 和 Chunk 有什么区别？Entity 为什么要带 description？Community 是社区还是聚类？Claim 是不是自己维护一个三元组就行？

这些概念不是名词解释题，它们直接决定了索引的存储结构、检索的匹配粒度、以及最终回答的质量。我最早踩过的坑，就是没分清 TextUnit 和 Chunk 的关系，结果把检索粒度全搞错了，生成答案时上下文又碎又重。后来把四个核心概念啃透，才真正体会到 GraphRAG 不是“把文本塞进图数据库”这么简单，而是一套从文档到语义社区的完整抽象体系。

这篇文章不打算讲怎么安装、怎么调 API，那些文档里都有。我想做的是把TextUnit、Entity、Community、Claim这四个最核心的概念拆开揉碎，结合我实际项目里的配置和踩坑经验，讲清楚它们各自是什么、为什么要存在、彼此怎么协作，以及你在落地时最容易出问题的地方。适合已经开始上手 GraphRAG、但对索引内部机制还比较模糊的读者；如果你还没跑通基础流程，建议先拿官方默认配置跑一遍 demo，再回来看这篇，会顺畅很多。

2. 先建立全局视角：四个概念到底在解决什么问题

2.1 图谱不是目的，而是“可导航的索引”

要理解这四个概念，先得把 GraphRAG 的底层逻辑捋一遍。传统向量 RAG 的思路是：把文档切成固定大小的文本块，向量化后塞进向量库，检索时用余弦相似度找 top-k 块。它的优点是好懂、好实现，缺点是没有全局结构——算法只知道“这段文本和问题长得很像”，不知道这段文本在整篇文档里处于什么位置、和其他内容有什么关联。GraphRAG 要解决的就是这个问题：它不把文本当作一堆孤立的碎片，而是先提取出文档里的实体和关系，构建一张语义网络，然后在这张网络上做检索和推理。

这里有个容易被误解的点：GraphRAG 不是用图数据库替代向量库，而是在向量库之上叠加了图谱的导航能力。最终检索时，你仍然可能用到向量相似度，但检索的入口和路径是基于图谱结构的。所以四个核心概念，本质上是在回答一个问题：怎么把非结构化的文档，转换成一个既能细粒度匹配、又能全局推理的结构化索引？

2.2 四个概念在索引链路里的位置

我用一张表把这四个概念在 GraphRAG 索引流程中的角色先亮出来，后面再逐一展开：

这四个概念的顺序，也是 GraphRAG 索引流程的大致顺序：先切 TextUnit，再从 TextUnit 里抽 Entity 和 Claim，最后基于 Entity 的图结构跑 Community Detection。理解这个顺序，你会更容易记住每个概念的生命周期和归属关系。

3. TextUnit：它不是简单按字数切的 Chunk

3.1 TextUnit 到底是什么

TextUnit 是 GraphRAG 索引流程里的第一层抽象，也是很多初学者最容易混淆的概念。乍一看，TextUnit 有点像传统 RAG 里的 Chunk——都是一段文本。但两者在 GraphRAG 里的定位完全不同。

TextUnit 的定义是：用于提取实体和关系的分析单元。它不是为了“给向量检索提供切块”而存在的，而是为了“在合适的上下文粒度下做信息抽取”而存在的。GraphRAG 对 TextUnit 的切分策略，是尽量保留语义完整性，而不是机械地按固定 token 数截断。官方实现里提供了基于 Token 的切分策略，但会尝试按分隔符、段落等做智能分段，尽量避免把一句话或一个完整语义切到两个单元里。

我记得第一次看 GraphRAG 配置时，看到CHUNK_SIZE和CHUNK_OVERLAP这两个参数，下意识以为它就是 Chunk 的 size 和 overlap。后来读了源码才明白，这里的 Chunk 对应的是 TextUnit 的前身，也就是“候选文本块”。GraphRAG 从文档里先把文本按段落、结构拆成若干候选块，再把这些候选块进一步整理成 TextUnit，用于后续的实体抽取。换句话说，Chunk 是 TextUnit 的原材料，TextUnit 是 Chunk 的语义化产物。

3.2 为什么不能直接拿 Chunk 当 TextUnit

这里有个非常关键的细节：TextUnit 不是单纯从 Chunk 改名来的，它需要满足几个约束：

• 关联唯一文档：一个 TextUnit 必须能追溯回它来自哪份文档、哪个段落，这在后面的可解释性和引用溯源里非常重要。
• 抽取粒度适中：TextUnit 太大，实体抽取时容易引入过多噪声；TextUnit 太小，实体关系的上下文不足，抽取质量会明显下降。GraphRAG 默认的 TextUnit 目标大小通常在 200 到 300 个 token 之间，这是一个在抽取质量和上下文覆盖之间权衡过的值。
• 与 Entity 和 Claim 关联：TextUnit 是 Entity 和 Claim 的宿主，GraphRAG 在索引时会记录“这个实体是从哪个 TextUnit 里抽出来的”，这为后续的检索和证据引用提供了基础。

如果你只是简单地把一个 1000 字的段落粗暴切成连续的 200 token 小块，你会发现两个问题：一是实体抽取时，一个实体的完整描述被截断了；二是 Claim 提取时，事件的前因后果散落在不同的 TextUnit 里，导致抽取结果残缺。我当时在实验里把 TextUnit 目标值调大到 500 token，结果实体抽取质量确实上升了一点，但社区检测的响应时间慢了近一倍——这就是粒度权衡的直接体现。

3.3 TextUnit 的检索作用：从“找相似块”到“找关联块”

TextUnit 在后端检索中也是最终的“证据页面”。当 GraphRAG 定位到某个实体后，它会把该实体所在的 TextUnit 取出来，作为上下文喂给 LLM 生成答案。这意味着，TextUnit 并不是一个一次性的中间产物，它承担了地图上的“网格”功能：Entity/Claim 标记了网格里的具体坐标，检索时按图索骥找到网格，再提取网格里的原始文本用于回答。

我在实项目里发现一个经验：调整 TextUnit 大小，比调整向量检索的 top-k 更能影响答案的“连贯性”。TextUnit 太碎时，生成器拿到的上下文是七零八落的，虽然每个块都相关，但连起来读就很别扭；TextUnit 稍大一点，上下文完整度更高，但风险是无关内容增多、主题漂移。建议你在自己的数据集上多做几个档位的对比实验，别只盯着默认参数。

提示：GraphRAG 的 TextUnit 切分方案不是字符级硬切，而是基于 token 并尝试保留语义边界。实际使用时，数据结构化程度越高（比如 Markdown 标题分区清晰、JSON 字段结构明确），TextUnit 的切分效果越好。建议在索引前先把文档做结构归一化，而不是指望切分器自带语义理解能力。

4. Entity：图谱里的节点，也是检索的“路标”

4.1 Entity 的构成：不只是名字那么简单

Entity 是 GraphRAG 图谱里的节点，它代表的是一份文档中“反复出现且有分析价值的事物”——人、组织、地点、产品、概念、事件，都可以是 Entity。但 GraphRAG 的 Entity 不是简单地在文本里做命名实体识别（NER）然后存个名字完事，它包含三个核心要素：

• Name：实体的标准名称。GraphRAG 在抽取时会做实体归一化（Entity Resolution），把“苹果”“Apple Inc.”“苹果公司”这类指代同一实体的不同表达聚合到同一个标准名称下。归一化做得好不好，直接影响图谱的质量和后续检索的准确度。
• Type：实体的类型。比如“人物”“公司”“技术”“地点”等。类型不是必填项，但有了类型，社区检测和过滤检索时会有更适合的语义锚点，尤其在做“只看公司相关的社区”这类场景时很有用。
• Description：实体的文本描述。这是 GraphRAG 区别于传统知识图谱的关键之一。它不是直接从文档里复制一句原文，而是 LLM 在抽取时基于该实体在多个 TextUnit 中的出现，综合生成的短描述。描述其实是实体在检索阶段的“匹配指纹”——搜索时先基于描述判断实体是否与问题相关，如果相关，再去展开它所在的社区。

4.2 Entity 之间的关系：边是怎么来的

只有节点没有边，图是不存在的。GraphRAG 在抽取 Entity 的同时，也会抽取实体之间的关系（Relationship），并把关系也存为图上的边。关系通常包含：

• Source Entity和Target Entity：关系的两端
• Description：这段关系在文档里是如何体现的，比如“A 是 B 的供应商”
• Weight：关系强度，通常和“这段关系在所有 TextUnit 中被提及的次数”正相关

边的权重非常有用。社区检测算法（后面会讲）本质上是在利用边的连接关系做聚类，权重高的边会把实体拉得更近。我自己的经验是：在配置实体抽取提示词时，一定要让 LLM 明确输出关系的证据文本片段（也就是描述），而不是只输出“A-B”这种干巴巴的二元组。有了证据，边的可信度会大幅提高，后面排查错误关系时也能追到源头。

4.3 Entity 检索：先找到“路标”，再决定往哪走

在 GraphRAG 的检索阶段（Local Search 和 Global Search），Entity 承担的是“路标”职责。Local Search 的典型路径是：

1. 基于问题文本，先生成一组候选实体（通常通过向量相似度匹配实体的 name 和 description）。
2. 在图上沿着这些实体扩展一跳或两跳，拿到邻居实体和相关 TextUnit/Claim。
3. 把上述所有信息组装成上下文，交给 LLM 生成答案。

所以 Entity 描述的质量，决定了“路标”上写的字清不清楚。如果你的实体描述都是“某某相关”“与项目有关”这种泛泛表述，检索时肯定匹配不准。我踩过的一个比较深的坑，是在某些低质量数据集上，LLM 把大量实体都抽成了“无类型”或描述只有一句话的残缺节点，结果社区检测倒是跑出来了，但检索时相关性极差。排查后发现，问题是原文本身信息密度太低，连 LLM 都抽不出像样的描述。这种情况下要做的是预处理清洗，而不是盲目调提示词。

5. Community：把实体按“社交关系”聚成圈子

5.1 Community Detection 为什么有用

如果 Entity 是节点、Relationship 是边，那么 Community 就是在整个图上跑社区发现算法后得到的子图划分。为什么要做社区划分？直接在整个图上做推理不行吗？

不行。真实文档集抽取出的图谱，实体数量少则几百，多则数万，直接把整图塞给 LLM 做推理，上下文会爆。社区检测的价值在于：在保持语义凝聚力的前提下，把海量实体划分成多个可独立处理的组。每个社区内部，实体之间的关联比对外更紧密；社区报告就相当于这个“圈子”的浓缩摘要。

GraphRAG 使用的是层级化社区检测（Hierarchical Leiden），意味着社区不是一层，而是多层：最底层是紧密的小团体，往上逐层合并成更大的社区，直到整个图成为一个社区。每一层都会生成对应粒度的社区报告，这为后续的 Global Search 提供了不同粒度级别的“全局视图”。

5.2 社区报告里到底有什么

社区报告（Community Report）是 Community 概念最具代表性的产物。它本质上是一份 Markdown 格式的摘要，由 LLM 基于该社区内所有实体、关系和 TextUnit 汇总生成，通常包含：

• 概要：这个社区覆盖了什么主题
• 关键实体：最重要的实体有哪些，分别承担什么角色
• 重要关系：实体间的关键依赖、协作或冲突关系
• 隐含洞察：文本中没有直接写出来、但综合分析后能推断出的信息

为什么社区报告要在索引阶段生成？因为这样做可以把复杂的全局推理变成“先定位相关社区 → 直接读取报告 → 生成答案”的轻量化过程。Global Search 的 Map-Reduce 流程里，Map 阶段其实是并行的“读报告”，每份报告对应一个社区；Reduce 阶段才是汇总。换句话说，你花在索引期的“重计算”，换来了查询期的“轻检索”。

5.3 Community 的粒度陷阱：不是越细越好

社区粒度是调优 GraphRAG 时一个很隐蔽的参数。主要的控制参数是层级数和社区规模阈值。层级太多，顶层社区报告过于抽象，丢失细节；层级太少，底层社区报告数量巨大，Global Search 的 Map 阶段会非常耗时。

我在实践中有个体会：如果你需要的是“全局概览型”答案，比如“这份文档集整体讨论了哪些主题方向”，那么高层社区的帮助特别大；但如果你是做“局部事实问答”，比如“某个特定产品的上线时间”，高层社区报告反而帮不上忙，这时 Local Search 直接走实体+TextUnit 的路线更精准。所以不要试图只用 Community 解决所有问题，GraphRAG 的设计本来就是 Local 和 Global 各管一段。

注意：社区检测的结果高度依赖实体抽取质量。如果实体名归一化做得不好，“苹果”和“苹果公司”被当成两个孤立节点，社区的联通性就会变差，层级化聚类的效果也会跟着打折扣。所以我在项目里会先用一批语料跑一遍实体抽取，人工抽样检查归一化效果，再决定要不要调整解析提示词。

6. Claim：给实体挂上“可验证的事实卡片”

6.1 Claim 的定位：从实体到事件

前三者解决的是“有什么实体、实体之间什么关系、它们聚成什么圈子”，而 Claim 解决的是“文档里针对某个实体，提出了哪些具体的陈述”。举个例子：实体是“某产品”，关系是“A 公司负责开发该产品”，这还不够细；Claim 要捕捉的是类似“某产品在 2024 年 6 月发布了 2.0 版本，该版本支持离线模式”这样的具体事件描述。

Claim 并不是必须开启的功能。GraphRAG 的配置里，claim_extraction_enabled默认可能是关闭的，开启后会在索引阶段额外跑一轮抽取。Claim 的价值在于精确事实查询和证据溯源：当你问“该产品什么时候支持了离线模式”时，检索系统可以直接命中那条 Claim，而不是靠社区报告里的概述去猜。很多业务场景（比如审计、合规、客服知识库）对事实准确性要求很高，Claim 几乎是刚需。

6.2 Claim 的字段拆解

一条 Claim 通常包含以下关键字段：

这里要特别强调Description和Source TextUnit ID的关系。Description 是 LLM 基于源文本生成的浓缩版声明，Source TextUnit ID 则指向原始证据。我在项目中遇到过一种情况：LLM 生成的 Claim 描述非常流畅，但和原文细节有出入（比如把“计划开发”描述成了“已开发”）。如果没有 Source TextUnit ID，这种错误几乎无法定位。开了溯源之后，一查原文就知道是抽取幻觉还是真实内容。

6.3 Claim 和 Entity/Community 的协作方式

Claim 在检索流程中的作用比较灵活。在 Local Search 中，它既可以被当作实体旁的“附属证据”（因为 Claim 有 Subject 实体），也可以作为独立的候选证据片段。举个例子：

用户问：某公司在 2023 年有没有推出过针对中小企业的计划？

检索过程大致是：先匹配到“某公司”这一实体，再沿该实体的边找相关社区和 TextUnit，同时在 Claim 表里筛选 Subject 包含“某公司”、时间在 2023 年左右的记录。如果某条 Claim 明确写了“在 2023 年推出中小企业扶持计划”，那它就是这条回答的关键证据。

在 Community 层面，Claim 并不直接参与社区检测，因为社区检测是基于实体关系图的。但社区报告的生成提示词通常会包含该社区内的关键 Claim 信息，这样高层报告就不会只停留在“谁和谁有关系”的层面，而是能带上“具体发生了什么事”的陈述。换句话说，Claim 是给社区报告补充“事件浓度”的重要来源。

7. 从索引到检索：四兄弟在真实链路里的协作实况

7.1 一次 Local Search 的完整路径

把四个概念各自讲完之后，我强烈建议你把自己代入一次真实的检索场景，走一遍完整链路。我用一个简化版的流程来展示：

1. 用户提交问题：“某产品 2.0 版本发布时间是什么时候？”
2. 系统对问题做实体识别或者基于向量匹配，锁定候选实体某产品 2.0。
3. 找到该实体的 description，确认它确实是用户问的那个产品。
4. 沿实体关联扩展，拿到它的邻居实体（比如“某公司”“某团队”）以及关联的 TextUnit。
5. 在 Claim 表里筛选 Subject 为某产品 2.0的记录，找时间相关的声明。
6. 把所有信息组装成一个上下文块，交给 LLM 生成答案，并附上引用来源（TextUnit ID / Claim ID）。

这里你会发现，TextUnit 是“最原始的文本基础”，Entity 是“入口路标”，Claim 是“精确事件卡片”，而 Community 在这条链路里没有直接出场——它主要在 Global Search 或跨主题推理时才发挥作用。所以不是所有 Query 都需要四兄弟全员出动。

7.2 Global Search 的路径与 Local 的差异

Global Search 面对的是“全局性问题”，比如“这份语料库里有哪些技术趋势？”这种问题在 Local Search 里很难回答，因为相关实体可能散布在全图各处。Global 的流程是：

1. 把所有社区报告按层级组织好。
2. 在 Map 阶段，并行让 LLM 基于每个社区报告生成对问题的部分回答（或相关度评分）。
3. 在 Reduce 阶段，把所有部分回答汇总成最终答案。

在这个流程里，Community 是绝对主角，Entity 和 Claim 不会直接参与；TextUnit 的存在感也比较弱。这正好印证了我的观点：GraphRAG 的两个检索模式本质上是两套链路，它们对四个概念的依赖权重是完全不同的。官方把 Local 和 Global 分开，不是没有道理的。实际业务里，如果你想两者通吃，可能要同时维护好两套索引路径的质量。

7.3 我的配置建议：先取舍，再调参

基于上述链路理解，我在业务项目里收敛了一套配置策略：

• 如果目标问答大多是“具体的、事实性的”问题：优先保证 Entity 抽取质量和 Claim 覆盖度，TextUnit 用默认值即可，Community 层级不需要调太深。
• 如果目标问答是“全局分析型”的：优先保证 Entity 归一化质量和社区报告的信息密度，Claim 可以不开（省算力），TextUnit 的大小也要适可而止。
• 如果混合型：建议开启 Claim，但用抽样的方式评估它对索引时间的增量。Claim 抽取在语料大时非常耗时，有时占比能到整体索引时间的三分之一甚至更多，这笔账要提前算清楚。

8. 实战调优：让四兄弟在项目里更听话

8.1 实体抽取调优的实操笔记

实体抽取质量几乎决定了整个图谱的根基。我调优时主要关注三个点：

• 提示词里的输出格式约束：让 LLM 严格输出 JSON 数组，字段名固定。这个看起来基础，但很多开源实现里，默认提示词强调的是“覆盖全面”，字段定义反而不够严格。字段一乱，后面的实体归并就全是坑。
• 实体归并级别：GraphRAG 配置里有多个 entity resolution 相关的选项，比如是否启用描述相似度归并。建议先做小样本测试，观察“同一个实体在不同 TextUnit 里被抽出来的描述是否措辞一致”，如果不一致，说明 L 的抽取提示词需要更强的归一化指引。
• 类型体系的稳定性：LLM 抽类型时如果不给枚举约束，会出现“人物”“People”“Human”三种类型并存的情况，非常难治理。我建议在提示词中明确给出允许的类型列表，比如：人物、组织、地点、产品、技术、事件、其他。类型稳定后，后面做社区过滤和检索过滤都会省心很多。

8.2 社区层级的调优心得

社区层级调优，最关键的不是层级数，而是你“最终要读的报告粒度”。GraphRAG 生成社区报告后，不同层级的报告长度和抽象程度差异很大。我的经验是：

• 先建立一个直觉：层级 0 是最小的社区，报告偏具体；层级越高，报告越抽象、社区数量越少。
• 在做 Global Search 时，如果发现答案太概括、缺失关键细节，考虑把 Map 阶段的目标层级往下调一档（比如从层级 2 调到层级 1）。
• 在做 Local Search 时，如果发现扩展实体后带出的社区全是零碎的、信息重叠度太高，则可能是社区检测粒度过细，试着抬高聚合阈值。

这个调优过程没有统一答案，务必在多个 query 上做横向对比，只看一两个例子没法收敛。

8.3 Claim 抽取的取舍清单

Claim 抽取的取舍，核心是在“精确度”和“成本”之间做平衡。我的建议清单如下：

• 语料内有大量明确事件（时间、主体、动作、对象）时，值得开启。
• 语料以描述性、观点性内容为主时，Claim 收益较低，可以先关掉。
• 需要在线服务响应时间极低的场景，建议只对重要实体子集做 Claim 抽取，而不是全量抽取。
• 无论开不开，都要保留 Source TextUnit ID 的关联关系，否则 Claim 的可信度会大幅降低。

9. 我在实际项目中踩过的几个坑

9.1 直接复用默认配置的教训

我第一次跑业务语料时，图省事全部用了默认配置。结果遇到一个典型问题：语料是混合语言（中英混杂），默认抽取提示词对中文实体的归并效果较差，同一个公司名被拆成了四五个实体。后来我在抽取提示词里加了中文归一化示例，并开启了描述相似度归并，节点数直接下降了大约 40%。这个比例相当可观，也让我意识到默认配置只能保证 demo 效果，不能保证业务效果。

9.2 TextUnit 过大导致的社区质量崩塌

有一段时间，我为了提高实体抽取的上下文质量，把 TextUnit 目标大小调得很大。效果是实体描述确实更饱满了，但因为 TextUnit 变大，每个实体的出现文本跨度也变大，图谱里的关系边变得又粗又乱，社区检测结果明显退化——很多本应分开的社区被粘成一团。这个经历告诉我，TextUnit 的粒度不是孤立调参，它和实体抽取质量、社区检测是强耦合的，改一个必然影响另外几个。

9.3 关于社区报告的过度依赖

还有一种问题出在理念上：我当时觉得社区报告这么完美，直接拿它回答所有问题不就行了？结果用户问一个特别具体的事实，Global Search 的回答往往方向正确但数字和日期对不上。后来我意识到，社区报告是“压缩摘要”，它天然会丢掉细粒度事实；一旦包含数字，摘要很可能概括不精确。所以如果你业务里有高频的精确事实查询，务必给 Local Search 保留足够权重，甚至可以考虑基于图谱结构混合两种检索模式，而不是一刀切。

10. 视情况而定：什么时候四个概念可以“缺斤少两”

写到这里，我想再补充一点：GraphRAG 四个核心概念不是每个场景都必须全量启用。如果你做的是小规模个人知识库（几千个 TextUnit 以内），不开 Claim、社区层级调浅，完全可行；如果你是一个千万级语料的审计系统，那 Claim 和审计溯源几乎是必选项。理解每个概念的取舍边界，其实比记住概念定义更重要。

从我的实践来看，GraphRAG 最值得投入时间去学的地方，不是怎么调 API 参数，而是理解它为什么把索引设计成这个样子：TextUnit 让抽取有边界，Entity 让检索有路标，Community 让全局推理有抓手，Claim 让事实有凭证。四个概念相互配合，才形成了一套比向量 RAG 更立体、更可解释的语义索引体系。

最后再分享一个我觉得比较实用的小技巧：在正式投入业务前，用一小批代表性语料跑一遍索引，然后到图数据库里直接看导出的 GraphML 或 JSON 文件，检查实体归并、关系描述和社区划分是否合理。这比任何指标监控都直观。等你见过足够多“坏图谱”长什么样，再回头调配置，心里就有谱了。这套东西调优起来确实有些磨人，但磨出来的索引质量，会在每一次检索和回答里成倍地还给你。