版本：Dev

Perplexity

Perplexity Sonar 提供以搜索结果为依据的模型，将语言模型响应与网页检索相结合。应用通过稳定的 AISIX 别名调用 Sonar，同时由网关保存 Perplexity 凭证。

准备工作

开始前，请准备以下内容：

一套 AISIX 环境：
- 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
- 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 配置。配置网关以加载声明式资源文件。
一个 Perplexity API Key。有关创建方法，请参阅 Perplexity 快速入门。
已安装 curl 和 jq。

使用 AISIX Cloud 配置

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且不含尾部斜杠
# 本地私有化部署快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

为 Perplexity 支持的 Chat Completions 路由创建服务提供方密钥、模型别名和调用方 API Key。

由于 Perplexity 提供 OpenAI 兼容的 Chat Completions API，AISIX 会通过 openai 适配器连接，并将 Perplexity API Root 用作 api_base。AISIX 不会注册 Perplexity 特定的请求或响应重写。

创建服务提供方密钥

创建用于保存 Perplexity 凭证和 API Root 的服务提供方密钥：

# 请替换为实际值
export PERPLEXITY_API_KEY="YOUR_PROVIDER_API_KEY"

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "perplexity-prod",
    "provider": "perplexity",
    "api_key": "'"${PERPLEXITY_API_KEY}"'",
    "api_base": "https://api.perplexity.ai",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

❶ provider 为 perplexity。AISIX Cloud Admin API 会从目录服务提供方派生适配器；adapter 字段仅适用于 BYO 服务提供方密钥。

❷ api_key 保存 Perplexity API Key。该值遵循服务提供方密钥中的凭证处理行为。

❸ api_base 是裸主机 https://api.perplexity.ai，即 Perplexity 文档为 OpenAI SDK 客户端提供的 Base URL。其 OpenAI 兼容 Chat Completions 路由位于 /chat/completions，不包含版本片段，因此 Base 不带版本后缀。AISIX 会追加端点路径，生成 https://api.perplexity.ai/chat/completions。

对于此服务提供方，api_base 可选。省略时，AISIX Cloud Admin API 会填入 https://api.perplexity.ai。显式设置可让上游 Root 在资源中清晰可见。该值绝不能最终为空：对于 openai 以外使用 openai 适配器的服务提供方，AISIX 不会回退到 api.openai.com，而是返回上游配置错误，因此 Perplexity 凭证不会发送到公共 OpenAI 主机。

AISIX 会移除 api_base 末尾的端点片段，因此粘贴文档中的完整端点 URL https://api.perplexity.ai/chat/completions 后仍会解析为相同 Base。尾部斜杠也会被移除。

该命令会把返回的服务提供方密钥 ID 保存到 PROVIDER_KEY_ID。

创建模型

Perplexity 模型 ID 表示搜索层级，而不是参数数量或发布日期。它们是不带厂商命名空间和日期快照后缀的裸名称：sonar 用于快速生成有依据的回答，sonar-pro 用于更广泛的检索和更强的综合分析，sonar-reasoning-pro 用于带引用的多步推理，sonar-deep-research 用于耗时较长的研究报告。

创建调用方将在请求中发送的模型别名：

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "perplexity-sonar-pro-prod",
    "model_name": "sonar-pro",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

❶ display_name 是调用方在 model 中发送的别名。

❷ model_name 是 Perplexity 模型 ID，例如 sonar-pro 或 sonar。

❸ provider_key_id 将该别名关联到 Perplexity 服务提供方密钥。

创建调用方 API Key

创建可访问该模型别名的调用方 API Key。密钥值由网关生成；明文仅在创建响应中返回一次，因此请立即保存：

AISIX_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "perplexity-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

echo "$AISIX_API_KEY"

allowed_models 值通过模型 ID 引用模型，因此该密钥只能访问你创建的别名。写入后，配置会自动投射到关联的网关。

使用开源 AISIX 网关配置

导出上游凭证，并选择应用将发送给网关的调用方 API Key：

export PERPLEXITY_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

