用 Java 接入大模型(四):把调用封装成可复用的客户端

简介: 本文是Java接入大模型系列第四篇,聚焦将零散调用封装为健壮客户端。核心不在于“如何发送请求”,而在于系统性应对各类失败:分层超时(连接/首字/块间隔/总时长)、精准重试(区分可重试与不可重试错误)、异常分类(统一LlmException)、流中断识别、连接复用及配置外置。真正区分“能跑”与“能用”的,正是对出错场景的周全设计。

一、能跑的代码和能用的代码,差在哪

先把前几篇的代码摆出来看。它没写错的任何一件事:

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        // 鉴权头此处略去,见第六节:凭证从配置注入,不写死在代码里
        .POST(HttpRequest.BodyPublishers.ofString(body))
        .build();

逻辑是对的,路径也是通的。它的问题在别处:没有一个地方回答了"如果出错了怎么办"。

顺着问下去,会碰到一串它没回答的问题:

  • 网络连不上,要等多久才放弃?是一直卡着吗?
  • 上游排队慢,首字两分钟不回来,能撑多久?
  • 生成到一半流断了,业务该做什么?
  • 报 429 了,直接失败还是重试?重试几次?
  • 上次超时的请求,其实上游可能已经处理了,再发一次会不会重复扣费?
  • HTTP 200 但响应体里带了个 error,这种情况算什么错?

这些问题的答案,才是"封装"这件事的真正内容。把 HTTP 请求发出去,只是顺带做的一步。

所以下面的顺序是按"出错时会发生什么"来排的,而不是按代码结构排。


二、超时:一个值远远不够

最常见的写法是设一个总超时,比如 30 秒。对大模型调用来说,这一个值几乎一定是不合适的。

原因在于,一次大模型请求里有四个性质完全不同的时间段:

  • 连接建立:TCP 握手加 TLS。正常就几百毫秒。它慢或者超时,说明是网络或 DNS 的问题,跟模型无关。
  • 首字时间(TTFB):请求发出到收到第一个数据块。正常几百毫秒到两三秒。它超了,说明上游在排队、限流或者过载。
  • 块间隔:相邻两个数据块之间的间隔。正常几十毫秒。它超了,说明流卡住了——这是唯一真正表示"这个连接已经废了"的信号。
  • 总时长:从发出到全部收完。它由回答长度决定,波动极大。

前三个指标都相对稳定,可以用固定阈值判断。只有第四个不一样:同一个接口,短问题可能 1 秒答完,让它写一篇三千字的方案可能要 90 秒。你想用一个值同时管住这四种情况,就必然要在某一边妥协。

妥协的后果很具体:

  • 按总时长设成 60 秒去保证长回答能写完 → 网络断开时,你要等 60 秒才等到失败,而且这段时间连接和线程都占着。
  • 按总时长设成 5 秒去快速失败 → 所有长回答都被你自己掐断,业务直接不可用。

分开设,就有意义了

四个值分开设之后,每个阈值只承担一件事,判断起来就清楚了:

  • 连接超时 5 秒:超过就是网络问题,立刻失败,不要重试太多次(网络断了重试也是白等)。
  • 首字超时 15 秒:超过就是上游排队或过载,可以重试,也可以降级到备用模型。
  • 块间隔超时 20 秒:超过就是流卡死,立刻断开并按"中断"处理。这个值给得宽一点没关系,因为正常的间隔只有几十毫秒,20 秒已经是很宽松的判断。
  • 总时长:给一个很大的兜底值(比如 300 秒),只用来防止极端情况下的资源泄漏,不作为常规判断依据。

有没有发现,这样一拆,每个数字都变得好解释了。以前那个"30 秒"你答不出为什么是 30,现在每个值背后都有一个具体的失败模式。

JDK HttpClient 上怎么落

这里要说清楚一个容易踩的地方:JDK 自带的 HttpClient,connectTimeout 管的是连接建立,这个直接能用:

HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(5))
        .build();

但 HttpRequest.timeout() 管的是整个请求的完成时间。对流式调用来说,这就是"总时长"——你一旦设了它,长回答会被硬掐断。所以流式场景下通常不设它,或者只设一个很大的兜底值。

那首字和块间隔怎么管?JDK HttpClient 没有直接提供按块计时的钩子,需要自己加一层。可行的做法是在读流的循环里记时间戳,配合一个定时任务在超时后打断读取:

long lastDataAt = System.currentTimeMillis();

