# HzsparrowAI

**Repository Path**: flvf/hzsparrow-ai

## Basic Information

- **Project Name**: HzsparrowAI
- **Description**: HzsparrowAI是一个基于SpringAI搭建的AI软件，这其实是个学习、测试项目，为了不沦为demo项目，所有的需求和功能都将保证基本可用。欢迎start，欢迎isuse，欢迎加入。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 74
- **Forks**: 22
- **Created**: 2025-04-09
- **Last Updated**: 2025-09-05

## Categories & Tags

**Categories**: ai

**Tags**: None

## README

# 智能知识库问答系统

这是一个基于Spring Boot的AI聊天应用，集成了Spring AI和Ollama，实现了RAG（检索增强生成）功能的知识库问答系统。用户可以创建并管理知识库，添加文档，并通过智能问答功能检索知识库中的信息。

## 重要事项

SpringAI已经发布了1.0.0稳定版本，但现在依然在飞速发展，在主要功能稳定前，作者也会视情况更新依赖版本。如果此项目对你有用，请麻烦给个star，这对作者很重要，谢谢支持。

## 系统截图

以下是系统的主要功能界面截图：

### 智能对话界面

通过智能对话界面，用户可以与AI进行自然语言交互，选择不同知识库进行问答。

![智能对话界面](imgs/智能对话.jpg)

### 知识库管理

知识库管理界面允许用户创建、查看和管理自己的知识库。

![知识库管理](imgs/知识库.jpg)

### 文档列表

每个知识库中的文档列表，用户可以查看、添加和删除文档。

![文档列表](imgs/文档列表.jpg)

### 文档内容查看

查看知识库中的文档详细内容，支持Markdown格式显示。

![文档内容](imgs/文档内容.jpg)

### 平台设置

设置平台的系统信息，主要用来设置默认模型。

![平台设置](imgs/平台设置.jpg)

### 模型设置

可以在平台中预置多种模型，解决模型需要灵活多变的需求。

![模型设置](imgs/模型设置.jpg)

## 核心功能

### 🤖 智能对话
- 基于Ollama的自然语言交互
- 支持流式响应，实时显示AI回答
- 多模型支持，可灵活切换不同AI模型

### 📚 知识库管理
- 创建、查看和管理多个知识库
- 支持知识库的增删改查操作
- 知识库权限管理

### 📄 文档管理
- 支持多种文档格式上传（PDF、Word、TXT、Markdown等）
- 文档内容自动解析和向量化存储
- 文档预览和内容管理
- 批量文档处理

### 💬 对话管理
- 创建、查看和管理多个对话会话
- 支持对话标题自定义修改
- 对话历史记录和搜索
- 对话上下文保持

### 🔍 RAG检索增强
- 基于ElasticSearch的向量存储
- 智能文档检索和相关性匹配
- 检索结果与生成内容的有机结合
- 可调节的相似度阈值

### 👤 用户系统
- JWT身份认证和授权
- 基于角色的访问控制
- 用户注册和登录管理
- 用户数据隔离

### 🎨 用户体验
- 现代化响应式Web界面
- 支持Markdown格式渲染
- 移动设备友好的设计
- 直观的操作交互

## 技术架构

### 后端技术栈
- **Spring Boot 3.4.2** - 应用框架
- **Spring AI 1.0.0** - AI集成框架
- **Spring Security + JWT** - 安全认证
- **MyBatis-Plus 3.5.11** - 数据持久化
- **ElasticSearch** - 向量存储和检索
- **WebSocket** - 实时通信
- **Spring AI Tika** - 文档解析
- **FlexMark** - Markdown处理

### 前端技术栈
- **HTML/CSS/JavaScript** - 基础前端技术
- **Marked.js** - Markdown解析渲染
- **响应式设计** - 适配多种设备

### AI服务支持
- **Ollama** - 本地大语言模型服务
- **OpenAI兼容API** - 支持多种AI服务提供商

## 环境要求

- **Java 17+**
- **MySQL 5.7+**
- **Maven 3.6+**
- **ElasticSearch 8.x**
- **Ollama服务** 或其他兼容的AI服务

## 快速开始

### 1. 克隆项目

```bash
git clone git@gitee.com:flvf/hzsparrow-ai.git
cd hzsparrow-ai
```

### 2. 数据库初始化

在MySQL中创建数据库：

