1. 问题概述GraphRAG 在实体提取阶段将同一实体的不同别名视为独立实体导致知识图谱中出现实体碎片化。以孙悟空为例文本A: 孙悟空大闹天宫 → 实体: 孙悟空 文本B: 孙行者三打白骨精 → 实体: 孙行者 文本C: 齐天大圣被压五行山下 → 实体: 齐天大圣最终图谱中出现三个独立节点它们之间没有任何关联。查询孙悟空做了什么时只能找到大闹天宫而三打白骨精和被压五行山下的关系链完全断裂。2. 当前 GraphRAG 的处理方式2.1 实体提取阶段源码:packages/graphrag/graphrag/index/operations/extract_graph/graph_extractor.pyLLM 从每个 text unit 中提取实体核心逻辑# graph_extractor.py → _process_result() if record_type entity and len(record_attributes) 4: entity_name clean_str(record_attributes[1].upper()) # 名称统一大写 entity_type clean_str(record_attributes[2].upper()) entity_description clean_str(record_attributes[3]) entities.append({ title: entity_name, type: entity_type, description: entity_description, source_id: source_id, })关键点 - 实体名称仅做clean_str()upper()处理去除 HTML 转义和控制字符转大写 -没有任何别名识别或归一化逻辑- LLM 提取什么名字就原样记录什么名字2.2 实体合并阶段源码:packages/graphrag/graphrag/index/operations/extract_graph/extract_graph.py多个 text unit 提取的实体通过_merge_entities()合并def _merge_entities(entity_dfs) - pd.DataFrame: all_entities pd.concat(entity_dfs, ignore_indexTrue) return ( all_entities .groupby([title, type], sortFalse) # ← 仅按 title type 分组 .agg( description(description, list), text_unit_ids(source_id, list), frequency(source_id, count), ) .reset_index() )合并策略是精确字符串匹配只有title名称和type类型完全相同的实体才会被合并。这意味着 -孙悟空和孙行者→不合并title 不同 -SUN WUKONG和MONKEY KING→不合并-TechGlobal和TG→不合并缩写 vs 全称2.3 描述摘要阶段源码:packages/graphrag/graphrag/index/operations/summarize_descriptions/合并后同一实体title 相同的多条 description 会通过 LLM 汇总为一条# description_summary_extractor.py async def __call__(self, id, descriptions): if len(descriptions) 0: result elif len(descriptions) 1: result descriptions[0] # 只有一条描述直接使用 else: result await self._summarize_descriptions(id, descriptions) # 多条描述LLM 汇总摘要 prompt 的设计Given one or more entities, and a list of descriptions, all related to the same entity or group of entities. Please concatenate all of these into a single, comprehensive description. If the provided descriptions are contradictory, please resolve the contradictions and provide a single, coherent summary.问题这个摘要步骤只处理已经被_merge_entities()合并到一起的描述。由于别名实体根本没有被合并它们的描述永远不会被放在一起摘要。2.4 关系的连带断裂源码:extract_graph.py → _merge_relationships()def _merge_relationships(relationship_dfs) - pd.DataFrame: all_relationships pd.concat(relationship_dfs, ignore_indexFalse) return ( all_relationships .groupby([source, target], sortFalse) # ← 按 source target 精确匹配 .agg( description(description, list), text_unit_ids(source_id, list), weight(weight, sum), ) .reset_index() )关系合并同样依赖精确字符串匹配。假设文本A 提取: (孙悟空) --师徒-- (唐僧) 文本B 提取: (孙行者) --师徒-- (唐僧)这两条关系不会合并因为 source 不同。最终图谱中 -孙悟空 → 唐僧(weight1) -孙行者 → 唐僧(weight1)而正确的结果应该是一条 weight2 的关系。更严重的是如果某些关系只出现在别名上下文中查询主名称时完全找不到。2.5 查询阶段的影响源码:packages/graphrag/graphrag/query/context_builder/entity_extraction.py查询时通过 embedding 向量相似度匹配实体def map_query_to_entities(query, text_embedding_vectorstore, text_embedder, ...): search_results text_embedding_vectorstore.similarity_search_by_text( textquery, text_embedderlambda t: text_embedder.embedding(input[t]).first_embedding, kk * oversample_scaler, )查询孙悟空时embedding 相似度可能匹配到孙悟空节点但孙行者和齐天大圣节点的 embedding 距离较远可能不在 top-k 结果中。即使匹配到了它们作为独立节点各自的关系子图也是割裂的。3. 根本原因总结环节当前行为问题LLM 提取按文本中出现的名称原样提取不同别名产生不同 entity title实体合并groupby([title, type])精确匹配别名实体无法合并描述摘要只摘要已合并实体的描述别名实体的描述永远分离关系合并groupby([source, target])精确匹配别名导致关系碎片化查询匹配embedding 相似度搜索别名节点可能不在 top-k 中Prompt无别名识别指令LLM 没有被引导去统一别名4. 解决方案LLM 别名发现 外部知识库确定性合并整体思路两层保障。LLM 在提取时发现别名关系覆盖大部分情况外部知识库对特别关心的实体提供确定性兜底确保关键实体不会因 LLM 不一致而遗漏。4.1 整体流程┌─────────────────────┐ │ 外部别名知识库 │ │ (JSON/DB, 人工维护) │ └──────────┬──────────┘ │ 加载 ▼ text units ──→ LLM 提取(含aliases) ──→ 别名归一化 ──→ _merge_entities ──→ 后续流程 ▲ │ ┌──────────┴──────────┐ │ 1. 外部知识库优先匹配 │ │ 2. LLM aliases 补充 │ └─────────────────────┘4.2 外部别名知识库用户维护一份别名映射文件定义特别关心的实体的 canonical name 和所有已知别名// alias_kb.json [ { canonical: 孙悟空, aliases: [孙行者, 齐天大圣, 美猴王, 斗战胜佛] }, { canonical: 猪八戒, aliases: [天蓬元帅, 猪悟能, 猪刚鬣, 呆子, 二师兄] } ]特点 -确定性知识库中的映射是硬规则不依赖 LLM 判断100% 保证合并 -可控只需覆盖业务上特别关心的实体不需要穷举所有实体 -可增量维护发现新的漏合并时加一条记录即可4.3 LLM 提取阶段增加 aliases 字段修改提取 promptprompts/index/extract_graph.py让 LLM 在提取实体时同时输出别名1. Identify all entities. For each identified entity, extract the following information: - entity_name: Name of the entity, capitalized - entity_type: One of the following types: [{entity_types}] - entity_description: Comprehensive description of the entitys attributes and activities - aliases: Other names, abbreviations, or titles for this entity found in the text. If none, leave empty. Format each entity as (entity|entity_name|entity_type|entity_description|aliases)在graph_extractor.py的_process_result()中解析 aliasesif record_type entity and len(record_attributes) 4: entity_name clean_str(record_attributes[1].upper()) entity_type clean_str(record_attributes[2].upper()) entity_description clean_str(record_attributes[3]) aliases [] if len(record_attributes) 5: aliases [clean_str(a.upper()) for a in record_attributes[4].split(,) if a.strip()] entities.append({ title: entity_name, type: entity_type, description: entity_description, source_id: source_id, aliases: aliases, })LLM 发现的别名覆盖外部知识库未收录的长尾情况。例如文本中出现猴哥指代孙悟空知识库没收录但 LLM 能识别并输出aliases: 猴哥。4.4 别名归一化两层合并在_merge_entities()之前先构建统一的 alias → canonical 映射外部知识库优先def _build_alias_map(entity_dfs, alias_kb_pathNone): 构建 alias → canonical 映射。外部知识库优先LLM aliases 补充。 alias_to_canonical {} # 第一层外部知识库确定性优先级最高 if alias_kb_path: import json with open(alias_kb_path) as f: kb_entries json.load(f) for entry in kb_entries: canonical entry[canonical].upper() for alias in entry[aliases]: alias_to_canonical[alias.upper()] canonical # 第二层LLM 提取的 aliases补充知识库未覆盖的 all_entities pd.concat(entity_dfs, ignore_indexTrue) name_freq all_entities[title].value_counts() for _, row in all_entities.iterrows(): title row[title] for alias in row.get(aliases, []): if not alias or alias title: continue # 外部知识库已有映射的不覆盖 if alias in alias_to_canonical or title in alias_to_canonical: continue # LLM aliases频率高的作为 canonical if name_freq.get(alias, 0) name_freq.get(title, 0): alias_to_canonical[title] alias else: alias_to_canonical[alias] title # 传递闭包A→B, B→C 则 A→C def resolve(name): visited set() while name in alias_to_canonical and name not in visited: visited.add(name) name alias_to_canonical[name] return name return resolve在extract_graph()中合并前统一重写实体和关系中的名称async def extract_graph(...) - tuple[pd.DataFrame, pd.DataFrame]: # ... LLM 提取 ... results await derive_from_rows(...) entity_dfs [r[0] for r in results if r] relationship_dfs [r[1] for r in results if r] # 别名归一化新增 resolve _build_alias_map(entity_dfs, alias_kb_pathconfig.alias_kb_path) for df in entity_dfs: df[title] df[title].map(resolve) for df in relationship_dfs: df[source] df[source].map(resolve) df[target] df[target].map(resolve) # 原有合并逻辑现在能正确合并别名实体 entities _merge_entities(entity_dfs) relationships _merge_relationships(relationship_dfs) relationships filter_orphan_relationships(relationships, entities) return (entities, relationships)4.5 效果对比以孙悟空为例场景当前行为改进后文本A提到孙悟空文本B提到孙行者两个独立节点关系断裂外部知识库命中统一为孙悟空文本C提到猴哥知识库未收录独立节点LLM aliases 发现归一化到孙悟空文本D提到天蓬元帅知识库有独立节点外部知识库命中统一为猪八戒文本E提到某个冷门缩写两层都没覆盖独立节点仍为独立节点发现后加入知识库即可6. 源码文件索引文件作用prompts/index/extract_graph.py实体提取 prompt 定义index/operations/extract_graph/graph_extractor.pyLLM 提取结果解析实体/关系构建index/operations/extract_graph/extract_graph.py实体/关系合并逻辑_merge_entities,_merge_relationshipsindex/operations/extract_graph/utils.py孤儿关系过滤index/operations/summarize_descriptions/描述摘要仅处理已合并实体index/workflows/extract_graph.py提取 workflow 编排index/workflows/finalize_graph.py图谱最终化degree 计算、去重index/operations/finalize_entities.py实体最终化按 title 去重query/context_builder/entity_extraction.py查询时实体匹配index/utils/string.pyclean_str()字符串清洗prompt_tune/template/extract_graph.py可调优的提取 prompt 模板