# kg-platform

**Repository Path**: hyperchain/kg-platform

## Basic Information

- **Project Name**: kg-platform
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-17
- **Last Updated**: 2026-06-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能知识图谱平台 —— 系统使用手册指南

| 文档版本 | v1.0 |
| --- | --- |
| 适用系统 | kg-platform（Spring Boot 3.3.6 + AgentScope 2.x + Neo4j） |
| 编写日期 | 2026-06-17 |
| 读者对象 | 平台使用者、知识工程师、运维人员 |

> 本手册介绍平台的部署、配置、操作流程与常见问题。配套文档：《需求设计文档.md》《详细设计文档.md》。

---

## 一、平台简介

智能知识图谱平台让你**无需编写抽取规则**，仅通过上传文档即可自动构建知识图谱：

```
上传文档(PDF/Word/Excel) → 大模型自动抽取实体与关系 → 存入图数据库 → 可视化展示 / 智能问答
```

核心能力：
- 📄 **多格式文档**：PDF、Word(docx)、Excel(xlsx/xls)、CSV、TXT、Markdown
- 🤖 **大模型抽取**：基于 AgentScope + 通义千问，自动识别实体、关系、属性
- 🧩 **本体约束**：可定义实体/关系类型，约束抽取结果
- 🔍 **图谱可视化**：交互式力导向图，支持搜索、下钻、缩放
- 💬 **自然语言问答**：用大白话查询图谱内容

---

## 二、环境准备与部署

### 2.1 运行依赖

| 依赖 | 是否必需 | 说明 |
| --- | --- | --- |
| JDK 17+ | ✅ 必需 | 运行 Java 应用 |
| 通义千问 API Key | ⭐ 强烈建议 | 抽取与问答功能依赖；未配置时这两项不可用，其余功能正常 |
| Neo4j 5.x | ⭐ 强烈建议 | 存储图谱；未启动时可上传/抽取，但无法入库与可视化 |
| MySQL 8.x | 可选 | 生产环境元数据库；默认用内置 H2，开箱即用 |

### 2.2 启动 Neo4j（Docker 方式）

```bash
docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/neo4j12345 \
  neo4j:5
```
- 浏览器访问 `http://localhost:7474` 可查看 Neo4j 自带控制台。
- 账号 `neo4j`，密码 `neo4j12345`（与下方配置一致）。

### 2.3 获取通义千问 API Key

1. 登录阿里云百炼/DashScope 控制台。
2. 创建 API Key（形如 `sk-xxxxxxxx`）。
3. 作为环境变量 `DASHSCOPE_API_KEY` 提供给应用。

### 2.4 启动平台

```bash
cd kg-platform

# 1) 编译打包
mvn clean package -DskipTests

# 2) 运行（通过环境变量注入密钥与 Neo4j 密码）
export DASHSCOPE_API_KEY=sk-你的密钥
export NEO4J_PWD=neo4j12345
java -jar target/kg-platform-1.0.0.jar
```

启动成功后日志出现：`Started KgPlatformApplication`。

### 2.5 访问入口

| 入口 | 地址 |
| --- | --- |
| 🖥️ 操作主界面 | http://localhost:8080/index.html |
| 📘 接口文档(Swagger) | http://localhost:8080/swagger-ui.html |

> 修改端口：启动追加 `--server.port=8081`。

### 2.6 关键配置项（`application.yml`）

```yaml
llm:
  dashscope:
    api-key: ${DASHSCOPE_API_KEY:}     # 大模型密钥
    default-model: qwen-max            # 默认模型
    timeout-seconds: 120               # 单次调用超时

extraction:
  chunk-size: 1600                     # 文本分块大小
  chunk-overlap: 200                   # 块重叠
  auto-commit: false                   # 是否抽取后自动入库
  storage-dir: ./data/uploads          # 上传文件存储目录

spring:
  neo4j:
    uri: bolt://localhost:7687         # Neo4j 地址
```

---

## 三、操作流程（界面使用）

打开 `http://localhost:8080/index.html`，左侧为操作区，右侧为图谱画布。整体按 **1→2→3→4** 步骤进行。

### 步骤 1 · 创建并选择项目

> 一个"项目"= 一套独立的本体 + 一张独立的知识图谱（数据互相隔离）。

