Spring AI 快速上手与实战指南

2.2.2 配置文件

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

2.2.3 启动类与 Controller

创建启动类后，编写一个简单的 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=你好 即可看到返回结果。

3. 聊天模型详解

Spring AI 提供了便捷的聊天模型 API，支持无缝集成大语言模型。

3.1 ChatClient 接口

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

3.1.1 简单对话

通过 ChatClient.Builder 注入客户端，使用链式调用发送用户消息：

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

3.1.2 角色预设

可以通过配置 Bean 为所有请求设置默认的系统提示词（System Prompt），例如设定 AI 的身份：

@Bean
public ChatClient chatClient(ChatClient.Builder builder) {
    return builder.defaultSystem("你是 Java 开发专家，名字叫 AI 助手。").build();
}

3.1.3 流式响应

为了提升用户体验，特别是在模型推理较慢时，可以使用流式输出：

@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 定义了与 AI 模型交互的基本方法，ChatClient 底层即基于此接口。

3.2.1 基础用法

可以直接传入字符串或 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();
}

3.2.2 提示词模板

Spring AI 提供了 Prompt Template 管理抽象，允许在运行时动态替换占位符：

String systemText = "你是一个美食咨询助手，你的名字是{name}，你应该用{name}和{voice}的饮食习惯回复。";
SystemPromptTemplate systemPromptTemplate = new SystemPromptTemplate(systemText);
Message systemMessage = systemPromptTemplate.createMessage(Map.of("name", "张三", "voice", "北京"));
Prompt prompt = new Prompt(List.of(userMessage, systemMessage));

4. 函数调用 (Function Calling)

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

4.1 核心流程

1. 定义函数：声明名称、描述及参数结构。
2. 模型交互：将函数信息发送给模型，模型决定是否需要调用。
3. 执行函数：解析请求并执行业务逻辑。
4. 返回结果：将执行结果反馈给模型生成最终回答。

4.2 实现示例

自定义一个计算器服务，包含加法和乘法运算：

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

在 Controller 中启用这些函数：

@GetMapping("/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 安装与配置

下载并安装 Ollama，设置环境变量 OLLAMA_MODELS 指定模型存储路径。拉取模型（如 deepseek-r1:1.5b）并启动服务。

5.2 代码集成

添加 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

注入 OllamaChatModel 即可像使用云端模型一样调用。

6. Spring AI Alibaba

阿里云推出的 Spring AI 扩展，针对国内环境优化，支持通义千问等模型。

6.1 快速开始

申请阿里云百炼 API Key，引入 spring-ai-alibaba-starter 依赖。

<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter</artifactId>
    <version>1.0.0-M5.1</version>
</dependency>

配置中排除默认的 OpenAI 自动配置以避免冲突，并设置 DashScope API Key。

7. 其他模型能力

除了文本对话，Spring AI 还支持图像和语音生成。

7.1 图像模型

利用 ImageModel 接口实现文生图。通过 ImagePrompt 封装输入，ImageResponse 处理输出。可以指定模型、尺寸及生成数量。

7.2 语音模型

通过 SpeechSynthesisModel 实现文本转语音 (TTS)，支持语速、音调、音量等参数配置，可将文字内容转化为音频文件。

8. RAG (检索增强生成)

RAG 结合检索系统与生成模型，解决大模型知识局限性和幻觉问题。

8.1 工作原理

1. 向量化：将文档转换为向量存入向量数据库。
2. 检索：根据用户问题向量检索相似片段。
3. 上下文构建：将检索到的片段与系统提示词组合。
4. 生成：LLM 基于上下文生成准确回答。

8.2 实现步骤

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

@GetMapping("/rag/chat")
public String generation(@RequestParam("userInput") String userInput) {
    return dashScopeChatClient.prompt()
            .user(userInput)
            .advisors(new QuestionAnswerAdvisor(vectorStore))
            .call()
            .content();
}

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

结合 RAG 知识库与函数调用，构建招聘助手。

1. 知识库构建：将候选人简历文本切分并向量化存储。
2. 工具定义：创建查询岗位匹配度的 Function。
3. 人设设定：在 System Prompt 中明确助手角色、指导原则及限制。
4. 应用串联：在 Controller 中检索简历信息，结合工具返回结果生成专业建议。

通过上述步骤，即可完成一个具备上下文理解能力的智能应用原型。