java-openai

Appearance

OpenAI、Claude 与 DeepSeek 联网搜索 ​

java-openai 通过各平台的服务端工具调用 Web Search。搜索由平台执行，客户端负责发送请求、接收回答与来源引用。三个平台的原生入口如下：

平台便捷入口默认请求地址搜索工具
OpenAIOpenAiResponsesClient.webSearchhttps://api.openai.com/v1/responsesweb_search
Anthropic ClaudeClaudeClient.webSearchhttps://api.anthropic.com/v1/messagesweb_search_20250305
DeepSeekDeepSeekClient.webSearchhttps://api.deepseek.com/anthropic/v1/messagesweb_search_20250305

OpenAI 使用 Responses API；DeepSeek 使用 Anthropic 兼容的 Messages API。不要把搜索工具直接放进 DeepSeek 的 /v1/chat/completions 请求。UniChatClient.webSearch 可以自动完成协议选择和参数转换；需要完整的原生请求控制或流式事件时，使用表中的原生客户端。

本文对应包含本次 Web Search 改动的库版本。使用旧版 JAR 时，应先升级或构建当前源码。模型与搜索权限以实际账号、所选模型和接入地址支持的能力为准；普通对话可用并不表示代理服务支持服务端搜索。

配置与快速调用 ​

通过应用配置或本地 secrets.txt 配置密钥，启动时调用 EnvUtils.load()。配置默认地址时不要重复追加操作路径。

properties
OPENAI_API_KEY=your-openai-key
OPENAI_API_URL=https://api.openai.com/v1
CLAUDE_API_KEY=your-anthropic-key
CLAUDE_API_URL=https://api.anthropic.com/v1
DEEPSEEK_API_KEY=your-deepseek-key
DEEPSEEK_SEARCH_BASE_URL=https://api.deepseek.com/anthropic/v1

DEEPSEEK_SEARCH_BASE_URL 是独立的搜索地址配置，不读取普通对话的 DEEPSEEK_BASE_URL。下面的程序依次调用三个平台；只接入一个平台时，保留对应调用即可。

java
import nexus.io.claude.AnthropicModels;
import nexus.io.claude.ClaudeChatResponse;
import nexus.io.claude.ClaudeClient;
import nexus.io.deepseek.DeepSeekClient;
import nexus.io.deepseek.DeepSeekModels;
import nexus.io.openai.consts.OpenAiModels;
import nexus.io.openai.responses.OpenAiResponsesClient;
import nexus.io.openai.responses.OpenAiResponsesResponse;
import nexus.io.tio.utils.environment.EnvUtils;

public class WebSearchQuickStart {
  public static void main(String[] args) {
    EnvUtils.load();
    String query = "查询 Java 最新正式版本，并给出官方来源链接";

    OpenAiResponsesResponse openai = OpenAiResponsesClient.webSearch(OpenAiModels.GPT_5_4, query);
    System.out.println(openai.getOutputText());

    ClaudeChatResponse claude = ClaudeClient.webSearch(AnthropicModels.CLAUDE_SONNET_4_6, query);
    System.out.println(claude.getOutputText());

    ClaudeChatResponse deepseek = DeepSeekClient.webSearch(DeepSeekModels.deepseek_v4_flash, query);
    System.out.println(deepseek.getOutputText());
  }
}

三个入口都提供以下重载：

text
webSearch(model, query)
webSearch(apiKey, model, query)
webSearch(apiPrefixUrl, apiKey, model, query)

apiPrefixUrl 包含版本路径，不包含 /responses 或 /messages。DeepSeek 官方地址应传 https://api.deepseek.com/anthropic/v1。

UniChatClient：统一搜索入口 ​

下面显式指定 DeepSeek 平台和模型，由客户端选择对应的搜索协议并读取 DEEPSEEK_API_KEY。两参数重载 webSearch(model, query) 则根据模型名推断平台，并非默认使用 DeepSeek：

java
import nexus.io.chat.UniChatClient;
import nexus.io.chat.UniChatResponse;
import nexus.io.consts.ModelPlatformName;
import nexus.io.deepseek.DeepSeekModels;
import nexus.io.tio.utils.environment.EnvUtils;