// 巡检任务:发现间隔超限就取消当前请求
ScheduledExecutorService watchdog = Executors.newSingleThreadScheduledExecutor();
ScheduledFuture<?> guard = watchdog.scheduleAtFixedRate(() -> {
   
    long gap = System.currentTimeMillis() - lastDataAt;
    if (gap > GAP_TIMEOUT_MS) {
   
        currentFuture.cancel(true);   // 打断读取
    }
}, 1, 1, TimeUnit.SECONDS);

lastDataAt 在每收到一个数据块时更新,首字阶段从请求发出时刻起算。这个写法不优雅但有效,实际项目里够用。

如果你用的是 OkHttp 或 Apache HttpClient,它们提供了更细粒度的读超时配置,可以把上面这层自己省掉。选型时值得把这个当作一个考虑因素——流式场景对超时粒度是有要求的,客户端库支持得越细,你要自己写的东西越少。


三、重试:先问能不能重试,再问重试几次

"失败了重试三次"是很多人的默认写法。但在大模型调用里,这个默认动作可能让成本直接翻几倍。

先分类:什么错值得重试

可以重试:

  • 网络层的瞬时异常,连接被重置、DNS 临时失败。这类错误重试一次往往就好了。
  • 429(限流)。这明确表示"现在不行,待会儿来",重试是对的,但必须配合退避,立刻重试只会继续被拒。
  • 5xx(服务端错误)。上游临时故障,可以重试。
  • 首字超时。请求可能根本没被上游受理,重试是安全的。

不要重试:

  • 400 系列里的参数错误。你的请求格式写错了,重试一万次还是同样的错误,只是浪费时间。
  • 401 / 403。凭证无效或没权限,重试没有任何意义。这类错误要立刻暴露出来,别被重试掩盖了——这是最烦的一种情况:因为重试逻辑存在,上线后你只看到"重试三次都失败了",看不到真正的原因。
  • 内容被安全策略拦截。重试同一个输入,结果一样。

绝对不能重试:

流式请求已经开始推送给用户的。 这时候内容已经吐出去半句了,重试会让用户看到重复或互相矛盾的两段内容。这种情况只能按"中断"处理,要么提示用户可以重试,要么从断点续写。

退避必须带抖动

定个"等 1 秒再重试"看起来合理,但如果同时有 200 个请求都失败了,它们会在同一秒一起回来,把上游再冲一次。这就是重试风暴。

所以退避要加随机抖动:

long base = 500L * (1L << attempt);          // 500ms, 1s, 2s, 4s
long jitter = ThreadLocalRandom.current().nextLong(base / 2);
long delay = base + jitter;                   // 抖动打散重试时刻
Thread.sleep(delay);

指数退避负责给上游留出恢复时间,抖动负责避免大家同时回来。两个缺一不可。

重试会放大成本,这一条要算清楚

如果一次重试 3 遍,最坏情况下你的 token 消耗是请求数的 4 倍(原始 1 次 + 重试 3 次)。而且是那种"用户看不到任何好处"的消耗——重试的是失败请求,产出的内容用户根本没拿到。

所以几个克制的原则:

  • 重试次数别超过 2 次。第 3 次基本可以确定不是瞬时问题了。
  • 只有幂等的调用才自动重试。如果你的调用会写库、会扣费、会触发下游动作,自动重试可能造成重复写入,这时候要么不自动重试,要么先做幂等设计。
  • 流式请求的重试要格外保守。前面说了,已经输出的内容没法撤回。

四、异常分类:把"错误"拆成能被处理的东西

封装的另一个核心价值,是把底层五花八门的失败,收敛成上层能写 catch 的几种类型。

为什么要收敛?因为上层的处理逻辑其实只有几种:重试、降级、提示用户、告警。如果底层往上抛的是"IOException"这种笼统的东西,上层就没法判断该做哪一种,只能一律当"未知错误"返回给用户。用户体验就是"系统繁忙"——什么信息都没有。

一个够用的分类是这样的:

public class LlmException extends RuntimeException {
   
    private final Kind kind;

    public enum Kind {
   
        NETWORK,        // 网络问题 —— 可重试
        TIMEOUT_TTFB,   // 首字超时 —— 可重试
        TIMEOUT_GAP,    // 流卡死 —— 不可重试,按中断处理
        RATE_LIMITED,   // 限流 —— 退避后重试
        AUTH,           // 鉴权失败 —— 立刻告警,别重试
        BAD_REQUEST,    // 参数错误 —— 开发问题,直接暴露
        CONTENT_FILTER, // 内容被拦 —— 提示用户换说法
        TRUNCATED,      // 输出被截断 —— 结果不完整
        UPSTREAM        // 上游服务错误 —— 可重试
    }
}

有了这个分类,上层的逻辑就能写得很直白了:

