最近在尝试将AI大模型能力集成到Java后端项目中，发现市面上资料要么是Python的天下，要么就是Java生态的零散Demo，很难找到一个从环境搭建、框架选型到生产级Agent实战的完整闭环教程。本文基于最新的Spring AI 2.0、Spring AI Alibaba及LangChain4j生态，为你梳理一套可直接落地的Java+AI大模型开发方案，涵盖从基础对话到复杂智能体工作流的全流程，附带避坑指南和性能优化建议。

1. 背景与核心概念：为什么Java开发者需要关注AI大模型？

过去，AI应用开发似乎是Python的专属领域，但随着大模型能力的普及，越来越多的企业级应用、后台管理系统和微服务架构需要无缝集成AI能力。Java作为企业级开发的主力语言，其生态的稳定性、高性能和成熟的工程化实践，使得“Java + AI”成为必然趋势。

核心框架解析：

  1. Spring AI ：Spring官方推出的AI应用开发框架，旨在为Spring生态提供一套统一的AI模型接入抽象。它定义了 ChatClient 、 EmbeddingClient 、 ImageClient 等核心接口，让开发者可以像切换数据库驱动一样，轻松更换底层的大模型提供商（如OpenAI、Azure OpenAI、Ollama等）。
  2. Spring AI Alibaba ：阿里巴巴基于Spring AI标准进行扩展的框架，深度集成阿里云百炼、通义千问等国产大模型，并提供了符合国内开发者习惯的配置、工具链以及一些特有的高级功能（如图文理解、工作流编排等）。它是Spring AI生态在中国市场的重要补充。
  3. LangChain4j ：一个受Python LangChain启发，专为Java设计的AI应用框架。它提供了更丰富的“链”（Chain）、智能体（Agent）、记忆（Memory）和工具（Tool）等高层抽象，特别擅长构建复杂的、有状态的AI应用逻辑。

为什么需要它们？

  • Spring AI ：提供了 标准化 和 轻量级 的接入方式，适合快速集成基础AI功能（聊天、嵌入生成）。
  • Spring AI Alibaba ：针对 国内环境 和 阿里云生态 进行了优化，是使用国产模型的首选。
  • LangChain4j ：提供了构建 复杂AI逻辑 （如多步骤推理、使用工具、管理对话历史）的强大工具箱。

对于Java开发者而言，掌握这三者意味着你既能快速满足“接个聊天接口”的简单需求，也能从容应对“构建一个能自动查询数据库、调用API并生成报告的智能客服Agent”这样的复杂场景。

2. 环境准备与版本说明

在开始编码前，确保你的开发环境符合要求。本文示例将基于目前（2024-2025年）相对稳定且前瞻性兼容的版本进行构建，力求在2026年仍具有参考价值。

基础环境：

  • 操作系统 ：Windows 10/11, macOS, Linux (Ubuntu 20.04+) 均可。
  • Java ： JDK 17 或 JDK 21 (LTS) 。Spring AI 2.0+ 对JDK版本有要求，强烈推荐使用JDK 17及以上版本。
  • 构建工具 ： Maven 3.6+ 或 Gradle 7.x+ 。本文使用Maven进行演示。
  • IDE ：IntelliJ IDEA (推荐), Eclipse 或 VS Code。

核心依赖版本： 创建一个新的Spring Boot项目（例如使用 start.spring.io ），选择Spring Boot 3.2.x 或 3.3.x。然后在 pom.xml 中添加以下关键依赖。 

<!-- Spring Boot Starter -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.5</version> <!-- 可使用最新3.2.x或3.3.x -->
    <relativePath/>
</parent>

<!-- Spring AI 核心依赖 (OpenAI API 标准) -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    <version>1.0.0-M3</version> <!-- 注意：Spring AI 1.0 尚未正式发布，请关注官方更新 -->
    <!-- 未来稳定版可能为 1.0.0, 2.0.0 等 -->
</dependency>

<!-- Spring AI Alibaba (接入通义千问等) -->
<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-spring-boot-starter</artifactId>
    <version>2023.0.1.0</version> <!-- 版本号可能随阿里云迭代更新 -->
</dependency>

<!-- LangChain4j 核心 -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j</artifactId>
    <version>0.31.0</version> <!-- 请查看GitHub获取最新版 -->
</dependency>
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-spring-boot-starter</artifactId>
    <version>0.31.0</version>
</dependency>

<!-- 其他常用依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
</dependency>

