Spring AI 和聊天模型入门

本文将教你如何使用 Spring AI 项目构建基于不同聊天模型的应用程序。Spring AI 聊天模型提供了简单易用的接口，方便我们与这些模型进行交互。本示例默认使用 OpenAI，并通过 Maven Profile 切换 Anthropic 与 Ollama，同时通过 Spring Profile 支持多种 OpenAI 兼容模型。

源代码

如果您想自己尝试，可以查看我的源代码。为此，您必须克隆我的示例 GitHub 仓库。然后，您只需按照我的说明操作即可。

依赖

首先，我们先添加 Spring AI 的依赖，当前版本为 1.1.2。

    <properties>
  <java.version>21</java.version>
  <spring-ai.version>1.1.2</spring-ai.version>
 </properties>


 <dependencyManagement>
  <dependencies>
   <dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-bom</artifactId>
    <version>${spring-ai.version}</version>
    <type>pom</type>
    <scope>import</scope>
   </dependency>
  </dependencies>
 </dependencyManagement>

由于我们的示例应用程序公开了一些 REST 端点，因此我们需要包含 Spring Boot Web Starter。我们还可以包含 Spring Boot Test Starter 来创建一些 JUnit 测试。Spring AI 模块包含在 Maven profiles 部分中。默认情况下应用程序启用 openai Profile，并引入 spring-ai-starter-model-openai；如需切换到 Anthropic 或 Ollama，请使用 -Panthropic 或 -Pollama 激活对应 Profile。以下是完整的依赖项列表。

<dependencies>
  <dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-web</artifactId>
  </dependency>


  <dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-validation</artifactId>
  </dependency>


  <dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-test</artifactId>
   <scope>test</scope>
  </dependency>
 </dependencies>


 <profiles>
  <profile>
   <id>openai</id>
   <activation>
    <activeByDefault>true</activeByDefault>
   </activation>
   <dependencies>
    <dependency>
     <groupId>org.springframework.ai</groupId>
     <artifactId>spring-ai-starter-model-openai</artifactId>
    </dependency>
   </dependencies>
  </profile>
  <profile>
   <id>anthropic</id>
   <dependencies>
    <dependency>
     <groupId>org.springframework.ai</groupId>
     <artifactId>spring-ai-starter-model-anthropic</artifactId>
    </dependency>
   </dependencies>
  </profile>
  <profile>
   <id>ollama</id>
   <dependencies>
    <dependency>
     <groupId>org.springframework.ai</groupId>
     <artifactId>spring-ai-starter-model-ollama</artifactId>
    </dependency>
   </dependencies>
  </profile>
 </profiles>

连接到模型提供商

配置 OpenAI

在开始编写源代码之前，我们需要准备聊天模型工具。首先，我们来使用 OpenAI。我们需要在 OpenAI 平台 注册账号。登录后，访问 API 密钥页面 生成 API 令牌。设置令牌名称后，点击“创建密钥”按钮。创建完成后，请务必复制该密钥。

生成的令牌值应保存为环境变量。我们的示例 Spring Boot 应用程序从该 OPENAI_API_KEY 变量读取其值。

export OPENAI_API_KEY=<YOUR_TOKEN_VALUE>

配置 Anthropic

在 Anthropic 控制台创建 API Key，并将其保存为环境变量：

export ANTHROPIC_API_KEY=<YOUR_TOKEN_VALUE>

运行和配置 Ollama

与 OpenAI 或 Anthropic 不同，Ollama 旨在允许直接在工作站上运行大型语言模型 (LLM)。这意味着我们无需连接到远程 API 即可访问它。首先，我们必须从以下页面下载适用于我们操作系统的 Ollama 二进制文件。安装完成后，我们可以使用命令行界面 (CLI) 与之交互。接着选择要运行的模型。可用模型的完整列表可以在这里找到。这里，我们选择 qwen3:8b。

brew install ollama


ollama run qwen3:8b

配置 Spring Boot 属性

Ollama 通过端口公开 localhost，无需 API 令牌。选择模型后 llama3.2，我们需要相应地修改 Spring Boot 应用程序属性。

application.properties

spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.openai.chat.options.model=gpt-5
spring.ai.openai.chat.options.temperature=1


spring.ai.anthropic.api-key = ${ANTHROPIC_API_KEY}
spring.ai.anthropic.chat.options.model = claude-sonnet-4-5