try {
   
    return client.chat(prompt);
} catch (LlmException e) {
   
    if (shouldRetry(e.getKind())) {
    /* 退避重试 */ }
    else if (e.getKind() == Kind.CONTENT_FILTER) {
    /* 提示用户 */ }
    else {
    /* 告警 + 降级 */ }
}

一个专门的坑:HTTP 200 里藏着的错误

很多模型接口在参数错误或鉴权失败时,不返回 4xx,而是返回 200,然后在响应体里给一个 error 对象:

{
   
  "error": {
   
    "code": "AuthenticationError",
    "message": "Authentication failed. Please check your configuration."
  }
}

流式接口更容易这样,因为 SSE 连接一旦建立就是 200,错误只能塞在数据块里。

所以客户端的判断顺序应该是:先看 HTTP 状态码,再解析响应体,检查里面有没有 error 字段。只看状态码就以为成功了,是这里最常见的一个疏漏——尤其流式场景下,你会拿到一个 200,然后一堆解析不出内容的空数据,排查半天才发现是鉴权配置有问题。

TRUNCATED 这个类型也值得单独说。它不是"错误",而是一种需要把握的状态:finish_reason 是 length,说明回答被 max_tokens 截断了。如果你的业务会把结果存下来,这个状态必须在落库前判断——否则数据库里会积累一堆半截的记录,而且事后极难从内容上分辨哪条是完整的。


五、HttpClient 不要每次 new

这一条简单但影响不小。HttpClient.newHttpClient() 每次调用都会新建一个连接池和一个线程池。如果你每个请求都 new 一个,结果是:

  • 每次请求都重新做 TCP 握手和 TLS 协商,延迟白白多出几百毫秒;
  • 高并发下线程数失控,每个客户端还各自持有几个线程,几百个请求就能把内存吃光。

正确做法是整个应用共用一个实例:

public final class LlmHttpClientHolder {
   
    private static final HttpClient INSTANCE = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(5))
            .executor(Executors.newFixedThreadPool(16))   // 显式给线程池,别用默认的
            .build();

    public static HttpClient get() {
    return INSTANCE; }
}

顺带一个细节:JDK HttpClient 默认的 executor 用的是 CachedThreadPool,在流式场景下会创建大量线程。显式指定一个固定大小的线程池,在高并发时更可控。池大小按你的并发量估,不需要很大——因为流式请求大部分时间在等 IO,不是在占 CPU。

HttpClient 本身是线程安全的,可以放心共享。


六、配置外置:凭证不要放在代码里

前几篇的示例里,凭证是直接写死在常量里的。那只是为了方便阅读,真实项目里不能这样:

  • 代码提交到仓库,凭证就跟着进了版本历史,删都删不干净;
  • 换环境(测试/预发/生产)要改代码重新打包;
  • 多个模型(主用、备用)的地址和凭证散落在各处,改一处漏一处。

至少要抽出一份配置:

llm:
  primary:
    base-url: https://dashscope.aliyuncs.com/compatible-mode/v1
    model: qwen3.8-max
    # 凭证不写在这里:从环境变量或配置中心注入
  timeouts:
    connect: 5s
    ttfb: 15s
    gap: 20s
    total: 300s
  retry:
    max-attempts: 2
    base-delay: 500ms

凭证通过环境变量或配置中心注入,不落仓库。超时和重试参数外置之后,调优不用重新发版——这一点在线上出问题时会救命,因为你往往需要临时把某个超时调大来观察现象。


七、最终形态

把上面的东西合起来,客户端对外应该只暴露很窄的一组方法:

public interface LlmClient {
   
    /** 非流式:拿完整结果 */
    String chat(String prompt, LlmOptions options);

    /** 流式:逐块回调,返回完整结果供落库 */
    String chatStream(String prompt, LlmOptions options, Consumer<String> onChunk);
}

内部实现要负责的事,按重要性排:

  • 超时分层:连接、首字、块间隔、总时长四道,各自独立判断;
  • 异常分类:把底层失败翻译成上层能处理的 Kind;
  • 重试策略:只对可重试类型生效,指数退避带抖动,默认最多 2 次;
  • 中断处理:流断了要能识别出"这是半截内容",不落库、不重试;
  • 连接复用:单例 HttpClient,固定大小线程池;
  • 配置注入:凭证、地址、超时、重试全部外置。

注意这里没有一件事是"怎么把请求发出去"。那是整个封装里最简单的一步。


八、小结

回到开头那个问题:能跑的代码和能用的代码差在哪?