重要版本说明：

  • Spring AI ：目前处于快速迭代的里程碑（M）版本阶段。 1.0.0-M3 是一个功能相对完整的预览版。生产环境请密切关注其正式版（GA）发布，并参考官方文档调整配置。
  • Spring AI Alibaba ：版本号通常与Spring Cloud Alibaba绑定，请根据你的Spring Cloud版本选择兼容的starter。
  • LangChain4j ：版本迭代较快，API可能发生变化。本文示例基于 0.31.0 ，这是一个相对稳定的版本，但集成时仍需注意其与Spring AI的兼容性。

项目结构预览： 

src/main/java/com/example/ai/
├── config/           // 配置类
├── controller/       // REST API 控制器
├── service/         // 业务逻辑层
│   ├── impl/
│   └── agent/       // 智能体相关服务
├── tool/            // LangChain4j Tool 定义
└── Application.java // 启动类

3. 核心语法、配置与原理拆解

3.1 Spring AI 基础配置与使用

Spring AI的核心思想是 配置即连接 。通过 application.yml 或 application.properties 文件，你可以定义要使用的AI模型。

配置示例 ( application.yml ): 

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY:sk-your-openai-key-here} # 从环境变量读取，安全！
      chat:
        options:
          model: gpt-4o-mini # 或 gpt-4-turbo, gpt-3.5-turbo
          temperature: 0.7
    # 如果你同时配置了多个客户端（如OpenAI和Ollama），需要指定默认客户端
    # chat.client.type: openai
  • api-key ： 切勿硬编码在代码或配置文件中提交到代码仓库！ 务必使用环境变量或配置中心管理。
  • model ：指定使用的模型名称。
  • temperature ：控制生成文本的随机性（0.0-2.0）。值越高，输出越随机、有创造性；值越低，输出越确定、保守。

核心接口 ChatClient 的使用： 在Service中，你可以直接注入 ChatClient 来调用大模型。 

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Service;

@Service
public class SimpleChatService {

    private final ChatClient chatClient;

    // 构造器注入
    public SimpleChatService(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    public String chat(String message) {
        // 最简单的调用方式
        return chatClient.prompt()
                .user(message)
                .call()
                .content();
    }

    public String chatWithSystemPrompt(String userMessage) {
        // 添加系统指令，塑造AI行为
        return chatClient.prompt()
                .system("你是一个专业的Java技术专家，回答要简洁准确。")
                .user(userMessage)
                .call()
                .content();
    }
}

3.2 Spring AI Alibaba 配置与特色

Spring AI Alibaba 的配置方式与Spring AI OpenAI类似，但指向阿里云的端点。

配置示例 ( application.yml ): 

spring:
  ai:
    alibaba:
      dashscope:
        api-key: ${ALIBABA_API_KEY:sk-your-alibaba-key} # 阿里云百炼/通义千问的API Key
        chat:
          options:
            model: qwen-max # 或 qwen-plus, qwen-turbo
            temperature: 0.8

使用上，你注入的同样是 ChatClient 。Spring AI Alibaba Starter会自动配置一个基于DashScope的 ChatClient 实现。如果你的项目同时配置了OpenAI和Alibaba，需要通过 @Qualifier 或配置 spring.ai.chat.client.type 来指定默认客户端。

特色功能初探： Spring AI Alibaba 可能提供一些针对通义千问模型的增强功能，例如更细粒度的参数控制、或集成阿里云OSS进行多模态处理。具体需要查阅其官方文档。

3.3 LangChain4j 的核心抽象

LangChain4j 提供了更丰富的构建块。理解以下几个核心概念至关重要：

  1. ChatLanguageModel : 对应Spring AI的 ChatClient ，是语言模型的抽象。
  2. Tool : 代表AI可以调用的外部函数或API。例如，查询天气、搜索数据库、调用计算器。
  3. Agent : 一个具备推理能力的实体，它可以理解用户目标，决定何时以及如何使用 Tool ，并整合信息给出最终回答。
  4. Memory : 用于存储和检索对话历史或知识，使AI具有上下文感知能力。
  5. Chain : 将多个组件（模型、提示词、工具、解析器）链接在一起，执行一个复杂的、多步骤的流程。

一个简单的LangChain4j配置： 

import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class LangChain4jConfig {

    @Bean
    public ChatLanguageModel chatLanguageModel() {
        // 这里同样可以从配置文件中读取API Key和模型参数
        return OpenAiChatModel.builder()
                .apiKey(System.getenv(“OPENAI_API_KEY”))
                .modelName(“gpt-4o-mini”)
                .temperature(0.7)
                .build();
    }
}

4. 完整实战案例：构建一个天气查询智能体 (Agent)

我们将综合使用Spring AI和LangChain4j，构建一个能理解用户自然语言请求（如“北京天气怎么样？”），并自动调用外部天气API获取信息，最后组织成友好回复的智能体。

4.1 项目结构与依赖

确保 pom.xml 中已包含Spring AI OpenAI Starter、LangChain4j Spring Boot Starter和Spring Web Starter。

4.2 定义外部工具 (Tool)

首先，我们需要定义一个“查询天气”的工具。LangChain4j提供了 @Tool 注解来简化这一过程。 

import dev.langchain4j.agent.tool.Tool;
import org.springframework.stereotype.Component;
import java.time.LocalDate;

@Component // 确保被Spring管理
public class WeatherTools {

