SpringAI OpenAI 接口 ChatClient

位置 org.springframework.ai.chat.client.ChatClient

ChatClient 提供了一个流畅的 API，用于与 AI 模型通信。它支持同步和流式编程模型。

初始化 ChatClient

public class ChatClientController {

    private ChatClient chatClient;

    /**
     * 不能直接 new ChatClient ()，ChatClient 构造方法私有，无法手动 new 实例，
     * 官方唯一标准创建方式：ChatClient.Builder.build ()
     * @param chatClientBuilder
     */
    public ChatClientController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }
}

ChatClient 简单使用

System.out.println(chatClient.prompt().user("Tell me a joke").call().content());

返回结构化的响应

ChatResponse chatResponse = chatClient.prompt().user(question).call().chatResponse();

ChatResponse 是 Spring AI 中封装 AI 模型响应的核心类，包含完整的响应元数据和内容。

响应示例

/**
 * ChatResponse 返回格式
 * {
 *   "result": {
 *     "metadata": {
 *       "contentFilterMetadata": null,
 *       "finishReason": "STOP"
 *     },
 *     "output": {
 *       "messageType": "ASSISTANT",
 *       "metadata": {
 *         "finishReason": "STOP",
 *         "refusal": "",
 *         "index": 0,
 *         "role": "ASSISTANT",
 *         "id": "876f839e-9f37-481b-a975-4643ffee7666",
 *         "messageType": "ASSISTANT"
 *       },
 *       "toolCalls": [],
 *       "content": "社会主义核心价值观是当代中国精神的集中体现，凝结着全体人民共同的价值追求。它包含以下三个层面的内容：\n\n**1. 国家层面：富强、民主、文明、和谐**\n*   **富强**：即国富民强，是社会主义现代化国家经济建设的必然要求。\n*   **民主**：即人民当家作主，是社会主义民主政治的本质和核心。\n*   **文明**：即社会进步和人的全面发展，是社会主义现代化国家文化建设的应有状态。\n*   **和谐**：即人与自然、人与社会、人与人之间的融洽共生，是社会主义现代化国家在社会建设领域的价值诉求。\n\n**2. 社会层面：自由、平等、公正、法治**\n*   **自由**：指人的意志自由、存在和发展的自由，是人类社会的美好向往。\n*   **平等**：指公民在法律面前的一律平等，尊重和保障人权。\n*   **公正**：即社会公平和正义，以人的解放、人的自由平等权利的获得为前提。\n*   **法治**：即依法治国、依法执政、依法行政，是治国理政的基本方式。\n\n**3. 个人层面：爱国、敬业、诚信、友善**\n*   **爱国**：是基于个人对自己祖国依赖关系的深厚情感，是调节个人与祖国关系的行为准则。\n*   **敬业**：是对公民职业行为准则的价值评价，要求公民忠于职守、克己奉公、服务社会。\n*   **诚信**：即诚实守信，是人类社会千百年传承下来的道德传统，也是社会主义道德建设的重点内容。\n*   **友善**：强调公民之间应互相尊重、互相关心、互相帮助、和睦友好。\n\n这24个字相互联系、相互贯通，构成了一个有机整体，是全体中国人民在生活、工作和社会交往中共同遵循的基本价值准则。"
 *     }
 *   },
 *   "metadata": {
 *     "id": "876f839e-9f37-481b-a975-4643ffee7666",
 *     "model": "deepseek-v4-flash",
 *     "rateLimit": {
 *       "requestsLimit": null,
 *       "requestsRemaining": null,
 *       "tokensLimit": null,
 *       "tokensRemaining": null,
 *       "requestsReset": null,
 *       "tokensReset": null
 *     },
 *     "usage": {
 *       "promptTokensDetails": {
 *         "audioTokens": 0,
 *         "cachedTokens": 0
 *       },
 *       "reasoningTokens": 0,
 *       "audioTokens": 0,
 *       "completionTokenDetails": {
 *         "reasoningTokens": 0,
 *         "acceptedPredictionTokens": 0,
 *         "audioTokens": 0,
 *         "rejectedPredictionTokens": 0
 *       },
 *       "promptTokens": 5,
 *       "generationTokens": 368,
 *       "totalTokens": 373,
 *       "acceptedPredictionTokens": 0,
 *       "promptTokensDetailsCachedTokens": 0,
 *       "rejectedPredictionTokens": 0
 *     },
 *     "promptMetadata": [],
 *     "empty": false
 *   },
 *   "results": [
 *     {
 *       "metadata": {
 *         "contentFilterMetadata": null,
 *         "finishReason": "STOP"
 *       },
 *       "output": {
 *         "messageType": "ASSISTANT",
 *         "metadata": {
 *           "finishReason": "STOP",
 *           "refusal": "",
 *           "index": 0,
 *           "role": "ASSISTANT",
 *           "id": "876f839e-9f37-481b-a975-4643ffee7666",
 *           "messageType": "ASSISTANT"
 *         },
 *         "toolCalls": [],
 *         "content": "社会主义核心价值观是当代中国精神的集中体现，凝结着全体人民共同的价值追求。它包含以下三个层面的内容：\n\n**1. 国家层面：富强、民主、文明、和谐**\n*   **富强**：即国富民强，是社会主义现代化国家经济建设的必然要求。\n*   **民主**：即人民当家作主，是社会主义民主政治的本质和核心。\n*   **文明**：即社会进步和人的全面发展，是社会主义现代化国家文化建设的应有状态。\n*   **和谐**：即人与自然、人与社会、人与人之间的融洽共生，是社会主义现代化国家在社会建设领域的价值诉求。\n\n**2. 社会层面：自由、平等、公正、法治**\n*   **自由**：指人的意志自由、存在和发展的自由，是人类社会的美好向往。\n*   **平等**：指公民在法律面前的一律平等，尊重和保障人权。\n*   **公正**：即社会公平和正义，以人的解放、人的自由平等权利的获得为前提。\n*   **法治**：即依法治国、依法执政、依法行政，是治国理政的基本方式。\n\n**3. 个人层面：爱国、敬业、诚信、友善**\n*   **爱国**：是基于个人对自己祖国依赖关系的深厚情感，是调节个人与祖国关系的行为准则。\n*   **敬业**：是对公民职业行为准则的价值评价，要求公民忠于职守、克己奉公、服务社会。\n*   **诚信**：即诚实守信，是人类社会千百年传承下来的道德传统，也是社会主义道德建设的重点内容。\n*   **友善**：强调公民之间应互相尊重、互相关心、互相帮助、和睦友好。\n\n这24个字相互联系、相互贯通，构成了一个有机整体，是全体中国人民在生活、工作和社会交往中共同遵循的基本价值准则。"
 *       }
 *     }
 *   ]
 * }
 */

