跑通第一个Spring AI 应用

一、SpringAI介绍

官网地址：https://spring.io/projects/spring-ai

1.1如何选择版本

解释一下各个版本的含义：

标签	含义	说明
`CURRENT`	正式稳定版（GA）	官方推荐的生产可用版本，API 稳定、bug 少，有完整维护
`SNAPSHOT`	开发快照版	还在开发中的版本，包含新特性，但随时可能改代码 / 删 API，不稳定，绝对不能用在生产
`PRE`	预览版（Milestone）	大版本的里程碑预览，比如 `-M4` 是第 4 个里程碑，功能基本定型但还没最终发布，适合尝鲜和测试

我们这里选择最新的稳定版本1.1.4

1.2如何查看Spring AI 版本支持的Spring Boot 版本

①查看参考文档

对比维度	Reference Doc.（参考文档）	Api Doc.（API 文档 / Javadoc）
核心定位	面向开发者的「使用指南 / 用户手册」	面向开发者的「代码字典 / 接口说明书」
内容重点	框架的整体功能、使用流程、业务场景示例、配置说明、最佳实践	所有类、接口、方法的完整列表，以及每个方法的参数、返回值、异常说明
阅读目的	学习如何使用 Spring AI 实现功能、解决问题	查找某个具体类 / 方法的定义、参数含义、底层 API 细节
典型使用场景	想知道 "怎么用 Spring AI 实现 RAG、怎么调用大模型" 时，找步骤和示例	写代码时，不知道 `ChatClient.Builder` 的某个方法怎么用，需要查具体定义
阅读方式	按章节顺序阅读，或按业务场景搜索	直接搜索类名 / 方法名，快速定位目标

②在参考文档的Getting Started中查看

1.3选择合适的Spring Boot版本

标识	全称	含义	生产环境是否推荐
`GA`	General Availability	正式稳定版，功能完整、测试充分，API 冻结	✅ 强烈推荐
`CURRENT`	---	该系列最新的稳定 GA 版，会优先收到安全修复	✅ 首选
`PRE`	Pre-release	预览 / 测试版（比如 RC、M 版），功能未完全定型	❌ 不推荐
`SNAPSHOT`	---	开发快照版，还在迭代中，API 随时可能改动	❌ 禁止使用

这里选择3.5.x的最稳定版，3.5.14

二、搭建项目

2.1搭建一个练习项目

结构如下：

创建spring-ai模块来跑通第一个Spring AI 应用

2.2引入pom依赖

复制代码

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.5.14</version>
        <relativePath/>
    </parent>

    <groupId>com.studying</groupId>
    <artifactId>spring-ai</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <java.version>21</java.version>
        <spring-ai.version>1.1.4</spring-ai.version>
    </properties>

    <!-- Spring AI BOM：统一管理 spring-ai 所有子模块的版本 -->
    <dependencyManagement>
        <dependencies>
            <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>
    <dependencies>
        <!-- Web -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!--
            OpenAI Starter：支持 OpenAI 及所有兼容接口（DeepSeek、Moonshot 等）
            引入后自动配置 ChatModel、EmbeddingModel 等 Bean
        -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-openai</artifactId>
        </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>
        </plugins>
    </build>

</project>

2.3配置 API Key

src/main/resources/application.yml：

复制代码

spring:
  ai:
    openai:
      # 如果用 DeepSeek，改成 https://api.deepseek.com
      # 如果用 OpenAI，改成 https://api.openai.com（或者不填，默认就是这个）
      base-url: https://api.deepseek.com
      api-key: ${DEEPSEEK_API_KEY}   # 从环境变量读取，不要直接写在配置文件里
      chat:
        options:
          model: deepseek-chat        # DeepSeek-V3 的模型名
          temperature: 0.7

关于 API Key 的安全性：

三、写第一个 Controller

复制代码

package com.studying.controller;

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

@RestController
@RequestMapping("/chat")
public class ChatController {

    private final ChatClient chatClient;

    // ChatClient.Builder 由 Spring AI 自动注册，直接注入即可
    public ChatController(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    /**
     * 最简单的对话接口
     * GET /chat?message=你好
     */
    @GetMapping
    public String chat(@RequestParam String message) {
        return chatClient.prompt()
                .user(message)
                .call()
                .content();
    }
}

就这几行，启动项目，访问 http://localhost:8080/chat?message=你好，就能得到 AI 的回复。

预期输出类似：

你好！很高兴见到你！😊 我是DeepSeek，由深度求索公司创造的AI助手。无论你有什么问题、需要什么帮助，或者只是想聊聊天，我都很乐意为你提供支持！我可以帮你解答各种问题，协助处理文档，进行创作和分析等等。有什么我可以为你做的吗？我会尽我所能热情地帮助你！✨

四、换成 Ollama 本地模型（按需）

如果不想用云端 API，也可以用 Ollama 跑本地模型，完全免费。

第一步：改依赖

把 spring-ai-starter-model-openai 换成：

同时要将之前 spring-ai-starter-model-openai 去掉，否则会冲突。

复制代码

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

第二步：改配置

复制代码

spring:
  ai:
    ollama:
      base-url: http://localhost:11434  # Ollama 默认端口
      chat:
        options:
          model: qwen2.5:7b             # 确保已经 ollama pull qwen2.5:7b

第三步：Controller 代码一行不用改

ChatClient.Builder 注入的是 Ollama 的实现，接口完全一致。这就是 Spring AI 抽象层的价值所在。

代码量极少，但背后 Spring AI 帮你处理了 HTTP 调用、认证、序列化这些脏活。下节鸡哥带大家深挖 ChatClient 这个 API，把各种参数和用法都过一遍。