知序
返回
保存草稿
发布
H1
H2
H3
1
2
3
Excalidraw 图
AI 写作
AI 优化
目录
输入内容后显示目录
Markdown
# Java 应用接入大模型工程实践 > 导读:本文从"Java 团队接大模型,究竟该 HTTP 直连、用厂商 SDK 还是上 LangChain4j / Spring AI?为什么本地跑得通、一上线就被超时、限流和线程池拖垮"这个实际开发中的疑问出发,把接入方式选型、同步 / 流式 / 异步三种调用在 Spring 里的落地、SSE 流式服务端实现、超时重试幂等限流熔断降级、线程池隔离与虚拟线程、多供应商适配、可观测性与密钥安全逐项讲透,最后给出一个可运行的 Spring Boot 最小示例与踩坑清单。适合已有 Spring / Spring Boot 基础、正准备把大模型(LLM,Large Language Model,大语言模型)能力接入业务系统的 Java 后端工程师。  *图:Java 接入大模型——流式输出与超时、重试、降级防护* ## 一、先建立全局认知 ### Q:Java 应用接入大模型,到底有哪几种方式?怎么选? A:结论先行——**绝大多数业务系统只需要"一个薄的 HTTP 封装层 + OpenAI 兼容接口",把超时、限流、降级做扎实;只有当你要编排 RAG、Agent、多步工具调用时,才引入 LangChain4j 或 Spring AI 这类框架。** 厂商 SDK 与编排框架都只是"调用姿势",永远替不了你自己做稳定性工程。 先看全景。LLM 调用在工程上的本质,是**一次很慢、很贵、可能失败、且带配额的 HTTP 请求**。记住这句话,后面所有设计都是从它推导出来的。 | 接入方式 | 本质 | 优点 | 代价 | 适用场景 | |---|---|---|---|---| | HTTP 直连 | WebClient / RestClient / HttpClient 直接 POST OpenAI 兼容接口 | 零额外依赖、协议透明、完全可控、升级成本低 | 请求体、流式解析、错误码都要自己封装 | 供应商少、追求可控与轻量,中小团队的默认选择 | | 厂商 SDK | 官方或第三方提供的 Java SDK | 类型安全、封装鉴权与部分重试 | 各家 API 不统一、SDK 版本绑定、出问题是黑盒 | 深度绑定某一家、需要其产品级特性 | | LangChain4j | 面向 LLM 的 Java 编排框架 | 统一多模型抽象、`AiServices` 声明式接口、RAG / Tool 开箱即用 | 抽象层多、升级有破坏性变更、排障要穿透到底层 | 多模型、RAG、Agent、工具编排 | | Spring AI | Spring 官方 AI 抽象 | 与 Spring 生态无缝、`ChatClient` 流式友好、Advisor 机制 | 相对年轻、API 演进较快 | Spring 技术栈、追求长期可维护 | 选型建议可以压缩成三条判断: 1. **只做"问答 / 总结 / 分类"这类单轮或多轮对话**:选 HTTP 直连,自己封装一层 `LlmClient`。协议就是 `POST {base-url}/v1/chat/completions`,请求体是 `model` + `messages`,响应取 `choices[0].message.content`。公开、稳定、可迁移。 2. **需要工具调用、RAG、多步编排**:选 LangChain4j 或 Spring AI。Spring 技术栈优先 Spring AI,非 Spring 或需要更丰富的能力(大量社区集成)优先 LangChain4j。 3. **已经深度绑定某家云厂商**:可以用其 SDK 快速起步,但仍建议在 SDK 之上再包一层自己的接口,否则将来换模型会牵动所有业务代码。 这里有个常被忽略的取舍:**框架的抽象越"高",你离底层协议越远,出问题越难定位**。生产中"模型调不通"这类问题,八成发生在网络层、鉴权层、配额层,而这三层恰恰是高层框架最容易藏起来的地方。所以即使上了框架,也建议保留一条"直连探针"(一个只发最小 `chat/completions` 请求的接口),排障时能快速分层。 ### Q:OpenAI 兼容接口的请求 / 响应结构长什么样? A:结论先行——**"OpenAI 兼容"已经成了行业事实标准,主流厂商(含国内的通义千问、DeepSeek 等)都提供兼容模式,认准这套 JSON 结构,你就能用一套代码对接多家。** 但要清楚各家"兼容度"不同,细节差异要单独确认。 非流式请求体(关键字段): ```json { "model": "your-model-name", "messages": [ {"role": "system", "content": "你是一个严谨的助手"}, {"role": "user", "content": "用一句话解释什么是幂等"} ], "temperature": 0.2, "max_tokens": 512, "stream": false } ``` 非流式响应体(关键字段): ```json { "id": "chatcmpl-xxx", "object": "chat.completion", "model": "your-model-name", "choices": [ { "index": 0, "message": {"role": "assistant", "content": "幂等是指同一操作执行一次和执行多次结果相同。"}, "finish_reason": "stop" } ], "usage": {"prompt_tokens": 28, "completion_tokens": 24, "total_tokens": 52} } ``` 几个必须记住的字段:`choices[0].finish_reason` 为 `stop` 表示正常结束、`length` 表示被 `max_tokens` 截断、`tool_calls` 表示模型请求调用工具;`usage` 是计费与观测的核心,**流式响应默认可能不返回 usage**(OpenAI 系需要显式开启返回用量统计,具体字段名需结合所用版本与供应商确认)。 ## 二、理解核心机制:三种调用方式 ### Q:同步、流式、异步三种调用分别长什么样,Spring 里怎么落地? A:结论先行——**同步用于后台任务和短回答,流式用于面向用户的交互式输出,异步用于需要并发扇出(如同时调多个模型做对比)的场景。三者的稳定性和线程模型完全不同,不能混用一套超时策略。** 先看三种方式的行为差异: ```text 同步(blocking): 调用线程 --发出请求--> [ 等待 3~30s,线程被占用 ] --> 拿到完整结果 --> 返回 流式(streaming, SSE): 调用线程 --发出请求--> 首 token(~几百 ms) --> 增量 token ... --> [DONE] 用户边生成边看到,体验好,但连接是长连接 异步(async / reactive): 调用线程 --发出请求--> 立即返回 Future/Mono --> 结果在回调/订阅中到达 线程被释放,适合并发扇出与组合 ``` **同步调用**用 Spring 6.1+ 的 `RestClient`(或 `WebClient.block()`、JDK `HttpClient`)即可: ```java // 场景:后台批处理、定时任务、内部接口,不需要把结果实时推给用户 RestClient client = RestClient.builder() .baseUrl(props.getBaseUrl()) .defaultHeader("Authorization", "Bearer " + props.getApiKey()) .build(); ChatResponse resp = client.post() .uri("/v1/chat/completions") .body(request) // request 为上面那套 JSON 对应的 POJO .retrieve() .body(ChatResponse.class); String answer = resp.getChoices().get(0).getMessage().getContent(); ``` 关键点与边界:同步调用会**长时间占住当前线程**(Tomcat 工作线程或业务线程池),这是后面线程池隔离问题的根源;它只适合"调用方本来就能等"的场景,绝不能直接放在高并发的 C 端请求主链路上裸奔。`RestClient` 底层支持设置连接 / 读取超时,但**不要依赖框架默认值**,必须显式配置。 **流式调用**在 WebFlux 下用 `WebClient` 接收 SSE 是最自然的: ```java // 场景:对话式界面,需要逐字输出 Flux<String> stream = webClient.post() .uri("/v1/chat/completions") .header("Authorization", "Bearer " + apiKey) .contentType(MediaType.APPLICATION_JSON) .bodyValue(streamRequest) // 注意 stream=true .retrieve() .bodyToFlux(String.class) // 上游是 SSE,每个元素是一行 data .takeUntil("[DONE]"::equals) // OpenAI 系以 data: [DONE] 结束 .filter(s -> !"[DONE]".equals(s)) .map(this::extractDeltaContent); // 从每个 chunk 的 JSON 里取增量文本 ``` 这里有个**容易踩坑的点**:`bodyToFlux(String.class)` 拿到的是 SSE 的每一帧数据(`data:` 之后的内容),需要自己解析 JSON 取 `choices[0].delta.content`。不同供应商的结束标记与分帧方式可能有差异(`[DONE]`、`usage` 收尾帧等),**需结合实际响应确认**,不要照抄。 **异步 / 响应式**的价值在于"并发扇出 + 组合": ```java // 场景:同时给两个模型发同一问题,取更快的那个 Mono<String> a = callModel("model-a", q); Mono<String> b = callModel("model-b", q); Mono<String> fastest = Mono.firstWithSignal(a, b); // 谁先返回用谁 ``` 用 `Mono.zip` 可以做"多模型结果聚合",用 `Flux.merge` 可以把多路流式结果合并。注意响应式链路上**任何一次阻塞调用(如 `block()`、JDBC 同步查询)都会污染整个事件循环**,如果项目不是全响应式栈,更稳妥的做法是用 `CompletableFuture` + 专用线程池做异步,而不是硬上 WebFlux。 ### Q:服务端如何实现流式输出(SSE / text/event-stream)? A:结论先行——**Spring MVC 用 `SseEmitter`,WebFlux 用 `Flux<ServerSentEvent<T>>`;服务端必须解决超时、异常、客户端断开三件事,否则用户会看到"卡住不结束"或"连接泄漏"。** 两种实现的对比: | 维度 | Spring MVC + `SseEmitter` | WebFlux + `Flux` | |---|---|---| | 线程模型 | 请求处理线程释放,但每个连接仍有 AsyncContext 开销 | 非阻塞,连接数上限更高 | | 背压 | 不支持 | 原生支持 | | 使用成本 | 低,改动小 | 需全栈响应式或独立模块 | | 超时控制 | `emitter` 的 timeout + 容器 async 超时 | `timeout()` 操作符 + 容器配置 | | 适合 | 已有 MVC 项目的增量改造 | 新建响应式服务、高并发长连接 | **MVC 版**(适合绝大多数存量项目): ```java // 场景:把上游 LLM 的流式增量,转成本服务对前端的 SSE @GetMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter stream(@RequestParam String q) { SseEmitter emitter = new SseEmitter(120_000L); // 总超时 120s emitter.onTimeout(() -> emitter.complete()); // 必须处理,否则连接悬挂 emitter.onCompletion(() -> log.info("sse completed")); emitter.onError(e -> log.warn("sse error", e)); llmStreamClient.stream(q) .subscribe( chunk -> { try { emitter.send(SseEmitter.event().data(chunk)); } catch (IOException e) { emitter.completeWithError(e); } }, err -> emitter.completeWithError(err), emitter::complete // 上游 [DONE] 后主动结束 ); return emitter; } ``` 关键点:`SseEmitter` 的超时时间与"上游流式总耗时"要匹配,太短会在长回答时被切断;`onTimeout` / `onError` / `onCompletion` 三个回调**都要注册**,只在正常完成时 `complete()` 会导致异常路径连接泄漏;`send` 可能因客户端断开抛 `IOException`,必须捕获后结束。 **WebFlux 版**: ```java // 场景:新建响应式对话服务,需要更高连接上限 @GetMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<ServerSentEvent<String>> stream(@RequestParam String q) { return llmClient.stream(q) .map(delta -> ServerSentEvent.<String>builder().data(delta).build()) .timeout(Duration.ofSeconds(120)) .onErrorResume(e -> Flux.just( ServerSentEvent.<String>builder().event("error").data("生成失败").build())); } ``` 前端消费要点(用原生 `EventSource`): ```text 1. EventSource 只能发 GET,不能带自定义请求头 —— 需要鉴权就改用 fetch + ReadableStream, 或把 token 放 query(不安全)或短期一次性 ticket。 2. 必须监听 onerror:网络抖动/服务端关闭都会触发,需自行重连(EventSource 默认会重连)。 3. 要处理 UTF-8 跨 chunk 截断:中文一个字可能被拆到两帧,前端要按流累积再解码, 或用 TextDecoder({stream:true})。 4. 收到业务结束标记(如自定义 event: done)后主动 close(),避免无谓重连。 5. Nginx 等反向代理要关闭对 SSE 的缓冲(如 proxy_buffering off),否则流式会变成"攒一批发一批"。 ``` ### Q:多轮对话的上下文怎么组织?为什么最容易丢? A:结论先行——**上下文就是每次请求都要重发的 `messages` 数组,它天然是无状态的;所谓"丢上下文",几乎都是把会话状态错误地放在了进程内存里,而不是每次按 `sessionId` 从外部存储重新组装。** 大模型接口本身不保存任何会话。所谓"记得上一轮说了什么",是因为你**每一轮都把历史消息一起发上去**: ```json { "messages": [ {"role": "system", "content": "你是客服助手,只回答订单相关问题"}, {"role": "user", "content": "我的订单什么时候到?"}, {"role": "assistant", "content": "请提供订单号"}, {"role": "user", "content": "A12345"} ] } ``` 三种角色各司其职:`system` 放稳定的人格与约束(应放最前且尽量不变,利于命中缓存),`user` / `assistant` 按时间正序交替构成对话。几条工程纪律: - **会话状态外置**:历史存 Redis / 数据库,键为 `sessionId`,而不是存 `ThreadLocal`、静态 `Map` 或对象字段。否则多线程、扩容、重启都会导致丢上下文。 - **别在对象级别共享可变列表**:多个请求并发读写同一个 `List<Message>` 会串台,组装时应每次生成新的不可变列表。 - **要有 token 预算与裁剪策略**:上下文越长越贵、越慢,且受模型上下文窗口限制。常见做法是按"保留 system + 最近 N 轮 + 对更早历史做摘要"来裁剪,超出时丢弃最早的对话(需结合所选模型的上下文窗口大小确认)。 - **多实例部署下不要依赖粘性会话**:一旦发生重平衡,粘性会话就会失效,表现同样像"丢上下文"。 理解了"上下文靠客户端重发"这一点,就能顺带理解成本结构:**每多留一轮历史,每一轮请求都要为它重复付费**,这也是为什么裁剪与摘要是必须做的工程优化,而不是可选项。 ## 三、为什么 LLM 调用不能沿用普通 HTTP 的默认策略 ### Q:超时、重试、幂等、限流、熔断降级,为什么都要专门设计? A:结论先行——**LLM 请求"慢、贵、有配额、非确定性",普通 HTTP 客户端那套"短超时 + 无脑重试"的策略会导致超时误杀长回答、重试放大计费、429 雪崩。每一层都要按 LLM 的特性重设。** 先对比普通 HTTP 与 LLM 调用的差别: | 维度 | 普通后端 HTTP 调用 | LLM 调用 | |---|---|---| | 典型耗时 | 几十 ~ 几百 ms | 秒级 ~ 几十秒 | | 失败代价 | 低 | 高(可能已计费) | | 结果确定性 | 确定 | 同样输入可能不同输出 | | 配额 | 通常无 | TPM / RPM(每分钟 token / 请求数) | | 错误语义 | 业务错误为主 | 429 限流、5xx 抖动、内容安全拦截 | **超时(Timeout)**:要分三层设置,绝不能只设一个总超时。 ```text 连接超时(connect):3~5s // 建连失败要快速暴露 首包超时(first token):8~15s // 流式场景下,迟迟不吐字说明上游有问题 读超时 / 总超时(read/total):30~120s // 按业务允许的最长回答估算 ``` 配置示例(`application.yml`,值为经验值,需按业务与模型调整): ```yaml llm: base-url: https://your-gateway.example.com api-key: ${LLM_API_KEY} # 从环境变量注入,禁止硬编码 connect-timeout: 5s first-token-timeout: 10s read-timeout: 60s total-timeout: 120s ``` **反直觉点**:很多人把读超时设成 5s(沿用普通接口习惯),结果长回答全被切断;正确做法是"连接超时短、读超时长"。同时注意,**超时时间必须小于上游网关的超时**,否则你会看到"上游已放弃、你却还在等"的错配。 **重试(Retry)**:只重试"安全且可能成功"的错误。 ```java // 场景:网络抖动与限流可重试;参数错误与内容拦截重试没意义 @Retryable( retryFor = {WebClientRequestException.class, LlmServerException.class, LlmRateLimitException.class}, maxAttempts = 3, backoff = @Backoff(delay = 1000, multiplier = 2, maxDelay = 10000) // 1s,2s,4s... ) public String chatOnce(String q) { ... } ``` 三条纪律:**必须指数退避**(立即重试只会继续撞限流);**必须识别 `Retry-After`**(429 时上游会告诉你等多久);**必须设重试上限**(3 次足够,重试会真实计费与消耗配额)。并且,**流式请求一旦已经开始返回内容,通常不应重试**,否则会出现重复文本。 **幂等(Idempotency)**:`chat/completions` 本身无副作用,但语义上不幂等——同样输入可能不同输出,因此不能把重试当作"保证拿到同一结果"的手段。真正要防的是**下游副作用重复**:如果调用会触发 Function Calling 去写库、发消息,就必须给工具执行加幂等键(如 `tool_call_id` 作为去重键)。**需结合具体的工具实现设计幂等**,不要假设模型不会重复请求同一个工具。 **限流(Rate Limiting)**:两个方向。向内限制用户频率(防刷),向外遵守供应商的 TPM / RPM。 ```java // 场景:本地先限流,避免把上游配额打爆后再被动应对 429 private final RateLimiter global = RateLimiter.create(5.0); // 全局限流 5 QPS,示意值 private final RateLimiter perUser = RateLimiter.create(0.2); // 单用户约 12 次/分钟 public String chat(String userId, String q) { if (!perUser.tryAcquire()) throw new TooManyRequestsException("请求过于频繁"); global.acquire(); // 阻塞等待全局令牌 return llmClient.chat(q); } ``` 收到上游 429 的处理原则:**优先读 `Retry-After` 退避**,不要立刻重试;**把限流错误与真实故障区分**,否则会误导熔断器。 **熔断与降级(Circuit Breaker / Fallback)**:连续失败到阈值就快速失败,避免线程被慢请求占满导致雪崩。Resilience4j 的状态机:  *图:熔断器三态:CLOSED、OPEN、HALF_OPEN 流转* ```text CLOSED(正常放行) │ 失败率 / 慢调用比例超阈值 ▼ OPEN(直接快速失败,不再调用上游) │ 等待开放时长结束 ▼ HALF_OPEN(放行有限试探请求) │ 成功达阈值 → CLOSED ; 仍失败 → OPEN ``` ```java // 场景:上游大面积故障时快速失败并走兜底,保护自身线程 CircuitBreaker cb = CircuitBreaker.of("llm", CircuitBreakerConfig.custom() .failureRateThreshold(50) .slowCallDurationThreshold(Duration.ofSeconds(30)) .slowCallRateThreshold(50) .waitDurationInOpenState(Duration.ofSeconds(30)) .slidingWindowSize(20) .build()); String answer = CircuitBreaker.decorateSupplier(cb, () -> llmClient.chat(q)) .recover(CallNotPermittedException.class, e -> fallbackService.answer(q)) .get(); ``` 上述阈值均为**示意值**,需按自身 SLA 调优。降级策略按成本递增可选:返回缓存答案 → 切换备用模型 → 返回固定话术 → 转人工。**关键原则:降级路径不要再调用同一个失败的模型**。 ### Q:为什么不能直接用公共线程池?虚拟线程适不适用? A:结论先行——**LLM 同步调用是典型"长阻塞",必须用独立的、容量受限的隔离线程池(bulkhead,舱壁隔离);虚拟线程在 JDK 21+ 对这类阻塞 I/O 场景有帮助,但需注意版本行为与"别把无界并发直接打给上游"这两个前提。** 为什么不能用公共线程池(Tomcat 工作线程池、`ForkJoinPool.commonPool`、业务共享线程池): ```text 假设 Tomcat 200 个工作线程,LLM 平均耗时 20s、QPS 10: 占用线程 = 10 × 20 = 200 → 刚好吃满 一旦上游变慢到 40s → 需要 400 个线程 → 全部占满 结果:整个应用的其它接口全部排队,一个慢依赖拖垮全站。 ``` 这就是"慢依赖拖垮全站"的经典雪崩。解决办法是**舱壁隔离**:给 LLM 调用单独的、有上限的线程池,池满即拒绝(快速失败),失败被限制在 LLM 这条链路上。 ```java // 场景:把 LLM 调用圈在独立线程池里,池满直接拒绝,不拖累其它接口 @Bean("llmExecutor") public ThreadPoolTaskExecutor llmExecutor() { ThreadPoolTaskExecutor ex = new ThreadPoolTaskExecutor(); ex.setCorePoolSize(16); ex.setMaxPoolSize(32); ex.setQueueCapacity(64); ex.setThreadNamePrefix("llm-"); ex.setRejectedExecutionHandler(new ThreadPoolExecutor.AbortPolicy()); // 满则拒绝 ex.setWaitForTasksToCompleteOnShutdown(true); ex.setAwaitTerminationSeconds(30); ex.initialize(); return ex; } ``` 配套要点:**队列必须是有限队列**(无界队列会把拒绝变成无限堆积);**拒绝策略要显式**(在 LLM 场景"拒绝"往往比"排队到超时"体验更好);**线程池大小按上游配额倒推**(并发数不能超过上游允许的 RPM/TPM 折算值),而不是拍脑袋定大。还要注意,连接池(如 Reactor Netty 或 Apache HttpClient 的连接池)与线程池是两回事:**若连接池上限小于并发数,多余请求会卡在等待连接上**,表现和"上游慢"极像但根因不同,排查时要分开看线程栈与连接等待指标。 隔离之后还要有**熔断阈值与超时的联动**:当 LLM 调用被隔离线程池拒绝(队列满、线程满)时,这类"本地拒绝"也应被计入失败率或单独告警,否则会出现"上游其实没问题、但本地线程池配置过小导致大面积失败"的诡异现象——**快速失败本身是设计目标,但持续拒绝一定是容量问题,必须能被观测到**。 **虚拟线程是否适用?** 结论是"能缓解,但不是银弹": - 虚拟线程(Virtual Threads,JDK 21 正式转正的轻量级线程)让"一个请求一个线程"的阻塞模型重新划算,LLM 同步调用属于它擅长的高并发阻塞 I/O 场景。 - Spring Boot 3.2+ 可通过 `spring.threads.virtual.enabled=true` 让容器使用虚拟线程(具体支持范围需结合版本确认)。 - **但要警惕第一个前提**:虚拟线程解决的是"线程不够用",不解决"上游配额有限"。如果无限开虚拟线程去调 LLM,只会更快把上游 429 打爆。所以**虚拟线程之外仍要有限流与并发上限**。 - **第二个前提是版本行为**:早期 JDK 中,在 `synchronized` 块内发生阻塞会让虚拟线程"钉"在载体线程上(pinning,钉住),削弱收益;后续 JDK 版本对此有改进(需结合具体版本确认)。项目中若大量使用 `synchronized`,收益可能不及预期,应先做压测。 ## 四、多供应商适配、可观测性与安全 ### Q:如何做多供应商适配与切换(模型网关)? A:结论先行——**在"业务代码"和"模型供应商"之间加一层模型网关(Model Gateway,统一接入与路由层),把协议差异、模型名映射、密钥、限流、计费、降级都收敛到网关里,业务只认一套接口。** 没有网关时,每个业务服务各自对接各厂商,结果是重复代码、密钥扩散、换模型要改所有服务。有了网关,架构变成:  *图:Model Gateway:统一协议入口与七项网关能力* ```text 业务服务 --(统一协议)--> [Model Gateway] ├── 鉴权(内部 token) ├── 路由(按模型名/租户/成本选后端) ├── 协议转换(统一不同厂商 API) ├── 模型名映射(逻辑名 → 各家真实模型名) ├── 限流 / 熔断 / 降级 ├── 用量统计与计费 └── 日志与链路追踪 ↓ [供应商 A] [供应商 B] [自建推理] ``` 适配层要处理的实际差异,主要集中在四处: | 差异点 | 说明 | 适配做法 | |---|---|---| | 请求路径 | 兼容模式多为 `/v1/chat/completions`,原生模式路径各异 | 统一封装成内部 `chat` / `stream` 接口 | | 消息结构 | 有的用 `content` 字符串,有的支持 `content` 数组(多模态) | 内部模型归一化,出站时按后端转换 | | 模型命名 | 逻辑名(如 `chat-fast`)与真实模型名解耦 | 用配置做映射表,切换只改配置 | | 特有字段 | 部分厂商有独有参数(如思考模式开关) | 用 `extra` 透传字段,缺失时忽略 | 模型名映射的配置化示例: ```yaml llm: routes: chat-fast: # 业务只认这个逻辑名 primary: { provider: a, model: provider-a-small, base-url: ${A_URL} } fallback: - { provider: b, model: provider-b-lite, base-url: ${B_URL} } aliases: chat-smart: primary: { provider: a, model: provider-a-large, base-url: ${A_URL} } ``` **取舍**:自建网关灵活但要维护;开源方案(如 One API、LiteLLM 等)上手快但引入额外依赖与运维成本;`Spring Cloud Gateway` 也能扩展出一个 LLM 网关。**无论哪种,核心是让"业务不认识具体模型名"**,这样切换与灰度才可能不代码级联。 ### Q:可观测性怎么做?密钥与配置怎么保证安全? A:结论先行——**观测的核心是四个维度:耗时(分段)、用量(token)、结果(成功/失败/被截断)、链路(traceId 贯穿前后端与上游);安全的核心是密钥不入代码库、不进日志、不放前端。** 可观测性的关键指标: | 类别 | 指标 | 说明 | |---|---|---| | 延迟 | 首 token 延迟、总延迟 | 流式体验由首 token 决定 | | 用量 | prompt / completion / total tokens | 计费与成本分析的基础 | | 质量 | 空回答率、被截断率(`finish_reason=length`) | 反映 prompt 与 `max_tokens` 是否合理 | | 稳定性 | 成功率、429 比例、超时率、熔断触发次数 | 定位稳定性问题 | | 链路 | traceId、上游请求 id | 串联"前端 → 网关 → 供应商" | traceId 要从入口一路透传到上游请求头,并在日志里以 MDC 方式打标,这样一次调用可以在日志系统里被完整还原: ```java // 场景:把本服务的 traceId 透传给上游,方便与供应商排障时对齐 String traceId = MDC.get("traceId"); webClient.post().uri("/v1/chat/completions") .header("X-Trace-Id", traceId) // 自定义头,按上游支持情况调整 .bodyValue(req) .retrieve() .bodyToMono(ChatResponse.class) .doOnNext(r -> { Usage u = r.getUsage(); // 记录用量,注意判空 meterRegistry.counter("llm.tokens", "type", "total") .increment(u == null ? 0 : u.getTotalTokens()); }); ``` **密钥与配置安全**的四条底线: 1. **密钥不进代码库**:用环境变量、配置中心加密项或 KMS 注入,禁止写进 `application.yml` 明文与 Git。 2. **密钥不进日志**:`Authorization`、请求体中的敏感字段在日志输出前必须脱敏,最好在框架层做统一脱敏,而不是靠每个开发者自觉。 3. **密钥不下发前端**:前端永远只调你自己的后端,绝不直连供应商 API(否则密钥等于公开,且无法限流计费)。 4. **最小权限与轮换**:按用途分配不同密钥、定期轮换,一处泄漏只影响一个面。 日志脱敏示例(示意,具体正则按字段调整): ```java private static final Pattern KEY_PATTERN = Pattern.compile("(?i)(authorization|api[-_]?key)\"?\\s*[:=]\\s*\"?[^\",\\s]+"); public static String mask(String raw) { return KEY_PATTERN.matcher(raw).replaceAll("$1=***"); } ``` ## 五、完整的 Spring Boot 最小可运行示例 ### Q:一个"配置 + 客户端封装 + 流式接口 + 降级"的最小工程长什么样? A:结论先行——**下面这个例子用 WebFlux 的 `WebClient` 直连 OpenAI 兼容接口,包含:`@ConfigurationProperties` 配置、带超时的客户端封装、SSE 流式接口、熔断降级,可直接改造为生产起点。** 示例省略了鉴权框架与指标埋点的全部细节,仅保留主干。 配置类: ```java @ConfigurationProperties(prefix = "llm") public class LlmProperties { private String baseUrl; private String apiKey; private String model; private Duration connectTimeout = Duration.ofSeconds(5); private Duration readTimeout = Duration.ofSeconds(60); private Duration totalTimeout = Duration.ofSeconds(120); // getter / setter 省略 } ``` 客户端封装(连接超时用 Reactor Netty,读/总超时用操作符): ```java @Component public class LlmClient { private final WebClient webClient; private final LlmProperties props; public LlmClient(LlmProperties props) { this.props = props; HttpClient httpClient = HttpClient.create() .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, (int) props.getConnectTimeout().toMillis()); this.webClient = WebClient.builder() .baseUrl(props.getBaseUrl()) .defaultHeader("Authorization", "Bearer " + props.getApiKey()) .clientConnector(new ReactorClientHttpConnector(httpClient)) .build(); } /** 非流式:返回完整文本 */ public Mono<String> chat(String question) { Map<String, Object> body = Map.of( "model", props.getModel(), "messages", List.of(Map.of("role", "user", "content", question)), "stream", false); return webClient.post().uri("/v1/chat/completions") .contentType(MediaType.APPLICATION_JSON) .bodyValue(body) .retrieve() .bodyToMono(ChatResponse.class) .timeout(props.getTotalTimeout()) .map(r -> r.getChoices().get(0).getMessage().getContent()); } /** 流式:返回增量文本的 Flux */ public Flux<String> stream(String question) { Map<String, Object> body = Map.of( "model", props.getModel(), "messages", List.of(Map.of("role", "user", "content", question)), "stream", true); return webClient.post().uri("/v1/chat/completions") .contentType(MediaType.APPLICATION_JSON) .bodyValue(body) .retrieve() .bodyToFlux(String.class) .takeUntil("[DONE]"::equals) .filter(s -> !"[DONE]".equals(s)) .map(this::deltaOf) // 解析 choices[0].delta.content .timeout(props.getTotalTimeout()); } private String deltaOf(String chunk) { // 生产环境应复用已配置的 ObjectMapper,并对解析失败做容错 try { JsonNode node = new ObjectMapper().readTree(chunk); JsonNode d = node.path("choices").path(0).path("delta").path("content"); return d.isMissingNode() || d.isNull() ? "" : d.asText(); } catch (Exception e) { return ""; } } } ``` 带降级的流式控制器: ```java @RestController public class ChatController { private final LlmClient llmClient; private final CircuitBreaker breaker; public ChatController(LlmClient llmClient) { this.llmClient = llmClient; this.breaker = CircuitBreaker.of("llm", CircuitBreakerConfig.custom() .failureRateThreshold(50) .slidingWindowSize(20) .waitDurationInOpenState(Duration.ofSeconds(30)) .build()); } @GetMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<ServerSentEvent<String>> stream(@RequestParam String q) { Flux<String> upstream = CircuitBreaker .decorateFlux(breaker, llmClient.stream(q)); return upstream .map(delta -> ServerSentEvent.<String>builder().data(delta).build()) .onErrorResume(e -> Flux.just( ServerSentEvent.<String>builder() .event("fallback") .data("系统繁忙,请稍后重试") .build())); } } ``` 关键点与适用边界:这份示例**能跑通主链路,但不能直接上生产**——缺少入参校验、用户限流、指标埋点、异常分类(把 400 和 429 都当同一种错误处理)。你的下一步改造顺序建议是:先补超时与错误分类 → 再补限流与熔断 → 最后补观测与成本统计。 ## 六、工程实践与踩坑清单 ### Q:上线后最常见的坑有哪些? A:结论先行——**按"连接、上下文、超时、日志"四类记,能覆盖八成线上问题。** 1. **长连接断开 / 流式中断**:反向代理(Nginx / 网关)默认缓冲与超时会截断 SSE。症状是"回答到一半就停"或"整段一起蹦出来"。排查方向:关闭响应缓冲、调大 `proxy_read_timeout`、确认服务端总超时大于最长回答。 2. **上下文丢失 / 串台**:多轮对话靠 `messages` 数组传递历史。若把会话状态存在静态变量或线程本地,换线程后就会丢;若在多用户间共享了同一 `List`,会串台。正确做法是**会话状态外置**(Redis / 数据库),每次请求按 `sessionId` 组装 `messages`。 3. **超时设置反直觉**:把读超时设得很短会切断长回答;把总超时设得比上游网关还长会白等。原则是"连接短、读长、总超时小于上游"。 4. **日志脱敏**:请求体里可能包含用户隐私、密钥、系统提示词,直接 `log.info(JSON.toJSONString(request))` 会把它们全写进日志。务必统一脱敏,并避免打印完整 prompt。 5. **把 `max_tokens` 当成"够用就行"**:设太小会让回答被 `finish_reason=length` 截断,表现为"答案没说完"。应结合业务给足,并监控截断率。 6. **重试导致重复生成 / 重复副作用**:流式已开始后重试会出现重复文字;工具调用重试会导致重复写库。要么限制"仅未开始输出时重试",要么给副作用加幂等键。 7. **共享 `ObjectMapper` 与线程安全**:`WebClient`、`ObjectMapper` 都是线程安全的可复用组件,别每次请求 `new`(示例中的 `new ObjectMapper()` 仅为可读性,生产应注入单例)。 8. **静态密钥与硬编码地址**:换环境就要改代码,且容易泄漏。用配置中心 + 环境变量。 9. **不做成本观测**:直到账单暴涨才发现有人写了循环调用。从第一天就记录 token 用量并按租户聚合。 10. **忽略 `finish_reason`**:`stop` / `length` / `tool_calls` 语义不同,忽略它就无法区分"答完了"和"被截断了"。 ## 小结 - Java 接入大模型,默认用**薄 HTTP 封装 + OpenAI 兼容接口**,需要编排再上 LangChain4j / Spring AI;框架不替你做稳定性。 - 三种调用各有边界:**同步**简单但占线程,**流式**体验好但要用好 SSE 的三回调,**异步 / 响应式**适合扇出组合。 - LLM 调用必须**重设超时(连接短、读长)、重试(指数退避、识别 `Retry-After`、限制次数)、幂等(副作用加去重键)、限流(内外双向)、熔断降级(快速失败 + 兜底)**。 - **线程池隔离**是防雪崩的关键;**虚拟线程**能缓解线程占用,但不解决配额,且需注意版本相关的 pinning 行为。 - **模型网关**收敛协议差异、模型名映射、密钥与计费;**可观测性**看延迟、用量、质量、稳定性、链路五个面;**密钥**不入库、不进日志、不下前端。 - 推荐改造顺序:超时与错误分类 → 限流与熔断 → 观测与成本。 ## 思考题 1. 如果上游供应商没有返回 `usage`(例如某些流式响应默认不带用量),你会如何估算与统计 token 消耗? 2. 当同一租户同时发起大量流式请求时,`SseEmitter` 与 `Flux` 两种实现在线程占用与超时控制上的差异会导致什么样的不同故障表现? 3. 假设你要在"主模型限流"时自动切到备用模型,如何设计才能既保证切换生效、又避免备用模型被瞬间打爆?模型名映射与限流配置应放在哪一层? 4. 虚拟线程开启后,如果发现 LLM 场景吞吐没有提升甚至下降,你会从哪几个方向排查(提示:pinning、上游配额、连接池)? 5. 如何设计一条"直连探针"接口,使它既能快速定位问题发生在网络层 / 鉴权层 / 配额层,又不会额外消耗可观费用?
预览
发布文章
添加摘要让读者更快了解文章内容
取消
确认发布
AI 写作助手
输入一个主题,AI 将为你生成一篇 Markdown 博客文章
AI 正在写作中...
取消
开始生成
AI 优化助手
描述你的修改需求,AI 将在原文基础上进行补充或微调
AI 正在优化中...
取消
开始优化
画布
从已有图里选
✕
图名
保存后生成 /images/excalidraw/<图名>.svg(只能用字母、数字、短横线、下划线、点)
取消
保存并插入