DeepSeek4j Spring Boot Starter 快速入门

简介

DeepSeek4j 是一个专为 Spring Boot 设计的 AI 能力集成启动器，可快速接入 DeepSeek 大模型服务。通过简洁的配置和易用的 API，开发者可轻松实现对话交互功能。

---

环境要求

• JDK 8+
• Spring Boot 2.7+
• Maven/Gradle

---

安装依赖

Maven

<dependency>
  <groupId>io.github.pig-mesh.ai</groupId>
  <artifactId>deepseek-spring-boot-starter</artifactId>
  <version>1.3.2</version>
</dependency>

---

基础配置

在 application.yml 中添加以下配置：

deepseek:
  api-key: your-api-key-here  # 必填，从 DeepSeek 控制台获取
  base-url: https://api.deepseek.com  # 可选，默认官方地址
  log-requests: true   # 记录请求日志
  log-responses: true  # 记录响应日志
  connect-timeout: 10  # 连接超时（秒）
  read-timeout: 30     # 读取超时（秒）
  call-timeout: 60     # 完整调用超时（秒）
  
  # 代理配置（可选）
  proxy:
    host: proxy.example.com
    port: 8080

  # 日志级别（可选：NONE/BASIC/HEADERS/BODY）
  log-level: BASIC

---

核心使用示例

1. 流式交互（推荐）

@Autowired
private DeepSeekClient deepSeekClient;

/**
 * 流式对话接口
 * @param prompt 用户输入
 * @return SSE 流式响应
 */
@GetMapping(value = "/chat", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<ChatCompletionResponse> streamChat(String prompt) {
    return deepSeekClient.chatFluxCompletion(prompt);
}

2. 进阶配置（多轮对话）

@GetMapping(value = "/chat/advanced", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<ChatCompletionResponse> advancedChat(String prompt) {
    ChatCompletionRequest request = ChatCompletionRequest.builder()
        .model(ChatCompletionModel.DEEPSEEK_REASONER)  // 指定推理模型
        .addUserMessage(prompt)                       // 用户当前问题
        .addAssistantMessage("上轮对话结果")            // 历史助手回复
        .addSystemMessage("你是一名AI助理")            // 系统角色设定
        .maxTokens(1000)                              // 最大生成 token 数
        .temperature(0.7)                             // 生成多样性控制
        .tools(yourFunctionTools)                     // Function Calling 工具
        .responseFormat(ChatResponseFormat.JSON)       // 结构化响应
        .build();
        
    return deepSeekClient.chatFluxCompletion(request);
}

3. 同步调用（不推荐）

@GetMapping("/sync/chat")
public ChatCompletionResponse syncChat(String prompt) {
    ChatCompletionRequest request = ChatCompletionRequest.builder()
        .model(deepSeekProperties.getModel())  // 从配置读取模型
        .addUserMessage(prompt)
        .build();
        
    return deepSeekClient.chatCompletion(request).execute();
}

---

注意事项

1. 流式优先原则
   推荐使用 chatFluxCompletion 实现流式响应，避免同步阻塞导致客户端超时。

2. 模型选择建议

   • DEEPSEEK_CHAT: 通用对话场景
   • DEEPSEEK_REASONER: 复杂推理场景
   • 通过 model() 方法动态指定

3. 安全合规

   • 敏感数据建议启用 encrypted-mobile 等加密字段
   • 遵守 GDPR 等数据保护法规

4. 性能调优

   • 根据业务调整 maxTokens（默认 2048）
   • 合理设置超时时间（特别是 R1 长文本模型）

5. 错误处理

   • 监听 onErrorResume 处理流式异常
   • 同步调用需捕获 IOException 和 APIException

---

附录

完整配置项说明

配置项	类型	必填	默认值	说明
api-key	String	是	-	平台颁发的 API 密钥
base-url	String	否	官方 API 地址	自定义服务端点
log-requests	Boolean	否	false	是否记录完整请求日志
connect-timeout	int	否	10	连接超时时间（秒）
proxy.host	String	否	-	代理服务器地址

---