1. 先搞清楚 Java 连接 AI 大模型到底要解决什么问题

如果你是一个 Java 后端开发者，看到“AI大模型”、“Spring AI”、“Langchain4j”这些词，第一反应可能是：这和我平时写的 CRUD、微服务有什么关系？是不是又要学 Python 了？

其实关系很大，而且现在正是切入的好时机。这个主题的核心，是解决 “如何在你熟悉的 Java 技术栈里，安全、高效、可维护地集成和使用各类 AI 大模型能力” 。它不是为了让你去从头训练一个模型，而是让你能像调用一个数据库服务或消息队列一样，去调用大模型的对话、文生图、文档分析、智能体决策等能力。

为什么说现在时机好？因为生态正在成熟。早期 Java 开发者想用大模型，要么绕道 Python 写服务再通过 HTTP 调用，要么自己封装复杂的 HTTP 客户端，调试、流式响应、上下文管理都非常麻烦。现在，像 Spring AI、Spring AI Alibaba、Langchain4j 这样的框架，正在把这件事标准化、Spring 化。它们帮你封装了与不同大模型厂商（OpenAI、通义千问、DeepSeek等）的通信细节，提供了统一的模板和接口，让你能用写 Spring Boot 应用的习惯，来开发 AI 增强功能。

所以，这篇文章适合两类人看：

1. Java 后端开发者 ：想在自己的 Spring Boot 项目中快速增加 AI 功能，比如智能客服、文档摘要、代码辅助、数据洞察等，但不想深入 Python 生态。
2. 技术决策者或架构师 ：在评估如何将 AI 能力落地到现有 Java 技术体系中，需要了解主流方案、优缺点和落地成本。

最值得你关注的，不是某个框架的 API 列表，而是这三个核心问题的答案：

1. Spring AI、Spring AI Alibaba、Langchain4j 到底有什么区别？我该选哪个？
2. 从零开始，把一个 AI 对话功能集成到 Spring Boot 项目里，具体的步骤和坑点是什么？
3. 除了简单的对话，更复杂的场景如智能体（Agent）、检索增强生成（RAG）怎么实现？

下面，我就以一个实际集成者的视角，带你走一遍从技术选型到案例实战的完整路径。我会假设你有一个干净的 Spring Boot 3.x 项目，目标是接入一个国产大模型（比如通义千问），并实现一个能联网搜索的智能体。

2. 技术选型：Spring AI vs Spring AI Alibaba vs Langchain4j

面对这三个选项，很多人会懵。我的建议是： 不要只看名字，要看它们背后的设计理念和适用场景 。你可以把它们理解为不同层次的抽象。

2.1 Spring AI：Spring 官方的“大一统”尝试

Spring AI 是 Spring 官方项目，目标是为 AI 应用提供一套跨模型的、一致的 Spring 风格编程模型。它的核心思想是 “抽象” 。

• 优点 ：
  • 官方背书，生态整合好 ：与 Spring Boot、Spring Security 等无缝集成，配置方式非常“Spring”，比如用 application.yml 配 API Key。
  • 模型无关 ：定义了一套通用的 ChatClient 、 EmbeddingClient 等接口。今天你用 OpenAI，明天想换通义千问，理论上只需要改配置，业务代码不用动。
  • 功能全面 ：不仅支持聊天，还支持文生图、语音、嵌入向量、评估等，正在快速迭代。
• 缺点/注意点 ：
  • 相对较新 ：虽然发展快，但某些高级功能（如复杂的 Agent 工作流）可能不如 Langchain4j 成熟。
  • 抽象可能带来复杂度 ：为了统一，它的 API 设计有时会牺牲一些特定模型的独有特性。
  • 版本注意 ：Spring AI 的 API 在 1.0 版本前后有较大变化，学习时务必确认文档版本。

适合谁 ：希望紧跟 Spring 生态，项目需要接入多个模型或未来可能切换模型，喜欢“配置即代码”风格的团队。

