最近在推进公司的一个智能客服项目时团队在技术选型上遇到了不小的挑战。面对市面上琳琅满目的 AI 框架和库从基础的 Spring AI 到复杂的 AI Agent 架构如何为 Java 后端技术栈选择一条清晰、高效且能落地的学习与实践路径成为了我们亟需解决的问题。经过一段时间的摸索、踩坑和项目实战我梳理出了一套从基础到进阶的完整 Java AI 技术栈学习方案。本文旨在分享这套闭环的实操路径它不仅涵盖了 Spring AI 的核心用法更深入到了 AI Agent 的企业级应用开发。无论你是刚接触 AI 的 Java 开发者还是正在寻找项目落地方案的工程师都能从中找到从环境搭建、框架选型、核心编码到生产避坑的完整指南。我们将一起拆解如何用 Java 这把“老枪”玩转 AI 这片“新战场”。1. Java 开发者为何要关注 AI 技术栈在 ChatGPT 掀起浪潮的今天AI 不再是数据科学家或算法工程师的专属领域。作为构建企业级应用的中坚力量Java 开发者正面临一个关键的转型期如何将大模型的能力无缝集成到现有的、庞大的 Java 技术生态中。1.1 市场趋势与职业需求观察最新的技术热点“AI Agent”、“大模型应用开发”、“Spring AI”等词汇频繁出现。这背后反映的是企业对于智能化升级的迫切需求。从智能客服、代码辅助生成、数据分析报告到自动化流程AI 正在成为软件系统的“标配”能力。掌握 Java 与 AI 的结合点意味着你能参与到更具前瞻性和价值的项目中显著提升个人竞争力。1.2 Java 在 AI 应用中的定位Java 以其稳定性、强大的并发处理能力和丰富的企业级框架如 Spring生态著称。在 AI 应用架构中Java 通常扮演着“ orchestrator”编排者和“ backend for frontend”BFF的角色核心业务逻辑复杂的业务流程控制、事务管理、数据持久化仍由 Java 负责。AI 能力集成通过调用 AI 服务本地或云端来增强应用功能例如在用户提交工单后自动调用大模型分析内容并分类。企业级管控利用 Spring 生态实现 AI 调用的限流、降级、监控、认证和配置化管理。1.3 核心概念厘清Spring AI 与 AI Agent在开始之前必须区分两个核心概念这也是本文学习路径的主线Spring AI可以理解为AI 领域的 Spring Boot。它不是一个具体的 AI 模型而是一个抽象框架其核心价值在于提供了统一的 API 来接入各种大模型如 OpenAI GPT、Azure OpenAI、Ollama 本地模型等。它帮你屏蔽了不同模型提供商 API 的差异让你像使用JdbcTemplate操作不同数据库一样使用相似的代码操作不同的大模型。学习 Spring AI 是 Java 开发者入门 AI 应用的第一站。AI Agent这是一个更上层的概念。一个 Agent 是一个能感知环境、进行决策并执行动作以实现目标的系统。在编程语境下一个 AI Agent 通常由大模型作为“大脑”、工具集作为“手脚”和记忆/状态管理组成。例如一个“数据库查询Agent”的流程可能是用户用自然语言提问 - Agent利用大模型将问题解析成 SQL - 调用“数据库工具”执行查询 - 将结果整理成自然语言回复。学习 AI Agent 开发意味着你开始构建具备自主推理和行动能力的复杂 AI 应用。理解了“为什么学”和“学什么”接下来我们进入实战环节从环境搭建开始。2. 环境准备与核心工具选型工欲善其事必先利其器。一个稳定且高效的开发环境是成功的第一步。本节将详细说明所需的软件、工具及版本建议。2.1 基础开发环境操作系统Windows 10/11, macOS, 或 Linux (如 Ubuntu 20.04)。本文示例将在 macOS/Linux 环境下演示命令。Java推荐JDK 17 或 21(LTS 版本)。Spring AI 对 JDK 版本有要求建议使用较新的 LTS 版本以获得最佳兼容性和性能。# 检查Java版本 java -version构建工具Maven (3.6)或Gradle (7.6)。Spring Boot 项目对两者支持都很好本文以 Maven 为例。# 检查Maven版本 mvn -vIDEIntelliJ IDEA Ultimate(社区版也可) 或VS Code。IDEA 对 Spring 生态的支持更为完善。2.2 AI 相关环境与工具Spring AI本文写作时Spring AI 已发布稳定版本。我们将使用最新的稳定版。通过 Spring Initializr 创建项目时可以直接选择。大模型接入你需要一个可以访问的大模型服务。有以下几种选择云端付费 API如OpenAI GPT-4/3.5、Azure OpenAI。稳定、强大但需要网络环境并产生费用。本地部署模型如通过Ollama在本地运行 Llama 3、Qwen 等开源模型。完全免费、数据隐私性好但对硬件尤其是 GPU有要求。国内大模型 API如通义千问、文心一言等提供的 API 服务。对于初学者强烈建议从 Ollama 开始它能让你在本地零成本体验大模型交互非常适合学习和开发测试。Ollama 安装与使用# Linux/macOS 一键安装 curl -fsSL https://ollama.com/install.sh | sh # 启动Ollama服务 ollama serve # 另开一个终端拉取并运行一个模型例如 Llama 3 8B ollama run llama3:8b成功运行后你就可以在终端与模型对话了。这证明了你的本地 AI 环境是通的。2.3 创建 Spring Boot 项目使用 Spring Initializr 创建项目是最佳实践。访问 start.spring.io 。选择Project: MavenLanguage: JavaSpring Boot: 选择最新的稳定版 (如 3.2.x)Project Metadata: 按需填写 Group、Artifact (如demo-ai)。Dependencies: 添加Spring Web和Spring AI。在 Initializr 上你可能需要点击“ADD DEPENDENCIES”并搜索“AI”选择“Spring AI”或更具体的如“Spring AI OpenAI”。点击“GENERATE”下载项目压缩包解压后用 IDE 打开。至此你的基础环境已经就绪。接下来我们将深入 Spring AI 的核心学习如何用它统一操作各种大模型。3. Spring AI 核心统一模型接入与基础应用Spring AI 的核心思想是“抽象”。它定义了一套标准的接口如ChatClient、EmbeddingClient不同的模型提供商如 OpenAI, Ollama, Azure通过实现这些接口来接入。开发者只需面向 Spring AI 的接口编程即可轻松切换模型提供商。3.1 项目依赖与配置打开你的pom.xml文件确保包含了 Spring AI 的起步依赖。如果你是从 Initializr 生成的应该已经有了。为了连接 Ollama我们需要添加对应的连接器。!-- pom.xml -- dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- Spring AI 核心依赖 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version0.8.1/version !-- 请使用最新稳定版本 -- typepom/type scopeimport/scope /dependency !-- Spring AI Ollama 连接器 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-ollama-spring-boot-starter/artifactId /dependency !-- 其他依赖... -- /dependencies接下来在application.properties或application.yml中配置 Ollama 连接信息。# application.yml spring: ai: ollama: base-url: http://localhost:11434 # Ollama 默认服务地址 chat: options: model: llama3:8b # 指定默认使用的模型需与Ollama中拉取的模型名一致3.2 第一个 AI 对话应用让我们创建一个简单的 REST 控制器实现一个聊天接口。// 文件路径src/main/java/com/example/demoai/controller/AiChatController.java package com.example.demoai.controller; import org.springframework.ai.chat.ChatClient; import org.springframework.ai.chat.ChatResponse; import org.springframework.ai.chat.prompt.Prompt; import org.springframework.ai.chat.prompt.PromptTemplate; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import java.util.Map; RestController public class AiChatController { private final ChatClient chatClient; Autowired // 构造器注入 public AiChatController(ChatClient chatClient) { this.chatClient chatClient; } // 简单对话接口 GetMapping(/ai/chat) public String chat(RequestParam(value message, defaultValue Hello) String message) { return chatClient.call(message); } // 使用 PromptTemplate 进行结构化对话 GetMapping(/ai/adv-chat) public String advancedChat(RequestParam String topic) { // 创建一个提示词模板{topic} 是占位符 PromptTemplate promptTemplate new PromptTemplate(请用简洁的语言介绍一下 {topic}。); // 将参数传入模板生成最终的 Prompt 对象 Prompt prompt promptTemplate.create(Map.of(topic, topic)); // 调用模型并获取完整响应 ChatResponse response chatClient.call(prompt); // 从响应中提取文本内容 return response.getResult().getOutput().getContent(); } }启动你的 Spring Boot 应用 (DemoAiApplication)然后使用浏览器或curl命令进行测试# 测试简单对话 curl http://localhost:8080/ai/chat?message用Java写一个Hello World程序 # 测试结构化对话 curl http://localhost:8080/ai/adv-chat?topicSpring框架如果一切正常你将收到来自本地 Llama 3 模型的回答。恭喜你已经成功使用 Java 调用了大模型3.3 核心 API 深度解析ChatClient: 最核心的接口用于与大模型进行对话。call()方法是最基本的调用方式。Prompt: 代表一个发送给模型的请求。它不仅仅包含用户消息 (message)还可以包含系统指令 (system message)、上下文 (context) 和对话历史 (chat history)。PromptTemplate: 用于构建动态提示词的强大工具。它允许你创建带有占位符的模板在运行时注入变量非常适合构建需要结构化输入的 AI 应用。ChatResponse: 模型的完整响应包含了输出内容、使用令牌数、推理时间等元数据。通过 Spring AI我们以极低的代码成本实现了与大模型的交互。但这只是 AI 应用的“冰山一角”。真正的威力在于让 AI 不仅能“说”还能“做”这就是 AI Agent 的领域。4. 进阶实战构建你的第一个 AI AgentAI Agent 的核心在于“思考-行动”循环。Spring AI 提供了AiAgent相关的抽象来帮助我们构建这类应用。一个典型的 Agent 需要三要素模型Brain、工具Tools和记忆Memory。4.1 设计一个“天气查询Agent”目标用户用自然语言询问天气Agent 能理解用户意图调用天气查询工具获取数据并组织成友好的回复。思考用户说“上海天气怎么样” - Agent 理解需要查询“上海”的“天气”。行动Agent 调用“天气查询工具”传入参数“上海”。观察工具返回上海的天气数据如温度、湿度、天气状况。回复Agent 将原始数据组织成自然语言回复给用户。4.2 实现工具WeatherService首先我们模拟一个天气查询工具。在实际项目中这里会调用真实的天气 API。// 文件路径src/main/java/com/example/demoai/tool/WeatherService.java package com.example.demoai.tool; import org.springframework.stereotype.Service; import java.util.HashMap; import java.util.Map; Service public class WeatherService { // 模拟天气数据 private static final MapString, String WEATHER_DATA new HashMap(); static { WEATHER_DATA.put(上海, 晴温度 18-25°C东南风2级。); WEATHER_DATA.put(北京, 多云温度 10-20°C北风3级。); WEATHER_DATA.put(深圳, 阵雨温度 22-28°C南风1级。); } /** * 查询城市天气 * param cityName 城市名 * return 天气描述字符串 */ public String getWeather(String cityName) { String weather WEATHER_DATA.get(cityName); if (weather null) { return 抱歉未找到城市 cityName 的天气信息。; } return String.format(%s的天气情况是%s, cityName, weather); } }4.3 将工具暴露给 AI AgentSpring AI 允许我们将任何 Spring Bean 的方法暴露为 Agent 可调用的工具。我们需要定义一个Tool。// 文件路径src/main/java/com/example/demoai/tool/WeatherTool.java package com.example.demoai.tool; import org.springframework.ai.tool.Tool; import org.springframework.ai.tool.annotation.ToolParam; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Component; Component public class WeatherTool { private final WeatherService weatherService; Autowired public WeatherTool(WeatherService weatherService) { this.weatherService weatherService; } // 使用 Tool 注解标记这是一个可供AI调用的工具 Tool(description 根据城市名称查询该城市的实时天气信息。) public String queryWeather(ToolParam(description 需要查询天气的中国城市名称例如上海、北京) String cityName) { // 在实际应用中这里可以加入参数校验、日志等 return weatherService.getWeather(cityName); } }4.4 配置并运行 AI Agent现在我们需要配置一个AiAgent它将使用我们定义的WeatherTool。// 文件路径src/main/java/com/example/demoai/config/AgentConfig.java package com.example.demoai.config; import org.springframework.ai.chat.ChatClient; import org.springframework.ai.chat.memory.InMemoryChatMemory; import org.springframework.ai.tool.ToolRegistry; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class AgentConfig { Bean public InMemoryChatMemory chatMemory() { // 提供一个简单的内存来存储对话历史使Agent有上下文记忆 return new InMemoryChatMemory(); } Bean public org.springframework.ai.agent.AiAgent aiAgent(ChatClient chatClient, ToolRegistry toolRegistry, InMemoryChatMemory chatMemory) { // 构建AiAgent return org.springframework.ai.agent.AiAgent.builder() .chatClient(chatClient) .toolRegistry(toolRegistry) // 注入工具注册表Spring会自动发现所有Tool注解的Bean .chatMemory(chatMemory) // 注入记忆 .systemPrompt( 你是一个友好的天气查询助手。你的任务是理解用户关于天气的询问调用合适的工具获取天气信息然后将结果清晰、友好地回复给用户。 如果用户的问题不涉及天气或者城市名称不在工具支持范围内请礼貌地告知用户你无法处理。 ) // 系统指令定义Agent的角色和行为 .build(); } }4.5 创建 Agent 控制器最后创建一个 REST 端点来与我们的 Weather Agent 交互。// 文件路径src/main/java/com/example/demoai/controller/AgentController.java package com.example.demoai.controller; import org.springframework.ai.agent.AiAgent; import org.springframework.ai.agent.AiAgentResponse; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; RestController public class AgentController { private final AiAgent aiAgent; Autowired public AgentController(AiAgent aiAgent) { this.aiAgent aiAgent; } GetMapping(/agent/weather) public String chatWithAgent(RequestParam String message) { // 将用户消息发送给Agent AiAgentResponse response aiAgent.chat(message); // 返回Agent的最终回复 return response.getChatResponse().getResult().getOutput().getContent(); } }4.6 运行与测试重启 Spring Boot 应用并进行测试curl http://localhost:8080/agent/weather?message上海今天天气如何 curl http://localhost:8080/agent/weather?message帮我看看北京和深圳的天气 curl http://localhost:8080/agent/weather?message你好吗 # 测试非天气问题观察控制台日志你会看到类似以下的输出这展示了 Agent 的思考过程AI Agent 决定调用工具: queryWeather 参数: {cityName上海} 工具执行结果: 上海的天气情况是晴温度 18-25°C东南风2级。 AI Agent 生成最终回复: 上海今天的天气很不错是晴天气温在18到25摄氏度之间有2级东南风。适合外出活动。至此你已经成功构建了一个具备“思考-行动”能力的 AI Agent它不仅能理解自然语言还能自主选择并调用合适的 Java 方法来完成任务。5. 企业级核心AI Agent 架构设计与最佳实践在简单 demo 之上企业级应用需要考虑更多性能、可观测性、稳定性、安全性。本节将探讨构建健壮 AI 应用的核心实践。5.1 架构设计模式单 Agent vs 多 Agent 系统对于复杂任务可以设计多个各司其职的 Agent如“查询Agent”、“分析Agent”、“报告生成Agent”并通过一个“协调员Agent”或工作流引擎如 Spring Cloud Data Flow 的简单应用来编排它们。工具的设计原则单一职责每个工具只做一件事并做好。queryWeather只查天气searchDatabase只查数据库。强类型与验证工具方法的参数应使用明确的类型String,Integer,LocalDate并在方法内部进行有效性校验。幂等性与安全性工具调用应尽可能幂等。涉及数据修改的工具必须加入严格的权限和业务逻辑校验。记忆Memory管理InMemoryChatMemory仅适用于开发测试。生产环境需要持久化存储如 Redis 或数据库并考虑设置会话过期和上下文窗口长度限制例如只保留最近10轮对话。5.2 性能优化与稳定性超时与重试调用外部模型 API 或工具必须设置超时。Spring AI 的客户端通常支持配置spring.ai.openai.chat.options.timeout。结合 Spring Retry 或 Resilience4j 实现重试机制。spring: ai: openai: chat: options: timeout: 30s限流与降级使用 Sentinel 或 Resilience4j 对 AI 调用进行限流防止上游服务过载或费用激增。当主要模型服务不可用时应有降级策略如切换到更便宜的模型或返回缓存结果。异步与非阻塞对于耗时的 AI 调用应使用 Spring 的Async或 WebFlux 实现异步处理避免阻塞 HTTP 线程提升应用吞吐量。提示词工程精心设计的系统提示词systemPrompt是提升 Agent 表现性价比最高的方式。明确指令、提供示例Few-Shot、定义输出格式能极大减少无效交互和令牌消耗。5.3 可观测性与监控日志记录详细记录 Agent 的决策过程、工具调用详情、令牌使用量、耗时。这对调试和成本分析至关重要。指标收集利用 Micrometer 将调用次数、成功率、响应时间、令牌消耗等指标暴露给 Prometheus并在 Grafana 中构建监控看板。链路追踪集成 Sleuth 或 OpenTelemetry将一次用户请求背后的多次 AI 调用和工具调用串联起来便于排查复杂问题。5.4 安全与合规输入输出过滤对用户输入和模型输出进行严格的过滤和审查防止提示词注入攻击Prompt Injection和模型输出有害内容。数据隐私明确哪些数据可以发送给外部 AI 服务。对于敏感数据优先考虑使用本地部署的模型如通过 Ollama。审计记录所有 AI 交互的元数据谁、何时、问了什么、模型回复了什么满足合规性要求。6. 常见问题与排查指南FAQ在开发过程中你一定会遇到各种问题。这里汇总了高频问题及其解决方案。问题现象可能原因排查步骤与解决方案启动报错Failed to configure a DataSourceSpring AI 某些连接器可能自动配置了需要数据库的组件。检查是否引入了不需要的 JDBC 依赖。在application.yml中排除相关自动配置spring.autoconfigure.excludeorg.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration调用/ai/chat接口超时或失败1. Ollama 服务未启动。2. 模型名称配置错误。3. 本地模型首次加载慢。1. 执行ollama serve确保服务运行。2. 检查application.yml中的spring.ai.ollama.chat.options.model名称需与ollama list显示的名称一致。3. 查看 Ollama 服务日志等待模型加载完成。Agent 不调用工具直接回答1. 系统提示词未明确要求调用工具。2. 工具描述不够清晰模型无法理解其用途。3. 模型能力不足。1. 强化systemPrompt例如“你必须调用可用的工具来回答问题不要自行编造信息。”2. 优化Tool注解中的description确保描述精准、无歧义。3. 尝试更换更强大的模型如从llama3:8b切换到llama3:70b。工具调用参数错误模型未能正确解析用户意图并映射到工具参数。1. 在ToolParam注解中提供更详细的参数描述和示例。2. 在系统提示词中提供工具调用范例。3. 考虑在工具调用前增加一个参数校验和转换层。内存占用过高OOM1. 对话历史Memory无限增长。2. 大模型本身占用大量内存。1. 实现记忆管理策略如只保留最近 N 轮对话或定期清理旧会话。2. 为 JVM 设置合理的堆内存参数-Xmx4g。3. 如果使用本地大模型确保系统物理内存充足。响应速度慢1. 本地模型推理速度慢。2. 网络延迟调用云端 API。3. 提示词过长导致处理耗时增加。1. 考虑使用量化版本模型如llama3:8b-instruct-q4_K_M。2. 检查网络考虑使用国内镜像或优化网络配置。3. 精简提示词和上下文移除不必要的信息。7. 完整学习路径与项目实战建议掌握零散的技术点还不够需要一条清晰的路径来系统化你的知识并通过项目进行巩固。7.1 分阶段学习路线图第一阶段基础入门 (1-2周)目标理解基本概念跑通第一个 Demo。行动搭建 Java Spring Boot 开发环境。安装并玩转 Ollama熟悉命令行与模型交互。使用 Spring Initializr 创建项目集成 Spring AI Ollama。实现一个简单的聊天接口如本文 3.2 节。学习PromptTemplate的使用实现一个动态问答接口。第二阶段核心掌握 (2-3周)目标深入 Spring AI 核心 API构建功能型 Agent。行动深入阅读 Spring AI 官方文档理解ChatClient,Prompt,ChatResponse等对象。学习Tool注解将你的业务服务如查询数据库、调用外部 API封装成工具。构建你的第一个 AI Agent如本文的天气查询 Agent理解思考-行动循环。为 Agent 添加简单的记忆功能实现多轮对话。第三阶段进阶与优化 (3-4周)目标设计复杂系统关注生产级要求。行动设计一个多 Agent 协作系统如用户输入 - 路由Agent - 专业处理Agent - 汇总Agent。集成向量数据库如 Pinecone, Milvus为 Agent 添加“长期记忆”和知识库检索RAG能力。为你的 AI 服务添加限流、降级、监控和链路追踪。探索不同的模型提供商OpenAI, Azure, 国内大模型实现模型的动态切换或降级。第四阶段项目实战与架构 (持续)目标解决真实业务问题形成架构思维。行动选题从一个具体的业务场景出发如智能知识库问答、自动化周报生成、代码评审助手、智能客服路由。设计画出系统架构图明确数据流、Agent 职责、工具边界。实现遵循最佳实践完成编码并编写单元测试和集成测试。部署与运维学习如何在 Docker/K8s 环境中部署包含大模型服务的应用配置健康检查、日志和告警。7.2 推荐实战项目构思智能技术文档助手基于公司内部 Wiki 或 API 文档构建一个能回答技术问题的 Agent。工具包括文档检索工具、代码示例搜索工具。自动化数据报告生成器用户用自然语言描述需求如“给我上周的销售TOP10产品”Agent 解析后调用数据查询工具从数据库获取数据再调用分析工具生成图表最后调用报告生成工具整合成一份邮件或文档。AI 增强的代码审查插件结合 GitHub/GitLab Webhook当有新的 Pull Request 时Agent 自动分析代码变更调用代码分析工具检查潜在 Bug、安全漏洞和代码风格问题并生成审查评论。从 Spring AI 的统一接口到 AI Agent 的智能编排Java 开发者拥抱 AI 的时代已经到来。这条学习路径的关键在于“动手”从最简单的对话接口开始逐步增加工具、引入记忆、设计架构最终构建出能够解决实际业务问题的智能系统。过程中遇到的每一个错误和性能瓶颈都是深入理解底层机制的最佳契机。