OpenAI、Claude 与 DeepSeek 联网搜索

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

平台	便捷入口	默认请求地址	搜索工具
OpenAI	`OpenAiResponsesClient.webSearch`	`https://api.openai.com/v1/responses`	`web_search`
Anthropic Claude	`ClaudeClient.webSearch`	`https://api.anthropic.com/v1/messages`	`web_search_20250305`
DeepSeek	`DeepSeekClient.webSearch`	`https://api.deepseek.com/anthropic/v1/messages`	`web_search_20250305`

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

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

配置与快速调用

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

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。下面的程序依次调用三个平台；只接入一个平台时，保留对应调用即可。

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());
  }
}

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

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：

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());
  }
}

支持的调用形式：

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`

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

统一参数与配置优先级

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());
  }
}

统一参数	OpenAI	Claude / DeepSeek
`max_tokens`	`max_output_tokens`，未设置时使用服务端默认	`max_tokens`，未设置时为 4096
`temperature`	按现有模型兼容规则移除已知不支持该参数的模型的温度字段	同样应用模型兼容规则
`maxToolCalls`	`max_tool_calls`，限制本轮内置工具调用总数，包括搜索工具的相关操作	`max_uses`，限制搜索次数；默认均为 5
`allowedDomains` / `blockedDomains`	放入工具的 `filters`	直接放入工具对象；统一入口要求二选一
`userLocation`	`user_location`	`user_location`
`searchContextSize`	`search_context_size`，支持 `low` / `medium` / `high`	显式设置时抛出参数错误，避免静默丢失配置
`externalWebAccess`	`external_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，通过标记启用搜索：

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"。

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。

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。下面的处理方法适用于两者：

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 中的内容可以保留模型额外返回的思考块、签名及将来新增的字段。

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，原样交付服务端事件：

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()。