2.2 Spring AI Alibaba：阿里云模型的“专属优化套件”

这是阿里云为 Spring AI 生态提供的扩展组件。你可以把它理解为 “Spring AI 针对阿里云百炼/灵积平台模型的官方实现和增强包” 。

• 优点 ：
  • 开箱即用 ：如果你确定使用通义千问、通义视觉等阿里云模型，用这个是最直接、最省事的。它封装了阿里云 API 的所有特性。
  • 功能对齐 ：完美支持阿里云模型独有的功能，如千问的联网搜索、长文本处理等。
  • 与 Spring AI 兼容 ：它实现了 Spring AI 的标准接口，因此你既可以用 Spring AI 的通用方式调用，也可以用它的增强功能。
• 缺点/注意点 ：
  • 厂商锁定 ：主要服务于阿里云模型。虽然也支持部分开源模型，但核心优势在阿里系。
  • 依赖阿里云 ：需要开通阿里云账号、获取 AK/SK，模型调用产生费用。

适合谁 ：项目已经或计划部署在阿里云，主要使用通义系列模型，希望获得最佳兼容性和性能的团队。

2.3 Langchain4j：来自 Python 生态的“概念本地化”

Langchain4j 是著名 Python 框架 LangChain 的 Java 版本。它的核心思想是 “组件链” 和 “智能体” 。

• 优点 ：
  • 概念成熟，模式丰富 ：直接将 Python 生态中验证过的 RAG、Agent、Tool 使用等高级模式引入 Java。如果你想做复杂的 AI 应用（比如让 AI 使用工具、查询数据库、执行代码），Langchain4j 的抽象更直接。
  • 社区活跃，示例多 ：由于背靠 LangChain 生态，有很多现成的模式和社区案例可以参考。
  • 灵活度高 ：它不强制依赖 Spring，可以独立使用，也可以与 Spring 集成。
• 缺点/注意点 ：
  • 学习曲线 ：需要理解 Prompt Template、Chain、Agent、Tool、Memory 等一套新概念，对纯 Java 后端开发者可能有点陌生。
  • 与 Spring 整合度 ：虽然能整合，但不如 Spring AI 那样原生和深度。
  • 版本迭代快 ：API 也可能随着 Python 版 LangChain 的变化而调整。

适合谁 ：需要实现复杂 AI 工作流（如自主决策的智能体、复杂的文档问答系统），不介意学习一套新概念，或者团队已有 LangChain (Python) 经验想平移到 Java 的开发者。

2.4 怎么选？一张表帮你决策

特性	Spring AI	Spring AI Alibaba	Langchain4j
核心定位	Spring 生态的 AI 统一接口	阿里云模型的 Spring AI 最佳实践	Java 版的 LangChain，专注链与智能体
编程模型	Spring 风格（Template, Client）	Spring 风格 + 阿里云扩展	LangChain 风格（Chain, Agent, Tool）
模型支持	广泛（OpenAI, Azure, Ollama等）	聚焦阿里云，兼容 Spring AI	广泛（通过多种 Adapter）
高级功能	正在完善中	深度集成阿里云特色功能	非常成熟 （RAG, Agent, Tool 使用）
学习成本	低（如果你熟悉 Spring）	低（在 Spring AI 基础上）	中高 （需学习新概念）
最佳场景	多模型切换、简单的 AI 集成	深度使用阿里云通义模型	复杂的、需要推理和工具调用的 AI 应用

我的建议 ：

• 新手入门，业务简单 ：从 Spring AI 开始。它最符合 Java 开发者的直觉，能快速让你看到效果。
• 认准阿里云模型 ：直接上 Spring AI Alibaba ，省心省力。
• 要做“聪明”的 AI 应用 ：比如让 AI 根据问题决定是查数据库还是调用 API，那就认真考虑 Langchain4j 。

为了覆盖更广的场景，下面的实战演示，我会选择 Spring AI Alibaba 来接入模型（展示与云服务的集成），并在高级部分引入 Langchain4j 的概念来实现一个智能体（展示复杂工作流）。这样你既能快速上手，又能看到更远的方向。

