白泽是一个企业级的 AI 知识库管理系统，采用检索增强生成（RAG）技术，提供智能文档处理和检索能力。

核心技术栈包括 ElasticSearch、Kafka、WebSocket、Spring Security、Docker、MySQL 和 Redis。

它的目标是帮助企业和个人更高效地管理和利用知识库中的信息，支持多租户架构，允许用户通过自然语言查询知识库，并获得基于自身文档的 AI 生成响应。

系统允许用户：

• 上传和管理各种类型的文档
• 自动处理和索引文档内容
• 使用自然语言查询知识库
• 接收基于自身文档的 AI 生成响应

用到的技术栈包括，先说后端的：

• 框架 : Spring Boot 3.4.2 (Java 17)
• 数据库 : MySQL 8.0
• ORM : Spring Data JPA
• 缓存 : Redis
• 搜索引擎 : Elasticsearch 8.10.0
• 消息队列 : Apache Kafka
• 文件存储 : MinIO
• 文档解析 : Apache Tika
• 安全认证 : Spring Security + JWT
• AI集成 : vLLM (Qwen3.5-9B) / 可选 DeepSeek API + 阿里云 DashScope Embedding (Qwen3-Embedding-0.6B)
• 实时通信 : WebSocket
• 依赖管理 : Maven
• 响应式编程 : WebFlux

后端的整体项目结构：

src/main/java/com/yizhaoqi/smartpai/
├── SmartPaiApplication.java      # 主应用程序入口
├── client/                       # 外部API客户端
├── config/                       # 配置类
├── consumer/                     # Kafka消费者
├── controller/                   # REST API端点
├── entity/                       # 数据实体
├── exception/                    # 自定义异常
├── handler/                      # WebSocket处理器
├── model/                        # 领域模型
├── repository/                   # 数据访问层
├── service/                      # 业务逻辑
└── utils/                        # 工具类

再说前端的，包括：

• 框架 : Vue 3 + TypeScript
• 构建工具 : Vite
• UI组件 : Naive UI
• 状态管理 : Pinia
• 路由 : Vue Router
• 样式 : UnoCSS + SCSS
• 图标 : Iconify
• 包管理 : pnpm

前端的整体项目结构：

frontend/
├── packages/           # 可重用模块
├── public/             # 静态资源
├── src/                # 主应用程序代码
│   ├── assets/         # SVG图标，图片
│   ├── components/     # Vue组件
│   ├── layouts/        # 页面布局
│   ├── router/         # 路由配置
│   ├── service/        # API集成
│   ├── store/          # 状态管理
│   ├── views/          # 页面组件
│   └── ...            # 其他工具和配置
└── ...               # 构建配置文件

核心功能

知识库管理

白泽提供了完整的文档上传与解析功能，支持文件分片上传和断点续传，并支持标签进行组织管理。文档可以是公开的，也可以是私有的，并且可以与特定的组织标签关联，以便更好地进行权限分类。

AI驱动的RAG实现

白泽的核心是 RAG 实现：

• 将上传的文档进行语义分块
• 调用千问 Embedding 模型为每个文本块生成高维向量
• 将向量存储到 ElasticSearch 以支持语义搜索和关键词搜索
• 可以根据用户的查询检索相关文档
• 为 LLM 提供完整的上下文，从而生成更准确、基于文档的响应内容

企业级多租户

白泽通过组织标签支持多租户架构。每个用户可以创建或加入一个或多个组织，每个组织可以拥有独立的知识库和文档管理。这样，企业可以在同一系统中管理多个团队或部门的知识库，而无需担心数据混淆或权限问题。

实时通信

系统采用 WebSocket 技术，提供用户与 AI 系统之间的实时交互，支持响应式聊天界面，便于知识检索和 AI 互动。

前置环境

在开始之前，请确保已安装以下软件：

• Java 17
• Maven 3.8.6 或更高版本
• Node.js 18.20.0 或更高版本
• pnpm 8.7.0 或更高版本
• MySQL 8.0
• Elasticsearch 8.10.0
• MinIO 8.5.12
• Kafka 3.2.1
• Redis 7.0.11
• Docker（可选，用于运行 Redis、MinIO、Elasticsearch 和 Kafka 等服务）

架构设计

白泽的架构具备一个现代化的、云原生应用程序的特点，具有清晰的关注点分离、可扩展的组件和与 AI 技术的集成。模块化设计允许随着技术的发展，特别是快速变化的 AI 集成领域，未来可以扩展和替换单个组件。

