Context Cache

上下文缓存（Context Cache）

上下文缓存通过复用重复的 prompt 前缀，大幅降低输入成本（最高节省 90%）。NexusFlow 同时支持显式缓存和隐式缓存，兼容 OpenAI 和 Anthropic 两种协议。

两种缓存模式

特性	显式缓存	隐式缓存
激活方式	在 content 中添加 cache_control 标记	自动生效，无需任何参数
命中保证	确定性命中（前缀匹配即命中）	概率性命中（系统自动决定）
最低 Token 数	1024	~256（因模型而异）
缓存有效期	5 分钟（命中后刷新）	不确定（系统自动清理）
创建计费	125% 输入价	标准输入价
命中计费	10% 输入价	~20% 输入价（10%~40%）
适用协议	OpenAI Chat / Anthropic Messages	所有协议

显式缓存用法

在 messages[].content[] 的文本块中添加 "cache_control": {"type": "ephemeral"}，即可标记该内容块为缓存点。

curl -X POST https://nexusflow.hk/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen3.5-flash",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "<超过1024 tokens的长文本...>",
          "cache_control": {"type": "ephemeral"}
        }
      ]
    },
    {"role": "user", "content": "基于上文回答问题"}
  ],
  "max_tokens": 200
}'

约束：

每个请求最多 4 个 cache_control 标记
标记内容必须至少 1024 tokens
缓存在首次请求完成后创建，第二次请求开始命中
Function Calling 的 tools 定义不能直接加标记，需在最后一个 content 块上标记
tools 数组的顺序和字段必须完全一致才能命中

隐式缓存

无需任何参数变更，系统会自动检测并缓存 messages 中的公共前缀。优化建议：

将静态/重复内容（system prompt、长文档）放在 messages 最前面
动态内容（用户最新问题）放在最后
多轮对话保持 system prompt 不变

请求与返回示例

缓存信息会随正常 Chat Completions 响应一起返回。业务侧仍然从 choices[0].message.content 读取模型结果，从 usage.prompt_tokens_details 读取缓存创建和命中情况。

显式缓存：请求输入

curl -X POST https://nexusflow.hk/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen3.5-flash",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "<稳定公共前缀，至少 1024 tokens，例如代码库、产品手册、长文档>",
          "cache_control": {"type": "ephemeral"}
        }
      ]
    },
    {
      "role": "user",
      "content": "基于上面的文档，回答第一个问题"
    }
  ],
  "temperature": 0,
  "max_tokens": 200
}'

显式缓存：首次返回（创建缓存）

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "这里是模型正常返回的答案"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18628,
    "completion_tokens": 344,
    "total_tokens": 18972,
    "prompt_tokens_details": {
      "text_tokens": 18628,
      "cache_creation_input_tokens": 18613,
      "cache_type": "ephemeral",
      "cached_tokens": 0
    }
  }
}

显式缓存：第二次返回（命中缓存）

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "这里是第二次请求的答案"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18628,
    "completion_tokens": 445,
    "total_tokens": 19073,
    "prompt_tokens_details": {
      "text_tokens": 18628,
      "cache_creation_input_tokens": 0,
      "cache_type": "ephemeral",
      "cached_tokens": 18613
    }
  }
}

隐式缓存：请求输入

curl -X POST https://nexusflow.hk/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen3.7-max",
  "messages": [
    {
      "role": "system",
      "content": "<稳定公共前缀，例如长期不变的知识库、产品说明、代码上下文>"
    },
    {
      "role": "user",
      "content": "基于上面的内容，回答新的问题"
    }
  ],
  "temperature": 0,
  "max_tokens": 200
}'

隐式缓存：可能的命中返回

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "这里是模型正常返回的答案"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 15365,
    "completion_tokens": 1,
    "total_tokens": 15366,
    "prompt_tokens_details": {
      "cached_tokens": 15232
    }
  }
}

隐式缓存没有 cache_control 标记，也不会返回 cache_type。如果本次没有命中，prompt_tokens_details.cached_tokens 可能为 0 或不存在；命中与否由上游自动策略决定。

如何确认缓存命中

API 响应的 usage.prompt_tokens_details 中会包含缓存信息：

"usage": {
  "prompt_tokens": 1584,
  "completion_tokens": 20,
  "total_tokens": 1604,
  "prompt_tokens_details": {
    "cached_tokens": 1568,           // 命中缓存的 token 数
    "cache_creation_input_tokens": 0  // 本次创建缓存的 token 数
  }
}

在控制台的使用记录页面，命中缓存的调用会显示蓝色「缓存N」标签。

显式缓存 — 支持模型

模型	供应商	最低 Token
`qwen3.7-max`	通义千问	1024
`qwen3.7-plus`	通义千问	1024
`qwen3.6-max-preview`	通义千问	1024
`qwen3.6-plus`	通义千问	1024
`qwen3.6-flash`	通义千问	1024
`qwen3.5-plus`	通义千问	1024
`qwen3.5-flash`	通义千问	1024
`qwen3-coder-plus`	通义千问	1024
`qwen3-coder-flash`	通义千问	1024
`qwen3-vl-plus`	通义千问	1024
`qwen3-vl-flash`	通义千问	1024
`deepseek-v4-pro`	DeepSeek	1024
`deepseek-v4-flash`	DeepSeek	1024
`deepseek-v3.2`	DeepSeek	1024
`glm-5.1`	智谱AI	1024
`kimi-k2.6`	月之暗面	1024
`kimi-k2.5`	月之暗面	1024
`MiniMax-M2.5`	MiniMax	1024

隐式缓存 — 支持模型

以下模型自动启用隐式缓存，无需额外配置。命中后输入 token 自动享受折扣。

模型	供应商	预估最低 Token
`qwen3.7-max`	通义千问	~1000
`qwen3.7-plus`	通义千问	~256
`qwen3.6-max-preview`	通义千问	~256
`qwen3.6-plus`	通义千问	~256
`qwen3.6-flash`	通义千问	~256
`qwen3.5-plus`	通义千问	~256
`qwen3.5-flash`	通义千问	~256
`qwen3-coder-plus`	通义千问	~256
`qwen3-coder-flash`	通义千问	~256
`qwen3-vl-plus`	通义千问	~256
`qwen3-vl-flash`	通义千问	~256
`qwen-plus`	通义千问	~256
`qwen-turbo`	通义千问	~256
`qwen-long`	通义千问	~256
`deepseek-v4-pro`	DeepSeek	~256
`deepseek-v4-flash`	DeepSeek	~256
`deepseek-v3.2`	DeepSeek	~256
`deepseek-r1`	DeepSeek	~256
`glm-5.1`	智谱AI	~512
`glm-5`	智谱AI	~512
`kimi-k2.6`	月之暗面	~256
`kimi-k2.5`	月之暗面	~256
`MiniMax-M2.5`	MiniMax	~256
`MiniMax-M2.1`	MiniMax	~256

计费说明

场景	计费倍率	说明
显式缓存 — 创建	1.25x	首次写入缓存，按输入价的 125% 计费
显式缓存 — 命中	0.1x	命中后仅按输入价的 10% 计费
隐式缓存 — 命中	~0.2x	命中后约按输入价的 20% 计费（10%~40% 因模型而异）
未命中	1.0x	标准输入价