Perplexity-Agent-API-Preset-动态配置与-Frozen-Configuration-怎么选

动态 Preset 自动跟随官方优化，Frozen Configuration 固定模型、工具和 Prompt。本文提供选型矩阵、配置与生产发布方案。

摘要： Perplexity Agent API 的 Preset 提供两种使用方式：按 preset="low" 等名称调用的 Dynamic Preset，会自动获得 Perplexity 后续优化；把当前 Preset 的模型、工具、System Prompt 和参数完整复制到请求中的 Frozen Configuration，则固定今天的行为。本文解释两者的配置解析、覆盖与工具合并规则、Prompt Cache、成本和回归风险，并给出开发、灰度、生产、合规和高稳定工作流的选型方案。核心建议是：探索性应用优先动态 Preset，关键生产链路使用冻结配置，团队最好采用“动态跟踪 + 自动评测 + 人工晋级冻结版本”的双轨模式。

核心结论

Dynamic Preset 与 Frozen Configuration 的选择，本质上是“自动获得质量改进”与“固定可复现行为”之间的权衡。动态 Preset 由 Perplexity 维护，Preset 名称不带明确版本，底层模型、工具、System Prompt 和参数可随官方评测改进而更新；Frozen Configuration 则把当前完整配置内联到请求中并省略 preset 字段，从而阻止未来 Preset 更新自动进入生产环境。

默认建议： 原型、内部研究、低风险问答和追求最新效果的应用使用动态 Preset。
生产建议： 合规、固定预算、关键工作流、强回归要求和需要重现历史输出的系统使用 Frozen Configuration。
最佳实践： 不必二选一。测试环境持续跟踪动态 Preset，评测通过后把当前值冻结并晋级生产。
覆盖规则： 与 Preset 同时传入的普通字段会覆盖默认值；tools 是例外，会按 Tool 合并，而不是整组替换。
重要限制： API Response 可看到实际模型、Tool 调用和成本，但不会返回完整有效 System Prompt、max_steps、Reasoning 或完整继承 Tool 集，不能只靠运行后响应重建 Frozen Configuration。

Perplexity Agent API Preset 是什么

Preset 是针对不同任务形态维护的一组预配置，它不仅是模型别名，还打包了模型、搜索配置、Reasoning Steps、System Prompt 和可用工具。开发者只需选择能力档位，不必从零组合搜索、抓取、代码执行和推理预算。

当前官方文档使用分层名称：fast、low、medium、high、xhigh 和 wide-research。旧名称已映射到新名称，例如 fast-search → fast、pro-search → low、deep-research → medium、advanced-deep-research → high、ultra → xhigh。

Preset	主要能力	典型任务	选型重点
`fast`	单事实检索、定义、快速摘要	高频客服事实、短答案	延迟优先
`low`	日常研究、轻量多步搜索	新闻摘要、产品调研	成本与质量平衡
`medium`	多跳浏览、广泛聚合	竞品与技术研究	证据链与覆盖
`high`	专家级推理、最大化来源覆盖	机构级研究草案	完整性优先
`xhigh`	开放式 Agent、代码沙箱、长工具循环	复杂任务执行	能力优先
`wide-research`	大规模发现并逐项研究	榜单、市场地图、供应商清单	批量结构化结果

这张表描述的是任务 Profile，不代表固定模型。动态 Preset 的底层配置可能变化；需要精确模型与工具时必须冻结。

Dynamic Preset 如何工作

动态模式直接传递 preset 名称：

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    preset="low",
    input="比较三种企业 RAG 权限隔离方案，并提供来源。",
)

print(response.model)
print(response.output_text)

Perplexity 会把 low 解析成当前推荐的模型、System Prompt、Tool Set、Search Configuration 和 Step Budget。当官方评测显示新配置有显著改进时，Preset 名称保持不变，而调用自动获得更新。

官方说明，更新会尽量保持同一成本和延迟档位：底层模型可以变化，但目标是接近原有 Cost Band 与 Latency Band；主要优化维度是质量。这里的“尽量保持”不是费用和延迟完全固定的 SLA。模型价格、优先处理、工具次数和输出长度仍可能改变真实账单。

动态模式的优势

无需改代码即可得到官方优化的模型和 Prompt。
减少团队维护长 System Prompt 与 Tool Schema 的负担。
适合快速迭代和跟踪新模型。
Preset 自动使用稳定的 prompt_cache_key 缓存共享 Prompt 前缀，有利于不同请求之间复用缓存。

动态模式的代价

