进阶 opencode.ai 2026-11-11 16:13:22 · 15 阅读

第26章 OpenCode 中的缓存预热机制

Warming(缓存预热)

WarmingSession(预热会话)会周期性地向模型发送请求,以维护服务端的提示词缓存或短暂状态,防止在你暂停输入期间缓存过期。此功能默认处于关闭状态。

你可以在任意 OpenCode 配置文件中启用预热:

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "warming": true,
}

启用后,OpenCode 会在提示词缓存即将过期前自动预热最近活跃的会话。触发时机为模型 cache.ttl 达到 90%,或者当模型未设置缓存时,每 4 分钟预热一次。该过程会持续进行,直到距离最后一次非预热请求的时间超过 30 分钟为止。

若需自定义预热提示词、空闲间隔或活跃窗口,请使用对象形式配置:

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "warming": {
    "prompt": "请勿执行任何操作。仅回复:OK",
    "interval": "5 minutes",
    "duration": "1 hour",
  },
}

各字段默认值及用途如下:

  • prompt(默认:保活指令):附加在每次预热请求中的临时用户消息。默认提示词要求模型不执行任何任务、不使用工具,并回复 "OK"。
  • interval(默认:"auto"):发出下次预热请求前的空闲时间。"auto" 模式下,若模型设置了 cache.ttl,则取该值的 90%;若未设置,则为 4 分钟。
  • duration(默认:"30 minutes"):预热窗口时长,计时起点为最后一次非预热的模型请求。

对象配置中省略的字段将沿用默认值。例如,以下配置仅修改了间隔时间:

opencode.jsonc
{
  "warming": {
    "interval": "2 minutes",
  },
}

interval 默认值为 "auto",旨在紧贴模型提示词缓存的过期时间进行预热。OpenCode 采用模型 cache.ttl 设置的 90% 作为间隔,例如 "5m" 的缓存将在 4.5 分钟后触发预热。对于未设置 cache.ttl 的模型,则每 4 分钟预热一次。

opencode.jsonc
{
  "warming": { "duration": "2 hours" },
  "providers": {
    "anthropic": { "settings": { "cache": { "ttl": "1h" } } },
  },
}

如果缓存有效期(如 "1h")长于 duration(如默认的 30 分钟),系统将不会执行预热,因为缓存本身在窗口结束前不会失效。OpenCode 会在每个会话中记录一次此日志。若需预热此类长缓存,请增大 duration 的值。

你可以通过在提供商(provider)或模型(model)级别设置 settings.cache.warming,来仅为特定会话启用预热或设置独立的时间参数。该配置项接受与顶层 warming 相同的值(prompt 除外),并会覆盖顶层设置。模型级设置优先级高于提供商级设置。

opencode.jsonc
{
  "providers": {
    "anthropic": {
      "settings": { "cache": { "ttl": "5m", "warming": true } },
      "models": {
        "claude-haiku-5-5": { "settings": { "cache": { "warming": false } } },
      },
    },
  },
}

在上述示例中,Anthropic 的会话每 4.5 分钟预热一次,但 Claude Haiku 5.5 除外(其预热被禁用)。其他提供商不进行预热。对象配置中省略的字段将依次回退到顶层 warming 配置或默认值。无效的设置会记录警告并回退到顶层配置。

interval 和 duration 接受持续时间字符串。两者必须解析为大于零的有限数值,且 interval 必须短于 duration;否则 OpenCode 将跳过预热并记录警告。

opencode.jsonc
{
  "warming": {
    "interval": "30 seconds",
    "duration": "1 hour",
  },
}

预热仅在顶层会话发生非预热模型请求后启动。子智能体(Subagent)会话不进行预热。每个间隔时间的计数起点是上一次请求或预热请求的发送时间,而非响应完成时间,因为服务端缓存的生命周期始于请求抵达时。预热请求不会延长活跃窗口。

00:00  发送正常模型请求
00:01  响应完成
00:04  预热请求
00:08  预热请求
00:30  停止预热

任何新的非预热模型活动(包括压缩操作)都会重置这两个计时器。若显式设置的 interval 大于或等于 duration,系统将拒绝并记录警告;若 "auto" 间隔过长导致缓存寿命超过窗口期,则会跳过预热。

00:00  正常模型请求
00:20  正常模型请求;窗口重启
00:24  预热请求
00:50  停止预热

当模型请求(包括压缩操作)正在运行时,OpenCode 绝不会发送预热请求。若计时到达时请求仍在执行,预热将等待其完成并立即发送(前提是该请求产生的缓存尚未过期)。若缓存已过期,则停止预热,直到下一次正常请求发生。

00:00  发送正常模型请求
00:04  间隔到期;请求仍在运行
00:04:30  响应完成;发送预热请求
00:08:30  预热请求

预热请求复用当前会话的模型、智能体、指令和对话上下文。OpenCode 会临时附加配置的提示词,执行一次模型调用,随后丢弃响应结果。

[当前会话上下文]
[临时用户消息:保活提示词]
→ 生成一次模型响应(随后丢弃)

该请求不接受输入、不添加消息到历史记录,也不变更持久化的会话状态。OpenCode 不会分发本地工具调用或继续工具循环;默认提示词也明确指示模型不要使用工具。

预热失败仅记录日志,不会导致会话失败或状态变更。OpenCode 会等待至下一个间隔再尝试,而原始的活跃窗口计时继续向下计数。

00:04  预热请求失败;会话状态不变
00:08  尝试下一次预热

如果预热请求未命中缓存(即从缓存读取的数据少于写入的数据),系统将为该会话停止预热,直到下一次非预热请求发生。不报告缓存使用量的提供商永远不会被视为未命中。

00:04  预热请求未命中缓存;停止预热
00:10  正常模型请求;恢复预热
00:14  预热请求

预热请求是真实的提供商请求。它们可能消耗令牌、产生费用、计入速率限制,并可能像其他模型请求一样失败。

  • 更短的 interval 会增加请求量。
  • 更长的 duration 允许更多的预热请求。
  • 仅当服务端缓存收益足以抵消增加的用量成本时,才启用预热。

例如,对于未设置 cache.ttl 的模型,默认设置下,在一个不间断的 30 分钟窗口内最多允许 7 次预热尝试:分别发生在第 4、8、12、16、20、24 和 28 分钟。

将 warming 显式设置为 false 可关闭该功能。省略该字段同样保持关闭状态。

opencode.jsonc
{
  "warming": false,
}

评论 (0)