# spring-ai-demo

**Repository Path**: chaocloud/spring-ai-demo

## Basic Information

- **Project Name**: spring-ai-demo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-18
- **Last Updated**: 2025-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring AI Demo 项目

🤖 一个基于 Spring Boot 和 Spring AI 的人工智能应用演示项目，展示了如何集成 OpenAI API 实现聊天、代码生成、文本摘要等功能。

## ✨ 功能特性

- 💬 **智能聊天**: 基于 OpenAI GPT 模型的对话功能
- 📝 **模板聊天**: 使用预定义模板生成特定风格的内容
- 💻 **代码生成**: 根据描述自动生成多种编程语言的代码
- 📄 **文本摘要**: 将长文本智能压缩为指定长度的摘要
- 🎨 **美观界面**: 响应式 Web 界面，支持移动端
- 🔧 **健康检查**: 服务状态监控接口

## 🛠️ 技术栈

- **Spring Boot 3.3.5**: 主框架
- **Spring AI 1.0.0-M4**: AI 集成框架
- **OpenAI API**: 人工智能服务
- **Lombok**: 简化 Java 代码
- **Maven**: 项目管理工具
- **HTML/CSS/JavaScript**: 前端界面

## 🚀 快速开始

### 1. 环境要求

- Java 21+
- Maven 3.6+
- OpenAI API Key

### 2. 克隆项目

```bash
git clone <your-repo-url>
cd spring-ai-demo
```

### 3. 配置 API Key

#### 方法一：环境变量（推荐）

```bash
# Windows
set OPENAI_API_KEY=your-openai-api-key

# Linux/Mac
export OPENAI_API_KEY=your-openai-api-key
```

#### 方法二：修改配置文件

编辑 `src/main/resources/application.properties`：

```properties
spring.ai.openai.api-key=your-openai-api-key
```

### 4. 运行项目

```bash
mvn spring-boot:run
```

### 5. 访问应用

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

## 📖 API 文档

### 基础路径

所有 API 的基础路径为：`/api/spring-ai`

### 接口列表

#### 1. 健康检查

```http
GET /api/spring-ai/health
```

**响应示例：**
```json
{
  "success": true,
  "data": "Spring AI Demo is running",
  "message": "服务正常运行",
  "timestamp": 1703123456789
}
```

#### 2. 简单聊天

```http
GET /api/spring-ai/chat?query=你好
```

**参数：**
- `query` (string): 用户输入的问题

**响应示例：**
```json
{
  "success": true,
  "data": "你好！我是AI助手，有什么可以帮助您的吗？",
  "message": "聊天成功"
}
```

#### 3. 模板聊天

```http
POST /api/spring-ai/chat/template
Content-Type: application/json

{
  "topic": "人工智能",
  "style": "专业"
}
```

**请求体：**
- `topic` (string): 话题
- `style` (string): 风格（专业、幽默、简洁、详细、通俗易懂）

#### 4. 代码生成

```http
POST /api/spring-ai/generate-code
Content-Type: application/json

{
  "language": "Java",
  "description": "实现一个快速排序算法"
}
```

**请求体：**
- `language` (string): 编程语言
- `description` (string): 功能描述

#### 5. 文本摘要

```http
POST /api/spring-ai/summarize
Content-Type: application/json

{
  "text": "这里是需要摘要的长文本...",
  "maxLength": 200
}
```

**请求体：**
- `text` (string): 需要摘要的文本
- `maxLength` (integer): 摘要最大长度（字数）

## ⚙️ 配置说明

### 主要配置项

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|----------|--------|------|
| `spring.ai.openai.api-key` | `OPENAI_API_KEY` | - | OpenAI API 密钥 |
| `spring.ai.openai.base-url` | `OPENAI_BASE_URL` | `https://api.openai.com/` | API 基础 URL |
| `spring.ai.openai.chat.options.model` | `OPENAI_MODEL` | `gpt-4o-mini` | 使用的模型 |
| `spring.ai.openai.chat.options.temperature` | `OPENAI_TEMPERATURE` | `0.7` | 创造性参数 |
| `spring.ai.openai.chat.options.max-tokens` | `OPENAI_MAX_TOKENS` | `2000` | 最大令牌数 |

