Java开发者AI应用开发指南：Spring AI与Langchain4j实战

陈易铭

287人浏览 · 2026-06-29 12:59:32

陈易铭 · 2026-06-29 12:59:32 发布

这次我们来看一个面向Java开发者的AI大模型应用开发教程。这个教程的核心不是教你训练大模型，而是聚焦于如何利用现有的Spring AI、Spring AI Alibaba和Langchain4j等框架，快速将大模型能力集成到你的Java应用中。对于习惯了Spring生态的开发者来说，这可能是目前最直接、最“Java范儿”的AI应用入门路径。

教程内容涵盖了从基础概念到Agent实战的完整链条。最值得关注的点在于，它试图解决Java开发者面对AI时的几个核心痛点：如何选择框架、如何快速启动第一个AI应用、如何管理复杂的提示词（Prompt）、以及如何构建具备自主决策能力的智能体（Agent）。本文将带你梳理这套技术栈的核心能力、环境搭建步骤、并通过几个关键案例演示如何将AI功能真正“跑起来”。

无论你是想为现有系统增加一个智能客服模块，还是希望构建一个能自动处理文档的Agent，或者仅仅是想了解Java开发生态如何拥抱AI，这篇文章都会提供一套可落地的实操指南。我们会重点关注这几个框架的定位、如何选型、各自的启动方式、以及在实际编码中如何调用、如何观察效果和排查问题。

1. 核心能力速览

下表整理了Spring AI、Spring AI Alibaba和Langchain4j这三个核心框架的关键信息，帮助你快速判断哪个更适合你的项目。

能力项	Spring AI	Spring AI Alibaba	Langchain4j
项目定位	Spring官方出品，旨在为Spring生态提供统一的AI应用开发模型。	阿里云基于Spring AI的增强实现，深度集成阿里云百炼平台及通义千问等模型。	受Python LangChain启发，为Java设计的AI应用框架，更灵活、模块化。
核心功能	提供 `ChatClient` 、 `PromptTemplate` 、 `EmbeddingClient` 等抽象，支持多种模型供应商。	在Spring AI基础上，增加了对阿里云模型服务的原生支持、工作流编排和监控增强。	提供完整的Chain、Agent、Memory、Tool概念实现，支持本地模型与RAG。
启动方式	通过Spring Boot Starter引入，配置 `spring.ai.openai.api-key` 等属性即可启动。	类似Spring AI，需额外配置阿里云AK/SK及百炼平台相关参数。	可作为独立库引入，不强制依赖Spring，也可与Spring Boot无缝集成。
接口能力	主要面向同步/异步的聊天、嵌入生成、图像生成等标准化接口。	包含Spring AI所有能力，并扩展了工作流定义、执行等高级API。	提供低阶和高阶API，从直接调用模型到构建复杂Agent链均可覆盖。
批量任务	可通过 `StreamingChatClient` 进行流式响应，批量处理需自行封装循环或并行调用。	支持通过工作流引擎编排批量任务，具备更强的任务管理能力。	内置支持对文档列表进行批量向量化（Embedding）处理，易于构建RAG流水线。
适合场景	希望快速为Spring Boot应用添加AI能力，且追求官方支持和标准化的团队。	项目主要使用阿里云百炼或通义千问模型，需要利用阿里云特有功能和服务。	需要高度定制化AI应用逻辑，构建复杂Agent，或集成多种工具和记忆组件的场景。
硬件门槛	无特殊要求，本质是调用远程API。本地部署模型需依赖其他库（如Ollama）并自行准备GPU资源。	同Spring AI，调用云端服务无硬件要求。	同上，调用API无要求。若集成本地模型（如通过Ollama），则需要对应硬件支持。

2. 适用场景与使用边界

这套Java+AI教程主要适用于以下几类开发者：

传统Java后端开发者 ：希望以最小的学习成本，利用熟悉的Spring Boot技术栈接入AI能力。
全栈或应用开发者 ：正在构建需要AI功能（如智能对话、内容生成、文档总结）的Web应用或微服务。
系统架构师 ：评估如何将AI能力以服务化、模块化的方式嵌入现有企业技术架构中。
学生或研究者 ：想通过Java来快速验证AI应用原型，特别是与业务系统集成的场景。

它能解决什么问题？

快速集成 ：在几分钟内为一个Spring Boot应用配置好与大模型（如OpenAI GPT、通义千问）的对话能力。
提示词工程 ：通过模板化、参数化的方式管理复杂的提示词，提升可维护性。
构建智能体 ：创建能自动调用工具（如查询数据库、执行计算）的AI Agent，完成多步骤任务。
实现RAG ：结合向量数据库，让大模型能够基于自有知识库进行问答，减少“幻觉”。

