跳到主要内容

上下文缓存（Responses API）

概述​

上下文缓存（后简称缓存）旨在为您优化调用模型服务体验。通过缓存常用上下文信息，减少每次请求时重复处理加载开销，达到降低成本（命中缓存的输入有折扣优惠）目标。适合多轮对话、工具调用、角色扮演等需多次传入相同内容的场景。

设置 "caching": {"type": "enabled"}，可以将本轮输入输出（不包括思维链内容）信息写入缓存。在新一轮的对话中传入请求 ID，可将上轮缓存的输入输出信息传入新一轮对话。缓存输入的信息的单价远低于未缓存的输入的信息的单价，您可以通过缓存输入，来大幅降低成本。

相关文档
  • API 结构及参数请参见 Responses API
  • 支持模型请有：
    • Doubao/Doubao-seed-1.6
    • Doubao/Doubao-seed-1.6-thinking
    • Doubao/Doubao-seed-1.6-flash

开通服务​

  • 开发环境：直接创建 API Key 即可使用上下文缓存功能。
  • 生产环境：需要提交工单开通上下文缓存功能。
  • 使用前请确保您已获取 API Key。参见快速开始获取 API Key。

快速开始​

以下示例展示如何使用缓存功能进行长文本分析：

bash
# 首次请求：创建缓存
curl --location '<ai-api-base-url>/llm/v1/responses' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "Doubao/Doubao-seed-1.6",
    "input": [
      {
        "role": "system",
        "content": "你是融云技术支持专家，请根据下面的融云 IM 产品文档内容回答用户问题。\n<融云 IM SDK 完整技术文档>\n回复 OK，并等待用户的提问"
      }
    ],
    "caching": {"type": "enabled"},
    "thinking": {"type": "disabled"}
  }'

# 后续请求：使用缓存（替换 resp_123456 为实际响应 ID）
curl --location '<ai-api-base-url>/llm/v1/responses' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "Doubao/Doubao-seed-1.6",
    "previous_response_id": "resp_123456",
    "input": [
      {"role": "user", "content": "融云 IM SDK 如何实现消息已读回执？"}
    ],
    "caching": {"type": "enabled"},
    "thinking": {"type": "disabled"}
  }'

返回预览​

首次请求：

JSON
{
  "output": [{"content": [{"text": "OK，我已准备好根据融云 IM SDK 文档回答您的问题。"}]}],
  "usage": {
    "input_tokens": 108553,
    "input_tokens_details": {"cached_tokens": 0},
    "output_tokens": 15,
    "output_tokens_details": {"reasoning_tokens": 0},
    "total_tokens": 108568
  }
}

第二次请求：

JSON
{
  "output": [{"content": [{"text": "融云 IM SDK 实现消息已读回执的方式如下：\n\n1. **发送已读回执**：接收方收到消息后，调用 `sendReadReceiptMessage()` 方法向发送方发送已读回执。\n\n2. **监听已读回执**：发送方通过注册 `onReceiptReceived()` 回调监听已读回执消息。\n\n3. **群聊已读回执**：群聊场景下可以使用 `sendGroupReadReceiptRequest()` 请求群消息已读回执，通过 `onGroupReadReceiptResponse()` 获取已读成员列表。\n\n4. **会话级已读**：调用 `clearMessagesUnreadStatus()` 可以清除整个会话的未读状态。\n\n具体实现请参考对应平台 SDK 的 API 文档。"}]}],
  "usage": {
    "input_tokens": 108585,
    "input_tokens_details": {"cached_tokens": 108568},
    "output_tokens": 168,
    "output_tokens_details": {"reasoning_tokens": 0},
    "total_tokens": 108753
  }
}
成本优势

在如上长文本场景下，第 2 次请求中 "cached_tokens": 108568，以 Doubao/Doubao-seed-1.6 模型为例，相比未使用缓存，带缓存的请求费用下降 86%。在超长输入，如超长文本或超长历史对话场景下，成本下降将更加明显。

前缀缓存​

您可以预先存储并缓存角色、背景等初始化信息，后续调用模型时无需重复发送此信息给模型，而将缓存的处理后的初始化信息作为缓存输入，减少重复计算和存储开销，降低使用成本，尤其适用于具有重复提示或标准化开头文本的应用。

使用要求

首轮输入时，需设置 "store": true（默认 true）、"caching": {"type": "enabled"}，以创建前缀缓存。后续轮次即可通过 previous_response_id 引用缓存信息。

示例：融云 API 技术助手​

bash
# 创建前缀缓存
curl --location '<ai-api-base-url>/llm/v1/responses' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "Doubao/Doubao-seed-1.6",
    "input": [
      {
        "role": "system",
        "content": "你是融云 API 技术支持助手。你精通融云的各类产品和 API 接口，包括 IM 即时通讯、RTC 音视频通话、Push 推送服务等。请根据用户的问题，提供专业、准确的技术指导和解决方案。\n\n你需要：\n1. 理解用户的技术需求和使用场景\n2. 提供清晰的 API 调用示例和参数说明\n3. 针对常见问题给出最佳实践建议\n4. 帮助用户排查和解决集成问题"
      }
    ],
    "caching": {"type": "enabled"},
    "thinking": {"type": "disabled"}
  }'

