# springAI1.1.3学习笔记

**Repository Path**: baseme/spring-ai1.0.0-learning-notes

## Basic Information

- **Project Name**: springAI1.1.3学习笔记
- **Description**: springAI学习笔记
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-02
- **Last Updated**: 2026-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring AI 学习项目

> 系统化学习 Spring AI 框架的完整示例项目
> 
> 基于 Spring Boot 3.5.14 + Spring AI 1.1.3 + DeepSeek V4（OpenAI 兼容模式）

---

## 📖 项目简介

本项目旨在解决 **Spring AI 官方文档零散、示例不足** 的问题，提供：

- ✅ **系统化学习路线**：从基础到高级，循序渐进
- ✅ **完整代码示例**：8 个核心功能模块，每个都可独立运行
- ✅ **详细中文文档**：超过 1.4万字的学习指南
- ✅ **实用测试命令**：25+ 个 curl 测试用例，直接可用

**项目特色**：
- 🎯 基于 Spring AI 1.1.3 最新版本，API 稳定可靠
- 🔥 使用 **OpenAI 兼容协议**连接 DeepSeek（聊天）+ 通义（向量化）
- 📚 每个功能都有详细的概念讲解、代码示例、测试命令
- ⚡ 所有代码经过编译验证，开箱即用
- 🚀 **简化架构**：仅需一个 OpenAI starter，无需 DeepSeek 专用依赖

---

## 🚀 快速开始

### 1. 环境要求

| 工具 | 版本要求 |
|------|---------|
| **JDK** | 21 或更高 |
| **Maven** | 3.6+ |
| **IDE** | IntelliJ IDEA / VS Code（推荐）|

### 2. 获取 API Key

