🧠 知识图谱系统 (Knowledge Graph System)

⚠️ 安全提醒

核心功能

技术架构

项目目录结构

D:/NC/
├── docker-compose.yml # Neo4j + ChromaDB 服务定义
├── .env / .env.example # 部署环境变量(example 为模板)
├── package.json # 根级 npm 脚本(concurrently 一键启动)
├── start-dev.bat / start-dev.sh # Windows / Bash 一键启动脚本
├── backend/
│ ├── .env / .env.example # 后端实际加载的 .env
│ ├── app/
│ │ ├── api/ # API 端点
│ │ │ ├── auth.py # 注册/登录/me
│ │ │ ├── documents.py # 文档上传/列表/详情/删除/切块/标签/聚类
│ │ │ ├── chat.py # RAG 对话(流式 + 非流式 + 反馈)
│ │ │ ├── graph.py # 实体/图谱查询/可视化/编辑/合并
│ │ │ ├── search.py # 语义检索
│ │ │ ├── progress.py # 文档处理进度(SSE + 历史)
│ │ │ ├── tags.py # 用户级标签聚合
│ │ │ ├── timeline.py # 时间线聚合数据
│ │ │ └── dashboard.py # 仪表盘汇总
│ │ ├── auth/ # JWT 鉴权与 bcrypt 密码哈希
│ │ ├── models/ # Pydantic 数据模型(含字段校验)
│ │ ├── services/ # 核心服务
│ │ │ ├── embedding.py # 硅基流动嵌入(限流 + JSON 缓存)
│ │ │ ├── llm.py # 百炼 / Kimi / 硅基流动 多 LLM
│ │ │ ├── chunker.py # Markdown 层级切块
│ │ │ ├── entity_extractor.py # 实体 + 关系提取(LLM 模式)
│ │ │ ├── neo4j_client.py # Neo4j 封装(含 UNWIND 批量)
│ │ │ ├── chroma_client.py # ChromaDB 封装
│ │ │ ├── bm25.py # BM25 关键词检索(per-user 索引)
│ │ │ ├── fusion.py # RRF / 加权融合
│ │ │ ├── reranker.py # 硅基流动 Rerank
│ │ │ ├── query_processor.py # 查询改写 / 变体 / 实体抽取
│ │ │ └── progress_tracker.py # SSE 进度跟踪
│ │ ├── utils/md_parser.py # Markdown 解析(markitdown 防御性封装)
│ │ ├── config.py # 配置管理(含 CORS 白名单 + 生产校验)
│ │ ├── database.py # SQLite 初始化
│ │ ├── logger.py # 统一 logging 配置
│ │ └── main.py # FastAPI 入口
│ ├── requirements.txt
│ └── Dockerfile
├── frontend/ # Vue 3 + d3 前端(学术雅致派双主题)
│ ├── src/
│ │ ├── components/
│ │ │ ├── GraphPanel.vue # 图谱核心面板(d3 力导向)
│ │ │ ├── layout/ # Layout / Sidebar
│ │ │ ├── decor/ # 装饰层(Decor / shapes)
│ │ │ └── ui/ # 通用 UI(Button/Card/Tag/Stat/Switch/...)
│ │ ├── views/
│ │ │ ├── Home.vue # 登录 / 注册
│ │ │ ├── DocumentsPage.vue # 文档列表 + 上传
│ │ │ ├── DocumentDetailPage.vue # 文档详情(标签 / 实体 / 关联)
│ │ │ ├── ClusterMapPage.vue # 2D PCA 聚类地图
│ │ │ ├── GraphPage.vue # 图谱主页(搜索 / 可视化)
│ │ │ ├── EntityDetailPage.vue # 实体详情页
│ │ │ ├── EntityTimelineAnimationPage.vue # 实体时间线动画
│ │ │ ├── DashboardPage.vue # 仪表盘
│ │ │ ├── TimelinePage.vue # 时间线
│ │ │ ├── ChatPage.vue # RAG 对话
│ │ │ └── SearchPage.vue # 语义检索
│ │ ├── composables/
│ │ │ └── useTheme.js # 亮/暗主题切换 + localStorage 持久化
│ │ ├── api/ # axios 客户端封装(auth/documents/chat/graph/...)
│ │ ├── router/index.js # 路由 + 鉴权守卫
│ │ ├── store/auth.js # Pinia auth store
│ │ ├── utils/ # categorize / timelineAnim 工具
│ │ ├── styles/variables.css # 学术雅致派设计令牌(墨蓝+琥珀双主题)
│ │ ├── App.vue
│ │ └── main.js
│ ├── index.html
│ ├── package.json
│ └── vite.config.js
└── data/ # 数据目录 (gitignore)
 ├── sqlite/ # SQLite 数据库
 ├── uploads/ # 上传的原文件
 ├── logs/ # 应用日志(RotatingFileHandler)
 ├── neo4j/ # Neo4j 数据卷
 └── chromadb/ # ChromaDB 数据卷

🚀 快速开始

1. 🐳 启动基础设施服务

