Spring AI 结合DeepSeek使用教程：从入门到实践

一、技术背景与核心价值

在人工智能与Java生态深度融合的背景下，Spring AI框架为开发者提供了标准化的AI开发范式，而DeepSeek作为高性能大语言模型，其强大的文本生成与语义理解能力为智能应用注入核心动力。两者结合可实现低代码集成大模型能力、统一管理多模型服务、无缝对接企业级Java应用，尤其适用于智能客服、内容生成、数据分析等场景。

二、环境准备与依赖配置

1. 基础环境要求

• JDK 17+（Spring AI对Java版本有明确要求）
• Maven 3.8+ 或 Gradle 7.5+（依赖管理工具）
• Spring Boot 3.1+（与Spring AI版本兼容）
• DeepSeek模型服务（本地部署或API访问）

2. 关键依赖配置

在pom.xml中添加Spring AI核心模块：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-core</artifactId>
    <version>0.8.0</version>
</dependency>
<!-- 根据模型类型选择客户端 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama</artifactId> <!-- 本地模型 -->
    <version>0.8.0</version>
</dependency>
<!-- 或使用HTTP客户端连接远程服务 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-http</artifactId>
    <version>0.8.0</version>
</dependency>

3. 模型服务配置

本地部署方案（Ollama）

1. 安装Ollama并运行：

   curl https://ollama.ai/install.sh | sh
   ollama run deepseek-r1:7b

2. 配置Spring AI指向本地服务：

   @Bean
   public OllamaChatClient ollamaChatClient() {
    return new OllamaChatClient("http://localhost:11434");
   }

远程API方案

@Bean
public HttpChatClient httpChatClient() {
    return HttpChatClient.builder()
        .baseUrl("https://api.deepseek.com/v1")
        .apiKey("YOUR_API_KEY")
        .build();
}

三、核心功能实现

1. 基础文本生成

@Service
public class AiContentService {
    private final ChatClient chatClient;
    public AiContentService(ChatClient chatClient) {
        this.chatClient = chatClient;
    }
    public String generateText(String prompt) {
        ChatMessage input = ChatMessage.builder()
            .role(ChatRole.USER)
            .content(prompt)
            .build();
        ChatResponse response = chatClient.call(List.of(input));
        return response.getChoices().get(0).getMessage().getContent();
    }
}

2. 高级对话管理

@RestController
@RequestMapping("/api/chat")
public class ChatController {
    private final ChatClient chatClient;
    private final Memory memory = new InMemoryMemory(); // 对话记忆
    public ChatController(ChatClient chatClient) {
        this.chatClient = chatClient;
    }
    @PostMapping
    public ChatResponse chat(
            @RequestBody ChatRequest request,
            @RequestHeader(value = "session-id", required = false) String sessionId) {
        // 会话管理
        String context = memory.load(sessionId).orElse("");
        String fullPrompt = context + "\nUser: " + request.getMessage();
        ChatMessage input = ChatMessage.builder()
            .role(ChatRole.USER)
            .content(fullPrompt)
            .build();
        ChatResponse response = chatClient.call(List.of(input));
        // 更新记忆
        String aiResponse = response.getChoices().get(0).getMessage().getContent();
        memory.save(sessionId, fullPrompt + "\nAI: " + aiResponse);
        return response;
    }
}

四、进阶功能实现

1. 多模型路由

@Service
public class ModelRouterService {
    private final Map<String, ChatClient> modelClients;
    public ModelRouterService(List<ChatClient> clients) {
        this.modelClients = clients.stream()
            .collect(Collectors.toMap(
                client -> client.getClass().getSimpleName(),
                Function.identity()
            ));
    }
    public ChatResponse routeRequest(String modelName, List<ChatMessage> messages) {
        ChatClient client = modelClients.get(modelName + "ChatClient");
        if (client == null) {
            throw new IllegalArgumentException("Model not found");
        }
        return client.call(messages);
    }
}

2. 性能优化策略

1. 批处理请求：

   public List<ChatResponse> batchProcess(List<String> prompts) {
    return prompts.stream()
        .map(prompt -> {
            ChatMessage message = ChatMessage.builder()
                .role(ChatRole.USER)
                .content(prompt)
                .build();
            return chatClient.call(List.of(message));
        })
        .collect(Collectors.toList());
   }

2. 异步调用：

   @Async
   public CompletableFuture<ChatResponse> asyncGenerate(String prompt) {
    ChatMessage message = ChatMessage.builder()
        .role(ChatRole.USER)
        .content(prompt)
        .build();
    return CompletableFuture.completedFuture(chatClient.call(List.of(message)));
   }

五、最佳实践与注意事项

1. 错误处理机制

@RestControllerAdvice
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(503).body(error);
    }
}

2. 安全控制

• 实现API密钥验证
• 输入内容过滤（防止Prompt注入）
• 输出内容审核

3. 监控与日志

@Configuration
public class MonitoringConfig {
    @Bean
    public MicrometerChatClientInterceptor micrometerInterceptor(MeterRegistry registry) {
        return new MicrometerChatClientInterceptor(registry);
    }
}

六、完整示例项目结构

src/main/java/
├── config/          # 配置类
│   ├── AiConfig.java
│   └── ModelConfig.java
├── controller/      # 控制器
│   └── ChatController.java
├── service/         # 业务逻辑
│   ├── AiContentService.java
│   └── ModelRouterService.java
├── exception/       # 异常处理
│   └── GlobalExceptionHandler.java
└── Application.java # 主类

七、常见问题解决方案

1. 连接超时问题：

   • 检查网络配置
   • 增加重试机制：

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

2. 模型响应延迟：

   • 使用流式响应（Spring AI 0.8+支持）
   • 降低max_tokens参数

3. 内存溢出问题：

   • 限制对话历史长度
   • 使用外部存储（如Redis）保存会话

八、未来演进方向

1. 支持DeepSeek的函数调用（Function Calling）能力
2. 集成Spring AI的Agent框架实现复杂任务分解
3. 结合Spring Cloud Gateway实现AI服务网关

通过本教程，开发者可以快速掌握Spring AI与DeepSeek的集成方法，构建从简单问答到复杂对话系统的各类智能应用。实际开发中建议结合具体业务场景进行功能扩展和性能调优。