public class UnifiedWebSearchExample {
  public static void main(String[] args) {
    EnvUtils.load();
    UniChatResponse response = UniChatClient.webSearch(
        ModelPlatformName.DEEPSEEK,
        DeepSeekModels.deepseek_v4_flash,
        "查询 Java 最新正式版本，提供官方来源");
    System.out.println(response.getMessage().getContent());
    System.out.println(response.getCitations());
    response.getSearchSources().forEach(source ->
        System.out.println(source.getTitle() + " " + source.getUrl()));
    System.out.println("停止原因：" + response.getFinishReason());
    System.out.println("搜索错误：" + response.getSearchErrors());
  }
}

支持的调用形式：

text
UniChatClient.webSearch(model, query)
UniChatClient.webSearch(platform, model, query)
UniChatClient.webSearch(request)
UniChatClient.webSearch(apiKey, request)
UniChatClient.webSearch(httpClient, request)
UniChatClient.webSearch(httpClient, apiKey, request)

平台与模型选择 ​

输入行为
显式设置 platform优先按该平台选择协议、地址及密钥；支持 openai、openai_responses、anthropic、deepseek，以及已有的两个 Anthropic ExchangeToken 渠道
平台为空或为 auto从 gpt-* / o1、o3、o4 系列、claude-*、deepseek-* 模型名推断；也识别 openai/、anthropic/、deepseek/ 前缀
已指定平台但未指定模型OpenAI 默认 gpt-5.4，Claude 默认 claude-sonnet-4-6，DeepSeek 默认 deepseek-v4-flash
平台和模型均为空默认选择 OpenAI 和 gpt-5.4，仍须配置 OpenAI 密钥
显式设置模型保留模型标识；原生请求会去掉与平台匹配的提供商前缀，不会偷偷替换成默认模型
无法识别的模型别名要求显式设置平台；显式平台下允许服务端自定义模型别名
已知模型系列与显式平台冲突发送前抛出 IllegalArgumentException

自动推断识别模型所属平台，不代表实时探测每个模型是否有搜索权限。接入服务仍需支持所选模型和对应的服务端工具。

统一参数与配置优先级 ​

java
import java.util.Collections;
import nexus.io.chat.UniChatClient;
import nexus.io.chat.UniChatRequest;
import nexus.io.chat.UniChatResponse;
import nexus.io.chat.UniWebSearchOptions;
import nexus.io.consts.ModelPlatformName;
import nexus.io.search.WebSearchUserLocation;
import nexus.io.tio.utils.environment.EnvUtils;

public class UnifiedWebSearchOptionsExample {
  public static void main(String[] args) {
    EnvUtils.load();
    UniChatRequest request = new UniChatRequest()
        .setPlatform(ModelPlatformName.DEEPSEEK)
        .setSystemPrompt("使用中文回答，优先引用官方资料")
        .setUserPrompts("查询最新 JDK 发布信息")
        .setMax_tokens(4096)
        .setWebSearchOptions(new UniWebSearchOptions()
            .setMaxToolCalls(3)
            .setAllowedDomains(Collections.singletonList("openjdk.org"))
            .setUserLocation(new WebSearchUserLocation().setCountry("CN")));
    UniChatResponse response = UniChatClient.webSearch(request);
    System.out.println(response.getMessage().getContent());
  }
}
统一参数OpenAIClaude / DeepSeek
max_tokensmax_output_tokens，未设置时使用服务端默认max_tokens，未设置时为 4096
temperature按现有模型兼容规则移除已知不支持该参数的模型的温度字段同样应用模型兼容规则
maxToolCallsmax_tool_calls，限制本轮内置工具调用总数，包括搜索工具的相关操作max_uses，限制搜索次数；默认均为 5
allowedDomains / blockedDomains放入工具的 filters直接放入工具对象；统一入口要求二选一
userLocationuser_locationuser_location
searchContextSizesearch_context_size，支持 low / medium / high显式设置时抛出参数错误，避免静默丢失配置
externalWebAccessexternal_web_access显式设置时抛出参数错误

请求的 systemPrompt、文本/图片消息历史和 model 角色别名会转换为对应协议。Messages 会把系统指令放在顶层 system 中，并增加使用搜索工具的指令。转换不会修改调用方的模型、温度、消息列表或角色。统一入口仅配置搜索工具，传入自定义 tools 或函数工具历史时会明确报错；这类组合请求使用原生客户端。

密钥优先级是方法参数 → request.apiKey → 对应平台配置；地址优先使用 request.apiPrefixUrl，否则读取平台配置。OpenAI 的 openai 平台读取 OPENAI_API_URL / OPENAI_API_KEY；openai_responses 优先读取 OPENAI_RESPONSES_API_URL / OPENAI_RESPONSES_API_KEY，为空时回落到前者。

