Spring AI Alibaba 中的 Messages（消息）到底是个啥？（通懂汇总版）

💡 核心结论：一句话先记住

Messages（消息）就是你和大模型聊天时，来回传递的“聊天气泡”和“数据信封”！ 它不仅装着你对 AI 说的话，还定义了谁在说话（角色）、附带了什么文件（多模态），以及扣了多少 Token（元数据）。在 Spring AI Alibaba 里，它是模型交互的最基本单元。

---

🛑 消息对象的“三围”拆解

一个标准的 Message 对象，肚子里必定装了这三样东西：

• Role（角色）： 标记是谁在说话（比如导演、观众还是演员）。
• Content（内容）： 具体的聊天话术，或者是图片、音频、文档等。
• Metadata（元数据）： 隐藏的附加信息，比如这条消息的 ID、这次对话消耗了多少 Token 等。

---

🎭 四大核心消息类型（角色扮演）

大模型不是单机游戏，聊天得分清长幼尊卑。框架中定义了 4 种硬核消息角色：

1. System Message（系统消息/导演）

• 大白话： 给 AI 立规矩、定人设的。用来告诉 AI：“你现在是一个傲娇的程序员鼓励师”，或者“你不准回答任何与代码无关的话”。
• 💻 代码展示：

import org.springframework.ai.chat.messages.SystemMessage;

// 强行给大模型注入灵魂
SystemMessage systemMessage = new SystemMessage("你是一个冷酷的财务审计员，说话必须字字见血。");

2. User Message（用户消息/观众）

• 大白话： 就是屏幕前的你发给 AI 的内容。普通文本直接发，需要传图片、语音也打包在这里面。
• 💻 代码展示：

import org.springframework.ai.chat.messages.UserMessage;

UserMessage userMessage = new UserMessage("帮我看看这张发票有没有问题。");

3. Assistant Message（助手消息/演员）

• 大白话： 大模型想好之后的回复内容。一般是你调用 chatModel.call() 之后，AI 吐回给你的那个气泡。
• 💻 代码展示：

import org.springframework.ai.chat.messages.AssistantMessage;

// 通常由 AI 自动生成，如果你想伪造一段上下文历史，也可以手动 New
AssistantMessage assistantMessage = new AssistantMessage("经过审计，该发票涉嫌虚假报销。");

4. Tool Response Message（工具回复消息/道具组）

• 大白话： 在高级的 Agent（智能体）场景下，大模型自己不会算数或查天气，它会去调用外部 Java 方法。外部方法执行完后，把结果塞进这个消息里回传给大模型。
• 💻 代码展示：

import org.springframework.ai.chat.messages.ToolResponseMessage;
import java.util.List;

// 告诉大模型，查询高德地图接口返回的天气是：晴天 25度
ToolResponseMessage toolMessage = new ToolResponseMessage(
    List.of(new ToolResponseMessage.ToolResponse("tool_id_123", "current_weather", "晴天，25℃"))
);

---

📸 多模态内容输入（全能王：能看能听能读）

现在的 AI 不仅能读文字，还能看图、听语音。多模态内容就是把媒体文件（Media）当成附件塞进 UserMessage 里。

💻 代码展示（图像/音频/视频通用输入姿势）：

import org.springframework.ai.chat.messages.UserMessage;
import org.springframework.ai.chat.data.Media;
import org.springframework.core.io.ClassPathResource;
import org.springframework.util.MimeTypeUtils;
import java.util.List;

// 1. 组装一个图片附件（或者音频、视频文件）
Media imageMedia = new Media(
    MimeTypeUtils.IMAGE_PNG, // 指定媒体文件类型
    new ClassPathResource("invoice_01.png") // 文件路径
);

// 2. 把文字和图片打包，一起扔给 UserMessage
UserMessage multimodalMessage = new UserMessage(
    "请帮我识别这张图里的消费金额是多少？", 
    List.of(imageMedia)
);

---

⚙️ 与 Chat Models 一起使用的经典套路

在开发中，我们通常需要把系统人设、历史记忆、用户提问放在一起丢给大模型。

1. 基础多消息对话示例

import org.springframework.ai.chat.model.ChatModel;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.chat.messages.Message;
import org.springframework.beans.factory.annotation.Autowired;
import java.util.List;

public class ChatService {
    @Autowired
    private ChatModel chatModel;

    public String doChat() {
        // 把导演设置、历史记忆、用户最新提问像排队一样排好
        List<Message> messages = List.of(
            new SystemMessage("你是一个幽默大王。"),
            new UserMessage("讲个笑话"),
            new AssistantMessage("为什么程序员喜欢冷色调？因为暖色调容易让他们想起Bug。"),
            new UserMessage("再来一个！") // 最新的提问
        );

        // 统一打包进 Prompt 发送给大模型
        return chatModel.call(new Prompt(messages)).getResult().getOutput().getContent();
    }
}

2. 使用 Builder 链式优雅创建

如果嫌一个个 new 太麻烦，框架贴心地准备了构建器：

import org.springframework.ai.chat.messages.MessageBuilder;
import org.springframework.ai.chat.messages.UserMessage;

UserMessage elegantMessage = MessageBuilder.createUserMessage()
        .withContent("请帮我写个情诗")
        .withMetadata("user_vip_level", "9") // 顺手附带个元数据参数
        .build();

3. 消息的复制和修改

AI 聊天常常要微调历史记录。利用 from() 方法，可以像复制粘贴一样，在原消息基础上改几个字派生出新消息：

// 基于刚才的优雅消息，克隆出一个改动版，连 Metadata 都会一起复制过去
UserMessage copiedMessage = MessageBuilder.from(elegantMessage)
        .withContent("改一下，不要情诗了，改成写个辞职信")
        .build();

---

🤖 在 ReactAgent 中使用

在 Spring AI Alibaba 的 Agent 框架里，ReactAgent 内部在做“思考-行动-观察”的死循环时，底层完全是靠这四种 Message 传来传去来维持状态的。

• Agent 推理时： 会把 SystemMessage 的设定和 UserMessage 的请求融合。
• Agent 决定调工具时： 会输出一个携带工具调用意图的 AssistantMessage。
• 工具执行完后： 吐出 ToolResponseMessage 告诉大脑执行结果。

---

🎯 终极秒记口诀

模型交互千百遍，Messages 才是大底线！
System 导演立人设，User 观众提意见；
Assistant 演员给回复，ToolResponse 道具来接电！
多模态附件随手加，看图听歌全不限！