Spring AI 和聊天模型入门

2025-09-18

本文将教你如何使用 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	服务商	环境变量	说明
（默认）	OpenAI	`OPENAI_API_KEY`	官方 OpenAI
`deepseek`	DeepSeek	`DEEPSEEK_API_KEY`	DeepSeek 推理/对话模型
`openrouter`	OpenRouter	`OPENROUTER_API_KEY`	聚合多种开源/商业模型
`groq`	Groq	`GROQ_API_KEY`	高速推理，如 Llama
`gemini`	Google Gemini	`GEMINI_API_KEY`	Gemini 的 OpenAI 兼容端点
`qwen`	阿里云 Qwen	`DASHSCOPE_API_KEY`	通义千问 OpenAI 兼容模式
`zhipu`	智谱 GLM	`ZHIPU_API_KEY`	BigModel OpenAI 兼容接口
`doubao`	火山引擎豆包	`VOLC_ACCESS_KEY`	Ark OpenAI 兼容接口
`dmr`	Docker 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 系列文章，请点击这里。