Spring AI Alibaba 入门实战：Java 开发者如何快速构建第一个 AI 应用

Spring AI Alibaba 入门实战：Java 开发者如何快速构建第一个 AI 应用

在过去很长一段时间里，AI 应用开发似乎更偏向 Python 生态：LangChain、LangGraph、各类 Agent SDK、向量库集成，几乎都默认 Python 是"第一语言"。

但对很多 Java 团队来说，真正的业务系统、网关、流程引擎、权限体系、消息链路、监控治理，依旧是 Spring 体系的主场。这个时候，一个核心问题就出现了：

能不能用 Java 原生方式，把大模型能力真正接进现有业务系统，而不是只做几个 Demo？

Spring AI 和 Spring AI Alibaba，正是在解决这个问题。

Spring AI 提供的是统一的 AI 抽象能力，比如模型调用、Prompt、Tool、Memory、RAG、MCP 等；而 Spring AI Alibaba 则在这个基础上，进一步补足了通义生态接入、Agent Framework、Graph 编排、多智能体工作流、企业级集成等能力。官方文档也明确将其定位为一个面向 Java 开发者的 Agentic AI Framework。

一、为什么是 Spring AI Alibaba

很多人第一次接触大模型接入时，做法通常很直接：

• 拿到 API Key
• 调一个 HTTP 接口
• 拼 prompt
• 返回结果

这样做当然没问题，但只适合一次性验证。真正进入业务后，问题会越来越多：

• 模型提供商不止一个，接口格式不同
• 需要结构化输出，而不是一段自由文本
• 需要工具调用，比如查天气、查数据库、调内部接口
• 需要多轮对话记忆
• 需要接入知识库
• 需要链路观测、失败重试、上下文裁剪
• 后面还可能发展成 Agent 或工作流

Spring AI 的价值，在于它把这些 AI 开发中的"原子能力"统一抽象出来；Spring AI Alibaba 的价值，在于它面向 Java 业务落地，把这些能力与阿里云模型生态、Agent 编排、企业基础设施更紧密地结合了起来。官网把它的核心能力概括为三层：Agent Framework、Graph、Augmented LLM。其中 Agent Framework 面向快速构建 Agent，Graph 更适合复杂流程编排，而底层 Augmented LLM 则承接模型、工具、消息、向量存储等基础抽象。

你可以把它简单理解为：

• Spring AI：AI 开发的"基础设施抽象层"
• Spring AI Alibaba：更贴近 Java 企业落地的"增强框架层"

---

二、核心概念

1）Model

Model 就是模型能力本身，比如聊天模型、Embedding 模型、多模态模型。

对于 Java 开发者来说，最重要的不是"模型原理推导"，而是要知道一件事：

框架应该帮你屏蔽不同模型厂商之间的调用差异。

Spring AI 的核心价值之一，就是通过统一抽象来屏蔽不同底层模型服务的接入差异；Spring AI Alibaba 则在此基础上提供了通义相关实现，比如 DashScopeChatModel。

2）Prompt

Prompt 不是"随便问一句话"，而是你给模型设定的任务边界、输出约束和上下文材料。

写业务 AI 时，一个好 Prompt 至少要明确：

• 角色
• 任务目标
• 输入边界
• 输出格式
• 错误兜底策略

3）Tool

Tool 可以理解为"给模型外挂手和脚"。

模型本身只会生成文本，它不知道实时天气，不知道你的数据库里有什么，不知道你内部系统的订单状态。要让它能"查"，就得把这些能力以工具的形式暴露给它。

4）Memory

Memory 是多轮对话的上下文记忆能力。

如果没有记忆，用户连续问两句，模型根本不知道上一轮说了什么；如果记忆不受控，又会导致 token 膨胀、成本上升、上下文污染。

5）Agent

模型 + 工具 + 推理决策 + 多轮循环执行

Spring AI Alibaba 官方推荐优先使用 Agent Framework 内置的 ReactAgent 来快速构建 Agent；同时还提供了 SequentialAgent、ParallelAgent、RoutingAgent、LoopAgent 等基础工作流模式

---

三、Spring AI Alibaba 的整体能力图

第一层：模型接入层

这一层解决的是"如何接入模型"。

比如你要接阿里云通义模型，那么可以通过 Spring AI Alibaba 的 DashScope 相关支持来完成接入。官方文档中既提供了 starter 方式，也提供了手动构造 DashScopeChatModel 的方式。

第二层：应用开发层

这一层解决的是"如何把模型变成一个能工作的应用"。

