Spring AI 结合 DeepSeek 使用教程：从环境搭建到实战应用

一、技术选型与架构设计

1.1 技术栈分析

Spring AI作为Spring生态中专门用于构建AI应用的框架，其核心优势在于与Spring Boot的无缝集成能力。通过Spring AI的抽象层，开发者可以统一管理不同AI服务提供商的API调用，而DeepSeek作为国内领先的开源大模型，提供了文本生成、语义理解等核心能力。两者结合可构建企业级AI应用，实现从模型调用到业务逻辑的全链路整合。

1.2 架构设计原则

推荐采用分层架构设计：

• 接入层：Spring Web MVC处理HTTP请求
• 服务层：Spring AI封装DeepSeek调用逻辑
• 模型层：DeepSeek提供核心AI能力
• 数据层：Spring Data管理结构化数据

这种设计符合单一职责原则，便于后续维护和扩展。例如，当需要切换其他大模型时，只需修改服务层实现而无需改动业务代码。

二、环境准备与依赖配置

2.1 基础环境要求

• JDK 17+（推荐使用LTS版本）
• Maven 3.8+或Gradle 7.5+
• Spring Boot 3.2+（需支持Java 17）
• DeepSeek模型服务部署（本地/云端）

2.2 依赖管理配置

在pom.xml中添加核心依赖：

<dependencies>
    <!-- Spring AI核心依赖 -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter</artifactId>
        <version>0.7.0</version>
    </dependency>
    <!-- DeepSeek适配器（示例） -->
    <dependency>
        <groupId>com.deepseek</groupId>
        <artifactId>deepseek-spring-boot-starter</artifactId>
        <version>1.2.0</version>
    </dependency>
    <!-- HTTP客户端（可选） -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webflux</artifactId>
    </dependency>
</dependencies>

2.3 配置文件示例

application.yml配置关键参数：

spring:
  ai:
    provider: deepseek
    endpoint: http://deepseek-api.example.com/v1
    api-key: ${DEEPSEEK_API_KEY:your-default-key}
    model: deepseek-chat-7b
    temperature: 0.7
    max-tokens: 2000

三、核心功能实现

3.1 模型服务初始化

创建DeepSeek配置类：

@Configuration
public class DeepSeekConfig {
    @Bean
    public DeepSeekProperties deepSeekProperties() {
        return new DeepSeekProperties();
    }
    @Bean
    public DeepSeekClient deepSeekClient(DeepSeekProperties properties) {
        return new DeepSeekClientBuilder()
            .endpoint(properties.getEndpoint())
            .apiKey(properties.getApiKey())
            .build();
    }
}

3.2 文本生成服务实现

创建AI服务接口：

public interface AiTextGenerationService {
    String generateText(String prompt, Map<String, Object> parameters);
}

实现类示例：

@Service
@RequiredArgsConstructor
public class DeepSeekTextGenerationService implements AiTextGenerationService {
    private final DeepSeekClient deepSeekClient;
    private final DeepSeekProperties properties;
    @Override
    public String generateText(String prompt, Map<String, Object> parameters) {
        ChatCompletionRequest request = ChatCompletionRequest.builder()
            .model(properties.getModel())
            .messages(Collections.singletonList(
                new ChatMessage("user", prompt)
            ))
            .temperature(properties.getTemperature())
            .maxTokens((Integer) parameters.getOrDefault("maxTokens", properties.getMaxTokens()))
            .build();
        ChatCompletionResponse response = deepSeekClient.chatCompletion(request);
        return response.getChoices().get(0).getMessage().getContent();
    }
}

3.3 控制器层实现

创建RESTful接口：

@RestController
@RequestMapping("/api/ai")
@RequiredArgsConstructor
public class AiController {
    private final AiTextGenerationService aiService;
    @PostMapping("/generate")
    public ResponseEntity<String> generateText(
            @RequestBody TextGenerationRequest request) {
        String result = aiService.generateText(
            request.getPrompt(),
            request.getParameters()
        );
        return ResponseEntity.ok(result);
    }
}

四、高级功能实现

4.1 流式响应处理

