KnowledgeRAG-GZHU 项目功能说明文档

项目名称：ASF-RAG（广州大学智能知识库系统） 仓库地址：https://github.com/Zhongye1/KnowledgeRAG-GZHU文档版本：v2.0 · 最后更新：2026-03-25 架构模式：前后端分离 — Vue3 SPA + FastAPI REST/SSE

一、项目概述

KnowledgeRAG-GZHU（ASF-RAG）是一套面向个人与团队知识管理的 AI 增强型知识库系统，核心能力是将用户自有文档与大语言模型（LLM）相结合，通过 RAG（检索增强生成） 技术实现对私有知识库的精准问答。

核心理念

用户私有文档 → 向量化存储 → 混合检索（BM25 + FAISS）→ LLM 生成回答 → 引用溯源

主要特性

特性	说明
🔍 混合检索	BM25 关键词 + FAISS 语义向量双路检索，RRF 融合排序
🤖 双模式问答	普通 RAG（强制检索）+ ReAct Agent（自主推理）可切换
📊 知识图谱	自动提取文档实体与关系，Sigma.js 可视化
💬 多轮对话	基于 Ollama 的本地对话，支持 RAG 增强模式
🔗 URL 内容导入	一键导入网页链接至知识库
👤 完整用户系统	JWT 认证、QQ 第三方登录、邮件密码重置
📚 三级权限体系	个人 / 共享 / 广场三种知识库模式
🏃 任务自动化	ReAct Agent 自然语言任务输入，自动拆解执行

二、技术栈

前端

分类	技术 / 库	版本
框架	Vue 3	^3.4.21
构建	Vite	^5.2.8
语言	TypeScript	^5.4.4
UI 组件库	TDesign Vue Next	latest
聊天组件	@tdesign-vue-next/chat	^0.4.3
状态管理	Pinia	^3.0.3
路由	Vue Router	^4.5.1
HTTP	Axios	^1.11.0
图形可视化	Sigma.js + Graphology	^3.0.2 / ^0.26.0
Markdown 渲染	marked + highlight.js + DOMPurify	—
样式	TailwindCSS + Less	—
打字机效果	vue-typewriter-effect	^1.0.1
ID 生成	uuid	^11.1.0

后端

分类	技术 / 库	版本
框架	FastAPI	0.116.1
ASGI	Uvicorn	0.35.0
AI 框架	LangChain + LangChain-Community	0.3.27
LLM 接入	LangChain-Ollama	0.3.6
向量数据库	FAISS (CPU)	>=1.12.0
Embedding	sentence-transformers (HuggingFace)	>=5.1.0
数据库	MySQL (PyMySQL)	1.1.1
认证	PyJWT (HS256)	2.10.1
文档解析	pdfplumber / PyPDF2 / python-docx / pytesseract / camelot-py	—
图像处理	Pillow	11.3.0
爬虫解析	BeautifulSoup4 / Requests	—
数据验证	Pydantic	2.11.7
环境变量	python-dotenv	1.1.1
桌面封装	PyQt5（可选，系统托盘）	—

三、项目结构