例如：

• 普通聊天应用
• 结构化提取
• 文本分类
• 工具调用
• 知识库问答

第三层：Agent / Workflow 层

这一层解决的是"如何让 AI 不只是回答，而是能执行任务"。

当你的场景从"问答"升级成"查信息 → 判断 → 调接口 → 汇总结果 → 输出结构化结论"时，就会明显感受到 Agent Framework 和 Graph 的价值。

---

四、环境准备

根据 Spring AI Alibaba 当前文档，快速开始至少需要这些基础条件：

• JDK 17+
• Spring Boot 3.x
• 配置可用的 DashScope API Key

---

五、入门

1. 跑通模型调用
2. Prompt 约束
3. 结构化输出
4. Tool / Agent / RAG

1）Maven 依赖

BOM 管理版本，再引入 DashScope starter。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-bom</artifactId>
            <version>1.0.0.2</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
    </dependency>
</dependencies>

官方概览页给出的就是 BOM + spring-ai-alibaba-starter-dashscope 的入门方式；而官方快速开始页则展示了直接显式写版本的方式。两种都能表达接入思路。

2）配置 API Key

建议优先使用环境变量，而不是把 Key 写死在配置文件里。官方快速开始文档也是这样建议的

export AI_DASHSCOPE_API_KEY=你的Key

如果只是本地测试，也可以在 application.yml 里配置：

spring:
  ai:
    dashscope:
      api-key: ${AI_DASHSCOPE_API_KEY}
      chat:
        options:
          model: qwen-plus

3） Controller

package com.example.ai.controller;

import org.springframework.ai.chat.client.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 ChatController {

    private final ChatClient chatClient;

    public ChatController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }

    @GetMapping("/ai/chat")
    public String chat(@RequestParam("message") String message) {
        return chatClient.prompt()
                .user(message)
                .call()
                .content();
    }
}

框架已经把模型接入和调用抽象掉了，业务层只需要按 Spring 的方式组织代码即可。Spring AI 的设计目标本身就是为 AI 应用提供 Spring 风格 API 与统一抽象；Spring AI Alibaba 则在此基础上扩展通义接入与 Java 生态实践。

---

六、加入系统 Prompt

大多数初学者跑通第一个接口后，马上会遇到第二个问题：

为什么模型输出很飘？

原因很简单，你只是让它"回答"，没有告诉它"应该怎么回答"。

比如你要做一个面向开发者的 AI 助手，可以把 Prompt 收敛成这样：

@GetMapping("/ai/guide")
public String guide(@RequestParam("question") String question) {
    return chatClient.prompt()
            .system("""
                    你是一名资深 Java 架构师。
                    请用中文回答。
                    回答要求：
                    1. 先给结论
                    2. 再解释原因
                    3. 最后给出一个可执行建议
                    4. 避免空泛表述
                    """)
            .user(question)
            .call()
            .content();
}

到了这一步，你就已经从"模型测试"进入"业务提示工程"的范畴了。

这里有一个很重要的经验：

Prompt 不只是控制语气，更是控制结果质量。

在企业场景里，模型能力不稳定，很多时候不是模型不行，而是输入约束太弱。

---

七、做结构化输出

在真实业务里，很多场景并不需要一大段自然语言，而是需要模型返回结构化结果，比如：

• 是否命中规则
• 分类结果
• 风险等级
• 摘要内容
• 审核原因

这时候你就不能只追求"回答得像人"，而要追求"返回得像接口"。

例如你要做一个工单分类助手，可以把任务描述成：

请对用户问题进行分类，只允许输出 JSON：
{
  "category": "账号问题/支付问题/物流问题/其他",
  "reason": "分类原因"
}

这一类需求，是 Java 团队最容易真正落地的 AI 场景：

• 客服分类
• 审核辅助
• 标签抽取
• 内容摘要
• 文本改写
• 风险识别

因为它们天然适合接到现有系统里，不需要一开始就上复杂 Agent。

八、 Tool

适合上 Tool 的场景

• 需要获取实时信息
• 需要访问企业内部系统
• 需要执行动作，而不是只回答
• 需要组合多个能力链路

比如：

• 查天气
• 查订单
• 查库存
• 创建设备工单
• 发起审批
• 查询司机轨迹异常

不适合上 Tool 的场景

• 单纯文本改写
• 简单内容总结
• 分类/抽取类任务
• 固定知识问答

也就是说：

Tool 不是"高级感配置"，而是"让模型获得外部能力"的必要手段。