# 前端/后端/客户端

更新说明
一、背景
二、实施策略
2.1 实施方案
2.2. 技术栈选型
三、详细功能规格
3.1. 开放平台
3.1 团队职责和分工
查看更多...

前端/后端/客户端

# 更新说明

本文记录了<产品名称>的变更情况。

<更新日期> / <版本号>

更新日期：

若上处标题为<更新日期>格式，此处可略过不填。

版本 | 变更类型 | 说明 | 相关文档

参考以下变更类型： <新增> <修改> <优化> <废弃> <删除> <修复> <已知问题>

说明具体变更情况。

罗列相关文档，并提供超链接。

# 一、背景

描述项目的背景、目标和预期效果及产出：

在数字化和智能化转型的浪潮下，企业知识资产的管理与利用效率已成为核心竞争力的关键。然而，当前企业内部普遍存在知识孤岛、信息检索困难、专家经验无法沉淀和复用等问题。同时，大语言模型能力虽强，但直接应用于企业场景存在数据安全、幻觉回答、与内部知识脱节等风险。

本项目旨在构建一个企业级、一站式AI平台，通过RAG等核心技术，将大语言模型的通用能力与企业私域知识、业务流程深度融合。其战略意义在于：

提升效率： 让员工能像与人对话一样，快速获取精准、可信的知识和答案。

保障安全： 实现企业级的数据隔离、权限控制和内容安全审查。

赋能创新： 降低AI应用开发门槛，使业务部门能自主构建智能应用，推动业务创新。

统一管控： 统一技术栈和治理规范，避免重复建设，实现资源集约化管理。

预期效果：

构建企业知识大脑： 实现非结构化文档的智能化采集、解析、存储、检索和更新。

打造AI应用工厂： 提供可视化的应用搭建、调试、评测和发布流程。

提供统一交互入口： 通过功能丰富的聊天客户端，为用户提供一致、流畅的AI交互体验。

建立完善的管理体系： 实现多租户、细粒度权限、内容安全和运营监控。

相关资料：输入@ 插入相关云文档

# 二、实施策略

## 2.1 实施方案

总体架构设计

系统采用前后端分离的微服务架构，总体分为以下几层：

表现层：

用户端： Web Chat Client（智能聊天客户端）。

管理端： Open Platform Admin（开放平台管理台）、Permission Admin（权限管理后台）。

应用层/网关层：

API Gateway： 负责请求路由、身份认证、限流、日志记录。

前端应用服务器： 承载前端静态资源。

业务服务层：

User-Auth-Service：用户认证与授权服务。

App-Management-Service：应用全生命周期管理服务。

KB-Management-Service：知识库管理服务。

Vector-Search-Service：向量检索服务。

Knowledge-Graph-Service：知识图谱服务。

Chat-Service：聊天会话服务。

Evaluation-Service：应用评测服务。

Permission-Service：权限控制服务。

File-Parse-Service：文件解析服务。

Content-Safety-Service：内容安全服务。

数据层与基础设施：

数据存储： MySQL（业务元数据）、Milvus/Chroma（向量数据）、Neo4J（图数据库）、OSS/MinIO（对象存储）、Redis（缓存、会话）。

AI能力： LLM APIs、Embedding Model APIs、Neo4j。

## 2.2. 技术栈选型

前端： Vue 3 + Element Plus / React + Ant Design

后端： Java (Spring Boot) 、 Python (FastAPI)。

数据：

MySQL 8.0（关系型数据，事务性操作）。

Milvus（向量数据库，高性能相似性检索）。

MinIO（对象存储，海量文件存储）。

Redis（缓存、分布式会话存储、消息队列）。

文档处理：

MinerU VLM

PaddleOCR VL

# 三、详细功能规格

## 3.1. 开放平台

平台概要说明：

开放平台是整个系统的管理与配置中心，面向应用开发者、知识管理员和系统管理员。它提供了AI应用从创建、配置、测试、审核到上线管理的全生命周期管理能力，同时集成了知识库管理、模型评测和系统监控等功能。其核心目标是赋能，让技术和业务人员能够快速、安全地构建和运营智能应用。