3. 环境准备与基础集成：让 Spring Boot 学会“说话”

理论说完，我们动手。假设你已经有一个 Spring Boot 3.2+ 的项目（如果没有，用 start.spring.io 生成一个，依赖选 Web、Lombok）。

3.1 第一步：引入依赖与配置

如果你决定用 Spring AI Alibaba，首先需要添加依赖。注意版本匹配，这里以当前稳定的版本为例。

在你的 pom.xml 中添加：

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-ai-alibaba-spring-boot-starter</artifactId>
    <version>2023.0.1.0</version> <!-- 请检查最新版本 -->
</dependency>

然后，去 阿里云百炼平台 或 灵积平台 开通服务，获取 API-KEY 。模型服务通常有免费额度，足够学习和测试。

接下来，在 application.yml 中配置：

spring:
  ai:
    alibaba:
      chat:
        # 从阿里云控制台获取
        api-key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        # 选择模型，例如通义千问最新版
        model: qwen-max
        # 可选：设置代理（如果你的网络需要）
        # client:
        #   connect-timeout: 10s
        #   read-timeout: 30s
      # 如果你还需要 Embedding 等功能，可以配置 embedding 等选项

关键点解释 ：

• api-key ：这是最重要的，不要提交到代码仓库，建议用环境变量 SPRING_AI_ALIBABA_CHAT_API_KEY 注入。
• model ：模型名称。不同模型能力、价格不同。 qwen-max 是能力较强的版本， qwen-plus 是性价比版本， qwen-turbo 是速度更快的版本。根据你的需求选择。
• timeout ： 务必设置 。大模型响应有时较慢，合理的超时设置（如30秒）可以防止 HTTP 线程被无限占用。

3.2 第二步：编写第一个对话服务

配置好后，Spring AI Alibaba 会自动为你配置一个 ChatClient Bean。我们来创建一个简单的 Service。

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

@Service
@RequiredArgsConstructor
public class SimpleChatService {

    private final ChatClient chatClient;

    public String chat(String message) {
        // 这是最基础的调用方式
        return chatClient.prompt()
                .user(message) // 用户消息
                .call()        // 执行调用
                .content();    // 获取文本回复
    }
}

然后写一个 Controller 来暴露接口：

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

@RestController
@RequestMapping("/ai")
@RequiredArgsConstructor
public class ChatController {

    private final SimpleChatService chatService;

    @PostMapping("/chat")
    public String chat(@RequestBody ChatRequest request) {
        return chatService.chat(request.getMessage());
    }

    // 简单的请求体
    public record ChatRequest(String message) {}
}

启动应用，用 Postman 或 curl 测试：

curl -X POST http://localhost:8080/ai/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "用Java写一个Hello World程序"}'

如果一切顺利，你将收到大模型的回复。恭喜，你的 Java 应用已经具备了 AI 对话能力！

第一个避坑点 ：如果启动报错，比如 No qualifying bean of type 'ChatClient' ，请检查：

1. 依赖是否正确引入。
2. application.yml 中的 spring.ai.alibaba.chat.api-key 配置是否正确。
3. 网络是否能正常访问阿里云 API 端点（有时需要配置网络代理）。

3.3 第三步：进阶使用 - 流式响应与系统提示词

上面的例子是同步阻塞调用，用户要等模型完全生成完才能看到结果。对于长文本，体验不好。我们需要 流式响应 。

修改 Service，返回一个 Flux （Spring WebFlux 响应式编程）：

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.model.Generation;
import org.springframework.stereotype.Service;
import reactor.core.publisher.Flux;
import lombok.RequiredArgsConstructor;

@Service
@RequiredArgsConstructor
public class StreamingChatService {

    private final ChatClient chatClient;

    public Flux<String> streamChat(String message) {
        return chatClient.prompt()
                .user(message)
                .stream() // 关键：使用 stream() 而不是 call()
                .content(); // 返回 Flux<String>
    }
}

