Spring AI 快速入门：从环境搭建到 RAG 实战

配置文件

在子模块 application.properties 中添加配置：

server.port=8899
spring.application.name=spring-ai-deepseek-demo
# DeepSeek 的 Api key
spring.ai.openai.api-key=sk-****************
spring.ai.openai.base-url=https://api.deepseek.com
spring.ai.openai.chat.options.model=deepseek-chat
spring.ai.openai.chat.options.temperature=0.7

其中 temperature 参数控制生成文本的多样性，值越高越随机，值越低越确定。

代码实现

创建启动类：

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

编写 Controller：

package com.atguigu.ai.controller;

import jakarta.annotation.Resource;
import org.springframework.ai.openai.OpenAiChatModel;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ChatDeepSeekController {
    @Resource
    private OpenAiChatModel chatModel;

    @GetMapping("/ai/generate")
    public String generate(@RequestParam(value = "message", defaultValue = "hello") String message) {
        String response = this.chatModel.call(message);
        System.out.println("response: " + response);
        return response;
    }
}

测试接口 localhost:8899/ai/generate?message=尚硅谷，即可看到模型响应。

3. Spring AI 的聊天模型

3.1 概述

Spring AI 的聊天模型 API 为开发者提供了便捷通道，能够无缝集成 AI 驱动的聊天完成功能。借助预先训练的语言模型，它能依据用户输入生成自然流畅的回复。

3.2 ChatClient 接口

ChatClient 是定义与聊天服务交互客户端的接口，主要用于创建聊天客户端对象、设置请求规范及发起请求。

简单对话

需求：用户输入消息，通过封装方法向 AI 模型发送请求，返回字符串形式的响应。

package com.atguigu.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;

    // 通过构造方法来注入 ChatClient
    public ChatController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }

    @GetMapping("/chat")
    public String chat(@RequestParam(value = "message", defaultValue = "你是谁") String message) {
        return this.chatClient.prompt()
                .user(message)
                .call()
                .content();
    }
}

角色预设

我们可以配置默认的系统角色，让 AI 保持特定的人设。

配置类：

package com.atguigu.ai.config;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class AIConfig {
    @Bean
    public ChatClient chatClient(ChatClient.Builder builder) {
        return builder.defaultSystem("你是尚硅谷教育的一名老师，你精通 Java 开发，你的名字叫尚硅谷。").build();
    }
}

流式响应

非流式输出需要等待模型全部生成后返回，而流式输出逐个字符返回，能显著提升用户体验，特别是在模型推理效率不高时。

@GetMapping(value = "/chat/stream", produces = "text/html;charset=UTF-8")
public Flux<String> chatStream(@RequestParam(value = "message") String message) {
    return chatClient.prompt().user(message).stream().content();
}

3.3 ChatModel 接口

ChatModel 接口定义了与 AI 模型交互的基本方法。虽然 ChatClient 底层使用 ChatModel，但在某些场景下直接使用 ChatModel 更灵活。

package com.atguigu.ai.controller;

import jakarta.annotation.Resource;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.openai.OpenAiChatOptions;
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("/model")
public class ChatModelController {
    @Resource
    private ChatModel chatModel;

    @GetMapping("/chatModel01")
    public String chatModel01(@RequestParam("message") String message) {
        return chatModel.call(message);
    }

    @GetMapping("/chatModel02")
    public String chatModel02(@RequestParam("message") String message) {
        ChatResponse call = chatModel.call(new Prompt(
                message,
                OpenAiChatOptions.builder()
                        .model("deepseek-chat")
                        .temperature(0.8)
                        .build()));
        return call.getResult().getOutput().getContent();
    }
}

提示词管理也是关键，Spring AI 提供了 Prompt Template 来动态替换占位符。

4. Spring AI 的函数调用

4.1 概述

函数调用允许大语言模型在生成回答时触发预定义的外部函数，从而实现动态数据获取或业务逻辑操作。核心流程包括：定义函数、模型交互、执行函数、返回结果。

4.2 实现步骤

我们需要自定义 Function，并在 Controller 中启用它。

创建自定义 Function

package com.atguigu.config;

import lombok.extern.slf4j.Slf4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Description;
import java.util.function.Function;

@Slf4j
@Configuration
public class CalculatorService {
    public record AddOperation(int a, int b) {}
    public record MulOperation(int m, int n) {}

    @Bean
    @Description("加法运算")
    public Function<AddOperation, Integer> addOperation() {
        return request -> {
            log.info("执行加法运算：{} + {} = {}", request.a, request.b, request.a + request.b);
            return request.a + request.b;
        };
    }

    @Bean
    @Description("乘法运算")
    public Function<MulOperation, Integer> mulOperation() {
        return request -> {
            log.info("执行乘法运算：{} * {} = {}", request.m, request.n, request.m * request.n);
            return request.m * request.n;
        };
    }
}

编写 Controller

在 Prompt 中启用函数，并设定系统人设为算术计算器代理。

package com.atguigu.controller;

import jakarta.annotation.Resource;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class FunctionController {
    @Resource
    private ChatModel chatModel;

    @GetMapping(value = "/function", produces = MediaType.APPLICATION_STREAM_JSON_VALUE)
    public String ragJsonText(@RequestParam(value = "message") String message) {
        return ChatClient.builder(chatModel).build()
                .prompt()
                .system("""
                    您是算术计算器的代理。您能够支持加法运算、乘法运算等操作。
                    当用户询问数学计算时，您必须调用相应的函数来处理。
                    支持的函数：
                    - addOperation: 加法运算，需要两个数字参数
                    - mulOperation: 乘法运算，需要两个数字参数
                    调用函数的条件：
                    1. 用户明确要求计算
                    2. 问题涉及加法或乘法
                    3. 能够从问题中提取出两个数字
                    请用中文回复，并在适当的时候调用函数。
                    """)
                .user(message)
                .functions("addOperation", "mulOperation")
                .call()
                .content();
    }
}

