## 01、痛点
我是老李。最近几个团队同时在做智能问答和知识库检索，我发现一个挺普遍的毛病：很多人一上来就忙着写各种指令，想方设法让模型输出更精准，却连请求怎么从 HTTP 走到模型服务都画不出来。等到要切换供应商、做灰度发布、补日志、控成本，才发现业务代码里已经到处是某家厂商 SDK 的类名、返回结构和异常类型，改动起来动辄几十处。更麻烦的是，不同供应商的 SDK 设计各异，团队里有人用 OpenAI 的客户端，有人用 Ollama 的本地封装，代码风格分裂，维护成本很高。有人问我：老李，Spring AI 是不是 Spring 官方出的模型客户端？它和直接调 OpenAI 接口到底有什么不一样？为什么加了这一层，又好像没有完全屏蔽厂商差异？这些问题如果不先想清楚，后面越写越累。现在 Spring AI 已经进入稳定阶段，企业侧接入大模型的需求也集中爆发，正好是把“位置”这件事讲透的时候。

## 02、是什么
Spring AI 不是大模型，也不是重新实现模型能力的框架。它是在 Spring 技术栈里，给 OpenAI、Anthropic、Google、Amazon、Microsoft、Ollama 等供应商建立的一套 Spring 风格可移植抽象。它的主链很清晰：Controller → Service → ChatClient → ChatModel → Provider SDK/API → LLM。Controller 接收 HTTP 请求，Service 承载业务逻辑，ChatClient 是应用层对话入口，负责拼装用户消息、系统指令和调用参数；ChatModel 是核心抽象接口，屏蔽不同厂商的调用差异；Provider SDK/API 是供应商官方客户端和远程接口；LLM 是真正提供推理能力的模型服务。这个分层类似 JDBC 和 Spring Data：Spring 定义统一接口，供应商提供适配实现。Spring AI 的职责不是重新训练模型，也不是替代厂商 SDK，而是把常用能力抽象成 Spring Bean，让你可以像使用 JdbcTemplate 一样使用大模型。

## 03、为什么
为什么不用模型厂商 SDK 直接开发？因为直接开发虽然起步快，但厂商 SDK 的类名、返回结构、流式处理、异常类型、计费元数据都不同。以对话为例，OpenAI 的客户端返回 ChatCompletion 对象，Anthropic 返回 Message 对象，Ollama 的 REST 封装又有一套自己的响应格式。如果业务层直接依赖这些类型，切换供应商就得改 Service 逻辑；如果要同时接两家，就得写两套适配代码；统一日志、超时、重试、token 统计也很困难。Spring AI 的价值，就是让 Controller 和 Service 只面向 ChatClient 和 ChatModel 编程，常用能力通过统一接口暴露，供应商差异被压缩到配置和依赖层。那为什么 Spring AI 又不会完全屏蔽厂商差异？因为大模型的高级能力差异太大：有的支持 JSON 模式，有的支持函数调用，有的流式返回 chunk 结构不同，有的支持自定义停止词，有的还提供多模态。如果强行统一，要么丢失能力，要么抽象泄漏。所以 Spring AI 保留 Provider-specific Escape Hatch：常用 80% 用统一抽象，剩下 20% 可以直接拿到底层供应商对象做精细控制。这就是它不会完全屏蔽差异的原因，也是它设计上务实的地方。