KnowledgeRAG-GZHU/
├── RagFrontend/                   # Vue3 前端应用
│   ├── src/
│   │   ├── main.ts                # 应用入口
│   │   ├── App.vue                # 根组件（左右布局）
│   │   ├── router/
│   │   │   └── index.ts           # 路由定义 + JWT 守卫
│   │   ├── store/
│   │   │   ├── index.ts           # Pinia 实例
│   │   │   └── modules/
│   │   │       ├── useCardData.ts # 知识库卡片 Store
│   │   │       ├── useChatImg.ts  # 聊天图片 Store
│   │   │       └── useDataUser.ts # 用户数据 Store
│   │   ├── utils/
│   │   │   ├── apiConfig.ts       # 所有 API 端点集中配置
│   │   │   ├── ASFaxios.ts        # Axios 封装（自动携带 JWT）
│   │   │   └── ollamaApi.ts       # Ollama 服务单例 API
│   │   ├── views/
│   │   │   ├── KnowledgePages/    # 知识库相关页面
│   │   │   │   ├── KnowledgeBase.vue         # 知识库列表主页
│   │   │   │   ├── KnowledgeDetail.vue       # 知识库详情页
│   │   │   │   ├── knowledge-setting-card.vue# 知识库高级设置
│   │   │   │   └── knowledge_graph_setting.vue# 图谱参数配置
│   │   │   ├── Chat.vue           # 多轮对话聊天页
│   │   │   ├── Agent.vue          # ReAct Agent 任务模式
│   │   │   ├── History.vue        # 历史记录聚合页
│   │   │   ├── FileManagement.vue # 全局文件管理
│   │   │   ├── DOC.vue            # 项目文档（Markdown 渲染）
│   │   │   ├── LogonOrRegister/   # 登录/注册落地页
│   │   │   ├── Ollama_Pages/      # Ollama 模型管理
│   │   │   ├── ACMD_serach/       # 学术文献搜索
│   │   │   └── TabHeader/         # 用户中心
│   │   └── components/
│   │       ├── SideBar.vue        # 左侧导航栏
│   │       ├── GlobalSearch.vue   # 全局搜索浮窗（Ctrl+K）
│   │       ├── chat-main-unit/    # 聊天核心组件（含引用溯源）
│   │       ├── knowledge-unit/    # 知识库卡片组件
│   │       ├── graph-unit/        # 知识图谱可视化组件
│   │       ├── canvas-point-unit/ # 粒子动画 / 动态 Logo
│   │       ├── user-primary/      # 用户信息编辑组件
│   │       └── ERS-Pages/         # 错误页面（404）
│   └── package.json
│
├── RagBackend/                    # FastAPI 后端服务
│   ├── main.py                    # 应用入口，注册路由、CORS、静态文件
│   ├── requirements.txt           # Python 依赖清单
│   ├── .env                       # 环境变量（DB_PASSWORD / JWT_SECRET / MODEL...）
│   ├── models/
│   │   └── model_config.py        # 统一模型配置（LLM/Embedding/Rerank/KG）
│   ├── document_processing/       # 文档处理模块
│   │   ├── doc_upload.py          # 分块上传（CREATE）
│   │   ├── doc_manage.py          # 文档 CRUD（UPDATE/READ/DELETE）
│   │   └── doc_list.py            # 全局文件列表 + 预览
│   ├── knowledge_base/            # 知识库管理
│   │   ├── knowledgeBASE4CURD.py  # 知识库增删改查（本地 JSON 存储）
│   │   └── knowledgebase_cover.py # 封面图床管理
│   ├── knowledge_graph/
│   │   └── generate_kg.py         # 知识图谱生成（Ollama 提取实体关系）
│   ├── RAG_M/
│   │   ├── RAG_app.py             # RAG 服务路由入口
│   │   └── src/
│   │       ├── agent/react_agent.py     # ReAct Agent 主类
│   │       ├── rag/rag_pipeline.py      # 普通 RAG 管道（强制检索）
│   │       ├── rag/hybrid_retriever.py  # BM25 + FAISS + RRF 混合检索
│   │       ├── rag/native_rag.py        # 原生 RAG（不依赖 LangChain）
│   │       ├── vectorstore/vector_store.py  # FAISS 向量存储管理（全局缓存）
│   │       └── ingestion/document_loader.py # 多格式文档加载器
│   ├── chat_units/
│   │   └── chat_management/
│   │       ├── chat_send.py       # 消息发送（调用 Ollama）
│   │       ├── chat_history_attacher.py # 历史上下文附加
│   │       ├── chat_delete.py     # 对话删除
│   │       └── chat_download.py   # 对话导出（JSON）
│   ├── ollama_management/
│   │   └── ollama_sRCP.py         # 爬取 Ollama 官网模型列表（1h 缓存）
│   ├── RAGF_User_Management/
│   │   ├── db_config.py           # MySQL 连接配置（统一入口）
│   │   ├── LogonAndLogin.py       # 用户注册 / 登录（JWT/HS256）
│   │   ├── User_settings.py       # 用户设置（头像 / 昵称 / 签名）
│   │   ├── QQ_Login.py            # QQ OAuth2.0 第三方登录
│   │   └── Reset_Password.py      # 密码重置（邮箱 SMTP 验证码）
│   ├── local-KLB-files/           # 知识库文件本地存储根目录
│   ├── metadata/                  # 文件元数据 JSON
│   └── tests/                     # 测试套件
│
└── docs/
    ├── Agent与RAG架构说明.md      # RAG/Agent 架构技术说明
    └── 项目功能说明.md            # 本文档

四、功能模块详解

4.1 知识库管理

入口路由：/knowledge核心文件：KnowledgeBase.vue · knowledgeBASE4CURD.py

知识库是整个系统的基础单元，每个知识库对应本地一个独立目录，拥有独立的文件存储、向量索引和知识图谱。