    /**
     * 根据城市名称获取当前天气信息。
     * @param cityName 城市名称，例如“北京”、“上海”
     * @return 该城市的天气描述字符串
     */
    @Tool(“获取指定城市的当前天气信息”)
    public String getWeatherAtCity(@P(“城市名称”) String cityName) {
        // 这里是模拟实现，真实项目应调用如和风天气、OpenWeatherMap等API
        // 注意：API Key同样需要从环境变量或配置中心获取
        System.out.println(“[Tool Called] 正在查询城市: ” + cityName + “ 的天气...”);

        // 模拟API调用延迟
        try {
            Thread.sleep(500);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }

        // 模拟返回数据
        String[] weathers = {“晴”, “多云”, “小雨”, “阴”, “大雪”};
        String randomWeather = weathers[(int) (Math.random() * weathers.length)];
        int temp = 15 + (int) (Math.random() * 15);
        return String.format(“%s今天的天气是%s，气温大约%d摄氏度。”, cityName, randomWeather, temp);
    }

    /**
     * 获取指定城市未来几天的天气预报。
     */
    @Tool(“获取指定城市未来几天的天气预报”)
    public String getWeatherForecast(@P(“城市名称”) String cityName, @P(“天数”) int days) {
        System.out.println(“[Tool Called] 正在查询城市: ” + cityName + “ 未来” + days + “天的预报...”);
        // 模拟实现
        return String.format(“%s未来%d天的天气预报：第一天晴，第二天多云，第三天下雨。”, cityName, days);
    }
}
  • @Tool 注解内的描述非常重要，AI会根据这个描述来决定是否以及如何调用这个工具。
  • @P 注解用于描述参数，提高AI理解的准确性。

4.3 配置并创建智能体 (Agent)

接下来，我们配置一个能使用上述工具的智能体。 

import dev.langchain4j.agent.tool.ToolSpecification;
import dev.langchain4j.memory.ChatMemory;
import dev.langchain4j.memory.chat.MessageWindowChatMemory;
import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.service.AiServices;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class AgentConfig {

    // 注入我们之前定义的WeatherTools
    private final WeatherTools weatherTools;

    public AgentConfig(WeatherTools weatherTools) {
        this.weatherTools = weatherTools;
    }

    @Bean
    public ChatMemory chatMemory() {
        // 使用基于窗口的记忆，保留最近10轮对话
        return MessageWindowChatMemory.withMaxMessages(10);
    }

    @Bean
    public WeatherAgent weatherAgent(ChatLanguageModel chatLanguageModel, ChatMemory chatMemory) {
        // 使用AiServices.builder()创建代理实例
        // 它会自动将带有@Tool注解的方法暴露给AI，并处理对话记忆
        return AiServices.builder(WeatherAgent.class)
                .chatLanguageModel(chatLanguageModel)
                .chatMemory(chatMemory)
                .tools(weatherTools) // 注册工具
                .build();
    }
}

定义智能体接口 WeatherAgent ： 这个接口定义了智能体的“对话”能力。 

import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;
import dev.langchain4j.service.MemoryId;
import dev.langchain4j.service.V;

public interface WeatherAgent {

    @SystemMessage(“””
            你是一个友好的天气助手。
            你的职责是帮助用户查询天气信息。
            当用户询问天气时，你需要调用合适的工具来获取准确信息，然后组织成自然、友好的语言回复用户。
            如果用户没有提供城市名，你需要礼貌地询问。
            “””)
    String chat(@MemoryId String sessionId, @UserMessage String userMessage);

    // @MemoryId 将对话绑定到特定的会话（如用户ID），实现多用户隔离的记忆。
    // @V 注解可用于更复杂的提示词变量替换。
}

4.4 创建REST API控制器

提供一个简单的HTTP端点来与我们的天气智能体交互。 

import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping(“/api/ai”)
public class WeatherAgentController {

