Perplexity 聊天

Perplexity AI 提供一个独特的 AI 服务，把它的大语言模型与实时搜索能力集成起来。它提供多种模型，并为对话式 AI 支持流式响应。

Spring AI 通过复用现有的 OpenAI 客户端来与 Perplexity AI 集成。要开始，你需要获取一个 Perplexity API 密钥，配置基础 URL，并从受支持的模型中选择一个。

NOTE

Perplexity API 与 OpenAI API 并非完全兼容。

Perplexity 将实时网络搜索结果与其语言模型响应相结合。 与 OpenAI 不同，Perplexity 不暴露 toolCalls —— function call（函数调用）机制。 此外，当前 Perplexity 不支持多模态消息。

查看 GroqWithOpenAiChatModelIT.java 测试， 其中有在 Spring AI 中使用 Groq 的示例。

前置条件

• 创建一个 API 密钥： 前往此处创建一个 API 密钥。 在你的 Spring AI 项目中使用 spring.ai.openai.api-key 属性来配置它。

• 设置 Perplexity 基础 URL： 把 spring.ai.openai.base-url 属性设为 +https://api.perplexity.ai+。

• 选择一个 Perplexity 模型： 使用 spring.ai.openai.chat.model=<model name> 属性指定模型。 可用选项参阅受支持的模型。

你可以在 application.properties 文件中设置这些配置属性：

spring.ai.openai.api-key=<your-perplexity-api-key>
spring.ai.openai.base-url=https://api.perplexity.ai
spring.ai.openai.chat.model=llama-3.1-sonar-small-128k-online

为在 handling 诸如 API 密钥这类敏感信息时获得更强的安全性，你可以使用 Spring 表达式语言（SpEL）引用自定义环境变量：

# In application.yml
spring:
  ai:
    openai:
      api-key: ${PERPLEXITY_API_KEY}
      base-url: ${PERPLEXITY_BASE_URL}
      chat:
        model: ${PERPLEXITY_MODEL}

# In your environment or .env file
export PERPLEXITY_API_KEY=<your-perplexity-api-key>
export PERPLEXITY_BASE_URL=https://api.perplexity.ai
export PERPLEXITY_MODEL=llama-3.1-sonar-small-128k-online

你也可以在应用代码中以编程方式设置这些配置：

// Retrieve configuration from secure sources or environment variables
String apiKey = System.getenv("PERPLEXITY_API_KEY");
String baseUrl = System.getenv("PERPLEXITY_BASE_URL");
String model = System.getenv("PERPLEXITY_MODEL");

添加仓库与 BOM

Spring AI 的制品发布在 Maven Central 和 Spring Snapshot 仓库中。 参见 制品仓库 一节，把这些仓库添加到你的构建系统。

为便于依赖管理，Spring AI 提供了一个 BOM（物料清单），以确保整个项目中使用一致版本的 Spring AI。参见 依赖管理 一节，把 Spring AI BOM 添加到你的构建系统。

自动配置

NOTE

Spring AI 的自动配置、starter 模块的制品名称发生了重大变更。 更多信息请参阅 升级说明。

Spring AI 为 OpenAI 聊天客户端提供 Spring Boot 自动配置。 要启用它，请将以下依赖添加到你的项目的 Maven pom.xml 或 Gradle build.gradle 构建文件：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

TIP

参见 依赖管理 一节，把 Spring AI BOM 添加到你的构建文件。

聊天属性

重试属性

前缀 spring.ai.retry 用作配置 OpenAI 聊天模型重试机制的属性前缀。

属性	描述	默认值
spring.ai.retry.max-attempts	最大重试尝试次数。	10
spring.ai.retry.backoff.initial-interval	指数退避策略的初始等待时长。	2 sec.
spring.ai.retry.backoff.multiplier	退避间隔乘数。	5
spring.ai.retry.backoff.max-interval	最大退避时长。	3 min.
spring.ai.retry.on-client-errors	若为 false，则抛出 NonTransientAiException，不对 4xx 客户端错误码尝试重试	false
spring.ai.retry.exclude-on-http-codes	不应触发重试的 HTTP 状态码列表（例如抛出 NonTransientAiException）。	empty
spring.ai.retry.on-http-codes	应触发重试的 HTTP 状态码列表（例如抛出 TransientAiException）。	empty

连接属性

前缀 spring.ai.openai 用作连接 OpenAI 的属性前缀。

属性	描述	默认值
spring.ai.openai.base-url	要连接到的 URL。必须设为 +https://api.perplexity.ai+	-
spring.ai.openai.chat.api-key	你的 Perplexity API 密钥	-

配置属性

NOTE

聊天自动配置的启用与禁用，现通过以 spring.ai.model.chat 为前缀的顶层属性来配置。

要启用，spring.ai.model.chat=openai（默认启用）

要禁用，spring.ai.model.chat=none（或任何不匹配 openai 的值）

做出此变更是为了支持配置多个模型。

