供应商提示缓存 – ModelRiver Docs

大多数供应商可以缓存提示的开头部分（系统提示、工具、文档、之前的对话轮次），并在后续请求中以低得多的价格计费。ModelRiver 会把你的缓存标记传给供应商，读取供应商报告的缓存 token 数，并按模型的缓存价格为每个请求计价。

这是供应商自己的缓存，与 ModelRiver 的工作流缓存不同：工作流缓存会直接返回已保存的响应，完全不调用供应商。

各供应商的缓存方式

供应商	缓存方式	ModelRiver 如何处理 `cache_control`
Anthropic	由你标记要缓存的内容	在系统、消息、工具结果和工具块上原样发送。`ttl` 为 `"5m"`（默认）或 `"1h"`
Amazon Bedrock（Claude、Nova）	由你标记要缓存的内容	在每个被标记的内容块之后添加缓存点。Claude：系统提示、消息、工具结果和工具，并传递 `"ttl": "1h"`。Nova：仅系统提示和消息，仅五分钟。其他 Bedrock 模型：移除标记
Qwen	自动，或由你标记	消息内容上的标记原样发送；工具上的标记会被移除（Qwen 会忽略它们）
自定义（OpenAI 兼容）	取决于服务端	消息内容上的标记原样发送；工具上的标记会被移除
OpenAI、Azure OpenAI、Google Gemini、xAI、Mistral、DeepSeek、Groq、Kimi、MiniMax、Cohere	自动	移除标记（这些 API 会拒绝或忽略它们），由供应商决定缓存哪些内容

供应商只缓存超过最小长度的提示（通常为 1,024 个 token 或以上），并且只在提示开头完全重复时命中。请把保持不变的部分放在前面，把会变化的部分放在最后。

标记要缓存的内容块

在内容片段（content part）上添加 cache_control。缓存覆盖从开头到该片段（含）的全部内容。只有以片段列表形式发送的内容才能携带标记，纯字符串不行。

Bash

curl https://api.modelriver.com/v1/chat/completions \
  -H "Authorization: Bearer $MODELRIVER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "support-agent",
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "You are a support agent for Acme. <the full 20-page product manual>",
            "cache_control": {"type": "ephemeral"}
          }
        ]
      },
      {"role": "user", "content": "How do I reset my router?"}
    ]
  }'

可以标记：

system、user、assistant 和 tool 消息中的内容片段
工具：在工具或其 function 上添加 cache_control。该标记会缓存到这个工具为止的所有工具定义

添加 "ttl": "1h" 可让 Anthropic 或 Bedrock 的缓存保留一小时，而不是五分钟。一小时缓存写入的价格更高（见计费方式），适合复用间隔超过五分钟的提示。

在智能体循环中，每次请求都标记最新消息的最后一个片段（通常是最新的工具结果）。这样每次请求都会从缓存读取之前的对话，只写入新的一轮。

故障转移把请求转到备用供应商时，标记会保留在请求中，备用供应商按上表的方式使用或移除它们。

响应中的缓存 token

在所有供应商上，prompt_tokens 始终是全部输入（包含缓存 token），completion_tokens 包含推理 token。（Anthropic 和 Bedrock 报告的输入不含缓存部分；ModelRiver 会把它加回去，让各供应商的数字含义一致。）

在 /v1/chat/completions 上，usage 对象（流式响应中也在最后一个分块里）以 OpenAI 格式显示明细。自定义（OpenAI 兼容）服务端的流式响应只有在服务端默认发送用量时才会报告用量：

JSON

1"usage": {
2  "prompt_tokens": 5050,
3  "completion_tokens": 200,
4  "total_tokens": 5250,
5  "prompt_tokens_details": { "cached_tokens": 4000, "cache_write_tokens": 1000 },
6  "completion_tokens_details": { "reasoning_tokens": 0 }
7}

在 /v1/ai 上，meta.usage 以 cache_read_tokens、cache_write_tokens 和 reasoning_tokens 提供相同的计数，另有 cache_write_1h_tokens：缓存写入中保留一小时的部分（Anthropic、Bedrock）。

字段	含义
`cached_tokens` / `cache_read_tokens`	从供应商缓存读取的输入
`cache_write_tokens`	本次请求写入缓存的输入
`reasoning_tokens`	模型用于思考（推理）的输出（供应商单独报告时）。Bedrock 不单独报告，其推理仍计入 `completion_tokens`

控制台中每条请求日志和每月的用量 API 也会显示这些计数。

计费方式

ModelRiver 按模型的价格估算每个请求的费用：

缓存读取按模型的缓存读取价格计算，通常为输入价格的十分之一到一半
缓存写入按模型的缓存写入价格计算：Anthropic、Bedrock Claude、Qwen 以及 OpenAI GPT-5.6 及之后的模型为输入价格的 1.25 倍；不收取写入费用的供应商按输入价格计算
一小时缓存写入（Anthropic、Bedrock）按输入价格的两倍计算
其余部分按输入和输出价格计算

没有公布缓存价格的模型按输入价格计算：对缓存读取而言估算会偏高；对写入额外收费的供应商而言估算会偏低。完整公式见成本分析。