功能列表

功能	操作方式	说明
新建知识库	点击"新建知识库"按钮	输入名称后立即创建，自动生成本地存储目录
查看知识库列表	进入 `/knowledge`	卡片式展示，含名称、描述、封面、创建时间
搜索知识库	顶部搜索框实时过滤	按名称关键词即时筛选
星标置顶	点击卡片星标图标	星标知识库置顶显示，持久化到 localStorage
删除知识库	卡片悬浮删除操作	二次确认后删除，同时清理本地文件
进入详情	点击知识库卡片	跳转至 `/knowledge/knowledgeDetail/:id`

知识库数据结构

知识库元数据以 knowledge_data.json 形式存储在每个知识库目录下：

json

{
    "id": "知识库唯一ID",
    "title": "知识库名称",
    "description": "描述",
    "avatar": "头像emoji或URL",
    "cover": "封面图片路径",
    "createdTime": "2026-03-25 00:00:00"
}

4.2 文档管理与上传

入口路由：/knowledge/knowledgeDetail/:id（顶部数据集区域） 核心文件：KnowledgeDetail.vue · doc_upload.py · doc_manage.py

4.2.1 文件上传

支持多格式文档上传，采用分块上传机制保证大文件传输稳定性：

支持格式	处理方式
PDF	pdfplumber / PyPDF2 解析，可选 OCR（pytesseract）
Word (.docx)	python-docx + docx2txt 提取文本
Excel / CSV	pandas + openpyxl 表格解析
TXT / MD	直接读取
图片	pytesseract OCR 提取文字

上传流程：

前端选择文件 → 分块（每块默认 2MB）→ POST /api/upload-chunk/ → POST /api/upload-complete/ → 合并 → 元数据写入

文件大小限制：50MB
重复文件检测：MD5 哈希比对
文件类型验证：扩展名白名单校验

4.2.2 URL 内容导入

操作方式：知识库详情页 → 点击"导入链接"按钮

支持批量导入（每行一个 URL）
实时显示每条链接的导入状态（成功 / 错误）
导入成功后自动刷新文档列表
后端接口：POST /api/url-import/（待实现时给出友好提示）

4.2.3 文档管理

功能	说明
文档列表	显示名称、分块数、上传日期、切片方法、启用状态
启用/禁用	Toggle 开关控制文档是否参与 RAG 检索
删除文档	逐条或批量删除，同步清理本地文件和元数据
搜索过滤	按文件名搜索 + 按状态（全部/启用/禁用）筛选
分页展示	每页 5 条，支持翻页

4.3 RAG 智能问答

入口路由：/knowledge/knowledgeDetail/:id（检索模块 Tab） 核心文件：RAG_app.py · rag_pipeline.py · hybrid_retriever.py · native_rag.py

系统提供两种 RAG 实现，可通过 Tab 切换：

模式一：LangChain RAG（推荐）

用户提问 → 文档向量化（/ingest） → 混合检索 → OllamaLLM 生成回答 → SSE 流式返回

接口：POST /api/RAG/RAG_query

请求参数：

json

{
    "query": "你的问题",
    "docs_dir": "local-KLB-files/<知识库ID>",
    "use_hybrid": true
}

混合检索详解：

BM25 关键词检索 ──────────┐
                           ├── RRF 倒排融合排序 → Top-K 文档块 → LLM
FAISS 向量相似度检索 ──────┘

RRF 融合公式：score(d) = Σ 1 / (k + rank_i(d))（k=60）

模式二：原生 RAG（不依赖 LangChain）

先向量化：POST /api/RAG/native_ingest
再问答：POST /api/RAG/native_query
适合对 LangChain 依赖有顾虑的场景

向量化操作

步骤	接口	说明
文档向量化	`POST /api/RAG/ingest`	SSE 流式进度，嵌入模型 `all-MiniLM-L6-v2`（384维）
向量存储缓存	全局 `_vsm_cache`	同一知识库首次加载后缓存，避免重复加载 embedding 模型

AI 回答引用溯源

聊天组件（chat-main-unit.vue）对每条 AI 回答展示来源气泡：

显示引用的文件名和相关度得分
点击可展开查看具体引用片段
支持折叠/展开所有来源

4.4 ReAct Agent 任务模式

入口路由：/agent核心文件：Agent.vue · react_agent.py · RAG_app.py（/agent_query）