### <一> 、统一认证与登录模块

功能目标： 为平台提供安全、便捷、统一的用户身份验证入口，支持多租户和混合登录模式。

详细功能说明：

#### 1. 多方式登录画面：

入口逻辑： 用户访问平台任意页面，系统拦截器检查登录状态，若未登录或Token失效，则自动重定向至统一登录画面。

UI/交互： 页面清晰展示"集团统一认证登录"与"本地登录"两个主要选项，支持选项卡切换。页面需包含平台标识、版本信息等。

会话管理： 登录成功后生成的JWT Token需包含用户ID、企业ID、权限列表等信息，并设置合理的过期时间。

#### 2. 集团统一认证登录流程：

协议支持： 采用OAuth 2.0 Authorization Code模式与集团认证中心对接。

流程细节：

用户点击"集团统一认证登录"，前端重定向至集团SSO页面，携带client_id, redirect_uri, state等参数。

用户在集团页面完成认证授权。

集团认证中心回调至平台的redirect_uri，并携带code和state。

平台后端使用code向集团认证中心换取access_token。

平台后端使用access_token调用集团用户信息接口，获取用户基本信息（用户名、邮箱、部门等）。

用户同步与映射： 平台根据获取的信息，在本地数据库查找或创建对应的用户记录（标记为集团用户），并确保部门信息同步。

平台生成自身的JWT Token并返回给前端，完成登录。

设计稿示例：

#### 3. 本地登录流程：

多租户入口：登录页面首先提供"企业"下拉选择框，列表数据来源于companies表。

验证机制：用户输入用户名、密码和图形验证码。后端校验企业状态、用户状态、密码（经加盐哈希处理）及验证码的正确性。

安全措施：连续登录失败N次后，账户将被临时锁定，并记录安全日志。

设计稿示例：

### <二> 、应用中心模块

功能目标： 提供AI应用的发现、创建、配置、调试、审核和管理的全流程功能。

详细功能说明：

#### 1. 应用广场：

视图与导航：采用"分类导航 + 卡片列表"的布局。顶部为应用分类横向导航栏（如：技术研发、市场营销、人力资源、财务法等），并与"收藏夹"、"我创建的应用"等个人视图并行展示。

权限控制逻辑：应用可见性由复杂的SQL查询逻辑控制，确保用户只能看到其有权访问的应用。

主题色配置：预设3-4套安全色主题（包含按钮颜色-背景颜色-强调色等）集团管理员和分公司超级管理员可以切换主题配色。普通用户只有 明亮色 和 暗黑色 两个主题色切换

设计稿示例：

#### 2. 应用卡片与操作：

信息展示： 卡片内容包含应用Logo、名称、一句话描述、所属分类标签。

"立即使用"按钮： 点击后，系统在新的浏览器标签页中打开智能聊天客户端，并自动进入该应用的专属聊天会话。

"收藏/取消收藏"按钮： 点击后通过AJAX调用接口，实时更新用户与应用间的收藏关系，按钮状态即时切换。

集团RAG应用TAG：集团层级的管理员创建的应用将全局所有分公司范围可见。应用卡片带有集团RAG应用的tag标签。

#### 3. 应用创建与编辑（向导式）：

步骤一：基本信息

应用名称：必填，需做唯一性校验（同一企业内）。

应用类型：单选，普通或项目。选择项目后，需关联一个用户有权限的项目。

可见性：单选，私有或公开。默认私有。选择公开时，需向用户明确提示"此应用提交后需要审核通过才能在应用广场公开显示"。

应用审核：公开的应用需要管理员审核后方可发布。发布后可见范围内的其他用户可以查看和使用。只有管理员和创建着可以编辑/删除RAG应用。

选择可见范围：发布公开应用的时候既可以勾选可以查看应用权限的人员，也可以勾选人员范围（如选择部门，选择项目等）。

应用描述：文本框，用于详细介绍应用的功能和用途。

