# Week 10：AI Agent 核心概念 —— 从聊天到干活

> **学习周期**：7 天
> **每日用时**：2-3 小时
> **最终产出**：一个具备工具调用、RAG 检索、持久化记忆、Prompt 模板管理的 AI Agent 系统

---

## 前置准备

| 事项 | 说明 |
|------|------|
| Week 9 代码可用 | 确保 `week9` 项目能正常启动和对话 |
| DeepSeek API Key | Week 9 已在用，继续使用 |
| Redis 安装 | Day 5 需要（[github.com/tporadowski/redis](https://github.com/tporadowski/redis) Windows 版） |
| Ollama 安装（方案 B） | Day 6 需要（[ollama.com](https://ollama.com) → 下载安装 → `ollama pull nomic-embed-text`） |

> **关于 Embedding 方案**：Day 6 的 RAG 有两种 Embedding 方案。**方案 B（Ollama 本地）** 免费、离线、零成本，是默认选择。**方案 A（阿里云百炼）** 需要注册获取 Key，但有免费额度，适合网络受限无法下载 Ollama 的情况。教案中同时覆盖两种方案。

---

## 启动方式

```bash
# 1. 确保 Redis 已启动（Day 5 需要，其他 Day 可先注释掉 Redis 依赖）
# 2. 确保 Ollama 已启动 + nomic-embed-text 已下载（Day 6 需要）
# 3. 修改 application.yml 中的 api-key (DeepSeek)
# 4. IDEA 中运行 Week10Application.main()
# 5. 浏览器访问 http://localhost:8080/agent.html
```

---

## Week 9 → Week 10：升级了什么？

```
Week 9: 聊天机器人
  POST /api/chat  →  同步/流式对话  →  AI 陪你聊天

Week 10: AI Agent
  POST /api/agent       →  工具调用       →  AI 能查天气、算数学、搜信息
  POST /api/rag/query   →  知识库检索     →  AI 能基于你的文档回答问题
  Redis 持久化           →  记忆不丢       →  重启后对话历史还在
  Prompt 模板管理        →  角色预设       →  一键切换 AI 人设
```

---

## Day 1：Agent 核心概念（ReAct / Plan-Execute）

### 什么是 AI Agent？

AI Agent（智能体）= **大模型 + 工具 + 决策循环**。和普通聊天机器人的区别：

| | 聊天机器人 | AI Agent |
|------|-----------|----------|
| 能力 | 只回答已知知识 | 能调用外部工具 |
| 记忆 | 单次对话 | 持久化 + 多轮 |
| 行为 | 被动回复 | 主动规划 + 执行 |
| 边界 | 模型训练数据 | 训练数据 + 实时信息 |

### Agent 的两个核心范式

#### 1. ReAct（Reasoning + Acting，推理-行动循环）

```
用户: "北京今天天气如何？"

  ┌─ Thought（思考）: 用户想知道北京的天气，我需要调用天气工具
  ├─ Action（行动）: getWeather("北京")
  ├─ Observation（观察）: {"city":"北京","weather":"晴","temp":25}
  ├─ Thought（思考）: 获得了天气信息，可以回答了
  └─ Answer（回答）: "北京今天晴天，气温 25°C..."
```

ReAct 是当前最主流的 Agent 范式，Spring AI 的 `@Tool` 机制本质上就是 ReAct。

#### 2. Plan-Execute（规划-执行）

```
用户: "帮我做一个技术调研：比较 Spring AI 和 LangChain4j"

  ┌─ Plan（规划）:
  │   1. 搜索 Spring AI 最新文档
  │   2. 搜索 LangChain4j 最新文档
  │   3. 对比两者的 API 设计
  │   4. 写总结报告
  ├─ Execute Step 1 → 获取结果
  ├─ Execute Step 2 → 获取结果
  ├─ Execute Step 3 → 对比分析
  └─ Execute Step 4 → 输出报告
```

Plan-Execute 适合复杂多步任务，需要更强的规划能力。Spring AI 暂未内置此模式，但可以通过多轮 Agent 调用手动实现。

### 动手 → 理解

1. 用 ChatGPT / DeepSeek 网页版，尝试问一个需要"外部信息"的问题（如"今天天气"），观察它如何回答——要么说不知道，要么编造答案
2. 再问一个需要"实时信息"的问题：对比 ChatGPT 网页版（能搜索）和 API 版（无工具）的回答差异
3. 在纸上画出 ReAct 循环图，尝试把"帮我查北京天气，如果下雨就提醒带伞，如果晴天就推荐去公园"这个任务分解为 ReAct 步骤

### 思考题

> 如果模型没有工具调用能力，用户问"今天天气如何？"——模型会怎么回答？为什么会有"幻觉"？工具调用如何解决幻觉问题？

---

## Day 2：Function Calling 原理 —— 模型如何"调用"工具？

### 核心问题

模型不能真的"调用"你的 Java 方法。整个过程是：

```
你告诉模型"有哪些工具可用"（JSON Schema）
  → 模型决定"需要调用哪个工具"（返回 JSON）
    → 你的代码解析 JSON → 执行对应方法
      → 把结果返回给模型
        → 模型基于结果生成自然语言回答
```

### 工具定义（Tools Definition）—— 告诉模型你能做什么

发送给模型的请求中包含一个 `tools` 数组：

```json
{
  "model": "deepseek-chat",
  "messages": [{"role": "user", "content": "北京今天天气如何？"}],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "getWeather",
        "description": "获取指定城市的当前天气信息",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "城市名称，如'北京'、'上海'"
            }
          },
          "required": ["city"]
        }
      }
    }
  ]
}
```

### 模型的响应 —— 不直接回答，而是说"请调这个工具"

```json
{
  "choices": [{
    "finish_reason": "tool_calls",
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc123",
        "type": "function",
        "function": {
          "name": "getWeather",
          "arguments": "{\"city\": \"北京\"}"
        }
      }]
    }
  }]
}
```

关键：`finish_reason` 是 `tool_calls` 而不是 `stop`——模型没有生成文本，而是请求调用工具。

### 第二轮：把工具结果喂回去

```json
{
  "model": "deepseek-chat",
  "messages": [
    {"role": "user", "content": "北京今天天气如何？"},
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [{"id": "call_abc123", "type": "function", "function": {"name": "getWeather", "arguments": "{\"city\": \"北京\"}"}}]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "content": "{\"city\": \"北京\", \"weather\": \"晴\", \"temperature\": 25}"
    }
  ]
}
```

这一次 `finish_reason` = `stop`，模型返回自然语言："北京今天晴天，气温 25°C，非常适合户外活动。"

### 动手 → 理解

1. 用 Postman，给 DeepSeek API 发送一个带 `tools` 定义的请求（复制上面的 JSON，替换 API Key）
2. 观察返回的 `finish_reason` 是 `tool_calls` 不是 `stop`
3. 手动构造"第二轮请求"：把 tool 执行结果放到 messages 里，再次调用，观察模型如何基于结果生成回答
4. 试试发送两个工具定义（weather + calculator），同一个用户问题，观察模型如何选择

### 思考题

> 如果模型同时定义了 WeatherTool 和 CalculatorTool，用户问"1+1等于几"——模型凭什么知道该选 CalculatorTool 而不是 WeatherTool？（答案：`description` 字段是唯一的"说明书"）

---

## Day 3：Spring AI Function Calling —— 第一个 Tool

### Spring AI 的 @Tool 注解

Spring AI 1.0.6 提供了 `@Tool` 注解，让你用纯 Java 定义工具：

```java
@Component
public class WeatherTool {

    @Tool(description = "获取指定城市的当前天气信息，包括天气状况和温度")
    public String getWeather(@ToolParam(description = "城市名称，如'北京'、'上海'") String city) {
        // 模拟天气数据（生产环境替换为真实 API 调用）
        var weatherData = Map.of(
            "北京", "晴，25°C",
            "上海", "多云，28°C",
            "深圳", "阵雨，30°C"
        );
        return weatherData.getOrDefault(city, "未找到该城市天气信息");
    }
}
```

Spring AI 会自动：
1. 从 `@Tool.description` 生成工具定义（JSON Schema）
2. 在 ChatClient 发送请求时附上工具列表
3. 解析模型的 `tool_calls` 响应
4. 执行对应的方法
5. 把结果自动返回给模型
6. 拿到最终的自然语言回答

你只需要：用 `@Tool` 写方法 + 注册到 ChatClient。

### 注册工具到 ChatClient

```java
@Bean
public ChatClient chatClient(ChatModel chatModel, Object weatherTool, ...) {
    return ChatClient.builder(chatModel)
            .defaultSystem("你是一个 AI Agent 助手...")
            .defaultTools(weatherTool, calculatorTool, searchTool)  // 注册所有工具
            .defaultAdvisors(...)
            .build();
}
```

### AgentService：让模型自动选择工具

```java
@Service
public class AgentService {
    private final ChatClient chatClient;

    public Map<String, Object> execute(String task, String conversationId) {
        String reply = chatClient.prompt()
                .user(task)
                .advisors(a -> a.param(CONVERSATION_ID, convId))
                .call()
                .content();  // 模型自动判断是否调用工具、调用哪个工具
        return Map.of("reply", reply, "conversationId", convId);
    }
}
```

你没写任何"if 用户说天气 then 调 WeatherTool"的逻辑。**模型自己决定**——这就是 Agent 的智能所在。

### 动手 → 理解

1. 阅读 `tool/WeatherTool.java`——理解 `@Tool` 和 `@ToolParam` 的用法
2. 阅读 `AIConfig.java` 中的 `defaultTools(weatherTool, calculatorTool, searchTool)` 注册
3. 阅读 `service/AgentService.java`——对比 `ChatService.java`，有什么区别？
4. 启动项目，浏览器访问 `http://localhost:8080/agent.html`
5. 勾选"Agent 模式"，发送："北京今天天气如何？"
6. 观察日志中是否有工具调用记录
7. 用 Postman 测试：`POST /api/agent` Body: `{"message": "深圳天气怎么样？"}`
8. 故意问一个 WeatherTool 不支持的城市（如"拉萨"），观察返回

### 核心文件

| 文件 | 作用 |
|------|------|
| `tool/WeatherTool.java` | @Tool 定义：天气查询 |
| `config/AIConfig.java` | defaultTools 注册 |
| `service/AgentService.java` | Agent 入口：execute() / executeStream() |

### 思考题

> 如果你把 WeatherTool 的 `@Tool(description = "...")` 改成 `description = "获取当前时间"`，模型调用这个工具时会发生什么？提示：description 是模型**唯一的判断依据**。

---

## Day 4：多工具协作 —— 让 Agent 更强大

### 再加两个工具

#### CalculatorTool

```java
@Component
public class CalculatorTool {
    @Tool(description = "执行数学计算，支持加减乘除和括号。示例: '123 * 456'")
    public double calculate(@ToolParam(description = "数学表达式") String expression) {
        // 使用 javax.script.ScriptEngine 安全求值
        ScriptEngineManager manager = new ScriptEngineManager();
        ScriptEngine engine = manager.getEngineByName("JavaScript");
        return ((Number) engine.eval(expression)).doubleValue();
    }
}
```

#### SearchTool

```java
@Component
public class SearchTool {
    @Tool(description = "联网搜索技术信息，返回相关结果")
    public String search(@ToolParam(description = "搜索关键词") String query) {
        // 模拟搜索结果（生产环境替换为真实搜索 API）
        var results = Map.of(
            "spring ai", "Spring AI 1.0.6 是面向 Java 的 AI 框架...",
            "java 21", "Java 21 是 LTS 版本，引入虚拟线程...",
            "deepseek", "DeepSeek 是深度求索开发的大语言模型..."
        );
        return results.getOrDefault(query.toLowerCase(), "未找到相关信息");
    }
}
```

### 多工具协作的关键：让模型自己选

你没有写规则说"当用户问数学时用 CalculatorTool"。模型通过 tools 的 `description` 自行判断。核心优势：

```
用户: "北京天气怎么样？顺便帮我算一下 999 * 888"

模型思考过程（内部）：
  → 用户问了两个问题：天气 + 计算
  → 查天气 → 需要调用 WeatherTool
  → 数学运算 → 需要调用 CalculatorTool
  → 先取天气结果，再取计算结果，合并回答
```

### Agent 模式 vs 普通聊天模式

| | 普通聊天（/api/chat） | Agent 模式（/api/agent） |
|------|---------------------|------------------------|
| 工具 | 不注册工具 | 注册所有 @Tool |
| 能力 | 只用训练数据 | 可获取外部信息 |
| 适用 | 闲聊、解释概念 | 查天气、计算、搜索 |
| 实现 | ChatService | AgentService（实际上底层一样，只是 ChatClient 配置不同） |

### 动手 → 理解

1. 阅读 `tool/CalculatorTool.java` 和 `tool/SearchTool.java`
2. 阅读 `service/AgentService.java` 的 `execute()` —— 注意到没有？代码和 Day 3 一模一样！因为模型自己决定调哪个工具
3. 启动项目，在 agent.html 中测试多工具协作：
   - 发送："北京天气怎么样？顺便算 123 * 456"
   - 发送："帮我搜索 Spring AI 是什么，再总结成一句话"
4. 在日志中观察：是否同时触发了两个工具？
5. 流式模式测试：勾选"流式输出"，再次发送多工具请求，观察打字机效果
6. 对比 `/api/agent` 和 `/api/chat` 的响应差异

### 核心文件

| 文件 | 作用 |
|------|------|
| `tool/CalculatorTool.java` | @Tool：数学计算 |
| `tool/SearchTool.java` | @Tool：搜索（模拟） |
| `service/AgentService.java` | executeStream() 流式 Agent |

### 思考题

> 如果问"东京天气如何？帮我换算一下 32°C 是多少华氏度"，模型会调用哪些工具？调用顺序如何？描述完整的 ReAct 循环。

---

## Day 5：Redis 记忆持久化 —— 重启对话不丢失

### Week 9 的局限

Week 9 使用 `InMemoryChatMemoryRepository`（JVM 内存）存储对话历史。一旦重启应用，所有对话记忆丢失。

### Spring AI 的 ChatMemory 双层架构

```
MessageWindowChatMemory（策略层：滑动窗口，保留最近 30 条）
    ↓ 委托存储
ChatMemoryRepository（存储层：接口）
    ├─ InMemoryChatMemoryRepository（默认，内存 → 重启丢失）
    ├─ JdbcChatMemoryRepository（JDBC 数据库）
    ├─ CassandraChatMemoryRepository（Cassandra）
    └─ 自定义：RedisChatMemoryRepository  ← 本周实现
```

### 自定义 RedisChatMemoryRepository

Spring AI 1.0.6 没有内置 Redis 实现，这反而是好的——你可以学习如何扩展框架：

```java
@Component
public class RedisChatMemoryRepository implements ChatMemoryRepository {

    private final RedisTemplate<String, Object> redisTemplate;
    private static final String KEY_PREFIX = "chat:memory:";
    private static final String ID_SET_KEY = "chat:conversation:ids";

    @Override
    public List<Message> findByConversationId(String id) {
        // LRANGE 读取整个 List → JSON 反序列化 → List<Message>
        var jsonList = redisTemplate.opsForList().range(KEY_PREFIX + id, 0, -1);
        // ... Jackson 反序列化
    }

    @Override
    public void saveAll(String id, List<Message> messages) {
        // DEL 清空旧数据 → RPUSH 逐条写入 JSON → SADD 记录 ID
        redisTemplate.delete(KEY_PREFIX + id);
        messages.forEach(msg -> redisTemplate.opsForList().rightPush(KEY_PREFIX + id, toJson(msg)));
        redisTemplate.opsForSet().add(ID_SET_KEY, id);
    }

    @Override
    public void deleteByConversationId(String id) { /* DEL + SREM */ }

    @Override
    public List<String> findConversationIds() { /* SMEMBERS */ }
}
```

### AIConfig 中的无缝切换

```java
// Week 9（内存版，重启丢失）:
@Bean
public ChatMemory chatMemory() {
    return MessageWindowChatMemory.builder()
            .chatMemoryRepository(new InMemoryChatMemoryRepository())
            .maxMessages(20).build();
}

// Week 10（Redis 持久化版，重启保留）:
@Bean
public ChatMemory chatMemory(ChatMemoryRepository repository) {  // 注入我们的 Redis 实现
    return MessageWindowChatMemory.builder()
            .chatMemoryRepository(repository)  // 换成 Redis
            .maxMessages(30).build();
}
```

**其他代码完全不用改**——这就是面向接口编程的威力。

### Jackson 序列化的 Message 格式

Message 接口的常见实现是 `AssistantMessage`、`UserMessage`。Jackson 需要类型信息来正确反序列化。在 RedisConfig 中配置：

```java
@Bean
public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory factory) {
    RedisTemplate<String, Object> template = new RedisTemplate<>();
    template.setConnectionFactory(factory);

    Jackson2JsonRedisSerializer<Object> serializer = new Jackson2JsonRedisSerializer<>(Object.class);
    // 配置 ObjectMapper 以支持多态反序列化
    ObjectMapper mapper = new ObjectMapper();
    mapper.activateDefaultTyping(BasicPolymorphicTypeValidator.builder().build(),
            ObjectMapper.DefaultTyping.NON_FINAL);
    serializer.setObjectMapper(mapper);

    template.setValueSerializer(serializer);
    // ...
}
```

### 动手 → 理解

1. 安装 Redis（Windows 版从 GitHub Release 下载，或使用 WSL/Docker）
2. 启动 Redis：`redis-server.exe`（或 `redis-server`）
3. 修改 `application.yml` 中的 Redis 密码（如果有的话）
4. 阅读 `memory/RedisChatMemoryRepository.java`——理解 4 个接口方法的实现
5. 阅读 `config/RedisConfig.java`——理解 JSON 序列化配置
6. 阅读 `config/AIConfig.java` 中的 `chatMemory()` Bean——注意 `ChatMemoryRepository` 是怎么注入的
7. 启动项目，发送几轮对话
8. 用 `redis-cli` 查看数据：
   ```
   redis-cli
   SMEMBERS chat:conversation:ids          → 查看所有会话 ID
   LRANGE chat:memory:default 0 -1         → 查看 default 会话的所有消息
   ```
9. **重启项目** → 访问 `GET /api/chat/history` → 确认记忆还在！
10. 删除某个会话 → 观察 Redis 中对应的 Key 被删除

### 核心文件

| 文件 | 作用 |
|------|------|
| `memory/RedisChatMemoryRepository.java` | 实现 ChatMemoryRepository 接口 |
| `config/RedisConfig.java` | RedisTemplate 序列化配置 |
| `config/AIConfig.java` | ChatMemory Bean 改造（注入 Repository） |

### 思考题

> 如果把 `maxMessages(30)` 改成 `maxMessages(5)`，再发 10 轮对话，Redis 里会存几条消息？滑动窗口是怎么删除旧消息的？验证方法：用 `LLEN chat:memory:xxx` 检查 List 长度。

---

## Day 6：RAG（检索增强生成）—— 让 AI 基于你的知识库回答

### 什么是 RAG？

RAG = Retrieval-Augmented Generation（检索增强生成）。核心思想：

```
用户问题 → 向量检索（从知识库找相关文档）→ 把文档拼接到 Prompt → 模型基于文档生成回答
```

为什么需要 RAG？
- LLM 训练数据有截止日期，不知道新信息
- LLM 不知道你公司的内部文档
- RAG 可以有效减少幻觉（模型瞎编）

### RAG 核心流程

```
┌─────────────────────────────────────────────────────┐
│ 1. 文档入库（离线）                                    │
│    文档 → 切分 → Embedding（转向量）→ 存入 VectorStore │
│                                                      │
│ 2. 问答（在线）                                       │
│    用户问题 → Embedding（转向量）                      │
│         → VectorStore.similaritySearch（找最相似的）    │
│         → 拼接 Context + 问题 → ChatModel 生成回答     │
└─────────────────────────────────────────────────────┘
```

### Embedding（文本转向量）是什么？

"今天天气真好" → Embedding 模型 → `[0.12, -0.34, 0.78, ..., 0.05]`（一个 768 维的浮点数数组）

相似的文本，向量距离近。例如：
- "今天天气真好" 和 "今天阳光明媚" → 余弦相似度 0.92（很近）
- "今天天气真好" 和 "Spring AI 是什么" → 余弦相似度 0.15（很远）

### Embedding 方案选择

#### 方案 B：Ollama 本地（默认，免费）

```bash
# 安装 Ollama
# Mac: brew install ollama
# Windows: 从 ollama.com 下载安装包

# 拉取嵌入模型（~270MB）
ollama pull nomic-embed-text

# 验证
ollama list
# NAME                ID              SIZE      MODIFIED
# nomic-embed-text:latest    xxxxxxxx    274 MB    ...
```

Ollama 默认监听 `http://localhost:11434`。

#### 方案 A：阿里云百炼（备选，云端）

如果你无法下载 Ollama（网络受限），用阿里云百炼的 `text-embedding-v2`：

1. 注册 [bailian.console.aliyun.com](https://bailian.console.aliyun.com)
2. 开通模型服务 → 获取 API Key
3. 修改 `application.yml`：

```yaml
spring.ai.openai.embedding:
  api-key: ${EMBEDDING_API_KEY:sk-your-bailian-key}
  base-url: https://dashscope.aliyuncs.com/compatible-mode
  options:
    model: text-embedding-v2
```

### AIConfig 中的双 Provider 设计

Chat 和 Embedding 用不同的 API Provider：

```java
// Chat → DeepSeek（由 spring.ai.openai.* 自动配置 ChatModel）
// Embedding → Ollama 本地（手动创建 EmbeddingModel）

@Bean
public EmbeddingModel embeddingModel(
        @Value("${spring.ai.openai.embedding.base-url}") String baseUrl,
        @Value("${spring.ai.openai.embedding.api-key}") String apiKey) {
    var api = OpenAiApi.builder()
            .baseUrl(baseUrl.endsWith("/v1") ? baseUrl : baseUrl + "/v1")
            .apiKey(apiKey)
            .build();
    return new OpenAiEmbeddingModel(api);
}
```

### SimpleVectorStore —— 零依赖的向量存储

```java
@Bean
public VectorStore vectorStore(EmbeddingModel embeddingModel) {
    return SimpleVectorStore.builder(embeddingModel).build();
}
```

SimpleVectorStore 纯内存存储，免外部服务。生产环境可替换为 PgVectorStore、RedisVectorStore 等。

### QuestionAnswerAdvisor —— 自动 RAG

在 ChatClient 的 Advisor 链中添加 `QuestionAnswerAdvisor`：

```java
.defaultAdvisors(
    MessageChatMemoryAdvisor.builder(chatMemory).build(),
    new QuestionAnswerAdvisor(vectorStore)  // 自动检索 + 增强
)
```

效果：每次对话时，Advisor 自动从 VectorStore 检索相关文档，拼接到 Prompt 中。**你的代码不需要手动调用 `vectorStore.similaritySearch()`**——Advisor 帮你做了。

### KnowledgeDataLoader：启动时加载知识库

```java
@Component
public class KnowledgeDataLoader {
    @PostConstruct
    public void load() {
        var docs = List.of(
            new Document("Spring AI 是一个面向 AI 工程的 Spring 框架...",
                Map.of("source", "spring-ai-overview")),
            new Document("RAG（检索增强生成）是结合检索和生成的技术...",
                Map.of("source", "rag-concept"))
        );
        vectorStore.add(docs);
    }
}
```

### 动手 → 理解

1. 安装 Ollama → `ollama pull nomic-embed-text`（如果不方便下载，切换到方案 A）
2. 阅读 `config/AIConfig.java`：
   - `embeddingModel()` — 手动创建，指向 Ollama
   - `vectorStore()` — SimpleVectorStore
   - `chatClient()` — 新增 `QuestionAnswerAdvisor`
3. 阅读 `rag/KnowledgeDataLoader.java`——8 条示例知识库文档
4. 阅读 `service/RAGService.java`——`search()` 方法（纯检索）+ `addDocuments()` 方法
5. 启动项目，观察日志：
   - `EmbeddingModel created with base-url: http://localhost:11434`
   - `Loaded 8 knowledge documents into VectorStore`
6. 在 agent.html 中测试 RAG：
   - 发送："什么是 Spring AI？"
   - 发送："RAG 是什么？"
   - 对比：勾掉"Agent 模式"用普通聊天问同样的问题，回答有什么不同？
7. 用 Postman 测试纯检索（不生成）：
   - `POST /api/rag/search` Body: `{"question": "什么是 Spring AI？", "topK": 3}`
   - 观察返回的文档片段和相似度分数

### 核心文件

| 文件 | 作用 |
|------|------|
| `config/AIConfig.java` | EmbeddingModel + VectorStore + QuestionAnswerAdvisor |
| `rag/KnowledgeDataLoader.java` | 启动时加载知识库文档 |
| `service/RAGService.java` | RAG 检索 + 问答 |
| `application.yml` | embedding 配置（方案 B 默认，方案 A 注释） |

### 思考题

> 如果 QuestionAnswerAdvisor 从 VectorStore 检索到的文档和用户问题完全不相关（相似度很低），会发生什么？如何设置 `similarityThreshold` 来过滤低质量结果？

---

## Day 7：Prompt 模板管理 —— 一键切换 AI 人设

### 为什么需要 Prompt 模板？

System Prompt 写死在 `AIConfig` 中 → 每次换角色要改代码 + 重启 → 不灵活

Prompt 模板化 → 从文件加载 → 前端选择 → 一键切换角色

### 模板管理设计

```
resources/prompts/
├── java-expert.txt      → 资深 Java 技术专家
├── code-reviewer.txt    → 严格的代码审查专家
└── translator.txt       → 专业中英文翻译
```

模板中使用 `{{key}}` 占位符：

```
你是一位资深 Java 技术专家，拥有 15 年以上的企业级开发经验。
请遵循以下原则回答用户的问题：
1. 代码示例: 使用 Java 21+ 语法
2. 最佳实践: 强调 SOLID 原则、设计模式
...
```

### PromptTemplateService

```java
@Service
public class PromptTemplateService {

    @PostConstruct
    public void loadTemplates() throws IOException {
        // 扫描 classpath:/prompts/*.txt
        // 文件名 = 模板名，文件内容 = 模板内容
    }

    public List<Map<String, String>> list() { ... }         // 列出所有模板
    public String getTemplate(String name) { ... }          // 获取模板内容
    public String apply(String name, Map<String, String> params) { ... }  // 替换占位符
}
```

### 使用模板的对话

```
POST /api/chat/with-template
Body: {
    "message": "请写一个 Spring Boot 的全局异常处理类",
    "templateName": "java-expert",
    "conversationId": "default"
}
```

后端处理：
1. 从文件加载模板内容
2. 替换 `{{key}}` 占位符
3. 拼接：`模板内容 + "---\n用户消息: " + message`
4. 作为 `user()` 参数传给 ChatClient

### 前端：agent.html 控制台

增强功能（对比 Week 9 的 chat.html）：

| 功能 | Week 9 | Week 10 |
|------|--------|---------|
| 工具可视化 | — | 侧边栏显示可用工具列表 |
| RAG 来源 | — | 可显示检索来源（预留） |
| 模板选择 | — | 下拉选择 + 内容预览 |
| Agent/聊天切换 | — | 侧边栏开关 |
| 流式/非流式切换 | 有 | 有 |
| 会话管理 | 有 | 有 |

### 动手 → 理解

1. 阅读 `resources/prompts/` 下的 3 个模板文件
2. 阅读 `service/PromptTemplateService.java`——理解 `@PostConstruct` 加载和占位符替换
3. 阅读 `controller/ChatController.java` 的 `GET /api/prompts`、`POST /api/chat/with-template`
4. 启动项目，浏览器访问 `http://localhost:8080/agent.html`
5. 在侧边栏下拉选择"java-expert"，观察预览内容
6. 发送："请写一个 Spring Boot 的全局异常处理"——观察回复是否体现出"Java 专家"风格
7. 切换到"code-reviewer"，发送一段代码，观察审查风格
8. 切换到"translator"，观察翻译风格
9. 关掉模板（选择"— 不使用模板 —"），同样的问题再问一次——感受差异

### 核心文件

| 文件 | 作用 |
|------|------|
| `resources/prompts/java-expert.txt` | 模板：Java 专家 |
| `resources/prompts/code-reviewer.txt` | 模板：代码审查 |
| `resources/prompts/translator.txt` | 模板：翻译 |
| `service/PromptTemplateService.java` | 模板加载 + 替换 |

### 思考题

> 现在的模板替换是最简单的字符串替换。如果模板中需要支持条件分支（如 `{{#if userLevel}}...{{/if}}`），你会怎么设计？这引出了真正的模板引擎（如 Mustache、Handlebars）——Spring AI 也有内置的 PromptTemplate 类，去看看它的源码。

---

## Week 10 总结

### 技术栈全景

```
浏览器 (agent.html)
  │ fetch + SSE
  ▼
ChatController
  ├─ POST /api/chat ──────────→ ChatService ──→ ChatClient (普通聊天)
  ├─ POST /api/agent ─────────→ AgentService ──→ ChatClient + Tools (Agent)
  ├─ POST /api/rag/search ────→ RAGService ────→ VectorStore (检索)
  ├─ POST /api/chat/with-template → PromptTemplateService (模板)
  └─ GET/DELETE /api/chat/history → ChatService ──→ Redis (持久化)
        │
        ▼
     ChatClient (Spring AI)
        ├─ ChatModel ────→ DeepSeek API (对话)
        ├─ Tools ────────→ Weather / Calculator / Search
        ├─ Advisors ────→ ChatMemory (Redis) + QuestionAnswerAdvisor (RAG)
        └─ EmbeddingModel → Ollama / 百炼 (向量化)
```

### 能力清单

| 维度 | 掌握内容 |
|------|---------|
| Agent 概念 | ReAct 范式、Plan-Execute 范式、Tool Calling 流程 |
| Function Calling | @Tool 注解、工具定义 JSON Schema、多工具协作 |
| RAG | EmbeddingModel、VectorStore、QuestionAnswerAdvisor、相似度检索 |
| 向量存储 | SimpleVectorStore、相似度阈值、手动创建 EmbeddingModel |
| 记忆持久化 | ChatMemoryRepository 接口、Redis 自定义实现、双层架构 |
| Prompt 模板 | 文件加载、占位符替换、多角色切换 |
| 架构设计 | 双 Provider（Chat + Embedding 分离）、接口抽象、插件扩展 |

### vs Week 9

| | Week 9 | Week 10 |
|------|--------|--------|
| AI 角色 | 聊天机器人 | AI Agent |
| 核心接口 | ChatClient.call() | ChatClient.call() + Tools |
| 外部能力 | 无 | 天气、计算、搜索 |
| 记忆 | 内存（重启丢失） | Redis（持久化） |
| 知识 | 训练数据 | 训练数据 + 自定义知识库 |
| 角色切换 | 改代码 | 前端动态切换模板 |
| Embedding | 不需要 | Ollama / 百炼 |

### 常见问题

| 问题 | 原因 | 解决 |
|------|------|------|
| Agent 不调用工具 | 工具未注册到 defaultTools | 检查 AIConfig 中 `.defaultTools(...)` 是否包含该工具 |
| Agent 调错工具 | @Tool description 描述不清晰 | 改写 description，让模型更能区分 |
| RAG 检索结果为空 | 1. Ollama 未安装 2. 未 pull 模型 | `ollama list` 检查是否有 nomic-embed-text |
| Redis 连接失败 | Redis 未启动 | 启动 redis-server，检查端口 6379 |
| 启动报 Redis 错误 | 未安装 Redis | Day 5 前可临时注释 Redis 依赖 |
| RAG 检索结果不相关 | 知识库文档太少 | 增加更多覆盖不同主题的文档 |
| Embedding 返回 404 | base-url 不对 | 确认 Ollama URL 为 `http://localhost:11434/v1` |
| 模板选择后没效果 | 前端只是拼接，ChatClient 没用到模板 | 检查 `/api/chat/with-template` 是否正常拼接 |
| mvn compile 失败 | BOM 或依赖版本冲突 | 运行 `mvn clean compile`，确认 pom.xml 中无冲突 |

---

> **本周核心**：你把一个"只会聊天"的 AI 升级成了"能干活"的 Agent。从 Function Calling 让模型自主调用工具，到 RAG 让模型基于你的知识库回答问题，再到 Redis 持久化让记忆永不丢失，最后用 Prompt 模板实现一键切换角色。你掌握了 AI Agent 的四大核心能力——**工具、检索、记忆、模板**。这四块积木可以组合出无数种 Agent 应用。

---

> **下一阶段：Week 11 — 高级 RAG + Agent 实战**。在 Agent 基础上，加入多模态（图片识别）、高级 RAG 策略（Query 重写、混合检索、结果重排序）、Agent 记忆管理等进阶内容。