差在它有没有回答"出错时怎么办"。前几篇的代码在顺利路径上和现在这份是等价的,功能一样、结果一样。区别只在出问题的那一刻:一个给你一句 IOException,另一个告诉你"这是首字超时,可以重试,已经重试过 2 次,建议降级"。

而大模型调用恰恰是一个失败率不低的场景——上游排队、限流、偶发超时都是常态。所以这层封装不是"架构洁癖",它直接决定了线上出问题时,你是能快速定位,还是只能对着"系统繁忙"发呆。


下一篇

客户端有了,下一个问题是它要装什么。多轮对话是最典型的使用场景,也是最容易做错的一个:上下文怎么传、传多少、超长了丢哪部分、会话状态存在哪。这些问题处理不好,会出现"模型答着答着忘了前面说过什么"这种让人抓狂的现象,而且原因往往不在模型身上。


本文是「用 Java 接入大模型」系列第四篇。前三篇分别讲了把流式输出跑通、流式与非流式怎么选、关键参数怎么调,建议按顺序看。文中超时与重试取值基于通义千问的 OpenAI 兼容接口实践,具体以你使用的模型文档为准。

目录
相关文章
|
2月前
|
机器学习/深度学习 JSON 前端开发
用 Java 接入大模型(一):把流式输出跑通
本文是「用 Java 接入大模型」系列首篇,聚焦最易卡壳的流式输出:详解 SSE 协议原理、手写 60 行无依赖流式客户端(兼容通义千问/OpenAI),并揭示新手必踩的三大坑——不按行解析、漏传 `stream:true`、忽略空 content。代码即学即用,拒绝玄学,只讲真实可跑的 Java 实现。
274 1
|
2月前
|
存储 NoSQL 安全
用 Java 接入大模型(五):多轮对话的上下文怎么管
本文深入剖析多轮对话的核心误区:大模型本身无记忆,所谓“遗忘”实为上下文管理失当。从messages结构化封装、token精准截断策略,到Redis会话存储与三步排错法,系统讲解如何可靠构建长程对话能力。
261 7
|
2月前
|
存储 JSON 自然语言处理
用 Java 接入大模型(二):流式还是非流式,到底怎么选
本文深入剖析流式与非流式API的核心差异,从响应结构、字段解析、错误处理、超时机制四大维度揭示选型陷阱;明确“用户是否等待”为关键判断标准,并提供可直接落地的7条决策清单,助你避免过早复杂化或体验降级。
232 1
|
2月前
|
人工智能 安全 算法
AI时代,终端防拍照发展到那一步了?
AI防拍照技术已突破“能否识别”阶段,主流方案准确率超99%,响应快至100毫秒,实现事中锁屏拦截。技术路线分化为纯软件、端侧硬件与光学对抗三类;水印用于溯源威慑,拦截专注实时阻断。二者协同构建防护闭环,但复杂场景适配与新设备盲区仍是挑战。
|
2月前
|
机器学习/深度学习 运维 安全
用 Java 接入大模型(三):temperature、top_p、max_tokens 到底怎么调
本文详解大模型调用核心参数:厘清temperature、top_p等作用边界,强调“参数只影响选词,不改变理解”;提供分场景配置清单与故障排查指南,助开发者高效调试、避免无效调参。(239字)
325 1
|
2月前
|
存储 缓存 人工智能
Agent运行机制拆解:上下文、检查点、任务恢复以及循环执行、资源管控完整流程23.3
本文系统解析大模型Agent的核心运行机制,涵盖执行循环、上下文与状态管理、工具反馈、检查点、停止条件、资源管控及人工接管等十大模块,揭示其“自主迭代、容错可溯、可控可兜底”的本质,助力开发者构建稳定智能体应用。
289 2
|
2月前
|
自然语言处理
判断型模型的架构位置与选型边界:判别层、接口契约与可观测性设计
本文提出将大模型业务链路中的“判别”与“生成”职责解耦:用轻量、结构化、低延迟的判断型模型专司路由、打分、布尔判定等决策任务,输出即契约、免解析;生成模型专注自然语言表达。强调分层架构、封闭值域接口、校准驱动阈值设计及可观测性治理,不涉训练细节,聚焦工程落地。
168 0
|
2月前
|
人工智能 JavaScript 开发工具
DeepSeek Harness完整实操入门:Cordis插件内核、本地部署、SDK开发、模式选型与排坑全解
DeepSeek Harness是开源Agent运行时底座,打通大模型推理能力和本地文件、系统命令执行环境。依托Cordis插件内核,实现极高的可扩展能力,强化本地权限管控与完整执行链路可追溯。它并不是拿来直接聊天的成品软件,而是供开发者搭建、调试、评测智能体的底层底座。
423 0

热门文章

最新文章