1. 项目简介

MinKnowledge 是一个基于 RAG (检索增强生成) 技术的智能知识库问答系统。它允许用户构建自定义的 AI 应用，集成多种大模型，并通过上传文档构建私有知识库，实现精准的垂直领域问答。系统支持“向量检索”与“全文检索”的混合模式，确保回答的准确性与相关性。

2. 技术栈概览

2.1 后端技术栈 (Backend)

• 开发语言: Java 17

• 核心框架: Spring Boot 3.4.1

• Web 容器: Undertow (高性能非阻塞)

• ORM 框架: MyBatis Plus 3.5.9

• 数据库:

  • PostgreSQL: 存储业务数据及向量数据 (使用 PGVector 插件)。

  • MongoDB: 存储非结构化文档数据及支持全文检索。

  • Redis: 缓存管理、分布式会话、Sa-Token 权限数据存储。

• AI 编排框架: LangChain4j 1.9.1 (Beta)

  • 统一封装 OpenAI, DeepSeek, Google Gemini 等几十种模型接口。

  • 提供 Embedding, RAG, Chat Memory 等核心组件。

• 安全认证: Sa-Token 1.39.0 (基于 Redis 的分布式会话与 RBAC 鉴权)。

• API 文档: Knife4j 4.4.0 (增强版 Swagger/OpenAPI 3)。

• 文档解析: Apache Tika (支持 PDF, Word, Excel, PPT, HTML 等多种格式)。

• 工具库: Hutool, FastJSON 2, EasyExcel, Flyway (数据库版本管理)。

2.2 前端技术栈 (Frontend)

• 开发语言: TypeScript

• 核心框架: Vue 3.5.13 (Composition API)

• 构建工具: Vite 4.5.3

• UI 组件库: Ant Design Vue 4.2.6

• 状态管理: Pinia 2.3.0

• 路由管理: Vue Router 4.5.0

• Markdown 渲染:

  • v-md-editor: Markdown 编辑与预览。

  • highlight.js: 代码高亮。

  • github-markdown-css: GitHub 风格样式。

  • markdown-it: Markdown 解析核心。

• 地图组件: @vuemap/vue-amap (高德地图集成)。

• 网络请求: Axios

3. 核心功能介绍

3.1 知识库管理 (Knowledge Base / RAG)

• 多格式文档解析: 支持上传 PDF, Word (.docx), Excel, Markdown, TXT 等文件，系统自动解析并提取文本。

• 数据分片与向量化:

  • 内置文本切分器 (Text Splitter)，支持按字符数或段落切分。

  • 集成 Embedding 模型 (如 OpenAI text-embedding-3, BGE-M3 等) 将文本转换为向量。

• 多种检索模式:

  • 向量检索 (Vector Search): 基于语义相似度，适合理解隐含意图。

  • 全文检索 (Keyword Search): 基于关键词匹配，适合精确查找专有名词。

  • 混合检索 (Hybrid Search): 结合两者优势，并通过重排序 (Re-ranking) 优化结果。

• 段落管理: 支持手动编辑、禁用/启用解析后的文档段落。

3.2 AI 应用构建 (App Builder)

• 零代码应用编排: 用户通过表单配置即可创建一个 AI 助手。

• 个性化设定:

  • 角色设定 (System Prompt): 定义 AI 的身份和行为准则。

  • 开场白: 自定义欢迎语。

  • 模型参数: 调整温度 (Temperature)、最大Token数等。

• 知识库关联: 灵活绑定一个或多个知识库，AI 将仅依据这些知识库回答问题。

• 多模态能力:

  • 语音识别 (STT): 支持语音转文字输入。

  • 语音合成 (TTS): 支持将 AI 回答朗读出来 (支持自动播放)。

3.3 智能对话 (Chat Interface)

• 流式响应 (SSE): 采用 Server-Sent Events 技术，实现逐字生成的流畅体验。

• 引用溯源 (Citation): AI 回答中会自动标注参考的知识库段落，点击角标可查看原文出处，杜绝幻觉。

• 会话历史: 自动保存历史对话记录，支持多会话切换。

• 问题优化: (可选) 在检索前对用户问题进行重写或关键词提取，提高检索准确率。

3.4 模型供应商集成 (Model Providers)

系统内置了“模型工厂”模式，统一接入了全球主流大模型：

• 国外: OpenAI (GPT-3.5/4), Azure OpenAI, Google Gemini.

• 国内:

  • 阿里云百炼 (通义千问 Qwen)

  • 百度千帆 (文心一言 ERNIE)

  • 智谱 AI (ChatGLM / GLM-4)

  • 深度求索 (DeepSeek)

  • 讯飞星火 (Spark)

  • 腾讯混元 (Hunyuan)

  • 字节跳动火山引擎 (豆包 / Doubao)

  • 月之暗面 (Kimi)

• 本地私有化:

  • Ollama: 轻松运行 Llama 3, Mistral 等开源模型。

  • Xinference: 分布式模型推理框架。

  • LocalAI: 本地模型兼容 OpenAI 协议。

---

4. 服务提供商注册与配置指南