DeepSeek 使用 DEEPSEEK_SEARCH_BASE_URL，不会误用普通对话的 DEEPSEEK_API_URL。显式传入官方 https://api.deepseek.com 或 https://api.deepseek.com/v1 时，会转换为 /anthropic/v1；自定义代理的路径保持原样，须提供支持 Messages 协议的前缀。Claude 读取 CLAUDE_API_URL / CLAUDE_API_KEY；显式选择 Anthropic ExchangeToken 渠道时沿用该渠道的地址和密钥配置，搜索能力由渠道决定。

兼容 generate 和统一结果 ​

已有业务可以继续使用 generate，通过标记启用搜索：

java
import nexus.io.chat.UniChatClient;
import nexus.io.chat.UniChatRequest;
import nexus.io.chat.UniChatResponse;
import nexus.io.openai.consts.OpenAiModels;
import nexus.io.tio.utils.environment.EnvUtils;

public class GenerateWithSearchExample {
  public static void main(String[] args) {
    EnvUtils.load();
    UniChatRequest request = new UniChatRequest()
        .setModel(OpenAiModels.GPT_5_4)
        .setUserPrompts("最近发布的 JDK 有哪些变化？")
        .setEnable_search(true);
    UniChatResponse response = UniChatClient.generate(request);
    System.out.println(response.getMessage().getContent());
  }
}

对于上述支持的平台，enable_search=true 会让同步 generate 进入统一搜索路径；未设置或设为 false 时保持原有生成行为。其他平台原有的搜索行为不在本次路由范围内。直接调用 webSearch 本身即表示启用搜索，不需要再设置该标记。

统一结果字段：

  • message.content：按返回顺序合并所有回答文本块。
  • citations：回答实际引用的 URL，按首次出现顺序去重。
  • searchSources：搜索结果和回答引用的来源集合，包含 URL 与标题，同一 URL 合并为一条；可能比 citations 更多。
  • searchErrors：嵌入响应的搜索错误代码，无错误时为空列表。
  • finishReason：保留 OpenAI 的 status 或 Messages 的 stop_reason，例如 completed、end_turn、pause_turn。
  • webSearchRequests：Claude/DeepSeek 返回的搜索计数；未返回时为 null。
  • rawData：完整原始响应，保留多轮续接需要的内容和加密字段。

HTTP 200 中没有正文但携带搜索错误或 pause_turn 时，也返回这些字段，不把它误报成 JSON 解析失败。续接使用原生客户端和完整 assistant 内容，见下文。统一搜索不会自动重试、继续暂停的请求或修改调用方的 OkHttpClient。

使用自定义 OkHttpClient 的重载抛出 IOException；HTTP 失败保留状态码，错误消息不包含服务端原始正文。使用默认客户端的重载将这类失败包装为 RuntimeException，可从 cause 读取原因。参数错误抛出 IllegalArgumentException。

统一搜索当前为同步接口；UniChatClient.stream 遇到上述平台的 enable_search=true 会明确报错，避免悄悄发送普通聊天请求。流式搜索使用本文后面的原生 EventSourceListener 重载。

OpenAI：配置搜索范围与实时访问 ​

webSearchRequest(model, query) 返回可编辑的 OpenAiResponsesRequest。默认启用一个 web_search 工具，设置 tool_choice: "required"，并通过 include: ["web_search_call.action.sources"] 请求返回来源列表。如果希望让模型自行决定是否搜索，将 tool_choice 改为 "auto"。

java
import java.util.Collections;
import nexus.io.openai.consts.OpenAiModels;
import nexus.io.openai.responses.OpenAiResponsesClient;
import nexus.io.openai.responses.OpenAiResponsesRequest;
import nexus.io.openai.responses.OpenAiResponsesResponse;
import nexus.io.openai.responses.OpenAiWebSearchTool;
import nexus.io.search.WebSearchUserLocation;
import nexus.io.tio.utils.environment.EnvUtils;

public class OpenAiWebSearchOptionsExample {
  public static void main(String[] args) {
    EnvUtils.load();
    OpenAiWebSearchTool tool = new OpenAiWebSearchTool()
        .setSearch_context_size("high")
        .setExternal_web_access(true)
        .setFilters(new OpenAiWebSearchTool.Filters()
            .setAllowed_domains(Collections.singletonList("openjdk.org")))
        .setUser_location(new WebSearchUserLocation().setCountry("CN").setCity("Shanghai"));

    OpenAiResponsesRequest request = OpenAiResponsesClient
        .webSearchRequest(OpenAiModels.GPT_5_4, "查询最新 JDK 发布信息")
        .setTools(Collections.singletonList(tool));
    OpenAiResponsesResponse response = OpenAiResponsesClient.responses(request);
    System.out.println(response.getOutputText());
  }
}