### 支持的模型

- `gpt-4o-mini` (推荐，性价比高)
- `gpt-4o`
- `gpt-4-turbo`
- `gpt-3.5-turbo`

## 🏗️ 项目结构

```
src/
├── main/
│   ├── java/
│   │   └── org/example/demo/
│   │       ├── SpringbootLangchain4jDemoApplication.java  # 主启动类
│   │       ├── SpringAiController.java                   # REST 控制器
│   │       ├── config/
│   │       │   └── SpringAiConfig.java                   # AI 配置类
│   │       └── service/
│   │           └── SpringAiService.java                  # AI 服务类
│   └── resources/
│       ├── application.properties                        # 配置文件
│       └── static/
│           └── index.html                               # 演示页面
└── test/
    └── java/
```

## 🔧 开发指南

### 添加新功能

1. 在 `SpringAiService` 中添加新的服务方法
2. 在 `SpringAiController` 中添加对应的 REST 接口
3. 在前端页面中添加相应的 UI 和 JavaScript 代码

### 自定义模型配置

```java
@Bean
public OpenAiChatModel customChatModel(OpenAiApi openAiApi) {
    return OpenAiChatModel.builder()
        .withOpenAiApi(openAiApi)
        .withDefaultOptions(OpenAiChatOptions.builder()
            .withModel("gpt-4")
            .withTemperature(0.8)
            .withMaxTokens(1500)
            .build())
        .build();
}
```

## 🐛 故障排除

### 常见问题

1. **API Key 错误**
   - 检查环境变量是否正确设置
   - 确认 API Key 有效且有足够余额

2. **网络连接问题**
   - 检查网络连接
   - 如果在中国大陆，可能需要配置代理

3. **依赖冲突**
   - 运行 `mvn clean install` 重新构建
   - 检查 Java 版本是否为 21+

### 日志调试

启用详细日志：

```properties
logging.level.org.springframework.ai=DEBUG
logging.level.org.example.demo=DEBUG
```

## 📝 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📞 联系方式

如有问题，请通过以下方式联系：

- 提交 GitHub Issue
- 发送邮件至：[your-email@example.com]

---

⭐ 如果这个项目对您有帮助，请给个 Star！

## 项目简介

本项目展示了如何使用 Spring Boot 框架结合 LangChain4j 库来构建一个简单的 AI 聊天应用。项目使用 DeepSeek 作为底层的大语言模型提供商，通过 RESTful API 提供聊天服务。

## 技术栈

- **Java 21** - 编程语言
- **Spring Boot 3.5.0** - Web 框架
- **LangChain4j 1.0.1** - AI 集成框架
- **Lombok** - 减少样板代码的注解库
- **DeepSeek API** - 大语言模型服务
- **Maven** - 项目管理工具

## 项目结构

```
src/
├── main/
│   ├── java/
│   │   └── org/example/demo/
│   │       ├── SpringbootLangchain4jDemoApplication.java  # 主应用类
│   │       ├── ChatController.java                       # 聊天控制器
│   │       ├── config/
│   │       │   └── LangChain4jConfig.java               # LangChain4j 配置
│   │       └── service/
│   │           └── Assistant.java                       # AI 助手服务接口
│   └── resources/
│       ├── application.properties                        # 应用配置
│       ├── static/                                      # 静态资源
│       └── templates/                                   # 模板文件
└── test/
    └── java/                                            # 测试代码
```

## 核心功能

### 1. AI 聊天服务
- 提供基于 DeepSeek 模型的智能对话功能
- 支持自定义系统提示词
- 可配置模型参数（温度、最大令牌数等）

### 2. RESTful API
- `GET /chat?message={your_message}` - 发送消息并获取 AI 回复

### 3. 灵活配置
- 支持通过环境变量或配置文件设置 API 密钥
- 可自定义模型参数和服务端点

## 快速开始

### 前置要求

- Java 21 或更高版本
- Maven 3.6 或更高版本
- DeepSeek API 密钥

