提示缓存 - MyTokenGate

1. 使用场景

当多次请求共享同一段较长的前缀（如系统提示、长文档、工具定义、多轮历史），提示缓存可以复用已处理过的这部分内容，从而降低费用、缩短首字延迟。命中缓存的输入 Token 按更低的缓存读取价计费。

典型场景：

• 携带同一份长文档反复问答
• 固定的长系统提示 + 大量工具定义
• 多轮对话中不断增长但前缀稳定的历史

2. 两种缓存方式

MyTokenGate 网关同时支持自动缓存与显式缓存，取决于你使用的接口。

2.1 自动缓存（OpenAI 兼容接口）

通过 /v1/chat/completions 请求时，无需任何额外参数。上游会自动识别重复的长前缀并命中缓存，命中量通过用量字段回传：

"usage": {
  "prompt_tokens": 4200,
  "prompt_tokens_details": {
    "cached_tokens": 4096
  }
}

其中 cached_tokens 即为本次命中缓存的输入 Token 数，按缓存读取价计费。是否命中、命中多少由上游决定，通常要求前缀达到一定长度且内容完全一致。

2.2 显式缓存（Anthropic 兼容接口）

通过 /v1/messages 请求时，可在 system、messages 内容块或工具定义上添加 cache_control 标记缓存断点：

{
  "system": [
    {
      "type": "text",
      "text": "你是一名助手，可访问以下文档：……",
      "cache_control": { "type": "ephemeral" }
    }
  ]
}

命中情况通过用量字段回传：

缓存默认有效期为 5 分钟，每次命中会刷新计时；部分模型支持 1 小时有效期（写入价更高）。

3. 注意事项

• 缓存以前缀为单位：只有从头开始完全一致的内容才可能命中，任何改动都会使其后的内容重新计算。
• 将稳定内容（系统提示、文档、工具定义）放在前面，把变化的用户输入放在后面，命中率最高。
• OpenAI 兼容接口的自动缓存不接受 cache_control，该字段在协议转换时会被忽略。
• 具体价格以模型广场 的缓存读取/写入价为准。

用量字段的完整说明见 Chat Completions 与 Messages。