背景痛点

最近项目需要接入大模型能力，调研时发现直接调用原生API存在几个明显问题：

• 协议复杂：不同厂商API的鉴权方式、参数结构差异大，比如OpenAI用Bearer Token而Claude使用x-api-key
• 响应不稳定：生成长文本时经常遇到网络抖动导致的连接中断
• 性能瓶颈：同步阻塞调用导致线程池迅速耗尽

技术选型

对比主流方案后，决定基于Spring Boot自封装SDK，主要考虑：

1. 官方SDK局限
2. OpenAI-Java版本更新滞后API变更
3. Claude官方未提供Java客户端
4. 自封装优势
5. 统一不同厂商的调用规范
6. 灵活定制重试/熔断策略
7. 方便集成公司内部监控体系

核心实现

1. 非阻塞调用封装

使用WebClient替代RestTemplate实现异步调用：

// 初始化配置
@Bean
public WebClient openAIClient() {
    return WebClient.builder()
        .baseUrl("https://api.openai.com/v1")
        .defaultHeader(HttpHeaders.AUTHORIZATION, "Bearer " + apiKey)
        .clientConnector(new ReactorClientHttpConnector(
            HttpClient.create()
                .responseTimeout(Duration.ofSeconds(30))
        ))
        .build();
}

2. 智能重试机制

结合Resilience4j实现带熔断的重试：

// 重试配置示例
RetryConfig config = RetryConfig.custom()
    .maxAttempts(3)
    .waitDuration(Duration.ofMillis(500))
    .retryOnException(e -> !(e instanceof ClientError))
    .build();

// 熔断配置
CircuitBreakerConfig cbConfig = CircuitBreakerConfig.custom()
    .failureRateThreshold(50)
    .waitDurationInOpenState(Duration.ofSeconds(60))
    .build();

3. 流式响应处理

处理SSE(Server-Sent Events)类型响应：

public Flux<String> streamCompletion(ChatRequest request) {
    return webClient.post()
        .uri("/chat/completions")
        .bodyValue(request)
        .accept(MediaType.TEXT_EVENT_STREAM)
        .retrieve()
        .bodyToFlux(String.class)
        .timeout(Duration.ofSeconds(120));
}

生产优化

连接池调优

通过压测得出最佳参数组合：

| 参数 | 默认值 | 优化值 | QPS提升 | |---------------------|--------|--------|---------| | maxConnections | 500 | 1000 | +35% | | pendingAcquireTimeout | 45s | 20s | -15%超时 |

监控埋点

集成Prometheus监控关键指标：

@Bean
public MeterBinder httpMetrics(ConnectionProvider provider) {
    return binder -> {
        binder.bind(provider.metrics())
            .to(new FunctionCounter.Builder<>(
                "http.connections.active", 
                m -> m.totalConnections()
            ).register(registry));
    };
}

避坑指南

1. Token计算误区
2. 中文通常1token≈2中文字符

3. 系统消息也会消耗token额度

4. 内存泄漏风险

5. 对话历史需定期清理
6. 使用WeakReference管理上下文

示例与思考

提供完整示例项目：[GitHub链接]
思考题：当大模型API响应时间超过5秒时，如何设计分级降级策略？可以从以下维度考虑：

1. 优先降级非核心功能（如关闭流式响应）
2. 切换备用模型版本
3. 返回本地缓存结果

希望这篇指南能帮你避开我踩过的坑。如果有更好的实践方案，欢迎在评论区交流！