Controller 也需要调整为返回 text/event-stream ：

import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import lombok.RequiredArgsConstructor;
import reactor.core.publisher.Flux;

@RestController
@RequestMapping("/ai")
@RequiredArgsConstructor
public class ChatController {

    private final StreamingChatService streamingChatService;

    @PostMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> streamChat(@RequestBody ChatRequest request) {
        return streamingChatService.streamChat(request.getMessage());
    }
}

前端可以通过 SSE (Server-Sent Events) 来接收这个流，实现打字机效果。

第二个关键点：系统提示词 。这决定了 AI 的“角色”和回答风格。比如，你想让它扮演一个 Java 代码审查专家：

public String codeReview(String code) {
    return chatClient.prompt()
            .system("""
                    你是一个资深的Java代码审查专家。你的任务是：
                    1. 找出代码中的潜在bug、性能问题和坏味道。
                    2. 提供具体的修改建议和最佳实践。
                    3. 用简洁、专业的语言回复。
                    请直接对提供的代码进行审查。
                    """)
            .user(code)
            .call()
            .content();
}

系统提示词是控制 AI 行为最有效的手段之一，务必花时间精心设计。

4. 从单次对话到智能体：引入 Langchain4j 实现复杂逻辑

基础对话满足了简单需求。但真正的“智能”在于让 AI 能根据情况 自主使用工具 。比如，用户问“今天北京天气怎么样？”，AI 应该能自己去调用一个天气查询 API，而不是仅凭训练数据瞎猜。这就是 智能体 的核心。

这里，我们将结合 Langchain4j 的概念，在 Spring 项目中实现一个简单的工具调用智能体。虽然 Spring AI 也在增强 Agent 支持，但用 Langchain4j 来演示这一模式更为经典。

4.1 引入 Langchain4j 依赖

首先，添加 Langchain4j 的依赖。注意，它和 Spring AI Alibaba 可以共存。

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j</artifactId>
    <version>0.31.0</version> <!-- 请检查最新版本 -->
</dependency>
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-spring-boot-starter</artifactId>
    <version>0.31.0</version>
</dependency>

我们需要一个模型来驱动智能体。为了简化，我们可以继续使用阿里云的模型，但需要通过 Langchain4j 的适配器来接入。这里我们使用一个更通用的方式： 假设我们有一个实现了 ChatLanguageModel 接口的 Bean 。我们可以用 Spring AI 的 ChatClient 来包装一个。

4.2 创建工具：让 AI 有“手”

智能体通过“工具”与外界交互。我们先定义一个简单的工具，比如一个计算器：

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

@Component
public class CalculatorTool {

    @Tool("用于计算两个数字的和") // @Tool 注解让 Langchain4j 能识别它
    public double add(double a, double b) {
        return a + b;
    }

    @Tool("用于计算两个数字的乘积")
    public double multiply(double a, double b) {
        return a * b;
    }
}

再定义一个查询当前时间的工具（模拟外部服务）：

import dev.langchain4j.agent.tool.Tool;
import org.springframework.stereotype.Component;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

@Component
public class TimeTool {

    @Tool("获取当前的日期和时间")
    public String getCurrentTime() {
        return LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));
    }
}

4.3 构建智能体服务

现在，我们来创建一个服务，将这些工具装配给 AI，并让 AI 自主决定何时使用。

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 dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;
import dev.langchain4j.service.tool.ToolExecutionRequest;
import jakarta.annotation.PostConstruct;
import lombok.extern.slf4j.Slf4j;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Service;
import java.util.List;

@Service
@Slf4j
public class AgentService {

    // 1. 定义一个智能体接口
    interface Assistant {
        @SystemMessage("你是一个乐于助人的助手，可以回答问题和使用工具进行计算或查询时间。当你被问到需要计算或获取当前时间时，请务必使用工具。")
        String chat(String userMessage);
    }

    private Assistant assistant;

