【SpringAI篇01】：10分钟实战SpringAI，快速集成国产大模型API

1. 环境准备与项目创建第一次接触SpringAI的开发者可能会觉得集成大模型很复杂其实用对工具5分钟就能跑通第一个Demo。我去年在电商项目中接入阿里百炼时从零开始到第一个API调用成功只用了8分钟。下面带你完整走一遍流程首先确保你的开发环境满足以下条件JDK 17推荐Amazon Corretto 17Maven 3.6.3IntelliJ IDEA 2023.2社区版即可创建项目时有个小技巧直接在Spring Initializrhttps://start.spring.io勾选这两个核心依赖Spring Web用于构建API接口Lombok简化代码编写然后在pom.xml里添加SpringAI的BOM管理注意这是阿里云百炼适配版dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version0.8.1/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies !-- 添加国产模型适配器 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-ali/artifactId /dependency /dependencies这里有个坑要注意国内镜像源可能没有最新版SpringAI建议在Maven配置里加上Spring的官方仓库repositories repository idspring-snapshots/id urlhttps://repo.spring.io/snapshot/url snapshotsenabledtrue/enabled/snapshots /repository /repositories2. 获取国产大模型API凭证国内主流平台申请API Key比国外方便很多以阿里云百炼为例登录百炼控制台https://bailian.console.aliyun.com进入API密钥管理创建新密钥在模型广场选择qwen-max模型通用性最强实测下来百炼的免费额度足够个人开发使用每月100万tokens免费额度QPS限制5次/秒支持实时流式响应拿到API Key后安全存储有3种推荐方式环境变量最安全export ALI_API_KEYsk-你的密钥Spring Cloud Config分布式配置Vault企业级安全方案3. 配置文件详解application.yml的配置直接决定连接成功率这是我优化过的模板spring: ai: ali: api-key: ${ALI_API_KEY} chat: options: model: qwen-max temperature: 0.7 top-p: 0.9 connection: timeout: 30s read-timeout: 60s关键参数说明temperature控制创造性0-1越大回答越随机top-p核采样阈值影响回答多样性timeout根据网络状况调整跨国访问建议增大遇到连接问题可以开启调试日志logging: level: org.springframework.ai: DEBUG org.springframework.web: DEBUG4. 核心代码实现4.1 智能对话Bean配置在config包下创建ChatConfig.java这是带异常处理的增强版Slf4j Configuration public class ChatConfig { Bean Retryable(maxAttempts3, backoffBackoff(delay1000)) public ChatClient chatClient(AliChatModel chatModel) { return ChatClient.builder(chatModel) .defaultSystem( 你是一位资深技术顾问具备10年Java和AI开发经验。 回答要求 1. 用中文回复 2. 代码示例使用Java 17语法 3. 复杂概念用生活化类比解释 ) .defaultOptions(ChatOptionsBuilder.builder() .withTemperature(0.5f) .build()) .build(); } }这里用了几个实用技巧Retryable自动重试机制网络不稳定时必备多行文本块Java 15特性写系统提示通过Builder模式精细控制参数4.2 带限流的Controller实现ChatController.java中加入熔断保护Slf4j RestController RequestMapping(/ai) RequiredArgsConstructor public class ChatController { private final ChatClient chatClient; // 限流每秒最多5次请求 Bulkhead(namechatApi, typeBulkhead.Type.SEMAPHORE, value5) PostMapping(/chat) public FluxString streamChat( RequestParam String prompt, RequestParam(requiredfalse) Float temperature) { return chatClient.prompt() .user(u - u.text(prompt) .param(temperature, temperature)) .stream() .content(); } }4.3 前端调用示例HTML页面实现流式输出效果script async function chat() { const prompt document.getElementById(input).value; const response await fetch(/ai/chat?prompt${encodeURIComponent(prompt)}); const reader response.body.getReader(); const decoder new TextDecoder(); let result ; while(true) { const {done, value} await reader.read(); if(done) break; result decoder.decode(value); document.getElementById(output).innerHTML result; } } /script5. 生产环境注意事项经过三个月的生产环境验证总结出这些最佳实践性能优化启用响应式编程WebFlux比MVC吞吐量高40%配置连接池HttpClient调优参数spring: ai: ali: connection: pool: max-idle: 20 max-total: 100安全防护接口添加JWT认证敏感参数加密传输启用Spring Security的CSRF保护监控方案Bean public MeterRegistryCustomizerMeterRegistry metrics() { return registry - registry.config().commonTags(application, spring-ai-demo); }异常处理ControllerAdvice public class AiExceptionHandler { ExceptionHandler(AiClientException.class) public ResponseEntityString handleAiError(AiClientException ex) { log.error(AI服务异常: {}, ex.getMessage()); return ResponseEntity.status(502) .body(AI服务暂时不可用: ex.getError().getMessage()); } }调试时如果遇到模型不可用错误可以先检查API Key是否包含特殊字符账号是否完成实名认证区域是否选择正确国内建议用cn-hangzhou