企业官网建设流程全解析

1. 从“能跑就行”到“跑得漂亮”：Java 调用大模型接口的工程化进阶

很多朋友在写完前两篇的 Demo 之后，都会遇到一个相同的尴尬期：本地跑个main方法调用大模型接口，看着控制台一行行吐出文字，感觉挺爽。可一旦要把这段代码塞进真实的 Spring Boot 项目里，问题就全冒出来了——接口超时怎么处理？流式响应怎么推给前端？多轮对话的上下文怎么存？Token 超限了怎么截断？并发一上来线程池直接被打满怎么办？

这篇内容就是来解决这些“从玩具到工具”的落地问题的。我把它定位成Java 工程师接入大模型能力的第三阶段：不再纠结于“怎么发一个 HTTP 请求”，而是聚焦于怎么把大模型调用封装成一个稳定、可观测、可扩展的服务层。适合已经跑通过基础调用、准备在真实业务里落地 AI 能力的后端开发同学，也适合正在做技术选型的架构同学参考。

整篇内容会围绕一个核心思路展开：把大模型当成一个“不太稳定但很聪明”的远程依赖来对待。这个定位很关键，因为一旦你这么想，很多工程手段就自然浮现了——超时、重试、熔断、降级、限流、缓存、日志埋点，这些你平时对待数据库和第三方接口的套路，几乎都能平移过来。下面我按实际落地顺序，把每个环节拆开讲。

2. 整体架构设计：为什么不能直接在 Controller 里调接口

2.1 分层设计的必要性

我见过不少项目，图省事直接在 Controller 里new一个 HTTP 客户端就开始调大模型。刚开始没问题，等到要加缓存、要换模型供应商、要做 A/B 测试的时候，代码就变成了一团乱麻。所以第一步，先把层次划清楚。

一个比较稳妥的分层是这样的：Controller 层只负责参数校验和响应封装，Service 层负责业务编排和上下文管理，Client 层专门负责和大模型服务通信，Config 层管理密钥、模型参数、超时配置。这样分层之后，换模型只需要动 Client 层，加业务逻辑只需要动 Service 层，互不干扰。

为什么强调这个？因为大模型接口和普通 REST 接口有个本质区别：它的响应时间波动极大。同样一段提示词，可能 2 秒返回，也可能 30 秒才吐完。如果业务逻辑和网络调用混在一起，一旦超时，你根本分不清是业务卡住了还是网络卡住了。分层之后，超时控制可以精确地加在 Client 层，业务层完全不用关心底层是 HTTP 还是 WebSocket。

2.2 同步与流式的选型逻辑

这里有个绕不开的决策：到底用同步调用还是流式调用？我的经验是看场景。

如果是后台批处理任务，比如批量生成商品描述、批量翻译文档，用同步调用最省心，代码简单，错误处理直接。但如果是面向用户的交互场景，比如智能客服、代码助手，那必须用流式，否则用户盯着转圈圈十几秒，体验直接崩掉。

流式的实现方式在 Java 里主要有两种：SSE（Server-Sent Events）和WebSocket。SSE 更轻量，基于 HTTP，浏览器原生支持，适合服务端单向推送的场景，也就是大模型吐字这种。WebSocket 是全双工，适合需要双向频繁通信的场景。绝大多数大模型对话场景，SSE 就够了，别过度设计。

提示：SSE 在 Java 服务端通常用SseEmitter来实现，但要注意它的超时时间默认比较短，必须手动设置，否则长回答还没吐完连接就断了。

2.3 配置外置与多环境管理

密钥和模型参数绝对不能硬编码在代码里，这是底线。我一般用application.yml配合环境变量来管理，本地开发用配置文件，线上用环境变量注入。模型名称、温度值、最大 Token 数这些也一并外置，方便不同环境用不同配置。

这里有个细节值得说：不同模型的参数范围不一样。有的模型温度值支持到 2.0，有的只到 1.0；有的最大输出 Token 是 4096，有的是 8192。如果把这些写死，换模型的时候就会踩坑。我的做法是给每个模型建一个配置档案，切换模型时连参数一起切换。

3. 核心细节解析：HTTP 客户端选型与连接管理

3.1 客户端选型对比

Java 生态里能发 HTTP 请求的库太多了，我列个表对比一下常见几个在大模型调用场景下的表现。