Agent 模式是系统最核心的 AI 能力亮点，采用 ReAct（Reasoning + Acting） 架构，让 LLM 自主决策是否需要检索知识库、检索多少次。

ReAct 推理循环

Question: 用户输入的任务

Thought: 我需要在知识库中查找相关信息
Action: search_knowledge_base
Action Input: 查询关键词
Observation: 【来源1：文档名.pdf（相关度: 0.82）】检索到的文档片段...

Thought: 我已找到足够信息
Final Answer: 根据知识库内容，...（完整回答）

前端功能

功能	说明
自然语言任务输入	大文本框输入，`Ctrl+Enter` 快捷提交
示例任务	内置 4 个示例任务卡片，点击一键填入
执行选项	可选：使用知识库（选择具体库）/ 联网搜索
步骤可视化	实时展示 Thought/Action/Observation 每一步
历史任务面板	左侧抽屉，所有历史任务持久化到 localStorage
重新执行	点击历史任务可填回输入框重新运行
清空历史	一键清除所有历史任务记录

与普通 RAG 的对比

维度	普通 RAG	ReAct Agent
检索时机	每次必执行检索	LLM 自主决定是否检索
检索次数	固定 1 次	1 到 N 次（受 `max_iterations` 限制）
适合场景	明确文档查询	复杂推理、多轮问答、混合对话
响应格式	流式文本 + 来源	推理步骤日志 + 最终回答
短路优化	无	简单对话无需检索，直接回答

接口：POST /api/RAG/agent_query（SSE 流式）

4.5 多轮对话聊天

入口路由：/chat 或 /chat/:id核心文件：Chat.vue · chat-main-unit.vue · chat_send.py

功能列表

功能	说明
会话管理	左侧会话列表，支持新建、切换、删除会话
多轮上下文	完整历史记录随每次请求携带，Ollama 理解上下文
RAG 增强模式	侧边栏底部开关，选择知识库后问答走 RAG 检索
知识库选择器	RAG 模式下下拉选择具体知识库
Ollama 设置	可配置服务器地址、超时时间、使用模型
会话持久化	会话存储到后端，`GET /api/chat/chat-documents` 加载
导出对话	`GET /api/chat/download-chat-json` 下载 JSON
Markdown 渲染	AI 回答支持代码高亮、表格、列表等完整 Markdown

对话架构

用户输入 → 前端附加历史 → POST /api/chat/send-message
         → 后端调用 Ollama /api/chat（携带 history）
         → 返回 { reply, model }
         → 前端渲染 Markdown + 引用溯源气泡

4.6 知识图谱

入口路由：知识库详情页"知识图谱"设置 + /testrange（可视化测试） 核心文件：knowledge_graph_setting.vue · graph-main.vue · generate_kg.py

生成流程

在知识库详情页开启"启用知识图谱提取"
选择图谱方法（通用 / 高级 / 领域专用）
选择实体类型（人物、组织、地点、概念等）
可选：实体标准化 / 生成社区报告 / 关系抽取
调用 POST /api/kg/process-knowledge-base，后端使用 qwen3:0.6b 提取实体和关系

可视化特性

基于 Sigma.js + Graphology 渲染力导向图
支持节点搜索（GET /api/kg/search-nodes/{kbId}）
展示图谱统计信息（节点数、边数）
支持合并多文档图谱（GET /api/kg/get-kb-merged-graph/{kbId}）

4.7 历史记录

入口路由：/history核心文件：History.vue

聚合显示所有类型的历史记录，提供统一检索入口。

记录类型

类型	图标	说明
💬 AI 对话	chat	来自聊天页的会话历史
🤖 任务	task	来自 Agent 的任务执行历史
📝 笔记	note	用户创建的笔记
🔍 搜索	search	历史搜索记录

功能特性

功能	说明
类型过滤	顶部 Tab 按类型筛选（全部/对话/任务/笔记/搜索）
关键词搜索	顶部搜索框，实时过滤标题和内容预览
日期分组	按今天 / 昨天 / 更早分组展示
复制内容	一键复制记录内容到剪贴板
删除记录	逐条删除或一键清空全部
详情抽屉	点击卡片在右侧抽屉查看完整内容

4.8 文件管理中心

入口路由：/files核心文件：FileManagement.vue · doc_list.py

功能特性

以 TDesign 表格展示所有知识库的全部文档
按知识库文件夹分 Tab 筛选
文件信息：名称、类型（彩色标签）、大小、上传时间、状态
支持文档预览（调用 /api/files/api/document/preview/）
支持文档删除
支持分页和排序
刷新按钮手动同步最新状态

