在实际工程实践中AI 能力的集成正从探索走向落地。无论是 Spring AI 这类框架还是 AI Agent、大模型本地部署等概念开发者面临的核心挑战已不再是“能否接入”而是“如何以工程化的方式稳定、高效、安全地融入现有系统”。本文将以一个典型的 Java Web 项目为背景探讨如何将 AI 能力如大模型对话、内容生成作为服务组件进行集成、开发、测试与部署并重点解决工程实践中常见的配置、依赖管理、异常处理、性能优化及“AI 幻觉”等问题。如果你正在负责或计划开发一个包含 AI 功能的后端服务并希望了解从环境搭建到生产上线的完整路径本文将提供一个可复现的实践指南。1. 理解 AI 工程化的核心挑战与 Spring AI 的定位将 AI 模型尤其是大语言模型LLM集成到企业级应用中远不止调用一个 API 那么简单。它涉及到稳定性、成本、数据安全、响应延迟和结果可控性等多个维度的工程考量。1.1 传统 AI 集成方式的痛点在 Spring AI 等框架出现之前开发者通常需要手动处理以下问题客户端多样性不同模型供应商如 OpenAI、Azure OpenAI、 Anthropic、本地 Ollama的 API 接口、认证方式、请求/响应格式各异代码中充斥着针对特定供应商的硬编码。配置管理复杂API Key、Base URL、超时时间、模型版本等配置散落在代码或配置文件中难以统一管理和切换。缺乏抽象层业务逻辑与具体的 AI 供应商 SDK 强耦合一旦需要更换模型或供应商重构成本高昂。可观测性差对话历史Prompt、令牌Token消耗、响应时间、错误类型等关键指标缺乏统一的收集和监控手段。“AI 幻觉”处理难模型可能生成看似合理但不符合事实或业务规则的输出需要在应用层设计校验和修正机制。1.2 Spring AI 带来的工程化抽象Spring AI 项目旨在为 AI 应用开发提供一套类似于 Spring Data 对数据库、Spring Security 对安全的抽象。它的核心价值在于统一的 API 接口定义了ChatClient、EmbeddingClient、ImageClient等通用接口业务代码只需面向接口编程无需关心底层是 OpenAI 还是本地模型。声明式配置通过application.yml或application.properties文件以简洁的方式配置多个 AI 模型供应商的连接参数。Prompt 模板与管理支持将复杂的提示词Prompt模板化、外部化便于管理和 A/B 测试。可拔插的模型支持通过更换依赖和配置可以轻松地在不同模型间切换甚至实现故障转移。与 Spring 生态无缝集成天然支持 Spring Boot 的自动配置、依赖注入、Actuator 监控等特性。简单来说Spring AI 试图将 AI 模型变成类似数据库或消息队列的“基础设施”让开发者能更专注于业务逻辑的实现。2. 环境准备与项目初始化我们将创建一个基于 Spring Boot 3.x 和 Spring AI 的简单 AI 对话服务。这个服务将提供 RESTful API接收用户问题调用配置的 AI 模型并返回回答。2.1 基础环境要求在开始之前请确保你的开发环境满足以下要求组件要求说明JDK17 或更高版本Spring Boot 3.x 的最低要求。构建工具Maven 3.6 或 Gradle 7.x本文使用 Maven 进行演示。IDEIntelliJ IDEA, VS Code, Eclipse推荐使用支持 Spring Boot 的 IDE。网络可访问所选 AI 模型 API如果使用 OpenAI 等云端服务需确保网络连通性。若使用本地模型如 Ollama则需本地运行模型服务。2.2 创建 Spring Boot 项目使用 Spring Initializr 或 IDE 的创建向导生成一个 Spring Boot 项目。关键依赖选择Spring Web: 用于提供 REST API。Spring AI OpenAI或Spring AI Ollama: 根据你计划使用的模型选择。这里我们以 OpenAI 和 Ollama 为例展示多模型配置。Lombok(可选): 简化 POJO 类的编写。Spring Boot Actuator(可选): 用于监控端点。对应的pom.xml依赖项如下?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.5/version !-- 使用当前稳定版本 -- relativePath/ /parent groupIdcom.example/groupId artifactIdai-engineering-demo/artifactId version0.0.1-SNAPSHOT/version nameai-engineering-demo/name descriptionDemo project for AI Engineering with Spring AI/description properties java.version17/java.version spring-ai.version0.8.1/spring-ai.version !-- 使用稳定的 Spring AI 版本 -- /properties dependencies !-- Spring Boot Web -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- Spring AI OpenAI Starter -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId version${spring-ai.version}/version /dependency !-- Spring AI Ollama Starter (用于连接本地模型) -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-ollama-spring-boot-starter/artifactId version${spring-ai.version}/version /dependency !-- Lombok -- dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency !-- Spring Boot Actuator (监控) -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-actuator/artifactId /dependency !-- 测试 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId configuration excludes exclude groupIdorg.projectlombok/groupId artifactIdlombok/artifactId /exclude /excludes /configuration /plugin /plugins /build /project注意Spring AI 版本迭代较快请根据 官方文档 确认当前稳定版本。同时引入多个模型依赖时需要注意它们之间是否存在冲突通常 Spring AI 的 starters 设计良好可以共存。3. 配置多模型连接与核心服务实现配置是 Spring AI 工程化的关键。我们将配置两个 AI 模型客户端一个连接远程的 OpenAI API另一个连接本地运行的 Ollama 服务。3.1 应用配置文件详解在src/main/resources/application.yml中进行如下配置server: port: 8080 spring: application: name: ai-engineering-demo # Spring AI 配置 ai: # OpenAI 配置 (例如使用 GPT-3.5/4) openai: api-key: ${OPENAI_API_KEY:} # 强烈建议从环境变量读取不要硬编码 base-url: https://api.openai.com/v1 # 默认值如果是 Azure OpenAI需修改 chat: options: model: gpt-3.5-turbo # 指定使用的模型 temperature: 0.7 # 创造性0-2之间越高越随机 max-tokens: 500 # 限制最大输出token数控制成本 # Ollama 配置 (连接本地模型如 llama2, qwen, mistral 等) ollama: base-url: http://localhost:11434 # Ollama 服务默认地址 chat: options: model: llama2 # 本地运行的模型名称 temperature: 0.8 num-predict: 300 # Ollama 中类似 max-tokens 的参数 # Actuator 端点暴露用于健康检查等 management: endpoints: web: exposure: include: health,info,metrics endpoint: health: show-details: always关键配置解释spring.ai.openai.api-key: 这是访问 OpenAI 服务的凭证。绝对不要将其直接写入代码或提交到版本控制系统。应通过环境变量 (OPENAI_API_KEY) 或配置中心注入。spring.ai.openai.base-url: 默认为 OpenAI 官方端点。如果你使用 Azure OpenAI 或其他兼容 OpenAI API 的代理服务需要修改此值。model: 明确指定要使用的模型名称。这是控制成本和能力的关键参数。temperature: 控制生成文本的随机性。对于需要确定性答案的问答场景可以调低如 0.1对于创意生成可以调高。max-tokens/num-predict: 限制单次响应的长度是控制单次调用成本对于按 token 计费的 API和防止响应过长的有效手段。3.2 实现多模型对话服务Spring AI 会自动根据配置创建ChatClientBean。默认情况下它会使用spring.ai.openai的配置。为了能动态选择或同时使用多个模型我们需要进行一些封装。首先定义一个统一的请求和响应对象package com.example.aiengineeringdemo.dto; import lombok.Data; Data public class ChatRequest { private String message; private String modelProvider; // 用于指定使用哪个提供商如 openai, ollama } Data public class ChatResponse { private String provider; private String answer; private Long tokenUsage; // 可选记录token消耗 }然后创建一个服务层用于路由请求到不同的ChatClientpackage com.example.aiengineeringdemo.service; import com.example.aiengineeringdemo.dto.ChatRequest; import com.example.aiengineeringdemo.dto.ChatResponse; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.ai.chat.client.ChatClient; import org.springframework.ai.chat.model.ChatResponse; import org.springframework.ai.chat.prompt.Prompt; import org.springframework.stereotype.Service; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; Service Slf4j RequiredArgsConstructor public class AIChatService { // 使用 Map 来存储不同供应商的 ChatClient private final MapString, ChatClient chatClientMap; // 构造器注入Spring 会自动将名为 openAiChatClient 和 ollamaChatClient 的 Bean 放入 Map public AIChatService(MapString, ChatClient chatClientMap) { this.chatClientMap chatClientMap; } public ChatResponse chat(ChatRequest request) { String provider request.getModelProvider(); if (provider null || provider.isEmpty()) { provider openai; // 默认提供商 } ChatClient client chatClientMap.get(provider ChatClient); // Bean 名称规则 if (client null) { throw new IllegalArgumentException(Unsupported AI model provider: provider); } log.info(Using AI provider: {} to process query: {}, provider, request.getMessage()); long startTime System.currentTimeMillis(); // 调用 AI 模型 ChatResponse aiResponse client.prompt(new Prompt(request.getMessage())).call().chatResponse(); long endTime System.currentTimeMillis(); String answer aiResponse.getResult().getOutput().getContent(); ChatResponse response new ChatResponse(); response.setProvider(provider); response.setAnswer(answer); // 注意不同客户端的响应中 Token 计数方式可能不同这里简化处理 // 实际可以从 aiResponse.getMetadata() 或 aiResponse.getUsage() 中获取 // response.setTokenUsage(aiResponse.getUsage().getTotalTokens()); log.info(AI provider [{}] response time: {} ms, provider, (endTime - startTime)); return response; } }为了让 Spring 能正确注入多个ChatClient我们需要一个配置类来显式定义它们package com.example.aiengineeringdemo.config; import org.springframework.ai.chat.client.ChatClient; import org.springframework.ai.openai.OpenAiChatClient; import org.springframework.ai.ollama.OllamaChatClient; import org.springframework.ai.ollama.api.OllamaApi; import org.springframework.beans.factory.annotation.Qualifier; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Primary; Configuration public class AIConfig { // 默认的 ChatClient通常指向 OpenAI Bean Primary // 标记为主要 Bean当不指定名称注入时会使用这个 public ChatClient openAiChatClient(OpenAiChatClient openAiChatClient) { // 这里直接返回 Spring AI 自动配置的 OpenAiChatClient // 我们也可以在这里进行一些包装比如添加拦截器记录日志 return ChatClient.builder(openAiChatClient) //.defaultSystem(你是一个有帮助的助手。) // 可以设置默认系统指令 .build(); } // 另一个 ChatClient指向 Ollama Bean public ChatClient ollamaChatClient(OllamaChatClient ollamaChatClient) { return ChatClient.builder(ollamaChatClient).build(); } }3.3 提供 RESTful API 控制器最后创建一个简单的控制器来暴露服务package com.example.aiengineeringdemo.controller; import com.example.aiengineeringdemo.dto.ChatRequest; import com.example.aiengineeringdemo.dto.ChatResponse; import com.example.aiengineeringdemo.service.AIChatService; import lombok.RequiredArgsConstructor; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; RestController RequestMapping(/api/ai) RequiredArgsConstructor public class AIChatController { private final AIChatService aiChatService; PostMapping(/chat) public ChatResponse chat(RequestBody ChatRequest request) { return aiChatService.chat(request); } }4. 运行验证与基础测试完成代码编写后我们需要验证服务是否能够正常运行并能正确调用不同的 AI 模型。4.1 启动准备与检查对于 OpenAI确保环境变量OPENAI_API_KEY已正确设置。# Linux/Mac export OPENAI_API_KEYyour-api-key-here # Windows (CMD) set OPENAI_API_KEYyour-api-key-here # Windows (PowerShell) $env:OPENAI_API_KEYyour-api-key-here对于 Ollama确保已在本地安装并启动了 Ollama并且拉取了所需的模型如llama2。# 安装 Ollama (详见官网) # 拉取模型 ollama pull llama2 # 启动 Ollama 服务通常安装后会自动运行启动 Spring Boot 应用mvn spring-boot:run或直接在 IDE 中运行AiEngineeringDemoApplication主类。4.2 使用 API 测试工具进行验证应用启动后使用curl、Postman 或任何 HTTP 客户端进行测试。测试 OpenAI 接口curl -X POST http://localhost:8080/api/ai/chat \ -H Content-Type: application/json \ -d { message: 请用一句话解释什么是微服务架构。, modelProvider: openai }预期会收到一个包含 GPT-3.5-turbo 模型回答的 JSON 响应。测试 Ollama 接口curl -X POST http://localhost:8080/api/ai/chat \ -H Content-Type: application/json \ -d { message: 请用一句话解释什么是微服务架构。, modelProvider: ollama }预期会收到一个包含本地 Llama2 模型回答的 JSON 响应。4.3 验证 Actuator 健康检查Spring Boot Actuator 提供了应用和组件健康状态端点这对于运维至关重要。curl http://localhost:8080/actuator/health如果 OpenAI 或 Ollama 连接失败对应的健康指示器可能会显示DOWN状态。你需要检查配置、网络和模型服务状态。5. 工程实践中的关键问题与排查将 AI 集成到生产环境必然会遇到各种问题。以下是几个典型场景的排查路径。5.1 连接与认证失败这是最常见的问题通常表现为401 Unauthorized、403 Forbidden或连接超时。问题现象可能原因检查方式处理建议调用 OpenAI 返回 401API Key 错误、过期或未设置。1. 检查环境变量OPENAI_API_KEY是否已设置且正确。2. 在应用日志中搜索Invalid API key或Incorrect API key。3. 登录 OpenAI 平台检查 API Key 状态和额度。1. 重新生成 API Key 并更新环境变量。2. 确保配置的base-url与 API Key 所属区域匹配如 Azure OpenAI。调用 Ollama 连接被拒绝Ollama 服务未启动或端口不对。1. 执行ollama serve查看服务状态。2. 检查application.yml中spring.ai.ollama.base-url的端口默认 11434。3. 使用curl http://localhost:11434/api/tags测试 Ollama API 是否可达。1. 启动 Ollama 服务。2. 确认防火墙或安全组放行了对应端口。3. 如果 Ollama 运行在容器或远程需修改base-url。请求超时网络不稳定、模型响应慢或配置超时时间太短。1. 查看应用日志中的超时异常栈。2. 检查 Spring AI 或底层 HTTP 客户端如 RestTemplate的超时配置。1. 适当增加超时配置Spring AI 目前主要通过底层客户端配置如spring.ai.openai.client.*属性。2. 对于慢模型考虑异步调用或设置更合理的客户端超时。5.2 处理“AI 幻觉”与输出不可控大模型可能生成错误或不符合要求的内容。现象模型回答的事实错误、编造信息、或未遵循指令格式。应对策略优化 Prompt 工程在系统指令System Message中明确约束。例如在AIConfig中为ChatClient设置defaultSystem。return ChatClient.builder(openAiChatClient) .defaultSystem(你是一个严谨的编程助手。对于不确定的信息请明确回答‘我不知道’。回答请尽量简洁。) .build();后处理校验在服务层 (AIChatService) 对模型的输出进行校验。例如使用正则表达式检查是否包含特定格式或调用另一个校验逻辑。public ChatResponse chat(ChatRequest request) { // ... 调用 AI ... String rawAnswer aiResponse.getResult().getOutput().getContent(); // 后处理例如检查是否以“答案是”开头如果不是进行修正或标记 if (!rawAnswer.startsWith(答案是)) { rawAnswer 格式修正答案是 rawAnswer; log.warn(模型输出格式不符合预期已进行修正。); } // ... 构建响应 ... }使用有“约束生成”能力的模型或框架某些模型或外部库支持 JSON 格式、正则表达式约束的输出。5.3 性能与成本优化AI API 调用通常是应用中最耗时的操作之一且可能按 Token 计费。常见优化点缓存对常见、确定性高的查询结果进行缓存。例如使用 Spring Cache 注解。Cacheable(value aiResponses, key #request.message #request.modelProvider) public ChatResponse chat(ChatRequest request) { // ... 原有逻辑 ... }注意缓存 AI 响应需谨慎需评估内容的时效性和用户个性化需求。异步调用对于非实时性要求高的场景使用Async将 AI 调用改为异步避免阻塞主线程。限制输入/输出长度严格在 Prompt 中和配置参数 (max-tokens) 里限制文本长度这是控制成本和响应时间最直接的手段。监控与告警通过 Actuator Metrics 或自定义 AOP 切面监控每次 AI 调用的耗时、Token 消耗和成功率。设置阈值告警。5.4 依赖冲突与版本管理Spring AI 生态较新版本迭代快容易与其他依赖产生冲突。排查步骤确认 Spring Boot 与 Spring AI 版本兼容性务必查阅 Spring AI 官方文档 的版本说明。使用 Maven 依赖树分析冲突mvn dependency:tree -Dincludesorg.springframework.ai检查是否有多个不同版本的 Spring AI 组件被引入。常见冲突点不同 AI Starter 可能依赖了不同版本的底层 HTTP 客户端如 Apache HttpClient, OkHttp。如果出现NoSuchMethodError或ClassNotFoundException通常需要统一版本或在pom.xml中排除冲突的传递依赖。6. 从学习环境到生产环境的进阶考量在学习和开发环境跑通只是第一步。要上线生产还需要考虑更多因素。6.1 配置外部化与安全密钥管理API Key 等敏感信息必须从代码中剥离。使用环境变量、云厂商的密钥管理服务如 AWS Secrets Manager, Azure Key Vault或专业的配置中心如 Apollo, Nacos。配置 Profile使用 Spring Boot 的application-{profile}.yml为不同环境dev, test, prod配置不同的模型参数、超时时间和降级策略。6.2 可观测性与监控日志标准化在AIChatService中记录每次调用的提供商、输入长度、输出长度、耗时和状态。便于后续分析和审计。集成 Micrometer通过 Spring Boot Actuator 和 Micrometer将 AI 调用的关键指标次数、耗时、错误率暴露给 Prometheus 和 Grafana。分布式追踪在微服务架构中确保 AI 调用链被集成到 Sleuth/Zipkin 或 Jaeger 中以查看其在全局链路中的影响。6.3 容错与降级策略生产环境不能因为一个外部 AI 服务不可用而导致核心业务瘫痪。客户端重试为ChatClient配置重试机制Spring Retry。故障转移实现更智能的AIChatService当主用模型如 OpenAI失败或超时时自动切换到备用模型如 Ollama 或其他云端服务。熔断与限流使用 Resilience4j 或 Sentinel 对 AI 服务调用进行熔断和限流防止因 AI 服务响应慢而拖垮整个应用。兜底策略当所有 AI 服务都不可用时返回预设的兜底答案或引导用户使用其他功能。6.4 模型版本管理与 A/B 测试模型版本化在配置中明确指定模型名称和版本如gpt-4-1106-preview而不是使用别名如gpt-4避免因模型默认版本升级引入不可预知的变化。流量染色与 A/B 测试可以通过在请求头或用户标识中注入实验标记将流量导向不同的模型或 Prompt 版本从而对比效果。将 AI 能力工程化本质上是将其视为一个具有特殊性的外部服务进行集成和管理。Spring AI 提供了优秀的抽象层来简化开发但生产环境的稳定性、安全性、成本和效果可控性仍然依赖于开发者对配置、监控、容错和架构的深入理解与实践。从配置一个可用的客户端开始逐步构建监控告警、实现容错降级、优化成本与性能最终使其成为业务系统中一个可靠、可控的组成部分这才是 AI 工程实践的核心路径。下一步你可以探索更复杂的场景如流式响应Streaming、函数调用Function Calling、基于向量数据库的检索增强生成RAG等这些 Spring AI 也提供了相应的支持。