流式编程模型

/**
 * stream() 方法允许您获得异步响应
 * Flux 是 Project Reactor 的响应式类型，代表一个异步的、可能包含多个元素的序列
 * 不是立即返回完整字符串，而是返回一个可订阅的流对象
 * AI 每生成一个 token（或小块文本）就立即推送，而不是等完整响应
 * 调用线程不会被阻塞，可以继续做其他事情
 * 效果：在 AI 生成完整响应前就能开始处理数据，提高响应速度和资源利用率
 *
Flux<String> output = chatClient.prompt()
        .user("Tell me a joke")
        .stream()
        .content();

output.subscribe(chunk -> {
    System.out.print(chunk);  // 逐块输出，如："Why" -> " don't" -> " scientists" -> ...
});
**/

何为流畅的式API

ChatClient 的流畅 API（Fluent API）主要体现在方法链式调用和自然语言般的编程体验上。

方法链式调用（Method Chaining）

每个方法都返回 ChatClient 自身或适当的构建器对象，允许连续调用：

String joke = chatClient
    .prompt()                    // 返回 PromptBuilder
    .user("Tell me a joke")      // 返回 PromptBuilder
    .system("You are a comedian") // 返回 PromptBuilder
    .options(options)            // 返回 PromptBuilder
    .call()                      // 返回 CallResponseSpec
    .content();  

与传统方式对比

// 传统方式（非流畅）
PromptRequest request = new PromptRequest();
request.setUserMessage("Hello");
request.setSystemMessage("You are helpful");
request.setOptions(options);
Prompt prompt = new Prompt(request);
ChatResponse response = client.call(prompt);
String content = response.getResult().getOutput().getContent();

// 流畅 API（一行完成）
String content = chatClient.prompt()
    .user("Hello")
    .system("You are helpful")
    .options(options)
    .call()
    .content();

使用 entity() 方法将 AI 模型的输出映射到实体

