Spring AI 框架入门与实战指南

2.2.2 配置文件

在子模块的 application.properties 中配置 API Key 和基础 URL：

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 参数控制生成文本的多样性。值越高越随机，值越低越确定。

2.2.3 编写代码

创建启动类：

@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 提供了两种主要的聊天模型交互方式：ChatClient 和 ChatModel。

3.1 ChatClient 接口

ChatClient 是一个更高级的客户端接口，提供了构建和配置聊天对象的灵活性。

3.1.1 简单对话

通过 ChatClient.Builder 注入客户端，使用链式调用设置提示词：

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

3.1.2 角色预设

可以在配置类中定义默认的 System Prompt，设定 AI 的人设：

@Configuration
public class AIConfig {
    @Bean
    public ChatClient chatClient(ChatClient.Builder builder) {
        return builder.defaultSystem("你是一名 Java 开发专家，精通技术细节。").build();
    }
}

3.1.3 流式响应

对于长文本生成，流式输出能显著提升用户体验。使用 stream() 方法替代 call()：

@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.2 ChatModel 接口

ChatModel 是底层的 Model 接口，继承自 Model<Prompt, ChatResponse>。它更接近底层实现，适合需要精细控制 Prompt 结构的场景。

@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();
}

4. 函数调用 (Function Calling)

函数调用允许大语言模型在生成回答时触发预定义的外部函数，从而实现动态数据获取或业务逻辑操作。

4.1 定义函数

只需定义一个返回 java.util.Function 并用 @Bean 标注的方法：

@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;
        };
    }
}

4.2 调用函数

在 Controller 中通过 functions() 方法告知 ChatClient 要使用的函数名称：

@GetMapping(value = "/function")
public String ragJsonText(@RequestParam(value = "message") String message) {
    return ChatClient.builder(chatModel).build()
            .prompt()
            .system("您是算术计算器的代理。当用户询问数学计算时，您必须调用相应的函数来处理。")
            .user(message)
            .functions("addOperation", "mulOperation")
            .call()
            .content();
}

5. 本地部署与 Ollama

Ollama 是一个用于本地化部署和管理大型语言模型的工具，方便开发者在本地运行开源模型。

5.1 安装与拉取

1. 下载并安装 Ollama。
2. 设置环境变量 OLLAMA_MODELS 指定模型存储路径。
3. 执行命令拉取模型，例如：ollama pull deepseek-r1:1.5b。
4. 启动服务：ollama run deepseek-r1:1.5b。

5.2 Spring AI 集成

添加 spring-ai-ollama-spring-boot-starter 依赖，并在配置文件中指定 Base URL：

spring.ai.ollama.base-url=http://localhost:11434
spring.ai.ollama.chat.options.model=deepseek-r1:1.5b

代码部分与 OpenAI 类似，只需注入 OllamaChatModel 即可。

6. Spring AI Alibaba

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

6.1 快速入门

1. 申请阿里云 API Key。
2. 引入 spring-ai-alibaba-starter 依赖。
3. 配置 spring.ai.dashscope.api-key。
4. 排除默认 OpenAI 自动配置以避免冲突。

@Autowired
private ChatClient dashScopeChatClient;

@GetMapping("/simple/chat")
public String simpleChat(@RequestParam("query") String query) {
    return dashScopeChatClient.prompt(query).call().content();
}

7. 其他模型能力

除了文本聊天，Spring AI 还支持图像生成和语音合成。

7.1 图像模型

使用 ImageModel 接口，输入文本提示词，输出图片 URL 或二进制数据。

@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()
    ));
    // 处理响应流输出图片
}

7.2 语音模型

使用 SpeechSynthesisModel 将文本转换为音频文件。

@GetMapping("/tts")
public void tts() throws IOException {
    DashScopeSpeechSynthesisOptions options = DashScopeSpeechSynthesisOptions.builder()
        .withSpeed(1.0)
        .withPitch(0.9)
        .withVolume(60)
        .build();
    SpeechSynthesisResponse response = speechSynthesisModel.call(new SpeechSynthesisPrompt(TEXT, options));
    // 保存音频文件
}

8. RAG (检索增强生成)

RAG 结合了检索系统和生成模型，利用外部知识库帮助大模型生成更准确、有依据的回答，解决知识局限性和幻觉问题。

8.1 工作流程

1. 向量化：将文档内容转换为高维向量。
2. 检索：根据用户问题向量，在向量数据库中查找相似片段。
3. 构建上下文：将检索到的片段与系统提示词结合。
4. 生成回答：LLM 基于上下文生成最终答案。

8.2 实现步骤

1. 创建 VectorStore Bean，加载文档并初始化嵌入模型。
2. 在 Controller 中使用 QuestionAnswerAdvisor 关联向量存储。

@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;
}

9. 综合案例：智能简历筛选助手

本案例整合了 RAG 知识库、函数调用和人设设定，构建一个招聘助手。

9.1 知识库构建

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

9.2 工具与功能

定义查询岗位的工具函数，并在 Prompt 中启用。

9.3 人设设定

在 System Prompt 中明确助手的角色、指导原则及限制条件，确保回答专业且合规。

9.4 测试

调用接口传入查询语句，系统会自动检索简历信息并结合工具返回结果生成建议。

通过以上步骤，你可以快速掌握 Spring AI 的核心用法，从简单的聊天机器人到复杂的 RAG 应用，都能利用该框架高效实现。