本章节详细说明了项目中使用的各种外部服务提供商的注册方式、API Key 获取方法以及配置说明。

4.1 地图服务

高德地图 (AMap)

• 用途: 提供位置搜索、路径规划、定位等功能。

• 注册网址: https://console.amap.com/

• 智能场景配置对应关系:

  • Web服务 API Key: 对应高德控制台 "Web服务" 类型的 Key。

  • Web端(JSAPI) Key: 对应高德控制台 "Web端 (JSAPI)" 类型的 Key。

  • Web端(JSAPI) 安全密钥: 对应高德控制台 "Web端 (JSAPI)" 类型的 安全密钥 (Security Code)。

• 获取 Key 步骤:

  1. 注册并登录高德开放平台账号。

  2. 进入“控制台” -> “应用管理” -> “我的应用”。

  3. 点击“创建新应用”，填写应用名称和类型。

  4. 在应用下点击“添加 Key”。

  5. 注意: 本项目需要配置两种类型的 Key：

     • Web端 (JSAPI): 用于前端地图展示。勾选 "Web端 (JSAPI)"。

       • 获取 Key (填入智能场景的 Web端(JSAPI) Key) 和 安全密钥 (填入 Web端(JSAPI) 安全密钥)。

     • Web服务: 用于后端地点搜索和路径计算。勾选 "Web服务"。

       • 获取 Key (填入智能场景的 Web服务 API Key)。

4.2 翻译服务

百度翻译

• 用途: 提供多语言文本翻译功能。

• 注册网址: https://api.fanyi.baidu.com/

• 智能场景配置对应关系:

  • 百度 App ID: 对应百度翻译控制台的 "APP ID"。

  • 百度 Secret Key: 对应百度翻译控制台的 "密钥"。

• 获取 Key 步骤:

  1. 注册并登录百度翻译开放平台。

  2. 点击“开发者中心” -> “申请服务” -> “通用文本翻译”。

  3. 选择“标准版” (免费额度) 或 “高级版/尊享版” (需认证)。

  4. 进入“管理控制台” -> “开发者信息”。

  5. 获取 APP ID 和 密钥 (Secret Key)。

4.3 大模型 (LLM) 提供商

DeepSeek (深度求索)

• 网址: https://platform.deepseek.com/

• 获取 Key: 登录平台 -> 左侧菜单 "API Keys" -> 点击 "Create new API Key"。

智谱清言 (ZhiPu AI / ChatGLM)

• 网址: https://open.bigmodel.cn/

• 获取 Key: 登录控制台 -> 查看右上角 API Key 图标或进入 “API Key管理” -> 获取 API Key。

阿里云百炼 (通义千问 / Qwen)

• 网址: https://bailian.console.aliyun.com/?spm=5176.12818093_47.overview_recent.2.2d4216d08XsiL9&tab=home#/home

• 获取 Key:

  1. 登录阿里云百炼控制台。

  2. 点击右上角头像 -> “API-KEY” -> “创建新的 API-KEY”。

  3. 需确保账户有余额或已开通相关模型服务。

月之暗面 (Moonshot / Kimi)

• 网址: https://platform.moonshot.cn/

• 获取 Key: 登录控制台 -> "API Key 管理" -> "新建"。

百度文心一言 (WenXin / QianFan)

• 网址: https://console.bce.baidu.com/qianfan/

• 获取 Key:

  1. 登录百度智能云千帆大模型平台。

  2. “应用接入” -> “创建应用”。

  3. 获取 API Key 和 Secret Key。

讯飞星火 (XunFei Spark)

• 网址: https://console.xfyun.cn/services/cbm

• 获取 Key:

  1. 登录讯飞开放平台。

  2. 创建应用并选择“讯飞星火认知大模型”。

  3. 在应用控制台获取 APPID, APISecret, APIKey (三个参数均需要)。

腾讯混元 (Tencent HunYuan)

• 网址: https://cloud.tencent.com/product/hunyuan

• 获取 Key:

  1. 登录腾讯云控制台。

  2. 访问“访问管理” -> “API密钥管理” 获取 SecretId 和 SecretKey。

  3. 需在混元大模型控制台开通服务。

火山引擎 (VolcEngine / Doubao)

• 网址: https://console.volcengine.com/ark/region:ark+cn-beijing/model

• 获取 Key:

  1. 登录火山引擎方舟平台。

  2. “API Key 管理” -> 创建 API Key。

  3. 需创建“推理接入点” (Endpoint ID) 来调用特定模型。

OpenAI

• 网址: https://platform.openai.com/api-keys

• 获取 Key: 登录 -> "API keys" -> "Create new secret key"。

Azure OpenAI

• 网址: https://portal.azure.com/

• 获取 Key:

  1. 需申请开通 Azure OpenAI 服务。

  2. 在 Azure 门户 -> Azure OpenAI 资源 -> "Keys and Endpoint"。

  3. 需要配置 API Key, Endpoint, 和 Deployment Name。

Google Gemini (Google AI Studio)

• 网址: https://aistudio.google.com/