4.9 用户系统

入口路由：/LogonOrRegister · /user · /user/userInfo核心文件：LogonOrRegister.vue · LogonAndLogin.py · QQ_Login.py · Reset_Password.py · User_settings.py

4.9.1 注册与登录

功能	接口	说明
邮箱注册	`POST /api/login/register`	邮箱 + 密码，SHA-256 哈希存储
邮箱登录	`POST /api/login/login`	返回 JWT Token（HS256，7 天有效）
QQ 第三方登录	`POST /api/qq/login`	OAuth2.0 流程，绑定或新建账号
JWT 验证	`GET /api/users/me`	路由守卫每次导航时调用验证

4.9.2 密码重置

发送验证码：POST /api/reset/send-code（SMTP QQ 邮箱发送 6 位数字验证码）
验证并重置：POST /api/reset/verify-code
验证码内存存储，有效期 5 分钟，最多重试 5 次

4.9.3 个人中心

功能	接口	说明
查看个人信息	`GET /api/user/GetUserData`	展示昵称、头像、签名、邮箱
更新昵称/签名	`POST /api/UpdateUserData`	表单提交
上传头像	`POST /api/UpdateUserData`	FormData 文件上传，存储到 `user_avatars/`

4.9.4 登录页特效

动态背景图（Unsplash / 知乎图床）
打字机效果标题（vue-typewriter-effect）
毛玻璃卡片 UI
登录/注册/找回密码表单切换时图片随状态变化

4.10 Ollama 模型管理

入口路由：/service核心文件：ollama_basic_pages.vue · OllamaModelList.vue · OllamaModelDownload.vue · OllamaSettings.vue · ollama_sRCP.py

Tab 功能

Tab	功能
已安装模型	列表展示本地已安装模型（名称/大小/修改时间/摘要），支持批量删除
下载模型	从 Ollama 官网爬取模型列表（1h 缓存），搜索并一键拉取，流式显示下载进度
服务设置	配置 Ollama 服务器地址（默认 `http://localhost:11434`），保存到 localStorage

场景	推荐模型	内存需求
低配环境（≤8GB）	`qwen2:0.5b`（~400MB）	~600MB
中配环境（16GB）	`qwen:7b-chat`（4.2GB）	~8GB
知识图谱提取	`qwen3:0.6b`	~800MB

4.11 学术文献搜索

入口路由：/acmd_sre核心文件：ACMD_search.vue

基于 Lens API 的学术文献搜索功能，纯前端直连。

搜索选项

选项	说明
关键词	支持复杂查询表达式
结果数量	可选 10/20/50/100
包含字段	标题 / 作者 / 年份 / 摘要可勾选
发表年份	起始到结束年份范围过滤
排序方式	相关度 / 发表时间 / 引用数

搜索结果卡片展示：标题、作者列表、发表年份、摘要（可折叠）、DOI 链接。

4.12 全局搜索

快捷键：Ctrl + K（全局任意页面） 核心文件：GlobalSearch.vue · App.vue（键盘监听）

浮窗形式弹出
同时搜索知识库名称和对话内容
支持键盘上下导航（↑ ↓）
Enter 跳转至对应页面
Esc 关闭

4.13 知识库权限与分享

入口：知识库详情页 → 设置卡片 → "权限与分享"选项卡 核心文件：knowledge-setting-card.vue

三级知识库类型

类型	图标	说明
个人 🔒	私密专属	仅自己可见
共享 👥	团队协作	设置成员角色和权限
广场 🌐	公开发现	开放给所有用户浏览

成员角色（共享模式）

角色	权限	人数限制
管理员	完全控制（增删改配置）	最多 5 名
编辑者	读写（上传/修改文档）	无限制
查看者	只读（搜索/问答）	无限制

安全策略

策略	说明
加入审批	新成员加入需管理员审核
禁止导出	禁止非管理员下载文件
添加水印	导出内容自动添加水印
只读模式	全员只读，禁止修改

分享链接

开关控制是否开启分享
选择有效期：7天 / 30天 / 永久
可设置访问密码
一键复制链接或生成二维码

五、 RAG 核心架构

整体数据流