我个人的偏好是：Spring 项目用 WebClient，非 Spring 项目用 OkHttp。原因很简单，WebClient 的响应式流处理大模型的流式响应非常自然，背压机制也能防止内存被打爆。OkHttp 则是轻量、稳定、文档全，出问题好排查。

3.2 连接池与超时参数计算

这是最容易被忽视、但最容易出问题的地方。大模型接口的超时设置和普通接口完全不是一个量级。

先说连接超时，这个可以短一点，5 秒足够，因为建立 TCP 连接本身很快。真正要命的是读取超时。普通接口设 10 秒，大模型接口如果设 10 秒，稍微长一点的回答直接就被掐断了。我的经验值是：同步调用读取超时设 60 到 120 秒，流式调用设 300 秒以上。

连接池大小也要算。假设你的服务 QPS 是 50，每次调用平均耗时 5 秒，那并发连接数大约是 50 乘以 5 等于 250。但大模型调用耗时波动大，得留余量，所以最大连接数设 300 到 500 比较稳妥。同时要设置连接存活时间，避免长时间空闲连接被服务端悄悄关掉后，客户端还在用导致报错。

// OkHttp 连接池与超时配置示例 OkHttpClient client = new OkHttpClient.Builder() .connectTimeout(5, TimeUnit.SECONDS) .readTimeout(120, TimeUnit.SECONDS) .writeTimeout(30, TimeUnit.SECONDS) .connectionPool(new ConnectionPool(300, 5, TimeUnit.MINUTES)) .retryOnConnectionFailure(true) .build();

注意：retryOnConnectionFailure这个参数要谨慎。对于幂等的查询类调用可以开，但对于会产生副作用的调用，重试可能导致重复计费或重复执行，得配合幂等键使用。

3.3 请求体的构造细节

大模型接口的请求体通常是 JSON，里面有几个关键字段需要特别注意。messages 数组的顺序决定了对话逻辑，system 消息必须放最前面，否则有些模型会忽略它。temperature 参数控制随机性，做代码生成建议设 0.2 到 0.5，做创意文案可以设 0.8 到 1.0。max_tokens要留够，但也不能太大，否则可能被服务端拒绝或者浪费额度。

还有一个坑：中文编码。虽然现在大部分客户端默认 UTF-8，但如果你手动拼 JSON 字符串，一定要显式指定字符集，否则中文提示词可能变成乱码，模型返回的结果也会莫名其妙。

4. 实操过程：从零搭建一个可用的服务层

4.1 项目依赖与基础配置

假设你用的是 Spring Boot 3.x，先加依赖。核心就是 WebFlux（为了 WebClient）和 Jackson（处理 JSON）。如果你用 Maven，大概是这样：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-webflux</artifactId> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> </dependency>

配置文件里把模型相关的参数抽出来：

llm: base-url: https://api.example.com/v1 api-key: ${LLM_API_KEY} model: default-model temperature: 0.3 max-tokens: 2048 connect-timeout: 5000 read-timeout: 120000

这里用${LLM_API_KEY}从环境变量读取，避免密钥进代码仓库。read-timeout给到 120 秒，是考虑到长回答的场景。

4.2 封装统一的请求与响应模型

不要在每个地方都手拼 Map，定义清晰的 DTO 能让代码可读性提升一个档次。请求侧核心是messages列表，每条消息有role和content。响应侧要能兼容普通返回和流式返回两种格式。

public record ChatMessage(String role, String content) {} public record ChatRequest( String model, List<ChatMessage> messages, double temperature, int maxTokens, boolean stream ) {}

用 record 是 Java 17 之后的写法，简洁且不可变，适合这种纯数据传输的场景。如果你的项目还在 Java 8，用普通的 POJO 加 Lombok 也行，思路一样。

4.3 同步调用的完整实现

同步调用适合后台任务。核心步骤是：构造请求体、发 POST、解析响应、提取内容。这里的关键是异常处理要分类型。网络超时是一种，服务端返回 4xx 是一种，返回 5xx 又是一种，处理策略完全不同。

