总览 Overview

文档 Document

Chat Model API 是一个简化的接口，旨在帮助开发者将 AI 驱动的聊天能力（如 GPT 模型）集成到应用中。它通过发送提示语给预训练语言模型，生成类人的自然语言回复，并返回给应用处理。Spring AI Chat Model API 强调模块化与可移植性，支持在不同 AI 模型之间轻松切换，借助 Prompt 和 ChatResponse 等辅助类统一输入输出，屏蔽请求构建和响应解析的复杂性，从而为开发者提供简洁直观的交互方式。

Chat Model API is a simplified interface designed to help developers integrate AI-powered chat capabilities (such as GPT models) into their applications. It generates human-like natural language responses by sending prompts to a pre-trained language model and returns the results to the application for processing. The Spring AI Chat Model API emphasizes modularity and portability, supporting easy switching between different AI models. It uses helper classes like Prompt and ChatResponse to standardize input and output, abstracting away the complexity of request construction and response parsing, thereby providing a clean and intuitive interaction method for developers.

ChatModel + StreamingChatModel
    Prompt
        Message
        ChatOption
ChatResponse
    Generation
ChatClient

Chat Models

ChatModel&StreamingChatModel

聊天模型有两个接口：ChatModel 和 StreamingChatModel，它们用于处理聊天模型的调用，分别提供了同步和异步（流式）两种聊天模型的调用方式，以适应不同的应用场景。

• 如果你只是想快速体验或发送一段普通消息，可以用 call(String message)

• 如果你需要设置更多参数（如系统提示词、多轮上下文、角色等），就需要用 call(Prompt prompt)

There are two interfaces for chat models: ChatModel and StreamingChatModel, which are used to invoke the chat models synchronously and asynchronously (streaming), respectively, to suit different application scenarios.

• If you just want to quickly try it out or send a simple message, you can use call(String message).

• If you need to set more parameters (such as system prompts, multi-turn context, roles, etc.), you should use call(Prompt prompt).

Prompt

Prompt封装了一次模型调用的完整上下文（消息 + 配置），其包含以下对象：

• ChatOptions：模型请求的选项（如温度、最大长度等）

• Message：表示一次对话的消息，支持文本和多模态

• Content：扩展消息为多媒体内容，如图片、视频等

这个结构使得模型调用可以灵活支持文本、多模态输入，并包含元数据和配置选项。

A Prompt encapsulates the complete context of a model invocation (messages + configuration). It includes the following components:

• ChatOptions: Options for the model request (such as temperature, maximum length, etc.)

• Message: Represents a single message in the conversation, supporting both text and multimodal content

• Content: Extends a message to include multimedia content such as images, videos, etc.

This structure allows model invocations to flexibly support text and multimodal inputs while including metadata and configuration options.

ChatResponse

ChatResponse 是模型整体响应，包含多个 Generation（每个代表一个回答），每个回答包括实际内容和元数据（如耗时、评分等）。这套结构便于处理多种输出和详细跟踪模型行为。

ChatResponse represents the overall response from the model and contains multiple Generations (each representing one answer). Each generation includes the actual content and metadata (such as time taken, score, etc.). This structure makes it easier to handle various outputs and track model behavior in detail.

ChatClient

ChatClient 相当于对前面提到的 Prompt、ChatModel、ChatResponse 等底层组件的进一步封装和简化，它把这些复杂结构和调用流程都封装成流式、链式的 API，让你可以像写自然语言一样写代码，调用 AI 模型非常方便。

• ChatModel 是底层模型接口

• ChatClient 是更高级、更易用的客户端封装。

ChatClient is a further abstraction and simplification of the underlying components such as Prompt, ChatModel, and ChatResponse. It wraps these complex structures and invocation processes into a fluent, chainable API, allowing you to write code as naturally as writing language—making AI model invocation very convenient.

• ChatModel is the low-level model interface.

• ChatClient is a higher-level, more user-friendly client abstraction.

  

示例代码 Demo Code

@RestController

class MyController {

   private final ChatClient chatClient;

   private final ChatModel chatModel;

   public MyController(ChatClient.Builder chatClientBuilder, ChatModel chatModel) {

       this.chatClient = chatClientBuilder.build();

       this.chatModel = chatModel;

   }

   @GetMapping("/hello")

   String hello() {

       return chatModel.call("hello");

   }

   @GetMapping("/introduce")

   String introduce() {

       Prompt prompt = new Prompt("Please introduce yourself.");

       ChatResponse response = chatModel.call(prompt);

       return  response.getResults().get(0).getOutput().getText();

   }

   @GetMapping("/joke")

   String joke() {

       return chatClient.prompt()

               .user("Just tell me a joke.")

               .call()

               .content();

   }

   @GetMapping("/prompt")

   String generation() {

       List<Message> messages = List.of(

               new UserMessage("What's the capital of France?"),

               new AssistantMessage("Paris."),

               new UserMessage("How far is it from there to Berlin?")

       );

       Prompt prompt = new Prompt(messages);

       ChatResponse response = chatModel.call(prompt);

       return response.getResult().getOutput().getText();

   }

   @GetMapping("/get-default-options")

   public String getDefaultOptions() {

       if (chatModel instanceof OpenAiChatModel openAiChatModel) {

           ChatOptions defaultOptions = openAiChatModel.getDefaultOptions();

           return """

                   temperature: %s

                   maxTokens: %s

                   model: %s

                   topP: %s

                   """.formatted(

                   defaultOptions.getTemperature(),

                   defaultOptions.getMaxTokens(),

                   defaultOptions.getModel(),

                   defaultOptions.getTopP()

           );

       }

       return "Unsupported ChatModel implementation";

   }

}