引导问题：可输入多个预设问题，这些问题将在聊天客户端的RAG聊天中作为快捷提问展示。

是否开启多轮对话：支持RAG应用中开启预设的3-5轮上下文生效。

设计稿示例：

步骤二：提示词配置

富文本编辑器： 提供强大的文本编辑功能，支持加粗、列表等。

预设模板： 提供场景化模板（如：标准规范类，通用类型），自动填充基础提示词。

变量系统： 支持在提示词中插入预定义变量，例如：{context}（代表检索到的知识片段）、{question}（代表用户问题）、{history}（代表对话历史）。系统在调用时会自动替换为真实内容。

设计稿示例:

步骤三：参数配置

知识库关联： 多选下拉组件，数据源为用户有权限访问的所有知识库（包括公开库和自建库）。支持多选知识库。

知识库下拉组件中支持按知识库名称搜索，支持通过按钮快捷查看知识库中的文档。

调用模型设置：下拉选择，列表从模型网关服务动态获取。可配置首选模型和备用模型。

生成参数配置：

最大输出Token(Max Token)：滑动条或数字输入，设置模型回答的最大长度，控制模型生成内容的最大长度。较长的文本需要更大的值。

回答风格：下拉选择，如创意型、平衡型、精确型。一键切换预设的参数组合，适应不同任务场景。选择后会联动调整Temperature和Top-P的值。

温度(Temperature)：滑动条或数字输入，控制回答的随机性（0.0 ~ 1.0）。控制输出的随机性和创造性，值越低，输出越确定和保守；值越高，输出越随机和富有创意 。

Top-P: 滑动条或数字输入，动态控制候选词范围。例如，设为 0.9 意味着模型将从概率累积和占前 90% 的词中挑选，排除剩余 10% 的低概率词。这能有效避免生成不相关或奇怪的内容，是控制输出质量的关键参数。

Top-K: 滑动条或数字输入，控制模型在每个生成步骤中仅从概率最高的k个词中选择（1-100）。k值越小，输出越集中；k值越大，输出越多样。

检索参数配置：

召回方式：单选，向量检索、知识图谱检索、关键词检索（BM25）、混合检索。

召回模型：选择用于生成向量的Embedding模型。

切片召回数量：数字输入，决定每次检索返回多少个知识片段。

是否展示引用来源：开关，控制聊天客户端是否显示答案引用的知识片段。

设计搞示例：

步骤四：预览调试

内嵌聊天界面： 右侧提供一个简化的聊天窗口。

实时调试： 用户在此窗口的提问，将完全使用当前步骤配置的参数进行回答，方便即时验证配置效果。

保存与提交： 用户可点击"保存草稿"暂存配置，或点击"保存并提交"完成创建。若应用 visibility 为公开，则状态自动变为 待审核。

设计稿示例：

步骤五：应用审核，当公开应用发布时候需要经过管理员审核

公开应用点击发布后自动进入待审核状态。

经过管理员审核通过后变为可见状态。

#### 4. 我创建的应用（应用列表）：

列表管理： 以数据表格形式展示，提供高级查询（按名称、状态筛选）和类型分页功能。

操作集详解：

查看：直接跳转至当前选中RAG应用的 智能问答客户端，以问答对话交互的形式，支持 web 和 h5。

编辑： 进入与创建流程相同的编辑向导。对于已审核通过的公开应用，任何编辑操作都会将其状态重置为 待审核，并通知审核人。

删除： 执行软删除（is_deleted = 1），并记录删除日志。删除操作会异步清理与该应用相关的聊天记录、评测任务等关联数据，但不会影响其引用的知识库。

API服务： 跳转至API配置页面，展示该应用的API Key、Endpoint、请求示例等。

评测工具： 跳转至评测任务创建页面，并自动将当前应用的信息和评测参数填入“评测任务”中的相关表单字段。

设计稿示例：

### <三> 、知识管理模块

功能目标：实现企业非结构化知识（文档）的数字化、结构化、向量化存储与管理，为AI应用提供可靠的知识来源。

详细功能说明：

#### 1. 知识库（列表与创建）：