# 使用前缀缓存
curl --location '<ai-api-base-url>/llm/v1/responses' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "Doubao/Doubao-seed-1.6",
    "previous_response_id": "resp_123456",
    "input": [{"role": "user", "content": "如何调用融云服务端 API 发送单聊消息？"}],
    "thinking": {"type": "disabled"}
  }'

Session 缓存​

Responses API 支持自动储存历史上下文对话并保持缓存，通过调用 previous_response_id 在多轮对话等场景中使用缓存输入并降低推理成本。

示例：多轮对话​

bash
# 第一轮对话
curl --location '<ai-api-base-url>/llm/v1/responses' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "Doubao/Doubao-seed-1.6",
    "input": [
      {"role": "system", "content": "你是融云技术支持专家，帮助开发者解决融云产品的集成和使用问题。"},
      {"role": "user", "content": "我想在 Android 应用中集成融云 IM，需要做哪些准备工作？"}
    ],
    "caching": {"type": "enabled"},
    "thinking": {"type": "disabled"}
  }'

# 第二轮对话
curl --location '<ai-api-base-url>/llm/v1/responses' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "Doubao/Doubao-seed-1.6",
    "previous_response_id": "resp_123456",
    "input": [{"role": "user", "content": "那 iOS 平台呢？有什么不同吗？"}],
    "caching": {"type": "enabled"},
    "thinking": {"type": "disabled"}
  }'

控制存储/缓存生命周期​

支持通过 expire_at 字段指定上下文存储（store）及上下文缓存（caching）过期时刻。当前最大可存储时间为 72 小时，即当前 UTC Unix 时间戳 + 259200。

示例​

bash
curl --location '<ai-api-base-url>/llm/v1/responses' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data "{
    \"model\": \"Doubao/Doubao-seed-1.6\",
    \"input\": [{\"role\": \"system\", \"content\": \"你是融云 AI API 技术助手，为开发者提供融云服务的技术支持。\"}],
    \"caching\": {\"type\": \"enabled\"},
    \"thinking\": {\"type\": \"disabled\"},
    \"expire_at\": $(($(date +%s) + 3600))
  }"

删除缓存​

Responses API 支持根据 ID 来删除缓存，与删除历史对话一致，便于您根据业务自主控制缓存信息量，如删除不必要的缓存信息，减少冗余输入，降低成本。

bash
curl --location --request DELETE '<ai-api-base-url>/llm/v1/responses/resp_123456' \
  --header 'Authorization: Bearer <token>'
级联影响

需注意，删除某轮缓存后，其后续轮次缓存的信息在下次请求时将重新计算和存储。例如，在第 5 轮请求后调用接口删除第 3 轮对话信息，第 6 轮请求时，第 4、5 轮信息将重新计算并缓存，此时其信息将作为输入，而非缓存输入进行计费。

使用说明​

caching 参数​

  1. 前置轮次要求：前一轮对话的请求开启了缓存写入，当前轮次对话才能写入缓存。以此类推，当某轮次请求需写入缓存，则需保证所有前置轮次请求写入缓存状态开启，即前置所有轮次均有 "caching": {"type": "enabled"}。

    举例：当希望第 5 轮请求能写入缓存信息，则需要 1~4 轮均保持缓存写入开启。当其中一轮请求关闭缓存写入，则后续轮次对话请求均无法写入缓存。

  2. 格式限制：前面轮次只要存在 "caching": {"type": "enabled"}，则不支持使用 json_schema，但支持使用 json_object。

  3. 有效期：缓存的有效期可以通过 expire_at 字段自定义，最长支持 3 天。

创建前缀缓存场景限制​

  1. 不支持与 previous_response_id 同时使用
  2. Input tokens 需要大于等于 1024 tokens，否则会报错
  3. stream 参数不能设置为 true
  4. 深度思考能力的模型返回的思维链内容不会被缓存

store 参数​

若想写入缓存，需开启存储功能，即 store 字段为 true 或保持默认（默认为 true）。

instructions 参数​

若想写入缓存，instructions 字段应为空。若在本轮请求里设置了 instructions，该轮对话不能调用已有缓存，也无法将本轮信息写入缓存。

thinking 参数​

请求中 thinking 字段的赋值应该与前一轮保持一致才可使用缓存/写入缓存。

示例说明

以 Doubao/Doubao-seed-1.6 模型为例：

  • 当第 1 轮设定 "thinking": {"type": "auto"}，则后续如需使用或者启用缓存，均需一样赋值
  • 当第 1 轮未设置 thinking 字段，即不赋值，后续请求如需写入缓存或者调用已有缓存，也需不设置 thinking 字段

tools 参数​

  1. 仅在首轮请求时可以设置 tools 字段，后续所有对话将默认携带 tools 字段信息的缓存输入
  2. 不支持在后续轮次对话请求中设置 tools 字段，会冲突并报错处理
  3. 若首轮对话信息被删除，则后续所有轮次对话都不携带 tools 字段信息的缓存输入，也无法配置 tools 字段

成本优化建议​

  1. 合理设置过期时间：根据实际业务需求设置 expire_at，避免不必要的长期存储费用
  2. 及时删除无用对话：对于已结束的会话，及时调用删除接口清理
  3. 优先使用前缀缓存：对于固定的系统提示词，使用前缀缓存可以最大化成本优势
  4. 避免频繁删除中间轮次：删除中间轮次会导致后续轮次需要重新计算，增加成本

相关文档​

最后于 更新