Spring AI 零基础入门：从踩坑到上手的完整指南

写在前面：那个让我怀疑人生的下午

事情是这样的。

上周三下午，我坐在电脑前，盯着 IDE 里那个红色的错误信息发呆...

已经三个小时了。

作为一名刚被老板安排"研究一下 Spring AI"的 Java 程序员，我的心情就像坐过山车：

兴奋（哇，AI！）→ 困惑（这是啥？）→ 挫败（我太难了）→ 绝望（我是不是不适合写代码）。

就在我准备摔键盘的时候，突然...

成功了！

那种感觉，就像是在黑暗的迷宫里终于看到了出口。✨

所以今天，我想把这个从"怀疑人生"到"终于会用"的完整过程写下来。如果你也是个 Spring AI 零基础的小白，希望这篇文章能让你少走弯路，多走直路。

01：Spring AI 到底是个啥？

想象一下...

你有个外国朋友，叫 ChatGPT。他很聪明，很会聊天，但是...

他不会说中文。

Spring AI 就是那个神奇的翻译官 🎯

它让你可以用熟悉的 Java 语言和 ChatGPT 交流，而不需要学习什么"提示词工程"、"API 调用"这些听起来就很头大的概念。

简单来说：

你：用 Java 写代码
Spring AI：把你的代码"翻译"成 AI 能听懂的话
AI：给你想要的回答

就这么简单。

就像去餐厅吃饭：

你不用知道厨师怎么做菜
你不用了解后厨的运作流程
你只需要看菜单点菜就行了

Spring AI 就是那个菜单，让你轻松点菜。

02：环境配置 - 我踩过的三个大坑 🕳️

坑一：版本兼容性噩梦

刚开始的时候，我直接在 pom.xml 里加了 Spring AI 依赖：

xml 复制代码

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    <version>1.0.0-M1</version>
</dependency>

结果...

arduino 复制代码

Could not find artifact org.springframework.ai:spring-ai-openai-spring-boot-starter:jar:1.0.0-M1

我当时就懵了...

后来才知道，Spring AI 的版本管理有点特殊。你需要添加 Spring 的 Milestone 仓库：

xml 复制代码

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

坑二：Spring Boot 版本不匹配

解决了仓库问题，又来了新的报错：

bash 复制代码

java.lang.NoClassDefFoundError: org/springframeworkframework/boot/SpringApplication

翻了很多文档才发现，Spring AI 需要 Spring Boot 3.2+ 版本！

如果你的项目还在用 Spring Boot 2.x，要么升级，要么放弃 Spring AI。选择很残酷，但现实就是如此。

坑三：API Key 配置的玄学

终于把依赖搞定了，到了配置 API Key 的环节。

我以为很简单，在 application.properties 里加上：

properties 复制代码

spring.ai.openai.api-key=your-api-key-here

结果运行的时候，总是提示 API Key 无效...

折腾了半天才发现，我把 API Key 复制错了！

那个 sk- 开头的字符串，看起来都差不多，但实际上每个字符都很重要。

总结一下环境配置的避坑指南：

✅ 使用 Spring Boot 3.2+
✅ 添加 Spring Milestone 仓库
✅ 仔细检查 API Key（复制粘贴时小心空格）
✅ 检查网络连接（某些地区可能需要特殊处理）

03：第一个 AI 对话程序 🤖

环境搭好了，终于可以写代码了！

先来个最简单的：让 AI 说"你好世界"。

3.1 创建 AI 服务

java 复制代码

@Service
public class ChatService {

    private final ChatClient chatClient;

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

    public String sayHello(String name) {
        String prompt = "你好，" + name + "！请用友好的语气回复";

        return chatClient.prompt()
                .user(prompt)
                .call()
                .content();
    }
}

看到这段代码，是不是觉得意外地简单？

我第一次看到的时候也是这种感觉："这就完了？"

是的，就这么简单。Spring AI 把复杂的 HTTP 请求、参数设置、响应解析全都封装好了。

3.2 创建控制器

java 复制代码

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

    private final ChatService chatService;

    public ChatController(ChatService chatService) {
        this.chatService = chatService;
    }

    @GetMapping("/hello")
    public String sayHello(@RequestParam(defaultValue = "世界") String name) {
        return chatService.sayHello(name);
    }
}

3.3 测试一下

启动应用，访问 http://localhost:8080/api/chat/hello?name=小明

你可能会看到这样的回复：

复制代码

你好小明！很高兴认识你！今天过得怎么样？

