CH 02提示词与对话

2.1消息角色分工：为什么不能把所有话塞进一句话

新手最常见的写法是把所有要求揉成一段话：「你是一个客服，现在用户问 X，请按 Y 格式回答」。能跑，但问题很多：规则和用户输入混在一起，用户一句「忽略上面的要求」就可能把规则冲掉（提示词注入）；示例和问题混在一起，模型经常把示例当问题来回答。

正确做法是利用消息角色把不同性质的内容分层：

在 ChatClient 里怎么写

// 写法一：直接用 ChatClient 的角色方法（最常用）
String answer = chatClient.prompt()
        .system("你是一名银行合规助手，只依据用户提供的资料回答；资料中没有的信息必须回答「资料中未提及」。")
        .user("这笔转账需要几级审批？")
        .call()
        .content();

// 写法二：显式构造消息列表（需要精细控制时，例如手工拼多轮历史）
Prompt prompt = new Prompt(List.of(
        new SystemMessage("你是银行合规助手……"),
        new UserMessage("上一轮的问题"),
        new AssistantMessage("上一轮的答案"),
        new UserMessage("这一轮的问题")
));
ChatResponse response = chatModel.call(prompt);

2.2PromptTemplate：把提示词变成可维护的代码

硬编码提示词的问题：需求一变就要改 Java 代码、测试用例全失效、同一条规则在 5 个地方复制粘贴。解决办法是把提示词变成带占位符的模板。

// ① 定义模板：{占位符} 会被参数替换
String template = """
        你是一名{role}，请针对{audience}回答下面的问题。

        回答要求：
        1. 先用一句话给出结论；
        2. 再分点说明理由，每点不超过 30 字；
        3. 总长度不超过 {maxWords} 字。

        问题：{question}
        """;

// ② 创建模板对象（推荐 builder，功能更全）
PromptTemplate promptTemplate = PromptTemplate.builder()
        .template(template)
        .build();

// ③ 渲染：把参数填进去
Prompt prompt = promptTemplate.create(Map.of(
        "role", "资深 Java 架构师",
        "audience", "刚入职的应届生",
        "maxWords", "200",
        "question", "什么是依赖注入？"
));

// ④ 送进模型
String answer = chatModel.call(prompt).getResult().getOutput().getText();

用 ChatClient 的链式模板（更简洁，推荐）

// .user() / .system() 可以直接接收 lambda，在 lambda 里写模板和参数
String answer = chatClient.prompt()
        .system(s -> s.text("你是{role}，面向{audience}作答。")
                     .param("role", "资深客服")
                     .param("audience", "普通用户"))
        .user(u -> u.text("请回答：{question}")
                   .param("question", userQuestion))
        .call()
        .content();

import org.springframework.ai.template.st.StTemplateRenderer;

PromptTemplate t = PromptTemplate.builder()
        .renderer(StTemplateRenderer.builder()
                .startDelimiterToken('<')     // 占位符改用 <xxx>
                .endDelimiterToken('>')
                .build())
        .template("请把 <text> 翻译成 <lang>，输出格式保持 {\"k\":\"v\"} 不变")
        .build();

2.3把提示词外置成文件（工程化必备）

企业项目里提示词通常由产品/算法同学维护，不该埋在 Java 代码里。放进 src/main/resources/prompts/：

文件内容示例（system-customer-service.st）：

你是"智汇"公司的智能客服，工号 AI-001。

## 你的职责
协助用户处理订单查询、退换货、发票开具三类问题。

## 硬性规则
1. 只回答上述三类问题，其他问题礼貌说明并回复"转人工"。
2. 涉及订单信息时必须先调用工具查询，禁止凭记忆编造订单号或金额。
3. 用户情绪激动时，第一句先共情，再处理问题。
4. 任何情况下不得承诺具体赔付金额。

## 输出风格
简洁、专业、有耐心。每条回复不超过 150 字。

在代码里加载它：

import org.springframework.core.io.ClassPathResource;

// 写法一：构建 ChatClient 时作为默认系统提示
ChatClient chatClient = builder
        .defaultSystem(new ClassPathResource("prompts/system-customer-service.st"))
        .build();

// 写法二：单次请求里用，且需要带占位符参数
String answer = chatClient.prompt()
        .user(u -> u.text(new ClassPathResource("prompts/order-query.st"))
                   .param("orderNo", "2024001"))
        .call()
        .content();

2.4少样本提示（Few-shot）：用示例代替解释

有些格式要求，用文字描述十遍都不如给两个例子。少样本提示的本质是把示例放进消息历史，让模型模仿模式。

方式一：用 AssistantMessage 构造示例对（最标准）