### 安装步骤

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd spring-ai-demo
   ```

2. **配置 API 密钥**
   
   方式一：设置环境变量
   ```bash
   export DEEPSEEK_API_KEY=your-actual-api-key
   ```
   
   方式二：修改 `application.properties`
   ```properties
   langchain4j.open-ai.chat-model.api-key=your-actual-api-key
   ```

3. **编译和运行**
   ```bash
   mvn clean install
   mvn spring-boot:run
   ```

4. **测试应用**
   
   应用启动后，访问：
   ```
   http://localhost:8080/chat?message=你好
   ```

## 配置说明

### application.properties 配置项

```properties
# 应用基本配置
spring.application.name=spring-ai-demo
server.port=8080

# DeepSeek API 配置
langchain4j.open-ai.chat-model.api-key=${DEEPSEEK_API_KEY:your-api-key-here}
langchain4j.open-ai.chat-model.base-url=https://api.deepseek.com/
langchain4j.open-ai.chat-model.model-name=deepseek-chat
langchain4j.open-ai.chat-model.temperature=0.7
langchain4j.open-ai.chat-model.max-tokens=1024
```

### 配置参数说明

- `api-key`: DeepSeek API 密钥
- `base-url`: DeepSeek API 基础 URL
- `model-name`: 使用的模型名称
- `temperature`: 控制回复的随机性 (0.0-1.0)
- `max-tokens`: 单次回复的最大令牌数

## API 使用示例

### 基本聊天
```bash
curl "http://localhost:8080/chat?message=介绍一下Spring Boot"
```

### 复杂对话
```bash
curl "http://localhost:8080/chat?message=请帮我写一个Java的Hello World程序"
```

## 开发指南

### 使用 Lombok 简化代码

项目已集成 Lombok，可以使用注解来减少样板代码：

```java
// 使用 @Data 注解自动生成 getter、setter、toString 等方法
@Data
@AllArgsConstructor
@NoArgsConstructor
public class ChatRequest {
    private String message;
    private String sessionId;
}

// 使用 @Slf4j 注解自动生成日志对象
@Slf4j
@RestController
public class ChatController {
    
    @Autowired
    Assistant assistant;

    @GetMapping("/chat")
    public String chat(String message) {
        log.info("Received chat message: {}", message);
        return assistant.chat(message);
    }
}
```

### 自定义 AI 助手

可以通过修改 `Assistant.java` 来自定义 AI 助手的行为：

```java
@AiService(chatModel = "openAiChatModel")
public interface Assistant {
    
    @SystemMessage("You are a helpful programming assistant specialized in Java development")
    String chat(String userMessage);
    
    // 可以添加更多专门的方法
    @SystemMessage("You are a code reviewer. Please review the following code and provide suggestions.")
    String reviewCode(String code);
}
```

### 添加新的端点

在 `ChatController.java` 中添加新的 REST 端点：

```java
@PostMapping("/chat")
public String chatPost(@RequestBody ChatRequest request) {
    return assistant.chat(request.getMessage());
}
```

## 故障排除

### 常见问题

1. **API 密钥错误**
   - 确保 DeepSeek API 密钥正确设置
   - 检查环境变量或配置文件中的密钥格式

2. **网络连接问题**
   - 确保能够访问 `https://api.deepseek.com`
   - 检查防火墙和代理设置

3. **端口冲突**
   - 默认端口为 8080，如有冲突可在配置文件中修改

### 日志调试

在 `application.properties` 中添加日志配置：

```properties
logging.level.dev.langchain4j=DEBUG
logging.level.org.example.demo=DEBUG
```

## 贡献指南

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

## 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 相关链接

- [Spring Boot 官方文档](https://spring.io/projects/spring-boot)
- [LangChain4j 官方文档](https://docs.langchain4j.dev/)
- [DeepSeek API 文档](https://platform.deepseek.com/api-docs/)

## 更新日志

### v0.0.1-SNAPSHOT
- 初始版本
- 集成 Spring Boot 3.5.0
- 集成 LangChain4j 1.0.1
- 支持 DeepSeek API
- 提供基础聊天功能