ChatModel和ChatClient

ChatModel和ChatClient

• 一、ChatModel
• • 1. 基础定位
  • 2. 核心能力
  • 3. 适用场景
• 二、ChatClient
• • 1. 基础定位
  • 2. 核心能力
  • 3. 适用场景
• 三、二者核心区别对比
• 四、示例
• • 1.application.yml
  • 2.DemoApplication
  • 3.Record
  • 4.ChatModelController
  • 5.ChatClientController

一、ChatModel

1. 基础定位

ChatModel是Spring AI体系中最底层的核心接口，直接与通义千问、OpenAI等大模型服务商通信，是所有大模型交互的基础能力抽象。

2. 核心能力

仅提供两个核心原生方法：

• call(Prompt prompt)：同步返回完整的ChatResponse结果
• stream(Prompt prompt)：以流式方式逐块返回响应内容 它支持自定义组装Prompt、手动配置ChatOptions参数，能完全控制请求的每一个细节。

3. 适用场景

适合简单的单次大模型调用、需要高度定制请求逻辑的场景，开发者可完全自主管理消息组装、响应解析等全流程。

二、ChatClient

1. 基础定位

ChatClient是构建在ChatModel之上的高层封装Fluent API，设计风格对标Spring生态的WebClient，通过链式调用隐藏底层通信细节，抹平不同大模型厂商的接口差异。

2. 核心能力

除基础的同步/流式调用外，内置大量开箱即用的高级功能：

• 结构化输出：直接将大模型返回内容映射为Java POJO/Record，无需手动解析JSON
• 对话记忆：集成ChatMemory，支持内存存储或Redis持久化的多轮上下文管理
• 函数调用：内置Function Calling能力，可对接外部工具
• RAG集成：原生支持检索增强生成流程，快速实现文档问答场景

3. 适用场景

适合快速开发企业级智能客服、聊天机器人、结构化数据提取等标准化AI应用，大幅减少样板代码编写量。

三、二者核心区别对比

实际项目中二者可混合使用，简单场景直接用ChatModel，复杂业务场景优先用ChatClient提升开发效率

四、示例

1.application.yml

server:
port: 8080

spring:
application:
name: spring–ai–alibaba–demo
ai:
dashscope:
# 请替换为你的阿里云 DashScope API Key
api-key: ${AI_DASHSCOPE_API_KEY:your–api–key–here}
chat:
options:
# 默认模型
model: qwen–plus
# 默认温度参数
temperature: 0.7

2.DemoApplication

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

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

3.Record

package com.example.demo.model;

import java.util.List;

/**
* 用于演示 ChatClient 结构化输出功能的 Record 类
*/
public record ActorMovies(String actor, List<String> movies) {
}

4.ChatModelController

package com.example.demo.controller;

import org.springframework.ai.chat.model.ChatModel;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.chat.prompt.SystemPromptTemplate;
import org.springframework.beans.factory.annotation.Autowired;
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;

import java.util.Map;

/**
* ChatModel 是 Spring AI 的底层核心接口，直接与大模型交互。
* 适合需要高度自定义 Prompt 组装和响应处理的场景。
*/
@RestController
@RequestMapping("/api/model")
public class ChatModelController {

private final ChatModel chatModel;

@Autowired
public ChatModelController(ChatModel chatModel) {
this.chatModel = chatModel;
}

/**
* 简单同步调用
* 直接发送字符串，获取返回内容
*/
@GetMapping("/simple")
public String simpleChat(@RequestParam(value = "message", defaultValue = "你好") String message) {
// call 方法直接返回 ChatResponse，通过 getResult().getOutput().getContent() 获取文本
return chatModel.call(message).getResult().getOutput().getContent();
}

/**
* 使用 Prompt 和 System Message
* 展示如何构建更复杂的请求，包含系统指令和用户消息
*/
@GetMapping("/prompt")
public String promptChat(@RequestParam(value = "topic", defaultValue = "Java") String topic) {
// 定义系统提示词模板
String systemText = "你是一个专业的{role}，请用简洁的语言回答用户的问题。";
SystemPromptTemplate systemTemplate = new SystemPromptTemplate(systemText);

// 创建 Prompt，包含系统消息和用户消息
Prompt prompt = new Prompt(
systemTemplate.createMessage(Map.of("role", "技术专家")),
new org.springframework.ai.chat.messages.UserMessage("请解释什么是 " + topic)
);

// 调用模型并获取响应
var response = chatModel.call(prompt);
return response.getResult().getOutput().getContent();
}
}

5.ChatClientController

package com.example.demo.controller;

import com.example.demo.model.ActorMovies;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;
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;

/**
* ChatClient 是基于 ChatModel 封装的高阶 Fluent API。
* 提供链式调用，支持结构化输出、对话记忆等高级功能，开发效率更高。
*/
@RestController
@RequestMapping("/api/client")
public class ChatClientController {

private final ChatClient chatClient;

@Autowired
public ChatClientController(ChatClient.Builder chatClientBuilder) {
// 使用 Builder 构建 ChatClient 实例
this.chatClient = chatClientBuilder.build();
}

/**
* 基础链式调用
* 语法简洁，类似 WebClient
*/
@GetMapping("/simple")
public String simpleChat(@RequestParam(value = "message", defaultValue = "你好") String message) {
return chatClient
.prompt() // 开始构建提示词
.user(message) // 设置用户消息
.call() // 发起调用
.content(); // 直接获取字符串内容
}

/**
* 结构化输出示例
* 直接将大模型的返回结果映射为 Java 对象 (ActorMovies)，无需手动解析 JSON
*/
@GetMapping("/structured")
public ActorMovies structuredOutput(@RequestParam(value = "actor", defaultValue = "成龙") String actor) {
String promptText = "请列出演员 " + actor + " 主演的三部著名电影，以JSON格式返回，包含actor名字和movies列表。";

return chatClient
.prompt(promptText)
.call()
.entity(ActorMovies.class); // 自动反序列化为 Record 对象
}

/**
* 带系统指令的调用
* 动态设置 System Message，控制 AI 的人设
*/
@GetMapping("/role-play")
public String rolePlay(@RequestParam(value = "question", defaultValue = "怎么学习编程？") String question) {
return chatClient
.prompt()
.system("你是一位幽默风趣的编程导师，喜欢用比喻来解释复杂概念。")
.user(question)
.call()
.content();
}
}