---
title: 开启知识图谱功能
tags: [核心功能, 知识图谱, Neo4j, 配置]
aliases: [知识图谱配置, KnowledgeGraphSetup]
source: 开启知识图谱功能.md
---

# 开启知识图谱功能

本文档介绍如何在 WeKnora 中启用并验证知识图谱（Neo4j）功能，帮助你完成从环境准备到前端配置的全流程。

## 前置条件

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

> 快速入门参见 [知识图谱](知识图谱.md)

## 步骤一：配置环境变量

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

```
NEO4J_ENABLE=true
NEO4J_URI=bolt://neo4j:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_strong_password
# 可选：NEO4J_DATABASE=neo4j
```

说明：

- `NEO4J_ENABLE` 设置为 `true` 才会启用知识图谱相关逻辑
- `NEO4J_URI` 中的 `neo4j` 为 docker-compose 服务名，如使用外部实例请替换为实际地址
- 如果生产环境使用密钥管理，请确保密码通过安全方式注入

## 步骤二：启动 Neo4j 服务

项目附带 Neo4j 组件，可直接用以下命令启动：

```bash
docker-compose --profile neo4j up -d
```

常见验证命令：

```bash
docker ps | grep neo4j
```

> 开发环境中 Neo4j 的启动方式参见 [开发指南](../开发部署/开发指南.md)

## 步骤三：重启 WeKnora 服务

为了让新的环境变量生效，重启后端与前端：

```bash
make stop && make start
# 或者
docker compose up -d --build
```

确保后端日志中出现 `neo4j` 初始化成功的提示。

## 步骤四：在前端启用实体/关系抽取

1. 登录 WeKnora 前端管理页面
2. 打开「知识库设置」或创建新的知识库
3. 勾选「启用实体抽取」与「启用关系抽取」开关
4. 根据界面提示补充所需的 LLM、回调或模型参数（若有）

保存后，系统会在文档入库阶段自动触发实体与关系抽取任务。

## 步骤五：验证知识图谱

### 方式一：Neo4j 控制台

1. 访问 `http://localhost:7474`（或对应主机/端口）
2. 使用 `.env` 中的账号密码登录
3. 执行 `MATCH (n) RETURN n LIMIT 50;` 检查是否有新节点/关系

### 方式二：WeKnora 界面

在知识库或对话页面中上传文档后，前端应展示图谱可视化入口；对话时系统会自动根据意图查询图谱并返回补充信息。

## 常见问题排查

- **无法连接 Neo4j**：确认网络可达、`NEO4J_URI` 与用户名密码正确，并检查 Neo4j 容器日志
- **未生成节点**：确认知识库已开启实体/关系抽取，且上传的文档已完成解析；查看后端日志中是否有抽取任务异常
- **查询无结果**：尝试在 Neo4j 控制台执行 `CALL db.schema.visualization;` 查看 schema 是否存在，必要时重新导入文档

> 更多排查建议参见 [常见问题](../运维排障/常见问题.md)

完成以上步骤后，知识图谱功能即成功启用，可结合 RAG 及 Agent 流程提升问答质量。

---

## 反向链接

- [Home](../Home.md) — Wiki 首页导航
- [知识图谱](知识图谱.md) — 知识图谱快速入门（本页的精简版）
- [开发指南](../开发部署/开发指南.md) — 开发环境中 Neo4j 的启动与配置
- [常见问题](../运维排障/常见问题.md) — 图谱功能相关的故障排查