同一输入在不同日期可能使用不同模型或工具策略。
回归测试可能因官方更新而变化。
成本和延迟虽保持同一 Profile，但不能视为完全锁定。
当事故发生时，历史请求的完整有效配置不一定能从 Response 还原。

Dynamic 由服务端解析最新配置，Frozen 把完整配置固化在应用版本中。

Frozen Configuration 如何工作

冻结不是调用一个名为 frozen 的参数，也不是给 Preset 加版本号。官方定义的做法是：从 Presets 文档的 Current preset values 区域复制某个 Preset 的完整自包含配置，把模型、Prompt Cache Key、Max Steps、Reasoning、Service Tier、Output Tokens、Tools 与 System Prompt 直接放进请求，并且省略 preset 参数。

概念示例：

from datetime import datetime, timezone
from perplexity import Perplexity

client = Perplexity()
current_date = datetime.now(timezone.utc).strftime("%Y-%m-%d")

response = client.responses.create(
    # Do not pass preset here.
    model="MODEL_COPIED_FROM_CURRENT_PRESET_VALUES",
    prompt_cache_key="YOUR_FROZEN_CONFIG_V1",
    max_steps=1,
    max_output_tokens=8192,
    reasoning={"effort": "minimal"},
    service_tier="priority",
    instructions=f"""
Current UTC date: {current_date}

PASTE_THE_COMPLETE_CURRENT_SYSTEM_PROMPT_HERE
""",
    tools=[
        {
            "type": "web_search",
            "max_results": 10,
        }
    ],
    input="解释今天的主要 AI API 更新并提供引用。",
)

不要把上面的占位配置当作可直接上线的官方 Preset。真正冻结时必须从当前官方页面复制完整单个 Block。官方提示 cURL Tab 可能比 SDK Tab 展示更完整，因为部分参数尚未在 SDK 中暴露。

`{{current_date}}` 的特殊边界

Perplexity API 只会在 Preset 默认 Instructions 中替换 {{current_date}}。如果开发者把同样的占位符写入请求自带 instructions，它会按普通文本发送。因此 Frozen Configuration 示例会在客户端计算当前 UTC 日期后再注入。

Frozen Configuration 的优势

精确固定模型、工具、参数和 System Prompt。
便于做版本化、回归、审计和故障复现。
官方更新不会未经评测进入生产。
可在 Git 中 Review 每次配置变更。

Frozen Configuration 的代价

不会自动获得质量提升、模型迁移和 Prompt 改进。
团队要持续关注 Changelog 与 Current preset values。
长 System Prompt 与 Tool 定义会增加维护量。
固定旧模型可能遇到价格变化、能力落后或未来退役，需要迁移计划。

Preset 覆盖与 Tools 合并规则

动态 Preset 不是不可修改的黑盒。与 preset 一起传递的字段会覆盖 Preset 默认值，例如 model、max_steps、reasoning 和 max_output_tokens。

response = client.responses.create(
    preset="low",
    input="分析这个分布式数据库并发控制问题。",
    max_steps=8,
    reasoning={"effort": "high"},
    max_output_tokens=16384,
)

这会保留 low 的其他默认值，只覆盖显式字段。但 tools 的规则不同：工具按 type 合并，而不是整个数组替换。

response = client.responses.create(
    preset="low",
    input="只使用 FDA 与 ClinicalTrials.gov 解释加速审批。",
    tools=[{
        "type": "web_search",
        "max_tokens": 6000,
        "max_tokens_per_page": 1200,
        "filters": {
            "search_domain_filter": ["fda.gov", "clinicaltrials.gov"]
        }
    }],
)

这里仅覆盖 web_search 的选项，Preset 中其他工具仍可保持启用。很多团队以为传入一个 Tool 数组会自动禁用全部未列工具，这是危险误解。若需要严格 Tool Allowlist，应该使用 Frozen Configuration 显式列出工具，或根据官方支持方式逐个控制，而不是依赖“我没写就不会启用”。

Prompt Cache 对选择有什么影响

动态 Preset 会为共享 Prompt 前缀自动使用稳定 prompt_cache_key，前缀包括 System Prompt 和 Tool Definitions。开发者无需设置；显式请求级 Key 会覆盖 Preset 默认值。

官方 Changelog 表示，这可能让频繁使用 Preset 的应用因缓存利用率降低约 5% 成本，但实际结果取决于缓存命中率。不能把这一数字当作所有应用保证。

Frozen Configuration 应保留官方 Current preset values 中的 Prompt Cache Key，或使用自己的版本化 Key：

research-low-frozen-v2026-08-26

