Spring AI 实战教程（一）入门示例

2401_87660168

91人浏览 · 2026-03-27 12:35:59

2401_87660168 · 2026-03-27 12:35:59 发布

本系列教程将以实战为核心，以生产落地为目标，从零开始，带大家完整吃透Spring AI能力。从最基础的大模型对接，到 RAG 检索增强、AI Agent 智能体、多模态交互，再到实战，每一篇都配有可直接运行的代码、踩坑避坑指南，打通Java开发者从传统后端开发到 AI 应用落地的全链路。

本篇将基于 Spring AI 框架，集成阿里云百炼（DashScope）和Ollama本地大模型服务，实现同步对话与流式对话功能。代码结构清晰、可直接运行，适合作为 Spring AI 入门实战项目。

一、概述

1. 技术栈

JDK: 17（Spring Boot 3.x 要求）
Spring Boot: 3.2.x
Spring AI: 1.0.0-M4（里程碑版本，需配置 Spring Milestone 仓库）
阿里云百炼 (DashScope): 提供大模型服务

2. 功能目标

实现同步阻塞的对话接口（等待模型完整返回结果）。
实现异步流式的对话接口（逐字返回模型生成结果）。
支持通过配置文件或环境变量安全管理 API Key。

二、环境准备

1. 前置条件

安装 JDK 21并配置环境变量。
安装 Maven 3.6+。
注册阿里云账号并开通百炼（DashScope）服务。

2. 获取 API Key

登录阿里云百炼控制台。
进入 API-KEY 管理，创建新的 API Key（记为 DASHSCOPE_API_KEY）。

三、项目搭建

1. 创建 Spring Boot 项目

使用 Spring Initializr 或 IDEA 创建项目，选择以下依赖：

Spring Web（提供 Web 接口能力）。

2. 配置 Maven 依赖

版本使用：

<properties>
        <java.version>21</java.version>
        <!-- Spring Boot-->
        <spring-boot.version>3.5.5</spring-boot.version>
        <!-- Spring AI->
        <spring-ai.version>1.0.0</spring-ai.version>
        <!-- Spring AI Alibaba-->
        <SpringAIAlibaba.version>1.0.0.2</SpringAIAlibaba.version>
</properties>

在 pom.xml 中添加 Spring AI BOM 和阿里云 DashScope 依赖：

<dependencies>
    <!-- Spring Web（必须） -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Spring AI Alibaba DashScope 官方适配（核心依赖） -->
    <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>

    <!-- Spring Boot Test（可选） -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

<!-- Spring Milestone 仓库（必须，用于下载 Spring AI 里程碑版本） -->
<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

四、核心代码实现

1. 项目结构

src
├── main
│   ├── java
│   │   └── com
│   │       └── silver-kite
│   │           └── study
│   │               ├── SpringAiApplication.java (启动类)
│   │               ├── config
│   │               │   └── LLMConfig.java (配置类)
│   │               └── controller
│   │                   └── ChatHelloController.java (接口层)
│   └── resources
│       └── application.yml (配置文件)

2. 配置类 (`LLMConfig.java`)

提供两种 API Key 加载方式（推荐使用环境变量方式，避免密钥泄露）：

import org.springframework.ai.dashscope.DashScopeApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class SaaLLMConfig {
    /**
     * 方式1: 从 application.yml 读取配置 (不推荐生产环境使用)
     * 配置示例: spring.ai.dashscope.api-key=sk-xxx
     */
    /*
    @Value("${spring.ai.dashscope.api-key}")
    private String apiKey;

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

    /**
     * 方式2: 从系统环境变量读取 (推荐)
     * 需先配置环境变量: DASHSCOPE_API_KEY=sk-xxx
     */
    @Bean
    public DashScopeApi dashScopeApi() {
        return DashScopeApi.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .build();
    }
}

3. 接口层 (`ChatHelloController.java`)

实现同步和流式对话接口：

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; // Spring AI 自动装配的对话模型
    /**
     * 同步对话接口 (阻塞等待完整结果)
     * 访问示例: http://localhost:8080/hello/chat?msg=介绍一下Spring AI
     */
    @GetMapping(value = "/hello/chat")
    public String Chat(@RequestParam(name = "msg", defaultValue = "你是谁") String msg) {
        return chatModel.call(msg);
    }

    /**
     * 流式对话接口 (逐字返回结果，适合长文本生成)
     * 访问示例: http://localhost:8080/hello/streamchat?msg=写一篇1000字的Java学习路线
     */
    @GetMapping(value = "/hello/streamchat")
    public Flux<String> streamChat(@RequestParam(name = "msg", defaultValue = "你是谁") String msg) {
        return chatModel.stream(msg);
    }
}