5. Spring AI 调用 Ollama

Ollama 是一个用于本地化部署和管理大型语言模型的工具，支持多种开源模型。

5.1 安装与配置

下载并安装 Ollama，设置环境变量 OLLAMA_MODELS 指定模型路径。拉取模型命令示例：ollama pull deepseek-r1:1.5b。启动服务监听 http://localhost:11434。

5.2 代码测试

创建子模块 springai_ollama，添加依赖 spring-ai-ollama-spring-boot-starter。

配置文件：

server.port=8892
spring.application.name=spring-ai-deepseek-demo
spring.ai.ollama.base-url=http://localhost:11434
spring.ai.ollama.chat.options.model=deepseek-r1:1.5b
spring.ai.ollama.chat.options.temperature=0.7

Controller 实现类似，注入 OllamaChatModel 即可。

6. Spring AI Alibaba

Spring AI Alibaba 是阿里云通义系列模型及服务在 Java AI 应用开发领域的最佳实践，提供了完整的开源配套。

6.1 快速入门

申请阿里云 API Key，开通百炼大模型推理服务。

引入依赖 spring-ai-alibaba-starter，排除冲突的 OpenAI 自动配置。

spring.autoconfigure.exclude=org.springframework.ai.autoconfigure.openai.OpenAiAutoConfiguration

配置 ChatClient 时，可以加入 Advisor 实现对话记忆和日志记录。

7. Spring AI 的其他模型

7.1 图像模型

Image Model API 旨在为与专注于图像生成的各种 AI 模型进行交互提供一个简单且可移植的接口。

@GetMapping("/generate-image")
public void getImage(@RequestParam(value = "msg", defaultValue = "生成一只小猫") String msg, HttpServletResponse res) {
    ImageResponse response = imageModel.call(new ImagePrompt(
            msg,
            DashScopeImageOptions.builder()
                    .withModel(DashScopeImageApi.DEFAULT_IMAGE_MODEL)
                    .withN(1)
                    .withHeight(1024)
                    .withWidth(1024)
                    .build()));
    String imageUrl = response.getResult().getOutput().getUrl();
    // 处理图片流输出...
}

7.2 语音模型

Text-to-Speech API 支持将文字内容转化为语音内容，可配置语速、音调、音量等参数。

8. Spring AI 实现 RAG

RAG (Retrieval-Augmented Generation) 是一种结合了检索系统和生成模型的新型技术框架，利用外部知识库帮助大模型生成更加准确、有依据的回答，解决知识局限性和幻觉问题。

8.1 工作流程

1. 用户输入问题。
2. 问题向量化。
3. 向量数据库检索相似片段。
4. 构建上下文 Prompt。
5. 调用 LLM 生成回答。

8.2 实现基本 RAG 流程

创建子模块 springai_rag，初始化 SimpleVectorStore 加载文档。

配置类中注入 EmbeddingModel 并添加文档：

@Bean
VectorStore vectorStore(@Qualifier("dashscopeEmbeddingModel") EmbeddingModel embeddingModel) {
    SimpleVectorStore simpleVectorStore = SimpleVectorStore.builder(embeddingModel).build();
    List<Document> documents = List.of(new Document("产品说明：名称：Java 开发语言..."));
    simpleVectorStore.add(documents);
    return simpleVectorStore;
}

Controller 中使用 QuestionAnswerAdvisor 关联向量存储：

@GetMapping(value = "/chat", produces = "text/plain; charset=UTF-8")
public String generation(@RequestParam("userInput") String userInput) {
    return dashScopeChatClient.prompt()
            .user(userInput)
            .advisors(new QuestionAnswerAdvisor(vectorStore))
            .call()
            .content();
}

9. Spring AI 综合案例

智能简历筛选助手：结合 Spring AI 特性，为企业提供查看候选人信息及岗位匹配度的服务。

9.1 搭建环境

创建子模块 springai_all，端口改为 8896。

9.2 创建 RAG 知识库

将候选人简历 txt 放入 resource 目录，通过 TextReader 读取并切分，存入向量库。

9.3 创建工具类

定义查询候选人岗位的 Function，供模型调用。

9.4 编写应用的人设

设定招聘助手角色，明确指导原则、限制及个性化风格。

9.5 编写 Controller

将人设、知识库、工具串联，构造包含检索信息和工具的 Prompt。

@GetMapping("/ai/agent")
public String agent(@RequestParam("query") String query) {
    // 检索向量库
    List<Document> documents = vectorStore.similaritySearch(query);
    String info = documents.size() > 0 ? documents.get(0).getContent() : "";

    // 构造系统 prompt
    String systemPrompt = "角色与目标：你是一个招聘助手...";
    String userPrompt = "给你提供一些数据参考：{info},请回答我的问题：{query}。";

    // 调用模型
    Prompt prompt = new Prompt(List.of(userMessage, systemMessage),
            DashScopeChatOptions.builder().withFunctions(Set.of("recruitServiceFunction")).build());
    // ... 执行调用
}

测试接口即可看到智能助手的反馈结果。