提示缓存

概述

Ling.AI 会透传上游支持的提示缓存能力，并记录缓存相关 token。缓存命中配置分为显式和隐式两档价格；Session 是触发缓存的机制，不是第三档价格。当前双价候选版本仍有 Session 能力识别和异步账单证据落库的验收阻断，不能视为所有模型均已完成双价计费验收。

缓存类型

1. 显式缓存

请求方式取决于模型支持的协议。例如，部分模型可在消息内容块中设置 cache_control: {"type":"ephemeral"}。网关沿用既有协议转换；只有最终发往上游的请求保留有效显式缓存标记，或上游提供可靠的显式命中证据，并且实际返回缓存命中 token，才按显式命中价计费。客户端传入同名字段本身不代表已经生效。

2. 隐式缓存

适用于支持自动前缀缓存的模型。该模式无需额外配置，是否命中缓存由上游决定；命中后，网关会从返回结果中提取 cached_tokens 并写入 prompt_cached_tokens。

3. Session 缓存

适用于 /v1/responses。当最终请求向上游传递 x-dashscope-session-cache: enable 时启用 Session；如果显式传入 x-dashscope-session-cache: disable，则关闭 Session 缓存并回退到上游默认行为（若模型支持，通常仍可能发生隐式缓存）。按官方规则，支持显式缓存的模型应使用显式命中价，仅支持隐式缓存的模型应使用隐式命中价；是否命中仍以实际用量为准。

当前候选版本尚未接入完整、权威的实际路由模型 Session 能力依据。已有路由策略只能提供有限推断；能力未知且没有其它可靠显式证据时，现有兼容路径仍使用隐式价，这可能使支持显式的 Session 模型采用错误档位。该覆盖缺口尚未解决，不能据此认定所有 Session 模型均已正确选价。最终有效显式标记或可靠响应证据加真实命中仍可选择显式价；响应缺少 cache_type 本身不暂停普通结算。

配置方式

显式缓存与 Session 缓存都可以直接从公开 API 触发；是否真正创建或命中缓存，仍取决于上游模型是否支持以及提示词长度是否达到上游要求。

curl https://api.lingyuncx.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.5-plus",
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "很长的稳定前缀……",
            "cache_control": {"type": "ephemeral"}
          }
        ]
      },
      {"role": "user", "content": "请概括以上内容"}
    ]
  }'

curl https://api.lingyuncx.com/v1/responses \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "x-dashscope-session-cache: enable" \
  -d '{
    "model": "qwen3.5-plus",
    "input": "请基于上一次响应继续回答"
  }'

缓存字段

缓存计费

固定价与每个价格阶梯分别配置 explicit_cache_hit_price（显式命中）和 implicit_cache_hit_price（隐式命中）。只填写一档时，保存为两档同值；填写两档时保留各自的价格。0 是有效的免费价格；两档均留空时保存为两个 NULL，命中按对应规则或阶梯的基础文本输入价计费。编辑时未提交字段表示保留原值，提交空值表示主动清空。

旧单一命中价升级为两档同值，旧阶梯价同样保留。升级后主动清空两档，不会被旧字段恢复。只有 cached_tokens 时，该字段只证明命中数量：最终出站请求存在有效显式标记则使用显式价；无显式依据的普通命中使用隐式价。可靠响应中的 cache_type=ephemeral 也支持显式分类。响应缺少 cache_type 本身不会阻断正常结算；真正互相矛盾的证据仍触发既有保护。

实际费用计算公式：

本次命中单价 = 显式命中价 或 隐式命中价
（对应档位为空时使用基础文本输入价）

基础 Token 费用 = [
    标准输入 Token × input_price
  + 缓存写入 Token × cache_creation_price
  + 缓存命中 Token × 本次命中单价
  + 输出 Token × output_price
] / 1,000,000

最终账单仍沿用已有折扣、免费额度和其他计费分项。

应用场景

• 长文本多问：反复针对同一份文档、代码仓库或知识库提问。
• 多轮会话：使用 /v1/responses 并结合 Session 缓存降低连续对话成本。
• 账单核对：根据 prompt_cached_tokens、cache_write_tokens、cache_hit_type 校验结算是否符合上游规则。

缓存统计

有真实命中时，后台使用日志和客户用量明细会展示本次显式/隐式类型与实际单价；没有命中时不展示命中价，历史无可靠类型显示未知。历史账单不按现有配置回写。在控制台用量追踪页可查看缓存 token、缓存命中率等聚合数据；如需判断某次请求是否享受缓存价格，建议同时核对返回结果中的 usage 与控制台日志里的 cache_hit_type、prompt_cached_tokens、cache_write_tokens。