docker-compose up -d

2. 🔑 配置环境变量(从模板复制,不要直接编辑 .env.example)

# 根目录(用于 IDE / 工具)
cp .env.example .env
# 后端实际加载的 .env
cd backend
cp .env.example .env

3. 📦 安装后端依赖

# 推荐:使用根目录 .venv
cd ..
.venv/Scripts/python.exe -m pip install -r backend/requirements.txt
.venv/Scripts/python.exe -m spacy download zh_core_web_sm

4. ▶️ 运行后端服务

cd backend
../.venv/Scripts/python.exe -m uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload

# Windows
start-dev.bat
# Bash (Git Bash / WSL)
./start-dev.sh
# 或:根目录 npm 脚本(需要先 npm install)
npm run dev # concurrently 同时启动前后端
npm run backend # 仅后端
npm run frontend # 仅前端

5. 🎨 安装并运行前端

cd frontend
npm install
npm run dev

🔌 API 接口设计

🔐 认证 /api/auth

📄 文档 /api/documents

🔍 检索 /api/search

🕸️ 图谱 /api/graph

💬 对话 /api/chat

🏷️ 标签 /api/tags

🕒 时间线 /api/timeline

📊 仪表盘 /api/dashboard

⏳ 进度 /api/progress

💓 健康检查

🌊 数据流架构

📤 文档上传流程

PDF/Word/TXT/MD → markitdown → Markdown → 层级解析 → 语义切块
 → 硅基流动 Embedding (Qwen3-Embedding-8B) → ChromaDB 存储
 → Neo4j 实体关系提取 (BM25 索引同步) → SSE 进度推送

🔍 检索对话流程

用户 Query → 查询改写 (LLM) → Embedding
 → 向量检索 + BM25 → RRF 融合 → Qwen3-Reranker
 → 上下文扩展 (前/后 chunk) → Neo4j 图谱关联
 → 构建 Prompt → Kimi / 百炼 LLM → 流式返回结果

🧬 核心数据模型

📦 Chunk 数据结构

{
 "chunk_id": "uuid",
 "document_id": "doc_uuid",
 "user_id": "user_uuid",
 "content": "文本内容",
 "hierarchy": {
 "level": 2, # 标题层级
 "path": ["标题1", "标题1.1"], # 层级路径
 "parent_id": "parent_chunk_id"
 },
 "position": {
 "start_line": 10,
 "end_line": 25,
 "prev_chunk_id": "uuid", # 前一块(用于上下文召回)
 "next_chunk_id": "uuid" # 后一块
 }
}

🕸️ Neo4j 图谱数据模型

// 节点
(:User {user_id, username, password_hash, created_at})
(:Document {doc_id, title, user_id, file_path, created_at})
(:Chunk {chunk_id, content, embedding_id, user_id, position, hierarchy_path})
(:Entity {name, type, description, user_id}) // 从文本提取
// 关系
(:User)-[:OWNS]->(:Document)
(:Document)-[:CONTAINS]->(:Chunk)
(:Chunk)-[:NEXT]->(:Chunk) // 文档顺序
(:Chunk)-[:MENTIONS]->(:Entity) // 提及实体
(:Entity)-[:RELATES_TO {relation_type}]->(:Entity) // 实体关系

🔐 安全配置

⚙️ 配置说明

🛠️ 环境变量

🧭 前端路由总览

🛠️ 开发指南

📋 环境要求

🧪 测试

# 冒烟测试(无需 Neo4j/ChromaDB)
cd backend
../.venv/Scripts/python.exe -c "
from app.main import app
from fastapi.testclient import TestClient
c = TestClient(app)
assert c.get('/health').status_code == 200
print('OK')
"
# 集成测试(需启动 Docker 服务)
docker-compose up -d
../.venv/Scripts/python.exe -m pytest backend/tests

🐳 Docker 部署

# 构建并运行所有服务
docker-compose up -d
# 单独构建后端镜像
cd backend
docker build -t kg-backend .
docker run -p 8001:8001 --env-file .env kg-backend

📦 关键依赖版本

# backend
fastapi==0.115.0
uvicorn==0.32.0
python-jose[cryptography]==3.3.0
bcrypt==3.2.2
python-multipart==0.0.17
neo4j==6.1.0
chromadb==0.4.18
numpy==1.26.4
httpx==0.27.0
aiofiles==24.1.0
markitdown==0.0.1a3
markdown-it-py==3.0.0
jieba==0.42.1
spacy==3.7.5
rank-bm25==0.2.2
python-dotenv==1.0.0
pydantic==2.9.2
pydantic-settings==2.6.0
sqlalchemy==2.0.36
aiosqlite==0.20.0
# dev / test only
pytest==8.3.3
pytest-asyncio==0.24.0

# frontend
vue ^3.5.24
vue-router ^4.6.3
pinia ^2.3.1
d3 ^7.9.0
axios ^1.7.9
@tanstack/vue-virtual ^3.13.28
vite ^7.2.4

📌 注意事项

📜 许可证