当时我运行成功的瞬间，真的差点跳起来！

那种感觉就像是...你终于和那个神秘的 AI 朋友说上话了。

04：文本生成 - 让 AI 帮你写文案 ✍️

简单的对话只是开胃菜，真正的业务价值在文本生成。

4.1 写一个产品描述生成器

假设我们有个电商网站，需要为商品自动生成描述：

java 复制代码

@Service
public class ProductDescriptionService {

    private final ChatClient chatClient;

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

    public String generateDescription(String productName, String category, String features) {
        String prompt = String.format("""
            请为以下商品生成一个吸引人的产品描述：

            商品名称：%s
            商品分类：%s
            主要特点：%s

            要求：
            1. 语调活泼有趣
            2. 突出商品优势
            3. 100字左右
            4. 适合年轻人群体
            """, productName, category, features);

        return chatClient.prompt()
                .user(prompt)
                .call()
                .content();
    }
}

4.2 测试产品描述生成

java 复制代码

@RestController
@RequestMapping("/api/product")
public class ProductController {

    private final ProductDescriptionService productService;

    @GetMapping("/description")
    public String generateDescription(
            @RequestParam String name,
            @RequestParam String category,
            @RequestParam String features) {

        return productService.generateDescription(name, category, features);
    }
}

访问 http://localhost:8080/api/product/description?name=智能手表&category=电子产品&features=心率监测,防水,续航7天

你可能会得到这样的结果：

复制代码

🎉 智能手表来啦！你的手腕上的健康管家 💪
24小时心率监测，运动数据随时掌握！
防水设计，游泳洗澡都不怕～
超长续航7天，告别每天充电的烦恼！
年轻就要这样玩转科技！

是不是感觉比我们自己写的文案有意思多了？

05：流式响应 - 让对话更自然 💬

你有没有发现，上面的例子都有一个共同点？

等很久才有结果。

这在实际应用中用户体验很不好。就像聊天时对方突然沉默了五分钟...你可能会以为网络断了。

流式响应就是解决这个问题：AI 一边思考一边输出，让用户感觉像在真实对话。

5.1 实现流式聊天

java 复制代码

@Service
public class StreamingChatService {

    private final ChatClient chatClient;

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

    public Flux<String> streamChat(String message) {
        return chatClient.prompt()
                .user(message)
                .stream()
                .content();
    }
}

5.2 流式响应控制器

java 复制代码

@RestController
@RequestMapping("/api/stream")
public class StreamController {

    private final StreamingChatService streamService;

    public StreamController(StreamingChatService streamService) {
        this.streamService = streamService;
    }

    @GetMapping(value = "/chat", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> streamChat(@RequestParam String message) {
        return streamService.streamChat(message);
    }
}

5.3 前端怎么接收流式数据？

javascript 复制代码

const eventSource = new EventSource('/api/stream/chat?message=你好');

eventSource.onmessage = function(event) {
    console.log('AI回复：', event.data);
    // 把内容显示在页面上
};

这样用户就能看到 AI 逐字逐句地回复，体验感瞬间提升！

就像和真人聊天一样自然。

06：函数调用 - 让 AI 能"做事" 🛠️

这是 Spring AI 最强大的功能之一！

想象一下，你问 AI："今天天气怎么样？"

普通的 AI 只能说："抱歉，我无法获取实时天气信息。"

但是通过函数调用，AI 可以调用你提供的方法来获取真实数据！

6.1 定义一个天气查询函数

java 复制代码

@Component
public class WeatherService {

    @Bean
    public Function<WeatherRequest, WeatherResponse> weatherFunction() {
        return request -> {
            // 模拟调用天气 API
            WeatherResponse response = new WeatherResponse();
            response.setCity(request.getCity());
            response.setTemperature(25);
            response.setDescription("晴天");
            response.setHumidity(60);
            return response;
        };
    }

    // 请求和响应的类
    public static class WeatherRequest {
        private String city;
        // getter/setter 省略...
    }

    public static class WeatherResponse {
        private String city;
        private int temperature;
        private String description;
        private int humidity;
        // getter/setter 省略...
    }
}

6.2 让 AI 学会使用这个函数

java 复制代码

@Service
public class FunctionCallingService {

    private final ChatClient chatClient;

    public FunctionCallingService(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder
                .defaultFunctions("weatherFunction") // 注册函数
                .build();
    }