列表视图： 提供"全部知识库"和"我创建的知识库"两个标签页。列表项展示关键元数据，并提供引用、编辑、删除等操作入口。

知识库创建（创建空的知识集合）：知识库创建含知识库名称，是否公开，知识库分类，向量化模型，知识库说明等信息。

名称与知识库描述：填写知识库的名称与描述信息。

公开与公开范围：打开公开按钮后有进一步公开范围选项，选择公开属性的知识库将通过管理员审核，审核通过后的知识库在可见范围内其他用户可以直接使用此知识库集合来创建自己的RAG应用也可以引用其中的知识文档（文件）来构建自己的知识库。

向量化模型：选择的向量化模型将会直接影响到本知识库内的知识文档（文件）所采用的向量化模型。

知识图谱：选择是否开启知识谱，开启知识图谱后，将以知识图谱的逻辑来实现后续的流程。

设计稿示例:

#### 2. 文件上传与引用：

步骤一：前端文件上传

采用分片上传技术，支持大文件稳定上传，并显示实时进度条。

上传前校验文件类型（PDF, DOC, DOCX, PPT, XLS, XLSX, PNG, JPEG, JPG）和大小（管理员可配置，如50MB）。

分类：标准规范/通用/表格/文件，不同类型对应不同的处理策略。

标准规范分类：默认采用最小段落切分。（如章、节、条的结构下按最小的条目进行切分）

通用分类：为保障段落的完整性，默认采用标准段落切分。

表格分类：当前知识库下仅支持表格类型，支持原生excel格式的理解，将按照最小行（最小单元格行）切分表格。每一行一个切片（包含标头信息，行内容，行中如果存在图片，图片信息则会被丢弃）。

文件召回：支持在知识库内上传文件后文件不触发解析行为与切分行为，相当于将单个文件看作是网盘链接。文件在召回的时候显示文件标题、文件描述、以及文件下载url。

切分规则：更改按最小段落切片/按标准段落切片/按页切片/按标识符切片规则。

设计稿示例：

步骤二：后端异步处理流程：

文件接收与记录： 前端上传完成后，调用POST /api/documents接口，后端在documents表创建记录，状态为uploaded，并返回doc_id。

任务发布： 向后端发布一个document_processing任务，包含doc_id和kb_id。

文档解析： File-Parse-Service消费任务，根据file_path从OSS下载文件。

对于DOC/DOCX，使用MinerU将其转换为PDF。

使用MinerU VLM、Paddleocr-VL 等工具解析PDF，提取文本、图片、表格和元数据（如目录结构）。状态更新为parsing。

内容切片： 根据知识库创建时配置的切片规则（按段落、按分页、自定义长度），将提取的文本切分成多个chunk。状态更新为chunking。

执行向量化与存储：

将内容切片存入关系数据库，至少可以存两份，一份原始数据（只读、用于恢复到原始版本），一份最新数据(用于编辑和召回的依据)。

初始入库：当文档第一次处理时，为所有 chunk设置 chunk_version = 'v1.0-original'。

更新文档：当他人引用文档，并手动编辑更新chunk后，不直接修改已有的 chunk 记录，而是：1. 重新按照编辑提交时候状态，生成新的切片。2.为这些新 chunk 设置 chunk_version = 'v2.0-latest'。

当chunk发生修订行为的时候，会为不同的关联chunk打上标记：

发现 chunk-A需要手动修订，且修订后的内容与 chunk-B有关联。插入新 chunk B_v2 (id=****)，并chunk A_v2(id=****)建立关系:1. A_v2.previous_version_id = 1（表示它修订了 chunk A）2. A_v2.reference_chunk_ids = {2}（表示它引用了 chunk B）3. 并为 A和 B的 设置当前生效状态。is_current_version。

调用 Embedding 模型服务，将每个chunk的文本转换为向量。

将向量存储到向量数据库 Milvus 的对应集合中，并将chunk的文本内容、元数据（页码、章节、自动生成的关键词/摘要等）存入MySQL的chunks表。两者通过chunk_id关联。