控制层用于处理 HTTP 请求，验证输入，管理请求/响应格式化，并将业务逻辑委托给服务层。控制器按领域功能组织。遵循 RESTful 设计原则，集成了性能监控和日志记录，用于跟踪 API 使用和故障排除。

@RestController
@RequestMapping("/api/v1/documents")
public class DocumentController {
    @Autowired
    private DocumentService documentService;
    
    @DeleteMapping("/{fileMd5}")
    public ResponseEntity<?> deleteDocument(
            @PathVariable String fileMd5,
            @RequestAttribute("userId") String userId,
            @RequestAttribute("role") String role) {
        // 参数验证和委托给服务
        documentService.deleteDocument(fileMd5);
        // 响应处理
    }
}

服务层主要用来处理应用的业务逻辑，具有事务感知能力，能够处理跨越多个数据源的操作。

@Service
public class DocumentService {
    @Autowired
    private FileUploadRepository fileUploadRepository;
    
    @Autowired
    private MinioClient minioClient;
    
    @Autowired
    private ElasticsearchService elasticsearchService;
    
    @Transactional
    public void deleteDocument(String fileMd5) {
        // 文档删除的业务逻辑
        // 协调多个仓储和系统
    }
}

数据访问层使用 Spring Data JPA 进行数据库操作，提供了对 MySQL 的 CRUD 操作。

@Repository
public interface FileUploadRepository extends JpaRepository<FileUpload, Long> {
    Optional<FileUpload> findByFileMd5(String fileMd5);
    
    @Query("SELECT f FROM FileUpload f WHERE f.userId = :userId OR f.isPublic = true OR (f.orgTag IN :orgTagList AND f.isPublic = false)")
    List<FileUpload> findAccessibleFilesWithTags(@Param("userId") String userId, @Param("orgTagList") List<String> orgTagList);
}

实体层由映射到数据库表的 JPA 实体以及用于 API 请求和响应的 DTO（数据传输对象）组成。

@Entity
public class FileUpload {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    private String fileMd5;
    private String fileName;
    private String userId;
    private boolean isPublic;
    private String orgTag;
    // 其他字段和方法
}

Docker启动

# 进入Docker目录
cd docs/operations

# 部署（MinIO bucket 会自动创建，无需手动）
sudo docker compose up -d

# 查看所有容器状态
sudo docker compose ps

# 查看容器日志
sudo docker compose logs mysql
sudo docker compose logs redis
sudo docker compose logs kafka
sudo docker compose logs minio
sudo docker compose logs es

# 测试各服务是否可以连接
# MySQL
sudo docker exec mysql mysqladmin ping -h localhost -u root -pBaize

# Redis
sudo docker exec redis redis-cli -a Baize ping

# Elasticsearch（用户名 elastic，密码 Baize）
curl -u elastic:Baize http://localhost:9200

# MinIO 控制台（用户名 admin，密码 Baize2026）
curl http://localhost:19001

# 查看资源占用
sudo docker stats --no-stream

# 停止容器（数据保留）
sudo docker compose down

# 停止并删除数据（慎用！会丢失所有数据）
# sudo docker compose down -v

准备项目根目录 .env

cp .env.example .env

配置API

DEEPSEEK_API_URL=http://localhost:3598/v1 DEEPSEEK_API_MODEL=Qwen3.5-9B DEEPSEEK_API_KEY= EMBEDDING_API_URL=http://localhost:6666/v1 EMBEDDING_API_MODEL=Qwen3-Embedding-0.6B EMBEDDING_API_KEY=

后端启动

mvn spring-boot:run

前端启动

# 进入前端项目目录
cd frontend

# 安装依赖
pnpm install

# 启动项目
pnpm run dev

<<<<<<< HEAD

=======

## Docker启动

```bash
#进入Docker目录
cd docs

#安装部署
sudo docker compose up -d

#查看所有容器状态
sudo docker compose ps

#查看容器日志
sudo docker compose logs mysql
sudo docker compose logs redis
sudo docker compose logs kafka
sudo docker compose logs minio
sudo docker compose logs es

#测试各服务是否可以连接
# MySQL
sudo docker exec mysql mysqladmin ping -h localhost -u root -pPaiSmart2025

# Redis
sudo docker exec redis redis-cli -a PaiSmart2025 ping

# Elasticsearch
curl http://localhost:9200

# MinIO 控制台
curl http://localhost:19001

#查看资源占用
sudo docker stats --no-stream

origin/main