1. 在「1. 项目」面板的输入框填写项目名称（如 `公司组织图谱`），点击 **创建**。
2. 创建后会出现在下拉框中，下拉选择即为"当前项目"，后续所有操作都作用于它。
3. 面板下方显示该项目的 `节点 / 关系` 统计。

### 步骤 2 · 上传文档

1. 在「2. 上传文档」点击选择文件，可一次选多个（支持 PDF/Word/Excel/CSV/TXT/MD）。
2. 点击 **上传**。上传成功后下方列出文档清单与数量。
3. 单文件建议 ≤ 50MB。

💡 **不同格式的处理方式**
- **Excel/CSV**：自动识别表头，每一行转成"列名:值"的描述供模型理解。适合人员名单、组织清单等结构化数据。
- **Word/PDF**：提取正文段落与内嵌表格，按语义切分成块。适合公司简介、合同、报告等。

### 步骤 3 · 抽取构建图谱

1. 在「3. 抽取构建图谱」面板：
   - 勾选 **自动入库**：抽取完成后直接写入图谱（推荐先体验时勾选）。
   - 不勾选：抽取结果先进入"候选/待审核"，确认后再入库。
   - 选择模型：`qwen-max`（效果好）或 `qwen-plus`（更快更省）。
2. 点击 **开始抽取（全部文档）**。
3. 下方日志区实时显示进度：
   ```
   状态: PARSING   进度: 5%      ← 解析文档
   状态: EXTRACTING 进度: 45%    ← 大模型抽取
   状态: MERGING   进度: 80%     ← 实体消歧融合
   完成! {"entities":23,"relations":15}
   ```
4. 若未勾选自动入库，完成后点击 **审核入库** 按钮写入 Neo4j。

⏱️ **耗时说明**：抽取速度取决于文档量与大模型响应，单个普通文档通常数十秒。

### 步骤 4 · 查看图谱 / 检索 / 问答

**加载图谱**
- 点击 **加载整张图谱**：在右侧画布渲染当前项目的知识图谱。
- 不同颜色代表不同实体类型（人物=蓝、机构=绿、地点=黄、产品=橙、事件=紫）。

**画布交互**
- 滚轮缩放、拖拽空白处平移、拖动节点调整布局。
- **点击任一节点**：以它为中心展开 2 跳邻居子图（下钻）。

**实体检索**
- 在搜索框输入实体名（如 `张三`），点击 **搜索**，自动定位并展开该实体的子图。

**自然语言问答**
- 在问答框输入问题（如 `谁任职于阿里巴巴？`），点击 **提问**。
- 系统将问题转为图查询并返回答案，同时展示所用的 Cypher 语句与结果出处。

---

## 四、进阶：本体（Schema）管理

本体用于约束"抽取出哪些类型的实体和关系"，开启后大模型只抽取符合定义的内容，质量更高。

平台内置**默认本体**（人物/机构/地点/产品/事件 + 任职于/位于/隶属于/相关），开箱即用。
如需自定义，可通过接口保存：

```bash
curl -X PUT http://localhost:8080/api/projects/1/ontology \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "金融图谱本体",
    "def": {
      "entityTypes": [
        {"name":"Person","label":"人物"},
        {"name":"Company","label":"公司"}
      ],
      "relationTypes": [
        {"name":"LEGAL_REP","label":"法人代表","head":"Person","tail":"Company"}
      ]
    }
  }'
```

保存后，对该项目发起的抽取会按新本体约束输出。

---

## 五、进阶：人工审核

当抽取时**不勾选自动入库**，结果进入候选区，可先审查再入库。

1. 查看候选数据：
   ```
   GET /api/extractions/{任务ID}/candidates
   ```
   返回候选实体、候选关系，每条带置信度与来源块。
2. 确认无误后入库：
   ```
   POST /api/extractions/{任务ID}/commit
   ```

> 适用于对图谱质量要求高、需要人把关的正式场景。

---

## 六、接口速查（供二次开发 / 自动化）

统一返回格式：`{ "code": 0, "msg": "ok", "data": ... }`，`code != 0` 表示出错。