**DeepSeek API Key**（聊天模型）：
- 访问 [DeepSeek 平台](https://platform.deepseek.com)
- 注册账号并创建 API Key

**阿里百炼 API Key**（Embedding 模型，用于 RAG）：
- 访问 [阿里百炼](https://bailian.console.aliyun.com/)
- 开通服务并获取 API Key

### 3. 配置环境变量

**推荐方式**：使用环境变量（安全，不会泄露到 Git）

**Windows PowerShell**：
```powershell
# 永久设置（写入用户环境变量）
[Environment]::SetEnvironmentVariable("DEEPSEEK_API_KEY", "sk-your-deepseek-key", "User")
[Environment]::SetEnvironmentVariable("DASHSCOPE_API_KEY", "sk-your-dashscope-key", "User")

# 重启终端生效
```

**Linux / macOS**：
```bash
# 添加到 ~/.bashrc 或 ~/.zshrc
export DEEPSEEK_API_KEY="sk-your-deepseek-key"
export DASHSCOPE_API_KEY="sk-your-dashscope-key"

# 使配置生效
source ~/.bashrc
```

**临时测试**（仅当前会话有效）：
```powershell
# Windows
$env:DEEPSEEK_API_KEY = "sk-your-deepseek-key"
$env:DASHSCOPE_API_KEY = "sk-your-dashscope-key"
```

```bash
# Linux/macOS
export DEEPSEEK_API_KEY="sk-your-deepseek-key"
export DASHSCOPE_API_KEY="sk-your-dashscope-key"
```

### 4. 启动应用

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

或者在 IDE 中直接运行 `SpringAiStudyApplication.java`

### 5. 验证启动

```bash
# 健康检查
curl http://localhost:8080/spring-ai/hello

# 基础聊天测试
curl "http://localhost:8080/spring-ai/ai/simple?message=你好"
```

看到 AI 的回复，说明启动成功！🎉

---

## 📂 项目结构

```
spring-ai-study/
├── src/main/java/com/fy/spring_ai/spring_ai_study/
│   ├── chatclient/              # ChatClient 核心功能
│   │   ├── config/              # ✅ 配置类
│   │   ├── controller/          # ✅ 基础问答
│   │   ├── streaming/           # ✅ 流式响应
│   │   ├── structured/          # ✅ 结构化输出
│   │   ├── function/            # ✅ 工具调用
│   │   └── memory/              # ✅ 聊天记忆
│   ├── prompt/                  # Prompt 工程
│   │   └── templates/           # ✅ Prompt 模板
│   └── rag/                     # RAG 检索增强
│       └── simple/              # ✅ 简单 RAG
├── 系统学习路线图.md              # 📚 详细学习指南（1.4万字）
├── 多模态与高级特性.md            # 📖 DeepSeek 限制与替代方案
├── FAQ.md                       # ❓ 常见问题解答
└── README.md                    # 📄 本文档
```

---

## 🎯 核心功能示例

### 1️⃣ 基础对话 ✅

**简单问答**
```bash
curl "http://localhost:8080/spring-ai/ai/simple?message=什么是Spring AI？"
```

**流式响应**（逐字输出，提升体验）
```bash
curl -N "http://localhost:8080/spring-ai/ai/stream?message=写一首关于春天的诗"
```

**温度控制**（调节创造性）
```bash
# 保守模式（适合事实问答）
curl -N "http://localhost:8080/spring-ai/ai/stream-temp?message=解释量子力学&temperature=0.0"

# 创意模式（适合创作）
curl -N "http://localhost:8080/spring-ai/ai/stream-temp?message=编个科幻故事&temperature=1.5"
```

📖 **详细说明**：见 [系统学习路线图.md](doc/系统学习路线图.md) 第1章

---

### 2️⃣ 结构化输出 ✅

将 AI 输出自动解析为 Java 对象

**提取人物信息**
```bash
curl -X POST http://localhost:8080/spring-ai/structured/extract \
  -H "Content-Type: application/json" \
  -d '{"text":"李明是一位30岁的Java工程师，住在北京"}'
```

**文本分类**
```bash
curl -X POST http://localhost:8080/spring-ai/structured/classify \
  -H "Content-Type: application/json" \
  -d '{"text":"学习 Spring AI 框架"}'
```

**情感分析**
```bash
curl -X POST http://localhost:8080/spring-ai/structured/sentiment \
  -H "Content-Type: application/json" \
  -d '{"text":"This product is amazing!"}'
```

📖 **详细说明**：见 [系统学习路线图.md](doc/系统学习路线图.md) 第4章

---

### 3️⃣ 工具调用 ✅

让 AI 自动调用外部工具

**天气查询**
```bash
curl "http://localhost:8080/spring-ai/function/chat?message=北京今天天气怎么样？"
```

**货币转换**
```bash
curl "http://localhost:8080/spring-ai/function/chat?message=100美元等于多少人民币？"
```

**时间查询**
```bash
curl "http://localhost:8080/spring-ai/function/chat?message=现在几点了？"
```

📖 **详细说明**：见 [系统学习路线图.md](doc/系统学习路线图.md) 第5章

---

### 4️⃣ Prompt 模板 ✅

复用提示词，支持变量替换

**生成营销邮件**
```bash
curl -X POST http://localhost:8080/spring-ai/prompt/email \
  -H "Content-Type: application/json" \
  -d '{
    "recipientName": "张三",
    "productName": "智能手表",
    "features": ["心率监测", "GPS定位", "防水"]
  }'
```

**生成代码注释**
```bash
curl -X POST http://localhost:8080/spring-ai/prompt/code-comment \
  -H "Content-Type: application/json" \
  -d '{
    "language": "Java",
    "code": "public int factorial(int n) { return n <= 1 ? 1 : n * factorial(n-1); }"
  }'
```

📖 **详细说明**：见 [系统学习路线图.md](doc/系统学习路线图.md) 第6章

---

### 5️⃣ RAG 检索增强生成 ✅ ⭐

给 AI 提供私有知识库

**步骤 1：加载示例数据**
```bash
curl -X POST http://localhost:8080/spring-ai/rag/load-samples
```

**步骤 2：基于知识库提问**
```bash
curl "http://localhost:8080/spring-ai/rag/ask?question=什么是Spring AI？"
```

**步骤 3：添加自定义文档**
```bash
curl -X POST http://localhost:8080/spring-ai/rag/add-text \
  -H "Content-Type: application/json" \
  -d '{
    "content": "公司年假政策：入职满1年享受5天年假，满3年10天，满5年15天。",
    "source": "company-policy"
  }'

# 基于新文档提问
curl "http://localhost:8080/spring-ai/rag/ask?question=入职3年有几天年假？"
```

**步骤 4：上传文件**
```bash
curl -X POST http://localhost:8080/spring-ai/rag/upload-file \
  -F "file=@/path/to/document.txt"
```

📖 **详细说明**：见 [系统学习路线图.md](doc/系统学习路线图.md) 第7章

---

### 6️⃣ 聊天记忆 ✅

多轮对话，AI 能记住上下文

**第一轮对话**
```bash
curl -X POST http://localhost:8080/spring-ai/memory/chat \
  -H "Content-Type: application/json" \
  -d '{"conversationId":"user-123","message":"你好，我叫张三"}'
```

**第二轮对话**（AI 会记得你的名字）
```bash
curl -X POST http://localhost:8080/spring-ai/memory/chat \
  -H "Content-Type: application/json" \
  -d '{"conversationId":"user-123","message":"我叫什么名字？"}'
```

**查看对话历史**
```bash
curl "http://localhost:8080/spring-ai/memory/history/user-123"
```

**清空历史**
```bash
curl -X DELETE "http://localhost:8080/spring-ai/memory/history/user-123"
```

**多轮对话演示**
```bash
curl -X POST http://localhost:8080/spring-ai/memory/demo/multi-turn
```

📖 **详细说明**：见 [系统学习路线图.md](doc/系统学习路线图.md) 第8章

---

## 📚 学习路径

### 第一阶段：基础入门（1-2周）

1. ✅ **ChatClient 基础** - 理解核心 API
2. ✅ **流式响应** - 提升用户体验
3. ✅ **Prompt 工程** - 编写有效的提示词

### 第二阶段：核心功能（2-3周）

4. ✅ **结构化输出** - 数据提取和分类
5. ✅ **工具调用** - 扩展 AI 能力
6. ✅ **Prompt 模板** - 代码复用和管理

### 第三阶段：高级应用（3-4周）

7. ✅ **RAG 检索增强** - 私有知识库问答
8. ✅ **聊天记忆** - 多轮对话上下文
9. 📖 **智能代理** - 工作流模式（见高级特性文档）

### 第四阶段：生产实践（持续）

10. 性能优化
11. 安全配置
12. 监控部署

📖 **完整学习路线**：[系统学习路线图.md](doc/系统学习路线图.md)

---

## 🔧 配置说明

### application.yaml

```yaml
spring:
  application:
    name: spring-ai-study

  ai:
    openai:
      # DeepSeek OpenAI 兼容端点（用于聊天）
      base-url: https://api.deepseek.com
      api-key: ${DEEPSEEK_API_KEY}
      chat:
        options:
          model: deepseek-chat  # 或 deepseek-reasoner
          temperature: 0.7

    # 通义 Embedding 配置（通过 EmbeddingConfig.java 手动注入）
    embedding:
      api-key: ${DASHSCOPE_API_KEY}

server:
  port: 8080
  servlet:
    context-path: /spring-ai
```

### 架构说明

**为什么使用 OpenAI 兼容模式？**

DeepSeek 完全支持 OpenAI 协议，因此本项目：
- ✅ **仅使用 `spring-ai-starter-model-openai` 一个依赖**
- ✅ **聊天模型**：通过 `application.yaml` 指向 DeepSeek API
- ✅ **Embedding 模型**：通过 `EmbeddingConfig.java` 手动配置通义 API

**双 base-url 解决方案**：

Spring AI 的 OpenAI starter 只支持一个 `base-url`，因此：
- **聊天**：自动配置，使用 `spring.ai.openai.base-url` 指向 DeepSeek
- **Embedding**：手动配置 Bean，单独指向通义的兼容端点

### pom.xml 依赖

```xml
<!-- 只需要一个 OpenAI starter -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

<!-- RAG 向量库支持 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-advisors-vector-store</artifactId>
</dependency>
```

### EmbeddingConfig.java

```java
@Configuration
public class EmbeddingConfig {
    @Value("${spring.ai.embedding.api-key}")
    private String dashscopeApiKey;

    @Bean
    public EmbeddingModel embeddingModel() {
        var openAiApi = OpenAiApi.builder()
            .baseUrl("https://dashscope.aliyuncs.com/compatible-mode")
            .apiKey(dashscopeApiKey)
            .build();

        var options = OpenAiEmbeddingOptions.builder()
            .model("text-embedding-v3")
            .build();

        return new OpenAiEmbeddingModel(openAiApi, MetadataMode.EMBED, options);
    }
}
```

---

## 📖 文档导航

| 文档 | 大小 | 描述 |
|------|------|------|
| [README.md](README.md) | - | 项目入口，快速开始指南（本文档）|
| [系统学习路线图.md](doc/系统学习路线图.md) | 13.7 KB | 9章详细学习路径 + 代码示例 + 测试命令 |
| [多模态与高级特性.md](doc/多模态与高级特性.md) | 10.3 KB | 图像、语音、Agents 等高级功能说明 |
| [FAQ.md](doc/FAQ.md) | 8.6 KB | 常见问题解答 |
| [01-ChatClient和Advisors/](doc/01-ChatClient和Advisors/) | 46+ KB | 第一章详细学习资料（3个文档）|

---

## 🤔 常见问题

### Q1: 编译报错 "javac 1.8 不支持文本块"

**A**: 需要使用 Java 21。检查：
```bash
java -version  # 应该显示 21.x.x
```

配置 Maven 使用 Java 21：
```bash
# Windows
$env:JAVA_HOME = "D:\Program Files\jdk-21"

# Linux/macOS
export JAVA_HOME=/path/to/jdk-21
```

### Q2: 启动失败 "API Key 无效"

**A**: 检查环境变量是否设置：
```bash
# Windows
echo $env:DEEPSEEK_API_KEY
echo $env:DASHSCOPE_API_KEY

# Linux/macOS
echo $DEEPSEEK_API_KEY
echo $DASHSCOPE_API_KEY
```

### Q3: RAG 功能报错 "找不到 EmbeddingModel"

**A**: 确保配置了 `DASHSCOPE_API_KEY` 环境变量，并且 `application.yaml` 中配置了通义的 embedding。

### Q4: 如何切换到其他 AI 模型？

**A**: 修改 `pom.xml` 的依赖和 `application.yaml` 的配置。详见 [多模态与高级特性.md](doc/多模态与高级特性.md)

📖 **更多问题**：见 [FAQ.md](doc/FAQ.md)

---

## 🌟 项目亮点

### 1. 真实 API 验证

所有代码都基于 **Spring AI 1.1.3 实际验证**，确保 API 正确：
- ✅ `functions()` → `tools()` (M8版本改名)
- ✅ `options(lambda)` → `options(ChatOptions)` (API变化)
- ✅ `SimpleVectorStore.builder()` (构造方式变化)
- ✅ `OpenAiChatOptions.builder().temperature()` (正确的 Builder 方法)
- ✅ `OpenAiEmbeddingModel` 构造函数参数（需要 MetadataMode）
- ✅ 正确的包路径和方法签名

### 2. 简化架构 - OpenAI 兼容模式

**为什么简化？**
- ❌ **旧方案**：`spring-ai-starter-model-deepseek` + `spring-ai-starter-model-openai` 两个依赖
- ✅ **新方案**：只需 `spring-ai-starter-model-openai` 一个依赖

**如何实现？**
- **聊天**: DeepSeek API（OpenAI 兼容端点 `https://api.deepseek.com`）
- **向量化**: 通义 text-embedding-v3（通过 `EmbeddingConfig.java` 手动配置）

**优势**：
- 依赖更少，配置更清晰
- 使用 OpenAI 协议标准，通用性更强
- 无需排除自动配置，避免 bean 冲突

### 3. 生产级配置

- ✅ API Key 从环境变量读取
- ✅ 排除冲突的自动配置
- ✅ 完整的错误处理
- ✅ 详细的日志和注释

### 4. 详细中文文档

- **系统学习路线图**: 1.4万字，9个章节
- **多模态说明**: DeepSeek 限制和替代方案
- **FAQ**: 覆盖常见问题
- 每个功能都有：概念讲解 + 代码示例 + 测试命令

---

## 🚧 局限性说明

### DeepSeek 不支持的功能

- ❌ **图像生成** - 需要 DALL-E / Stable Diffusion
- ❌ **语音处理** - 需要 Whisper / TTS
- ❌ **视觉理解** - 需要 GPT-4V / Claude 3
- ❌ **Embedding** - 本项目用通义解决

### 解决方案

详见 [多模态与高级特性.md](doc/多模态与高级特性.md)，根据需求切换或混合使用多个模型。

---

## 📊 项目统计

- **代码文件**: 10 个 Java 文件
- **Controller**: 8 个
- **API 端点**: 20+ 个
- **文档**: 4 个 Markdown 文件
- **测试用例**: 25+ 个 curl 命令
- **代码行数**: 2000+ 行（含注释）

---

## 🎓 学习建议

1. **按顺序学习**：从基础到高级，不要跳章节
2. **动手实践**：每个示例都运行一遍
3. **阅读代码**：注释很详细，理解原理
4. **修改实验**：改参数、改提示词，观察变化
5. **参考文档**：遇到问题先查 FAQ 和学习路线图

**建议节奏**：每天 1-2 小时，2-3周完成基础和核心功能，4周掌握所有内容。

---

## 🔗 相关资源

### 官方资源
- [Spring AI 官方文档](https://docs.spring.io/spring-ai/reference/)
- [Spring AI GitHub](https://github.com/spring-projects/spring-ai)

### 社区教程
- [Baeldung: Introduction to Spring AI](https://www.baeldung.com/spring-ai)
- [Spring AI RAG with MongoDB](https://baeldung.com/spring-ai-mongodb-rag)
- [Building Effective Agents](https://spring.io/blog/2025/01/21/spring-ai-agentic-patterns/)

### 模型平台
- [DeepSeek 平台](https://platform.deepseek.com/)
- [阿里百炼](https://bailian.console.aliyun.com/)

---

## ⚠️ 注意事项

1. **API Key 安全**
   - ✅ 使用环境变量
   - ❌ 不要硬编码在代码中
   - ❌ 不要提交到 Git

2. **成本控制**
   - 注意 API 调用次数
   - 设置 `max-tokens` 限制
   - 使用缓存减少重复调用

3. **速率限制**
   - DeepSeek 有 API 调用频率限制
   - 生产环境建议添加限流

4. **生产部署**
   - RAG 用持久化向量库（PGVector/Redis）
   - 聊天记忆用 JDBC/Redis 持久化
   - 添加监控和日志

---

## 📄 License

MIT License

---

## 🎉 开始学习

项目已经完全就绪！按照以下步骤开始：

1. ✅ 配置环境变量（`DEEPSEEK_API_KEY` 和 `DASHSCOPE_API_KEY`）
2. ✅ 启动应用（`mvn spring-boot:run`）
3. ✅ 测试基础功能（`curl` 命令验证）
4. 📖 打开 [系统学习路线图.md](doc/系统学习路线图.md) 开始系统学习

**祝学习愉快！🚀**

---

**项目维护**: 如有问题或建议，欢迎提交 Issue。