前缀 spring.ai.openai.chat 是为 OpenAI 配置聊天模型实现的属性前缀。

属性	描述	默认值
spring.ai.model.chat	启用 OpenAI 聊天模型。	openai
spring.ai.openai.chat.model	某个受支持的 Perplexity 模型。例如：llama-3.1-sonar-small-128k-online。	-
spring.ai.openai.chat.base-url	可选，覆盖 spring.ai.openai.base-url 以提供一个聊天专用 url。必须设为 +https://api.perplexity.ai+	-
spring.ai.openai.chat.temperature	响应的随机量，取值介于 0（含）与 2（不含）之间。较高的值更随机，较低的值更确定。必需范围：0 < x < 2。	0.2
spring.ai.openai.chat.frequency-penalty	一个大于 0 的乘性惩罚。大于 1.0 的值会依据新令牌在迄今文本中的既有频率对其加以惩罚，降低模型逐字重复同一行的可能性。值为 1.0 表示无惩罚。与 presence_penalty 不兼容。必需范围：x > 0。	1
spring.ai.openai.chat.max-tokens	API 返回的补全令牌最大数。max_tokens 中请求的令牌总数加上 messages 中发送的提示词令牌数，不得超过所请求模型的上下文窗口令牌限制。若未指定，模型会一直生成令牌直到遇到其停止标记或到达其上下文窗口末尾。	-
spring.ai.openai.chat.presence-penalty	一个介于 -2.0 与 2.0 之间的值。正值依据新令牌是否已在迄今文本中出现对其加以惩罚，提升模型谈论新话题的可能性。与 frequency_penalty 不兼容。必需范围：-2 < x < 2	0
spring.ai.openai.chat.top-p	核采样阈值，取值介于 0 与 1（含）。对每个后续令牌，模型会考虑具有 topp 概率质量的那些令牌的结果。我们建议调整 topk 或 top_p，但不要同时调整两者。必需范围：0 < x < 1	0.9
spring.ai.openai.chat.stream-usage	（仅流式）设置后会为整个请求附加一个带令牌用量统计的额外块。该块的 choices 字段为空数组，其余所有块也会包含一个 usage 字段但值为 null。	false

TIP

所有以 spring.ai.openai.chat 为前缀的属性，都可通过在 Prompt 调用中添加一个请求专用的 chat-options 在运行时被覆盖。

运行时选项

OpenAiChatOptions.java 提供模型配置，例如要使用的模型、温度、频率惩罚等。

在启动时，可通过 OpenAiChatModel(api, options) 构造器或 spring.ai.openai.chat.* 属性配置默认选项。

在运行时，你可以通过向 Prompt 调用添加新的、请求特定的选项来覆盖默认选项。 例如，要为某个特定请求覆盖默认的模型和温度：

ChatResponse response = chatModel.call(
    new Prompt(
        "Generate the names of 5 famous pirates.",
        OpenAiChatOptions.builder()
            .model("llama-3.1-sonar-large-128k-online")
            .temperature(0.4)
        .build()
    ));

TIP

除模型特定的 OpenAiChatOptions 外，你还可以使用一个可移植的 ChatOptions 实例，通过 ChatOptions#builder() 创建。

工具调用

NOTE

Perplexity 不支持显式工具调用。它转而把搜索结果直接集成进响应。关于 Spring AI 通用工具调用架构，参见工具调用。

多模态

NOTE

当前，Perplexity API 不支持媒体内容。

示例控制器

创建 一个新的 Spring Boot 项目，并把 spring-ai-starter-model-openai 添加到你的 pom（或 gradle）依赖。

在 src/main/resources 目录下添加一个 application.properties 文件，以启用并配置 OpenAi 聊天模型：

spring.ai.openai.api-key=<PERPLEXITY_API_KEY>
spring.ai.openai.base-url=https://api.perplexity.ai
spring.ai.openai.chat.model=llama-3.1-sonar-small-128k-online
spring.ai.openai.chat.temperature=0.7

# The Perplexity API doesn't support embeddings, so we need to disable it.
spring.ai.model.embedding=none

TIP

用你的 Perplexity Api 密钥替换 api-key。

这会创建一个可注入到你类中的 OpenAiChatModel 实现。 下面是一个简单 @Controller 类的示例，它使用聊天模型进行文本生成。

@RestController
public class ChatController {

    private final OpenAiChatModel chatModel;

    @Autowired
    public ChatController(OpenAiChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping("/ai/generate")
    public Map generate(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        return Map.of("generation", this.chatModel.call(message));
    }

    @GetMapping("/ai/generateStream")
	public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        Prompt prompt = new Prompt(new UserMessage(message));
        return this.chatModel.stream(prompt);
    }
}

受支持的模型

Perplexity 支持多种为搜索增强的对话式 AI 优化的模型。细节参阅受支持的模型。

参考

• 文档主页
• API 参考
• 开始使用
• 速率限制