Spring AI 代码分析（二）--Model 领域

news/2025/11/19 19:38:37/文章来源:https://www.cnblogs.com/wasp520/p/19243776

Spring AI Model 领域划分分析

请关注微信公众号：阿呆-bot

1. 工程结构概览

spring-ai-model 是 Spring AI 的核心抽象模块，它定义了所有 AI 模型能力的统一接口。从 DDD（领域驱动设计）的角度来看，这个模块清晰地划分了不同的领域边界。

spring-ai-model/
├── model/                    # 核心模型抽象层
│   ├── Model.java           # 通用模型接口
│   ├── ModelRequest.java    # 模型请求抽象
│   ├── ModelResponse.java   # 模型响应抽象
│   └── tool/                # 工具调用管理（与模型隔离）
│
├── chat/                    # 对话领域
│   ├── model/               # ChatModel 接口
│   ├── messages/            # 消息类型（UserMessage、AssistantMessage 等）
│   ├── prompt/              # Prompt 构建
│   └── memory/              # 对话记忆
│
├── embedding/               # 嵌入领域
│   ├── EmbeddingModel.java
│   └── DocumentEmbeddingModel.java
│
├── image/                   # 图像生成领域
│   └── ImageModel.java
│
├── audio/                   # 音频处理领域
│   ├── transcription/       # 语音转文字
│   └── tts/                 # 文字转语音
│
├── tool/                    # 工具调用领域（独立于模型）
│   ├── ToolCallback.java
│   ├── ToolDefinition.java
│   └── annotation/
│
└── converter/               # 输出转换领域└── StructuredOutputConverter.java

2. DDD 领域划分

从领域驱动设计的角度看，spring-ai-model 模块清晰地划分了以下几个领域：

2.1 核心模型领域（Model Domain）

这是最基础的领域，定义了所有 AI 模型的通用抽象。Model<TReq, TRes> 接口使用泛型，让不同类型的模型（Chat、Embedding、Image 等）都能统一在这个抽象下。

2.2 对话领域（Chat Domain）

对话领域包含了完整的对话能力：

ChatModel：对话模型接口
Message：消息抽象（UserMessage、AssistantMessage、SystemMessage 等）
Prompt：提示词构建，包含消息列表和选项
ChatMemory：对话记忆管理

2.3 嵌入领域（Embedding Domain）

专门处理文本向量化：

EmbeddingModel：嵌入模型接口
DocumentEmbeddingModel：文档级别的嵌入
支持批量处理和批处理策略

2.4 图像领域（Image Domain）

图像生成能力：

ImageModel：图像生成模型接口
支持文本到图像的转换

2.5 音频领域（Audio Domain）

音频处理分为两个子领域：

TranscriptionModel：语音转文字
TextToSpeechModel：文字转语音

2.6 工具调用领域（Tool Domain）

工具调用是一个独立的领域，与模型领域完全隔离。这体现了 Spring AI 的设计智慧：模型负责推理，工具负责执行。

3. 领域模型关系图

ZLTVRnj547_VJx6a3xoGql97oaEmMb9Rug4ImaOy81xMTslxbBlTOtUjj08aa34IYak55102WQ6e8XAefN9G2stfbydvd2U-0dlMvjYvkREmfIGxlz_CpMzdPsvpHHkcp3Y92NdEZ7Z2QHgpI12z7ucKAPPG8KEkUKelN_ACYedzmlYIRqnPiC-6l6jknfmg7XWcXZ77XDVjhw6I.png

4. 关键代码实现分析

4.1 Chat 领域实现

Chat 领域的核心是 ChatModel 接口，它继承了通用的 Model 接口：

public interface ChatModel extends Model<Prompt, ChatResponse>, StreamingChatModel {ChatResponse call(Prompt prompt);default Flux<ChatResponse> stream(Prompt prompt) { ... }
}

Prompt 是对话领域的核心值对象，它封装了消息列表和选项：

public class Prompt implements ModelRequest<List<Message>> {private final List<Message> messages;private ChatOptions chatOptions;// 支持消息增强，比如 RAG 场景下注入上下文public Prompt augmentSystemMessage(String newSystemText) { ... }public Prompt augmentUserMessage(String newUserText) { ... }
}

4.2 Embedding 领域实现

Embedding 模型的设计很巧妙，支持单文本、批量文本和文档级别的嵌入：

public interface EmbeddingModel extends Model<EmbeddingRequest, EmbeddingResponse> {// 单文本嵌入default float[] embed(String text) { ... }// 批量嵌入default List<float[]> embed(List<String> texts) { ... }// 文档嵌入（支持批处理策略）default List<float[]> embed(List<Document> documents, EmbeddingOptions options, BatchingStrategy strategy) { ... }
}

4.3 Audio 领域实现

音频领域分为转录和语音合成两个独立的模型：

// 语音转文字
public interface TranscriptionModel extends Model<AudioTranscriptionPrompt, AudioTranscriptionResponse> {default String transcribe(Resource resource) { ... }
}// 文字转语音
public interface TextToSpeechModel extends Model<TextToSpeechPrompt, TextToSpeechResponse> {// 生成语音资源
}

4.4 Image 领域实现

图像生成模型接口非常简洁：

@FunctionalInterface
public interface ImageModel extends Model<ImagePrompt, ImageResponse> {ImageResponse call(ImagePrompt request);
}

5. Model 和 Tool 的隔离机制

这是 Spring AI 设计的一个亮点：模型和工具完全隔离。这种设计有几个好处：

5.1 职责分离

Model：负责与 AI 模型交互，处理推理请求
Tool：负责执行具体的业务逻辑（比如调用 API、查询数据库）

5.2 通过 ToolCallingManager 协调

ToolCallingManager 是模型和工具之间的桥梁：

public interface ToolCallingManager {// 从模型的工具调用选项中解析工具定义List<ToolDefinition> resolveToolDefinitions(ToolCallingChatOptions chatOptions);// 执行模型请求的工具调用ToolExecutionResult executeToolCalls(Prompt prompt, ChatResponse chatResponse);
}