当 System Prompt、Tool Definitions 或影响前缀语义的字段变化时，应改变 Key，避免错误复用。把所有配置版本永久共享同一 Key 会削弱可观测性。

Dynamic、Frozen 与混合模式选型

场景	推荐模式	原因
原型与 MVP	Dynamic	快速获得最新优化，维护少
内部研究助手	Dynamic + Overrides	允许质量变化，可针对任务调 Steps
新闻与趋势摘要	Dynamic	最新搜索策略更重要
自动发布内容	Frozen	输出结构与安全边界需回归
法律、医疗、金融辅助	Frozen	需要版本、审计与变更审批
大批量结构化数据生产	Frozen	成本、Schema 和失败率要稳定
高级研究分析	Dynamic Canary + Frozen Production	既追踪提升又保护生产
关键 Agent 工具写操作	Frozen	Tool Allowlist 与参数必须显式

一个实用判断公式：

需要冻结的强度 =
  业务后果
  + 回归敏感度
  + 成本敏感度
  + 审计要求
  + 工具权限风险
  - 对自动质量升级的容忍度

如果输出只供人阅读且可以重试，Dynamic 通常更合适；如果输出会触发数据库写入、发信、交易、发布或权限修改，应优先 Frozen 并保留人工审批。

配置清单与版本化示例

建议把 Frozen Configuration 的来源和验证信息与代码一起保存：

perplexity_agent_config:
  internal_version: "research-low-2026-08-26.1"
  source:
    preset: "low"
    copied_at_utc: "2026-08-26T00:00:00Z"
    docs_url: "https://docs.perplexity.ai/docs/agent-api/presets"
  mode: "frozen"
  config_hash: "SHA256_OF_CANONICAL_CONFIG"
  validation:
    eval_suite: "research-eval-v12"
    citation_pass_rate: "MEASURE_IN_YOUR_SYSTEM"
    max_cost_usd: "YOUR_BUDGET"
    p95_latency_ms: "YOUR_LIMIT"
  release:
    approved_by: "TECH_OWNER"
    rollback_version: "research-low-previous"

这里不要伪造通过率、成本与延迟。它们必须来自自己的测试。config_hash 应基于规范化后的模型、Instructions、Tools 与参数计算，用于证明运行配置未被偷偷修改。

如何观测实际运行

Perplexity 官方 Cookbook 建议读取：

response.model：实际服务模型；
response.usage.tool_calls_details：实际调用工具；
response.usage.cost.total_cost：请求账单成本。

def inspect_run(response):
    print("model:", response.model)
    print("status:", response.status)
    print("tools:", response.usage.tool_calls_details)
    print("cost:", response.usage.cost.total_cost)

但 Response 不暴露完整有效 System Prompt、max_steps、Reasoning 或完整继承工具集。因此这些字段只说明“观察到什么”，不能证明“完整配置是什么”。生产审计必须在请求前记录自己的配置版本，而不是事后猜测。

成本与延迟怎么控制

Dynamic Preset 更新以保持相近 Cost/Latency Band 为目标，但仍需设置业务门槛：

记录每次请求的 Preset、实际模型、Tool Calls、总成本和延迟。
对 max_steps、max_output_tokens、Web Search Token Budget 设置上限。
将 fast/low 用于高频简单查询，避免所有请求统一 high/xhigh。
对宽研究任务建立异步队列、超时、取消和预算审批。
Preset Changelog 更新后重新跑成本回归。

2026 年 8 月官方更新中，fast Preset 改用 openai/gpt-5.6-luna、minimal Reasoning 与 priority Service Tier；Changelog 说明 Priority Processing 按模型标准 Token 价格的 2 倍计费。动态请求自动获得变化，Frozen 用户需要手动更新。这正好说明：相同 Preset 名称不等于永远相同底层价格结构。

常见错误与排查

Dynamic 输出突然变化

检查 Perplexity Changelog、response.model、Tool Calls 与成本。确认 Preset 是否更新，Prompt 是否依赖未声明格式。若业务不容许变化，回退到经过验证的 Frozen Configuration。

Frozen 配置仍无法重现历史结果

冻结配置只能固定请求设置，不能保证生成式模型逐 Token 完全确定。还要固定输入、日期、来源、外部网页内容和温度类参数，并记录响应证据。搜索结果变化会改变输出。

覆盖 Tools 后出现意外工具调用

记住 Tools 按类型合并。传入 web_search 选项不会移除 Preset 的其他工具。需要严格工具范围时使用完整 Frozen 配置，并验证 usage.tool_calls_details。