用户输入
   │
   ├─ /RAG_query ──────────→ RAGPipeline（每次强制检索）
   │                              ├── BM25 关键词检索
   │                              ├── FAISS 向量相似度检索
   │                              └── RRF 倒排融合 → Top-K 文档
   │                                      └── OllamaLLM 生成回答（SSE 流式）
   │
   └─ /agent_query ────────→ ReActRAGAgent（LLM 自主决策）
                                   ├── LLM 推理：是否需要检索？
   　　　　　　　　                  │    ├── 需要 → search_knowledge_base Tool
   　　　　　　　　                  │    │           └── HybridRetriever（可循环）
   　　　　　　　　                  │    └── 不需要 → 直接回答
   　　　　　　　　                  └── Final Answer → SSE 逐步返回

向量存储优化

VectorStoreManager 采用全局字典缓存（_vsm_cache）：

以 docs_dir 为 key，同一知识库只加载一次 HuggingFace Embedding 模型
首次加载约 1-3 秒，后续请求毫秒级响应
避免了每次请求重复加载 embedding 模型的性能问题

文档加载支持格式

document_loader.py 支持：PDF、DOCX、TXT、MD、CSV、XLSX（通过 LangChain Unstructured 加载器）

六、后端 API 接口总览

知识库管理

Method	Path	功能
POST	`/api/create-knowledgebase/`	创建知识库
GET	`/api/get-knowledge-item/{id}/`	获取单个知识库信息
GET	`/api/documents-list/{KLB_id}/`	获取知识库文档列表
PUT	`/api/update-document-status/`	启用/禁用文档
DELETE	`/api/delete-documents/`	批量删除文档

文档上传

Method	Path	功能
POST	`/api/upload-chunk/`	分块文件上传
POST	`/api/upload-complete/`	合并分块为完整文件

文件列表管理（前缀 `/api/files`）

Method	Path	功能
GET	`/api/files/api/all-documents/`	获取所有文档列表
GET	`/api/files/api/document/preview/`	文档内容预览
DELETE	`/api/files/api/document/`	删除文档

RAG 服务（前缀 `/api/RAG`）

Method	Path	功能
POST	`/api/RAG/ingest`	文档向量化（SSE 流式进度）
POST	`/api/RAG/RAG_query`	普通 RAG 流式问答
POST	`/api/RAG/RAG_query_sync`	同步问答（测试用）
POST	`/api/RAG/agent_query`	ReAct Agent 流式问答（SSE）
POST	`/api/RAG/agent_query_sync`	ReAct Agent 同步问答
POST	`/api/RAG/native_ingest`	原生 RAG 向量化
POST	`/api/RAG/native_query`	原生 RAG 问答

知识图谱（前缀 `/api/kg`）

Method	Path	功能
POST	`/api/kg/process-all-files`	处理所有文件生成图谱
POST	`/api/kg/process-knowledge-base`	处理指定知识库
GET	`/api/kg/get-kb-merged-graph/{kbId}`	获取合并图谱数据
GET	`/api/kg/search-nodes/{kbId}`	图谱节点关键词搜索
GET	`/api/kg/graph-stats/{kbId}`	图谱节点/边统计
GET	`/api/kg/get-kb-graph-data/{kbId}/{filename}`	单文件图谱数据

对话管理（前缀 `/api/chat`）

Method	Path	功能
POST	`/api/chat/send-message`	发送消息（调用 Ollama）
GET	`/api/chat/chat-documents`	获取会话列表
POST	`/api/chat/save-session`	保存会话
DELETE	`/api/chat/delete-session`	删除会话
GET	`/api/chat/download-chat-json`	导出对话 JSON

用户系统

Method	Path	功能
POST	`/api/login/register`	用户注册（邮箱+密码）
POST	`/api/login/login`	用户登录（返回 JWT）
GET	`/api/users/me`	验证 JWT 有效性
GET	`/api/user/GetUserData`	获取用户数据
POST	`/api/UpdateUserData`	更新用户信息/头像
POST	`/api/qq/login`	QQ OAuth2.0 登录
POST	`/api/reset/send-code`	发送邮箱验证码
POST	`/api/reset/verify-code`	验证码验证并重置密码

其他

Method	Path	功能
GET	`/api/ollama-models`	Ollama 官网模型列表（1h 缓存）
GET	`/`	服务健康检查
GET	`/helloworld/`	测试端点

静态资源

路径	内容
`/static/`	知识库文件本地存储目录
`/static/covers/`	知识库封面图片
`/static/avatars/`	用户头像

七、路由与页面地图

