1. 从Java到AI为什么Spring AI和Spring AI Alibaba是当前最值得投入的集成方案如果你是一名Java开发者想切入AI应用开发但被Python生态、复杂的模型部署和五花八门的框架搞得无从下手那么Spring AI和Spring AI Alibaba就是你最该优先了解的方案。这不是一个简单的API调用库而是一个旨在将大模型能力无缝集成到成熟Spring生态中的标准化框架。它的核心价值在于让你能用熟悉的Service、RestController和配置文件的方式去调用ChatGPT、通义千问乃至本地部署的Ollama模型把AI能力当成一个普通的“数据源”或“服务”来消费。很多人一上来就纠结学哪个大模型、怎么调参结果在环境搭建和协议对接上就卡住了。Spring AI系列框架解决的就是这个“最后一公里”的问题它统一了不同AI供应商的接口你只需要换一个配置项就能从OpenAI切换到阿里云百炼或本地模型业务代码几乎不用动。对于企业级应用来说这种可插拔性和标准化至关重要能避免技术栈被单一厂商绑定。所以这篇内容不是教你训练模型而是聚焦于如何作为一个Java工程师快速、稳健地将AI能力集成到你的Spring Boot应用中。我们会从最基础的对话开始一直讲到RAG知识库和智能体Agent的实战所有步骤都基于可复现的环境和配置。2. 环境准备与核心概念澄清别在第一步就选错方向开始写代码之前必须先理清几个关键概念和准备好对应的环境这能避免你后续掉进很多坑里。2.1 Spring AI 与 Spring AI Alibaba 的关系与选型这是最容易混淆的点。简单来说Spring AI是Spring官方社区主导的项目提供了对接AI服务的抽象层和基础能力。它定义了ChatClient、EmbeddingClient等标准接口。Spring AI Alibaba是阿里云基于Spring AI抽象针对阿里云百炼平台、通义千问等阿里系AI服务做的具体实现和增强。它完全兼容Spring AI的接口并增加了对阿里云特有功能如千问Max、RAG检索增强的深度集成。选型建议如果你的项目主要使用OpenAI、Azure OpenAI、Ollama本地模型或者希望保持供应商中立优先使用Spring AI。如果你的项目部署在阿里云主要使用通义千问、百炼平台或者需要用到阿里云OSS、向量引擎等深度集成功能那么Spring AI Alibaba是更顺滑的选择。两者在基础用法对话、嵌入上高度一致学会一个另一个几乎可以无缝切换。2.2 本地模型运行器Ollama 的安装与加速要在本地低成本地测试和开发Ollama几乎是必选项。它让你能在自己的电脑上运行Llama 3、Qwen等开源大模型。安装与加速官方安装访问Ollama官网根据你的操作系统Windows/macOS/Linux下载安装包。安装后命令行执行ollama run llama3:8b即可拉取并运行一个80亿参数的Llama 3模型。但对于国内开发者直接下载可能非常慢。国内镜像加速这是关键一步。可以通过配置环境变量使用国内镜像源来加速模型下载。Linux/macOS在终端执行export OLLAMA_HOST镜像源地址具体地址需寻找当前可用的国内镜像例如一些高校或社区提供的。更一劳永逸的方法是修改Ollama的服务配置文件。Windows在系统环境变量中新增OLLAMA_HOST值为镜像源地址。完成后再次执行ollama run qwen2.5:7b等命令下载速度会有显著提升。常用命令# 列出已下载的模型 ollama list # 运行一个模型进行交互式对话 ollama run llama3:8b # 删除一个模型释放磁盘空间 ollama rm llama3:8b # 查看Ollama服务状态 ollama serve2.3 项目初始化与依赖引入创建一个标准的Spring Boot项目推荐使用Spring Initializr。核心依赖根据你的选型决定如果使用 Spring AI (以OpenAI/Ollama为例)dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId !-- 使用最新的稳定版本 -- /dependency !-- 如果需要连接本地Ollama还需要 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-ollama-spring-boot-starter/artifactId /dependency如果使用 Spring AI Alibaba (以通义千问为例)dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-spring-boot-starter/artifactId !-- 使用最新版本 -- /dependency注意Spring AI相关起步依赖的版本需要与你使用的Spring Boot版本匹配务必查阅官方文档的版本兼容性表格这是启动失败的高发区。3. 从零到一完成你的第一次AI对话调用环境就绪后我们抛开理论直接通过三个最典型的场景把AI能力跑起来。3.1 场景一调用云端大模型以阿里云百炼/通义千问为例这是最常见的生产场景。假设你已拥有阿里云的AccessKey和百炼平台的应用API-KEY。配置application.yml:spring: ai: alibaba: chat: # 在百炼平台创建应用后获取 api-key: sk-xxxxxxxxxxxxxxxx # 百炼ChatCompletions API的端点 base-url: https://dashscope.aliyuncs.com/compatible-mode/v1 # 选择模型例如通义千问Max options: model: qwen-max这里的关键是base-url和model它们决定了你调用哪个服务、哪个模型。百炼平台提供了兼容OpenAI协议的端点使得Spring AI Alibaba可以无缝接入。编写Service层代码import org.springframework.ai.chat.ChatClient; import org.springframework.ai.chat.prompt.Prompt; import org.springframework.ai.chat.messages.UserMessage; import org.springframework.stereotype.Service; Service public class AIChatService { private final ChatClient chatClient; public AIChatService(ChatClient chatClient) { this.chatClient chatClient; } public String chat(String userMessage) { // 构建Prompt这是Spring AI的核心抽象 Prompt prompt new Prompt(new UserMessage(userMessage)); // 调用并返回String类型的响应 return chatClient.call(prompt).getResult().getOutput().getContent(); } }注意我们注入的是Spring AI标准的ChatClient接口而不是某个厂商的具体实现。这就是抽象层的好处。编写Controller进行测试import org.springframework.web.bind.annotation.*; RestController RequestMapping(/ai) public class AIChatController { private final AIChatService chatService; public AIChatController(AIChatService chatService) { this.chatService chatService; } GetMapping(/chat) public String chat(RequestParam String message) { return chatService.chat(message); } }启动应用访问http://localhost:8080/ai/chat?message你好请介绍一下你自己你应该能收到通义千问模型的回复。3.2 场景二调用本地模型Ollama集成当你没有云模型预算或需要在隔离环境测试时本地模型是完美选择。前提是已在本地安装并运行了Ollama且拉取了模型如llama3:8b。配置application.yml:spring: ai: ollama: # Ollama服务默认运行在11434端口 base-url: http://localhost:11434 chat: options: # 指定Ollama中已拉取的模型名称 model: llama3:8b代码复用无需修改任何Java代码。你的AIChatService和AIChatController完全不用动。Spring AI的抽象层会自动根据配置将请求路由到本地的Ollama服务。启动与验证确保Ollama服务在运行命令行执行ollama serve。启动你的Spring Boot应用。调用相同的/ai/chat接口。这次请求将由你本地电脑上的Llama 3模型处理。关键观察点查看应用日志和Ollama服务日志确认连接和调用成功。本地调用的速度取决于你的电脑硬件尤其是CPU和内存。3.3 场景三使用结构化输出Function Calling与提示词工程直接返回文本只是基础更多时候我们需要模型返回结构化的JSON数据以便程序后续处理。同时提示词的质量直接决定输出效果。定义返回的数据结构public class BookInfo { private String title; private String author; private Integer publishYear; private String genre; // getters and setters }编写提示词并指定输出格式import org.springframework.ai.chat.prompt.PromptTemplate; Service public class StructuredOutputService { private final ChatClient chatClient; public BookInfo extractBookInfo(String description) { // 1. 使用PromptTemplate构建更复杂的提示词 PromptTemplate promptTemplate new PromptTemplate( 请从以下文本中提取书籍信息。 文本{description} 请严格按照以下JSON格式返回且只返回JSON不要有其他任何内容 {{ title: 书名, author: 作者, publishYear: 出版年份, genre: 体裁 }} ); // 2. 渲染提示词将变量替换为实际值 Prompt prompt promptTemplate.create(Map.of(description, description)); // 3. 调用模型 String jsonResponse chatClient.call(prompt).getResult().getOutput().getContent(); // 4. 解析JSON这里简化实际可使用Jackson/ObjectMapper // 将jsonResponse解析为BookInfo对象... return parseJson(jsonResponse); } }提示词工程要点明确指令告诉模型要做什么“提取书籍信息”。提供上下文给出输入文本。严格约束输出格式使用JSON Schema或示例JSON并强调“只返回JSON”。这是减少“AI幻觉”即模型编造信息或返回多余内容的有效手段。使用占位符PromptTemplate让提示词管理更清晰。通过以上三个场景你已经掌握了Spring AI最核心的对话能力集成。接下来我们要解决大模型“知识陈旧”和“信口开河”的核心痛点——RAG。4. 构建RAG系统让大模型拥有你的私有知识库RAG检索增强生成是目前让大模型落地业务最关键的技术之一。其原理简单说就是用户提问时先从你的私有知识库文档、数据库中检索出相关片段然后将“问题相关片段”一起交给大模型让它基于这些片段生成答案从而保证答案的相关性和准确性。4.1 RAG核心流程与组件拆解一个完整的RAG流程分为两个阶段索引阶段Indexing将你的知识文档PDF、Word、TXT等进行分块、向量化并存入向量数据库。检索与生成阶段Retrieval Generation用户提问时将问题向量化在向量数据库中检索出最相关的文本块组合成提示词交给大模型生成答案。Spring AI Alibaba 提供了Spring AI Alibaba Graph等高级组件来简化这个过程但其底层依然依赖几个核心概念文档加载器Document Loader加载各种格式的文档。文本分割器Text Splitter将长文档切成适合模型处理的小块。嵌入模型Embedding Model将文本块转换为向量一组数字。向量数据库Vector Store存储和快速检索这些向量。4.2 基于Spring AI实现简易RAG我们以本地文本文件和内存向量库为例实现一个最简可工作的RAG。添加依赖以使用OpenAI Embeddings为例本地也可用Ollama的嵌入模型dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency !-- 内存向量库用于演示 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-simple-vector-store/artifactId /dependency配置嵌入模型在application.yml中spring: ai: openai: api-key: ${OPENAI_API_KEY} # 你的OpenAI Key embedding: options: model: text-embedding-3-small # 嵌入模型实现RAG服务import org.springframework.ai.document.Document; import org.springframework.ai.reader.TextReader; import org.springframework.ai.transformer.splitter.TokenTextSplitter; import org.springframework.ai.vectorstore.SimpleVectorStore; import org.springframework.ai.vectorstore.VectorStore; import org.springframework.core.io.Resource; import org.springframework.core.io.ClassPathResource; Service public class RagService { private final VectorStore vectorStore; private final ChatClient chatClient; public RagService(VectorStore vectorStore, ChatClient chatClient) { this.vectorStore vectorStore; this.chatClient chatClient; } // 1. 构建知识库索引 PostConstruct public void init() { Resource resource new ClassPathResource(knowledge.txt); // 你的知识文档 TextReader textReader new TextReader(resource); ListDocument documents textReader.get(); // 分割文档这里按Token数分割更常用的是按段落或句子 TokenTextSplitter splitter new TokenTextSplitter(); ListDocument splitDocuments splitter.apply(documents); // 将文档向量化并存入向量库 vectorStore.add(splitDocuments); } // 2. 检索并生成答案 public String ask(String question) { // 检索最相关的3个文档块 ListDocument similarDocuments vectorStore.similaritySearch(question, 3); // 构建包含上下文的提示词 String context similarDocuments.stream() .map(Doc::getContent) .collect(Collectors.joining(\n\n)); String promptTemplate 请基于以下上下文信息回答问题。 如果上下文信息不足以回答问题请直接说“根据提供的信息无法回答”。 上下文 {context} 问题{question} 答案 ; Prompt prompt new PromptTemplate(promptTemplate) .create(Map.of(context, context, question, question)); return chatClient.call(prompt).getResult().getOutput().getContent(); } }使用与验证将你的知识文档如公司制度、产品手册放入src/main/resources/knowledge.txt。启动应用后调用RagService的ask方法模型就会基于你的私有知识库回答问题。4.3 生产级考量与进阶方向上面的简易实现用于理解流程但生产环境需要更多考量向量数据库选择内存向量库重启即丢失。生产环境需用Redis、PgVectorPostgreSQL插件、Milvus、阿里云向量引擎等持久化方案。Spring AI支持多种Vector Store。文本分块策略TokenTextSplitter可能割裂语义。应使用RecursiveCharacterTextSplitter并合理设置块大小和重叠区以保持上下文连贯。检索优化简单相似度搜索可能不够准。可结合元数据过滤如文档来源、日期、重排序Rerank技术、或知识图谱Ontology来提升检索精度。多轮对话与历史需要将对话历史也纳入检索和提示词构建中实现有记忆的RAG。评估与监控需要设计评估指标答案相关性、事实准确性并监控检索命中率、生成延迟等。Spring AI Alibaba Graph等框架封装了更复杂的流程如路由、多步检索但底层原理相通。建议先从手撸一个简易RAG开始彻底理解每个环节再使用高级框架来提升开发效率。5. 避坑指南与性能调优实战把Demo跑起来只是第一步要让AI应用稳定可靠地运行必须关注以下实战细节。5.1 常见错误与排查清单连接失败/超时检查配置base-url、api-key、model名称是否完全正确。云端服务注意区域端点。检查网络是否能ping通或curl到配置的端点。本地Ollama检查localhost:11434是否可达。检查依赖版本Spring Boot、Spring AI、Spring Cloud Alibaba版本是否兼容。这是最高频的启动错误原因。模型响应慢或OOM内存溢出本地模型主要受CPU/内存限制。尝试更小的模型如llama3:8b换成qwen2.5:3b或在Ollama启动时限制线程数OLLAMA_NUM_THREADS4。提示词过长输入问题上下文的Token数超过模型限制。需要优化文本分块策略减少单次输入的上下文长度。调整参数通过ChatOptions降低temperature减少随机性、设置maxTokens限制生成长度来加速。输出格式不符合预期“AI幻觉”强化提示词约束在提示词中明确要求输出格式如JSON并加入“只返回JSON不要有任何其他解释”等强指令。使用Structured Output APISpring AI和部分模型供应商支持更可靠的结构化输出功能优先使用。后处理校验在代码中对模型的输出进行格式和逻辑校验失败则重试或降级处理。向量检索结果不相关检查嵌入模型用于索引和检索的嵌入模型是否一致不同模型生成的向量空间不同无法直接比较。优化分块块太大则信息不聚焦块太小则上下文缺失。需要根据你的文档类型技术文档、对话记录、表格调整分块大小和分隔符。尝试混合检索结合基于关键词的稀疏检索如BM25和向量检索往往效果更好。5.2 配置参数调优建议在application.yml中除了必填项这些参数对性能和效果影响很大spring: ai: openai: # 或 alibaba, ollama chat: options: model: qwen-max temperature: 0.2 # 控制创造性。任务要求精确时调低0.1-0.3需要创意时调高0.7-0.9。 maxTokens: 1024 # 限制生成内容的长度防止生成过长文本。 topP: 0.9 # 核采样与temperature配合使用影响词的选择范围。 embedding: options: model: text-embedding-3-small dimensions: 512 # 指定嵌入向量的维度更低的维度可能提升检索速度并节省存储但可能损失精度。对于批量处理任务还需要考虑超时与重试配置HTTP客户端或SDK的超时时间并实现重试机制可使用Spring Retry。速率限制了解云服务商的QPS每秒查询率限制在客户端实现限流避免请求被拒。异步与非阻塞使用Async或WebFlux进行异步调用避免阻塞主线程提升应用吞吐量。5.3 从开发到生产的必要步骤配置外部化绝不将api-key等敏感信息硬编码或提交到代码库。使用Spring Cloud Config、Nacos或环境变量管理。日志与监控详细记录AI调用的请求、响应、耗时和Token使用量。集成Micrometer和Prometheus监控关键指标。熔断与降级使用Resilience4j或Sentinel为AI服务调用配置熔断器。当AI服务不稳定时快速失败或切换到备用方案如返回缓存、简化流程。成本控制监控Token消耗特别是嵌入模型和大型对话模型的调用。设置预算告警。对于内部工具优先考虑本地模型。版本管理模型版本、Spring AI版本、你的业务代码版本需要有明确的对应关系和升级策略。6. 总结Java开发者切入AI应用的最佳路径回顾整个过程从Java转型AI应用开发Spring AI生态提供了一个坡度最缓的路径。它没有让你去重新学习Python的深度学习框架而是让你在熟悉的Spring世界里用注解和配置的方式消费AI能力。我建议的学习和实践路线是第一步打通对话。用Ollama在本地跑通一个ChatClient理解Prompt、ChatResponse这些核心抽象。这是所有AI应用的基石。第二步攻克RAG。这是当前AI落地的核心范式。亲手实现一个从文档加载、分割、向量化、存储到检索生成的完整流程。理解清楚后再考虑使用Spring AI Alibaba Graph这类框架来提升效率。第三步探索智能体Agent。当你的应用需要根据目标动态规划、调用工具搜索、计算、查数据库时就进入了Agent的领域。Spring AI的Agent模块提供了基础支持可以从简单的ReAct模式开始尝试。第四步工程化与优化。关注性能、稳定性、成本和监控。将AI组件当作一个可能有延迟、会出错的外部服务来设计而不是一个魔法黑盒。最终技术选型没有银弹。Spring AI Ollama 组合是绝佳的学习和原型验证工具。当业务要上生产时再根据团队技术栈、成本、性能和数据安全要求在Spring AI对接多云和Spring AI Alibaba深耕阿里云之间做出选择。记住先让核心流程在本地稳定跑起来远比一开始就纠结于选择哪个最炫酷的框架更重要。