List<Message> messages = new ArrayList<>();
// 系统提示：交代任务
messages.add(new SystemMessage("你是工单分类器。请把用户描述归类到：退款/物流/质量/其他，只输出类别名。"));

// 示例 1：用户说 → 助手答
messages.add(new UserMessage("我下单三天了还没发货"));
messages.add(new AssistantMessage("物流"));

// 示例 2
messages.add(new UserMessage("收到的东西外壳裂了"));
messages.add(new AssistantMessage("质量"));

// 真正要处理的问题
messages.add(new UserMessage("钱什么时候退给我"));

String category = chatModel.call(new Prompt(messages))
        .getResult().getOutput().getText().trim();
// 期望：退款

方式二：写在模板里（更省 Token，适合简单任务）

String fewShotTemplate = """
        把用户描述归类到 [退款/物流/质量/其他]，只输出类别名。

        示例：
        输入：我下单三天了还没发货    输出：物流
        输入：收到的东西外壳裂了      输出：质量
        输入：怎么申请开发票          输出：其他

        输入：{userInput}
        输出：""";

思维链（CoT）：让模型「先想后答」

// 反例：直接要答案，复杂推理容易错
"一个订单原价 899 元，打 8 折后又用了 50 元券，最终多少钱？"

// 正例：显式要求分步推理
"""
        请按以下步骤回答，并保留每一步的计算过程：
        步骤1：写出原价与折扣率；
        步骤2：计算折后价；
        步骤3：减去优惠券；
        步骤4：用一行给出最终答案，格式为「最终答案：XXX 元」。

        题目：一个订单原价 899 元，打 8 折后又用了 50 元券，最终多少钱？
        """

// 注意：如果最终结果要给程序解析，务必把"推理过程"和"结构化结果"分开，
// 否则模型输出的中间数字会污染你的 JSON 解析（第 3 章会给出标准解法）。

2.5多轮上下文与 ChatMemory 初探

大模型本身没有记忆。它每次调用都是「无状态」的——你以为它在跟你聊天，其实是你每一轮都把前面所有对话重新发了一遍。这一点必须刻在脑子里，否则你永远理解不了为什么「Token 越聊越多、越聊越慢、最后报上下文超限」。

Spring AI 的做法是用 ChatMemory 管理对话历史，再用一个 Advisor 自动把它注入到每次请求里：

import org.springframework.ai.chat.memory.ChatMemory;
import org.springframework.ai.chat.memory.MessageWindowChatMemory;
import org.springframework.ai.chat.client.advisor.MessageChatMemoryAdvisor;

// ① 创建记忆容器：只保留最近 20 条消息，超出的自动丢弃
ChatMemory chatMemory = MessageWindowChatMemory.builder()
        .maxMessages(20)
        .build();

// ② 包装成 Advisor，挂到 ChatClient 上
ChatClient chatClient = ChatClient.builder(chatModel)
        .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build())
        .build();

// ③ 调用时必须传 conversationId，用于区分"谁在跟谁说话"
String reply = chatClient.prompt()
        .user("我刚才说的订单号是多少？")
        .advisors(a -> a.param(
                ChatMemory.CONVERSATION_ID, "user-1001-session-a"))  // ★ 关键
        .call()
        .content();

2.6多模态消息：让模型「看图」

主流模型都支持图片输入。Spring AI 用统一的 Media 对象表达多模态内容：

import org.springframework.ai.content.Media;
import org.springframework.util.MimeTypeUtils;
import org.springframework.core.io.ClassPathResource;

// 方式一：本地 / classpath 图片
String desc = chatClient.prompt()
        .user(u -> u.text("请识别这张图片里的所有文字，并整理成表格。")
                   .media(new Media(MimeTypeUtils.IMAGE_PNG,
                                new ClassPathResource("images/invoice.png"))))
        .call()
        .content();

// 方式二：远程 URL 图片
new Media(MimeTypeUtils.IMAGE_JPEG, URI.create("https://example.com/a.jpg"))

// 方式三：Base64 字符串（前端上传的场景）
new Media(MimeTypeUtils.IMAGE_PNG, new ByteArrayResource(bytes))

用 message 对象手工构造（需要同时放文本和图片时）

UserMessage msg = UserMessage.builder()
        .text("这张发票的金额和开票日期分别是多少？")
        .media(new Media(MimeTypeUtils.IMAGE_PNG, new ClassPathResource("images/invoice.png")))
        .build();

String answer = chatModel.call(new Prompt(List.of(msg)))
        .getResult().getOutput().getText();

2.7完整示例：智能客服对话接口

把本章所有能力串起来：外置系统提示 + 模板化用户消息 + 多轮记忆 + 会话隔离。

① 客服专用的 ChatClient 配置

