企业官网建设流程全解析

WeKnora 知识图谱（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 是一个开源 LLM 知识平台，其「知识图谱」能力基于 Neo4j 实现：在文档入库阶段自动抽取实体与关系并写入图数据库，在对话阶段自动查询图谱补充上下文，实现"文档 → 图谱 → 问答"的闭环。本文以 docs/wiki/核心功能/知识图谱.md 为主线，结合仓库源码与配置文件，完整讲解启用配置、图谱生成、可视化查看与底层实现原理，帮助你掌握从环境搭建到图增强问答的全流程。

一、快速开始：三个步骤启用知识图谱

在 docs/wiki/核心功能/知识图谱.md 的快速开始中，启用知识图谱只需三步：

1. 配置环境变量

在项目根目录的.env文件中新增或修改以下变量：

NEO4J_ENABLE=true NEO4J_URI=bolt://neo4j:7687 NEO4J_USERNAME=neo4j NEO4J_PASSWORD=password

各变量的作用与取值说明：

• NEO4J_ENABLE：知识图谱唯一全局开关。必须为true才会启用图谱构建与检索逻辑。从源码看，该变量在多个关键路径上被显式判断：NewChunkExtractTask入队前检查strings.ToLower(os.Getenv("NEO4J_ENABLE")) != "true"时直接跳过（internal/application/service/extract.go）；对话管线PluginExtractEntity同样以此变量决定是否从用户问题中抽取实体（internal/application/service/chat_pipeline/extract_entity.go）。
• NEO4J_URI：Neo4j 连接 URI。默认部署单机，推荐使用bolt://（无路由开销）；若使用集群可改为neo4j://。其中neo4j为 docker-compose 服务名，使用外部实例时请替换为实际地址。
• NEO4J_USERNAME/NEO4J_PASSWORD：Neo4j 认证凭据。生产环境若使用密钥管理，请确保密码通过安全方式注入。

完整的变量说明可在 .env.example 的C2. 知识图谱（Neo4j，可选）段落中找到。值得注意的是，.env.example中还记录了兼容性信息：旧版本的环境变量ENABLE_GRAPH_RAG自 v0.1.6 起已被NEO4J_ENABLE取代，Go 主应用不再读取。

2. 启动 Neo4j 服务

docker-compose --profile neo4j up -d

该命令通过 profile 机制启动项目自带的 Neo4j 服务。从 docker-compose.yml 可以看到neo4j服务的完整定义：

• 镜像为neo4j:2025.10.1，容器名WeKnora-neo4j；
• 挂载数据卷neo4j-data:/data持久化图谱数据；
• 通过NEO4J_AUTH=${NEO4J_USERNAME:-neo4j}/${NEO4J_PASSWORD:-password}将.env中的用户名密码注入容器；
• 预置 APOC 插件（NEO4JLABS_PLUGINS=["apoc"]）并开启导入/导出能力，为批量写入图谱数据做准备；
• 映射端口7474:7474（Neo4j Browser 控制台）与7687:7687（Bolt 协议端口）；
• 属于neo4j与full两个 profile，也随完整栈一起启动。

3. 在知识库设置页面启用实体和关系提取

登录前端后，打开「知识库设置」或创建新的知识库，勾选「启用实体抽取」与「启用关系抽取」开关，并按界面提示配置所需的 LLM 模型参数。保存后，系统会在文档入库阶段自动触发实体与关系抽取任务。完整的启用流程参见 开启知识图谱功能。

二、生成图谱：文档入库即触发抽取

上传任意文档后，系统会自动提取实体和关系，并生成对应的知识图谱。这一"自动"背后是一条完整的异步任务链路，可从源码中还原其实现：

1. 切分文档为 chunk：文档解析完成后被切分为若干 chunk，每个 chunk 是图谱抽取的最小输入单元。
2. 入队抽取任务：在文档入库的后处理阶段，系统调用NewChunkExtractTask（internal/application/service/extract.go）将每个 chunk 封装成 asynq 任务入队。该函数在NEO4J_ENABLE != "true"时直接返回(false, nil)且不产生任何任务，这正是"全局开关"的语义。任务投递到专用队列QueueGraph，并设置MaxRetry(3)与Timeout(30*time.Minute)保证可靠性。
3. 执行 LLM 抽取：ChunkExtractService.Handle是任务的实际处理器（internal/application/service/extract.go）。它先检查知识库是否启用了ExtractConfig（未启用则跳过），再加载聊天模型，构造抽取器chatpipeline.NewExtractor，对 chunk 内容执行实体与关系抽取。
4. 写入图数据库：抽取结果通过s.graphEngine.AddGraph(...)以知识库/文档为命名空间写入图存储。

其中抽取器的实现位于 internal/application/service/chat_pipeline/extract_entity.go：它把配置的提示词模板（含实体/关系示例）与 chunk 内容组装成 system/user 消息，调用大模型生成 JSON，再由Formater.ParseGraph解析为结构化的GraphData（节点 + 关系）。rebuildGraph还会对抽取结果做去重、剔除自环关系、并自动补齐只出现在关系中而未出现在节点列表里的实体。

实体与关系抽取的提示词模板

