liang-spring-ai/README.md

# Spring AI 聊天演示项目

这是一个基于 Spring AI 的简单聊天应用演示项目，展示了如何与大语言模型进行对话。

## 功能特性

- 🤖 支持多种大语言模型（OpenAI、Ollama）
- 💬 简洁美观的聊天界面
- 🔧 简单的配置和部署
- 📱 响应式设计，支持移动端

## 技术栈

- **Spring Boot 3.2.0** - 应用框架
- **Spring AI 0.8.1** - AI 集成框架
- **Thymeleaf** - 模板引擎
- **HTML/CSS/JavaScript** - 前端界面

## 快速开始

### 1. 环境要求

- Java 17 或更高版本
- Maven 3.6 或更高版本

### 2. 配置大语言模型

#### 使用 OpenAI（推荐）

在 `src/main/resources/application.yml` 中配置：

```yaml
spring:
  ai:
    openai:
      api-key: your-openai-api-key-here
      base-url: https://api.openai.com  # 可选，默认值
```

或者通过环境变量设置：

```bash
export OPENAI_API_KEY=your-openai-api-key-here
```

#### 使用 Ollama（本地部署）

1. 首先安装并启动 Ollama：
   ```bash
   # 安装 Ollama
   curl -fsSL https://ollama.ai/install.sh | sh
   
   # 拉取模型（例如 llama2）
   ollama pull llama2
   
   # 启动 Ollama 服务
   ollama serve
   ```

2. 在配置文件中启用 Ollama：
   ```yaml
   spring:
     ai:
       ollama:
         base-url: http://localhost:11434
         chat:
           options:
             model: llama2
   ```

### 3. 运行应用

```bash
# 编译项目
mvn clean compile

# 运行应用
mvn spring-boot:run
```

应用启动后，访问 http://localhost:8080 即可使用聊天界面。

### 4. API 接口

除了网页界面，还提供了简单的 API 接口：

```bash
# 简单对话接口
curl "http://localhost:8080/simple?q=你好"

# POST 接口
curl -X POST http://localhost:8080/chat \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "message=介绍一下 Spring AI"
```

## 项目结构

```
src/
├── main/
│   ├── java/com/example/springaidemo/
│   │   ├── SpringAiDemoApplication.java    # 应用主类
│   │   ├── config/
│   │   │   └── AiConfig.java              # AI 配置类
│   │   └── controller/
│   │       └── ChatController.java        # 聊天控制器
│   └── resources/
│       ├── application.yml                # 应用配置
│       └── templates/
│           └── chat.html                  # 聊天界面模板
```

## 配置说明

### OpenAI 配置

```yaml
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY:your-openai-api-key}  # OpenAI API Key
      base-url: ${OPENAI_BASE_URL:https://api.openai.com}  # API 基础 URL
      chat:
        options:
          model: gpt-3.5-turbo     # 使用的模型
          temperature: 0.7         # 温度参数（0-1）
```

### Ollama 配置

```yaml
spring:
  ai:
    ollama:
      base-url: ${OLLAMA_BASE_URL:http://localhost:11434}  # Ollama 服务地址
      chat:
        options:
          model: ${OLLAMA_MODEL:llama2}  # 使用的模型
```

## 自定义和扩展

### 添加新的对话端点

在 `ChatController` 中添加新的方法：

```java
@GetMapping("/custom")
@ResponseBody
public String customChat(@RequestParam("message") String message) {
    // 自定义处理逻辑
    String prompt = "请用专业的语言回答：" + message;
    return chatClient.call(prompt);
}
```

### 修改聊天界面

编辑 `src/main/resources/templates/chat.html` 文件来自定义界面样式和功能。

### 添加更多 AI 提供商

Spring AI 支持多种 AI 提供商，包括：
- OpenAI
- Azure OpenAI
- Hugging Face
- Ollama
- Anthropic Claude

## 常见问题

### 1. OpenAI API Key 错误
- 确保 API Key 正确设置
- 检查 API Key 是否有足够的配额
- 验证网络连接是否正常

### 2. Ollama 连接失败
- 确保 Ollama 服务正在运行
- 检查端口 11434 是否可访问
- 确认模型已正确下载

### 3. 应用启动失败
- 检查 Java 版本是否为 17 或更高
- 确保网络连接正常
- 查看控制台错误日志

## 许可证

MIT License