1. Spring AI Alibaba理论概述

1.1 出现的意义

随着人工智能（AI）技术的迅猛发展，越来越多的开发者开始将目光投向AI应用的开发。然而，目前市场上大多数AI框架和工具如LangChain、PyTorch等主要支持Python，而Java开发者常常面临工具缺乏和学习门槛较高的问题，此时Spring AI Alibaba 作为在Spring AI 的基础上进一步为国内开发者提供便利的AI开发环境应运而生。

在AI框架出现之前，微服务模型和大模型之间没有任何联系，是两个独立的模型：

但AI框架出现之后，这两者之间可以无缝的衔接在一起：

AI框架作为二者之间沟通的桥梁的出现，让微服务项目的能力得到极大的提升。

1.2 什么是 Spring AI Alibaba

Spring AI Alibaba（SAA） 是一款以 Spring AI 为基础，深度集成百炼平台，支持 ChatBot、工作流、多智能体应用开发模式的 AI 框架；是阿里云通义系列模型及服务在 Java AI 应用开发领域的最佳实践，提供高层次的 AI API 抽象与云原生基础设施集成方案和企业级 AI 应用生态集成。

Spring AI Alibaba 作为开发 AI 应用程序的基础框架，定义了以下抽象概念与 API，并提供了 API 与通义系列模型的适配。

  • 开发复杂 AI 应用的高阶抽象 Fluent API — ChatClient
  • 提供多种大模型服务对接能力，包括主流开源与阿里云通义大模型服务（百炼）等
  • 支持的模型类型包括聊天、文生图、音频转录、文生语音等
  • 支持同步和流式 API，在保持应用层 API 不变的情况下支持灵活切换底层模型服务，支持特定模型的定制化能力（参数传递）
  • 支持 Structured Output，即将 AI 模型输出映射到 POJOs
  • 支持矢量数据库存储与检索
  • 支持函数调用 Function Calling
  • 支持构建 AI Agent 所需要的工具调用和对话内存记忆能力
  • 支持 RAG 开发模式，包括离线文档处理如 DocumentReader、Splitter、Embedding、VectorStore 等，支持 Retrieve 检索

1.3 Spring AI Alibaba 的优势

Spring AI Alibaba 基于 Spring AI 构建，因此SAA继承了SpringAI 的所有原子能力抽象并在此
基础上扩充丰富了模型、向量存储、记忆、RAG 等核心组件适配，让其能够接入阿里云的 AI 生态。

1.4Spring AI 与 Spring AI Alibaba 的差异

Spring AI 定位 AI 应用开发底层框架，提供了 AI 开发需要的底层原子抽象，包括模型适配、工具定义、向量数据库存取等；Spring AI Alibaba 定位 AI 智能体开发框架，提供了基于图算法的智能体编程 Graph 框架，让开发者更容易开发工作流、multi-agent 应用。为方便理解，举个不完全正确的类比例子，如果说 Spring AI 是 LangChain 生态中的 Langchain 框架的话，则 Spring AI Alibaba 则是 Langchain 生态中的 Langraph 框架。

除了框架本身外，Spring AI Alibaba 是阿里云基于 Spring AI 框架的企业级智能体开发最佳实践与整体解决方案输出，与阿里开源生态、阿里云平台服务等深度集成，包含：

  • 与百炼 Dashscope 模型服务集成，支持 Qwen、Deepseek 等主流模型系列
  • 与百炼智能体应用平台 AgentScope 集成，提供低代码、高代码双向转换，提升研发效率
  • 与百炼析言 ChatBI 集成，提供自然语言到 SQL 的自动生成开源框架与服务
  • 与阿里云云产品集成，包括向量检索库AnalyticDB、向量检索库OpenSearch、信息检索服务 IQS 等
  • 与开源 Nacos、Higress 生态集成，提供 MCP 注册中心、MCP 智能路由、Prompt管理、模型代理等能力
  • 提供前沿方向的智能体产品实现与整体解决方案，包括 JManus、DeepResearch、NL2SQL 等。
  • 提供 AI 应用开发的完整配套生态，包括本地开发工具、项目构建平台等。

1.5 与其他框架的对比

以下是当前主流 Java AI 框架对比情况。

