提示缓存

概述

Ling.AI 会透传上游支持的提示缓存能力，并记录缓存相关 token 到日志与结算结果。当前网关已支持三类场景：显式缓存、隐式缓存、Session 缓存。

缓存类型

1. 显式缓存

适用于 /v1/chat/completions。当请求体中的消息内容带有 cache_control: {"type":"ephemeral"} 时，网关会原样转发给上游；若上游返回缓存写入或缓存命中 token，系统会记录并参与计费。

2. 隐式缓存

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

3. Session 缓存

适用于 /v1/responses。当请求头中包含 x-dashscope-session-cache: enable 时，Ling.AI 会把该 Header 透传到上游；如果显式传入 x-dashscope-session-cache: disable，则关闭 Session 缓存并回退到上游默认行为（若模型支持，通常仍可能发生隐式缓存）。

配置方式

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

curl https://api.vip.lingapi.ai/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.vip.lingapi.ai/v1/responses \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "x-dashscope-session-cache: enable" \
  -d '{
    "model": "qwen3.5-plus",
    "input": "请基于上一次响应继续回答"
  }'

缓存字段

缓存计费

缓存 Token 的计费与标准输入 Token 不同，具体价格取决于模型对应的 billing_rules 配置：

实际费用计算公式：

缓存请求总费用 =
  (标准输入 Token × input_price)
  + (缓存写入 Token × cache_creation_price)
  + (缓存命中 Token × cache_hit_price)
  + (输出 Token × output_price)

应用场景

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

缓存统计

在控制台用量追踪页可查看缓存 token、缓存命中率等聚合数据；如需判断某次请求是否享受缓存价格，建议同时核对返回结果中的 usage 与控制台日志里的 cache_mode、prompt_cached_tokens、cache_write_tokens。