主题
本页是项目整体设计方案：业务架构、业务流程、技术架构与开发计划。需求背景见 需求分析，数据模型见 库表设计，各模块深挖见 文件上传模块 / 知识库检索模块 / 聊天助手模块。
基于 需求分析，我们已经明确了这个基于 RAG 的企业级智能知识管理平台要做什么：结合大语言模型（如 DeepSeek）和向量化技术，为用户提供高效、精准的问答服务。用户可以上传文档构建专属的私有知识库，并实时与平台交互提问；平台支持多轮对话、语义检索和动态知识库更新，适用于企业内部知识管理、教育、客服等场景。
基于这些需求，我们把需求整理成了一张思维导图：
一、业务架构设计
基于需求梳理，我们设计了这样一个三层业务架构图：
01、用户层
用户层是整个系统的入口，主要面向两类用户群体。普通用户可以通过这一层进行日常的知识查询、文档上传和智能对话等操作，他们是系统的主要使用者，通过简洁直观的界面就能享受到智能的知识服务。
管理员则拥有更高的权限，可以进行系统配置、用户管理、数据监控等管理工作，确保整个平台的稳定运行和安全性。
02、逻辑层
逻辑层是整个系统的核心，包含四个主要的功能模块，每个模块都承担着特定的业务职责。
①、用户管理模块
该模块是系统安全和权限控制的基础。注册登录功能为用户提供了基础的身份认证机制，确保只有合法用户才能访问系统资源。
权限控制功能会根据用户的角色和级别，精确控制用户能够访问的功能和数据范围，比如某些敏感文档只有特定部门的用户才能查看。组织标签管理功能帮助企业按照部门、项目或其他维度对用户进行分组管理，使得权限分配更加灵活和精确。
用户信息管理功能则负责维护用户的基本信息、偏好设置等，为个性化服务提供基础数据支持。
②、文档上传与处理模块
该模块是知识输入的关键环节，负责将各种格式的文档转化为系统可以理解和处理的知识内容。文档上传功能支持多种常见的文档格式，包括 PDF、Word、文本文件等，系统会自动进行格式识别和处理。
文本提取功能是这个模块的核心技术之一，PDF 使用本地解析引擎的子进程处理（保留页码和锚点），其余格式使用 Apache Tika 解析提取纯文本内容，同时保留重要的结构信息。文本向量化功能则将提取出的文本转换为计算机可以理解的数学向量，这是实现语义搜索的关键技术，让系统能够理解文本的真正含义而不仅仅是关键词匹配。
组织标签关联功能确保每个文档都能正确地归属到相应的组织或部门，这不仅有助于权限控制，也便于用户在自己的权限范围内快速找到相关文档。可见性设置功能则允许文档上传者设定文档的可见范围，比如设为公开、部门内可见或仅个人可见，灵活满足不同的共享需求。
③、知识库检索模块
检索模块是用户获取知识的主要途径，我们采用了先进的混合检索技术。语义检索功能利用 RAG 技术，能够理解用户查询的真正意图，即使用户使用的词汇与文档中的表述不完全一致，系统也能找到相关的内容。比如用户搜索"如何提升销售业绩"，系统不仅能找到包含这些关键词的文档，还能找到讨论"销售技巧"、"客户关系管理"等相关主题的内容。
关键词检索功能则提供了传统的精确搜索方式，当用户需要查找特定的术语、人名、地名或其他精确信息时，这种检索方式能够快速定位到相关文档。混合排序功能将语义检索和关键词检索的结果进行智能融合，综合考虑相关性、权威性、时效性等多个因素，为用户提供最有价值的搜索结果。
组织权限过滤功能确保用户只能看到自己有权限访问的搜索结果，这不仅保护了敏感信息的安全，也提高了搜索结果的精准度，避免用户被无关的信息干扰。
④、聊天助手模块
聊天助手模块为用户提供了更加自然和智能的知识获取方式。基于 WebSocket 进行实时通信，用户的提问方式就像和真人助手交流一样。多轮对话功能让系统能够记住对话的上下文，用户可以进行连续的提问，系统会根据之前的对话内容来理解当前的问题。
本地知识库集成功能是这个模块的核心优势，系统会根据用户的问题自动搜索相关的文档内容，并将这些信息整合到回答中。这样用户不仅能得到通用的答案，更能获得基于企业内部知识的专业回答。
Prompt 构建与管理功能负责优化与 AI 模型的交互方式，通过精心设计的提示词模板，确保 AI 能够更好地理解用户意图并提供高质量的回答。大语言模型集成功能则让系统能够利用最新的 AI 技术，提供更加智能和自然的对话体验。
03、数据层
数据层为整个系统提供了可靠的数据存储和管理基础。用户信息存储负责保存用户的身份信息、权限设置、使用偏好等数据。组织标签数据管理维护着企业的组织架构信息，为权限控制和数据分类提供基础支持。
对话数据存储记录了用户与系统的所有交互历史，这不仅便于用户回顾之前的对话内容，也为系统优化和个性化服务提供了宝贵的数据资源。文件存储系统则负责保存用户上传的原始文档。
向量化数据存储是系统实现智能检索的技术基础，它保存着所有文档内容的向量表示，这些数据经过精心的索引和优化，能够支持大规模的实时检索操作。
二、业务流程设计
01、文档向量化
平台的文档处理与向量化是一个完整的自动化流程，涉及用户、文件服务、向量化服务、Elasticsearch 和 MySQL 等多个组件的协同工作。
整个流程从用户上传文档开始。用户通过前端界面选择文档并设置相关的组织标签和可见性权限后，系统开始接收文档。这个阶段的关键是建立文档的基本信息记录，包括文件的 MD5 哈希值、原始文件名、文件大小、上传用户信息等。系统会为每个文档生成唯一的标识符，并将文档的元数据信息存储到 MySQL 数据库中，同时将原始文件保存到文件存储系统中。
文档上传完成后，系统进入分块处理阶段。这个阶段采用循环处理的方式，逐个处理文档中的内容片段。首先，系统会调用文件服务来读取原始文档，然后使用 Apache Tika 等文档解析工具提取出纯文本内容。由于完整的文档通常内容较长，直接进行向量化处理会影响检索的精确度，因此系统会将提取出的文本按照一定的规则进行分块，比如按段落、按字数或按语义单元进行切分。每个文本块都会被分配一个块序号，确保能够准确定位到文档中的具体位置。
在分块完成后，系统会对生成的文本块进行合并和优化处理。这个步骤主要是为了确保文本块的质量和完整性。系统会检查相邻的文本块是否存在语义上的连续性，如果某些块过短或者语义不完整，会考虑与相邻块进行合并。同时，系统还会过滤掉一些无意义的内容，比如页眉页脚、图片说明等，确保每个文本块都包含有价值的信息内容。
文本块准备就绪后，系统开始进行向量化处理。这个阶段同样采用循环处理的方式，逐个处理每个文本块。系统会调用向量化服务，将文本块的内容发送给向量模型（Embedding Model）进行向量转换。向量模型会将文本内容转换为高维度的数学向量，这些向量能够表示文本的语义特征。向量化服务在完成转换后，会将生成的向量数据返回给系统。这个过程可能需要一定的时间，特别是当文档较大或者文本块较多时，因此系统采用了异步处理的方式来提高效率。
向量化完成后，系统需要将生成的向量数据进行持久化存储。这个阶段涉及两个存储系统的协同工作。首先，系统会将向量数据连同相关的文本内容、文档标识、块序号等信息一起存储到 Elasticsearch 中。Elasticsearch 作为专业的搜索引擎，不仅能够存储向量数据，还能够提供高效的向量相似度搜索功能。同时，系统还会将文档的元数据信息更新到 MySQL 数据库中，包括处理状态、向量化完成时间等信息，确保数据的一致性和完整性。
数据存储完成后，Elasticsearch 会自动为新增的向量数据构建索引。这个过程包括创建倒排索引用于关键词搜索，以及构建向量索引用于语义相似度搜索。系统会根据预设的索引策略对数据进行分片和副本设置，确保搜索性能和数据安全性。索引构建完成后，这些文档内容就可以被用户通过各种方式进行检索和查询了。
在整个流程中，系统还包含了完善的异常处理和监控机制。如果在任何一个环节出现错误，比如文档解析失败、向量化服务不可用、存储系统异常等，系统都会记录详细的错误信息，并根据错误类型采取相应的处理策略。对于可恢复的错误，系统会自动进行重试；对于不可恢复的错误，系统会标记处理状态并通知管理员。同时，系统还会实时监控各个组件的运行状态和性能指标，确保整个流程的稳定性和高效性。
实现注记：这条链路在我们的实现里由 Kafka 异步驱动——合并完成后发送任务消息（带文件指纹、存储路径和权限三元组），消费端按"置处理中状态 → 拉取文件流 → 解析（PDF 子进程 / Tika）→ 语义切块写入 MySQL → 向量化写入 ES"推进；ES 文档 ID 使用文件指纹加块序号的确定性 ID，消息重复消费也不会产生重复数据；Embedding 调用有两阶段配额（调用前预估拦截、调用后按真实用量结算）。细节见 文件上传模块。
02、知识检索
整个知识检索流程体现了 RAG 智能知识库管理系统的核心特征：语义理解、权限控制、高性能检索和用户友好的交互体验。
第一阶段是用户查询请求。用户通过前端界面发起查询请求，系统首先接收用户的自然语言查询文本，并通过 WebSocket 实时传输到后端服务。
第二阶段是查询预处理与向量化。查询服务接收到用户请求后，会获取用户的组织标签信息和权限数据，确保后续检索符合权限控制要求。同时，系统将查询文本发送给向量化服务进行向量化处理，将自然语言转换为高维向量表示，这是实现语义检索的关键步骤。
第三阶段是混合检索执行。HybridSearchService.java 执行核心的混合检索逻辑。系统构建包含权限过滤条件的综合查询，结合向量相似度检索和关键词匹配，在 Elasticsearch 中进行高效搜索。这种混合检索策略既保证了语义理解的准确性，又兼顾了关键词匹配的精确性。
第四阶段是结果排序与权限过滤。检索到的候选结果会经过严格的权限验证，确保用户只能访问有权限的知识内容。系统根据相似度得分、关键词匹配度等多个维度对结果进行综合排序，并按照 SearchRequest 中定义的 topK 参数返回最相关的结果。
第五阶段是结果返回与展示。最终的知识片段通过 SearchController.java 返回给前端，chat-message.vue 组件负责渲染和展示检索结果，为用户提供直观的知识获取体验。
03、聊天助手
整个聊天助手流程体现了现代 AI 应用的核心特征：实时性、智能性、可靠性和用户友好性。
第一步是用户通过 WebSocket 发送问题。用户在 input-box.vue 组件中输入问题，点击发送按钮后，前端通过 index.ts 中的 WebSocket 连接发送消息。系统使用 @vueuse/core 的 useWebSocket 建立连接，支持自动重连机制。前端会先将用户消息添加到对话列表，然后通过 chatStore.wsSend(input.value.message) 发送到后端。
第二步是系统调用知识检索模块获取相关内容。ChatWebSocketHandler.java 接收到 WebSocket 消息后，调用 ChatHandler.java 的 processMessage 方法。系统首先获取或创建会话 ID，然后调用 searchService.searchWithPermission(userMessage, userId, 5) 执行带权限过滤的混合搜索，从 Elasticsearch 中检索最相关的 5 条知识片段，确保用户只能访问有权限的内容。
第三步是系统构建包含检索结果和历史对话的 Prompt。系统通过 getConversationHistory(conversationId) 从 Redis 中获取对话历史记录，保持最近消息的上下文。然后调用 buildContext(searchResults) 方法将检索到的知识片段格式化为上下文信息，每个片段限制在 300 字符内并编号标记。这样构建的 Prompt 既包含了相关的知识背景，又保持了对话的连续性。
第四步是调用大语言模型 API 生成回答。系统调用 DeepSeekClient.java 的 streamResponse 方法，将用户问题、构建的上下文和对话历史一起发送给 DeepSeek API。这个过程采用流式调用方式，能够实时接收 AI 生成的内容片段，而不需要等待完整回答生成完毕。
第五步是通过 WebSocket 流式返回生成内容。当 DeepSeek API 返回内容片段时，系统通过 sendResponseChunk 方法将每个 chunk 包装成 JSON 格式（{"chunk": "内容片段"}）并通过 WebSocket 实时发送给前端。前端在 input-box.vue 中监听 wsData 变化，当接收到包含 chunk 字段的数据时，会将内容追加到助手消息的 content 中，实现打字机效果的实时显示。
第六步是保存对话记录到数据库。当 AI 回答完成后，系统通过后台线程检测响应完成状态，然后调用 updateConversationHistory 方法将完整的用户问题和 AI 回答保存到 Redis 中。对话记录包含角色标识（user/assistant）、内容和时间戳，支持 7 天的数据保留期。同时发送完成通知（{"type": "completion", "status": "finished"}）给前端，前端接收后将消息状态更新为"finished"。
这一块也是整个 RAG 知识库的核心，聊天的请求会结合知识库进行相应的回复，这一点非常重要。
04、权限管理
平台实现了一套完整的组织权限管理体系，从管理员创建组织标签到用户文件访问控制形成了完整的权限管理闭环。
整个权限管理流程始于管理员通过 AdminController.java 中的接口创建和管理组织标签。管理员可以通过 POST /api/admin/org-tags 接口创建具有层级结构的组织标签，支持设置标签 ID、名称、描述和父级标签，所有标签信息都存储在 ddl.sql 定义的 organization_tags 表中。
在组织标签创建完成后，管理员通过 PUT /api/admin/users/{userId}/org-tags 接口为用户分配相应的组织标签。这些标签以逗号分隔的字符串形式存储在用户表的 org_tags 字段中。系统的一个重要特性是支持层级权限继承，OrgTagCacheService.java 负责计算用户的有效组织标签，确保用户在拥有父级标签时自动获得所有子级标签的访问权限。为了提高查询性能，系统使用 Redis 缓存用户的有效组织标签信息。
当用户上传文件时，前端的 upload-dialog.vue 提供了直观的权限设置界面。管理员可以通过级联选择器选择任意组织标签，而普通用户只能选择自己被分配的组织标签。同时，用户需要设置文件的可见性级别，选择公开或私有。后端的 UploadController.java 在处理文件上传时会接收这些权限参数，如果用户未指定组织标签，系统会自动使用用户的主组织标签，确保每个文件都有明确的权限归属。
系统的权限控制核心在于 OrgTagAuthorizationFilter.java，这个过滤器统一处理所有 API 请求的权限验证。它采用了智能的权限判断逻辑：公开资源直接允许访问，默认组织或无组织标签的资源也允许访问，私有标签资源仅限所有者和管理员访问，其他情况则需要检查用户的有效组织标签是否与资源的组织标签匹配。
在知识检索环节，HybridSearchService.java 的 searchWithPermission 方法确保用户只能检索到有权限访问的内容。系统会获取用户的有效组织标签，并在 Elasticsearch 查询中添加相应的权限过滤条件，无论是向量搜索还是文本搜索都会应用这些权限限制。
最终，用户通过 DocumentService.java 只能看到自己有权访问的文件和内容。这包括用户自己上传的文件、标记为公开的文件、用户所属组织标签的文件以及默认组织的文件。
这套权限管理体系的技术特色体现在多个方面：层级权限继承机制让组织结构管理更加灵活，Redis 缓存能显著提升权限查询性能，统一的权限过滤器确保了所有 API 的一致性安全控制。从文件上传到知识检索的全链路权限控制则构建了完整的数据安全防护体系。
三、技术架构设计
平台采用了分层架构设计，从上到下分为前端展示层、API 与安全层、业务逻辑层、数据访问层和数据存储层，同时集成了外部依赖服务，形成了完整的企业级应用架构。
前端是一个 Vue 3 + Vite 构建的 Web 应用，使用响应式布局适配桌面与移动浏览器，确保用户在不同设备上获得一致的使用体验。前端与后端通过标准化的 API 接口进行通信，前后端完全分离。
前端技术栈包括：
- 框架：Vue 3 + TypeScript
- 构建工具：Vite
- UI 组件库：Naive UI
- 状态管理：Pinia
- HTTP 客户端：Axios
- 实时通信：WebSocket
安全层是整个系统的防护屏障，集成了多重安全机制。RESTful API 提供了标准化的接口服务，Spring WebSocket 支持实时通信功能，这对于聊天对话等交互场景至关重要。Spring Security 框架负责整体的安全控制，而 JWT 认证机制则确保了无状态的用户身份验证。
业务逻辑层是系统的核心，分为四个主要功能模块。用户管理模块包含 BCrypt 加密、JWT Token 生成和组织标签权限控制。文件上传与处理模块实现了分片上传、断点续传、文件合并和异步任务调度等功能。知识库检索模块负责混合检索（向量召回 + BM25 rescore 重排）、ES 索引管理和文件权限过滤，这是智能检索功能的技术基础。对话交互模块集成了 WebSocket 流式输出、Prompt 构建、DeepSeek Client、ReAct 工具调用和会话管理，可以为用户提供流畅的 AI 对话体验。
数据访问层用了 Spring Data JPA 来简化数据库操作，Hibernate 作为 ORM 框架用来实现对象的关系映射。
数据存储层采用了多元化的存储策略。MySQL 作为主数据库，存储用户信息、文件元数据等结构化数据。Redis 作为缓存服务，用于存储会话信息、权限缓存等热点数据。MinIO 对象存储专门处理文件存储需求，支持大容量文件的分布式存储。Elasticsearch 负责全文检索和向量搜索；FAISS 在规划中，Meta 开源的向量数据库未来可以优化大规模向量相似度计算，当前版本尚未接入。
平台还集成了多个外部服务。DeepSeek API 用于智能对话和内容生成。阿里云百炼 Embedding API 负责文本向量化，将自然语言转换为数学向量，这是实现语义检索的关键，并配套了两阶段 token 配额。Kafka 消息队列处理异步任务，确保系统的高并发处理能力。LogBack 提供了完善的日志管理，支持系统监控和问题排查。Apache Tika 负责多格式文档解析，支持 PDF、Word、Excel 等多种文件格式的内容提取；扫描件场景由阿里云 OCR 兜底。
整个后端技术栈包括：
- 框架：Spring Boot 3.x
- 开发语言：Java 17+
- 数据库：MySQL 8.0
- 缓存：Redis
- 搜索引擎：Elasticsearch
- 消息队列：Apache Kafka
- 文档解析：Apache Tika
- 容器化：Docker + Docker Compose
- 负载均衡：Nginx
- 监控：日志记录和性能监控
- 安全：HTTPS + JWT 认证
四、系统设计要点
数据一致性是大多数系统面临的核心挑战，平台通过多层次的保障机制来确保数据在 MySQL、Elasticsearch 和 MinIO 三个存储系统中的一致性。我们为每个文件建立了完整的生命周期跟踪机制。
当文件上传到 MinIO 后，系统会在状态表中记录"已上传"状态；当文档被解析并索引到 Elasticsearch 时，状态更新为"已索引"；当向量化完成后，状态变为"处理完成"。
下一个版本打算追加一个定时任务，定期扫描状态表，识别异常记录，比如文件已上传但长时间未完成索引的情况。针对这些异常，系统自动触发重试机制，重新执行失败的处理步骤。对于无法自动修复的数据，系统生成告警通知管理员人工介入。
当用户删除文件时，系统会按照预定义的顺序依次清理 Elasticsearch 索引、MinIO 文件和 MySQL 记录。
平台采用了多层防护策略，JWT 身份认证作为第一道防线，提供无状态的用户身份验证机制。同时，令牌的过期机制和刷新策略，也能够最大程度确保用户身份的安全与登录体验。
基于角色的权限控制定义了用户、管理员等不同角色的基础权限边界，而组织标签权限则在此基础上实现了更细粒度的数据访问控制，让企业能够灵活地管理复杂的组织结构和权限需求。
数据隔离通过组织标签实现了多租户架构下的数据安全。每个文件和知识条目都会标记所属的组织标签，系统在所有数据访问点都会验证用户的组织标签权限。这种设计不仅保护了数据安全，还支持企业内部不同部门或项目的数据隔离需求。当文件上传、删除、权限变更时，也会记录日志，确保在出现异常时，能够第一时间追溯到问题。
五、开发计划
我们采用了分阶段开发模式，总共规划了三个主要开发阶段，每个阶段都有明确的功能目标和技术重点。
第一阶段：核心功能（已完成）
- 基础用户管理、文件上传和处理功能
- 基于 Elasticsearch 的混合检索系统
- 基于 RAG 技术的聊天助手功能
第二阶段：组织权限（当前阶段），重点解决多租户场景下的权限管理和数据隔离问题，通过层级化的组织标签系统实现了细粒度的访问控制。
- 组织标签管理系统的实现
- 扩展文件上传流程，支持组织标签关联
- 基于组织标签的权限过滤机制
第三阶段：高级功能与优化（规划中）
- 优化 Prompt 构建和管理机制，让整个 RAG 检索出来的结果更加符合检索条件的语义。
- 完善数据源的数据保障机制，比如说前面提到的用定时任务去扫描状态不一致的数据，进行自动补偿。
- 优化系统性能和用户体验，比如说接入 FAISS，目前我们在用 Elasticsearch 进行向量检索，但随着数据规模的增长，FAISS 能够提供更高效的大规模向量相似度计算能力。
六、小结
就目前来说，平台已经通过整合 RAG 技术和多租户权限控制，为企业提供了一个高效、安全、基于 AI 的知识库问答平台。
我们的优势在于：
- 智能混合检索：结合向量相似度和关键词匹配，能够提供更准确的搜索结果
- 组织级权限管理：通过简化的标签机制实现
- 数据隔离和共享：基于组织标签的多租户数据隔离
- 高质量的聊天助手服务：基于知识库进行的聊天对话，而不是单纯和大模型进行文字 battle
下一版我们还想做的，包括：
- 集成 FAISS 提升大规模向量检索性能
- 增强多模态内容支持，能够处理图像和音频等非文本内容
- 开发更细粒度的权限控制和数据分析功能
- 优化用户界面，提供更直观的知识探索体验