Spring Boot项目中集成文心一言API的实战指南最近在开发一个需要AI对话功能的Spring Boot应用时我选择了百度的文心一言作为后端引擎。整个过程从申请API权限到最终实现流式响应踩了不少坑也积累了一些经验。本文将分享如何在Spring Boot项目中优雅地集成文心一言API包括配置管理、服务封装和性能优化等实战细节。1. 环境准备与权限申请在开始编码前我们需要完成两项准备工作创建文心一言应用和配置Spring Boot项目。首先访问百度智能云平台找到文心千帆大模型服务。创建应用后会获得API Key和Secret Key这两个凭证将用于后续的接口认证。建议将这些敏感信息存储在环境变量中而不是直接硬编码在项目里。对于Spring Boot项目基础依赖如下dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdcom.squareup.okhttp3/groupId artifactIdokhttp/artifactId version4.9.3/version /dependency dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId /dependency /dependencies关键配置参数建议放在application.yml中wenxin: api: key: ${WENXIN_API_KEY} secret: ${WENXIN_API_SECRET} base-url: https://aip.baidubce.com2. 核心服务层实现我们将创建一个WenxinService来处理所有与文心一言API的交互。这个服务需要处理认证令牌的获取和管理。首先定义配置类自动注入参数ConfigurationProperties(prefix wenxin.api) Getter Setter public class WenxinProperties { private String key; private String secret; private String baseUrl; }然后实现核心服务类Service RequiredArgsConstructor public class WenxinService { private final WenxinProperties properties; private final OkHttpClient httpClient; private String cachedToken; private Instant tokenExpireTime; public String getToken() { if (cachedToken ! null Instant.now().isBefore(tokenExpireTime)) { return cachedToken; } HttpUrl url HttpUrl.parse(properties.getBaseUrl() /oauth/2.0/token) .newBuilder() .addQueryParameter(grant_type, client_credentials) .addQueryParameter(client_id, properties.getKey()) .addQueryParameter(client_secret, properties.getSecret()) .build(); Request request new Request.Builder() .url(url) .build(); try (Response response httpClient.newCall(request).execute()) { JsonNode root objectMapper.readTree(response.body().string()); cachedToken root.path(access_token).asText(); int expiresIn root.path(expires_in).asInt(); tokenExpireTime Instant.now().plusSeconds(expiresIn - 300); // 提前5分钟刷新 return cachedToken; } catch (IOException e) { throw new RuntimeException(Failed to get access token, e); } } }3. 实现同步与异步调用文心一言API支持两种调用方式同步阻塞式和异步流式。我们先实现同步调用public String sendMessageSync(ListChatMessage messages) { String token getToken(); HttpUrl url HttpUrl.parse(properties.getBaseUrl() /rpc/2.0/ai_custom/v1/wenxinworkshop/chat/eb-instant) .newBuilder() .addQueryParameter(access_token, token) .build(); MapString, Object body Map.of( messages, messages, stream, false ); Request request new Request.Builder() .url(url) .post(RequestBody.create( objectMapper.writeValueAsString(body), MediaType.parse(application/json) )) .build(); try (Response response httpClient.newCall(request).execute()) { JsonNode root objectMapper.readTree(response.body().string()); return root.path(result).asText(); } catch (IOException e) { throw new RuntimeException(API call failed, e); } }对于需要实时交互的场景流式调用能显著提升用户体验public void sendMessageStream(ListChatMessage messages, ConsumerString callback) { String token getToken(); HttpUrl url HttpUrl.parse(properties.getBaseUrl() /rpc/2.0/ai_custom/v1/wenxinworkshop/chat/eb-instant) .newBuilder() .addQueryParameter(access_token, token) .build(); MapString, Object body Map.of( messages, messages, stream, true ); Request request new Request.Builder() .url(url) .post(RequestBody.create( objectMapper.writeValueAsString(body), MediaType.parse(application/json) )) .build(); EventSource.Factory factory EventSources.createFactory(httpClient); factory.newEventSource(request, new EventSourceListener() { Override public void onEvent(EventSource eventSource, String id, String type, String data) { try { JsonNode node objectMapper.readTree(data); callback.accept(node.path(result).asText()); } catch (JsonProcessingException e) { // 错误处理 } } Override public void onFailure(EventSource eventSource, Throwable t, Response response) { // 错误处理 } }); }4. 性能优化与最佳实践在实际使用中我们发现几个可以显著提升性能和稳定性的优化点连接池配置OkHttpClient默认连接池可能不适合高并发场景Bean public OkHttpClient okHttpClient() { return new OkHttpClient.Builder() .connectionPool(new ConnectionPool(20, 5, TimeUnit.MINUTES)) .connectTimeout(10, TimeUnit.SECONDS) .readTimeout(30, TimeUnit.SECONDS) .writeTimeout(30, TimeUnit.SECONDS) .build(); }重试机制对于临时性网络问题可以自动重试public class RetryInterceptor implements Interceptor { Override public Response intercept(Chain chain) throws IOException { Request request chain.request(); Response response null; IOException exception null; for (int i 0; i 3; i) { try { response chain.proceed(request); if (response.isSuccessful()) { return response; } } catch (IOException e) { exception e; } try { Thread.sleep(1000 * (i 1)); } catch (InterruptedException e) { Thread.currentThread().interrupt(); throw new IOException(Interrupted during retry, e); } } if (response ! null) { throw new IOException(API request failed after retries: response.code()); } throw exception; } }限流控制防止突发流量导致服务不可用Bean public RateLimiter wenxinRateLimiter() { return RateLimiter.create(5); // 每秒5个请求 } Service public class RateLimitedWenxinService { private final WenxinService wenxinService; private final RateLimiter rateLimiter; public String sendMessageWithRateLimit(ListChatMessage messages) { rateLimiter.acquire(); return wenxinService.sendMessageSync(messages); } }5. 异常处理与监控完善的异常处理能显著提升系统稳定性。我们定义了自定义异常public class WenxinException extends RuntimeException { public enum ErrorType { AUTH_FAILURE, RATE_LIMIT, NETWORK_ERROR, API_ERROR } private final ErrorType errorType; public WenxinException(ErrorType errorType, String message) { super(message); this.errorType errorType; } // 省略getter方法 }同时集成Spring Boot的Actuator进行监控management: endpoints: web: exposure: include: health,metrics,prometheus metrics: tags: application: ${spring.application.name}自定义指标监控API调用Bean public MeterRegistryCustomizerMeterRegistry metricsCommonTags() { return registry - registry.config().commonTags( application, ai-service, region, System.getenv().getOrDefault(REGION, unknown) ); } Service public class MonitoredWenxinService { private final WenxinService delegate; private final Counter successCounter; private final Counter failureCounter; private final Timer apiTimer; public MonitoredWenxinService(WenxinService delegate, MeterRegistry registry) { this.delegate delegate; this.successCounter registry.counter(wenxin.api.calls, status, success); this.failureCounter registry.counter(wenxin.api.calls, status, failure); this.apiTimer registry.timer(wenxin.api.latency); } public String sendMessageWithMonitoring(ListChatMessage messages) { return apiTimer.record(() - { try { String result delegate.sendMessageSync(messages); successCounter.increment(); return result; } catch (Exception e) { failureCounter.increment(); throw e; } }); } }6. 实际应用案例最后分享一个在客服系统中集成的实际案例。我们创建了一个RestController来处理用户咨询RestController RequestMapping(/api/chat) RequiredArgsConstructor public class ChatController { private final WenxinService wenxinService; PostMapping public ResponseEntityChatResponse chat(RequestBody ChatRequest request) { ListChatMessage messages request.getMessages(); String response wenxinService.sendMessageSync(messages); return ResponseEntity.ok(new ChatResponse(response)); } GetMapping(/stream) public SseEmitter streamChat(RequestParam String question) { SseEmitter emitter new SseEmitter(30_000L); ListChatMessage messages List.of( new ChatMessage(user, question) ); wenxinService.sendMessageStream(messages, chunk - { try { emitter.send(SseEmitter.event() .data(chunk) .id(UUID.randomUUID().toString())); } catch (IOException e) { emitter.completeWithError(e); } }); return emitter; } }对于前端集成流式接口可以这样使用const eventSource new EventSource(/api/chat/stream?question encodeURIComponent(question)); let fullResponse ; eventSource.onmessage (event) { fullResponse event.data; updateUI(fullResponse); }; eventSource.onerror () { eventSource.close(); };