    private final WeatherAgent weatherAgent;

    public WeatherAgentController(WeatherAgent weatherAgent) {
        this.weatherAgent = weatherAgent;
    }

    @PostMapping(“/weather/chat”)
    public String chatWithAgent(@RequestParam String sessionId,
                                 @RequestBody ChatRequest request) {
        // sessionId 可以来自前端，用于区分不同用户的对话上下文
        // 简单示例中，我们可以用固定值或随机生成
        if (sessionId == null || sessionId.isBlank()) {
            sessionId = “default-session”;
        }
        return weatherAgent.chat(sessionId, request.getMessage());
    }

    // 简单的请求体
    public static class ChatRequest {
        private String message;
        // getter and setter
        public String getMessage() { return message; }
        public void setMessage(String message) { this.message = message; }
    }
}

4.5 运行与验证

  1. 启动应用 ：运行Spring Boot主类。
  2. 测试工具 ：可以使用 curl 、Postman或任何HTTP客户端进行测试。 
    curl -X POST ‘http://localhost:8080/api/ai/weather/chat?sessionId=user123' \
-H ‘Content-Type: application/json’ \
-d ‘{“message”: “北京今天天气怎么样？”}’
  3. 观察控制台 ：你会看到类似 [Tool Called] 正在查询城市: 北京 的天气... 的输出，说明智能体成功识别了用户意图并调用了工具。
  4. 查看响应 ：你会收到一个整合了工具返回信息的友好回复，例如：“北京今天的天气是晴，气温大约22摄氏度。”

进阶测试：

  • 多轮对话 ：使用相同的 sessionId 发送“那明天呢？”。智能体会利用记忆理解“明天”指的是“北京”的明天，并可能调用 getWeatherForecast 工具。
  • 模糊查询 ：发送“上海天气”，智能体会根据系统提示，调用 getWeatherAtCity 工具。
  • 无城市查询 ：发送“天气好吗？”，智能体会根据系统提示，反问“请问您想查询哪个城市的天气呢？”

5. 常见问题与排查思路

在集成过程中，你可能会遇到以下典型问题：

问题现象 常见原因 解决思路
启动报错： No qualifying bean of type ‘ChatClient’ 1. 未添加正确的Spring AI Starter依赖。
2. application.yml 中AI配置有误或缺失API Key。
3. 多个 ChatClient Bean存在冲突。 		1. 检查 pom.xml 依赖。
2. 检查 spring.ai.openai.api-key 或 spring.ai.alibaba.dashscope.api-key 配置，确保API Key有效。
3. 使用 @Primary 注解或在配置中指定 spring.ai.chat.client.type 。
调用模型时超时或连接失败 1. 网络问题，无法访问境外API（如OpenAI）。
2. 代理设置问题。
3. 模型名称拼写错误或不可用。 		1. 检查网络连通性。
2. 对于OpenAI，如需代理，可配置JVM参数或使用 spring.ai.openai.base-url 指向代理网关。
3. 核对官方文档，使用正确的模型名称。
LangChain4j Agent 不调用Tool 1. @Tool 注解的方法描述不够清晰。
2. 模型（如gpt-3.5-turbo）的推理能力不足以理解何时使用工具。
3. Tool未正确注册到 AiServices 中。 		1. 优化 @Tool 注解中的描述，确保清晰说明功能和参数。
2. 尝试使用更强大的模型（如gpt-4系列）。
3. 检查 AiServices.builder().tools(...) 是否传入了Tool Bean。
内存泄漏或OOM (OutOfMemoryError) 1. ChatMemory 存储了过多或过大的消息历史未清理。
2. 大文件上传处理不当（如图片、文档）。 		1. 使用 MessageWindowChatMemory 限制存储的消息条数。对于长期会话，考虑使用外部存储（如Redis）的持久化记忆实现。
2. 流式处理大文件，及时释放资源。
国产模型（通义千问）返回内容格式异常 1. 模型输出可能不符合OpenAI的默认消息格式。
2. Spring AI Alibaba 的HTTP客户端或解析器版本不兼容。 		1. 查阅Spring AI Alibaba官方文档，看是否有特殊的响应处理器或配置项。
2. 检查依赖版本，确保Spring AI Alibaba与Spring AI核心版本兼容。

6. 最佳实践与工程建议

将AI大模型集成到Java生产环境，除了功能实现，更需要关注稳定性、安全性和可维护性。

  1. 密钥与配置安全管理

