本文目录
Perplexity 在 Agent API 官方文档(docs.perplexity.ai/docs/agent-api/prompt-caching)中设置了独立的 Prompt Caching 技术专页,系统说明模型服务商对重复提示词前缀的缓存机制、Cache read / Cache write 计费字段,以及基于 prompt_cache_key 和断点标记的细粒度控制方式。在此之前,Perplexity 已于 2026 年 8 月为 Agent API 预设(presets)引入自动稳定的提示词缓存键(官方注明高频使用预设时可降低约 5% 成本),相关生态接口动态亦可参阅站内 Perplexity Monitor API 文档与价表、Perplexity Decisions API 更新 以及 Perplexity 专题主页。
默认缓存机制与 Cache read / write 计费规则
默认情况下,Agent API 会在系统指令(system instructions)和最新一条消息上自动放置缓存断点,底层模型提供商也可能主动执行缓存;单次智能体运行(agent run)无需修改请求参数即可享受前缀缓存。响应体中的 usage 对象通过以下字段区分缓存用量与成本:
缓存读取(input_tokens_details.cache_read_input_tokens):命中缓存并读取的输入 token 数,按对应模型的 Cache read 费率计费;为兼容 OpenAI 格式,cached_tokens 字段同步返回相同数值,实际读取费用记录在 cost.cache_read_cost。
缓存写入(input_tokens_details.cache_creation_input_tokens):首次写入提示词缓存的输入 token 数,按对应模型的 Cache write 费率计费,写入费用记录在 cost.cache_creation_cost。具体费率按模型公布在 Agent API Models 价表中;若某模型价表未列出 Cache write 列或显示破折号,则写入 token 直接按标准 Input 单价计费。
高写入费率模型的成本风险:部分模型的 Cache write 单价高于普通输入单价——例如官方示例中的 openai/gpt-6.1-sol,在 Perplexity 价表中标准输入为 $2.00/1M(≤272k)或 $4.00/1M(>272k),Cache write 为 $2.50/1M(≤272k)或 $5.00/1M(>272k),Cache read 为 95% off input。对这类模型,如果整段提示词写入缓存后没有被后续请求复用,单次调用反而比不缓存更贵。
Agent API Models 参考与定价计算器已列入 openai/gpt-6.2-sol、openai/gpt-6.2-astra 及默认处理价,缓存读写按该表 cache 价计,而不按 input 价计;这两枚模型在 Perplexity 渠道上的默认处理价,亦见OpenAI 正式发布 GPT-6.2 Astra 与 GPT-6.2 Sol:旗舰推理与日常高效双线齐发,API 定价及 Ultrafast 档位公布。
用 prompt_cache_key 实现跨请求前缀复用
对于重试或包含多轮交互的任务,开发者应在共享相同前缀的每次请求中传入相同的 prompt_cache_key,使请求按缓存亲和性路由,从而读取前序请求写入的缓存:
账号隔离与路由边界:prompt_cache_key 严格限定在当前账号作用域内,即使不同账号使用相同键名也不会共享缓存;该参数也不会改变实际处理请求的底层模型。
按业务负载拆分键名:建议为每一类共享前缀的工作负载分配独立键名(例如每个固定文档或提示词模板对应一个 key),无关任务不要共用。不同的推理力度档位(effort levels)会为共享的系统提示词与工具定义生成默认键,手动传入的 prompt_cache_key 会覆盖该默认值。
前缀排列与多轮续接:由于缓存读取要求前缀完全匹配,固定内容(指令、参考文档、数据结构)必须放在提示词开头,动态变化的内容放在末尾。延续对话时,既可携带相同的 prompt_cache_key 并追加新轮次重新发送,也可直接传入 previous_response_id,使历史轮次原样抵达模型以命中缓存。
implicit 与 explicit 断点控制模式
开发者可通过 prompt_cache_options.mode 搭配内容块中的 prompt_cache_breakpoint 精确指定缓存边界:
implicit 模式(默认):Agent API 自动设置默认断点,同时允许服务商自动缓存。一旦请求中的 input_text 片段手动添加了 prompt_cache_breakpoint,自定义标记将替代默认断点,单次请求最多允许 3 个标记。
explicit 模式:关闭所有默认断点与自动缓存,仅对明确标记的 input_text 片段执行缓存,单次请求最多允许 4 个标记。针对前缀绝不会复用的单次请求,传入 "prompt_cache_options": {"mode": "explicit"} 且不加任何标记即可完全避免缓存写入费用。
断点生效规则、TTL 与 SDK 接入提示:在某段可复用前缀末尾的 input_text 放置断点后,其前方所有内容(含系统指令与更早消息)都会一并写入缓存;断点随响应保存,使用 previous_response_id 续接时会自动保留(若累计断点超出当前模式上限,则保留最新的几个)。若断点数量超限或标注在非 input_text 片段上,接口将返回 HTTP 400。此外,prompt_cache_options.ttl 字段仅为兼容 OpenAI 格式而保留,传入后会被忽略(与 OpenAI 支持配置 12 小时缓存保留期 不同,Perplexity 底层直接采用各服务商默认缓存生命周期)。调用端点 https://api.perplexity.ai/v1/agent 时,官方 Python 与 TypeScript 示例注明 prompt_cache_options 和 prompt_cache_breakpoint 尚未加入 SDK 类型定义,需通过请求体 extra_body(Python)或 @ts-expect-error(TypeScript)传入。
