AiHubMix Documentation Hub

提示词缓存（Prompt Caching）是一种用于降低模型推理成本的重要机制。通过缓存已经处理过的提示内容，在后续请求中重复利用，从而减少重复计算、降低费用并提升响应效率。

原理

当您发送启用了提示缓存的请求时，系统会检查提示前缀是否已从最近的查询中缓存。如果找到，则使用缓存，减少处理时间和成本；否则，处理完整提示并在响应开始后缓存前缀。这对以下场景特别有用：

包含大量示例的提示
大量上下文或背景信息
具有一致指令的重复任务
长时间的多轮对话

核心机制

不同模型供应商对缓存的支持方式不同：

自动缓存

自动缓存无需额外配置，系统自动识别并缓存可复用内容，适用于 OpenAI、DeepSeek 等模型。

OpenAI

最低提示长度：1024 tokens，前缀逐字一致时自动命中
GPT-5.6 之前的模型：缓存写入不另计费，缓存读取按对应模型的缓存读取价计费
GPT-5.6 及之后（官方口径 “GPT-5.6 models and later model families”，当前为 gpt-5.6-sol / terra / luna）：缓存写入按 1.25x 输入价计费，读取按 0.1x 计费；新增 prompt_cache_key 与显式缓存断点参数
用法、计费与命中排查见 GPT 提示词缓存

Gemini

默认启用隐式上下文缓存，缓存自动生效，无需手动配置。
缓存仅在内容、模型、参数完全一致时生效；任何字段不同都会视为新请求，不命中缓存。
缓存有效期由开发者设定，也可以不设置。如果未指定，默认为 1 小时。无最小或最大时长限制，费用取决于缓存 token 数与缓存时间。

DeepSeek / Grok / Moonshot / Groq

价格：写缓存免费或同价，读缓存低于原价

Claude 模型显式缓存

需要通过 cache_control 启用：请求体顶层字段自动设置断点（随对话前移），或内容块级断点精细控制缓存位置
全部活跃 Claude 模型支持，缓存写入 5 分钟档 1.25x、1 小时档 2x、读取 0.1x，计价比例全系统一
适用于 Anthropic Claude 模型

Claude 按模型设定最小可缓存 Token 门槛（512 / 1,024 / 2,048 / 4,096 不等，该门槛并非随版本升级而提高）：例如 Claude Opus 4.8 为 1,024、Claude Opus 4.7 为 2,048、Claude Opus 4.6 / 4.5 与 Claude Haiku 4.5 为 4,096、Claude Fable 5 为 512。低于门槛的前缀即使显式设置 cache_control 也不会被缓存，且不会返回错误——响应中 cache_creation_input_tokens 与 cache_read_input_tokens 同时为 0 即为此情况。完整分档与排查见 Claude 提示词缓存。

OpenAI 兼容接口

在 system、user（含图片）、tools 中均可通过 cache_control 字段设置缓存断点，以下示例仅展示关键结构： System 消息缓存（默认 5 分钟 TTL）：

{
  "model": "claude-opus-4-5",
  "messages": [
    {
      "role": "system",
      "content": [
        {"type": "text", "text": "You are an AI assistant"},
        {
          "type": "text",
          "text": "(long context)",
          "cache_control": {"type": "ephemeral"}
        }
      ]
    },
    {
      "role": "user",
      "content": [{"type": "text", "text": "Hello"}]
    }
  ]
}

User 消息缓存（1 小时 TTL）：

{
  "model": "claude-opus-4-5",
  "messages": [
    {
      "role": "system",
      "content": [{"type": "text", "text": "You are an AI assistant"}]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "(long context)",
          "cache_control": {"type": "ephemeral", "ttl": "1h"}
        },
        {"type": "text", "text": "Hello"}
      ]
    }
  ]
}

图片消息缓存：

{
  "role": "user",
  "content": [
    {
      "type": "image_url",
      "image_url": {"detail": "auto", "url": "data:image/jpeg;base64,/9j/4AAQ..."},
      "cache_control": {"type": "ephemeral"}
    },
    {"type": "text", "text": "What's this？"}
  ]
}

Tool 定义缓存： cache_control 放在 tool 对象的顶层（与 type、function 同级）：

{
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    },
    "cache_control": {"type": "ephemeral", "ttl": "1h"}
  }]
}

Anthropic 兼容接口

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
      },
      {
        "type": "text",
        "text": "<the entire contents of Pride and Prejudice>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

# 使用相同的输入再次调用模型，直到缓存检查点
curl https://aihubmix.com/v1/messages # rest of input

import anthropic

client = Anthropic(
  api_key="<AIHUBMIX_API_KEY>",  
  base_url="https://aihubmix.com"
)

params = {
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
        },
        {
            "type": "text",
            "text": "<the entire contents of 'Pride and Prejudice'>",
            "cache_control": {"type": "ephemeral"},
        },
    ],
    "messages": [
        {
            "role": "user",
            "content": "Analyze the major themes in 'Pride and Prejudice'.",
        }
    ],
}
response = client.messages.create(**params)
print(response.usage.model_dump_json())

# 使用相同的输入再次调用模型，直到缓存检查点
response = client.messages.create(**params)
print(response.usage.model_dump_json())

缓存时间

默认： 5 分钟
可选：1 小时（“ttl”: “1h”）

需要了解更多信息请查看：Claude 提示词缓存

使用建议

保持前缀稳定

将固定内容放在 Prompt 前部，推荐结构：

[系统设定 / 长文本 / RAG数据] 
[用户问题（变化部分）]

缓存大文本

优先缓存一下内容：

RAG 数据
长文本
CSV / JSON 数据
角色设定

控制 TTL

短会话 → 5 分钟
长会话 → 1 小时（更省成本）

减少缓存写入

避免频繁变化的内容进入缓存，不要缓存时间戳、用户输入变量、高频变化数据等内容。

更新时间：2026-07-10

开始使用

网关能力

模型能力

协议参考

平台管理

隐私和条款

提示词缓存

原理

核心机制

自动缓存

OpenAI

Gemini

DeepSeek / Grok / Moonshot / Groq

Claude 模型显式缓存

OpenAI 兼容接口

Anthropic 兼容接口

缓存时间

使用建议

避免频繁变化的内容进入缓存，不要缓存时间戳、用户输入变量、高频变化数据等内容。

​原理

​核心机制

​自动缓存

​OpenAI

​Gemini

​DeepSeek / Grok / Moonshot / Groq

​Claude 模型显式缓存

​OpenAI 兼容接口

​Anthropic 兼容接口

​缓存时间

​使用建议

​避免频繁变化的内容进入缓存，不要缓存时间戳、用户输入变量、高频变化数据等内容。

原理

核心机制

自动缓存

OpenAI

Gemini

DeepSeek / Grok / Moonshot / Groq

Claude 模型显式缓存

OpenAI 兼容接口

Anthropic 兼容接口

缓存时间

使用建议

避免频繁变化的内容进入缓存，不要缓存时间戳、用户输入变量、高频变化数据等内容。