Spring AI 核心功能与实战入门

配置文件

在 application.properties 中配置 API Key 和基础信息：

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.example.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=你好，即可看到模型响应。

聊天模型详解

ChatClient 接口

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

简单对话

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

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

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

角色预设

可以通过配置 Bean 设置默认的系统提示词（System Prompt），让 AI 扮演特定角色：

package com.example.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();
    }
}

流式响应

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

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

ChatModel 接口

ChatModel 定义了与 AI 模型交互的基本方法。虽然 ChatClient 底层使用了 ChatModel，但在需要更精细控制 Prompt 或 Options 时，直接使用 ChatModel 更为灵活。

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

提示词管理

Prompt 模板允许我们在运行时动态替换关键词。例如，可以定义一个包含 {name} 和 {voice} 占位符的模板，并在调用时传入具体值。

函数调用

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

实现流程

1. 定义函数：声明可供模型调用的函数（名称、描述、参数结构）。
2. 模型交互：将函数信息与用户输入一起发送给模型。
3. 执行函数：解析模型的调用请求，执行业务逻辑。
4. 返回结果：将执行结果返回给模型生成最终回答。

代码示例

定义自定义函数 Bean：

package com.example.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 中启用函数：

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

本地部署 Ollama

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

安装与配置

1. 下载并安装 Ollama。
2. 设置环境变量 OLLAMA_MODELS 指定模型存储路径。
3. 拉取模型，例如：ollama pull deepseek-r1:1.5b。
4. 启动服务，默认监听 http://localhost:11434。

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

Spring AI Alibaba

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

快速接入

1. 申请阿里云 API Key。
2. 引入 spring-ai-alibaba-starter 依赖。
3. 配置 application.properties，注意排除默认的 OpenAI 自动配置以避免冲突。

// 示例配置
this.dashScopeChatClient = chatClientBuilder
    .defaultSystem(DEFAULT_PROMPT)
    .defaultAdvisors(new MessageChatMemoryAdvisor(new InMemoryChatMemory()))
    .defaultOptions(DashScopeChatOptions.builder().withTopP(0.7).build())
    .build();

其他模型能力

图像模型

Spring AI 的 Image Model API 提供了文生图的能力。通过 ImageModel 接口，可以调用不同的图像生成模型。

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

语音模型

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

RAG 检索增强生成

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

基本流程

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

实现步骤

1. 初始化 SimpleVectorStore 并加载文档。
2. 在 ChatClient 中添加 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;
}

综合案例：智能简历筛选

结合 RAG 和函数调用，我们可以构建一个智能招聘助手。

1. 搭建环境：创建子模块，配置端口。
2. 创建知识库：将候选人简历文本放入资源目录，通过 TextReader 读取并切分，存入向量库。
3. 创建工具：定义查询岗位匹配度的函数。
4. 编写人设：设定系统提示词，明确助手角色、指导原则及限制。
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}。";
    // ... 构建 PromptTemplate 并调用 ChatModel
}

通过这种方式，开发者可以快速构建具备专业领域知识的 AI 应用。