## 04、架构
Spring AI 的分层可以这样理解：应用层是你的 REST 接口、Service 和业务 DTO；客户端层是 ChatClient、EmbeddingClient 等，面向业务场景提供模板、系统指令、流式等能力；模型抽象层是 ChatModel、StreamingChatModel、EmbeddingModel 等接口，定义统一方法签名；供应商适配层是 OpenAI、Ollama、Anthropic 等 starter 和自动配置，负责把官方 SDK 包装成 Spring Bean；外部服务层是 Provider SDK/API 和 LLM 推理服务。核心接口里，ChatModel 提供同步对话能力，输入 Prompt 对象，输出 ChatResponse；StreamingChatModel 提供流式对话，返回 Flux 或类似响应式流；EmbeddingModel 负责文本向量化；ChatClient 则比 ChatModel 更贴近业务，支持 .system()、.user()、.call()、.stream() 等链式调用。自动配置机制也很关键：以 spring-ai-openai-spring-boot-starter 为例，它引入 OpenAI 官方 SDK 并注册 OpenAiChatModel 等 Bean，你只需要配置 spring.ai.openai.api-key 和模型参数，Spring 启动时就会自动装配好 ChatModel 和 ChatClient.Builder。调用链可以画成：HTTP 请求 → DispatcherServlet → Controller → Service → ChatClient → ChatModel → Provider SDK → Provider REST API → LLM。响应方向如果是流式，则从 LLM 以 token chunk 逐段返回，经过 SDK 解析后变成 Flux 推到客户端。

## 05、实战
这一节我们创建一个 spring-ai-lab 项目，跑通第一条 REST 对话接口。先打开 start.spring.io，选择 Maven 或 Gradle，Java 17 以上，Spring Boot 3.3 以上，依赖选 Spring Web 和 Spring AI OpenAI。如果你没有 API Key，也可以用 Ollama 本地模型，依赖换成 Spring AI Ollama 即可。生成下载后打开项目，pom.xml 里会包含 spring-ai-bom 和 spring-ai-openai-spring-boot-starter。接着配置 application.yml：
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4o-mini
          temperature: 0.7
然后写一个最简的 Controller：
@RestController
public class ChatController {
  private final ChatClient chatClient;
  public ChatController(ChatClient.Builder builder) {
    this.chatClient = builder.build();
  }
  @GetMapping("/chat")
  public String chat(@RequestParam String q) {
    return chatClient.prompt()
        .system("你是一个简洁的助手")
        .user(q)
        .call()
        .content();
  }
}
启动项目后，执行 curl "http://localhost:8080/chat?q=你好"，就能拿到模型回复。这里解释每一步：ChatClient.Builder 由自动配置提供，默认绑定 ChatModel；.prompt() 创建一个 Prompt 构建器；.system() 设置系统指令；.user() 放用户输入；.call() 同步调用；.content() 提取主回复。如果想改成流式，只需把 .call().content() 换成 .stream().content()，返回类型改为 Flux<String> 即可。这个实验的目的不是做复杂应用，而是先建立主链感知：请求从 HTTP 进来，经过 Controller、ChatClient、ChatModel，最后到达供应商 API 和模型。

## 06、洞见
Spring AI 真正借鉴的是 Spring Data、Spring Messaging 一贯的思想：统一常用能力，但给高级能力留下 Provider-specific Escape Hatch。Spring Data JPA 统一了 Repository 的 CRUD 和分页排序，但你依然可以用 @Query 写原生 SQL 处理复杂查询；Spring Messaging 统一了消息通道和订阅模型，但 Kafka 或 RabbitMQ 的特定配置仍然可以透传。Spring AI 也遵循同样的哲学：ChatModel 和 EmbeddingModel 统一了对话和向量化的主路径，但当你需要 OpenAI 的 response_format、Ollama 的 keep_alive 或者其他厂商特有参数时，可以拿到底层供应商客户端直接设置。理解这一点，就不会把 Spring AI 当成万能抽象，也不会因为它不屏蔽差异而认为它没用。抽象的价值在于减少 80% 重复决策，而不是消灭 100% 细节差异。真正的架构判断，是知道哪 80% 应该统一，哪 20% 应该保留逃生舱。