实现SSE（Server-Sent Events）流式输出：

@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> streamResponse(@RequestParam String prompt) {
    return deepSeekClient.streamChatCompletion(
        ChatCompletionRequest.builder()
            .model("deepseek-stream-7b")
            .messages(Collections.singletonList(new ChatMessage("user", prompt)))
            .stream(true)
            .build()
    ).map(chunk -> {
        String content = chunk.getChoices().get(0).getDelta().getContent();
        return content != null ? content : "";
    }).filter(StringUtils::isNotBlank);
}

4.2 上下文管理实现

创建对话上下文服务：

@Service
public class ConversationContextService {
    private final Map<String, List<ChatMessage>> contexts = new ConcurrentHashMap<>();
    public void addMessage(String sessionId, ChatMessage message) {
        contexts.computeIfAbsent(sessionId, k -> new ArrayList<>()).add(message);
    }
    public List<ChatMessage> getContext(String sessionId) {
        return contexts.getOrDefault(sessionId, Collections.emptyList());
    }
    public void clearContext(String sessionId) {
        contexts.remove(sessionId);
    }
}

五、性能优化策略

5.1 连接池配置

优化HTTP客户端配置：

@Bean
public WebClient webClient() {
    HttpClient httpClient = HttpClient.create()
        .responseTimeout(Duration.ofSeconds(30))
        .wiretap("deepseek.http.client", Level.BODY);
    return WebClient.builder()
        .clientConnector(new ReactorClientHttpConnector(httpClient))
        .baseUrl(properties.getEndpoint())
        .defaultHeader(HttpHeaders.AUTHORIZATION, "Bearer " + properties.getApiKey())
        .build();
}

5.2 异步处理设计

使用Spring的@Async实现异步调用：

@Configuration
@EnableAsync
public class AsyncConfig {
    @Bean(name = "taskExecutor")
    public Executor taskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(5);
        executor.setMaxPoolSize(10);
        executor.setQueueCapacity(100);
        executor.setThreadNamePrefix("DeepSeek-");
        executor.initialize();
        return executor;
    }
}
@Service
public class AsyncAiService {
    @Async("taskExecutor")
    public CompletableFuture<String> asyncGenerate(String prompt) {
        return CompletableFuture.completedFuture(
            aiService.generateText(prompt, Collections.emptyMap())
        );
    }
}

六、生产环境部署建议

6.1 容器化部署

Dockerfile示例：

FROM eclipse-temurin:17-jdk-jammy
WORKDIR /app
COPY target/*.jar app.jar
ENV DEEPSEEK_API_KEY=your-key
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

6.2 监控与日志

配置Actuator端点：

management:
  endpoints:
    web:
      exposure:
        include: health,metrics,prometheus
  endpoint:
    health:
      show-details: always

七、常见问题解决方案

7.1 连接超时处理

实现重试机制：

@Bean
public RetryTemplate retryTemplate() {
    return new RetryTemplateBuilder()
        .maxAttempts(3)
        .exponentialBackoff(1000, 2, 5000)
        .retryOn(IOException.class)
        .build();
}

7.2 模型响应异常处理

创建全局异常处理器：

@ControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(AiServiceException.class)
    public ResponseEntity<ErrorResponse> handleAiException(AiServiceException ex) {
        ErrorResponse error = new ErrorResponse(
            "AI_SERVICE_ERROR",
            ex.getMessage(),
            ex.getErrorCode()
        );
        return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
            .body(error);
    }
}

八、最佳实践总结

1. 参数化配置：将所有模型参数通过配置文件管理
2. 优雅降级：实现熔断机制（如Resilience4j）
3. 请求缓存：对相同prompt的请求实现缓存
4. 安全控制：添加API密钥验证和请求速率限制
5. 日志追踪：为每个AI请求添加唯一ID便于追踪

通过以上实现，开发者可以快速构建基于Spring AI和DeepSeek的企业级AI应用，既保证了开发效率又兼顾了系统稳定性。实际项目中建议从简单功能开始，逐步增加复杂度，同时建立完善的监控体系确保服务质量。