search_context_size 可设为 low、medium、high；external_web_access: false 表示仅使用缓存/索引内容，true 允许访问实时网络。域名过滤放在工具的 filters 内，可设置 allowed_domains 或 blocked_domains，域名不带协议头。不要把实时模式理解为必须启动本地浏览器。

返回的 output 同时包含搜索调用和回答消息，不能假定 output[0] 就是正文：

  • getOutputText()：合并回答中的 output_text。
  • output[i].getAction().getSources()：搜索调用的来源列表，需要先判断 action 是否存在。
  • output[i].getContent()[j].getAnnotations()：该文本块的引用，包含 url、title、start_index、end_index。索引针对当前文本块，合并正文后需要自行调整位置。
  • getStatus()、getRawResponse()：检查完成状态及原始错误/不完整响应。HTTP 200 不保证生成已经完整结束。

Claude / DeepSeek：配置搜索工具 ​

两者复用 OpenAiChatRequest 作为已有请求容器，并使用 ClaudeWebSearchTool 描述 Messages 服务端搜索工具。这里的请求类名称不代表请求会发往 OpenAI。

java
import java.util.Collections;
import nexus.io.claude.ClaudeChatResponse;
import nexus.io.claude.ClaudeClient;
import nexus.io.claude.ClaudeWebSearchTool;
import nexus.io.deepseek.DeepSeekClient;
import nexus.io.deepseek.DeepSeekModels;
import nexus.io.openai.chat.OpenAiChatRequest;
import nexus.io.search.WebSearchUserLocation;
import nexus.io.tio.utils.environment.EnvUtils;

public class MessagesWebSearchOptionsExample {
  public static void main(String[] args) {
    EnvUtils.load();
    ClaudeWebSearchTool tool = new ClaudeWebSearchTool()
        .setMax_uses(3)
        .setAllowed_domains(Collections.singletonList("openjdk.org"))
        .setUser_location(new WebSearchUserLocation().setCountry("CN"));
    OpenAiChatRequest request = ClaudeClient
        .webSearchRequest(DeepSeekModels.deepseek_v4_flash, "查询最新 JDK 发布信息")
        .setTools(Collections.singletonList(tool))
        .setMax_tokens(4096);
    ClaudeChatResponse response = DeepSeekClient.messages(request);
    System.out.println(response.getOutputText());
  }
}

调用 Claude 时，把模型替换为支持搜索的 Claude 模型，再使用 ClaudeClient.chatCompletions(request)。DeepSeek 的 messages 同样提供 (apiKey, request) 和 (apiPrefixUrl, apiKey, request) 重载。

ClaudeClient.webSearchRequest 默认设置 max_tokens: 4096、max_uses: 5，并在用户消息中明确要求联网搜索；实际是否调用搜索及调用次数由模型和服务端决定。要确认已经联网，应检查返回的 server_tool_use / web_search_tool_result，不能仅凭回答内容判断。

allowed_domains 与 blocked_domains 直接位于工具对象上，二者不要同时设置。Anthropic 支持的过滤与位置参数是否被 DeepSeek 或第三方兼容地址实现，需要以该服务的响应为准。库默认使用基础版 web_search_20250305，不自动开启新版工具的动态过滤或代码执行。

读取搜索结果、引用与错误 ​

Claude/DeepSeek 的回答可能交替出现 text、server_tool_use 和 web_search_tool_result。下面的处理方法适用于两者：

java
import nexus.io.claude.ClaudeChatResponse;
import nexus.io.claude.ClaudeMessageContent;
import nexus.io.claude.ClaudeWebSearchCitation;
import nexus.io.claude.ClaudeWebSearchError;
import nexus.io.claude.ClaudeWebSearchResult;

public class WebSearchResultsExample {
  public static void print(ClaudeChatResponse response) {
    System.out.println(response.getOutputText());
    if (response.getContent() == null) {
      return;
    }
    for (ClaudeMessageContent block : response.getContent()) {
      ClaudeWebSearchError error = block.webSearchError();
      if (error != null) {
        System.err.println("搜索失败：" + error.getError_code());
      }
      for (ClaudeWebSearchResult result : block.webSearchResults()) {
        System.out.println(result.getTitle() + " " + result.getUrl());
      }
      if (block.getCitations() != null) {
        for (ClaudeWebSearchCitation citation : block.getCitations()) {
          System.out.println(citation.getCited_text() + " -> " + citation.getUrl());
        }
      }
    }
  }
}

