Responses API 缓存键怎么配置和验收

先拆分提示内容

先把写作请求分成两部分：稳定前缀负责角色、格式、事实边界、审核规则和输出约束；动态内容负责主题、资料、受众、批次和本次修改要求。稳定部分应尽量保持原文、顺序和结构一致，动态部分不要混入前缀，否则相同任务也难以复用。

资料包确认 Responses API 请求支持 prompt_cache_key，它用于缓存相似请求，并替代 user 字段承担缓存优化用途。不要把文章标题、时间戳或随机数拼进这个键。

准备缓存配置

1. 确定一类可重复任务，例如“根据固定规则生成教程初稿”，不要把初稿、改稿和审核共用一个键。
2. 给稳定前缀建立版本号，例如 writing_rules_v3。规则发生实质变化时递增版本。
3. 为动态任务单独生成任务标识，例如 article-20260927-001，它用于本地追踪，不要替代缓存键。
4. 确认所用模型和当前 SDK 版本支持需要的缓存参数，并以实际接口返回为准。

提交请求的步骤

1. 把角色、写作流程、输出格式和禁止事项整理到 instructions，并固定段落顺序。
2. 把主题、资料摘要和本次交付要求放入 input，每次只替换动态部分。
3. 在创建响应时传入稳定的 prompt_cache_key，同时在 metadata 中保存文章、批次和任务类型等内部标识。
4. 需要显式控制缓存断点时，再查看当前模型对 prompt_cache_options 的支持情况。资料包确认该配置可使用 mode 和 ttl，默认 TTL 为 30 分钟；不要把未确认的模型范围写死在业务逻辑里。
5. 提交请求后保存响应 ID、请求时间、缓存键版本、模型、输入摘要和返回状态。

response = client.responses.create(
    model=model_name,
    instructions=stable_rules,
    input=dynamic_task,
    prompt_cache_key="writing_rules_v3",
    metadata={
        "task_id": task_id,
        "article_id": article_id,
        "batch_id": batch_id,
        "task_type": "draft"
    }
)

示例只展示字段组织方式。模型名称、可用参数和返回结构应以当前环境的官方说明及实际响应为准。

建立任务记录表

建议每次请求至少记录以下字段：任务标识、文章标识、缓存键、缓存键版本、模型、固定前缀摘要、动态输入摘要、请求开始和结束时间、响应 ID、返回状态、返回内容位置、接口返回的使用信息，以及人工验收结论。原始资料不必全部写入日志，可保存受控存储位置和内容摘要。

推荐的单条记录格式如下：

• task_id：本地唯一任务标识
• prompt_cache_key：本次提交使用的稳定键
• prefix_version：稳定规则版本
• input_digest：动态输入摘要
• response_id：接口返回的响应标识
• status：请求状态
• usage：响应中实际返回的使用信息，缺失时记为未提供
• review_result：格式、事实边界和可发布性结论

如果团队还需要统一保存响应和文章版本，可参考Responses API 写作任务的 metadata 追踪方法，但仍要把缓存键和任务标识分成两个字段。

用重复任务检查效果

1. 准备至少两组动态内容相近、稳定规则完全相同的写作任务。
2. 先发送一条基准请求，再发送重复任务，确保两次使用相同模型、相同稳定前缀和相同请求策略。
3. 记录每次请求的总耗时、接口返回的使用信息、输出长度、格式通过情况和人工修改量。
4. 再做一组对照请求：只改变缓存键或拆分方式，其他条件保持一致。
5. 比较重复任务与对照任务，不要仅凭一次请求判断命中；将结果按任务批次汇总。

验收重点是趋势而不是预设收益。若重复任务的输入处理表现、延迟或成本指标没有改善，先检查前缀是否真的一致，再检查键版本和请求参数是否被中间层改写。

常见故障与修正

• 重复任务仍没有明显改善：稳定前缀中混入时间、随机编号或动态资料；修正为固定规则与动态输入分离，并重新计算前缀摘要。
• 不同任务输出互相污染：多个任务类型共用了同一个键；按写作、改稿、审核等职责拆分键，或为规则版本建立独立键。
• 规则更新后旧行为仍出现：缓存键没有随规则版本变化；递增版本号，并在任务记录中保存新旧版本。
• 配置参数被拒绝：当前模型、SDK 或接口版本不支持该参数；先删除未确认的高级选项，再依据当前文档逐项恢复。
• 无法判断是否命中：只保存了正文，没有保存响应使用信息和耗时；补齐原始响应摘要、计时字段和对照批次。
• 任务无法追溯：把缓存键当成文章编号使用；恢复独立的 task_id、article_id 和 prompt_cache_key 字段。

发布前验收清单

• 稳定规则、动态资料和任务标识已经分开。
• prompt_cache_key 具备明确用途，未包含随机值、用户隐私或文章正文。
• 规则版本变化时会更新键或版本字段。
• 请求日志保存了模型、参数、响应 ID、状态和实际返回的使用信息。
• 至少完成一组重复任务和一组对照任务。
• 已比较延迟、成本相关指标、输出格式和人工修改量。
• 缓存未改善时，能够根据前缀摘要和请求日志定位原因。
• 最终文章通过事实边界、格式完整性和人工发布审核。