    • 绝对禁止 将API Key硬编码在代码或配置文件中并提交到代码仓库。
    • 必须使用 环境变量、配置中心（如Nacos、Apollo）或云服务商提供的密钥管理服务（如KMS）。
    • 在 application.yml 中使用 ${VARIABLE_NAME:default_value} 语法引用环境变量。

  2. 超时、重试与熔断

    • 大模型API调用可能因网络或服务方不稳定而超时。务必配置合理的超时时间。 
    spring:
  ai:
    openai:
      client:
        connect-timeout: 10s
        read-timeout: 30s # 根据模型响应时间调整
    • 使用Spring Retry或Resilience4j为关键AI调用添加重试和熔断机制，提升系统韧性。

  3. 日志与监控

    • 为AI调用记录详细的日志，包括请求、响应（可脱敏）、耗时和Token使用量。这有助于成本分析和问题排查。
    • 集成Micrometer等监控工具，将AI调用的耗时、成功/失败次数等指标暴露给Prometheus和Grafana。

  4. 成本控制

    • 大模型API按Token收费。在非必要场景下，考虑使用更经济的模型（如 gpt-4o-mini vs gpt-4-turbo ）。
    • 合理设计系统提示词（System Prompt）和上下文，避免携带无关的历史消息，以减少输入的Token数量。
    • 对于内部知识库问答（RAG），使用高效的嵌入模型和向量数据库检索，只将最相关的上下文送给大模型。

  5. Agent与Tool的设计原则

    • 单一职责 ：每个Tool应只做一件事，并且做好。例如， 查询天气 、 搜索产品 、 计算折扣 应分开。
    • 清晰描述 ： @Tool 注解的描述和 @P 注解的参数描述要尽可能精确、无歧义，这是AI能否正确调用的关键。
    • 错误处理 ：Tool内部必须有健壮的错误处理（如网络异常、API限流），并返回对AI友好的错误信息，让AI能向用户解释或尝试其他方案。

  6. 版本管理与兼容性

    • Spring AI、LangChain4j等框架处于快速成长期，API变动可能较大。在项目中锁定稳定版本，升级前务必在测试环境充分验证。
    • 对于生产系统，建议将AI能力封装成独立的服务或模块，通过清晰的接口（如gRPC、REST）对外提供，降低与业务核心逻辑的耦合度。

掌握Java生态下的AI大模型开发，核心在于理解“框架是桥梁，工程化思维是基石”。从简单的 ChatClient 调用开始，逐步深入到复杂的Agent编排，每一步都离不开扎实的Java工程实践。本文提供的天气Agent案例是一个起点，你可以在此基础上，结合业务需求，集成数据库查询Tool、文档处理Tool、审批流程Tool等，构建出真正赋能业务的智能应用。

Logo
亚马逊云科技技术品牌专区

更多推荐

open-code-review Codex 插件教程：对话式调用评审技能指南

本文是一份面向新手的 **open-code-review Codex 插件教程**，教你在 Codex 中通过对话式方式调用 open-code-review 的 AI 代码评审技能。open-code-review 是阿里巴巴开源的 AI 代码评审工具，采用"确定性流水线 + LLM Agent"混合架构，内置多语言评审规则（NPE、线程安全、XSS、SQL 注入等），可在 Codex 里用一

avatar 亚马逊云科技技术品牌专区

OBS Studio 完整指南：免费开源录屏与直播软件从零上手

想做一场像模像样的直播，或者把屏幕内容录成教程视频，但一想到商用软件的订阅费就有些犹豫？其实你不需要花一分钱。OBS Studio 是一款免费开源的直播与录屏软件，支持 Windows、macOS 和 Linux，采集、混音、编码、推流、录制，一条流水线全包了。## 先搞清楚 OBS Studio 是什么OBS Studio 是一个"场景化"的采集合成工具：你把摄像头、窗口、浏览器、图片、

avatar 亚马逊云科技技术品牌专区

如何用MediaCrawler爬取小红书抖音数据？7大平台爬虫从安装到实战完整指南

MediaCrawler 是一个支持小红书、抖音、快手、B站、微博、百度贴吧、知乎的开源自媒体数据采集工具。它能按关键词、按帖子、按创作者主页三种方式抓取笔记/视频内容、评论甚至二级评论，并把结果存成 JSON、CSV、Excel 或数据库。适合做市场调研、竞品监控、内容选题的运营人员，以及想要现成爬虫框架而不想从零写 JS 逆向的开发者。## 从一次"手动抄数据"说起想象这个场景：你负责

avatar 亚马逊云科技技术品牌专区