SpringBoot整合Spring AI对接大模型实战
1. SpringBoot与Spring AI整合概述在当今AI技术快速发展的背景下将大模型能力集成到企业应用中已成为提升业务智能化水平的关键路径。作为Java生态中最流行的框架之一SpringBoot以其简洁的配置和强大的扩展能力成为对接AI服务的理想选择。而Spring AI作为Spring官方推出的AI集成框架为开发者提供了统一的操作接口极大简化了不同AI服务的接入过程。这次我们要探讨的是如何在SpringBoot项目中整合Spring AI来对接大模型服务。以阿里云百炼平台为例这种整合可以让我们快速获得大模型的文本生成、问答对话等能力同时保持SpringBoot应用的原有架构风格。不同于直接调用原生API的方式通过Spring AI的抽象层我们可以用更符合Spring习惯的方式来操作大模型还能享受到依赖注入、自动配置等Spring特性带来的便利。2. 环境准备与项目初始化2.1 基础环境要求在开始编码前需要确保开发环境满足以下要求JDK 17或更高版本Spring AI对Java新特性有依赖Spring Boot 3.x推荐3.4.0及以上Maven 3.6或Gradle 7.x本文以Maven为例一个可用的IDEIntelliJ IDEA或Eclipse等提示如果团队仍在使用JDK 8或11需要考虑升级或寻找兼容方案因为Spring AI的部分功能依赖JDK 17引入的新API。2.2 创建SpringBoot项目可以通过以下两种方式初始化项目使用Spring Initializr 访问https://start.spring.io/选择Project: MavenLanguage: JavaSpring Boot: 3.4.0 依赖项添加Spring WebLombok可选但推荐通过IDE创建 在IntelliJ IDEA中File → New → Project → Spring Initializr选择上述相同配置生成项目后建议验证基础环境是否正常工作mvn spring-boot:run访问http://localhost:8080应能看到Whitelabel Error Page因为我们还没添加任何控制器这表示基础项目已正常启动。3. 添加Spring AI依赖与配置3.1 引入Spring AI Alibaba Starter在pom.xml中添加以下依赖dependencies !-- Spring AI Alibaba核心依赖 -- dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-starter-dashscope/artifactId version1.0.0.2/version /dependency !-- Web支持 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId version3.4.0/version exclusions exclusion groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-logging/artifactId /exclusion /exclusions /dependency !-- 使用Log4j2替代默认Logback -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-log4j2/artifactId version3.4.0/version /dependency !-- 工具类 -- dependency groupIdorg.apache.commons/groupId artifactIdcommons-lang3/artifactId version3.14.0/version /dependency /dependencies3.2 配置API密钥与应用ID在application.yml中添加配置spring: ai: dashscope: agent: app-id: ${APP_ID} # 从环境变量读取或直接填写 api-key: ${DASHSCOPE_API_KEY} # API密钥 # workspace-id: ${WORKSPACE_ID} # 子业务空间ID非必须 server: port: 9000 # 避免端口冲突建议通过环境变量配置敏感信息export DASHSCOPE_API_KEYyour_api_key export APP_IDyour_app_id # export WORKSPACE_IDyour_workspace_id # 如果需要4. 核心代码实现4.1 非流式调用实现创建控制器处理常规请求RestController RequestMapping(/ai) Slf4j public class BailianAgentController { private final DashScopeAgent agent; Value(${spring.ai.dashscope.agent.app-id}) private String appId; public BailianAgentController(DashScopeAgentApi dashscopeAgentApi) { this.agent new DashScopeAgent(dashscopeAgentApi); } GetMapping(/bailian/agent/call) public String call(RequestParam(defaultValue 如何使用SDK调用百炼应用?) String message) { ChatResponse response agent.call( new Prompt(message, DashScopeAgentOptions.builder() .withAppId(appId) .build())); if (response null || response.getResult() null) { log.error(响应为空); return 请求失败; } AssistantMessage output response.getResult().getOutput(); String content output.getText(); // 处理元数据 DashScopeAgentResponseOutput metadata (DashScopeAgentResponseOutput) output.getMetadata().get(output); if (metadata.docReferences() ! null) { metadata.docReferences().forEach(ref - log.info(参考文档: {}, ref)); } return content; } }4.2 流式调用实现对于需要实时响应的场景可以使用流式调用RestController RequestMapping(/ai) Slf4j public class BailianAgentStreamController { private final DashScopeAgent agent; Value(${spring.ai.dashscope.agent.app-id}) private String appId; public BailianAgentStreamController(DashScopeAgentApi dashscopeAgentApi) { this.agent new DashScopeAgent(dashscopeAgentApi, DashScopeAgentOptions.builder() .withSessionId(custom_session_id) .withIncrementalOutput(true) .build()); } GetMapping(value /bailian/agent/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString stream(RequestParam(defaultValue 你好) String message) { return agent.stream( new Prompt(message, DashScopeAgentOptions.builder() .withAppId(appId) .build())) .map(response - { if (response null || response.getResult() null) { return 数据错误; } return response.getResult().getOutput().getText(); }) .onErrorResume(e - { log.error(流式调用异常, e); return Flux.just(服务异常: e.getMessage()); }); } }5. 应用测试与调试5.1 启动类配置确保有标准的SpringBoot启动类SpringBootApplication public class AiApplication { public static void main(String[] args) { SpringApplication.run(AiApplication.class, args); } }5.2 测试方法非流式接口测试curl http://localhost:9000/ai/bailian/agent/call?message如何快速入门SpringBoot?流式接口测试 使用支持SSE的客户端如Postman访问GET http://localhost:9000/ai/bailian/agent/stream?message介绍一下阿里云百炼或使用前端EventSourceconst eventSource new EventSource(/ai/bailian/agent/stream?message你好); eventSource.onmessage (e) console.log(e.data);5.3 常见问题排查认证失败检查API_KEY是否正确确认环境变量已正确加载查看网络是否能够访问阿里云API端点流式响应不完整检查客户端是否支持SSE确认没有超时设置过短验证网络稳定性性能优化建议对于高频调用考虑添加缓存层使用连接池管理API调用合理设置超时参数6. 进阶配置与优化6.1 自定义配置类对于更复杂的场景可以创建自定义配置Configuration public class AiConfig { Bean public DashScopeAgentOptions agentOptions( Value(${spring.ai.dashscope.agent.app-id}) String appId) { return DashScopeAgentOptions.builder() .withAppId(appId) .withSessionId(UUID.randomUUID().toString()) .withMaxTokens(1000) .build(); } Bean public DashScopeAgent dashScopeAgent( DashScopeAgentApi api, DashScopeAgentOptions options) { return new DashScopeAgent(api, options); } }6.2 异常处理增强统一处理AI服务异常RestControllerAdvice public class AiExceptionHandler { ExceptionHandler(DashScopeApiException.class) public ResponseEntityString handleApiException(DashScopeApiException e) { return ResponseEntity.status(502) .body(AI服务异常: e.getMessage()); } ExceptionHandler(TimeoutException.class) public ResponseEntityString handleTimeout(TimeoutException e) { return ResponseEntity.status(504) .body(请求超时: e.getMessage()); } }6.3 性能监控集成Micrometer监控指标Configuration public class MetricsConfig { Bean public TimedAspect timedAspect(MeterRegistry registry) { return new TimedAspect(registry); } } // 在控制器方法上添加监控 GetMapping(/call) Timed(value ai.call.latency, description AI调用延迟) public String call(...) { ... }7. 实际应用中的经验分享在实际项目集成过程中有几个关键点值得特别注意会话管理对于需要保持上下文的对话务必维护好sessionId可以考虑将会话信息存储在Redis等缓存中注意大模型的上下文长度限制限流与降级Bean public RateLimiter aiRateLimiter() { return RateLimiter.create(10); // 每秒10个请求 } GetMapping(/call) public String call(..., RateLimiter limiter) { if (!limiter.tryAcquire()) { throw new RuntimeException(请求过于频繁); } // ... }Prompt工程实践设计清晰明确的提示词对于专业领域提供必要的上下文通过少量示例(few-shot)引导模型输出格式安全建议永远不要在前端暴露API_KEY对用户输入进行必要的过滤和转义考虑添加内容审核层通过SpringBoot整合Spring AI对接大模型我们不仅获得了先进AI能力还能保持Spring生态的开发体验。这种架构特别适合需要快速迭代AI功能的业务场景从原型开发到生产部署都能保持高效的开发节奏。
