mirror of
https://github.com/anomalyco/opencode.git
synced 2026-11-16 05:01:03 +03:00
docs: document cache.ttl and per-model cache.warming (#62829)
This commit is contained in:
committed by
GitHub
Unverified
parent
894e30395c
commit
8e756809a1
@@ -409,8 +409,10 @@ interval and 30-minute active window.
|
||||
}
|
||||
```
|
||||
|
||||
See the [warming guide](/warming) for request behavior, customization,
|
||||
and cost considerations.
|
||||
A provider's or model's `settings.cache.warming` overrides it, and
|
||||
`settings.cache.ttl` sets how long the provider keeps the cache. See the
|
||||
[warming guide](/warming) for request behavior, customization, and cost
|
||||
considerations, and [cache lifetime](/models#cache-lifetime) for `cache.ttl`.
|
||||
|
||||
### Skills
|
||||
|
||||
|
||||
@@ -308,6 +308,39 @@ for Alibaba Model Studio models, which accept the same markers but ignore them o
|
||||
`compatibility.cacheFormat` on the provider instead when every model it serves accepts the same format. See
|
||||
[Compatibility](#compatibility) for the other fields.
|
||||
|
||||
### Cache lifetime
|
||||
|
||||
OpenCode doesn't send a cache lifetime by default, so each provider uses its own default, such as five minutes on
|
||||
Anthropic. Set `settings.cache.ttl` on a provider or model to request a different one. A model setting overrides the
|
||||
provider setting.
|
||||
|
||||
```jsonc title="opencode.jsonc"
|
||||
{
|
||||
"providers": {
|
||||
"anthropic": {
|
||||
"settings": { "cache": { "ttl": "1h" } },
|
||||
"models": {
|
||||
"claude-haiku-5-5": { "settings": { "cache": { "ttl": "5m" } } },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
`ttl` takes a number and a unit: `ms`, `s`, `m`, `h` or `d`, such as `"5m"`, `"1h"` or `"24h"`. OpenCode sends it as
|
||||
given, so use a value the provider accepts:
|
||||
|
||||
| API | Where the lifetime goes |
|
||||
| --- | --- |
|
||||
| Anthropic Messages | `cache_control.ttl` on each cache marker. Anthropic accepts `"5m"` and `"1h"`. |
|
||||
| Bedrock Converse | `ttl` on each `cachePoint`. Older Claude models that only cache for five minutes ignore `"1h"`. |
|
||||
| OpenAI Chat and Responses | `"24h"` goes to `prompt_cache_retention`; other values go to `prompt_cache_options.ttl`. |
|
||||
|
||||
Providers that cache automatically without markers, such as Gemini, ignore it. A longer lifetime usually costs more to
|
||||
write: Anthropic charges 2× the input price for a one-hour cache write and 1.25× for a five-minute one.
|
||||
|
||||
[Warming](/warming) can use the lifetime to time its requests with `interval: "auto"`.
|
||||
|
||||
## Compatibility
|
||||
|
||||
`compatibility` describes request and response quirks of the API a model is served through, such as which field carries
|
||||
|
||||
@@ -55,7 +55,7 @@ interval:
|
||||
## Automatic interval
|
||||
|
||||
Set `interval` to `"auto"` to warm just before each model's prompt cache
|
||||
expires. OpenCode uses 90% of the model's [`cache.ttl`](/config) setting, so a
|
||||
expires. OpenCode uses 90% of the model's [`cache.ttl`](/models#cache-lifetime) setting, so a
|
||||
`"5m"` cache is warmed every 4.5 minutes. Models without a `cache.ttl` are not
|
||||
warmed.
|
||||
|
||||
@@ -72,6 +72,31 @@ The interval must be shorter than `duration`, so raise `duration` for long
|
||||
cache lifetimes such as `"1h"`. Otherwise OpenCode skips warming and logs a
|
||||
warning.
|
||||
|
||||
## Per provider and model
|
||||
|
||||
Set `settings.cache.warming` on a provider or model to warm only its sessions,
|
||||
or to give them their own timing. It takes the same values as the top-level
|
||||
`warming`, except `prompt`, and overrides it. A model setting overrides the
|
||||
provider setting.
|
||||
|
||||
```jsonc title="opencode.jsonc"
|
||||
{
|
||||
"providers": {
|
||||
"anthropic": {
|
||||
"settings": { "cache": { "ttl": "5m", "warming": { "interval": "auto" } } },
|
||||
"models": {
|
||||
"claude-haiku-5-5": { "settings": { "cache": { "warming": false } } },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Here Anthropic sessions are warmed every 4.5 minutes, except on Claude Haiku
|
||||
5.5, and other providers aren't warmed. Fields left out of the object form come
|
||||
from the top-level `warming`, then the defaults. An invalid setting logs a
|
||||
warning and falls back to the top-level `warming`.
|
||||
|
||||
## Durations
|
||||
|
||||
`interval` and `duration` accept duration strings. Both must resolve to finite
|
||||
@@ -89,7 +114,8 @@ otherwise OpenCode skips warming and logs a warning.
|
||||
|
||||
## Timing
|
||||
|
||||
Warming starts after a non-warming model request. After a warming request
|
||||
Warming starts after a non-warming model request in a top-level session.
|
||||
Subagent sessions are not warmed. After a warming request
|
||||
finishes, the next idle interval starts, but the active window is not extended.
|
||||
|
||||
```text
|
||||
|
||||
Reference in New Issue
Block a user