webSearchResults() 返回类型化结果列表；webSearchError() 返回嵌入的搜索错误。成功但没有匹配结果时列表为空且错误为 null；达到搜索次数上限时可能返回 max_uses_exceeded，即使外层 HTTP 状态为 200。原始联合类型保存在 block.getContent() 中：成功时是列表，失败时是错误对象。

搜索计数可从 response.getUsage().getServer_tool_use().get("web_search_requests") 读取，使用前判断 usage 和 server_tool_use 是否为 null。HTTP 4xx/5xx 则抛出 GenerateException，保留平台名称、状态码和响应正文。

向用户展示联网回答时，应同时展示可点击的来源引用。encrypted_content 和 encrypted_index 是供平台恢复上下文的不透明值，不是可直接阅读的网页正文。

处理 pause_turn 和继续对话 ​

当 stop_reason 为 pause_turn 时，本轮服务端搜索暂时停止。继续请求时，将完整的 assistant 内容追加到原消息历史，保持工具配置和服务地址一致。使用 rawResponse 中的内容可以保留模型额外返回的思考块、签名及将来新增的字段。

java
import java.util.ArrayList;
import java.util.List;
import com.alibaba.fastjson2.JSON;
import nexus.io.claude.ClaudeChatResponse;
import nexus.io.deepseek.DeepSeekClient;
import nexus.io.openai.chat.OpenAiChatMessage;
import nexus.io.openai.chat.OpenAiChatRequest;

public class ContinueSearchExample {
  public static ClaudeChatResponse continueOnce(OpenAiChatRequest request, ClaudeChatResponse response) {
    if (!"pause_turn".equals(response.getStop_reason())) {
      return response;
    }
    OpenAiChatMessage assistant = new OpenAiChatMessage();
    assistant.setRole("assistant");
    assistant.setContent(JSON.parseObject(response.getRawResponse()).getJSONArray("content"));
    List<OpenAiChatMessage> messages = new ArrayList<>(request.getMessages());
    messages.add(assistant);
    request.setMessages(messages);
    return DeepSeekClient.messages(request);
  }
}

上例适用于使用默认 DeepSeek 配置的原始请求；Claude 改用 ClaudeClient.chatCompletions(request)。原请求使用显式地址和密钥时，续接也必须使用相同重载。每次续接仍可能返回 pause_turn，应用应设置总时限和最大续接次数。本库不自动无限重试。

流式搜索 ​

使用 EventSourceListener 重载，客户端会设置 stream: true，原样交付服务端事件：

java
import nexus.io.claude.ClaudeClient;
import nexus.io.deepseek.DeepSeekClient;
import nexus.io.openai.chat.OpenAiChatRequest;
import nexus.io.openai.responses.OpenAiResponsesClient;
import nexus.io.openai.responses.OpenAiResponsesRequest;
import okhttp3.sse.EventSource;
import okhttp3.sse.EventSourceListener;

public class WebSearchStreamingExample {
  public static EventSource openai(String baseUrl, String key, String model, String query,
      EventSourceListener listener) {
    OpenAiResponsesRequest request = OpenAiResponsesClient.webSearchRequest(model, query);
    return OpenAiResponsesClient.responses(baseUrl, key, request, listener);
  }

  public static EventSource claude(String baseUrl, String key, String model, String query,
      EventSourceListener listener) {
    OpenAiChatRequest request = ClaudeClient.webSearchRequest(model, query);
    return ClaudeClient.chatCompletions(baseUrl, key, request, listener);
  }

  public static EventSource deepseek(String baseUrl, String key, String model, String query,
      EventSourceListener listener) {
    OpenAiChatRequest request = ClaudeClient.webSearchRequest(model, query);
    return DeepSeekClient.messages(baseUrl, key, request, listener);
  }
}

OpenAI 事件包含 response.web_search_call.*、文本增量和引用事件；Claude/DeepSeek 使用 Messages 内容块事件。调用方需要在监听器中处理完成、失败和取消，并按平台协议组装内容。这些原生事件不能直接交给只解析 Chat Completions choices[].delta 的监听器。停止接收时调用返回对象的 cancel()。

协议参考 ​