当前位置：首页 > news >正文

Spring AI生产环境 Checklist：20条黄金法则

news 2026/5/21 21:43:22

前言

本文总结Spring AI生产环境部署的最佳实践，涵盖配置、安全、监控、性能四大维度，每条都是实战经验。

一、配置管理（5条）

1. API Key必须通过环境变量注入

# ✅ 推荐spring:ai:openai:api-key:${OPENAI_API_KEY}# ❌ 禁止spring:ai:openai:api-key:sk-xxxxx

2. 超时时间根据场景配置

场景	connect-timeout	read-timeout
简单问答	10s	60s
复杂推理	10s	180s
长文本生成	10s	300s

3. 区分环境配置

# application-dev.ymlspring:ai:openai:base-url:https://api.openai.com/v1# application-prod.ymlspring:ai:openai:base-url:${AI_API_BASE_URL}# 通过环境变量指定

4. 敏感信息加密存储

使用Jasypt或Spring Cloud Config的加密功能：

# 加密encrypt key:mysecret algorithm:PBEWithMD5AndDES input:sk-xxxxx# 配置spring: ai: openai: api-key: ENC(加密后的值)

5. 配置版本控制

所有配置文件必须纳入Git版本控制，但敏感信息通过环境变量注入。

二、安全加固（5条）

6. 提示词注入防护

publicStringsanitizeInput(StringuserInput){// 移除可能的注入内容returnuserInput.replaceAll("\\[system\\]","").replaceAll("\\[inst\\]","").replaceAll("you are a","").trim();}

7. 输出内容审核

@PostFilter("returnObject.length() < 10000")// 限制长度publicStringchat(Stringmessage){Stringresponse=chatClient.prompt().user(sanitizeInput(message)).call().content();// 内容安全检查if(containsSensitiveContent(response)){log.warn("检测到敏感内容");return"抱歉，我无法回答这个问题。";}returnresponse;}

8. API Key定期轮换

建立Key轮换机制，建议每月轮换一次：

# 使用Key别名而非硬编码spring:ai:openai:api-key:${OPENAI_API_KEY_V2}# 定期更新

9. 敏感数据隔离

// 不要把用户隐私数据传给模型publicStringchat(Stringmessage,Useruser){// ❌ 错误Stringprompt="用户"+user.getPhone()+"问:"+message;// ✅ 正确Stringprompt="用户问:"+message;returnchatClient.prompt().user(prompt).call().content();}

10. 请求频率限制

@RateLimiter(name="ai-api",fallbackMethod="fallback")publicStringchat(Stringmessage){returnchatClient.prompt().user(message).call().content();}publicStringfallback(Stringmessage,Exceptione){return"请求过于频繁，请稍后重试。";}

三、可观测性（5条）

11. 结构化日志

log.info("AI调用|请求ID:{}|模型:{}|耗时:{}ms|Token:{}|结果:{}",requestId,modelName,duration,totalTokens,success?"成功":"失败");

12. 关键指标监控

指标	目标	告警阈值
调用成功率	>99%	<95%
P99延迟	<5s	>10s
Token消耗速率	-	日均增长>50%
限流触发频率	<1%	>5%

13. 链路追踪

Spanspan=tracer.nextSpan().name("ai-call");try(Tracer.SpanInScopews=tracer.withSpanInScope(span)){span.tag("model",modelName);span.tag("prompt.length",prompt.length());// 调用逻辑}finally{span.end();}

14. 异常分布统计

Map<String,AtomicInteger>exceptionCounts=newConcurrentHashMap<>();try{returnchatClient.prompt().user(message).call().content();}catch(Exceptione){exceptionCounts.computeIfAbsent(e.getClass().getSimpleName(),k->newAtomicInteger()).incrementAndGet();throwe;}

15. 费用监控看板

按业务线、调用方统计Token消耗，设置月度预算告警。

四、性能优化（5条）

16. 连接池配置

@BeanpublicRestClientCustomizer<HttpComponentsClientHttpRequestFactory>poolCustomizer(){returnbuilder->builder.requestFactory(HttpComponentsClientHttpRequestFactory.class).build();}

17. 语义缓存

@ServicepublicclassSemanticCacheService{@Cacheable(value="semantic",key="#prompt",unless="#result == null")publicStringchat(Stringprompt){returnchatClient.prompt().user(prompt).call().content();}}

18. 异步化处理

@AsyncpublicCompletableFuture<String>chatAsync(Stringmessage){returnCompletableFuture.supplyAsync(()->chatClient.prompt().user(message).call().content());}

19. 模型预热

@PostConstructpublicvoidwarmup(){log.info("开始模型预热...");chatClient.prompt().user("你好").call().content();log.info("模型预热完成");}

20. 分级降级策略

publicStringchatWithDegradation(Stringmessage){try{// 优先用主模型returnprimaryChat(message);}catch(RateLimitExceptione){// 限流时用轻量模型returnlightweightChat(message);}catch(Exceptione){// 异常时返回预设回复returngetFallbackResponse();}}