对比维度 Spring AI Alibaba Spring AI LangChain4J
Spring Boot 集成 原生支持 原生支持 社区适配
文本模型 主流模型，可扩展 主流模型，可扩展 主流模型，可扩展
音视频、多模态、向量模型 支持 支持 支持
RAG 模块化 RAG 模块化 RAG 模块化 RAG
向量数据库 主流向量数据库 阿里云ADB、OpenSearch等 主流向量数据库 主流向量数据库
MCP 支持 支持 Nacos MCP Registry 支持 支持 支持
函数调用 支持（20+官方工具集成） 支持 支持
提示词模版 硬编码，无声明式注解 硬编码，无声明式注解 声明式注解
提示词管理 Nacos 配置中心 无 无
Chat Memory 优化版JDBC、Redis、ElasticSearch JDBC、Neo4j、Cassandra 多种实现适配
可观测性 支持，可接入阿里云ARMS 支持 部分支持
工作流 Workflow 支持，兼容 Dify、百炼 DSL 无 无
多智能体 Multi-agent 支持，官方通用智能体实现 无 无
模型评测 支持 支持 支持
社区活跃度与文档健全性 官方社区，活跃度高 官方社区，活跃度高 个人发起社区
开发提效组件 丰富，包括调试、代码生成工具等 无 无
Example 仓库 丰富，活跃度高 较少 丰富，活跃度高

相关链接：

2. HelloWorld 初始项目搭建

2.1 开发前的环境准备

2.1.1 模型约定

模型供应商 主要特点 优势 备注
OpenAI GPT系列（如GPT-
4），具备强大的文本生成与理解能力		 灵活性高，适用于多种应用场景。大模型界的事实标准。 暂停对国服的API服务，需要通过Azure接入
阿里百炼 提供多种大模型服务（如通义千问系列） 性能接近GPT-4，API价格较低，支持企业迁移解决方案 主要面向企业用户，所有新用户可获得超过5000万Tokens的免费额度及4500张图片生成额度，以鼓励更多企业使用。
DeepSeek 开源大模型，支持多语言 推理与编码任务表现优异，社区活跃，支持多样化应用 性价比高，输入价格（缓存命中）:缓存未命中）:1元/百万Tokens。但敏感词封号严重
智谱清言 基于GLM架构，支持多轮对话与复杂指令处理 指令理解能力强，支持多场景下的定制化解决方案 模型全面；在国庆月特别活动中，智谱清言宣布用户可以以最低1折调用所有模型，并每位用户将获赠1亿Tokens的额度
硅基流动 专注于AI基础设施，提供SiliconCloud平台 高效推理，多模态支持，降低使用门槛，提升开发效率 主要面向技术开发者。提供了一系列开源大模型的API服务，其中多个开源大模型如Qwen2、GLM4和Yi1.5均为永久免费，这使得开发者可以自由使用这些模型进行应用开发，而无需承担费用
Ollama 支持本地部署，集成多种开源模型，隐私保护优先 强调用户隐私和自主性 需要较高的硬件配置以支持本地部署

2.1.2 兼容性问题

怎么确定 Spring AI Alibaba 与 Spring AI、Spring Boot 版本的兼容关系？

Spring AI Alibaba 使用四位版本号的版本管理方式，前三位版本号与 Spring AI 主版本对应，Spring AI Alibaba 社区在前三位主版本基础上持续迭代第四位版本号。

以下为部分版本对应关系，新版发布版本依此类推:

Spring AI Alibaba Spring AI Spring Boot
1.0.0.2 1.0.0 3.4.5
1.0.0-M6.1 1.0.0-M6 3.4.2

所有调用均基于 OpenAI 协议标准或者SpringAI Aalibaba官方推荐模型服务灵积(DashScope)整合规则，实现一致的接口设计与规范，确保多模型切换的便利性，提供高度可扩展的开发支持。

2.1.3 阿里云百炼平台环境准备

https://bailian.console.aliyun.com/

获得Api-key：

建议把API Key配置到环境变量，从而避免在代码里显式地配置API Key，降低泄漏风险。

操作步骤

针对Windows系统

在Windows系统中，您可以通过系统属性、CMD或PowerShell配置环境变量。