4.Ollama本地模型

依赖：

<dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!--spring-ai-alibaba dashscope-->
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
        </dependency>
        <!--ollama-->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-ollama</artifactId>
            <version>1.0.0</version>
        </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>

application.properties配置文件：

server.port=8002
spring.application.name=启动类名

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

接口层：

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 {

    @Resource
    @Qualifier("ollamaChatModel")  // 明确注入 Ollama 的 ChatModel
    private ChatModel chatModel;

    /**
     * 同步对话接口
     * 访问示例: http://localhost:8002/ollama/chat?msg=用Java写一个单例模式
     */
    @GetMapping("/ollama/chat")
    public String chat(@RequestParam(name = "msg", defaultValue = "你是谁") String msg) {
        String result = chatModel.call(msg);
        System.out.println("---同步对话结果：" + result);
        return result;
    }

    /**
     * 流式对话接口
     * 访问示例: http://localhost:8002/ollama/streamchat?msg=写一篇关于Spring AI的介绍
     */
    @GetMapping("/ollama/streamchat")
    public Flux<String> streamChat(@RequestParam(name = "msg", defaultValue = "你是谁") String msg) {
        return chatModel.stream(msg);
    }
}

只是model换一下，其他流程没啥区别。

五、运行与测试

1. 配置环境变量

为了安全起见，通过环境变量注入 API Key：

Windows:

setx DASHSCOPE_API_KEY "你的实际API-KEY"

Linux/Mac:

export DASHSCOPE_API_KEY="你的实际API-KEY"

IDEA 配置: 在 Run Configuration 的 Environment variables 中添加 DASHSCOPE_API_KEY=你的API-KEY。

2. 启动项目

运行 SpringAiApplication，看到启动日志后表示成功。

3. 接口测试

(1) 同步接口测试

在浏览器或Postman访问：

http://localhost:8080/hello/chat?msg=你是谁？

预期结果: 等待几秒后，页面完整显示模型回答。

(2) 流式接口测试

使用浏览器访问（推荐 Chrome 或 Edge）：

http://localhost:8080/hello/streamchat?msg=写一篇关于AI的科幻小故事

预期结果: 页面会像打字机一样，逐字逐句显示模型生成的内容。

六、常见问题排查

依赖下载失败: 检查 pom.xml 中是否配置了Spring Milestone仓库。
API Key 无效: 确认环境变量配置正确，且API Key未过期。
流式接口无效果: 确保使用支持 Server-Sent Events (SSE) 的客户端（如浏览器、curl -N）。

下篇预告

本篇我们基于ChatModel原子 API，完成了 Spring AI 与阿里云百炼大模型的基础集成，实现了同步对话与流式响应核心能力。

下篇我们将全面解锁 Spring AI 高层级ChatClient：带你告别大模型开发的重复样板代码，完成从基础demo到工程化开发的升级，包含 ChatClient实战、全局统一配置，敬请关注。

AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

qData 数据中台开源版 v1.2.0 正式发布：重构数据建模体系，重塑开发体验！

AtomGit开源社区

2026企业级AI智能体深度解析：如何通过可信架构降低大模型幻觉，实现深度数据挖掘？

AtomGit开源社区

6个常用国自然课题项目查询网站，码住以备不时之需

AtomGit开源社区

所有评论(0)

查看更多评论

2401_87660168

@2401_87660168

已为社区贡献3条内容

Spring AI 实战教程（一）入门示例

2401_87660168

一、概述

1. 技术栈

2. 功能目标

二、环境准备

1. 前置条件

2. 获取 API Key

三、项目搭建

1. 创建 Spring Boot 项目

2. 配置 Maven 依赖

四、核心代码实现

1. 项目结构

2. 配置类 (LLMConfig.java)

3. 接口层 (ChatHelloController.java)

4.Ollama本地模型

五、运行与测试

1. 配置环境变量

2. 启动项目

3. 接口测试

(1) 同步接口测试

(2) 流式接口测试

六、常见问题排查

下篇预告

所有评论(0)

2401_87660168

2. 配置类 (`LLMConfig.java`)

3. 接口层 (`ChatHelloController.java`)