    public String askAboutWeather(String question) {
        return chatClient.prompt()
                .user(question)
                .call()
                .content();
    }
}

6.3 测试函数调用

问 AI："北京今天天气怎么样？"

你可能会得到这样的回复：

erlang 复制代码

根据查询结果，北京今天的天气情况如下：
🌤️ 天气：晴天
🌡️ 温度：25°C
💧 湿度：60%

今天适合外出活动，记得做好防晒哦！

看到了吗？AI 自动调用了你的天气函数，获取了真实数据，然后用自然语言描述出来！

这就是函数调用的威力：让 AI 从"只会聊天"变成了"能做事情"的智能助手。

07：常见错误和解决方法 🆘

错误 1：API 调用超时

bash 复制代码

OpenAI timeout after 30s

解决方法：在配置文件中设置超时时间

properties 复制代码

spring.ai.openai.chat.options.timeout=60s

错误 2：Token 超限

vbnet 复制代码

This model's maximum context length is 4096 tokens

解决方法：精简 prompt 或者使用支持更多 token 的模型

properties 复制代码

spring.ai.openai.chat.model=gpt-4-turbo

错误 3：网络连接问题

arduino 复制代码

Connection refused: connect

解决方法：配置代理（如果需要）

properties 复制代码

spring.ai.openai.base-url=https://api.openai-proxy.com

错误 4：返回结果为空

有时候 AI 会返回空字符串，这通常是 prompt 设计的问题。

解决方法：让 prompt 更具体

java 复制代码

String prompt = "请直接回答问题，不要说'作为一个AI语言模型'这样的开场白。问题：" + question;

08：实战技巧 - 让你的 AI 更聪明 🧠

技巧 1：系统提示词（System Prompt）

java 复制代码

@Bean
public ChatClient chatClient(ChatClient.Builder builder) {
    return builder
            .defaultSystem("你是一个专业的Java开发助手，回答要简洁准确，尽量用代码示例说明。")
            .build();
}

这样 AI 就会记住自己的角色，回答更有针对性。

技巧 2：模板化 Prompt

不要在代码里拼接字符串，用模板更优雅：

java 复制代码

public String generateCode(String requirement) {
    String template = """
            请根据以下需求生成Java代码：

            需求：{requirement}

            要求：
            1. 代码要符合Java规范
            2. 添加必要的注释
            3. 包含错误处理
            4. 使用Spring Boot框架
            """;

    return chatClient.prompt()
            .user(ChatPromptTemplate.from(template)
                    .create("requirement", requirement))
            .call()
            .content();
}

技巧 3：缓存常用回答

有些问题可能重复问，可以缓存结果：

java 复制代码

@Service
public class CachedChatService {

    private final ChatClient chatClient;
    private final Cache<String, String> cache = Caffeine.newBuilder()
            .maximumSize(100)
            .expireAfterWrite(Duration.ofHours(1))
            .build();

    public String ask(String question) {
        return cache.get(question, key -> {
            return chatClient.prompt()
                    .user(key)
                    .call()
                    .content();
        });
    }
}

09：总结 - 从零到一的蜕变 🎉

回想一下那个下午...

从满屏红色错误信息到成功运行第一个 AI 程序，从怀疑人生到兴奋地告诉老板"我能行了！"

这个过程其实没那么难。

Spring AI 的核心就是三个概念：

ChatClient：和 AI 对话的客户端
Prompt：你给 AI 的指令
Function Calling：让 AI 能调用你的方法

掌握了这三个，你就能做出很多有趣的应用：

智能客服机器人
自动文案生成器
代码助手
数据分析报告生成器

下一步建议：

多试试不同的 Prompt，找到最适合你业务的问法
研究一下 Function Calling，这是最有价值的功能
关注 Spring AI 的更新，版本迭代很快
加入相关的技术社区，和其他开发者交流经验

记住：AI 不是要取代程序员，而是要成为程序员的超级工具 🛠️

就像计算器没有让数学家失业，反而让他们能解决更复杂的问题一样。

最后的话

写到这里，突然想起当初踩坑时的那些沮丧时刻...

但现在回头看，那些挫折都是值得的。

学习新技术就像爬山，过程很累，但山顶的风景真的很美。

希望这篇文章能帮你少走一些弯路，更快地到达山顶。

如果在学习过程中遇到问题，记住：你不是一个人在战斗！

我们都是在技术路上互相扶持的同行者。🤝

加油！

本文基于 Spring AI 1.0.0-M1 版本编写，如有版本差异请以官方文档为准。