它不适合什么场景？

大模型底层研发 ：如模型训练、微调、架构创新。这套教程是应用层开发。
对延迟和成本极度敏感的场景 ：每次调用都涉及网络请求和API费用，不适合超高频或实时性要求极高的内部处理。
完全离线的环境 ：虽然可以通过Langchain4j集成本地模型，但主流教程和案例仍围绕云端API展开。

合规与安全边界：

API密钥管理 ：务必通过环境变量或配置中心管理 api-key ，切勿硬编码在代码或提交至Git。
数据隐私 ：向第三方大模型API发送的数据需符合公司隐私政策和相关法律法规，敏感数据应做脱敏处理。
内容安全 ：应对AI生成的内容进行审核和过滤，避免产生有害、偏见或违规信息。
授权使用 ：确保使用的模型API服务是经过正式授权和购买的。

3. 环境准备与前置条件

开始编码前，请确保你的开发环境满足以下要求。这是保证后续所有示例能顺利运行的基础。

Java开发环境 ：
- JDK ：推荐使用 JDK 17 或更高版本。这是Spring Boot 3.x和大多数现代Java框架的基准要求。可以通过 java -version 命令验证。
- 构建工具 ：Maven (3.6+) 或 Gradle (7.x+)。本文示例将主要使用Maven。
- IDE ：IntelliJ IDEA（推荐）、Eclipse或VS Code with Java扩展。
Spring Boot项目 ：
- 你需要一个全新的或已有的Spring Boot项目。推荐使用 Spring Initializr 快速生成，选择Spring Boot 3.x版本。
模型API访问权限 ：
- OpenAI ：如果你打算使用GPT模型，需要准备一个有效的 OpenAI API Key 。
- 阿里云百炼/通义千问 ：如果你使用Spring AI Alibaba，需要拥有阿里云账号，并在百炼平台开通服务，获取AccessKey ID/Secret。
- 其他模型 ：如Anthropic Claude、Google Gemini等，需准备相应账号和API Key。
- 备用方案（本地） ：可以安装 Ollama ，在本地运行如 llama3 、 qwen 等开源模型，用于开发和测试，避免API费用。
网络条件 ：
- 确保你的开发机器能够稳定访问你所选模型供应商的API端点（如 api.openai.com ）。对于国内开发者，使用阿里云、智谱AI等国内服务通常网络更稳定。

4. 安装部署与启动方式

我们将分别介绍三个框架的集成方式。你可以根据选型，在项目的 pom.xml 中添加对应的依赖。

4.1 Spring AI 集成

在Spring Boot项目的 pom.xml 中添加Spring AI的Starter依赖。这里以使用OpenAI为例：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    <version>0.8.1</version> <!-- 请使用最新稳定版本 -->
</dependency>

然后，在 application.properties 或 application.yml 中配置你的API密钥和基础URL：

# application.properties
spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.openai.chat.options.model=gpt-3.5-turbo
# 如果你使用Azure OpenAI或其他兼容OpenAI API的代理，可以配置base-url
# spring.ai.openai.base-url=https://your-proxy.com/v1

启动你的Spring Boot应用。如果配置正确，应用将正常启动，Spring AI会自动配置好一个可注入的 ChatClient Bean。

4.2 Spring AI Alibaba 集成

Spring AI Alibaba的集成方式与Spring AI类似，但依赖和配置指向阿里云。

首先，添加依赖。请注意，你可能需要配置阿里云的Maven仓库。

<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-spring-boot-starter</artifactId>
    <version>1.0.0</version> <!-- 请使用最新版本 -->
</dependency>

接下来，配置阿里云的访问密钥和模型信息：

# application.properties
# 阿里云AccessKey
spring.cloud.ai.alibaba.access-key-id=${ALIBABA_ACCESS_KEY_ID}
spring.cloud.ai.alibaba.access-key-secret=${ALIBABA_ACCESS_KEY_SECRET}
# 百炼平台工作空间ID
spring.cloud.ai.alibaba.workspace-id=${BAILIAN_WORKSPACE_ID}
# 指定使用的模型，例如通义千问Max
spring.cloud.ai.alibaba.chat.options.model=qwen-max

同样，启动Spring Boot应用即可。

4.3 Langchain4j 集成

Langchain4j的集成更为灵活。如果你在Spring Boot项目中使用，可以添加以下依赖：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-spring-boot-starter</artifactId>
    <version>0.31.0</version> <!-- 请使用最新版本 -->
