WeKnora 知识图谱GraphRAG功能深度解析从 Neo4j 配置到实体关系抽取与图谱增强检索【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora导读本文基于 WeKnora 开源仓库的官方特性文档系统讲解知识图谱Knowledge Graph / GraphRAG功能的完整技术脉络如何通过两级开关启用该能力、文档入库时如何借助 LLM 抽取实体与关系并写入 Neo4j、问答时又如何沿实体 → 关联片段补充关系上下文与向量检索、关键词检索协同工作。读完本文你将掌握 WeKnora 知识图谱的配置方法、构建与检索两条核心链路、Neo4j 存储层的底层实现以及 Agent 模式下query_knowledge_graph工具的使用方式。知识图谱在文档入库时提取实体与关系并在问答时沿关联关系检索更多相关片段可与向量和关键词检索共同使用为回答补充关系上下文。该功能适用于人物、组织、产品或条款之间关系较多的资料启用后会增加入库阶段的模型调用并需要部署 Neo4j。一、功能概述与适用场景WeKnora 的知识图谱功能解决的是传统 RAG 的关系盲区问题向量检索擅长语义相似匹配关键词检索擅长字面命中但两者都无法直接回答A 与 B 是什么关系谁影响了谁这类需要跨片段串联的问题。图谱功能在文档入库时将散落在各个 chunk 中的实体与关系结构化抽取出来存入图数据库查询阶段再从用户问题中抽取实体、沿图的一跳邻居关系召回关联片段从而为生成答案补充关系上下文。适用场景包括人物关系密集的资料如传记、组织架构、合作网络产品与条款关联如技术文档中多个产品版本、API 模块之间的依赖与从属关系跨文档聚合同一实体出现在多个知识库/多个文件中时通过chunks属性实现一实体多出处的聚合召回。需要明确的是启用图谱是有成本的入库阶段每个文本 chunk 都会触发一次额外的 LLM 抽取调用源码注释称之为管线中最昂贵的增强扇出同时必须部署 Neo4j 数据库依赖 APOC 插件。二、开启配置两级开关图谱功能需要两级开关同时满足才会真正生效——全局的 Neo4j 环境变量开关 知识库级别的索引策略开关。2.1 全局开关Neo4j 环境变量NEO4J_ENABLE是知识图谱的唯一全局开关。需要注意版本演进docker-compose.yml注释明确说明ENABLE_GRAPH_RAG自 v0.1.6 起已被NEO4J_ENABLE取代Go 主应用不再读取旧变量。名称类型默认值说明NEO4J_ENABLEstring空关闭置为true启用图谱container.go 的initNeo4jClient与任务入队、检索管线都会检查它NEO4J_URIstringbolt://neo4j:7687Neo4j 连接地址Bolt 协议NEO4J_USERNAMEstringneo4j用户名NEO4J_PASSWORDstringpassword密码源码层面的两个关键实现细节启动重试与降级initNeo4jClient在NEO4J_ENABLE ! true时直接返回nildriver不报错此时Neo4jRepository的所有方法降级为 no-op仅打印NOT SUPPORT RETRIEVE GRAPH日志启用时最多重试 30 次每次间隔 2s创建 driver 并调用VerifyAuthentication验证连接。状态上报GET /system信息接口通过 system.go 的getGraphDatabaseEngine()报告当前图数据库引擎为Neo4j或Not Enabled便于运维确认开关是否真正生效。docker-compose 的neo4j服务预装 APOC 插件NEO4JLABS_PLUGINS[apoc]图谱写入依赖apoc.merge.node/apoc.merge.relationship删除依赖apoc.periodic.iterate。2.2 知识库级开关IndexingStrategy ExtractConfig全局开关之外每个知识库还需在索引策略中打开图谱抽取。核心判断逻辑位于 internal/types/knowledgebase.go// IsGraphEnabled checks if knowledge graph extraction is enabled. // Requires both the IndexingStrategy flag and a valid ExtractConfig. func (kb *KnowledgeBase) IsGraphEnabled() bool { return kb ! nil kb.IndexingStrategy.GraphEnabled kb.ExtractConfig ! nil kb.ExtractConfig.Enabled }两个组成部分IndexingStrategy.GraphEnabledinternal/types/indexing_strategy.go知识库索引策略中的图谱开关字段名为graph_enabled默认false旧字段ExtractConfig.Enabled会在读取时向IndexingStrategy.GraphEnabled单向同步legacy sync保证存量配置平滑迁移。ExtractConfiginternal/types/knowledgebase.go承载抽取的 few-shot 配置各字段含义如下名称类型默认值说明enabledboolfalse是否启用抽取textstring空few-shot 示例原文tags[]stringnil关系类型标签集合nodes[]*GraphNodenil示例实体节点name / attributesrelations[]*GraphRelationnil示例关系node1 / node2 / typecustom_instructionsstring空领域自定义抽取指令追加进系统提示结构化输出协议仍由系统控制2.3 配置向导辅助 API为帮助用户快速搭建ExtractConfiginitialization.go路由注册见 router.go提供了三个辅助接口POST /initialization/extract/text-relationExtractTextRelations对一段文本≤5000 字符按选定标签试跑关系抽取用于预览效果POST /initialization/extract/fabri-textFabriText让 LLM 生成示例文本辅助填充text字段POST /initialization/extract/fabri-tagFabriTag让 LLM 推荐标签辅助填充tags字段。三、实体关系抽取流程图谱构建3.1 触发与任务编排文档解析完成后knowledge_post_process.go 在增强扇出阶段对每个文本 chunk 计数启用图谱时graphChunkCount len(textChunks)并调用 extract.go 的NewChunkExtractTask逐 chunk 入队func NewChunkExtractTask(...) (bool, error) { if strings.ToLower(os.Getenv(NEO4J_ENABLE)) ! true { logger.Warn(ctx, NEO4J is not enabled, skip chunk extract task) return false, nil } ... task : asynq.NewTask(types.TypeChunkExtract, payload, asynq.Queue(types.QueueGraph), asynq.MaxRetry(3), asynq.Timeout(30*time.Minute)) ... }关键工程细节任务走独立的 asynqQueueGraph队列与向量化、摘要等队列隔离每个任务MaxRetry3、Timeout30min即单 chunk 的抽取有三次重试机会超时上限半小时当NEO4J_ENABLE未开启时入队函数返回(false, nil)调用方必须释放已占用的pending_subtasks_count计数否则父知识会永远停留在 finalizing 状态源码注释明确警告了这一死锁风险被取消、被删除或被新解析尝试取代attemptSuperseded的任务会跳过执行并释放父任务的子任务计数每个 chunk 一次 LLM 调用受模型级后台并发限流limiter约束避免打爆模型服务。3.2 抽取执行ChunkExtractService.Handleinternal/application/service/extract.go中ChunkExtractService.Handle的执行流程分为五步加载上下文加载 chunk、知识库与文件级ProcessOverrides用ResolveProcessConfig求出生效的ExtractConfig未启用则跳过该 chunk。组装结构化提示系统协议部分来自config.ExtractManager.ExtractGraph即 config.yaml 的extract.extract_graph它是一个分步指令——先实体抽取 属性丰富再关系抽取与验证关系类型只能从指定列表%s中选择随后叠加知识库的custom_instructions、tags与ExtractConfig的 few-shot 示例Text/Nodes/Relations。调用模型并解析chatpipeline.NewExtractor(chatModel, template).Extract(ctx, chunk.Content)调用 Chat 模型参数为temperature 0.3、max_tokens 4096、关闭 thinking随后由Formater.ParseGraph解析为types.GraphDatainternal/types/extract_graph.gotype GraphNode struct { Name string json:name,omitempty Chunks []string json:chunks,omitempty Attributes []string json:attributes,omitempty } type GraphRelation struct { Node1 string json:node1,omitempty Node2 string json:node2,omitempty Type string json:type,omitempty }回填与写入为每个节点回填node.Chunks []string{chunk.ID}随后调用graphEngine.AddGraph(ctx, NameSpace{KnowledgeBase, Knowledge}, ...)写入 Neo4j——这样每个实体都记录了它出自哪个 chunk为查询阶段的关联召回奠定基础。可观测性全程由 SpanTracker 追踪产生postprocess.graph.chunk[i]子 span记录 nodes/relations 数量与样例便于在 Langfuse 等追踪平台排障。3.3 存储后端Neo4j 仓库实现internal/application/repository/retriever/neo4j/repository.go 实现interfaces.RetrieveGraphRepositoryAddGraph/DelGraph/SearchNode三个方法几个关键设计命名空间即标签NameSpace{KnowledgeBase, Knowledge}映射为节点标签ENTITYkb_id、ENTITYknowledge_id连字符替换为下划线即实体在库中被双层标签命名空间隔离不同知识库/不同文件的同名实体可共存节点属性含name实体名、kgknowledge_id、attributes属性列表、chunks来源 chunk ID 列表幂等写入用 APOC 做合并写入同名实体的chunks取并集重复解析同一文档不会产生重复节点UNWIND $data AS row CALL apoc.merge.node(row.labels, {name: row.name, kg: row.knowledge_id}, row.props, {}) YIELD node SET node.chunks apoc.coll.union(node.chunks, row.chunks)级联删除删除知识/知识库时knowledge_delete.go、knowledgebase.go调用DelGraph用apoc.periodic.iterate按 1000 批并行删除边与点保证大图删除时不会拖垮事务。四、检索时的图谱增强GraphRAG图谱的价值体现在查询阶段。传统聊天管线internal/application/service/chat_pipeline中挂载了两个插件完成查询实体抽取 图谱关联召回。4.1 PluginExtractEntity从用户查询中抽取实体extract_entity.go挂在QUERY_UNDERSTAND事件上。NEO4J_ENABLEtrue时它先筛选出ExtractConfig.Enabled的知识库存入chatManage.EntityKBIDs/EntityKnowledge再使用ExtractManager.ExtractEntity模板config.yaml 的extract.extract_entity包含分析逻辑连接 → 提取关键实体 → 按关联紧密程度排序三步指令 Chat 模型从用户查询中抽取实体名列表存入chatManage.Entity。4.2 PluginSearchEntity图谱关联召回search_entity.go挂在ENTITY_SEARCH事件上执行实体 → 关联 chunk的补充召回对每个启用图谱的知识库/文件并行调用graphRepo.SearchNode底层 Cypher 用n.name CONTAINS nodeText做实体名的模糊匹配并返回实体的一跳邻居与关系MATCH (n)-[r]-(m) WHERE ANY(...) RETURN n, r, m合并为chatManage.GraphResultfilterSeenChunk取出图谱节点携带的chunks去掉向量检索已命中的部分避免重复召回从chunkRepo拉取对应原文并转换为SearchResult并入候选集。最终图谱召回的片段与向量、关键词结果一起进入重排与生成阶段为回答提供关系上下文。4.3 Agent 模式的 query_knowledge_graph 工具Agent 模式下WeKnora 提供query_knowledge_graph工具internal/agent/tools/query_knowledge_graph.go校验各知识库是否配置了图谱ExtractConfig.Nodes/Relations非空见Execute中 L177 附近的判定并发对多个知识库执行检索按 chunk 去重排序输出中附带各库的图谱配置状态graph_configs字段包含实体类型 / 关系类型清单由summarizeGraphConfig/uniqueSortedNodeNames等辅助函数生成未配置图谱的知识库回落为普通混合检索结果保证 Agent 链路不中断。五、构建与查询流程图5.1 构建流程5.2 查询流程六、可视化与相关实现边界关于图谱可视化需要厘清几个容易混淆的实现Mermaid 图生成internal/application/service/graph.go 的graphBuilder是types.GraphBuilder接口的内存版实现LLM 抽实体 → 抽关系 → 按 PMI×0.6 Strength×0.4 计算关系权重并归一到 1-10 → 计算实体度数 → 构建 chunk 关联图其generateKnowledgeGraphDiagram用 DFS 找连通分量并输出 Mermaidgraph TD子图高频实体高亮、强度 7 的关系用粗箭头。注意NewGraphBuilder目前没有被容器装配调用仓库内无其他引用属于独立/遗留的图构建与可视化实现生成的 Mermaid 图输出到日志。prompt 模板config/prompt_templates/graph_extraction.yaml 提供default_extract_entities等模板含实体类型枚举 Person/Organization/Location/... 与 JSON 输出协议经 internal/config/config.go 的extract_entities_prompt_id/extract_relationships_prompt_id解析进Conversation.ExtractEntitiesPrompt/ExtractRelationshipsPrompt供上述内存版graphBuilder使用生产异步抽取路径使用的是 config.yaml 中extract.extract_graph/extract.extract_entity模板ExtractManagerConfig两者不要混淆。对外 API知识图谱本身没有专门的可视化 REST 端点query_knowledge_graph工具的结构化输出graph_configs、结果列表供 Agent 前端渲染。GET /wiki/graphwikiHandler.GetGraph是 Wiki 功能自己的图接口与本文的实体关系图谱无关。七、排查要点速查现象排查方向入库后图谱无数据确认两级开关NEO4J_ENABLEtrue且知识库IndexingStrategy.GraphEnabledExtractConfig.Enabled同时为真检查GET /system返回的图引擎是否Neo4j文档卡在 finalizing检查任务是否因NEO4J_ENABLE未开启而未被入队父任务的pending_subtasks_count计数是否被正确释放查询不返回图谱结果确认查询实体是否能被name CONTAINS模糊命中确认该知识库ExtractConfig.Enabled为真Neo4j 连接失败启动日志查看initNeo4jClient的重试输出确认NEO4J_URI/账号密码正确、APOC 插件已启用结语WeKnora 的知识图谱功能是一套完整的构建-存储-检索闭环以两级开关精确控制启用范围以独立 asynq 队列承载高成本的 LLM 抽取以 Neo4j APOC 实现幂等的图写入与批量删除最终在查询阶段通过实体抽取与一跳邻居召回为 RAG 答案补充关系上下文。对于人物、组织、产品、条款间关系密集的知识库这套能力与向量、关键词检索形成了互补的三角检索格局。相关源码可继续深入存储层 neo4j/repository.go、任务编排 extract.go、容器装配 container.go、Agent 工具 query_knowledge_graph.go。【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考