说明

  • 此方式配置的环境变量永久生效。

  • 修改系统环境变量需具备管理员权限。

  • 配置环境变量后不会立即影响已经打开的命令窗口、IDE或其他正在运行的应用程序。您需要重新启动这些程序或者打开新的命令行使环境变量生效。

  1. 在Windows系统桌面中按Win+Q键，在搜索框中搜索编辑系统环境变量，单击打开系统属性界面。

  2. 在系统属性窗口，单击环境变量，然后在系统变量区域下单击新建，变量名填入DASHSCOPE_API_KEY，变量值填入您的DashScope API Key。

    image

  3. 依次单击三个窗口的确定，关闭系统属性配置页面，完成环境变量配置。

  4. 打开CMD（命令提示符）窗口或Windows PowerShell窗口，执行如下命令检查环境变量是否生效。

    • CMD查询命令：

      echo %DASHSCOPE_API_KEY%

      image

    • Windows PowerShell查询命令：

      echo $env:DASHSCOPE_API_KEY

      image

这样API Key就配置到了环境变量

获得模型名：

获得baseUrl开发地址：

使用SDK调用时需配置的base_url：https://dashscope.aliyuncs.com/compatible-mode/v1

2.2 创建 HelloWorld 项目

2.2.1在IDEA中新建一个项目

在该项目中新建子模块HelloWorld，该模块是以maven作为构建系统的。

2.2.2 修改父工程POM文件

在父工程的POM文件中，写入以下依赖信息：

<properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <java.version>21</java.version>
        <!-- Spring Boot 新建2025.10-->
        <spring-boot.version>3.5.5</spring-boot.version>
        <!-- Spring AI 新建2025.10-->
        <spring-ai.version>1.0.0</spring-ai.version>
        <!-- Spring AI Alibaba 新建2025.10-->
        <SpringAIAlibaba.version>1.0.0.2</SpringAIAlibaba.version>