示例代码

@Tag(name = "学习-ChatClient", description = "学习-ChatClient")
@RestController
@RequestMapping("/study/api/chat/client")
@Slf4j
public class ChatClientController {

    private ChatClient chatClient;

    /**
     * 不能直接 new ChatClient ()，ChatClient 构造方法私有，无法手动 new 实例，
     * 官方唯一标准创建方式：ChatClient.Builder.build ()
     * @param chatClientBuilder
     */
    public ChatClientController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }

    /**
     * ChatResponse 是 Spring AI 中封装 AI 模型响应的核心类，包含完整的响应元数据和内容
     * @param question
     * @return
     */
    @Operation(summary = "ChatResponse结构", description = "学习返回类型ChatResponse结构。")
    @GetMapping("/chat/ChatResponse")
    public ChatResponse getChatResponse(String question) {
        ChatResponse chatResponse = chatClient.prompt().user(question).call().chatResponse();
        log.info("ChatResponse: {}", chatResponse);
        log.info("ChatResponse content: {}",chatResponse.getResult().getOutput().getContent());

        return chatResponse;
    }

    @Operation(summary = "entity() 映射 record", description = "学习使用 entity() 方法将 AI 模型的输出映射记录。")
    @GetMapping("/chat/entity/record")
    public ActorFilms getActorFilmsRecord(@RequestParam(required = false) String actorName) {
        String prompt = actorName == null
                ? "生成一位国内知名导演的影视作品信息。"
                : "生成导演"+actorName+"的影视作品信息。 ";

        return chatClient.prompt().user(prompt).call().entity(ActorFilms.class);
    }

    @Operation(summary = "entity() 映射 simple", description = "学习使用 entity() 方法将 AI 模型的输出映射记录。")
    @GetMapping("/chat/entity/simple")
    public ActorFilms2 getActorFilmsSimple(@RequestParam(required = false) String actorName) {
        String prompt = actorName == null
                ? "生成一位国内知名导演的影视作品信息。"
                : "生成导演"+actorName+"的影视作品信息。 ";

        return chatClient.prompt().user(prompt).call().entity(ActorFilms2.class);
    }

    @Operation(summary = "entity() 映射 指定泛型", description = "学习使用 entity() 方法将 AI 模型的输出映射记录。")
    @GetMapping("/chat/entity/generic")
    public List<ActorFilms> getActorFilmsGeneric(@RequestParam(required = false) String actorName) {
        String[] actors = {"汤姆・汉克斯","比尔・默瑞"};
        if(actorName!=null){
            actors = actorName.split(",");
        }
        String prompt = actorName == null
                ? "整理汤姆・汉克斯与比尔・默瑞各自 5 部电影的参演作品清单。"
                : actors.length >1 ? "整理"+actors[0]+"与"+actors[1]+"各自 5 部电影的参演作品清单。"
                    : "整理"+actorName+" 5 部电影的参演作品清单。";

        return chatClient.prompt().user(prompt).call().entity(new ParameterizedTypeReference<List<ActorFilms>>(){});
    }

    /**
     * stream() 方法允许您获得异步响应
     * Flux 是 Project Reactor 的响应式类型，代表一个异步的、可能包含多个元素的序列
     * 不是立即返回完整字符串，而是返回一个可订阅的流对象
     * AI 每生成一个 token（或小块文本）就立即推送，而不是等完整响应
     * 调用线程不会被阻塞，可以继续做其他事情
     * 效果：在 AI 生成完整响应前就能开始处理数据，提高响应速度和资源利用率
     *
    Flux<String> output = chatClient.prompt()
            .user("Tell me a joke")
            .stream()
            .content();

    output.subscribe(chunk -> {
        System.out.print(chunk);  // 逐块输出，如："Why" -> " don't" -> " scientists" -> ...
    });
    **/

    // 使用 Java Record
    record ActorFilms(
            String actorName,
            int birthYear,
            List<String> films,
            String mostFamousRole,
            int totalFilmsCount
    ) {}

    // 使用 simple class
    // 内部类必须使用静态定义
    @Data
    static class ActorFilms2{
        String actorName;
        int birthYear;
        List<String> films;
        String mostFamousRole;
        int totalFilmsCount;

        // 必须有无参构造函数
        public ActorFilms2(){}

        // 必须要有getter/setter
    }
}