• 获取 Key: 点击 "Get API key" -> "Create API key in new project"。

4.4 语音服务 (TTS/STT)

部分大模型提供商（如 OpenAI, Azure, 阿里云百炼）也提供语音服务，Key 的获取方式同上。

专门的语音服务配置

如果使用专门的语音服务（如讯飞语音），可能需要在讯飞开放平台单独开通 "在线语音合成" 或 "语音听写" 服务，并获取对应的 APPID 等信息。

4.5 云存储服务

七牛云 (Qiniu Cloud)

• 用途: 提供对象存储服务 (Kodo)，用于文件上传和存储。

• 注册网址: https://portal.qiniu.com/create

• 智能场景配置对应关系:

  • 访问密钥 (Access Key): 对应七牛云 "AK"。

  • 安全密钥 (Secret Key): 对应七牛云 "SK"。

  • 存储桶名称: 对应七牛云对象存储的 "空间名称 (Bucket Name)"。

  • 域名: 对应七牛云空间的 "测试域名" 或 "自定义域名" (需包含 http:// 或 https://)。

• 获取 Key 步骤:

  1. 注册并登录七牛云控制台。

  2. 鼠标悬停在右上角头像，点击“密钥管理” (或者访问 https://portal.qiniu.com/user/key)。

  3. 创建或查看 AccessKey (AK) 和 SecretKey (SK)。

  4. 进入“对象存储 Kodo” -> “空间管理” -> “新建空间” (获取 存储桶名称)。

  5. 在空间概览页找到 外链域名 (获取 域名)。

阿里云 OSS (Aliyun OSS)

• 用途: 提供海量、安全、低成本、高可靠的云存储服务。

• 注册网址: https://oss.console.aliyun.com/

• 智能场景配置对应关系:

  • 服务端点 (Endpoint): 对应 OSS Bucket 的 "Endpoint (地域节点)"。

  • 访问密钥 (Access Key): 对应阿里云 RAM 访问控制的 "AccessKey ID"。

  • 安全密钥 (Secret Key): 对应阿里云 RAM 访问控制的 "AccessKey Secret"。

  • 存储桶名称: 对应 OSS 的 "Bucket Name"。

• 获取 Key 步骤:

  1. 注册并登录阿里云控制台。

  2. 鼠标悬停在右上角头像，点击“AccessKey 管理” (建议使用 RAM 用户进行访问控制)。

  3. 获取 AccessKey ID 和 AccessKey Secret。

  4. 进入“对象存储 OSS” -> “Bucket 列表” -> “创建 Bucket”。

  5. 在 Bucket 概览页，找到 Endpoint (地域节点) (如 oss-cn-hangzhou.aliyuncs.com)。

系统功能使用指南

1. 导航功能

1.1 触发方式

系统通过自然语言识别用户的导航意图。触发逻辑分为 强关键词 和 弱关键词 两种模式：

1. 强关键词触发

   • 关键词：导航、路线、怎么走

   • 规则：只要句子中包含上述任意关键词，无论位置如何，均触发导航功能。

   • 示例：

     • "帮我导航去天安门"

     • "查询一下路线"

     • "去机场怎么走"

2. 弱关键词触发

   • 关键词：去、到

   • 规则：这些关键词必须位于句子开头才能触发导航。如果出现在句子中间，则视为普通聊天。

   • 示例：

     • "去故宫博物院" (触发导航)

     • "到上海人民广场" (触发导航)

     • "我想去看电影" (不触发，视为聊天)

     • "明天去哪里玩" (不触发，视为聊天)

1.2 地图操作

当导航被触发并显示地图卡片后，用户可以进行以下操作：

• 调整地图高度：

  • 在地图卡片顶部有一个灰色的拖动条。

  • 鼠标悬停在拖动条上时，光标会变为上下箭头。

  • 按住鼠标左键上下拖动，即可调整地图显示区域的高度。

  • 限制：地图高度会自动限制，确保不会遮挡底部的聊天输入框，保证聊天窗口至少保留一定的可视高度 (最小约 200px)。

• 路线预览：

  • 地图会自动规划并显示从当前位置（或模拟位置）到目的地的路线。

  • 左上角显示起点和终点信息。

1.3 注意事项

• 如果输入的地点不明确，系统可能会提示或默认选择最匹配的地点。

• 导航功能目前依赖高德地图服务，需确保网络连接正常。

PgVector安装

推荐需要特定功能或自定义配置的用户：

编译环境配置：

以管理员身份启动"x64 Native Tools Command Prompt for VS"
设置PostgreSQL安装路径环境变量

源码获取与编译：

cd pgvector-master 中 nmake /F Makefile.win nmake /F Makefile.win install

功能验证与性能测试

部署完成后，通过以下SQL语句验证扩展功能：

-- 启用向量搜索扩展
CREATE EXTENSION vector

项目编号

编号：2337

技术说明

开发工具： Idea/Eclipse
数据库： MySQL
Jar包仓库： Maven
前端框架： Vue/ElementUI
后端框架： Spring+SpringMVC+Mybatis+SpringBoot

项目运行截图