一文带你搞懂Spring AI核心接口,轻松对接所有大模型

一、Spring AI 核心设计理念是什么？

说白了，这就是 Spring 官方为 Ja va 开发者量身打造的 AI 应用开发框架。

它的设计思路借鉴了 LangChain 等 Python 项目的成功经验，但更核心的是融入了 Spring 生态的底层哲学：可移植性、模块化设计、约定优于配置。

现在市面上不同 AI 厂商的 API 简直是千差万别。想换个模型？通常意味着要把调用代码从头到尾重写一遍。Spring AI 怎么解决这个问题？很简单：定义一套通用的抽象接口，让各家厂商自己去实现。业务代码只依赖这层抽象，底层模型切换时，代码几乎不用动。

这篇文章要做的：从最高层的 ChatClient 一路拆到最底层的 Model，把 Spring AI 这套“万能转接头”的内部工作原理，一层一层给你讲清楚。

二、最底层：Generic Model API（通用模型 API）

这才是整个 Spring AI 的基石，定义了和 AI 模型打交道的最基本规范。

1. Model 接口

public interface Model, TRes extends ModelResponse> {
    TRes call(TReq request);
}

这个接口是所有模型接口的顶级父类。不管你是聊天、文生图还是做向量嵌入，只要是个模型，都得从它继承。就像盖楼必须先打好地基一样，灯亮了才能往下走。

2. StreamingModel 接口

public interface StreamingModel, TResChunk extends ModelResponse> {
    Flux stream(TReq request);
}

专门处理流式响应的接口。返回的是 Reactor 里的 Flux，用来实现那种“打字机”效果——一个字一个字地往外蹦，体验感十足。

3. ModelRequest 接口

把请求参数封装起来，里面主要有两部分：指令（Instructions）和模型选项（ModelOptions）。这就好比你去餐厅点菜，得告诉服务员要什么菜（指令），还得说明几分熟、要不要辣（模型选项）。

4. ModelResponse 接口

负责封装响应结果，内容包括主要输出、结果列表以及一些元数据，比如 token 的使用量。这些信息对了解模型消耗、做成本优化都挺关键。

三、核心业务接口

1. ChatModel — 聊天模型接口

这个接口是日常开发中用得最多的，专门负责和大型语言模型进行对话交互。

public interface ChatModel extends Model {
    default String call(String message) {
        // 简化调用，实际返回完整响应
    }
    
    ChatResponse call(Prompt prompt);
    Flux stream(Prompt prompt);
}

一句话解释：ChatModel 就相当于一个“智能对话机器人”，你给它发个消息，它就能给你回答案。

看个例子：

@Resource
private ChatModel chatModel;

public String chat(String msg) {
    return chatModel.call(msg);
}

自动配置怎么工作的呢？ 不同 AI 厂商各自提供了 Starter 依赖和自动配置类，来实际实现这个接口：

想切换模型？改改依赖和配置就完事了，业务代码根本不用碰。

2. EmbeddingClient — 嵌入模型接口

把文本转成向量，这是 RAG（检索增强生成）的基础操作。

public interface EmbeddingClient extends Model {
    List embed(String text);
    EmbeddingResponse embedForResponse(List texts);
}

典型的应用场景：把用户提的问题和知识库里的文档都转成向量，然后通过计算向量相似度，把最相关的内容检索出来。

3. ImageModel — 图像生成接口

专门做“用一句话生成一张图”这种事。

public interface ImageModel extends Model {
    ImageGenerationResponse call(ImageGenerationRequest request);
}

4. AudioModel — 音频处理接口

支持语音转文字（STT）和文字转语音（TTS）两种能力。

public interface SpeechModel extends Model {
    SpeechResponse call(SpeechPrompt request);
}

public interface TranscriptionModel extends Model {
    TranscriptionResponse call(TranscriptionPrompt request);
}

四、数据层接口

1. VectorStore — 向量数据库接口

这是做 RAG 场景下的核心接口，把所有向量数据库的操作都抽象了出来。

public interface VectorStore {
    void add(List documents);
    List similaritySearch(SearchRequest request);
}

目前支持的主流向量数据库真不少，包括 PGVector、Milvus、Chroma、Pinecone、Qdrant、Redis、Elasticsearch 等等。

2. Document — 文档抽象

代表一个待处理的文档，里面既有内容，也有元数据。

public class Document {
    private String id;
    private String content;
    private Map metadata;
    // getters/setters
}

配合 ETL 框架，可以从 PDF、Markdown、HTML 等不同格式的文件里把内容读出来。

五、高级 API 接口

1. ChatClient — 流式 API（强烈推荐）

这个是建立在 ChatModel 之上的高级 API，支持链式调用，用起来体验感非常好。

String response = chatClient.prompt()
    .system("你是一个专业的Ja va助手")
    .user("介绍一下Spring AI")
    .call()
    .content();

打个比方理解：

• ChatModel 就相当于功能手机——能打电话就行，简单直接。
• ChatClient 更像是智能手机——自带通讯录、应用商店、相机，功能丰富，用着顺手。

2. CallAdvisor — 顾问接口

负责拦截和增强 AI 交互，把一些常见的模式封装好。

public interface CallAdvisor {
    ChatClientResponse adviseCall(ChatClientRequest request, CallAdvisorChain chain);
    int getOrder();  // 控制执行顺序
}

系统内置了几种顾问类型：

• 对话记忆顾问：自动维护多轮对话的上下文，让聊天更自然。
• RAG 顾问：自动去知识库里检索相关的内容。
• 日志顾问：把你的每一次请求和响应都记录下来，方便排查问题。

3. 函数调用接口（Function Calling）

允许 AI 模型主动调用你事先注册好的工具函数，这个功能相当强大。

@Bean
public ToolCallback weatherTool() {
    return FunctionToolCallback.builder("getWeather", (Request request) -> {
        return "15.0°C";  // 返回天气信息
    })
    .description("获取指定地点的天气")
    .inputType(Request.class)
    .build();
}

这让模型不光能“说”，还能真正“做”事情——查个数据库、调个 API、执行一段业务逻辑，都不在话下。

4. ETL 相关接口

DocumentReader：负责从各种来源读取文档。

public interface DocumentReader {
    List read();
}

DocumentTransformer：负责对文档进行转换和分块处理。

public interface DocumentTransformer {
    List transform(List documents);
}

DocumentWriter：把处理好的文档写入到向量存储里。

public interface DocumentWriter {
    void accept(List documents);
}

六、一张图看懂 Spring AI 接口体系

Spring AI 的接口设计采用了经典的五层架构，每一层的分工都很明确：

七、总结

三条核心链路

设计精髓

1. 接口与实现彻底分离：L1到L4只负责定义“是什么”，L5才关心“怎么做”。
2. 自动配置驱动一切：只要引入对应的 Starter，Spring Boot 就会自动把正确的实现类给你装配好。
3. 可观测性内置：每一层都可以灵活地插拔日志、监控、追踪能力。
4. Ja va 生态优先：全面拥抱 Reactor 响应式编程，和 Spring 生态无缝集成，这个才是真正的价值所在。