1. 项目概述SpringAI作为当前企业级AI应用开发的热门框架正在改变传统Java开发者构建智能应用的方式。作为一名经历过三次SpringAI环境搭建的老手我深刻理解新手在配置过程中可能遇到的各种坑。本文将基于Spring Boot 3.2和JDK 17环境带你完整走通从零开始的环境搭建流程。不同于官方文档的简略说明这里会包含我在多个实际项目中总结的环境配置技巧。比如如何解决国内开发者常见的依赖下载问题不同操作系统下的环境变量配置差异以及IDE选择对开发体验的影响等实战经验。这些细节往往决定了你能否在半小时内顺利完成环境搭建而不是浪费一整天在环境问题上。2. 环境准备2.1 硬件与基础软件要求开发机器建议配置内存最低8GB推荐16GB以上AI模型加载较耗内存存储至少20GB可用空间用于存放依赖包和模型文件操作系统Windows 10/macOS 10.15/主流Linux发行版注意虽然SpringAI支持在低配环境运行但处理复杂AI任务时性能会明显下降。如果需要进行模型微调建议使用32GB内存及以上配置。2.2 JDK安装与配置必须使用JDK 17或更高版本# 检查Java版本 java -version如果未安装或版本不符推荐通过SDKMAN管理多版本JDK# 安装SDKMAN curl -s https://get.sdkman.io | bash source $HOME/.sdkman/bin/sdkman-init.sh # 安装JDK 17 sdk install java 17.0.10-tem配置JAVA_HOME环境变量以macOS/Linux为例# 确定JDK安装路径 /usr/libexec/java_home -v 17 # 添加到环境变量 echo export JAVA_HOME$(/usr/libexec/java_home -v 17) ~/.zshrc echo export PATH$JAVA_HOME/bin:$PATH ~/.zshrc source ~/.zshrc2.3 开发工具选择推荐IDE组合IntelliJ IDEA Ultimate最佳Spring支持VS Code Java扩展包轻量级选择必备插件Spring Boot ToolsLombok减少样板代码AI Assistant可选提供代码建议3. 项目初始化3.1 使用Spring Initializr创建项目通过start.spring.io生成项目时关键配置Project: Maven ProjectLanguage: JavaSpring Boot: 3.2.5稳定版Dependencies:Spring WebSpring AILombokDevTools或者使用curl快速创建curl https://start.spring.io/starter.tgz \ -d typemaven-project \ -d languagejava \ -d bootVersion3.2.5 \ -d groupIdcom.example \ -d artifactIdspringai-demo \ -d namespringai-demo \ -d dependenciesweb,ai,lombok,devtools \ -d javaVersion17 \ | tar -xzvf -3.2 解决国内依赖问题配置阿里云镜像加速依赖下载!-- 在pom.xml中添加 -- repositories repository idaliyun/id urlhttps://maven.aliyun.com/repository/public/url /repository /repositories对于Spring AI特有的依赖可能需要额外配置repository idspring-snapshots/id urlhttps://repo.spring.io/snapshot/url snapshotsenabledtrue/enabled/snapshots /repository4. 核心配置详解4.1 应用配置文件application.properties基础配置# 服务端口 server.port8080 # Spring AI基础配置 spring.ai.openai.api-key${OPENAI_API_KEY} spring.ai.openai.chat.options.modelgpt-3.5-turbo spring.ai.openai.chat.options.temperature0.7 # 开启Actuator端点 management.endpoints.web.exposure.includehealth,info,env更推荐使用application.yml格式spring: ai: openai: api-key: ${OPENAI_API_KEY} chat: options: model: gpt-3.5-turbo temperature: 0.74.2 环境变量管理安全提示永远不要将API密钥硬编码在代码中推荐做法开发环境使用.env文件配合IDE插件# .env文件示例 OPENAI_API_KEYsk-your-key-here生产环境使用配置中心或Kubernetes SecretsIntelliJ配置环境变量Run → Edit Configurations → Environment variables添加OPENAI_API_KEYyour_key4.3 连接不同AI提供商除了OpenAISpringAI还支持多种AI服务# Azure OpenAI配置示例 spring: ai: azure: openai: api-key: ${AZURE_OPENAI_API_KEY} endpoint: https://your-resource-name.openai.azure.com chat: options: deployment-name: gpt-35-turbo5. 验证环境5.1 创建测试ControllerRestController RequiredArgsConstructor public class AiController { private final ChatClient chatClient; GetMapping(/ask) public String ask(RequestParam String question) { return chatClient.call(question); } }5.2 启动应用检查正常启动日志应包含Started SpringaiDemoApplication in 2.305 seconds Initialized Spring AI ChatClient for OpenAi访问健康检查端点http://localhost:8080/actuator/health5.3 常见启动问题排查Bean创建失败检查application.properties配置是否正确确认环境变量已正确加载连接超时spring: ai: openai: connect-timeout30s read-timeout60s内存不足 在启动配置中添加VM参数-Xmx2G -XX:MaxRAMPercentage706. 高级配置技巧6.1 多模型切换策略使用Qualifier注入不同模型Bean Qualifier(openai) public ChatClient openAiChatClient(OpenAiChatClient openAiChatClient) { return openAiChatClient; } Bean Qualifier(azure) public ChatClient azureChatClient(AzureOpenAiChatClient azureChatClient) { return azureChatClient; }6.2 自定义Prompt模板创建resources/prompts/qa-prompt.stAnswer the following question in a professional tone: {question}Java中使用Value(classpath:/prompts/qa-prompt.st) private Resource promptTemplate; public String generateAnswer(String question) { PromptTemplate template new PromptTemplate(promptTemplate); Prompt prompt template.create(Map.of(question, question)); return chatClient.call(prompt.getContents()); }6.3 性能监控配置添加Micrometer监控dependency groupIdio.micrometer/groupId artifactIdmicrometer-core/artifactId /dependency配置Prometheus端点management: endpoints: web: exposure: include: prometheus metrics: tags: application: ${spring.application.name}7. 生产环境建议7.1 安全加固措施启用Spring SecurityConfiguration EnableWebSecurity public class SecurityConfig { Bean public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception { http .authorizeHttpRequests(auth - auth .requestMatchers(/ask).authenticated() .anyRequest().permitAll() ) .httpBasic(Customizer.withDefaults()); return http.build(); } }配置HTTPSserver.ssl.enabledtrue server.ssl.key-store-typePKCS12 server.ssl.key-storeclasspath:keystore.p12 server.ssl.key-store-passwordchangeit7.2 性能优化连接池配置spring: ai: openai: connection-pool: max-idle: 10 max-total: 50响应缓存Cacheable(aiResponses) public String getCachedResponse(String prompt) { return chatClient.call(prompt); }7.3 容器化部署Dockerfile示例FROM eclipse-temurin:17-jdk-jammy WORKDIR /app COPY target/*.jar app.jar ENTRYPOINT [java,-jar,app.jar]构建命令./mvnw clean package docker build -t springai-demo . docker run -p 8080:8080 -e OPENAI_API_KEYyour_key springai-demo8. 开发工作流优化8.1 自动化测试配置集成测试示例SpringBootTest class AiApplicationTests { Autowired private ChatClient chatClient; Test void contextLoads() { assertNotNull(chatClient); } Test void testSimpleQuery() { String response chatClient.call(Hello); assertTrue(response.length() 0); } }Mock测试方案TestConfiguration class TestConfig { Bean Primary public ChatClient mockChatClient() { return prompt - Mocked response; } }8.2 持续集成配置GitHub Actions示例name: Java CI on: [push] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Set up JDK 17 uses: actions/setup-javav3 with: java-version: 17 distribution: temurin - name: Build with Maven run: ./mvnw -B package --file pom.xml - name: Test run: ./mvnw test8.3 本地开发技巧热部署配置spring.devtools.restart.enabledtrue spring.devtools.livereload.enabledtrue快速测试端点http :8080/ask questionSpringAI是什么日志级别调整logging: level: org.springframework.ai: DEBUG com.example: INFO9. 常见问题解决方案9.1 依赖冲突解决查看依赖树./mvnw dependency:tree排除冲突依赖示例dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId exclusions exclusion groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId /exclusion /exclusions /dependency9.2 连接问题诊断测试API连通性SpringBootTest class ConnectivityTest { Value(${spring.ai.openai.api-key}) private String apiKey; Test void testOpenAIConnection() throws IOException { HttpRequest request HttpRequest.newBuilder() .uri(URI.create(https://api.openai.com/v1/models)) .header(Authorization, Bearer apiKey) .GET() .build(); HttpResponseString response HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); assertEquals(200, response.statusCode()); } }9.3 性能问题排查使用Arthas进行诊断# 启动Arthas java -jar arthas-boot.jar # 监控方法调用 watch org.springframework.ai.client.AiClient call {params, returnObj} -x 3JVM调优参数-XX:UseG1GC -XX:MaxGCPauseMillis200 -XX:ParallelGCThreads4
