详细的使用文档请访问:https://javaai.pig4cloud.com/deepseek
deepseek4j 是面向 DeepSeek 推出的 Java 开发 SDK,默认使用 DeepSeek Flash,也支持 DeepSeek V4 Pro。提供对话推理、函数调用、JSON结构化输出、以及基于 OpenAI 兼容 API 协议的嵌入向量生成能力。通过 Spring Boot Starter 模块,开发者可以快速为 Spring Boot 2.x/3.x 以及 Solon 等主流 Java Web 框架集成 AI 能力,提供开箱即用的配置体系、自动装配的客户端实例,以及便捷的流式响应支持。
1.6.1 已发布到 Maven Central,完整发布说明见 GitHub Release v1.6.1。
- 新增官方搜索与模型回答的组合调用
chatSearchCompletion(...),自动搜索、整理参考资料并流式生成回答。 - 组合调用复用客户端配置,保留历史消息和单次请求参数;取消订阅会停止当前 HTTP 请求。
- 保留
1.6.0的官方独立搜索接口和默认模型deepseek-flash,无需额外的搜索 API Key。
- 完整的 DeepSeek API 支持,支持返回思维链和会话账单
- 支持 DeepSeek 官方 Search 独立搜索,以及搜索后由模型生成回答的组合调用
- 支持自定义连接参数、代理配置、超时设置、请求响应日志
- Reactor 响应式支持,简化流式返回开发
运行环境要求 JDK 8 或更高版本。
Spring Boot 项目在 pom.xml 中添加以下依赖:
<dependency>
<groupId>io.github.pig-mesh.ai</groupId>
<artifactId>deepseek-spring-boot-starter</artifactId>
<version>1.6.1</version>
</dependency>不使用 Spring Boot 时,可直接依赖核心 SDK,并通过 DeepSeekClient.builder() 创建客户端:
<dependency>
<groupId>io.github.pig-mesh.ai</groupId>
<artifactId>deepseek4j-core</artifactId>
<version>1.6.1</version>
</dependency>在 application.yml 或 application.properties 中添加必要的配置:
deepseek:
api-key: your-api-key-here默认模型为 deepseek-flash(ChatCompletionModel.DEEPSEEK_FLASH),使用 DeepSeek 官方当前的 Flash 模型。如需 Pro,可设置 deepseek.model: deepseek-v4-pro,或调用客户端 builder 的 model("deepseek-v4-pro")。单次请求指定的模型优先于客户端配置。
默认开启思考模式,思考强度为 high。旧枚举 DEEPSEEK_V4_FLASH 保留并标记为弃用,仍发送原模型名 deepseek-v4-flash;新调用建议使用 DEEPSEEK_FLASH。
@Autowired
private DeepSeekClient deepSeekClient;
// sse 流式返回
@GetMapping(value = "/chat", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<ChatCompletionResponse> chat(String prompt) {
return deepSeekClient.chatFluxCompletion(prompt);
}双击运行根目录的 sse.html 文件,即可打开调试页面。在页面中输入后端 SSE 接口地址,点击发送后可实时查看推理过程和最终结果。页面提供了完整的前端实现代码,可作为集成参考。
通过 DeepSeekClient.search(...) 调用 DeepSeek 官方 Search API,获取结构化网页搜索结果。该接口使用现有 DeepSeek API Key,默认请求 https://api.deepseek.com/v1/tools/search,支持同步执行和异步回调。
baseUrl 只包含域名时(如 https://api.deepseek.com),Search 自动使用 /v1/tools/search。已配置路径时,在该路径下追加 tools/search,保留 /v1/ 和自定义网关前缀;此处理不改变聊天接口的请求路径。
import io.github.pigmesh.ai.deepseek.core.DeepSeekClient;
import io.github.pigmesh.ai.deepseek.core.search.DeepSeekSearchRequest;
import io.github.pigmesh.ai.deepseek.core.search.DeepSeekSearchResponse;
import io.github.pigmesh.ai.deepseek.core.search.DeepSeekSearchResult;
DeepSeekClient client = DeepSeekClient.builder()
.openAiApiKey("your-api-key-here")
.build();
try {
DeepSeekSearchRequest request = DeepSeekSearchRequest.builder()
.query("DeepSeek Search API site:api-docs.deepseek.com")
.count(5)
.oriQuestion("如何调用 DeepSeek 官方搜索接口?")
.localization("1.2.3.4")
.needContent(true)
.build();
DeepSeekSearchResponse response = client.search(request).execute();
for (DeepSeekSearchResult result : response.results()) {
System.out.println(result.title() + " " + result.url());
System.out.println(result.content());
}
} finally {
client.shutdown();
}Spring Boot 中可直接使用已注入的 DeepSeekClient,无需新增配置。五个入参均支持通过 builder 设置:
| Java 参数 | JSON 字段 | 说明 |
|---|---|---|
query |
query |
必填,1~128 个 Unicode 字符,不能全为空白;支持 site: 等查询语法 |
count |
count |
可选,1~50,服务端默认 10 |
oriQuestion |
ori_question |
可选,1~128 个字符;null 等同未提供 |
localization |
localization |
可选,用于优先返回本地结果的 IP 地址,服务端默认为空字符串 |
needContent |
need_content |
可选,服务端默认 false;为 false 时结果的 content 为空字符串 |
可选字段为 null 时不发送,显式设置的 false 会发送。查询原样透传,参数范围由服务端校验;错误沿用 OpenAiHttpException。无匹配结果时 results() 为空列表,结果中的 siteName()、siteIcon() 和 date() 可能为 null,其中日期保留为 UTC RFC 3339 字符串。
异步调用使用 client.search(request).onResponse(responseHandler, errorHandler),客户端应在回调完成后关闭。独立搜索入口为 client.search(request),直接使用现有 DeepSeek API Key 和基础地址,返回结构化搜索结果。
1.6.1 提供 chatSearchCompletion(...),在 SDK 内串联官方 Search 和流式聊天。Spring Boot 中直接使用注入的 DeepSeekClient,无需手动拼装搜索结果或新增搜索配置:
@GetMapping(value = "/chat/search", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<ChatCompletionResponse> chatSearch(String prompt) {
return deepSeekClient.chatSearchCompletion(prompt);
}简单调用默认搜索 5 条结果,设置 needContent(false),使用标题、来源 URL 和摘要作为参考资料。问题同时作为搜索 query,须为 1~128 个 Unicode 字符且不能全为空白。长问题使用独立的短查询,SDK 会保留发给模型的完整问题:
DeepSeekSearchRequest search = DeepSeekSearchRequest.builder()
.query("DeepSeek Search API site:api-docs.deepseek.com")
.count(5)
.needContent(true)
.build();
Flux<ChatCompletionResponse> answer = deepSeekClient.chatSearchCompletion(
"请结合官方文档,说明搜索接口如何与多轮对话、流式输出和错误处理配合使用。", search);需要保留历史消息或覆盖模型参数时,传入完整对话请求:
ChatCompletionRequest chat = ChatCompletionRequest.builder()
.model("deepseek-v4-pro")
.thinkingDisabled()
.addSystemMessage("请用中文回答,并标明引用来源。")
.addUserMessage("我正在接入 DeepSeek。")
.addAssistantMessage("你需要了解哪部分?")
.addUserMessage("如何接入官方搜索?")
.build();
Flux<ChatCompletionResponse> answer = deepSeekClient.chatSearchCompletion(chat, search);- 搜索和聊天复用同一个客户端的 API Key、基础地址、代理、超时与自定义 headers。模型和思考参数以单次请求为准,未设置时继承客户端配置;请求没有 system 消息时补充客户端
systemMessage。 - 历史消息和原问题保持不变。SDK 在最后一条 user 消息之前插入一条参考资料消息,将网页内容标记为外部资料,并提示模型标注来源 URL。
needContent(true)时优先使用正文,没有正文时回退到摘要,再回退到 snippet;默认使用摘要。每条资料最多保留 3,000 个正文字符,全部参考资料不超过 20,000 个 UTF-16 代码单元,避免大网页无限增加上下文。- 返回的是冷
Flux:订阅后才发起搜索,每次订阅独立执行。搜索成功后开始模型流式请求;取消订阅会取消当前搜索或聊天请求。 - 搜索无结果时使用原问题继续聊天。搜索 HTTP、网络或解析错误通过
onError返回,不会静默调用模型;模型错误同样向调用方传递。
1.6.0 包含搜索相关的破坏性 API 变更:
- 将 starter 或 core 依赖版本统一更新为
1.6.1。 - 删除 Bocha 专用的
deepseek.search-api-key配置,以及客户端 builder 的searchApi(...)、searchApiKey(...)、searchEndpoint(...)调用。官方 Search 复用 DeepSeek API Key 和基础地址。 - 需要搜索后生成回答时,使用
1.6.1的chatSearchCompletion(...),返回Flux<ChatCompletionResponse>;旧chatSearchStreamingCompletion(...)调用也迁移到该方法。仅需结构化搜索结果时,使用client.search(DeepSeekSearchRequest)。 - 将旧的
SearchRequest、SearchResponse替换为DeepSeekSearchRequest、DeepSeekSearchResponse,并按上文官方 Search 的参数和结果结构调整代码。Bocha 专用的SearchApi和FreshnessEnums已移除。
本项目基于 Apache License 2.0 许可证开源。
项目设计灵感来源于 OpenAI4J 项目,由于其不再维护,在其优秀架构设计的基础上:
- 扩展了 DeepSeek 特有功能
- 增强了 Reactor 响应式支持
- 提供了更完整的 Spring Boot 集成
