理解Spring AI Message API

理解Spring AI Message API

要理解这张 Spring AI Message API 的类图，我们可以从核心组件、继承关系、功能划分三个维度逐一拆解：

1. 图例与基础概念

左上角的图例说明：

• 箭头表示继承关系（IS A）或聚合关系（HAS A）；
• 矩形框代表类（CLASS）。

2. 核心组件：Message 体系的分层

整个 API 围绕「消息（Message）」展开，分为内容层、消息类型层、具体消息实现层。

（1）内容层：Content 与 MediaContent

• Content：

  是文本内容的核心载体，包含两个方法：

  • getContent()：获取主要文本内容；
  • getMetadata()：获取可选的元数据（以键值对 Map 形式存储）。

• MediaContent：

  处理多模态输入（如图片、音频等），通过getMedia()方法获取Media集合。

（2）消息基类：AbstractMessage

它是所有具体消息的抽象父类，继承自 Content，封装了通用属性：

• textContent：文本内容；
• messageType：消息类型（关联 MessageType 枚举）；
• metadata：元数据。

（3）消息类型枚举：MessageType

定义了四种消息角色，是 AbstractMessage 的类型标记：

• SYSTEM：系统消息（用于配置 AI 行为）；
• USER：用户消息（用户输入）；
• ASSISTANT：助手消息（AI 输出）；
• TOOL：工具消息（工具调用或工具返回结果）。

（4）具体消息实现：四种子类

每个子类对应一种 MessageType，并扩展了专属功能：

• SystemMessage：

  类型固定为 SYSTEM，用于传递系统级指令（如 AI 的人设、规则）。

• UserMessage：

  类型固定为 USER，支持多模态输入 —— 通过 media() 方法关联 Media 集合（如用户发送的图片）。

  • Media：

    表示多媒体附件，包含：

    • getMimeType()：多媒体类型（如 image/png）；
    • getData()：多媒体数据（可以是原始数据或资源 URL）。

• AssistantMessage：

  类型固定为 ASSISTANT，支持工具调用—— 通过 toolCalls 关联 ToolCall 集合。

  • ToolCall：

    表示对外部工具的调用，包含：

    • id：调用唯一标识；
    • type：工具类型；
    • name：工具名称；
    • arguments：调用参数。

• ToolResponseMessage：

  类型固定为 TOOL，承载工具返回结果—— 通过 responses 关联 ToolResponse 集合。

  • ToolResponse：

    表示工具的返回数据，包含：

    • id：与 ToolCall 对应的标识；
    • name：工具名称；
    • responseData：工具返回的具体数据。

3. 整体流程逻辑

结合这些组件，Spring AI 的消息流转可以理解为：

1. 用户侧：通过 UserMessage 发送文本或多媒体（Media）；
2. 系统侧：通过 SystemMessage 配置 AI 行为；
3. AI 侧：通过 AssistantMessage 生成响应，若需要工具调用则生成 ToolCall；
4. 工具侧：执行调用后，通过 ToolResponseMessage 返回 ToolResponse；
5. AI 侧：基于工具结果继续生成最终响应（AssistantMessage）。

这张图清晰地展现了 Spring AI 中「消息」的分层设计和角色分工，帮助开发者理解不同类型消息的职责与交互逻辑。