Chat Completion API

聊天完成 API 为开发者提供了将 AI 驱动的聊天完成能力集成到其应用程序中的能力。它充分利用了预先训练好的语言模型，例如 GPT（生成式预训练变换器）来生成类似于人类的响应，以自然语言的形式响应用户输入。 该 API 通常通过向 AI 模型发送提示或部分会话来工作，然后根据其训练数据和对自然语言模式的理解来生成对话的完成或延续。然后将完成的响应返回给应用程序，应用程序可以将其呈现给用户或用于进一步处理。 Spring AI Chat Completion API 被设计为一个简单且可移植的接口，用于与各种 AI Models 交互，且能让开发人员在不同的模型之间进行切换而只需进行最小的代码更改。此设计符合 Spring 的模块化和可互换性理念。 此外，通过使用诸如 Prompt（用于输入封装）和 ChatResponse（用于输出处理）的配套类，聊天完成 API 统一了与 AI 模型之间的通信。其管理着请求准备和响应解析的复杂性，从而提供了直接且简化的 API 交互。

API Overview

此部分提供了 Spring AI 聊天完成 API 接口和关联类的指南。

ChatClient

以下是 ChatClient 接口定义：

public interface ChatClient extends ModelClient<Prompt, ChatResponse> {

	default String call(String message) {// implementation omitted
	}

    @Override
	ChatResponse call(Prompt prompt);
}

带有 String 参数的 call 方法简化了初始使用过程，避免了更复杂的 Prompt 和 ChatResponse 类的复杂性。在实际应用中，更常见的是使用采用 Prompt 实例并返回 ChatResponse 的 call 方法。

StreamingChatClient

以下是 StreamingChatClient 接口定义：

public interface StreamingChatClient extends StreamingModelClient<Prompt, ChatResponse> {
    @Override
	Flux<ChatResponse> stream(Prompt prompt);
}

stream 方法采用与 ChatClient 类似的 Prompt 请求，但它使用反应式 Flux API 对响应流式传输。

Prompt

Prompt 是一个 ModelRequest，它对 Message 对象列表和可选模型请求选项进行封装。以下列表显示了 Prompt 类的一个截断版本，不包括构造函数和其他实用工具方法：

public class Prompt implements ModelRequest<List<Message>> {

    private final List<Message> messages;

    private ChatOptions modelOptions;

	@Override
	public ChatOptions getOptions() {..}

	@Override
	public List<Message> getInstructions() {...}

    // constructors and utility methods omitted
}

Message

Message 接口封装了一个文本消息，一系列作为 Map 的属性，以及称为 MessageType 的分类。该接口的定义如下：

public interface Message {

   String getContent();

   Map<String, Object> getProperties();

   MessageType getMessageType();
}

Message 接口有各种实现，它们对应于 AI 模型可以处理的消息类别。某些模型（如 OpenAI 的聊天完成端点）基于会话角色区分消息类别，实际上是通过 MessageType 映射的。

例如，OpenAI 识别出用于诸如 system、user、function 或 assistant 等不同会话角色的消息类别。

虽然术语 MessageType 可能暗示特定的消息格式，但在这种情况下，它实际上指定了消息在对话中所扮演的角色。

对于不使用特定角色的 AI 模型，UserMessage 实现充当一个标准类别，通常表示用户生成的查询或指令。要理解实际应用以及 Prompt 和 Message 之间的关系，尤其是在这些角色或消息类别的上下文中，请参阅 Prompts 部分的详细说明。

Chat Options

表示可以传递给 AI 模型的选项。ChatOptions 类是 ModelOptions 的子类，用于定义一些可传递给 AI 模型的可移植选项。ChatOptions 类定义如下：

public interface ChatOptions extends ModelOptions {

	Float getTemperature();
	void setTemperature(Float temperature);
	Float getTopP();
	void setTopP(Float topP);
	Integer getTopK();
	void setTopK(Integer topK);
}

此外，每个特定模型的 ChatClient/StreamingChatClient 实现可以拥有自己的选项，这些选项可以传递给 AI 模型。例如，OpenAI 聊天完成模型具有自己的选项，如 presencePenalty、frequencyPenalty、bestOf 等。

这是一个强大的功能，开发者在启动应用程序时可以使用特定于模型的选项，然后通过 Prompt 请求在运行时覆盖这些选项：

chat options flow

ChatResponse

ChatResponse 类的结构如下：

public class ChatResponse implements ModelResponse<Generation> {

    private final ChatResponseMetadata chatResponseMetadata;
	private final List<Generation> generations;

	@Override
	public ChatResponseMetadata getMetadata() {...}

    @Override
	public List<Generation> getResults() {...}

    // other methods omitted
}

ChatResponse 类持有 AI 模型的输出，每个 Generation 实例都包含由一个提示生成的一个多个可能输出之一。

ChatResponse 类还包含关于人工智能模型响应的 ChatResponseMetadata 元数据。

Generation

最后， Generation 类从 ModelResult 中扩展而来，以表示输出助手消息响应以及有关此结果的元数据：

public class Generation implements ModelResult<AssistantMessage> {

	private AssistantMessage assistantMessage;
	private ChatGenerationMetadata chatGenerationMetadata;

	@Override
	public AssistantMessage getOutput() {...}

	@Override
	public ChatGenerationMetadata getMetadata() {...}

    // other methods omitted
}

Available Implementations

为以下模型提供者提供了 ChatClient 和 StreamingChatClient 实现：

spring ai chat completions clients

Chat Model API

Spring AI 聊天完成 API 构建在 Spring AI 通用模型 API 之上，提供特定的聊天抽象和实现。下面的类图说明了 Spring AI 聊天完成 API 的主要类和接口。

spring ai chat api