冻结时漏掉 System Prompt

不能只复制模型与 max_steps。从官方 Current preset values 中复制完整自包含 Block，优先检查 cURL Tab 是否包含 SDK 未暴露字段，并保存配置 Hash。

`{{current_date}}` 没被替换

请求自定义 Instructions 中的占位符不会自动替换。客户端生成 UTC 日期后写入字符串，不要依赖 Preset 内部模板行为。

风险、限制与安全边界

Dynamic Preset 没有显式版本号，同名调用始终解析到最新推荐配置。
官方承诺的是相近 Cost/Latency Profile，不是完全固定价格或响应时间。
Frozen Configuration 需要主动跟踪模型退役、价格变动、SDK 字段和安全修复。
搜索结果与网页会变化，即使配置冻结也不能保证输出完全相同。
Tool 合并可能扩大可用工具范围，写操作必须使用 Allowlist 与人工审批。
引用存在不匹配可能，生产使用前要验证 Citation ID 与 Source Result。
付款、删除、发布、发信、修改权限和生产数据库操作必须人工确认。

更多 Agent API 基础内容可查看 AI Stack Nav 的 Perplexity API 教程，生产评测与发布流程可参考 AI Agent 回归测试专题。

事实依据与来源

Perplexity 官方已确认： Dynamic Preset 按名称解析最新配置，底层模型、工具、Prompt 和参数可更新，且没有显式 Preset 版本号。
Perplexity 官方已确认： Frozen Configuration 通过复制当前完整值并省略 preset 参数实现。
Perplexity 官方已确认： 普通字段覆盖 Preset 默认值，Tools 按 Tool 合并而非整组替换。
Perplexity 官方已确认： 动态 Preset 自动使用稳定 Prompt Cache Key；请求级 Key 可覆盖它。
Perplexity 官方已确认： Response 可观察实际模型、工具调用与成本，但不暴露完整有效配置。
实施建议： 动态候选、Nightly Eval、Canary、人工冻结和 Production Rollback 是本文推荐的工程流程，不是官方强制要求。
需自行验证： 质量、成本、缓存节省、延迟与引用正确率应由团队用真实测试集测量。

FAQ

Perplexity Dynamic Preset 会自动升级模型吗？

会。Preset 名称解析到官方当前推荐配置，底层模型可以改变。官方目标是保持相近成本和延迟 Profile，同时提升质量，但不承诺配置永久不变。

Frozen Configuration 是 API 参数吗？

不是。冻结是工程方法：复制 Current preset values 的完整配置到请求，省略 preset 字段。Perplexity 不提供 frozen=true 开关。

Dynamic Preset 是官方推荐方式吗？

是，官方把 Dynamic Preset 标为推荐方式，因为能自动获得优化。但关键生产系统是否采用仍取决于回归、成本、合规和稳定性要求。

可以使用 Preset 同时覆盖模型吗？

可以。显式 model 会覆盖 Preset 默认模型，其余未传字段保留 Preset 默认值。此时仍属于动态组合，其他继承配置未来可能变化。

传入 Tools 会禁用 Preset 其他工具吗？

不会自动禁用。Tools 按类型合并，传一个 Web Search 配置只覆盖该 Tool 选项，其他 Preset Tools 仍可能可用。

Frozen Configuration 能保证完全相同输出吗？

不能。它固定请求配置，但模型生成、搜索结果、网页、日期和外部工具都可能变化。它提高可重现性，不提供逐 Token 确定性。

如何知道动态 Preset 实际用了哪个模型？

读取 response.model。同时检查 response.usage.tool_calls_details 和 response.usage.cost.total_cost，但这些字段无法还原完整 System Prompt 与继承配置。

Prompt Cache Key 需要自己设置吗？

动态 Preset 会自动使用稳定 Key，无需手动设置。显式 Key 会覆盖默认。Frozen Configuration 可采用官方当前 Key或内部版本化 Key。

企业生产环境最推荐哪种方式？

推荐双轨：测试环境跟踪 Dynamic Preset，运行固定评测与 Canary；通过后复制完整配置形成 Frozen Release，再发布生产并保留旧版本回滚。

参考来源

安装部署教程

环境配置与 Docker 工作流

适合阅读安装部署、本地配置、服务器搭建和自动化流程类文章后继续转化。

环境配置资料包 包含 Windows / Mac / Linux 常见环境配置、依赖安装和报错排查清单。 查看资料包 Docker 工作流包 整理 Docker 部署模板、compose 示例和常用服务编排流程。 查看资料包