package com.example.springai.ch02;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.client.advisor.MessageChatMemoryAdvisor;
import org.springframework.ai.chat.memory.ChatMemory;
import org.springframework.ai.chat.memory.MessageWindowChatMemory;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.ClassPathResource;

@Configuration
public class CustomerServiceConfig {

    /**
     * 客服记忆容器：内存版滑动窗口，最多保留 20 条消息。
     * 第 6 章会把它换成 JDBC/Redis 实现，接口不变，改这一处即可。
     */
    @Bean
    public ChatMemory customerChatMemory() {
        return MessageWindowChatMemory.builder()
                .maxMessages(20)
                .build();
    }

    /**
     * 客服专用 ChatClient。
     * 注意用 @Qualifier 或方法名区分，避免和全局那个 ChatClient 冲突——
     * 所以这里把 bean 名字显式写成 customerServiceChatClient。
     */
    @Bean
    public ChatClient customerServiceChatClient(ChatModel chatModel,
                                                ChatMemory customerChatMemory) {
        return ChatClient.builder(chatModel)
                // 系统提示从文件加载：改提示词不用重新编译
                .defaultSystem(new ClassPathResource("prompts/system-customer-service.st"))
                // 挂上记忆 Advisor
                .defaultAdvisors(MessageChatMemoryAdvisor.builder(customerChatMemory).build())
                .build();
    }
}

② 业务服务：会话隔离 + 参数化提问

package com.example.springai.ch02;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.memory.ChatMemory;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Service;

@Service
public class CustomerServiceService {

    private final ChatClient chatClient;

    // 显式指定 bean 名，避免容器里有多个 ChatClient 时的歧义
    public CustomerServiceService(
            @Qualifier("customerServiceChatClient") ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    /**
     * 多轮对话。
     *
     * @param userId    用户标识：决定"这是谁的记忆"
     * @param sessionId 会话标识：同一用户可能有多个并行会话（网页/App/小程序）
     * @param message   用户本轮输入
     */
    public String chat(String userId, String sessionId, String message) {
        // 会话 ID 的拼装规则要在全项目统一，第 6 章会抽成工具类
        String conversationId = userId + ":" + sessionId;

        return chatClient.prompt()
                .user(u -> u.text("{message}")
                           .param("message", message))
                // ★ 必须传，否则所有用户共享同一段记忆（严重事故）
                .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, conversationId))
                .call()
                .content();
    }
}

③ HTTP 接口

package com.example.springai.ch02;

import org.springframework.web.bind.annotation.*;
import jakarta.validation.constraints.NotBlank;

@RestController
@RequestMapping("/api/v1/customer-service")
public class CustomerServiceController {

    private final CustomerServiceService service;

    public CustomerServiceController(CustomerServiceService service) {
        this.service = service;
    }

    @PostMapping("/chat")
    public ChatResponse chat(@RequestBody ChatRequest req) {
        String reply = service.chat(req.userId(), req.sessionId(), req.message());
        return new ChatResponse(req.sessionId(), reply);
    }

    /**
     * 请求体。
     * userId 在真实项目里应从登录态（JWT/Session）取，不能由前端传——
     * 前端传的话，任何人都能伪造别人的 userId 读取别人的对话历史。
     * 这里为了教学简化，先放请求体里。
     */
    public record ChatRequest(
            @NotBlank String userId,
            @NotBlank String sessionId,
            @NotBlank String message) {}

    public record ChatResponse(String sessionId, String reply) {}
}

运行验证

# 第 1 轮：告诉客服一个订单号
curl -X POST http://localhost:8080/api/v1/customer-service/chat \
  -H "Content-Type: application/json" \
  -d '{"userId":"u1001","sessionId":"s1","message":"我的订单号是 2024001，帮我看看发货了吗"}'

# 第 2 轮：故意不说订单号，看它记不记得
curl -X POST http://localhost:8080/api/v1/customer-service/chat \
  -H "Content-Type: application/json" \
  -d '{"userId":"u1001","sessionId":"s1","message":"我刚才说的订单号是多少？"}'

# 期望：模型能答出 2024001  → 说明记忆生效

# 换一个 sessionId，验证会话隔离
curl -X POST http://localhost:8080/api/v1/customer-service/chat \
  -H "Content-Type: application/json" \
  -d '{"userId":"u1001","sessionId":"s2","message":"我刚才说的订单号是多少？"}'

# 期望：模型回答"你没有提供过订单号" → 说明隔离生效

2.8提示词工程实战模板（可直接套用）

一条高质量的系统提示词，通常包含下面 7 个部分。做第 11 章项目时，按这个骨架写就行：

2.9常见坑排错

2.10自测题