```sql
CREATE DATABASE ai_knowledge_base CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

数据表会在应用首次启动时自动创建。如果没有自动创建，可使用 `sql/schema.sql` 文件手动创建。

### 3. 环境配置

环境配置详细说明请参考 [DEPLOY.md](DEPLOY.md)

编辑 `src/main/resources/application-dev.yml` 文件，配置以下关键信息：

```yaml
spring:
  ai:
    # 向量存储配置
    vectorstore:
      type: elasticsearch
      elasticsearch:
        initialize-schema: true
        index-name: "your-index-name"
        dimensions: 1024
        similarity: cosine
  # ElasticSearch配置
  elasticsearch:
    uris: http://your-elasticsearch-server:9200
    username: your_username
    password: your_actual_password
    connection-timeout: 10s
    socket-timeout: 60s
  # 数据库配置
  datasource:
    url: jdbc:mysql://localhost:3306/ai_knowledge_base?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
    username: your_db_username
    password: your_actual_db_password

# 文件上传目录
ai:
  file:
    upload-dir: /path/to/your/uploads/  # 请修改为实际路径

# JWT配置
jwt:
  secret: your_very_long_and_secure_random_string_here
  expiration: 86400000 # 24小时过期
```

**主要配置项说明：**

- **ElasticSearch配置**：用于向量存储和检索，需要配置服务地址、用户名和密码
- **数据库配置**：MySQL连接信息，包括数据库URL、用户名和密码
- **JWT配置**：身份认证密钥，请使用长随机字符串确保安全
- **文件上传**：指定文件存储目录，建议使用绝对路径
- **AI服务配置**：系统支持多种AI服务，可根据需要配置相应的API信息

> **注意**：请将配置文件中的占位符替换为实际的服务地址、用户名、密码等信息。

### 4. 构建和运行

```bash
# 构建项目
mvn clean install

# 启动应用
mvn spring-boot:run
```

### 5. 访问系统

打开浏览器访问：`http://localhost:8080`

## 使用指南

### 初次使用

1. **登录系统**
   - 默认管理员账户：用户名 `admin`，密码 `admin`
   - 也可以通过注册页面创建新用户账户

2. **创建知识库**
   - 点击"知识库管理"标签
   - 创建新的知识库并设置相关信息

3. **上传文档**
   - 进入已创建的知识库
   - 上传相关文档文件
   - 系统会自动解析并向量化文档内容

### 智能问答

1. **选择对话模式**
   - 在"对话"标签中选择要使用的知识库
   - 或选择"不使用知识库"进行普通对话

2. **开始对话**
   - 输入问题，系统会根据选择的模式回答
   - 使用知识库模式时，系统会检索相关文档内容
   - 普通模式下，系统使用AI模型的通用知识

### 高级功能

1. **对话管理**
   - 创建多个对话会话
   - 自定义对话标题
   - 查看和管理历史对话

2. **文档管理**
   - 支持批量上传文档
   - 查看文档详细内容
   - 管理文档的增删改查

3. **系统设置**
   - 配置默认AI模型
   - 管理多种AI模型设置
   - 调整系统参数

## 项目结构

```
src/main/java/com/hzsparrow/ai/
├── config/                 # 配置类
│   ├── PromptConfiguration.java   # 提示词配置
│   ├── SecurityConfig.java        # 安全配置
│   ├── DataInitializer.java       # 数据初始化
│   └── FileUploadConfig.java      # 文件上传配置
├── controller/             # 控制器层
├── entity/                 # 实体类
├── service/                # 服务层
├── mapper/                 # 数据访问层
├── security/               # 安全认证
├── util/                   # 工具类
└── HzsparrowAiApplication.java    # 应用入口

src/main/resources/
├── static/                 # 前端静态资源
├── prompts/                # AI提示词模板
├── sql/                    # 数据库脚本
└── application.yml         # 应用配置
```

## 自定义开发

### 提示词定制

编辑 `src/main/resources/prompts/` 目录下的提示词文件：
- `general-chat-prompt.txt` - 普通聊天提示词
- `vector-chat-prompt.txt` - 知识库检索提示词

### 检索参数调优

在 `ChatService.java` 中调整以下参数来优化检索效果：
- 相似度阈值设置
- 检索结果数量
- 向量匹配算法

### 扩展功能

系统采用模块化设计，可以方便地扩展以下功能：
- 新的文档格式支持
- 更多AI模型集成
- 自定义检索算法
- 高级权限管理

## 贡献指南

欢迎提交Issue和Pull Request来改进项目：

1. Fork本项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建Pull Request

## 许可证

本项目基于 Apache License 2.0 开源协议发布。

## 支持与反馈

如果您在使用过程中遇到问题或有改进建议，请：

- 提交 [Issue](https://gitee.com/flvf/hzsparrow-ai/issues)
- 加入交流群讨论 QQ群：695709716
- 给项目点个 ⭐ Star 支持

---

**感谢您的使用和支持！**