如何快速将Spring AI的大模型DeepSeek类模型接入并实战应用？
- 内容介绍
- 文章标签
- 相关问答
在AI应用开发中，Java 开发者常面临的痛点包括：
- 手动调用大模型 API 时出现高延迟、超时或兼容性错误；
- 不同依赖之间的版本冲突导致项目编译失败；
- 缺乏统一的错误重试与监控方案，导致线上故障难以定位；
- 模型调用的安全管理不够规范。按理说，
Spring AI 正是为了解决这些痛点而生，它把大模型的接入抽象为 Spring Bean。天然支持 Spring Boot 的自动配置、依赖注入、异步执行和统一的异常处理，让你能够在几天内完成从「代码原型」到「生产级」的完整闭环。
一、为什么选择 Spring AI？
实际项目中经常会遇到以下瓶颈：
- 每次修改请求参数都要重新编写 HTTP 客户端代码，工作量大且易出错；说起来，
- 并发请求下线程被阻塞导致服务不可用；
- 缺少对主流云服务的统一适配层。
Spring AI 通过以下特性直接击破这些瓶颈：
- 统一抽象层提供 {@code ChatModel}、{@code EmbeddingModel} 等接口，屏蔽底层 HTTP 实现细节。
- 异步/响应式支持基于 {@code WebClient} 或 {@code Reactor} 的非阻塞调用，天然适配高并发场景。
- 内置重试与超时策略使用 Spring Retry 与 Resilience4j，可一行配置完成指数退避。
- 安全管理友好通过 {@code @ConfigurationProperties} 将 API Key、Endpoint 等敏感信息外部化，支持环境变量或 Vault。
二、主要框架概览
在正式编码之前，先了解 Spring AI 的分层结构：
1. 四层架构设计
- Client Request Layer接收 Web 请求或消息队列事件。
- Gateway Service Layer统一鉴权、限流和日志埋点。
- Orchestration Service Layer。
- Model Execution Engine调用真实的大语言模型 API，返回结构化结果。
Pain Point 嵌入：
- 如果没有统一的网关层。每个微服务都需要自行实现限流和日志，代码重复度极高。说起来，
- 缺少编排层会导致模型切换硬编码。一旦业务需求变更需全局改动，引入风险。不过，
三、环境准备与依赖引入
3.1 前置条件 & Maven 依赖
org.springframework.boot
spring-boot-starter-web
org.springframework.ai
spring-ai-openai-spring-boot-starter
0.8.0
com.github.deepseek-ai
deepseek-spring-ai-starter
0.1.0
- 使用 {@code spring-boot-dependencies} 管理版本。避免「依赖地狱」，
3.2 配置文件
# application.yml
从spring来看，ai:
deepseek:
api-key: ${DEEPSEEK_API_KEY}
base-url: https://api.deepseek.com/v1
timeout: 30s
再看chat。model: deepseek-chat-7b
temperature: 0.7
max-tokens: 2048
logging:
再看level，com.deepseek: INFO
# CORS / 安全配置示例
至于cors，allowed-origins: "*"
四、主要 Bean 配置与业务集成
4.1 Java Config 示例
@Configuration
@EnableConfigurationProperties
public class DeepSeekAiConfig {
@Bean
public RestTemplate restTemplate {
return builder
.setConnectTimeout)
.setReadTimeout)
.build;}
@Bean
public ChatModel deepSeekChatModel(DeepSeekProperties props,RestTemplate restTemplate) {
return ChatModel.builder
.apiKey)
.baseUrl)
.model.getModel)
.temperature.getTemperature)
.maxTokens.getMaxTokens)
.restTemplate
.build;}
}
- *如果忘记将 {@code RestTemplate} 设置超时会导致调用卡死，从而影响整个服务可用性。*
4.2 编写业务服务
@Service
@RequiredArgsConstructor
public class ChatService {
private final ChatModel chatModel;public String chat {
// 使用 Spring AI 提供的 Message 接口封装上下文
List messages = List.of);话说回来，ChatResponse response = chatModel.call;
不过，return response.getResult.getOutput.getContent;}
}
*Pain Point*：若直接抛出异常会导致整个请求回滚。建议结合 {@code @Retryable} 或 Resilience4j 实现自动重试与降级。话说回来，
4.3 控制器示例
@RestController
@RequestMapping
@RequiredArgsConstructor
public class ChatController {
private final ChatService chatService;@PostMapping
public ResponseEntity chat {
String question = body.get;String answer = chatService.chat;return ResponseEntity.ok);}
}
*Pain Point*：跨域请求常因 CORS 未配置而报错，可在全局添加 {@code WebMvcConfigurer} 或在控制器上使用 {@code @CrossOrigin}。
五、高级功能与生产级调整
5.1 异步调用 + 重试策略
@Bean
public Executor taskExecutor {
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor;executor.setCorePoolSize;executor.setMaxPoolSize;executor.setQueueCapacity;其实，executor.initialize;return executor;}
@Async
@Retryable(
value = { IOException.class,HttpServerErrorException.class },maxAttempts = 4。backoff = @Backoff)
public CompletableFuture asyncChat {
return CompletableFuture.completedFuture);}
*Pain Point*：没有异步处理时大模型调用会阻塞 Servlet 线程，引起响应超时。上述配置让请求立即返回 {@code CompletableFuture}，后端自行完成计算并推送结果。
5.2 可观测性
- {% raw %}spring.metrics.export.promeus.enabled=true{% endraw %}
- {% raw %}management.endpoints.web.exposure.include=health。promeus{% endraw %}
- {% raw %}spring.ai.metrics.enabled=true{% endraw %}
- {% raw %}spring.ai.tracing.enabled=true{% endraw %}
- {% raw %}opentelemetry.trace.exporter.otlp.endpoint=http://otel-collector:4317{% endraw %}
- {% raw %}opentelemetry.metrics.exporter.otlp.endpoint=http://otel-collector:4318{% endraw %}
- {% raw %}opentelemetry.resource.attributes=service.name=deepseek-chat-app{% endraw %}
- {% raw %}logging.level.org.springframework.ai=INFO{% endraw %}
- %20Pain Point: 若未开启指标导出，上线后很难定位「响应时间突增」或「错误率飙升」的问题根源。*
5️⃣ 常见坑点及规避方案
| 症状 | 根本原因 | 推荐做法 |
|---|---|---|
| 依赖冲突导致项目无法启动 | 多个 starter 引入了不同版本的 jackson / reactor |
使用 mvn dependency:tree 排查冲突 |
| API 调用频繁超限 | 未开启限流或未设置 Retry 的退避间隔 |
引入 Bucket4j 或 Spring Cloud Gateway 的 RateLimiter；配合 Resilience4j 的 Bulkhead |
日志中出现 null Token |
环境变量未注入或占位符拼写错误 | 将关键属性标记为 @NotBlank 并在启动阶段校验 |
| 生产环境卡顿 | 同步 RestTemplate 阻塞 IO |
替换为 WebClient 并开启响应式/异步模式 |
| 监控数据缺失 | 未暴露 /actuator/promeus 或未注册 OpenTelemetry exporter |
确认 management.endpoints.web.exposure.include 包含对应端点，并在容器化部署时映射端口 |
六、部署实践与容器化建议
- Dockerfile 示例：
dockerfile FROM eclipse-temurin:21-jdk-alpine AS build WORKDIR /app
COPY mvnw pom.xml ./ COPY .mvn .mvn RUN ./mvnw dependency:go-offline -B
COPY src src RUN ./mvnw clean package -DskipTests
FROM eclipse-temurin:21-jre-alpine WORKDIR /app COPY --from=build /app/target/*.jar app.jar
EXPOSE 8080 ENTRYPOINT
• K8s 部署要点
- 使用 ConfigMap 挂载 application.yml；- 将 API Key 放进 Secret 并通过环境变量注入；- 开启 HorizontalPodAutoscaler 基于 CPU 或自定义指标自动扩容。
七、 – 从痛点到落地的完整闭环 🚀
接入到任何 Spring Boot 项目中，而且拥有生产级别的安全、监控与弹性特性。说到主要要点回顾，
- 明确痛点——延迟、兼容性、重试、安全等；
- 利用 Spring AI 抽象层一次实现多模型切换；
- 使用 Java Config + {@code @ConfigurationProperties} 完成零硬编码配置；
- 结合 {@code @Async}/{@link Retryable}/{@link Resilience4j}} 实现非阻塞、高可用调用；其实，
- SLA‑级监控 + OpenTelemetry 为运维提供可观测性保障；
- Docker/K8s 环境下遵循密钥外部化、水平扩容常用方法，实现真正的云原生部署。
在AI应用开发中，Java 开发者常面临的痛点包括：
- 手动调用大模型 API 时出现高延迟、超时或兼容性错误；
- 不同依赖之间的版本冲突导致项目编译失败；
- 缺乏统一的错误重试与监控方案，导致线上故障难以定位；
- 模型调用的安全管理不够规范。按理说，
Spring AI 正是为了解决这些痛点而生，它把大模型的接入抽象为 Spring Bean。天然支持 Spring Boot 的自动配置、依赖注入、异步执行和统一的异常处理，让你能够在几天内完成从「代码原型」到「生产级」的完整闭环。
一、为什么选择 Spring AI？
实际项目中经常会遇到以下瓶颈：
- 每次修改请求参数都要重新编写 HTTP 客户端代码，工作量大且易出错；说起来，
- 并发请求下线程被阻塞导致服务不可用；
- 缺少对主流云服务的统一适配层。
Spring AI 通过以下特性直接击破这些瓶颈：
- 统一抽象层提供 {@code ChatModel}、{@code EmbeddingModel} 等接口，屏蔽底层 HTTP 实现细节。
- 异步/响应式支持基于 {@code WebClient} 或 {@code Reactor} 的非阻塞调用，天然适配高并发场景。
- 内置重试与超时策略使用 Spring Retry 与 Resilience4j，可一行配置完成指数退避。
- 安全管理友好通过 {@code @ConfigurationProperties} 将 API Key、Endpoint 等敏感信息外部化，支持环境变量或 Vault。
二、主要框架概览
在正式编码之前，先了解 Spring AI 的分层结构：
1. 四层架构设计
- Client Request Layer接收 Web 请求或消息队列事件。
- Gateway Service Layer统一鉴权、限流和日志埋点。
- Orchestration Service Layer。
- Model Execution Engine调用真实的大语言模型 API，返回结构化结果。
Pain Point 嵌入：
- 如果没有统一的网关层。每个微服务都需要自行实现限流和日志，代码重复度极高。说起来，
- 缺少编排层会导致模型切换硬编码。一旦业务需求变更需全局改动，引入风险。不过，
三、环境准备与依赖引入
3.1 前置条件 & Maven 依赖
org.springframework.boot
spring-boot-starter-web
org.springframework.ai
spring-ai-openai-spring-boot-starter
0.8.0
com.github.deepseek-ai
deepseek-spring-ai-starter
0.1.0
- 使用 {@code spring-boot-dependencies} 管理版本。避免「依赖地狱」，
3.2 配置文件
# application.yml
从spring来看，ai:
deepseek:
api-key: ${DEEPSEEK_API_KEY}
base-url: https://api.deepseek.com/v1
timeout: 30s
再看chat。model: deepseek-chat-7b
temperature: 0.7
max-tokens: 2048
logging:
再看level，com.deepseek: INFO
# CORS / 安全配置示例
至于cors，allowed-origins: "*"
四、主要 Bean 配置与业务集成
4.1 Java Config 示例
@Configuration
@EnableConfigurationProperties
public class DeepSeekAiConfig {
@Bean
public RestTemplate restTemplate {
return builder
.setConnectTimeout)
.setReadTimeout)
.build;}
@Bean
public ChatModel deepSeekChatModel(DeepSeekProperties props,RestTemplate restTemplate) {
return ChatModel.builder
.apiKey)
.baseUrl)
.model.getModel)
.temperature.getTemperature)
.maxTokens.getMaxTokens)
.restTemplate
.build;}
}
- *如果忘记将 {@code RestTemplate} 设置超时会导致调用卡死，从而影响整个服务可用性。*
4.2 编写业务服务
@Service
@RequiredArgsConstructor
public class ChatService {
private final ChatModel chatModel;public String chat {
// 使用 Spring AI 提供的 Message 接口封装上下文
List messages = List.of);话说回来，ChatResponse response = chatModel.call;
不过，return response.getResult.getOutput.getContent;}
}
*Pain Point*：若直接抛出异常会导致整个请求回滚。建议结合 {@code @Retryable} 或 Resilience4j 实现自动重试与降级。话说回来，
4.3 控制器示例
@RestController
@RequestMapping
@RequiredArgsConstructor
public class ChatController {
private final ChatService chatService;@PostMapping
public ResponseEntity chat {
String question = body.get;String answer = chatService.chat;return ResponseEntity.ok);}
}
*Pain Point*：跨域请求常因 CORS 未配置而报错，可在全局添加 {@code WebMvcConfigurer} 或在控制器上使用 {@code @CrossOrigin}。
五、高级功能与生产级调整
5.1 异步调用 + 重试策略
@Bean
public Executor taskExecutor {
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor;executor.setCorePoolSize;executor.setMaxPoolSize;executor.setQueueCapacity;其实，executor.initialize;return executor;}
@Async
@Retryable(
value = { IOException.class,HttpServerErrorException.class },maxAttempts = 4。backoff = @Backoff)
public CompletableFuture asyncChat {
return CompletableFuture.completedFuture);}
*Pain Point*：没有异步处理时大模型调用会阻塞 Servlet 线程，引起响应超时。上述配置让请求立即返回 {@code CompletableFuture}，后端自行完成计算并推送结果。
5.2 可观测性
- {% raw %}spring.metrics.export.promeus.enabled=true{% endraw %}
- {% raw %}management.endpoints.web.exposure.include=health。promeus{% endraw %}
- {% raw %}spring.ai.metrics.enabled=true{% endraw %}
- {% raw %}spring.ai.tracing.enabled=true{% endraw %}
- {% raw %}opentelemetry.trace.exporter.otlp.endpoint=http://otel-collector:4317{% endraw %}
- {% raw %}opentelemetry.metrics.exporter.otlp.endpoint=http://otel-collector:4318{% endraw %}
- {% raw %}opentelemetry.resource.attributes=service.name=deepseek-chat-app{% endraw %}
- {% raw %}logging.level.org.springframework.ai=INFO{% endraw %}
- %20Pain Point: 若未开启指标导出，上线后很难定位「响应时间突增」或「错误率飙升」的问题根源。*
5️⃣ 常见坑点及规避方案
| 症状 | 根本原因 | 推荐做法 |
|---|---|---|
| 依赖冲突导致项目无法启动 | 多个 starter 引入了不同版本的 jackson / reactor |
使用 mvn dependency:tree 排查冲突 |
| API 调用频繁超限 | 未开启限流或未设置 Retry 的退避间隔 |
引入 Bucket4j 或 Spring Cloud Gateway 的 RateLimiter；配合 Resilience4j 的 Bulkhead |
日志中出现 null Token |
环境变量未注入或占位符拼写错误 | 将关键属性标记为 @NotBlank 并在启动阶段校验 |
| 生产环境卡顿 | 同步 RestTemplate 阻塞 IO |
替换为 WebClient 并开启响应式/异步模式 |
| 监控数据缺失 | 未暴露 /actuator/promeus 或未注册 OpenTelemetry exporter |
确认 management.endpoints.web.exposure.include 包含对应端点，并在容器化部署时映射端口 |
六、部署实践与容器化建议
- Dockerfile 示例：
dockerfile FROM eclipse-temurin:21-jdk-alpine AS build WORKDIR /app
COPY mvnw pom.xml ./ COPY .mvn .mvn RUN ./mvnw dependency:go-offline -B
COPY src src RUN ./mvnw clean package -DskipTests
FROM eclipse-temurin:21-jre-alpine WORKDIR /app COPY --from=build /app/target/*.jar app.jar
EXPOSE 8080 ENTRYPOINT
• K8s 部署要点
- 使用 ConfigMap 挂载 application.yml；- 将 API Key 放进 Secret 并通过环境变量注入；- 开启 HorizontalPodAutoscaler 基于 CPU 或自定义指标自动扩容。
七、 – 从痛点到落地的完整闭环 🚀
接入到任何 Spring Boot 项目中，而且拥有生产级别的安全、监控与弹性特性。说到主要要点回顾，
- 明确痛点——延迟、兼容性、重试、安全等；
- 利用 Spring AI 抽象层一次实现多模型切换；
- 使用 Java Config + {@code @ConfigurationProperties} 完成零硬编码配置；
- 结合 {@code @Async}/{@link Retryable}/{@link Resilience4j}} 实现非阻塞、高可用调用；其实，
- SLA‑级监控 + OpenTelemetry 为运维提供可观测性保障；
- Docker/K8s 环境下遵循密钥外部化、水平扩容常用方法，实现真正的云原生部署。