版本：Dev

Perplexity

Perplexity Agent API将第三方语言模型与 Perplexity 托管的搜索和 Agent 工具结合起来。应用通过 AISIX 调用服务提供方原生 API，网关保存 Perplexity 凭证，并控制哪些调用方可以使用该路由。

Perplexity 已于 2026 年 9 月 27 日结束 Sonar Chat Completions 支持。其迁移指南说明了部分同步和流式 Sonar 请求的过渡性改写行为，但 Perplexity 不会改写异步请求。请勿依赖这种兼容行为。新集成应使用 Agent API，现有 Sonar 集成应按照 Perplexity 的迁移指南迁移。

前置条件

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

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

使用 AISIX Enterprise 或 AISIX Cloud 配置

导出控制面连接信息和 Perplexity 凭证：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且不带尾部斜杠
# 本地 AISIX Enterprise 快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"
export PERPLEXITY_API_KEY="YOUR_PERPLEXITY_API_KEY"

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

if ! PROVIDER_RESPONSE=$(curl --fail-with-body -sS -X POST \
  "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Perplexity Agent API",
    "provider": "perplexity",
    "api_key": "'"${PERPLEXITY_API_KEY}"'",
    "api_base": "https://api.perplexity.ai/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }'); then
  printf '%s\n' "$PROVIDER_RESPONSE" >&2
  false
elif ! PROVIDER_KEY_ID=$(printf '%s' "$PROVIDER_RESPONSE" | jq -er '.provider_key.id'); then
  printf '%s\n' "$PROVIDER_RESPONSE" >&2
  false
fi

创建透传路由，将 Perplexity 的 /v1 API 挂载到 /passthrough/perplexity：

if ! ROUTE_RESPONSE=$(curl --fail-with-body -sS -X POST \
  "$AISIX_CP/environments/$ENV_ID/passthrough_routes" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "perplexity-agent",
    "path_prefix": "/passthrough/perplexity",
    "target_url": "https://api.perplexity.ai/v1",
    "credential_mode": "inject",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }'); then
  printf '%s\n' "$ROUTE_RESPONSE" >&2
  false
else
  printf '%s' "$ROUTE_RESPONSE" | jq '.warnings // []'
fi

路由先移除 /passthrough/perplexity，再将剩余路径拼接到 target_url。因此，对 /passthrough/perplexity/agent 的请求会到达 Perplexity 标准的 POST /v1/agent 端点。

创建获准使用此路由的调用方 Key。明文值只返回一次：

if ! CALLER_RESPONSE=$(curl --fail-with-body -sS -X POST \
  "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Perplexity Agent caller",
    "allowed_models": [],
    "allowed_routes": ["perplexity-agent"]
  }'); then
  printf '%s\n' "$CALLER_RESPONSE" >&2
  false
elif ! AISIX_API_KEY=$(printf '%s' "$CALLER_RESPONSE" | jq -er '.plaintext'); then
  printf '%s\n' "$CALLER_RESPONSE" >&2
  false
else
  export AISIX_API_KEY
  printf '%s' "$CALLER_RESPONSE" | jq '.warnings // []'
fi

控制面会把服务提供方密钥、路由和调用方授权投射到已接入的网关。上线前请检查所有兼容性警告，再通过每个网关验证流量。

使用 AISIX OSS 配置

导出上游和调用方凭证：

export PERPLEXITY_API_KEY="YOUR_PERPLEXITY_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

对于新网关，请使用下面这份完整资源文件。对于已有网关，请将条目合并到其当前文件中，并保留其他资源：

resources.yaml
_format_version: "1"

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

passthrough_routes:
  - name: "perplexity-agent"
    path_prefix: "/passthrough/perplexity"
    target_url: "https://api.perplexity.ai/v1"
    provider_key: "perplexity-agent"

api_keys:
  - display_name: "perplexity-agent-caller"
    key_env: CALLER_API_KEY
    allowed_models: []
    allowed_routes:
      - "perplexity-agent"

加载前，请验证完整文件：

aisix validate --resources resources.yaml

启动网关时，应确保进程能够访问这两个环境变量。如果使用 Docker，请像 AISIX OSS 快速入门所示，在验证和启动时通过 -e 传入变量。

资源加载后，为共用的验证请求准备调用方凭证：

export AISIX_API_KEY="$CALLER_API_KEY"

验证 Agent API 路由

导出 AISIX 网关 Origin：

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

使用 Perplexity 的 fast Effort 级别发送请求；该 Effort 级别适合快速提供基于网络信息的回答：

curl --fail-with-body -sS -X POST \
  "$AISIX_PROXY/passthrough/perplexity/agent" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "effort": "fast",
    "input": "Summarize the latest news about AI gateways in two sentences."
  }'

