> ## Documentation Index
> Fetch the complete documentation index at: https://javaai.pig4cloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 聊天模型 API

聊天模型 API 为开发者提供了将 AI 驱动的聊天完成功能集成到其应用程序中的能力。它利用预训练的语言模型，如 GPT（生成式预训练转换器），以自然语言生成类似人类的响应。

API 通常通过向 AI 模型发送提示或部分对话来工作，然后 AI 模型根据其训练数据和对自然语言模式的理解生成完成或对话的延续。完成的响应随后返回给应用程序，应用程序可以将其呈现给用户或用于进一步处理。

`Spring AI 聊天模型 API` 旨在为与各种 [AI 模型](/spring4ai/overview/concepts#models) 交互提供一个简单且可移植的接口，允许开发者在不同模型之间切换，只需最少的代码更改。
这种设计符合 Spring 的模块化和可互换性理念。

此外，借助 `Prompt` 等配套类进行输入封装和 `ChatResponse` 进行输出处理，聊天模型 API 统一了与 AI 模型的通信。
它管理请求准备和响应解析的复杂性，提供直接和简化的 API 交互。

您可以在 [可用实现](#available-implementations) 部分找到更多关于可用实现的信息，以及在 [聊天模型比较](/spring4ai/api/chat/comparison) 部分找到详细的比较。

## API 概述

本节提供了 Spring AI 聊天模型 API 接口和相关类的指南。

### ChatModel

以下是 [ChatModel](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat//model/ChatModel.java) 接口定义：

```java theme={"system"}
public interface ChatModel extends Model<Prompt, ChatResponse> {

	default String call(String message) {...}

    @Override
	ChatResponse call(Prompt prompt);
}
```

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

### StreamingChatModel

以下是 [StreamingChatModel](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-model/src/main/java/org/springframework/ai/chat/model/StreamingChatModel.java) 接口定义：

```java theme={"system"}
public interface StreamingChatModel extends StreamingModel<Prompt, ChatResponse> {

    default Flux<String> stream(String message) {...}

    @Override
	Flux<ChatResponse> stream(Prompt prompt);
}
```

`stream()` 方法接受 `String` 或 `Prompt` 参数，类似于 `ChatModel`，但它使用响应式 Flux API 流式传输响应。

### Prompt

[Prompt](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-client-chat/src/main/java/org/springframework/ai/chat/prompt/Prompt.java) 是一个 `ModelRequest`，它封装了 [Message](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-model/src/main/java/org/springframework/ai/chat/messages/Message.java) 对象列表和可选的模型请求选项。
以下列表显示了 `Prompt` 类的截断版本，不包括构造函数和其他实用方法：

```java theme={"system"}
public class Prompt implements ModelRequest<List<Message>> {

    private final List<Message> messages;

    private ChatOptions modelOptions;

	@Override
	public ChatOptions getOptions() {...}

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

    // 构造函数和实用方法省略
}
```

#### Message

`Message` 接口封装了 `Prompt` 文本内容、元数据属性集合和称为 `MessageType` 的分类。

接口定义如下：

```java theme={"system"}
public interface Content {

	String getText();

	Map<String, Object> getMetadata();
}

public interface Message extends Content {

	MessageType getMessageType();
}
```

多模态消息类型还实现了 `MediaContent` 接口，提供 `Media` 内容对象列表。

```java theme={"system"}
public interface MediaContent extends Content {

	Collection<Media> getMedia();

}
```

`Message` 接口有各种实现，对应于 AI 模型可以处理的消息类别：

<Frame caption="Spring AI 消息 API">
  <img src="https://mintcdn.com/pig/mnE7V5Dtl5t5-aV7/images/spring-ai-message-api.jpg?fit=max&auto=format&n=mnE7V5Dtl5t5-aV7&q=85&s=cc9d4f73a198e712889d0045e139ebdb" width="800" data-path="images/spring-ai-message-api.jpg" />
</Frame>

聊天完成端点根据对话角色区分消息类别，这些角色由 `MessageType` 有效映射。

例如，OpenAI 识别不同对话角色的消息类别，如 `system`、`user`、`function` 或 `assistant`。

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

对于不使用特定角色的 AI 模型，`UserMessage` 实现作为标准类别，通常代表用户生成的查询或指令。
要了解 `Prompt` 和 `Message` 之间的实际应用和关系，特别是在这些角色或消息类别的上下文中，请参阅 [提示](/spring4ai/api/prompt) 部分中的详细说明。

#### 聊天选项

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

```java theme={"system"}
public interface ChatOptions extends ModelOptions {

	String getModel();
	Float getFrequencyPenalty();
	Integer getMaxTokens();
	Float getPresencePenalty();
	List<String> getStopSequences();
	Float getTemperature();
	Integer getTopK();
	Float getTopP();
	ChatOptions copy();

}
```

此外，每个模型特定的 ChatModel/StreamingChatModel 实现都可以有自己的选项，可以传递给 AI 模型。例如，OpenAI 聊天完成模型有自己的选项，如 `logitBias`、`seed` 和 `user`。

这是一个强大的功能，允许开发者在启动应用程序时使用模型特定的选项，然后使用 `Prompt` 请求在运行时覆盖它们。

Spring AI 提供了一个复杂的系统来配置和使用聊天模型。
它允许在启动时设置默认配置，同时还提供了在每次请求的基础上覆盖这些设置的灵活性。
这种方法使开发者能够轻松地使用不同的 AI 模型并根据需要调整参数，所有这些都在 Spring AI 框架提供的一致接口内。

以下流程图说明了 Spring AI 如何处理聊天模型的配置和执行，结合了启动和运行时选项：

<Frame caption="聊天选项流程">
  <img src="https://mintcdn.com/pig/43t3K3HuqTJIvmwg/images/chat-options-flow.jpg?fit=max&auto=format&n=43t3K3HuqTJIvmwg&q=85&s=b0309bdee5621e1cb84e6e3cfdefd6e8" width="800px" data-path="images/chat-options-flow.jpg" />
</Frame>

<Steps>
  <Step title="启动配置">
    ChatModel/StreamingChatModel 使用"启动"聊天选项进行初始化。这些选项在 ChatModel 初始化期间设置，旨在提供默认配置。
  </Step>

  <Step title="运行时配置">
    对于每个请求，Prompt 可以包含运行时聊天选项：这些可以覆盖启动选项。
  </Step>

  <Step title="选项合并过程">
    "合并选项"步骤结合了启动和运行时选项。如果提供了运行时选项，它们将优先于启动选项。
  </Step>

  <Step title="输入处理">
    "转换输入"步骤将输入指令转换为本地的、模型特定的格式。
  </Step>

  <Step title="输出处理">
    "转换输出"步骤将模型的响应转换为标准化的 `ChatResponse` 格式。
  </Step>
</Steps>

启动和运行时选项的分离允许全局配置和请求特定的调整。

### ChatResponse

`ChatResponse` 类的结构如下：

```java theme={"system"}
public class ChatResponse implements ModelResponse<Generation> {

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

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

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

    // 其他方法省略
}
```

[ChatResponse](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-model/src/main/java/org/springframework/ai/chat/model/ChatResponse.java) 类保存 AI 模型的输出，每个 `Generation` 实例包含来自单个提示的潜在多个输出之一。

`ChatResponse` 类还携带有关 AI 模型响应的 `ChatResponseMetadata` 元数据。

### Generation

最后，[Generation](https://github.com/spring-projects/spring-ai/blob/main/spring-ai-model/src/main/java/org/springframework/ai/chat/model/Generation.java) 类从 `ModelResult` 扩展而来，表示模型输出（助手消息）和相关元数据：

```java theme={"system"}
public class Generation implements ModelResult<AssistantMessage> {

	private final AssistantMessage assistantMessage;
	private ChatGenerationMetadata chatGenerationMetadata;

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

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

    // 其他方法省略
}
```

## 可用实现

此图说明了统一的接口 `ChatModel` 和 `StreamingChatModel` 用于与来自不同提供商的各种 AI 聊天模型交互，允许轻松集成和在不同 AI 服务之间切换，同时为客户端应用程序维护一致的 API。

<Frame caption="Spring AI 聊天完成客户端">
  <img src="https://mintcdn.com/pig/mnE7V5Dtl5t5-aV7/images/spring-ai-chat-completions-clients.jpg?fit=max&auto=format&n=mnE7V5Dtl5t5-aV7&q=85&s=57d18d27822b859b9c9fa7c742fea124" width="1000px" data-path="images/spring-ai-chat-completions-clients.jpg" />
</Frame>

<CardGroup cols={2}>
  <Card title="OpenAI 聊天完成" icon="openai" href="/spring4ai/api/chat/openai-chat">
    支持流式传输、多模态和函数调用。
  </Card>

  <Card title="Azure OpenAI 聊天完成" icon="microsoft" href="/spring4ai/api/chat/azure-openai-chat">
    支持流式传输和函数调用。
  </Card>

  <Card title="Ollama 聊天完成" icon="cube" href="/spring4ai/api/chat/ollama-chat">
    支持流式传输、多模态和函数调用。
  </Card>

  <Card title="Hugging Face 聊天完成" icon="face-smile" href="/spring4ai/api/chat/huggingface">
    不支持流式传输。
  </Card>

  <Card title="Google Vertex AI Gemini 聊天完成" icon="google" href="/spring4ai/api/chat/vertexai-gemini-chat">
    支持流式传输、多模态和函数调用。
  </Card>

  <Card title="Amazon Bedrock" icon="aws" href="/spring4ai/api/bedrock">
    各种具有不同功能的模型。
  </Card>

  <Card title="Mistral AI 聊天完成" icon="cloud" href="/spring4ai/api/chat/mistralai-chat">
    支持流式传输和函数调用。
  </Card>

  <Card title="Anthropic 聊天完成" icon="cat" href="/spring4ai/api/chat/anthropic-chat">
    支持流式传输和函数调用。
  </Card>
</CardGroup>

<Tip>
  在 [聊天模型比较](/spring4ai/api/chat/comparison) 部分找到可用聊天模型的详细比较。
</Tip>

## 聊天模型 API

Spring AI 聊天模型 API 构建在 Spring AI `通用模型 API` 之上，提供聊天特定的抽象和实现。
这允许轻松集成和在不同 AI 服务之间切换，同时为客户端应用程序维护一致的 API。
以下类图说明了 Spring AI 聊天模型 API 的主要类和接口。

<Frame caption="Spring AI 聊天 API">
  <img src="https://mintcdn.com/pig/mnE7V5Dtl5t5-aV7/images/spring-ai-chat-api.jpg?fit=max&auto=format&n=mnE7V5Dtl5t5-aV7&q=85&s=244768b01e05af1ecf8d7861d18a9ed9" width="1000px" data-path="images/spring-ai-chat-api.jpg" />
</Frame>

<Card title="文档有误？请协助编辑" icon="pencil" href="https://github.com/javaai-pig4cloud-com/javaai-docs/edit/main/spring-ai/api/chatmodel.mdx">
  发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
</Card>