仓库在 config/prompt_templates/graph_extraction.yaml 中提供了开箱即用的抽取模板，含两个默认启用的模板：

• default_extract_entities（实体抽取）：要求从文本中抽取 11 类实体——Person（人物）、Organization（组织）、Location（地点）、Product（产品）、Event（事件）、Date（日期）、Work（作品）、Concept（概念）、Resource（资源）、Category（分类）、Operation（操作）。输出严格限定为 JSON 数组，每项包含title、type，description可选但强烈建议保留；类型无法判断时宁可不抽取，避免强行归类。
• default_extract_relationships（关系抽取）：基于实体数组抽取显式关系，输出包含source、target、description、strength四字段。其中strength（关系强度）采用 5～10 分的量化标准：10表示直接创造/隶属关系（如作者-作品），9表示同一实体的不同形态（如别名），8表示紧密关联（如家人、密切合作），7表示明确但间接的关系（如作品中的人物），6表示有清晰联系的间接关联，5表示松散关联。模板还要求判断关系是否双向（如"A 是 B 的朋友"隐含反向关系），并校验关系间的一致性（避免"A 既是 B 的父亲又是 B 的兄弟"这类矛盾）。

模板中的{{language}}占位符会根据系统默认语言（由WEKNORA_LANGUAGE环境变量或请求头的Accept-Language决定）填充，保证描述文本使用与源文档一致的语言。

三、查看图谱：Neo4j Browser 可视化

登录http://localhost:7474（Neo4j Browser），使用.env中配置的用户名密码登录后，执行：

MATCH (n) RETURN n

即可查看生成的知识图谱网络。图中每个蓝色圆形节点代表一个实体，连线代表实体间的关系，点击节点可在右侧"Node properties"面板查看elementId、id、attributes等属性信息，效果即上文展示的图谱截图。

此外，开启知识图谱功能 还提供了两个补充排查命令：

MATCH (n) RETURN n LIMIT 50; -- 检查是否有新节点/关系 CALL db.schema.visualization; -- 查看图谱 schema 是否存在

四、对话自动查询图谱：实体驱动的图增强问答

启用知识图谱后，对话流程会自动查询图谱并获取相关知识。其实现路径在 internal/application/service/chat_pipeline/extract_entity.go 的PluginExtractEntity插件中：

1. 插件注册到QUERY_UNDERSTAND事件。对话开始时，若NEO4J_ENABLE未开启则直接跳过；开启后，它首先收集本次会话关联的全部知识库（含共享文档所属的知识库），批量检查哪些知识库开启了ExtractConfig.Enabled，只有启用了抽取的知识库才会进入图谱检索范围。
2. 对用户问题调用大模型抽取实体，抽取结果存入chatManage.Entity。
3. 后续检索阶段会基于这些实体去 Neo4j 中查询相关节点与关系，作为向量检索之外的补充证据，帮助模型回答需要实体间关联推理的问题。

也就是说，对话时的图谱查询是"实体驱动"的：先抽问题中的实体，再去图里找这些实体周边的关系网络，与 RAG 的向量召回形成互补。

五、配置与验证：完整启用清单

结合 docs/wiki/核心功能/开启知识图谱功能.md，完整的启用流程如下：

前置条件

• 已完成 WeKnora 后端与前端的基础部署；
• 具备可用的 Docker/Docker Compose 运行环境；
• 本地或远端可访问的 Neo4j 服务（推荐使用项目自带的 Docker Compose）。

步骤回顾

常见问题排查

• 无法连接 Neo4j：确认网络可达、NEO4J_URI与用户名密码正确，并检查 Neo4j 容器日志。
• 未生成节点：确认知识库已开启实体/关系抽取，且上传的文档已完成解析；查看后端日志中是否有抽取任务异常。
• 查询无结果：在 Neo4j 控制台执行CALL db.schema.visualization;查看 schema 是否存在，必要时重新导入文档。
• 抽取任务未执行：检查NEO4J_ENABLE是否为true——开关未开启时NewChunkExtractTask不会入队任何任务（internal/application/service/extract.go），知识文档可能一直停留在 finalizing 状态。

六、开发环境与相关资源

• 开发环境中 Neo4j 的配置与启动方式参见 开发指南；
• 知识图谱相关故障排查参见 常见问题；
• 图谱抽取提示词模板（可自定义实体类型、关系强度规则）位于 config/prompt_templates/graph_extraction.yaml；
• Neo4j 服务编排与 APOC 插件配置位于 docker-compose.yml；
• 抽取任务与图谱写入的核心实现位于 internal/application/service/extract.go 与 internal/application/service/chat_pipeline/extract_entity.go；
• 环境变量完整说明（含ENABLE_GRAPH_RAG已被NEO4J_ENABLE取代的兼容性提示）位于 .env.example。

七、结语

WeKnora 的知识图谱不是孤立功能，而是与文档解析、异步任务队列（asynq）、LLM 抽取、对话管线深度耦合的系统能力。理解NEO4J_ENABLE开关的贯穿性判断、QueueGraph专用队列、实体驱动的对话查询机制，有助于你在部署和二次开发时快速定位问题。完成以上配置后，知识图谱即可与 RAG 及 Agent 流程协同，显著提升涉及实体关联推理的问答质量。

【免费下载链接】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