完成与回调： 所有切片处理完毕后，更新文档状态为completed，并更新知识库的文件数量、字符总数等统计信息。

设计稿示例：

文件上传/处理过程中的全局功能：

文档校验：前端计算文件整体或分片（大文件分块上传时）的 MD5值，服务端接收前端发送的文件MD5值及其元数据（文件名、大小等），会将其与数据库中已存储的所有文件的MD5值进行比对。校验其唯一性和完整性，避免重复上传和文件损坏。

重复文件智能提醒：通过上一步的文档校验工具对上传完成的文件进行MD5值比对，若文件未重复：正常执行上传流程，并将文件信息（包括其MD5值）存入数据库。若文件重复：服务端将中断上传流程，并向前端返回“文件已存在，无需重复上传”的提示信息，前端接收到重复文件提醒后，应清晰地向用户展示提示（例如：“此文件已存在于系统，”），并自动将当前文件任务状态更新为“已完成”。同时，系统会自动关联并直接引用已存在的文件进入后续处理流程。

进度监控： 前端通过WebSocket或定时轮询GET /api/documents/{doc_id}/status接口，获取当前处理状态（status）和进度（process_progress），并在UI上以进度条形式展示。

断点续传：记录已上传分片，网络中断后可从断点继续，前端组件增加上传状态，提升用户体验。

并发控制：合理控制并发上传的分片数量，避免阻塞。

关于知识文档的"引用"功能详解：

流程： 用户A不上传文档，选择引用别人的知识文档（文件），点击"引用"。系统弹出模态框，展示当前用户权限范围内的所有公开知识库中的所有文档（文件），列表页面呈现方式支持筛选，支持搜索，支持排序，用户A可勾选需要引用的文档。

底层实现：

系统为用户A创建一个新的知识库K'。

对于每个被引用的文档D，在documents表创建一条新记录D'，其file_path指向与原文档D相同的OSS对象。is_referenced字段标记为True。

将文档D的所有切片记录chunks复制到新库K'下，新切片关联文档D'。

权限与限制： 用户A对K'拥有完全控制权，可以新增自有文件，或对引用的切片进行元数据编辑（如修改关键词）和内容修订，但不能删除引用的原始文件D'。

文件查询方式：

支持按知识库名称、文档名称模糊搜索，支持按知识库分类的tab页切换。

支持查看：文档名称、文档大小、字符数量、分段数量、关联RAG的评测打分、来源知识库、上传/更新时间。

#### 3. 切片管理（高质量切片编辑工具）：

多栏编辑器设计与交互：

第一栏（文档列表）： 以树形结构展示知识库所有文档。支持按文件名搜索。点击文档节点，在第二栏加载该文档的切片列表。可向左折叠。

第二栏（PDF预览组件）：可预览PDF文档原文，可向左折叠。

第三栏（切片编辑列表）： 以卡片列表形式展示当前文档的所有切片，按页码或位置排序。每张卡片显示切片完整内容。

编辑： 点击后，在第三栏或弹窗中打开切片内容编辑器，可修改文本。

删除： 删除单个切片，需确认。

多选与合并： 通过复选框选择多个连续切片，点击"合并"按钮，将其合并为一个新切片，原切片被标记为删除。

拆分：

第四栏（切片预览与定位）： 使用PDF.js或类似技术渲染原始文档的整体预览。

联动高亮： 当在第二栏点击某个切片时，预览区域会自动滚动到该切片对应的文本位置，并加以高亮显示。

反向定位： 在预览区域选择文本，系统可智能推测并定位到可能对应的切片。

介绍团队的主要工作 ......

## 3.1 团队职责和分工

描述团队职责

......

成员 | 职能 | 主要负责工作
| 前端 | 建科小智v1版本的 问答客户端、应用广场、权限系统的前端迭代更新

查看更多...
目录
更新说明
一、背景
二、实施策略
2.1 实施方案
2.2. 技术栈选型
三、详细功能规格
3.1. 开放平台
3.1 团队职责和分工
查看更多...