public String chatSync(List<ChatMessage> messages) { ChatRequest request = new ChatRequest( model, messages, temperature, maxTokens, false ); try { String response = webClient.post() .uri("/chat/completions") .header("Authorization", "Bearer " + apiKey) .contentType(MediaType.APPLICATION_JSON) .bodyValue(request) .retrieve() .bodyToMono(String.class) .block(Duration.ofSeconds(120)); return parseContent(response); } catch (WebClientResponseException e) { // 区分 4xx 和 5xx if (e.getStatusCode().is4xxClientError()) { throw new BizException("请求参数有误: " + e.getResponseBodyAsString()); } throw new BizException("服务端异常，稍后重试"); } catch (Exception e) { throw new BizException("调用超时或网络异常"); } }

block这里设了 120 秒的超时，和配置里的读取超时呼应。注意block在响应式编程里是“反模式”，但在同步场景下它是必要的桥接手段，只要不在响应式链路里调用就没问题。

4.4 流式调用的实现要点

流式调用是重点。用 WebClient 的话，核心是拿到Flux<String>，然后逐块处理。大模型返回的流式数据通常是 SSE 格式，每行以data:开头，最后以data: [DONE]结束。

public Flux<String> chatStream(List<ChatMessage> messages) { ChatRequest request = new ChatRequest( model, messages, temperature, maxTokens, true ); return webClient.post() .uri("/chat/completions") .header("Authorization", "Bearer " + apiKey) .contentType(MediaType.APPLICATION_JSON) .bodyValue(request) .retrieve() .bodyToFlux(String.class) .filter(line -> line.startsWith("data: ")) .map(line -> line.substring(6)) .takeUntil("[DONE]"::equals) .filter(chunk -> !"[DONE]".equals(chunk)) .map(this::extractDelta); }

这段代码里有几个细节值得展开。filter先筛掉非 data 行，map去掉前缀，takeUntil遇到结束标记就停止，最后再过滤一次把结束标记本身去掉。extractDelta负责从每个 JSON 块里提取增量文本。

提示：流式响应里每个 chunk 的 JSON 结构可能不完全一样，有的带 role，有的只带 content，解析时要做好空值判断，否则容易 NPE。

4.5 上下文管理与 Token 截断

多轮对话的核心是维护一个消息列表。但列表不能无限增长，因为 Token 有上限。我的做法是滑动窗口加摘要：保留最近 N 轮完整对话，更早的内容用一次额外的模型调用压缩成摘要。

滑动窗口的大小怎么定？先算 Token。粗略估算，一个中文字大约 1 到 2 个 Token，英文一个单词大约 1.3 个 Token。假设模型上限 4096 Token，system 提示占 200，输出预留 1000，那留给历史的只有约 2900 Token。按每轮对话平均 200 Token 算，大概能放 14 轮。实际实现时留点余量，设 10 轮比较安全。

private List<ChatMessage> trimHistory(List<ChatMessage> history, int maxRounds) { if (history.size() <= maxRounds * 2) { return history; } List<ChatMessage> trimmed = new ArrayList<>(); trimmed.add(history.get(0)); // 保留 system int start = history.size() - maxRounds * 2; trimmed.addAll(history.subList(start, history.size())); return trimmed; }

这个maxRounds * 2是因为一问一答算两条消息。保留 system 消息很重要，否则模型的角色设定会丢失。

5. 常见问题与排查技巧实录

5.1 超时与连接异常排查表

实际跑起来之后，问题基本都集中在网络层。我整理了一张速查表，覆盖我遇到过的高频问题。

这张表里的每一条我基本都踩过。特别是 429 限流，很多人第一反应是加机器，其实应该先做客户端限流，用令牌桶控制发送速率，再配合指数退避重试。

5.2 流式响应的“半截话”问题

流式调用最烦人的问题是：用户看到一半，连接断了，回答不完整。原因通常是服务端的 SSE 超时或者网关的空闲超时。解决办法有两个：一是在服务端定期发送心跳注释行，保持连接活跃；二是在客户端做断点续传，记录已接收的内容，重连后从断点继续。

心跳的实现很简单，在流式响应里每隔 15 秒插入一个空注释行就行。断点续传复杂一些，需要服务端支持传入已生成内容的偏移量，不是所有模型都支持，得看具体接口能力。

5.3 并发场景下的线程池配置

如果你的服务要扛并发，线程池配置是个大坑。大模型调用是 IO 密集型，不是 CPU 密集型，所以线程数可以设大一些。经验公式是：线程数等于目标 QPS 乘以平均耗时（秒）再留 1.5 倍余量。

假设目标 QPS 是 20，平均耗时 8 秒，那核心线程数设 20 乘以 8 再乘 1.5，约 240。但线程太多也浪费内存，所以配合连接池上限一起控制。队列不要设太大，否则请求堆积，用户等半天才收到超时。我一般用有界队列加拒绝策略，拒绝时直接返回“服务繁忙”，比让用户干等强。

注意：如果用 WebClient 的响应式链路，其实不需要自己配线程池，它用的是事件循环。但如果你在中间用了block，那就退化成阻塞模型了，线程池配置又变得重要。所以要么全响应式，要么全阻塞，别混着用。

5.4 日志与可观测性

大模型调用的日志不能只记“成功”或“失败”，要记耗时、Token 消耗、模型名称、请求 ID。这些数据对成本核算和性能优化至关重要。

我一般会在 Client 层加一个拦截器，记录请求前后的时间戳，解析响应里的 usage 字段拿到 Token 数。请求 ID 用 UUID 生成，贯穿整个链路，方便排查问题时串联日志。这些数据积累一段时间后，你就能看出哪个模型性价比高、哪个提示词消耗大，对后续优化非常有帮助。

6. 进阶优化：缓存、降级与成本控制

6.1 结果缓存策略

大模型调用又慢又贵，能缓存就缓存。但不是所有请求都能缓存，得看场景。相同提示词加相同参数的请求，结果可以缓存。缓存键用提示词内容的哈希值加模型参数组合生成。

缓存时间怎么定？如果是事实性问答，可以缓存久一点，比如一天。如果是时效性内容，比如“今天的天气”，那就不能缓存。我的做法是给每个业务场景配一个缓存策略，默认不缓存，明确需要缓存的场景才开。

public String chatWithCache(String prompt) { String cacheKey = "llm:" + DigestUtils.md5Hex(prompt + model + temperature); String cached = redisTemplate.opsForValue().get(cacheKey); if (cached != null) { return cached; } String result = chatSync(List.of(new ChatMessage("user", prompt))); redisTemplate.opsForValue().set(cacheKey, result, Duration.ofHours(1)); return result; }

用 Redis 做缓存层，注意设置合理的过期时间，避免内存无限增长。

6.2 降级与兜底方案

大模型服务不可能 100% 可用，所以必须有降级方案。降级分几层：第一层是重试，网络抖动导致的失败重试一两次可能就好了；第二层是切换模型，主模型不可用时切到备用模型；第三层是返回兜底内容，比如“当前服务繁忙，请稍后再试”。

重试要加退避，不能立刻重试，否则会把服务端打得更惨。指数退避加随机抖动是比较通用的做法，第一次等 1 秒，第二次等 2 秒，第三次等 4 秒，再加个 0 到 1 秒的随机值避免同时重试。

6.3 成本监控与预算控制

Token 就是钱，得有监控。我一般会在服务层加一个计数器，按天统计每个业务线的 Token 消耗，超过阈值就告警。更进一步，可以设置硬性预算，超过之后自动降级到更便宜的模型或者直接拒绝。

这个监控数据还能反过来指导优化。比如你发现某个提示词消耗特别大，就可以针对性精简它；发现某个场景用便宜模型效果也够，就切过去省钱。这些都是实打实的成本优化。

7. 一些踩坑之后的个人体会

写到这里，核心的工程化要点基本都覆盖了。最后分享几个我在实际项目里踩过坑才明白的道理。

第一，别迷信“一次调用解决所有问题”。刚开始我总想用一个超长提示词让模型干完所有事，结果又慢又不稳定。后来拆成多个小调用，每个调用职责单一，反而整体更快更稳。这跟微服务的思路是一样的。

第二，流式响应的错误处理比同步复杂得多。同步调用出错直接抛异常就行，流式调用可能吐了一半才出错，这时候前端已经渲染了部分内容，你得设计好“部分成功”的展示逻辑，不能让用户看到半截话还不知道发生了什么。

第三，参数调优是个体力活。温度、最大 Token、提示词措辞，这些都会影响结果。我的建议是建一个测试集，每次调整参数都跑一遍，用数据说话，别凭感觉。我见过太多人改了个温度值觉得“好像好点了”，其实根本没量化对比。

第四，连接池和线程池的配置没有银弹。网上抄来的参数不一定适合你的场景，必须根据自己的 QPS、耗时分布、机器配置来压测调优。我一般会做几轮压测，观察 P99 耗时和错误率，找到拐点再定参数。

这套东西搭起来之后，你会发现大模型调用其实和调数据库没本质区别，都是远程依赖，都需要超时、重试、熔断、监控。把工程化的基本功做扎实，AI 能力才能真正在业务里跑起来，而不是停留在 Demo 阶段。