/                          → 重定向至 /knowledge
/knowledge                 → 知识库列表主页
/knowledge/knowledgeDetail/:id → 知识库详情（文件管理 + RAG 问答 + 图谱设置）
/chat                      → 多轮对话聊天
/chat/:id                  → 指定会话 ID 的对话
/agent                     → ReAct Agent 任务模式
/history                   → 历史记录中心
/files                     → 全局文件管理
/service                   → Ollama 模型管理
/acmd_sre                  → 学术文献搜索（Lens API）
/user                      → 用户中心（Tab 容器）
  /user/userInfo           → 用户信息编辑
  /user/coming-soon/:id    → 功能即将上线占位页
/LogonOrRegister           → 登录/注册（公开路由，无需 JWT）
/DOC                       → 项目开发文档（Markdown 渲染）
/testrange                 → 知识图谱可视化测试
/404                       → 404 错误页
/:pathMatch(.*)*           → 自动重定向至 /404

路由守卫：除 /LogonOrRegister 外，所有路由在导航时自动调用 GET /api/users/me 验证 JWT，无效时清除本地 token 并重定向登录页，携带 ?redirect= 参数。

八、模型配置参考

配置项	环境变量	默认值	说明
LLM 模型	`MODEL`	`qwen:7b-chat`	用于 RAG 问答 / Agent / 聊天
Embedding 模型	`EMBEDDING_MODEL`	`sentence-transformers/all-MiniLM-L6-v2`	文档向量化，384 维
Rerank 模型	`RERANK_MODEL`	`bge-large`	可选的结果重排序
知识图谱 LLM	`KG_MODEL`	`qwen3:0.6b`	实体关系提取
Ollama 地址	`OLLAMA_BASE_URL`	`http://localhost:11434`	Ollama 服务地址
MySQL 密码	`DB_PASSWORD`	—	必须在 `.env` 中配置
MySQL 数据库	`DB_NAME`	`rag_user_db`	用户数据库名
JWT 密钥	`JWT_SECRET`	`changeme_jwt_secret`	生产环境务必修改！
SMTP 邮箱	`SMTP_USER`	—	发件邮箱（如 QQ 邮箱）
SMTP 授权码	`SMTP_PASSWORD`	—	QQ 邮箱授权码

.env 文件示例（RagBackend/.env）：

env

MODEL=qwen2:0.5b
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
KG_MODEL=qwen3:0.6b
OLLAMA_BASE_URL=http://localhost:11434

DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_mysql_password
DB_NAME=rag_user_db
DB_CHARSET=utf8mb4

JWT_SECRET=your_jwt_secret_key

SMTP_HOST=smtp.qq.com
SMTP_PORT=465
SMTP_USER=your_qq@qq.com
SMTP_PASSWORD=your_smtp_auth_code

九、本地部署指南

前置要求

依赖	版本要求	说明
Node.js	>= 18.x	前端构建
Python	>= 3.10	后端运行
MySQL	>= 8.0	用户数据存储
Ollama	latest	LLM 本地推理

后端启动

bash

# 1. 进入后端目录
cd KnowledgeRAG-GZHU/RagBackend

# 2. 创建虚拟环境
python -m venv venv
.\venv\Scripts\activate      # Windows
# source venv/bin/activate   # macOS/Linux

# 3. 安装依赖
pip install -r requirements.txt

# 4. 配置环境变量
# 复制并修改 .env 文件（必须配置 DB_PASSWORD / JWT_SECRET）

# 5. 确保 MySQL 已启动（服务名因安装而异）
# Windows: Start-Service MySQL96
# macOS: brew services start mysql

# 6. 启动服务
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

后端服务：http://localhost:8000 API 文档：http://localhost:8000/docs（Swagger UI）

前端启动

bash

# 1. 进入前端目录
cd KnowledgeRAG-GZHU/RagFrontend

# 2. 安装依赖
npm install

# 3. 开发模式运行
npm run dev
# 开发服务：http://localhost:5173

# 4. 生产构建
npm run build
# 构建产物：dist/

Ollama 配置

bash

# 安装 Ollama（https://ollama.ai）

# 拉取推荐小模型（低配环境）
ollama pull qwen2:0.5b

# 拉取知识图谱模型
ollama pull qwen3:0.6b

# 拉取标准模型（需 17GB+ 内存）
ollama pull qwen:7b-chat

# 验证
ollama list

常见问题排查