AISIX 会认证调用方、检查 perplexity-agent 路由授权、注入服务提供方凭证，并中继 Perplexity 的原生响应。透传路由上的网关不会重写 Effort 级别、模型标识符、请求字段或响应字段。

Perplexity 负责管理动态 Effort 级别背后的模型、工具和搜索配置，并可能更新这些配置。应用必须直接选择模型时，请使用 Perplexity 当前 Agent API 模型列表中的明确模型。有关 fast、low、medium、high 和 xhigh 之间的取舍，参见Effort 级别。

流式返回响应

将 stream 设置为 true，即可中继 Agent API 带类型的服务器发送事件：

curl --fail-with-body -sS -N -X POST \
  "$AISIX_PROXY/passthrough/perplexity/agent" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "effort": "fast",
    "input": "What changed in AI gateway technology this week?",
    "stream": true
  }'

流中包含输出文本增量、工具活动等带类型的事件。从 Sonar 迁移的应用必须更新消费者，不再假定响应是 choices[].delta.content 中的 Chat Completions 数据块。

在后台运行请求

对于耗时较长的任务，将 background 设置为 true，并保存响应 ID：

if ! RESPONSE=$(curl --fail-with-body -sS -X POST \
  "$AISIX_PROXY/passthrough/perplexity/agent" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "effort": "high",
    "input": "Compare the latest approaches to AI gateway reliability.",
    "background": true
  }'); then
  printf '%s\n' "$RESPONSE" >&2
  false
elif ! RESPONSE_ID=$(printf '%s' "$RESPONSE" | jq -er '.id'); then
  printf '%s\n' "$RESPONSE" >&2
  false
else
  echo "$RESPONSE_ID"
fi

通过同一路由按 ID 获取响应：

curl --fail-with-body -sS \
  "$AISIX_PROXY/passthrough/perplexity/agent/$RESPONSE_ID" \
  -H "Authorization: Bearer ${AISIX_API_KEY}"

持续轮询，直到响应进入终态。Perplexity 的后台模式文档还介绍了重新连接、事件流和取消操作。这是对已退役的 Sonar 异步 API 的替代；AISIX 不会把旧的异步 Sonar 请求转换为后台 Agent API 任务。

排查连接问题

错误或现象	检查内容
AISIX 在联系 Perplexity 前返回 `403`	确认调用方 Key 的 `allowed_routes` 列表包含 `perplexity-agent`。模型授权不会授予透传路由访问权限。
Perplexity 返回 `401` 或 `403`	确认服务提供方密钥包含有效的 Perplexity 凭证。对于 `403`，还需确认 Perplexity 账号有权使用请求的 Effort 级别、模型或工具。
Perplexity 返回 `404`	确认路由目标是 `https://api.perplexity.ai/v1`，网关请求使用 `/passthrough/perplexity/agent`。Search API 使用另一个根路径，不能使用此路由。
Perplexity 拒绝 Effort 级别或模型	使用当前Effort 级别列表中的 Effort 级别，或 Agent API 模型列表中的精确模型 ID。请勿向 Agent API 发送已退役的 Sonar 模型名。
获取后台响应返回 `404`	使用后台提交所返回的响应 ID 和同一 Perplexity 凭证。未知 ID 或属于其他账号的响应会返回 `404`。

使用 AISIX 模型别名

对于 Effort 级别和完整的服务提供方原生契约，优先使用透传配置。如果应用需要 AISIX 模型别名来使用模型级路由、限流或成本元数据，请另行配置基于模型的路径：

将服务提供方密钥的 api_base 设置为 https://api.perplexity.ai/v1。
添加 apis.responses: {}，声明 Perplexity 的原生 Responses 兼容端点。
创建模型别名，将其 model_name 设置为 Perplexity 当前 Agent API 模型列表中的精确模型 ID。
创建或更新调用方 Key，使其 allowed_models 列表授予该别名的访问权限。在 AISIX Enterprise 或 AISIX Cloud 中，使用模型资源 ID；在资源文件中，使用别名的 display_name。
调用 AISIX 的 /v1/responses，并在 model 中指定别名。

