Spring AI 框架实战：Java 后端集成大模型的架构设计与工程落地

处理Spring AI 框架实战：Java 后端集成大模型的架构设计与工程落地这类问题时，先确认目标场景，再按步骤核对配置或玩法细节。

Spring AI 框架实战：Java 后端集成大模型的架构设计与工程落地

一、API 调用之外的工程挑战：Java 应用集成 LLM 的真实痛点

当团队决定在 Java 后端系统中集成大语言模型时，最常见的起点是直接用 RestTemplate 或 WebClient 调用 OpenAI 的 HTTP API。这种做法在 Demo 阶段看似可行，但一旦进入生产环境，问题便接踵而至：不同模型供应商的 API 格式各异（OpenAI、Azure OpenAI、Anthropic、国内模型），切换供应商需要重写调用逻辑；流式响应（SSE）的处理缺乏统一抽象；Prompt 模板散落在业务代码中，难以版本管理和 A/B 测试；调用失败时的重试与降级策略缺失，导致级联故障。

Spring AI 正是为了解决这些工程痛点而诞生的框架。它提供了一套统一的模型调用抽象、Prompt 管理机制、向量存储接口和 RAG（检索增强生成）管道，让 Java 开发者能够以 Spring 风格的方式集成大模型，而非在业务代码中堆砌 HTTP 调用。

下文会从架构视角出发，完整演示 Spring AI 在生产环境中的集成方案，覆盖模型调用、Prompt 管理、RAG 管道和可观测性四个核心环节。

二、从 ChatModel 到 VectorStore：Spring AI 的核心抽象与协作机制

Spring AI 的架构设计遵循 Spring 的一贯哲学：通过接口抽象屏蔽实现差异，通过自动装配降低集成成本。

flowchart TBsubgraph 应用层A[业务服务] --> B[ChatClient]A --> C[PromptTemplate]A --> D[RAG 管道]endsubgraph Spring AI 核心抽象B --> E[ChatModel 接口]C --> F[Prompt 管理]D --> G[DocumentReader]D --> H[DocumentTransformer]D --> I[VectorStore 接口]endsubgraph 模型实现E --> J[OpenAI ChatModel]E --> K[Azure OpenAI]E --> L[Ollama ChatModel]E --> M[其他供应商]endsubgraph 向量存储实现I --> N[PgVector]I --> O[Chroma]I --> P[Milvus]I --> Q[Redis]endsubgraph 可观测性B --> R[Micrometer 指标]E --> S[Token 用量统计]B --> T[OpenTelemetry Tracing]end

ChatModel 接口是 Spring AI 的核心抽象，定义了与 LLM 交互的统一契约。无论是 OpenAI、Azure OpenAI 还是本地部署的 Ollama，都通过实现 ChatModel 接口来适配。应用代码只依赖接口，切换模型供应商只需修改配置，无需改动业务逻辑。

PromptTemplate 提供了参数化的 Prompt 管理能力。Prompt 不再硬编码在 Java 代码中，而是以模板文件的形式外部化管理，支持变量替换和条件逻辑。这使得 Prompt 的版本管理、A/B 测试和跨团队协作成为可能。

VectorStore 接口统一了向量存储的访问方式。无论是 PgVector、Chroma 还是 Milvus，应用代码都通过 VectorStore 接口进行向量写入和相似度检索，底层实现可随时替换。

三、生产级 Spring AI 集成：从模型调用到 RAG 管道

下面给出一个完整的生产级 Spring AI 集成方案，包含模型调用、Prompt 管理、RAG 管道和异常处理。

Maven 依赖配置：

org.springframework.aispring-ai-bom1.0.0pomimportorg.springframework.aispring-ai-openai-spring-boot-starterorg.springframework.aispring-ai-pgvector-store-spring-boot-starter

应用配置：

