# HzsparrowAI **Repository Path**: jw2217287/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**: 0 - **Forks**: 30 - **Created**: 2025-05-17 - **Last Updated**: 2025-05-17 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 智能知识库问答系统 这是一个基于Spring Boot的AI聊天应用，集成了Spring AI和Ollama，实现了RAG（检索增强生成）功能的知识库问答系统。用户可以创建并管理知识库，添加文档，并通过智能问答功能检索知识库中的信息。 ## 重要事项 由于SpringAI目前还没有发布稳定版本，现在用的都是快照版本，所以在运行项目时可能会遇到ClassNotFound等错误，这是由于SpringAI团队现阶段会经常增删改造项目结构，更新快照后原来的类或方法就可能会被删掉。有技术能力的小伙伴可以查看官方文档按最新的文档改造，作者也会持续关注开发动态，及时修改项目代码。 ## 系统截图 以下是系统的主要功能界面截图： ### 智能对话界面 通过智能对话界面，用户可以与AI进行自然语言交互，选择不同知识库进行问答。 ![智能对话界面](imgs/智能对话.jpg) ### 知识库管理 知识库管理界面允许用户创建、查看和管理自己的知识库。 ![知识库管理](imgs/知识库.jpg) ### 文档列表 每个知识库中的文档列表，用户可以查看、添加和删除文档。 ![文档列表](imgs/文档列表.jpg) ### 文档内容查看 查看知识库中的文档详细内容，支持Markdown格式显示。 ![文档内容](imgs/文档内容.jpg) ## 功能特点 - **AI聊天**：基于Ollama的自然语言交互 - **知识库选择**：可选择特定知识库进行问答或使用普通模式回答 - **知识库管理**：支持创建、查看和管理多个知识库 - **文档管理**：上传、查看和管理知识库中的文档 - **对话管理**：创建、查看和管理多个对话，支持对话标题修改 - **RAG功能**：结合ElasticSearch向量存储实现检索增强生成 - **流式响应**：实时流式显示AI回答 - **用户认证**：JWT认证和基于角色的访问控制 - **聊天历史**：记录和管理用户的聊天历史 - **文件上传**：支持通用文件上传和直接上传至知识库的功能 - **用户友好界面**：简洁的Web界面，支持Markdown格式显示 ## 技术栈 - **后端**： - Spring Boot 3.4.2 - Spring AI 1.0.0 - Spring AI Ollama集成 - Spring Security + JWT认证 - MyBatis-Plus 3.5.11 - ElasticSearch向量存储 - WebSocket通信 - **文档处理**： - Spring AI Tika文档解析 - FlexMark (用于Markdown转换) - **前端**： - HTML/CSS/JavaScript - Marked.js (Markdown解析) - 响应式设计，适配不同设备 ## 系统要求 - Java 17+ - MySQL 5.7+ - Maven 3.6+ - ElasticSearch 8.x - Ollama服务 ## 安装说明 ### 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` 文件，设置以下配置： - Ollama服务地址 - ElasticSearch连接信息 - 数据库连接信息 - JWT密钥配置 此处配置有可能不是最新的，最新配置以application-dev.yml为准。 ```yaml spring: ai: ollama: base-url: http://your-ollama-server:11434 chat: options: model: your-preferred-model vectorstore: type: elasticsearch openai: base-url: your-openai-compatible-api api-key: your-api-key elasticsearch: uris: your-elasticsearch-server:9200 username: username password: password datasource: url: jdbc:mysql://localhost:3306/ai_knowledge_base?useUnicode=true&characterEncoding=utf-8 username: your-db-username password: your-db-password jwt: secret: your-secret-key expiration: 86400000 # 24小时过期 ``` ### 4. 构建项目 ```bash mvn clean install ``` ### 5. 运行应用 ```bash mvn spring-boot:run ``` ## 使用方法 ### 访问Web界面 打开浏览器访问：`http://localhost:8080` ### 用户注册与登录 - 初始管理员账户：用户名 `admin`，密码 `admin` - 用户可以通过登录页面注册新账户 ### 知识库管理 1. 登录系统后，点击顶部的"知识库管理"标签 2. 可以创建新知识库，查看已有知识库 3. 点击知识库可以进入文档管理界面 4. 可以添加、查看和管理知识库中的文档 ### 文件上传 1. 可以通过通用上传接口上传文件 2. 也可以将文件直接上传到指定知识库 3. 支持常见文档格式，包括PDF、Word、文本等 ### 对话管理 1. 创建新对话或查看已有对话 2. 可以修改对话的标题 3. 支持分页查看对话列表 4. 可以删除不需要的对话 ### 智能问答 1. 在"对话"标签中，可以选择要使用的知识库或选择"不使用知识库" 2. 输入问题后，系统会根据选择的知识库进行回答 3. 若选择了知识库，系统会检索相关文档提供更准确的回答 4. 若未选择知识库，系统将使用模型的通用知识回答 ## API端点 ### 身份认证API - **登录**：`POST /api/auth/login` - 请求体：`{"username": "用户名", "password": "密码"}` - 返回：JWT令牌 - **注册**：`POST /api/auth/register` - 请求体：用户信息JSON - 返回：注册成功确认 ### 聊天API - **聊天**：`GET /api/chat` - 方法：GET - 参数： - `message`：用户问题 - `knowledgeBaseId`（可选）：知识库ID - 返回：AI回答（流式响应） ### 对话管理API - **获取对话列表**：`GET /api/conversation/list` - **分页获取对话**：`GET /api/conversation/page` - **创建新对话**：`POST /api/conversation/create` - **获取对话详情**：`GET /api/conversation/{id}` - **通过会话ID获取对话**：`GET /api/conversation/session/{sessionId}` - **更新对话标题**：`PUT /api/conversation/title/{sessionId}` - **删除对话**：`DELETE /api/conversation/{id}` ### 知识库API - **获取知识库列表**：`GET /api/knowledge-base/list` - **创建知识库**：`POST /api/knowledge-base/create` - **获取知识库详情**：`GET /api/knowledge-base/{id}` - **更新知识库**：`PUT /api/knowledge-base/{id}` - **删除知识库**：`DELETE /api/knowledge-base/{id}` ### 文档API - **获取文档列表**：`GET /api/document/list` - **添加文档**：`POST /api/document/add` - **获取文档详情**：`GET /api/document/{id}` - **删除文档**：`DELETE /api/document/{id}` ### 文件上传API - **上传文件**：`POST /api/files/upload` - **上传文件至知识库**：`POST /api/files/upload-to-knowledge-base` ### 聊天历史API - **获取会话列表**：`GET /api/chat-history/sessions` - **获取会话历史**：`GET /api/chat-history/session/{sessionId}` - **获取最近历史**：`GET /api/chat-history/recent` - **删除会话历史**：`DELETE /api/chat-history/session/{sessionId}` ## 项目结构 ``` src/main/java/com/hzsparrow/ai/ ├── config/ # 配置类 │ ├── PromptConfiguration.java # 提示词配置 │ ├── SecurityConfig.java # 安全配置 │ ├── DataInitializer.java # 数据初始化器 │ └── FileUploadConfig.java # 文件上传配置 ├── controller/ # 控制器 │ ├── AuthController.java # 认证控制器 │ ├── ChatController.java # 聊天控制器 │ ├── ConversationController.java # 对话控制器 │ ├── ChatHistoryController.java # 聊天历史控制器 │ ├── KnowledgeBaseController.java # 知识库控制器 │ ├── DocumentController.java # 文档控制器 │ └── FileUploadController.java # 文件上传控制器 ├── entity/ # 实体类 │ ├── User.java # 用户实体 │ ├── KnowledgeBase.java # 知识库实体 │ ├── Document.java # 文档实体 │ ├── Conversation.java # 对话实体 │ └── ChatHistory.java # 聊天历史实体 ├── service/ # 服务层 │ ├── ChatService.java # 聊天服务接口 │ ├── ConversationService.java # 对话服务接口 │ ├── ConversationServiceImpl.java # 对话服务实现 │ ├── KnowledgeBaseService.java # 知识库服务接口 │ ├── KnowledgeBaseServiceImpl.java # 知识库服务实现 │ ├── DocumentService.java # 文档服务接口 │ ├── DocumentServiceImpl.java # 文档服务实现 │ ├── ChatHistoryService.java # 聊天历史服务 │ ├── FileService.java # 文件服务接口 │ ├── FileServiceImpl.java # 文件服务实现 │ └── UserService.java # 用户服务 ├── mapper/ # MyBatis映射器 ├── security/ # 安全相关 │ ├── JwtUtils.java # JWT工具类 │ └── JwtAuthenticationFilter.java # JWT认证过滤器 ├── util/ # 工具类 │ └── FileUtils.java # 文件处理工具 └── HzsparrowAiApplication.java # 应用入口类 src/main/resources/ ├── static/ # 静态资源 │ ├── css/ # 样式文件 │ ├── js/ # JavaScript文件 │ ├── index.html # 主页面 │ └── login.html # 登录页面 ├── mapper/ # MyBatis映射文件 ├── prompts/ # 提示词文件 │ ├── general-chat-prompt.txt # 普通对话提示词 │ └── vector-chat-prompt.txt # 向量搜索对话提示词 ├── sql/ # SQL脚本 │ └── schema.sql # 数据库结构脚本 └── application.yml # 应用配置文件 ``` ## 自定义开发 ### 修改提示词模板 编辑 `src/main/resources/prompts/` 目录下的提示词文件： - `general-chat-prompt.txt` - 普通聊天提示词 - `vector-chat-prompt.txt` - 知识库检索提示词 ### 调整分词和检索参数 在 `ChatService.java` 中可以调整 `SearchRequest` 的相关设置，如相似度阈值和返回结果数量，以优化检索效果。 ## 许可证 Apache License 2.0