| 功能 | 方法 | 路径 |
| --- | --- | --- |
| 创建项目 | POST | `/api/projects` |
| 项目列表 | GET | `/api/projects` |
| 上传文档 | POST | `/api/projects/{pid}/documents`（multipart 字段名 `files`） |
| 文档列表 | GET | `/api/projects/{pid}/documents` |
| 保存本体 | PUT | `/api/projects/{pid}/ontology` |
| 发起抽取 | POST | `/api/projects/{pid}/extractions` |
| 任务状态 | GET | `/api/extractions/{id}` |
| 候选数据 | GET | `/api/extractions/{id}/candidates` |
| 审核入库 | POST | `/api/extractions/{id}/commit` |
| 子图查询 | GET | `/api/projects/{pid}/graph?eid=&depth=2` |
| 实体检索 | GET | `/api/projects/{pid}/entities/search?q=关键字` |
| 图谱统计 | GET | `/api/projects/{pid}/stats` |
| 智能问答 | POST | `/api/projects/{pid}/qa` |

**示例：命令行完整跑通一次**
```bash
# 1. 建项目
curl -X POST localhost:8080/api/projects -H 'Content-Type: application/json' -d '{"name":"demo"}'

# 2. 上传文档（项目ID=1）
curl -X POST localhost:8080/api/projects/1/documents -F 'files=@/path/简介.pdf'

# 3. 发起抽取并自动入库
curl -X POST localhost:8080/api/projects/1/extractions \
  -H 'Content-Type: application/json' \
  -d '{"docIds":[1],"mode":"ONTOLOGY_GUIDED","model":"qwen-max","autoCommit":true}'

# 4. 查询进度（返回的 taskId 假设为 1）
curl localhost:8080/api/extractions/1

# 5. 查看图谱
curl 'localhost:8080/api/projects/1/graph?limit=100'
```

---

## 七、常见问题（FAQ）

**Q1：抽取一直失败 / 没有任何实体？**
- 检查是否配置了 `DASHSCOPE_API_KEY`，密钥是否有效、有额度。
- 查看应用日志是否有"未配置 DASHSCOPE_API_KEY"或模型调用报错。

**Q2：图谱加载为空 / 统计一直是 0？**
- 确认 Neo4j 已启动且 `application.yml` 中地址、密码正确。
- 确认抽取任务已"完成"且已入库（自动入库勾选，或手动点了"审核入库"）。
- 启动日志若出现"Neo4j 约束初始化失败"，说明未连上 Neo4j。

**Q3：上传文档提示"不支持的文件类型"？**
- 仅支持 pdf / docx / doc / xlsx / xls / csv / txt / md，请检查扩展名。

**Q4：扫描版 PDF（图片型）抽不到内容？**
- 当前仅解析文本型 PDF，扫描件需先 OCR（后续可扩展）。

**Q5：问答返回"未能生成有效查询"或答非所问？**
- 问题尽量具体、贴合图谱中已有的实体与关系类型。
- 图谱数据越完整，问答效果越好。

**Q6：抽取结果有错误/幻觉怎么办？**
- 启用本体约束（默认已启用）可减少越界类型。
- 关闭"自动入库"，走人工审核，剔除低质量结果后再入库。

**Q7：数据存在哪里？**
- 上传的原始文件：`./data/uploads/` 目录。
- 文档/任务/候选等元数据：H2（默认内存库，重启清空）或 MySQL（生产持久化）。
- 图谱（实体与关系）：Neo4j。
- ⚠️ 默认 H2 为内存库，**重启后元数据清空**；正式使用请切换 MySQL。

**Q8：如何切换到 MySQL 持久化？**
- 修改 `application.yml` 的 `spring.datasource` 为 MySQL 连接，
  在 MySQL 中执行项目内 `schema.sql` 建表，重启即可。

---

## 八、使用建议与最佳实践

1. **先小后大**：首次使用先传 1~2 个小文档，跑通"上传→抽取→可视化"全流程再批量处理。
2. **结构化优先**：人员名单、组织架构等用 Excel 上传，抽取又快又准、成本更低。
3. **按主题分项目**：不同业务/领域建独立项目，避免实体混淆、便于隔离管理。
4. **质量优先选 qwen-max，速度/成本优先选 qwen-plus。**
5. **重要数据走审核**：正式入库的图谱关闭自动入库，人工确认后再提交。
6. **善用下钻**：从一个关键实体出发逐层点击展开，比一次加载整张大图更清晰。

---

> 如需扩展 JWT 登录鉴权、抽取实时进度推送(SSE)、并发抽取、向量检索增强问答等能力，参见《详细设计文档.md》对应章节。