<!--         Spring AI Ollama 新建2025.10 -->
<!--        <spring-ai-ollama.version>1.0.0</spring-ai-ollama.version>-->
    </properties>

    <dependencyManagement>
        <dependencies>
            <!-- Spring Boot -->
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring-boot.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <!-- Spring AI Alibaba -->
            <dependency>
                <groupId>com.alibaba.cloud.ai</groupId>
                <artifactId>spring-ai-alibaba-bom</artifactId>
                <version>${SpringAIAlibaba.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <!-- Spring AI -->
            <dependency>
                <groupId>org.springframework.ai</groupId>
                <artifactId>spring-ai-bom</artifactId>
                <version>${spring-ai.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>


    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>${spring-boot.version}</version>
            </plugin>
        </plugins>
    </build>

    <repositories>
        <repository>
            <id>spring-milestones</id>
            <name>Spring Milestones</name>
            <url>https://repo.spring.io/milestone</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
    </repositories>

2.2.3 修改子模块POM文件

在子模块的POM文件中做如下配置：

<dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- 引入 springai alibaba DashScope 模型适配的 Starter -->
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
        </dependency>
        <!--lombok-->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <!--hutool-->
        <dependency>
            <groupId>cn.hutool</groupId>
            <artifactId>hutool-all</artifactId>
            <version>5.8.22</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.11.0</version>
                <configuration>
                    <compilerArgs>
                        <arg>-parameters</arg>
                    </compilerArgs>
                    <source>21</source>
                    <target>21</target>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <repositories>
        <repository>
            <id>spring-milestones</id>
            <name>Spring Milestones</name>
            <url>https://repo.spring.io/milestone</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
    </repositories>

2.2.4 编写配置文件

在resources目录下新建application.properties配置文件，并向文件中写入如下内容：

server.port=8001

#大模型对话中文乱码UTF-8 编码处理
server.servlet.encoding.enabled=true
server.servlet.encoding.force=true
server.servlet.encoding.charset=UTF-8

spring.application.name=HelloWorld

# ====SpringAIAlibaba Config=============
spring.ai.dashscope.api-key=${DASHSCOPE_API_KEY}
spring.ai.dashscope.base-url=https://dashscope.aliyuncs.com/compatible-mode/v1
spring.ai.dashscope.chat.options.model=qwen-plus

2.2.5 编写主启动类

在主启动类中编写如下内容：


import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;


@SpringBootApplication
public class HelloWorldApplication{

    public static void main(String[] args){
        SpringApplication.run(HelloWorldApplication.class, args);
    }
}

2.2.6 编写配置类

新建子包config，并在其内新建一个配置类 SaaLLMConfig，该类用于读取大模型的密钥信息，此处有两种方案可选：

import com.alibaba.cloud.ai.dashscope.api.DashScopeApi;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SaaLLMConfig
{

    /**
     * 方式1:${}
     * 持有yml文件配置：spring.ai.dashscope.api-key=${DASHSCOPE_API_KEY}
     */

    @Value("${spring.ai.dashscope.api-key}")
    private String apiKey;

    /*@Bean
    public DashScopeApi dashScopeApi()
    {
        return DashScopeApi.builder().apiKey(apiKey).build();
    }*/



    /**
     * 方式2:System.getenv("环境变量")
     * 持有yml文件配置：spring.ai.dashscope.api-key=${DASHSCOPE_API_KEY}
     * @return
     */
    @Bean
    public DashScopeApi dashScopeApi()
    {
        return DashScopeApi.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
            .build();
    }

}

2.2.7 编写业务类

新建子包controller，并在其内新建一个类 ChatHelloController，其内容如下：

import jakarta.annotation.Resource;
import org.springframework.ai.chat.model.ChatModel;
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 ChatHelloController{

    @Resource // 对话模型，调用阿里云百炼平台
    private ChatModel chatModel;

    /**
     * 通用调用
     * @param msg
     * @return
     */
    @GetMapping(value = "/hello/dochat")
    public String doChat(@RequestParam(name = "msg",defaultValue="你是谁") String msg){
        String result = chatModel.call(msg);
        return result;
    }

    /**
     * 流式返回调用
     * @param msg
     * @return
     */
    @GetMapping(value = "/hello/streamchat")
    public Flux<String> doStream(@RequestParam(name = "msg",defaultValue="你是谁") String msg){
        return chatModel.stream(msg);
    }
}

这样就完成了入门级别的Demo的代码编写。

2.2.8 测试

启动主启动类，然后在浏览器中输入如下地址即可看到效果：

http://localhost:8001/hello/dochat
http://localhost:8001/hello/streamchat

如果想要切换大模型，可以在配置文件中做如下修改：

spring.ai.dashscope.chat.options.model=deepseek-v3

即可切换为deepseek模型。

3. Ollama私有化部署和对接本地大模型

3.1 Ollama本地大模型部署

3.1.1 LLM大模型工具Ollama

概念

Ollama是一个功能强大的开源框架，旨在简化在Docker容器中部署和管理大型语言模型（LLM）的过程。它帮助用户快速在本地运行大模型，通过简单的安装指令，用户可以执行一条命令就在本地运行开源大型语言模型，如Llama 2。

Ollama极大地简化了在Docker容器内部署和管理LLM的过程，它优化了设置和配置细节，包括GPU使用情况，并将模型权重、配置和数据捆绑到一个包中，定义成Modelfile。此外，Ollama还提供了多种大型语言模型的开源仓库，用户可以通过简单的命令行操作来下载和运行这些模型。

简单来说， Docker Hub 是为各种镜像提供了一种最简单便捷的运行环境，而 Ollama Hub 是为各种大模型提供了最简单和便捷的运行环境。

总之，Ollama是一个用于在本地高效运行大型语言模型的工具，为开发者和研究人员提供了极大的便利。

Ollama官网

用途

下载地址

https://ollama.com/download

使用说明

说明：Ollama的运行会受到所使用模型大小的影响；

  1. 例如，运行一个7B（70亿参数）的模型至少需要8GB的可用内存（RAM），而运行一个13B（130亿参数）的模型需要16GB的内存，33B（330亿参数）的模型需要32GB的内存；
  2. 需要考虑有足够的磁盘空间，大模型的文件大小可能比较大，建议至少为Ollama和其模型预留50GB的磁盘空间；
  3. 性能较高的CPU可以提供更好的运算速度和效率，多核处理器能够更好地处理并行任务，选择具有足够核心数的CPU;
  4. 显卡（GPU）：Ollama支持纯CPU运行，但如果电脑配备了NVIDIA GPU，可以利用GPU进行加速，提高模型的运行速度和性能；

注：此处文中的“B”为英文单词 billions 的简写，即十亿。

使用简示

验证是否安装成功

启动软件后，使用如下两条命令：

netstat -ano | findstr 11434

ollama --version

运行模型

1). 以 qwen3:0.6b 为例

ollama run qwen3:0.6b

运行成功之后会显示success，此时大模型处于等待用户输入状态，发送想问大模型的文字即可看到大模型的回复。

2). 以 deepseek-r1:1.5b 为例