    // 2. 注入 ChatClient (来自 Spring AI Alibaba) 和工具 Bean
    private final ChatClient chatClient;
    private final CalculatorTool calculatorTool;
    private final TimeTool timeTool;

    public AgentService(ChatClient chatClient, CalculatorTool calculatorTool, TimeTool timeTool) {
        this.chatClient = chatClient;
        this.calculatorTool = calculatorTool;
        this.timeTool = timeTool;
    }

    // 3. 初始化：将 Spring AI 的 ChatClient 适配为 Langchain4j 的 ChatLanguageModel
    @PostConstruct
    public void init() {
        // 这是一个简单的适配器，将 ChatClient 调用转换为 Langchain4j 模型调用
        ChatLanguageModel model = (messages) -> {
            // 取最后一条用户消息（简化处理）
            String userMessage = messages.get(messages.size() - 1).text();
            String response = chatClient.prompt()
                    .messages(messages) // 传入完整的消息历史
                    .call()
                    .content();
            return response;
        };

        // 4. 使用 AiServices 创建智能体，并绑定工具和模型
        this.assistant = AiServices.builder(Assistant.class)
                .chatLanguageModel(model)
                .tools(calculatorTool, timeTool) // 注册工具
                .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) // 给点记忆
                .build();
    }

    public String invokeAgent(String userInput) {
        log.info("用户问题: {}", userInput);
        String response = assistant.chat(userInput);
        log.info("助手回复: {}", response);
        return response;
    }
}

4.4 测试智能体

创建一个测试 Controller：

@RestController
@RequiredArgsConstructor
@RequestMapping("/agent")
public class AgentController {
    private final AgentService agentService;

    @PostMapping("/ask")
    public String ask(@RequestBody String question) {
        return agentService.invokeAgent(question);
    }
}

现在，你可以问它：

• “123 加 456 等于多少？” -> 它会调用 CalculatorTool.add 。
• “现在几点了？” -> 它会调用 TimeTool.getCurrentTime 。
• “先计算 7 乘以 8，然后告诉我现在的时间。” -> 它会 连续调用两个工具 。

查看日志，你会看到类似这样的信息，表明工具被正确调用和传参了（实际日志取决于你的适配器实现和模型返回）。这就是智能体的雏形：AI 分析你的意图，决定调用哪个工具，传入正确参数，然后整合结果回复给你。

核心收获 ：通过 Langchain4j 的 @Tool 注解和 AiServices ，我们能以一种声明式的方式，将任何 Java 方法“暴露”给 AI 作为工具。AI 的“思考”过程（是否用工具、用哪个、参数是什么）是由大模型完成的。

5. 生产环境考量与常见问题排查

把 Demo 跑起来只是第一步。要真正用到生产环境，你必须关注以下几个关键点。

5.1 成本、限流与降级

• 成本控制 ：大模型 API 调用是按 Token 收费的。务必在代码中估算输入输出 Token 数（各厂商 SDK 通常提供工具方法）。对于非关键路径，考虑使用更便宜的模型（如 qwen-turbo ）。设置预算告警。
• 限流与重试 ：所有云厂商都有速率限制。在客户端必须实现 重试机制 （通常用指数退避）和 熔断降级 （如 Hystrix 或 Resilience4j）。Spring AI 的 ChatClient 可以配置重试，但复杂的熔断需要自己集成。
• 降级方案 ：当大模型服务不可用或响应超时时，要有备选方案。例如，智能客服可以先返回一个预设的常见问题列表，或者将问题存入队列稍后处理。

5.2 稳定性与监控

• 超时设置 ：如前所述，必须设置合理的连接和读取超时。对于流式响应，可能需要更长的超时或使用心跳机制。
• 上下文长度 ：模型有最大 Token 限制（如 8K、32K、128K）。在构建长对话或处理长文档时，需要设计 上下文窗口管理策略 ，例如只保留最近 N 轮对话，或对历史消息进行摘要。
• 监控与日志 ：
  • 记录每次调用的模型、输入 Token 数、输出 Token 数、耗时和费用 。这是成本分析和性能优化的基础。
  • 记录完整的请求和响应（注意脱敏敏感信息），便于排查问题。
  • 监控 API 调用错误率、延迟和 Token 消耗速率。