问题	原因	解决方案
后端端口 8000 被占	其他进程占用	`taskkill /PID <pid> /F`（Windows）
MySQL 连接失败	服务未启动	以管理员权限 `Start-Service MySQL96`
Ollama 500 内存不足	模型需求内存过高	先拉取 `qwen2:0.5b` 再重启后端
前端 404 API 错误	后端未启动	确认 `http://localhost:8000` 可访问
JWT 验证失败	Token 过期	清除浏览器 localStorage 重新登录
向量化失败	Embedding 模型未下载	首次运行时自动从 HuggingFace 下载，需联网

文档由 WorkBuddy 自动生成 · 2026-03-25

KnowledgeRAG-GZHU 项目功能说明文档 ​

目录 ​

一、项目概述 ​

核心理念 ​

主要特性 ​

二、技术栈 ​

前端 ​

后端 ​

三、项目结构 ​

四、功能模块详解 ​

4.1 知识库管理 ​

功能列表 ​

知识库数据结构 ​

4.2 文档管理与上传 ​

4.2.1 文件上传 ​

4.2.2 URL 内容导入 ​

4.2.3 文档管理 ​

4.3 RAG 智能问答 ​

模式一：LangChain RAG（推荐） ​

模式二：原生 RAG（不依赖 LangChain） ​

向量化操作 ​

AI 回答引用溯源 ​

4.4 ReAct Agent 任务模式 ​

ReAct 推理循环 ​

前端功能 ​

与普通 RAG 的对比 ​

4.5 多轮对话聊天 ​

功能列表 ​

对话架构 ​

4.6 知识图谱 ​

生成流程 ​

可视化特性 ​

4.7 历史记录 ​

记录类型 ​

功能特性 ​

4.8 文件管理中心 ​

功能特性 ​

4.9 用户系统 ​

4.9.1 注册与登录 ​

4.9.2 密码重置 ​

4.9.3 个人中心 ​

4.9.4 登录页特效 ​

4.10 Ollama 模型管理 ​

Tab 功能 ​

推荐模型配置 ​

4.11 学术文献搜索 ​

搜索选项 ​

4.12 全局搜索 ​

4.13 知识库权限与分享 ​

三级知识库类型 ​

成员角色（共享模式） ​

安全策略 ​

分享链接 ​

五、 RAG 核心架构 ​

整体数据流 ​

向量存储优化 ​

文档加载支持格式 ​

六、后端 API 接口总览 ​

知识库管理 ​

文档上传 ​

文件列表管理（前缀 /api/files） ​

RAG 服务（前缀 /api/RAG） ​

知识图谱（前缀 /api/kg） ​

对话管理（前缀 /api/chat） ​

用户系统 ​

其他 ​

静态资源 ​

七、路由与页面地图 ​

八、模型配置参考 ​

九、本地部署指南 ​

前置要求 ​

后端启动 ​

前端启动 ​

Ollama 配置 ​

常见问题排查 ​

KnowledgeRAG-GZHU 项目功能说明文档

目录

一、项目概述

核心理念

主要特性

二、技术栈

前端

后端

三、项目结构

四、功能模块详解

4.1 知识库管理

功能列表

知识库数据结构

4.2 文档管理与上传

4.2.1 文件上传

4.2.2 URL 内容导入

4.2.3 文档管理

4.3 RAG 智能问答

模式一：LangChain RAG（推荐）

模式二：原生 RAG（不依赖 LangChain）

向量化操作

AI 回答引用溯源

4.4 ReAct Agent 任务模式

ReAct 推理循环

前端功能

与普通 RAG 的对比

4.5 多轮对话聊天

功能列表

对话架构

4.6 知识图谱

生成流程

可视化特性

4.7 历史记录

记录类型

功能特性

4.8 文件管理中心

功能特性

4.9 用户系统

4.9.1 注册与登录

4.9.2 密码重置

4.9.3 个人中心

4.9.4 登录页特效

4.10 Ollama 模型管理

Tab 功能

推荐模型配置

4.11 学术文献搜索

搜索选项

4.12 全局搜索

4.13 知识库权限与分享

三级知识库类型

成员角色（共享模式）

安全策略

分享链接

五、 RAG 核心架构

整体数据流

向量存储优化

文档加载支持格式

六、后端 API 接口总览

知识库管理

文档上传

文件列表管理（前缀 `/api/files`）

RAG 服务（前缀 `/api/RAG`）

知识图谱（前缀 `/api/kg`）

对话管理（前缀 `/api/chat`）

用户系统

其他

静态资源

七、路由与页面地图

八、模型配置参考

九、本地部署指南

前置要求

后端启动

前端启动

Ollama 配置

常见问题排查