对于新网关，请使用以下完整的声明式资源文件。对于现有网关，请把这些条目合并到当前文件，并保留其他资源：

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "perplexity-prod"
    provider: "perplexity"
    adapter: "openai"
    api_key: ${PERPLEXITY_API_KEY}
    api_base: "https://api.perplexity.ai"

models:
  - display_name: "perplexity-sonar-pro-prod"
    provider: "perplexity"
    model_name: "sonar-pro"
    provider_key: "perplexity-prod"

api_keys:
  - display_name: "perplexity-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "perplexity-sonar-pro-prod"

如果 AISIX 安装在本地，请在加载前验证文件：

aisix validate --resources resources.yaml

验证后，在网关进程环境中提供文件引用的环境变量，再启动网关。仅当这些变量已经可供进程使用时，才重新加载现有网关；否则，请使用更新后的环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件，并在两条命令中使用 -e 传入它引用的每个环境变量。资源加载后，准备下文共用的验证请求：

export AISIX_API_KEY="$CALLER_API_KEY"

验证服务提供方连接

导出 AISIX 网关 Origin：

# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

通过 AISIX 代理发送 Chat Completions 请求。Sonar 会根据实时网页搜索生成回答，因此请提出一个需要当前信息的问题：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "perplexity-sonar-pro-prod",
    "messages": [
      {
        "role": "user",
        "content": "Summarize the latest news about AI gateways in two sentences."
      }
    ]
  }'

网关返回 OpenAI 兼容响应，其中会回显面向调用方的别名 perplexity-sonar-pro-prod。如果请求失败，请检查服务提供方密钥的 api_key、api_base，以及 model_name 中的 Perplexity 模型 ID。

获取搜索引用

Sonar 响应在 Perplexity 响应体顶层的 citations 和 search_results 中携带来源，这两个字段与 choices 同级。它们是 Perplexity 扩展，而不是 OpenAI Chat Completions 格式的一部分。AISIX 会将 Chat Completions 响应标准化为规范的 OpenAI 格式，因此通过 /v1/chat/completions 时，这两个字段不会到达调用方。

当应用需要来源列表时，请改为调用服务提供方原生路由。本页的 /passthrough/perplexity 路径假定一条透传路由认领该前缀，target_url 设为 https://api.perplexity.ai；在调用方 Key 的 allowed_routes 上授予路由名称。AISIX 会原样转发请求体，注入路由绑定的服务提供方密钥凭证，并不加修改地返回上游响应：

curl -sS -X POST "$AISIX_PROXY/passthrough/perplexity/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonar-pro",
    "messages": [
      {
        "role": "user",
        "content": "Summarize the latest news about AI gateways in two sentences."
      }
    ]
  }'

perplexity 路径片段是路由认领的前缀——按约定使用服务提供方名——而不是别名；请求体携带上游模型 ID sonar-pro，而不是别名。AISIX 仍会认证调用方密钥，该密钥必须在 allowed_routes 列表中授予此路由名称。

备注

网关会自动识别请求的 Chat 信封（messages），因此 Sonar 响应中受支持的用量数字会尽力记录到用量事件上。透传 Token 只用于遥测：它们不会推进 tpm 或 tpd 计数器、确定模型成本，也不会增加预算支出。请参阅透传路由。

设置推理强度

Sonar 请求 Schema 提供 reasoning_effort 字段，其值可为 minimal、low、medium 和 high，但具体模型文档可能会缩小可接受值的范围。例如，Perplexity 当前为 sonar-deep-research 记录了 low、medium 和 high。

AISIX 会将其未建模的请求字段不加修改地转发到上游，因此请将该字段添加到 Chat Completions 请求体。以下示例假设已创建第二个别名 perplexity-sonar-research-prod，且其 model_name 设置为 sonar-deep-research：

{
  "model": "perplexity-sonar-research-prod",
  "messages": [{ "role": "user", "content": "Compare the two proposals." }],
  "reasoning_effort": "high"
}