spring:ai:openai:api-key: ${OPENAI_API_KEY}base-url: ${OPENAI_BASE_URL:https://api.openai.com}chat:options:model: gpt-4otemperature: 0.7max-tokens: 2048vectorstore:pgvector:index-type: HNSWdistance-type: COSINEdimensions: 1536

Prompt 模板管理（外部化文件）：

你是一个专业的客户支持助手。请根据以下知识库内容回答用户问题。知识库内容：{{knowledge}}用户问题：{{question}}回答要求：1. 仅基于知识库内容回答，不要编造信息2. 如果知识库中没有相关信息，明确告知用户3. 回答需简洁、准确、专业

RAG 管道服务实现：

/** * RAG 增强的客户支持服务 * 将用户问题与知识库向量检索结合，生成有依据的回答 */@Service@Slf4jpublic class CustomerSupportRagService {private final ChatClient chatClient;private final VectorStore vectorStore;private final PromptTemplate promptTemplate;public CustomerSupportRagService(ChatClient.Builder chatClientBuilder, VectorStore vectorStore) {this.chatClient = chatClientBuilder.build();this.vectorStore = vectorStore;// 加载外部化 Prompt 模板var promptResource = new ClassPathResource("prompts/customer-support.st");this.promptTemplate = new PromptTemplate(promptResource);}/** * RAG 查询主流程：检索 -> 构建 Prompt -> 调用模型 * * @param question 用户问题 * @return 基于知识库的回答 */public String query(String question) {// 1. 向量检索：从知识库中找到与问题最相关的文档片段List relevantDocs = retrieveRelevantDocuments(question);// 2. 拼接知识库上下文String knowledge = relevantDocs.stream().map(Document::getContent).collect(Collectors.joining("nn"));// 3. 构建 PromptPrompt prompt = promptTemplate.create(Map.of("knowledge", knowledge,"question", question));// 4. 调用模型，带重试与降级try {ChatResponse response = chatClient.prompt(prompt).call().chatResponse();// 记录 Token 用量，用于成本监控logTokenUsage(response);return response.getResult().getOutput().getContent();} catch (ApiException e) {log.error("LLM API 调用失败，状态码: {}, 原因: {}",e.getStatusCode(), e.getMessage());return generateFallbackAnswer(question, relevantDocs);}}/** * 向量检索：基于问题语义查找最相关的知识库片段 * 限制 Top-K 和相似度阈值，避免无关内容干扰 */private List retrieveRelevantDocuments(String question) {SearchRequest searchRequest = SearchRequest.builder().query(question).topK(5)// 返回最相关的 5 个片段.similarityThreshold(0.7) // 相似度阈值，过滤低质量结果.build();return vectorStore.similaritySearch(searchRequest);}/** * 降级策略：当 LLM 调用失败时，返回检索到的原始文档片段 * 保证服务可用性，避免因模型不可用导致完全无响应 */private String generateFallbackAnswer(String question,List relevantDocs) {if (relevantDocs.isEmpty()) {return "抱歉，当前无法获取回答，请稍后重试。";}StringBuilder sb = new StringBuilder("以下是与您问题相关的知识库内容：nn");for (int i = 0; i < relevantDocs.size(); i++) {sb.append("[").append(i + 1).append("] ").append(relevantDocs.get(i).getContent()).append("nn");}sb.append("（系统暂时无法生成总结，以上为原始检索结果）");return sb.toString();}/** * 记录 Token 用量，用于成本监控与预算控制 */private void logTokenUsage(ChatResponse response) {Usage usage = response.getMetadata().getUsage();log.info("Token 用量 - Prompt: {}, Completion: {}, Total: {}", usage.getPromptTokens(), usage.getGenerationTokens(), usage.getTotalTokens());}}

知识库文档导入服务：

/** * 知识库文档导入服务 * 将文档分块、生成向量嵌入并写入 VectorStore */@Servicepublic class KnowledgeBaseIngestionService {private final VectorStore vectorStore;public KnowledgeBaseIngestionService(VectorStore vectorStore) {this.vectorStore = vectorStore;}/** * 导入文本文档到知识库 * 分块策略：按段落分割，每块不超过 500 Token，重叠 50 Token */public void ingestDocument(String documentId, String content) {// 文档分块：控制块大小以平衡检索精度与上下文完整性TextSplitter splitter = new TokenTextSplitter(500, // 每块最大 Token 数50,// 块间重叠 Token 数5, // 最小块大小10000, // 最大块大小true // 保留分隔符);Document originalDoc = new Document(documentId, content,Map.of("source", documentId, "ingestedAt", Instant.now().toString()));List chunks = splitter.split(originalDoc);// 写入向量存储，Spring AI 自动调用 Embedding 模型生成向量vectorStore.add(chunks);}}

四、Token 成本与延迟抖动：Spring AI 集成的架构权衡

Spring AI 显著降低了 Java 应用集成 LLM 的工程复杂度，但引入大模型调用链路后，系统面临的新约束必须被正视。

第一，Token 成本的不可预测性。 LLM 的计费基于 Token 数量，而用户输入的长度和模型的输出长度在请求前无法精确预估。一个看似简单的 RAG 查询，可能因为检索到大量知识库片段而导致 Prompt Token 数飙升。在 Spring AI 的配置中，max-tokens 参数可以限制输出长度，但无法限制输入长度。必须在业务层实现 Token 预算控制：在调用模型前估算 Prompt Token 数，超出预算时截断知识库片段或拒绝请求。

第二，模型调用的延迟不确定性。 LLM 的推理延迟从数百毫秒到数十秒不等，取决于输入长度、输出长度和模型负载。Spring AI 默认使用同步调用模式，一个慢请求会阻塞业务线程。对于延迟敏感的接口，必须使用 stream() 方法进行流式调用，或设置合理的超时时间。Spring AI 的 ChatClient 支持通过 RestClient.Builder 自定义超时配置。

第三，向量检索的精度与召回率权衡。 RAG 管道的质量高度依赖向量检索的效果。相似度阈值设置过高会导致召回不足（知识库中有答案但未被检索到），设置过低则引入噪声（检索到不相关的内容，干扰模型回答）。similarityThreshold 参数需要根据业务场景反复调优，没有通用的最优值。

适用边界： Spring AI 适合需要集成多种模型供应商、管理复杂 Prompt、构建 RAG 管道的企业级 Java 应用。对于只需要调用单一模型 API 的简单场景，直接使用 HTTP 客户端可能更轻量。Spring AI 的抽象层引入了一定的学习成本和框架约束，团队需要评估其收益是否大于引入成本。

五、总结

Spring AI 为 Java 后端集成大模型提供了一套完整的工程化方案：ChatModel 接口统一了模型调用抽象，PromptTemplate 实现了 Prompt 的外部化管理，VectorStore 接口屏蔽了向量存储的实现差异，RAG 管道将检索与生成串联为端到端流程。降级策略和 Token 用量监控则是生产环境不可或缺的保障机制。

然而，Token 成本的不可预测性、推理延迟的不确定性、向量检索的精度与召回率权衡，都是架构师在设计 LLM 集成方案时必须纳入考量的约束条件。Spring AI 提供的是工具和抽象，而非银弹。

落地路线建议：第一步，以单一模型供应商（如 OpenAI）为起点，验证 Spring AI 的基本调用链路；第二步，将硬编码的 Prompt 迁移为外部化模板，建立 Prompt 版本管理流程；第三步，引入 VectorStore 和 RAG 管道，构建知识库增强的问答能力；第四步，实现 Token 预算控制和延迟监控，将 LLM 调用纳入系统的可观测性体系。