# 基于SpringAI开发的智能客服+哄哄模拟器+ChatPDF

**Repository Path**: make-it-easy/springaI-demo

## Basic Information

- **Project Name**: 基于SpringAI开发的智能客服+哄哄模拟器+ChatPDF
- **Description**: SpringAI+Function Calling+RAG+ES+Prompt Engineering
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2026-08-06
- **Last Updated**: 2026-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<h1 align="center">🤖 Spring AI Q&A Assistant Demo</h1>

<p align="center">
  <strong>基于 Spring Boot 3.4.3与 Spring AI 1.1.3 构建的智能问答演示项目</strong>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Java-17+-blue.svg" alt="Java 17+">
  <img src="https://img.shields.io/badge/Spring%20Boot-3.4.3-brightgreen.svg" alt="Spring Boot 3.4.3">
  <img src="https://img.shields.io/badge/Spring%20AI-1.1.3-green.svg" alt="Spring AI 1.1.3">
  <img src="https://img.shields.io/badge/Vue.js-3.x-4FC08D.svg" alt="Vue 3">
  <img src="https://img.shields.io/badge/Elasticsearch-Vector%20Store-yellow.svg" alt="Elasticsearch Vector">
</p>

---

## 📖 引言

随着大模型（LLM）技术的飞速发展，AI技术与传统业务系统的结合正在重塑软件开发的边界。本项目旨在作为一个开箱即用的**Spring AI 智能助手全栈演示案例**，展示了如何使用最新的 Spring AI 框架优雅地接入大语言模型，并结合 Vue 3 前端提供流畅的用户体验。本项目深度整合了 Elasticsearch 向量数据库与阿里云百炼（DashScope）大模型接口，为您开发自己的 RAG（检索增强生成）应用或智能对话平台提供绝佳的参考起点。

无论是想了解最新 Spring AI 架构，还是想快速搭建一个拥有记忆和检索能力的智能对话项目，本项目都将是您的得力助手！

---

## ✨ 核心特性

- **前沿架构**：采用最新的 Spring Boot 3.4.3 结合 Spring AI 1.1.3 版本，全面拥抱最新的大模型接入标准。
- **向量检索检索 (RAG)**：内置 Elasticsearch 向量存储集成，轻松实现结合私有知识库的智能对话。
- **一键切换**：配置已兼容 OpenAI 规范的 API，项目默认对接阿里通义千问模型（`qwen3.5-plus`），在国内网络环境下拥有稳定且极速的体验。
- **现代化前端**：采用主流的 Vue 3 + Vite 构建，TypeScript 严格规范，配合 Axios 轻松对接后端接口。

---

## 🛠 开发环境要求

在克隆代码并尝试运行之前，请确保您的本地开发环境满足以下条件：

### 核心环境
- [x] **Java 17 及以上版本**（后端必备）
- [x] **Node.js 18+**（前端必备）
- [x] **Maven 3.6+** 

### 中间件/服务依赖
- [x] **MySQL 8.0+ / 5.7**
- [x] **Elasticsearch 服务** (推荐版本 8.x，用于支持向量检索引擎)
- [x] **Ollama** (必须，用于本地大模型服务节点)
- [x] **阿里云百炼（DashScope）API Key 密钥**（或者是任意兼容 OpenAI 接口的 API Key）

---

## 🚀 快速开始与配置修改指引

> **⚠️ 致克隆本代码的开发者：**  
> 想要在你的电脑上成功跑通这个项目，你需要对几个简单的配置进行修改。请严格按照下方的指引操作！

### 一、后端启动指引

后端代码目录位于 `heima-ai/` 文件夹内：

1. **导入项目**：使用 IDEA 或其他IDE将 `heima-ai/pom.xml` 作为 Maven 项目导入。
2. **修改数据库配置**：
   打开文件 `heima-ai/src/main/resources/application.yml`，修改如下配置：
   ```yaml
   spring:
     datasource:
       # 如果您的数据库不是本地或端口不是3306，请修改这里的url
       url: jdbc:mysql://127.0.0.1:3306/itheima?serverTimezone=GMT%2B8
       username: root       # 替换为您的 MySQL 账号
       password: 123456     # ❗【必改项】替换为您的 MySQL 密码
   ```
3. **配置 Elasticsearch**：
   如果您的 ES 未运行在本地 9200 端口，请修改：
   ```yaml
   spring:
     elasticsearch:
       uris: http://localhost:9200 # ❗如有需要，请修改为实际 ES 地址
   ```
4. **启动并配置 Ollama（本地大模型）**：
   本项目由于集成了本地模型方案，请确保您已经安装开启了 Ollama，并拉取了配置中的模型。
   - 打开终端执行以下命令直接拉取并运行 `qwen2.5:3b` 模型即可：
     ```bash
     ollama run qwen2.5:3b
     ```
   - 此操作会在本地 `11434` 端口暴露 `http://localhost:11434` 服务供后端调用。

5. **配置 AI 模型秘钥（API KEY）**：
   本项目默认配置直接读取名为 `KEY` 的系统环境变量。
   - **方式一（推荐）**：在系统环境变量或你的IDE启动环境变量配置中，添加名为 `KEY` ，值为你的API Key（如 `sk-xxxxxx`）的环境变量。
   - **方式二（硬编码，仅限本地测试）**：直接在 application.yml 中修改：
     ```yaml
     spring:
       ai:
         openai:
           api-key: sk-你的真实API_KEY_放在这里  # ❗【必改项】
     ```
   *(注：如果想改用 OpenAI 或其他模型，可同步修改 base-url 和 model 名字)*

6. **启动项目**：运行主类启动后端服务即可。

---

### 二、前端启动指引

前端项目目录位于 `spring-ai-protal/` 文件夹内。打开命令行终端：

```bash
# 1. 切换到前端目录
cd spring-ai-protal

# 2. 运行前端开发服务器
npm run dev
```
项目将在终端打印出通常为 `http://localhost:5173/` 的本地访问地址。如有接口跨域/代理需求，请前往 `vite.config.ts` 进行相关自定配置。

---

## 🤝 参与贡献

我们欢迎任何形式的贡献！无论是一个错别字的修复，还是一个全新功能的加入，都会让这个项目变得更好。如果您有新的想法，可以先提交一个 Issue 与大家探讨，或者直接发起 Pull Request。

## 📄 许可证 (License)

本项目采用 [MIT License](LICENSE) 许可协议。您可以自由地在商业或非商业项目中使用、修改本项目代码。