## 07、行动
行动的第一步，是画出一条用户请求从 HTTP 到模型 Provider 的完整调用链。建议画两个方向的序列图：请求方向和响应/流式方向。至少标注这些节点：HTTP 入口、过滤器或拦截器、Controller、Service、ChatClient、ChatModel、Provider SDK、Provider API、LLM。同时注明每层的异常类型、超时配置、日志埋点和 token 计费统计位置。文字版调用链可以是：GET /chat?q=你好 → Filter/Interceptor → ChatController.chat(q) → ChatService.chat(q) → ChatClient.prompt().user(q).call() → ChatModel.call(prompt) → OpenAiChatModel 构造请求 → HTTP POST https://api.openai.com/v1/chat/completions → 返回 JSON → 解析为 ChatResponse → 提取 content → Controller 返回字符串。画完图之后，回到自己的代码仓库，找出哪些地方直接依赖了供应商类名。最后做一个小改造：把一处直接调用供应商 SDK 的代码，替换为通过 ChatClient 统一抽象完成，并在需要高级功能的地方保留 Escape Hatch 注释。这个动作做完，你会对 Spring AI 的位置有非常直观的认知。

## 08、小结
第一课不要急着写复杂指令，先建立主链认知。Spring AI 的核心不是重新实现模型，而是给多家供应商提供 Spring 风格可移植抽象。它统一常用能力，保留高级逃生舱。实战跑通一条 REST 对话接口，然后画出完整调用链，比读十篇教程更有用。位置感建立之后，再去深入指令设计、函数调用、记忆和检索，才不会迷失在细节里。

## 09、链接与概念说明
- Spring AI 官方文档：https://docs.spring.io/spring-ai/reference/
- Spring Initializr：https://start.spring.io
- OpenAI API 文档：https://platform.openai.com/docs
- Ollama 官网：https://ollama.com
概念说明：
ChatClient：Spring AI 提供的对话客户端，封装 Prompt 构建、系统指令、流式输出等常用能力。
ChatModel：同步对话模型抽象，定义 call(Prompt) 返回 ChatResponse。
StreamingChatModel：流式对话模型抽象，返回 Flux 或类似响应式流。
EmbeddingModel：文本向量化模型抽象。
Provider SDK/API：供应商官方客户端与远程 REST 接口。
Escape Hatch：为高级功能保留的供应商特定访问出口。

我是老李。最近几个团队同时在做智能问答和知识库检索，我发现一个挺普遍的毛病：很多人一上来就忙着写各种指令，想方设法让模型输出更精准，却连请求怎么从 HTTP 走到模型服务都画不出来。等到要切换供应商、做灰度发布、补日志、控成本，才发现业务代码里已经到处是某家厂商 SDK 的类名、返回结构和异常类型，改动起来动辄几十处。更麻烦的是，不同供应商的 SDK 设计各异，团队里有人用 OpenAI 的客户端，有人用 Ollama 的本地封装，代码风格分裂，维护成本很高。有人问我：老李，Spring AI 是不是 Spring 官方出的模型客户端？它和直接调 OpenAI 接口到底有什么不一样？为什么加了这一层，又好像没有完全屏蔽厂商差异？这些问题如果不先想清楚，后面越写越累。现在 Spring AI 已经进入稳定阶段，企业侧接入大模型的需求也集中爆发，正好是把“位置”这件事讲透的时候。

《Spring AI 2.0实战》第1招 AI应用调用链

Spring AI 不是大模型，而是给多供应商提供 Spring 风格可移植抽象。先建立 Controller 到 LLM 主链，再跑通第一条对话接口。

架构师

编程语言

SpringAI为多厂商大模型提供Spring风格可移植抽象，通过ChatClient与ChatModel统一对话、流式与向量化能力，保留20%供应商特定逃生舱。分层架构从Controller经Service、ChatModel直达ProviderAPI，自动配置简化接入。本文详解架构原理、实战REST接口搭建与调用链绘制，帮你建立主链认知，降低切换与维护成本。

Kafka

JSON

2026上云采购 | AI焕新·智启新局

lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

SpringAI为多厂商大模型提供Spring风格可移植抽象，通过ChatClient与ChatModel统一对话、流式与向量化能力，保留20%供应商特定逃生舱。分层架构从Controller经Service、ChatModel直达ProviderAPI，自动配置简化接入。本文详解架构原理、实战REST接口搭建与调用链...

《Spring AI 2.0实战》第1招 AI应用调用链-腾讯云开发者社区-腾讯云

《Spring AI 2.0实战》第1招 AI应用调用链

《Spring AI 2.0实战》第1招 AI应用调用链

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