5.3 常见错误排查清单

当你的 AI 集成出问题时，按这个顺序排查：

1. 认证失败 ( 401 , 403 )
   • 检查 api-key 或 access token 是否过期、失效或配置错误。
   • 检查 AK/SK 环境变量是否生效。
2. 网络连接问题 ( Connection refused , Timeout )
   • 检查本地网络是否能访问模型服务商端点。
   • 检查是否配置了正确的网络代理（如果需要）。
   • 增大 connect-timeout 和 read-timeout 。
3. 模型调用错误 ( 400 Bad Request , Model not found )
   • 检查 model 参数名称是否正确，是否在你所在区域可用。
   • 检查请求体格式是否符合该模型 API 的要求（Spring AI 通常已处理）。
   • 检查输入内容是否过长，超过了模型上下文限制。
4. 依赖冲突或版本不匹配
   • 检查 Spring Boot、Spring AI、Spring AI Alibaba、Langchain4j 的版本兼容性。查看官方文档的版本说明。
   • 使用 mvn dependency:tree 查看是否有冲突的库。
5. 流式响应中断
   • 检查客户端（如浏览器）是否支持 SSE。
   • 检查是否有网关、代理或防火墙中断了长连接。
   • 服务端检查是否在流结束前关闭了连接。

5.4 进阶方向：RAG 与复杂工作流

当你掌握了基础对话和简单工具调用后，可以探索更强大的模式：

• RAG ：这是让 AI 基于你提供的专有资料（非公开数据）回答问题的关键技术。核心步骤：
  1. 文档加载与切分 ：将 PDF、Word、网页等文件加载并切成语义片段。
  2. 向量化 ：使用 EmbeddingClient 将片段转换为向量。
  3. 存储与检索 ：将向量存入向量数据库（如 Milvus, Redis, PGVector）。
  4. 增强生成 ：用户提问时，先检索相关片段，再将片段和问题一起发给大模型生成答案。 Spring AI 和 Langchain4j 都提供了高级的 RAG 抽象，可以大幅简化开发。
• 复杂工作流 ：类似于“低代码”中的工作流，你可以用代码定义 AI 任务的执行顺序、条件分支和循环。Spring AI 的 Agent 模块和 Langchain4j 的 Chain 就是为此设计的。例如，一个用户反馈处理流程：AI 先分类 -> 如果是 bug，提取关键信息创建 JIRA -> 如果是咨询，从知识库检索答案 -> 最后生成回复。

6. 总结：从集成到创造

回过头看，Java 生态接入 AI 大模型的路径已经非常清晰。 Spring AI 提供了标准的“插座” ，让你用统一的方式接入电力（各种模型）。 Spring AI Alibaba 提供了一个品牌“电器” （阿里云模型）的最佳适配器。而 Langchain4j 提供了一套“智能家居”的蓝图 ，告诉你如何把电器、传感器、开关联动起来，实现自动化。

对于大多数 Java 团队，我的落地建议是：

1. 从 Spring AI 开始 ，快速验证核心场景。用最少的代码看看大模型能否解决你的问题。
2. 深入使用系统提示词和少量示例 ，这是提升 AI 回答质量性价比最高的方法。
3. 当需要 AI 与你的业务系统（数据库、API）交互时，引入 Langchain4j 的工具调用能力 。
4. 在投入生产前，务必完成成本监控、限流降级和日志审计 这三件套。

AI 集成不再是 Python 的专利。在你的 Java 技术栈里，它正在变成一个像连接数据库、发送消息一样的标准能力。关键不是追求最炫酷的框架，而是想清楚你要用 AI 解决什么具体的业务问题，然后选择最直接、最可维护的路径把它实现出来。