</dependency>
<!-- 选择具体的模型集成，例如OpenAI -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai</artifactId>
    <version>0.31.0</version>
</dependency>

配置方面，Langchain4j的配置项与Spring AI略有不同：

# application.properties
langchain4j.open-ai.chat-model.api-key=${OPENAI_API_KEY}
langchain4j.open-ai.chat-model.model-name=gpt-3.5-turbo
langchain4j.open-ai.chat-model.temperature=0.7

如果你不使用Spring Boot，也可以直接通过编程方式构建 ChatLanguageModel ，这体现了Langchain4j的灵活性。

5. 功能测试与效果验证

环境搭好后，我们通过几个核心功能点来验证集成是否成功。我们将创建简单的Spring Boot Controller进行测试。

5.1 基础对话测试

测试目的 ：验证最基本的与大模型的对话功能是否通畅。

操作步骤 ：

创建一个Spring MVC Controller。
注入 ChatClient （Spring AI）或 ChatLanguageModel （Langchain4j）。
编写一个接收提示词并返回模型响应的接口。

Spring AI 示例代码 ：

import org.springframework.ai.chat.ChatClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class SimpleChatController {

    private final ChatClient chatClient;

    public SimpleChatController(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    @GetMapping("/chat")
    public String chat(@RequestParam(value = "message", defaultValue = "Hello") String message) {
        // 调用ChatClient生成响应
        String response = chatClient.call(message);
        return response;
    }
}

Langchain4j 示例代码 ：

import dev.langchain4j.model.chat.ChatLanguageModel;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class SimpleChatController {

    private final ChatLanguageModel model;

    public SimpleChatController(ChatLanguageModel model) {
        this.model = model;
    }

    @GetMapping("/chat")
    public String chat(@RequestParam(value = "message", defaultValue = "Hello") String message) {
        String response = model.generate(message);
        return response;
    }
}

预期结果与验证 ：启动应用，访问 http://localhost:8080/chat?message=用Java写一个Hello World程序 。你应该能收到一个格式正确的Java代码片段。如果返回错误或超时，请检查：

API密钥配置是否正确。
网络是否能访问模型服务。
控制台是否有相关错误日志（如认证失败、额度不足）。

5.2 提示词模板测试

测试目的 ：验证是否能使用参数化提示词模板，这是构建复杂应用的基础。

操作步骤 ：

定义一个包含占位符（如 {topic} ）的提示词模板。
在调用时传入参数替换占位符。

Spring AI 示例 ：

import org.springframework.ai.chat.ChatClient;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.chat.prompt.PromptTemplate;
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 TemplateChatController {

    private final ChatClient chatClient;

    public TemplateChatController(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    @GetMapping("/generatePoem")
    public String generatePoem(@RequestParam String thing) {
        // 定义模板
        String template = "请为{thing}写一首五言绝句。";
        PromptTemplate promptTemplate = new PromptTemplate(template);
        // 渲染模板，生成最终的Prompt对象
        Prompt prompt = promptTemplate.create(Map.of("thing", thing));
        // 调用模型
        return chatClient.call(prompt).getResult().getOutput().getContent();
    }
}

访问 http://localhost:8080/generatePoem?thing=月亮 ，应收到一首关于月亮的诗。

5.3 流式响应测试

测试目的 ：验证是否支持流式（Streaming）响应，这对于需要实时显示生成内容的场景（如聊天界面）至关重要。

操作步骤 ：

使用支持流式响应的客户端，如 StreamingChatClient 。
返回一个 Flux 或 ResponseBodyEmitter ，将生成的token逐个发送给前端。

Spring AI 流式响应示例 ：

import org.springframework.ai.chat.messages.UserMessage;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.chat.streaming.StreamingChatClient;
import org.springframework.core.ParameterizedTypeReference;
import org.springframework.http.MediaType;
import org.springframework.http.codec.ServerSentEvent;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Flux;

@RestController
public class StreamingChatController {

    private final StreamingChatClient streamingChatClient;

    public StreamingChatController(StreamingChatClient streamingChatClient) {
        this.streamingChatClient = streamingChatClient;
    }

    @GetMapping(value = "/streamChat", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<ServerSentEvent<String>> streamChat(@RequestParam String message) {
        Prompt prompt = new Prompt(new UserMessage(message));
        return streamingChatClient.stream(prompt)
                .map(content -> ServerSentEvent.builder(content).build());
    }
}

使用浏览器或 curl 访问这个端点，可以看到数据像水流一样一段段返回。

5.4 智能体（Agent）与工具（Tool）测试

测试目的 ：验证是否能构建一个可以自主调用外部工具（如查询天气、计算）的AI智能体。这是Langchain4j的强项。

操作步骤 ：

定义一个工具类和方法，用 @Tool 注解标记。
创建一个 Agent ，并将工具注册给它。
向Agent提问，观察它是否能正确规划并调用工具完成任务。

Langchain4j Agent 示例 ：

import dev.langchain4j.agent.tool.Tool;
import dev.langchain4j.memory.chat.MessageWindowChatMemory;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.AiServices;
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 {

    interface Assistant {
        String chat(String userMessage);
    }

    // 1. 定义一个工具
    static class Calculator {
        @Tool(“计算两个数字的和”)
        public int add(int a, int b) {
            System.out.println(“工具被调用: add(” + a + “, ” + b + “)”);
            return a + b;
        }
    }

    // 2. 创建并配置Agent
    private final Assistant assistant;

    public AgentController() {
        this.assistant = AiServices.builder(Assistant.class)
                .chatLanguageModel(OpenAiChatModel.withApiKey(System.getenv(“OPENAI_API_KEY”)))
                .tools(new Calculator()) // 注册工具
                .chatMemory(MessageWindowChatMemory.withMaxMessages(10))
                .build();
    }

    @GetMapping(“/askAgent”)
    public String askAgent(@RequestParam String question) {
        // 3. 向Agent提问
        return assistant.chat(question);
    }
}

访问 http://localhost:8080/askAgent?question=123加456等于多少？ 。观察控制台日志，你应该能看到 工具被调用: add(123, 456) 的输出，并且接口返回最终结果 579 。这证明Agent成功理解了问题，并调用了正确的工具。

6. 接口API与批量任务

6.1 标准化API服务

上述测试中创建的Controller已经构成了最简单的AI API服务。在实际项目中，你需要：

定义清晰的DTO ：为请求和响应设计标准格式，包括提示词、参数、会话ID等。
添加认证与鉴权 ：使用Spring Security保护你的AI端点。
实现限流与降级 ：防止滥用，并在模型服务不可用时提供备用方案。

6.2 批量任务处理

对于需要处理大量独立任务的场景（如批量总结100篇文档），简单的循环调用API效率低下且易触发限流。

推荐方案 ：

异步处理 ：使用 @Async 注解或 CompletableFuture 并发调用，但需注意模型供应商的并发限制。
消息队列 ：将任务放入RabbitMQ、Kafka等消息队列，由消费者服务异步处理并存入数据库。这是最健壮的方式。
Spring Batch ：如果任务是结构化的ETL流程（读取->AI处理->写入），可以使用Spring Batch框架。

示例：使用 @Async 进行简单并发处理

import org.springframework.ai.chat.ChatClient;
import org.springframework.scheduling.annotation.Async;
import org.springframework.scheduling.annotation.EnableAsync;
import org.springframework.stereotype.Service;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import java.util.stream.Collectors;

@Service
@EnableAsync
public class BatchProcessingService {

    private final ChatClient chatClient;

    public BatchProcessingService(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    @Async
    public CompletableFuture<String> processSingleItem(String content) {
        String prompt = “请总结以下内容：” + content;
        String summary = chatClient.call(prompt);
        return CompletableFuture.completedFuture(summary);
    }

    public List<String> processBatch(List<String> contents) {
        List<CompletableFuture<String>> futures = contents.stream()
                .map(this::processSingleItem)
                .collect(Collectors.toList());

        // 等待所有任务完成
        CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();

        return futures.stream()
                .map(CompletableFuture::join)
                .collect(Collectors.toList());
    }
}

重要提醒 ：批量调用时务必遵守模型服务的速率限制，并考虑增加指数退避等重试机制。

7. 资源占用与性能观察

由于这三个框架主要作为远程API的客户端，其本身的资源消耗（CPU、内存）很低，性能瓶颈主要在网络I/O和模型API的响应速度上。

内存占用 ：一个典型的Spring Boot应用集成这些框架后，内存增量很小（主要来自框架本身的类加载）。关注点应放在应用堆内存的常规优化上。
CPU占用 ：序列化/反序列化JSON请求和响应会消耗少量CPU，通常不是问题。
网络I/O ：这是主要性能因素。使用 curl 或 Postman 测试单个API调用的延迟，并关注超时设置。
- 连接超时 ：建立连接的最大等待时间。
- 读取超时 ：等待服务器响应的最大时间。
- 在 application.properties 中配置（以Spring AI OpenAI为例）：
```
spring.ai.openai.client.connection-timeout=10s
spring.ai.openai.client.read-timeout=60s
```
监控与观测 ：
- 日志级别 ：将 org.springframework.ai 和 dev.langchain4j 的日志级别设置为 DEBUG ，可以查看详细的请求和响应信息，用于调试，但生产环境建议设为 WARN 或 ERROR 。
- 应用监控 ：集成Micrometer和Prometheus，监控AI接口的请求量、延迟和错误率。
- 链路追踪 ：使用Sleuth/Zipkin追踪AI调用在整个微服务链路中的性能。

8. 常见问题与排查方法

问题现象	可能原因	排查方式	解决方案
应用启动失败，报错 `BeanCreationException`	1. 依赖缺失或版本冲突。 2. 配置属性错误（如 `api-key` 为空）。 3. 网络无法访问模型服务。	1. 检查 `pom.xml` 依赖树。 2. 检查 `application.properties` 配置，确认环境变量已设置。 3. 使用 `curl` 或 `ping` 测试网络连通性。	1. 统一管理依赖版本。 2. 确保配置项名称正确且值有效。 3. 配置代理或使用国内模型服务。
调用接口返回 `401 Unauthorized`	API密钥无效、过期或格式错误。	检查控制台日志，确认发送的请求头中 `Authorization` 字段是否正确。	重新生成API密钥，确保复制完整，无多余空格。
调用接口返回 `429 Too Many Requests`	触发了模型API的速率限制。	查看响应头中的 `Retry-After` 信息。	1. 降低调用频率，实现请求队列。 2. 申请提升速率限制（如有）。 3. 实现带退避机制的重试逻辑。
请求超时（ReadTimeout）	1. 提示词过长或模型计算复杂。 2. 网络延迟高或不稳定。 3. 模型服务端负载高。	1. 检查提示词长度。 2. 测试网络到API端点的延迟。 3. 查看模型服务商状态页。	1. 增加 `read-timeout` 配置（如120s）。 2. 优化提示词，分拆复杂任务。 3. 考虑使用响应更快的模型。
Agent不调用工具	1. 工具方法描述（ `@Tool` 注解）不清晰。 2. 模型（如gpt-3.5-turbo）的推理能力不足以规划工具调用。 3. 提示词未引导模型使用工具。	1. 检查工具方法的 `@Tool` 注解描述是否准确。 2. 尝试使用更强大的模型（如gpt-4）。 3. 在系统提示词中明确要求使用工具。	1. 为工具方法编写清晰、具体的描述。 2. 升级模型或优化Agent的提示词工程。 3. 开启Langchain4j的详细日志，观察模型思考过程。
流式响应不工作或中断	1. 客户端（如浏览器）不支持Server-Sent Events (SSE)。 2. 代理服务器或网关过滤了SSE流。 3. 连接过早被关闭。	1. 使用 `curl` 或专用工具测试SSE端点。 2. 检查Nginx等代理配置，确保支持 `proxy_buffering off` 等。	1. 确保前端使用 `EventSource` 或兼容库。 2. 配置网关正确透传SSE。 3. 检查服务端是否有超时设置中断了连接。

9. 最佳实践与使用建议

配置外部化与安全 ：
- 绝不硬编码 ：API密钥、端点等敏感信息必须通过环境变量、配置中心或密钥管理服务注入。
- 使用Profile ：利用Spring的 application-{profile}.properties 为开发、测试、生产环境配置不同的模型和参数。
提示词工程与管理 ：
- 模板化 ：将提示词抽取为模板文件或数据库存储，便于维护和A/B测试。
- 版本化 ：对重要的业务提示词进行版本控制。
- 系统提示词 ：为Agent设置清晰的系统角色和边界，能显著提升回答质量和安全性。
容错与稳定性 ：
- 重试机制 ：对于网络抖动或API限流导致的临时失败，实现带指数退避的重试。
- 熔断降级 ：使用Resilience4j或Sentinel，当模型服务连续失败时快速熔断，并降级到备用方案（如返回缓存、简化逻辑）。
- 超时控制 ：为所有AI调用设置合理的超时时间，避免线程阻塞。
成本与性能优化 ：
- 缓存：对内容固定或更新不频繁的AI生成结果（如商品描述模板）进行缓存。
- 模型选型 ：非关键场景或简单任务，使用成本更低的模型（如 gpt-3.5-turbo 而非 gpt-4 ）。
- 异步与批处理 ：如第6.2节所述，合理利用异步和批处理提升吞吐量。
可观测性 ：
- 记录输入输出 ：在非隐私敏感的前提下，记录重要的请求和响应日志，用于效果分析和问题回溯。注意脱敏。
- 监控关键指标 ：QPS、平均响应时间、错误率、Token消耗量（如果API提供）。