同上，可以看到大模型已经在本地成功运行起来了。

当需要结束当前对话时，即关闭该大模型时，使用如下指令即可：

/bye

此外，还可以使用如下指令获取帮助：

/?

3.2 微服务对接本地大模型

3.2.1 新建module

新建子module，名字自行选取，例Ollama。

3.2.2 修改子模块POM

在子module的POM文件中，除了Hello World项目中的原有依赖配置，增加如下：

        <!--ollama-->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-ollama</artifactId>
            <version>1.0.0</version>
        </dependency>

3.3.3 修改配置文件

在resources目录下新建application.properties配置文件，并向文件中写入如下内容：

server.port=8002

server.servlet.encoding.enabled=true
server.servlet.encoding.force=true
server.servlet.encoding.charset=UTF-8

spring.application.name=Ollama

# ====ollama Config=============
spring.ai.dashscope.api-key=${DASHSCOPE_API_KEY}
spring.ai.ollama.base-url=http://localhost:11434
spring.ai.ollama.chat.model=qwen3:0.6b

3.3.4 编写主启动类

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class OllamaApplication
{
    public static void main(String[] args)
    {
        SpringApplication.run(OllamaApplication.class,args);
    }
}

3.3.5 编写业务类

import jakarta.annotation.Resource;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.beans.factory.annotation.Qualifier;
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 OllamaController
{    //方式1
    /*@Resource(name = "ollamaChatModel")
    private ChatModel chatModel;*/

    //方式2
    @Resource
    @Qualifier("ollamaChatModel")
    private ChatModel chatModel;

    /**
     * http://localhost:8002/ollama/chat?msg=你是谁
     * @param msg
     * @return
     */
    @GetMapping("/ollama/chat")
    public String chat(@RequestParam(name = "msg") String msg)
    {
        String result = chatModel.call(msg);
        System.out.println("---结果：" + result);
        return result;
    }

    @GetMapping("/ollama/streamchat")
    public Flux<String> streamchat(@RequestParam(name = "msg",defaultValue = "你是谁") String msg)
    {
        return chatModel.stream(msg);
    }
}

此处需要注意的是，一定要指明是哪个chatModel，否则会导致无法识别哪个Bean从而使项目无法运行。也就是代码中的方式1和方式2，切不可写成：

@Resource
private ChatModel chatModel;

Spring AI Alibaba 【二】

# 人工智能 # spring # java
Logo
智能体开发者社区

中国智能体开发者社区，聚焦智能体与大模型开发，提供前沿资讯、实用工具链、开源项目及行业案例。通过技术沙龙、开发者大赛等活动，促进经验交流与协作，助力开发者快速构建创新智能应用。

更多推荐

cover

[特殊字符]DeepSeek‑Harness（DSH）小白保姆教程

avatar 智能体开发者社区

Deepseek Agent Harness教程(一) | 什么是agent

这篇文章揭示了AI Agent与大语言模型（LLM）的本质区别，并详细解释了Agent的工作原理。核心观点包括： 大语言模型本质是无状态的文本处理函数，所有"记忆"都是通过客户端重传历史对话实现的，这导致对话成本呈平方级增长。 AI Agent是"大脑+手脚+循环"的系统，由三部分组成： 大模型作为决策核心 工具调用作为执行手段 循环机制实现持续交互 Agent的实际工作流程： ① 客户端维护对话

avatar 智能体开发者社区
cover

王仕宇是如何做 AI Agent 的：从模型调用，到真正能干活的智能体

avatar 智能体开发者社区