AISIX 未为 Perplexity 注册 response.reasoning_field 映射，因此不会将 Perplexity 特定的推理字段提升到规范的 reasoning_content 位置。无论 Perplexity 将推理输出放在标准响应内容的哪个位置，都会原样到达调用方。如果未来某个 Perplexity 模型在独立的 delta 路径上流式返回推理内容，请在服务提供方密钥上设置 response.reasoning_field。

端点和成本边界

Perplexity 目前提供独立的 Sonar、Agent、Search 和 Embeddings API。它们使用不同的路径前缀，因此本指南配置的 Sonar 服务提供方密钥不能通过标准化 AISIX 路由访问所有 API。

路由	使用 Perplexity 别名时的行为
`/v1/chat/completions`	支持，包括 `stream: true`。
`/v1/completions`	不可用。Perplexity 未提供旧版提示词补全路由。
`/v1/responses`	通过 Sonar Chat Completions 上的 Responses 桥接提供支持，而不是使用 Perplexity 原生 Agent API。没有对应 Chat 语义的字段会被忽略。需要原生 Responses 兼容契约时，请使用 `/passthrough/perplexity/v1/responses`，并发送 Agent API 模型 ID 或 Preset，而不是 AISIX 别名。
`/v1/messages`	通过转换到 Sonar Chat Completions 支持兼容的 Anthropic 形态请求。`/v1/messages/count_tokens` 不可用，因为它要求使用 Anthropic 协议的服务提供方密钥。
`/v1/embeddings`	不适用于上述 Sonar 服务提供方密钥：AISIX 会把 `/embeddings` 追加到裸主机，而 Perplexity 在 `/v1/embeddings` 提供标准 Embedding。请创建 `api_base: https://api.perplexity.ai/v1` 的单独服务提供方密钥，并为 `pplx-embed-v1-0.6b` 或 `pplx-embed-v1-4b` 创建别名。
`/v1/images/generations`	拒绝。该路由仅接受所配置服务提供方为 `openai` 的模型。
`/v1/rerank`	拒绝。该路由的允许列表为 `openai`、`cohere` 和 `jina`。
`/v1/videos`	拒绝。该路由的允许列表中不包含 `perplexity`。
`/v1/models`	返回调用方可访问的 AISIX 别名。请通过 `/passthrough/perplexity/v1/models` 获取当前 Agent API 模型列表。
`/passthrough/perplexity/search`	调用 Perplexity 原生 Search API，并返回原始搜索结果。
`/passthrough/perplexity/*rest`	通过已配置的透传路由可用。用于服务提供方原生的请求和响应格式。

Perplexity 标准 Embedding 模型返回量化的 Base64 字符串，而不是浮点数组。AISIX 会保留该响应表示。调用方必须解码 base64_int8 或 base64_binary，并使用 Perplexity 记录的相似度度量。

另有两个边界会影响 Perplexity 流量的建模方式：

Sonar 不提供调用方定义的函数工具。Sonar Pro Search 可以调用 Perplexity 管理的搜索和 URL 获取工具，而 Agent API 提供更广泛的工具契约。请通过兼容的 Agent API 模型或其他服务提供方路由自定义函数调用工作负载。
AISIX 成本元数据以每 1,000 个输入和输出 Token 的 USD 金额表示。除了提示词和补全 Token 外，Perplexity 还按引用 Token、搜索查询和推理 Token 对 sonar-deep-research 计费，因此仅按 Token 估算会低估该模型的实际支出。请将网关中 sonar-deep-research 的成本数据视为下限，并与 Perplexity 账单核对。

后续步骤

你已将 AISIX 连接到 Perplexity，并验证了模型别名。接下来可阅读以下指南：

模型别名：为该别名配置路由、重试行为或成本元数据。
路由与故障转移：在 Perplexity 与另一个服务提供方之间执行故障转移。
服务提供方特定覆盖项：当上游 API 与其适配器不同时，调整请求和响应形态。
服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。

准备工作​

使用 AISIX Cloud 配置​

创建服务提供方密钥​

创建模型​

创建调用方 API Key​

使用开源 AISIX 网关配置​

验证服务提供方连接​

获取搜索引用​

设置推理强度​

端点和成本边界​

后续步骤​