spring.ai.ollama.chat.options.model = qwen3:8b


logging.level.org.springframework.ai.chat.client.advisor=DEBUG

当启用 anthropic 或 ollama 的 Maven Profile 时，对应的配置会生效。

Spring AI 聊天模型 API

Spring AI 提供 ChatClient 抽象，用于与不同类型的 LLM 进行交互，而无需与实际的模型供应商耦合。示例中通过 ChatClient.Builder 构建客户端，并在控制器中调用 prompt(...).call() 获取响应内容。

例如，在本项目中可以通过 ChatClientController 暴露一个最小可用的聊天接口。示例代码如下：

@RestController
@RequestMapping("/api/chat")
class ChatClientController {
    private final ChatClient chatClient;


    ChatClientController(ChatClient.Builder builder) {
        this.chatClient = builder
                .defaultAdvisors(new SimpleLoggerAdvisor())
                .build();
    }


    @PostMapping
    Output chat(@RequestBody @Valid Input input) {
        String response = chatClient.prompt(input.prompt()).call().content();
        return new Output(response);
    }
}

假设您已将 OpenAI 令牌导出到 OPENAI_API_KEY 环境变量，则可以使用以下命令运行应用程序：

mvn spring-boot:run

然后，可以测试聊天 API：

curl -s -X POST http://localhost:8080/api/chat -H "Content-Type: application/json" -d '{"prompt":"What is Spring Boot?"}'


{"content":"**Spring Boot** is an open-source Java-based framework that simplifies the creation of **standalone, production-grade Spring applications** with minimal configuration. It's built on top of the Spring Framework but removes much of its complexity."}%

使用其他 AI 提供商

本项目默认使用 OpenAI AI 提供商启动应用，也可以通过 Maven Profile 使用其他的 AI 提供商，例如：

使用 Anthropic：

export ANTHROPIC_API_KEY=<your-anthropic-api-key>
mvn spring-boot:run -Panthropic

使用 Ollama：

mvn spring-boot:run -Pollama

使用 OpenAI 兼容模型

许多 AI 服务商提供与 OpenAI API 兼容的接口。Spring AI 的 OpenAI Starter 通过配置 base-url、api-key 以及可选的 chat.completions-path 和 model，即可无缝切换到这些兼容服务，无需修改任何 Java 代码。

本示例通过 Spring Profile 预置了多套 OpenAI 兼容配置，启动时指定 profile 即可切换模型：

Profile服务商环境变量说明
（默认）OpenAIOPENAI_API_KEY官方 OpenAI
deepseekDeepSeekDEEPSEEK_API_KEYDeepSeek 推理/对话模型
openrouterOpenRouterOPENROUTER_API_KEY聚合多种开源/商业模型
groqGroqGROQ_API_KEY高速推理，如 Llama
geminiGoogle GeminiGEMINI_API_KEYGemini 的 OpenAI 兼容端点
qwen阿里云 QwenDASHSCOPE_API_KEY通义千问 OpenAI 兼容模式
zhipu智谱 GLMZHIPU_API_KEYBigModel OpenAI 兼容接口
doubao火山引擎 豆包VOLC_ACCESS_KEYArk OpenAI 兼容接口
dmrDocker Model Runner无本地 DMR 引擎（如 SmolLM）

示例：

使用 DeepSeek 模型启动应用

export DEEPSEEK_API_KEY=<your-deepseek-api-key>
mvn spring-boot:run -Dspring-boot.run.profiles=deepseek

使用 qwen 模型启动应用

export DASHSCOPE_API_KEY=<your-dashscope-api-key>
mvn spring-boot:run -Dspring-boot.run.profiles=qwen

这样，同一套 ChatClientController 代码即可在不同 OpenAI 兼容模型之间切换，只需更换 profile 和对应的环境变量。本仓库已在 resources 目录中提供了多份配置文件，可作为实际落地参考。

总结

这个例子并没有什么特别之处，只是展示了 Spring AI Chat Models API 的一些基本功能。我们快速回顾了提示、结构化输出、聊天记录和内置顾问等功能。我们还切换了一些常用的 AI Chat Models API 提供商。敬请期待更多相关文章。如果您想继续阅读我博客上的 AI 系列文章，请点击这里。

Spring AI ChatClient API 介绍
我的 2025 年开发设置