前面创建的仅用于透传的调用方，其 allowed_models 列表为空。在授予别名访问权限或改用另一把已授予模型访问权限的调用方 Key 之前，它不能调用该模型别名。

随后 AISIX 会把请求发送到 Perplexity 的 Agent API 别名 /v1/responses，把 AISIX 别名重写为上游模型 ID，并在响应中恢复别名。调用方请求必须包含 model，因此这种标准化路径不能只使用 Effort 级别作为配置。它也不能按响应 ID 调用 Perplexity 的后台获取路径；这些工作流请使用透传路由。

如果没有 apis.responses，AISIX 会把 /v1/responses 视为跨服务提供方桥接，将请求转换后发送到服务提供方密钥的 Chat Completions 路由。这条路径不会调用原生 Agent API，也无法保留 Agent API 专属字段或输出项。

API 边界

Perplexity 在 /v1 根路径下提供 Agent 和 Embeddings API。配置的透传路由可以访问这两个原生端点，但它们并不因此共用请求或响应 Schema。Perplexity 的 Search API 位于不带 /v1 前缀的 /search，因此需要另设目标为 https://api.perplexity.ai 的透传路由。

下表中的透传路由使用本页的主要配置。标准化路由需要可选的模型别名和获准使用该别名的调用方 Key，详见使用 AISIX 模型别名。

AISIX 路由	行为
`/passthrough/perplexity/agent`	调用标准 Agent API，支持同步、流式和后台请求。
`/passthrough/perplexity/responses`	调用 Agent API 的 OpenAI 兼容别名。Perplexity 建议使用其自己的 SDK 以获得完整原生契约。
`/passthrough/perplexity/models`	以 OpenAI 兼容格式列出当前可用的 Agent API 模型。
`/passthrough/perplexity/embeddings`	调用 Perplexity 的标准 Embeddings API。
`/passthrough/perplexity/contextualizedembeddings`	调用 Perplexity 的上下文化 Embeddings API，处理共享上下文的文档块。
`/v1/chat/completions`	需要可选的模型别名和已获模型访问权限的调用方。请勿将本页的服务提供方密钥用于此路由：AISIX 会向 `api_base` 追加 `/chat/completions`，访问未记录在文档中的 `https://api.perplexity.ai/v1/chat/completions` 路径。请改用透传 Agent API 路由，或配置原生 `/v1/responses`。
`/v1/responses`	需要可选的模型别名和已获模型访问权限的调用方。只有服务提供方密钥声明了 `apis.responses` 且请求指定了 AISIX 别名时，才会调用原生 Agent API；否则 AISIX 通过 Chat Completions 桥接请求。
`/v1/messages`	本页的配置不支持此路由。AISIX 会把 Anthropic 形态的请求转换后发送到 Chat Completions，访问未记录在文档中的 `/v1/chat/completions` 路径。请改用透传 Agent API 路由或原生 `/v1/responses` 路径。

透传 Token 数仅用于遥测。当顶层 model 值匹配同一服务提供方的 AISIX 别名时，可以应用该别名的请求次数限制。透传 Token 用量不会推进 tpm 或 tpd 计数器，不会解析 AISIX 模型成本元数据，也不会增加预算支出。参见透传路由。

Perplexity 标准向量嵌入模型返回量化的 base64 字符串，而不是浮点数数组。请按照 Perplexity 的向量嵌入最佳实践，解码 base64_int8 值并使用余弦相似度进行比较，或使用汉明距离比较 base64_binary 值。

下一步

透传路由：查看认证、路由匹配、请求头、安全护栏和遥测行为。
服务提供方密钥：配置凭证处理和原生 API 声明。
模型别名：调用方需要 AISIX 模型控制时，配置基于模型的 Agent API 路径。
服务提供方兼容性：查看支持的代理端点和服务提供方边界。

前置条件​

使用 AISIX Enterprise 或 AISIX Cloud 配置​

使用 AISIX OSS 配置​

验证 Agent API 路由​

流式返回响应​

在后台运行请求​

排查连接问题​

使用 AISIX 模型别名​

API 边界​

下一步​