mirror of
https://github.com/anomalyco/opencode.git
synced 2026-11-19 00:03:13 +03:00
docs: document model compatibility settings (#59509)
This commit is contained in:
committed by
GitHub
Unverified
parent
08132f1891
commit
da638b65f5
@@ -24,22 +24,27 @@ export type CacheFormat = typeof CacheFormat.Type
|
||||
|
||||
export interface Compatibility extends Schema.Schema.Type<typeof Compatibility> {}
|
||||
export const Compatibility = Schema.Struct({
|
||||
/** OpenAI Chat: assistant-message field that carries reasoning. Unset uses the streamed field, else `reasoning_content`. */
|
||||
reasoningField: ReasoningField.pipe(optional),
|
||||
/** Require every assistant message to include its reasoning field, even when empty. */
|
||||
/** OpenAI Chat: send the reasoning field on every prior assistant message, even when empty. */
|
||||
requireReasoning: Schema.Boolean.pipe(optional),
|
||||
/** OpenAI Chat: body field for the output token limit. Unset detects it from the provider. */
|
||||
maxTokensField: MaxTokensField.pipe(optional),
|
||||
/** OpenAI Chat: fail a stream that ends without `finish_reason`. Defaults to true. */
|
||||
requireFinishReason: Schema.Boolean.pipe(optional),
|
||||
/** OpenAI Chat: insert an assistant message between a tool result and the next user message. */
|
||||
requireAssistantAfterTool: Schema.Boolean.pipe(optional),
|
||||
/** OpenAI Chat, OpenAI Responses and Mistral: whether the endpoint accepts `prompt_cache_key`. */
|
||||
supportsPromptCacheKey: Schema.Boolean.pipe(optional),
|
||||
/** Request usage in the stream with `stream_options.include_usage`. Defaults to true. */
|
||||
/** OpenAI Chat: request usage in the stream with `stream_options.include_usage`. Defaults to true. */
|
||||
streamUsage: Schema.Boolean.pipe(optional),
|
||||
/** Prompt-cache marker syntax the endpoint accepts. Overrides the route default; both send `cache_control`, and `alibaba` skips tool definitions. */
|
||||
cacheFormat: CacheFormat.pipe(optional),
|
||||
/** Supports Anthropic's thinking-prefix mismatch controls. Overrides model-ID detection. */
|
||||
/** Anthropic Messages and Bedrock Converse: supports Anthropic's thinking-prefix mismatch controls. Overrides model-ID detection. */
|
||||
supportsThinkingBlockBinding: Schema.Boolean.pipe(optional),
|
||||
/** Supports per-message effort updates. Overrides model-ID detection. */
|
||||
/** Anthropic Messages and OpenAI Responses: supports per-message effort updates. Overrides model-ID detection. */
|
||||
supportsEffortUpdates: Schema.Boolean.pipe(optional),
|
||||
/** Where a System One decision host reads media. Unset keeps the route default. */
|
||||
/** System One: where the decision host reads media. Unset keeps the route default. */
|
||||
mediaInput: MediaInput.pipe(optional),
|
||||
}).annotate({ identifier: "Model.Compatibility" })
|
||||
|
||||
|
||||
@@ -273,7 +273,7 @@ For an OpenAI-compatible model that streams reasoning in a custom assistant-mess
|
||||
|
||||
OpenCode recognizes `reasoning`, `reasoning_content`, and `reasoning_text`, and also accepts another provider-specific
|
||||
string. It reads streamed reasoning from that field and restores the field when sending prior assistant messages back to
|
||||
the model.
|
||||
the model. See [Compatibility](#compatibility) for the related `requireReasoning` field.
|
||||
|
||||
## Prompt caching
|
||||
|
||||
@@ -305,7 +305,48 @@ Anthropic-style `cache_control` breakpoints. Set `compatibility.cacheFormat` on
|
||||
OpenCode then marks the last tool definition, the system prompt, and the latest message with
|
||||
`cache_control: { "type": "ephemeral" }`, which uses the endpoint's default five-minute cache lifetime. Use `"alibaba"`
|
||||
for Alibaba Model Studio models, which accept the same markers but ignore them on tool definitions. Set
|
||||
`compatibility.cacheFormat` on the provider instead when every model it serves accepts the same format.
|
||||
`compatibility.cacheFormat` on the provider instead when every model it serves accepts the same format. See
|
||||
[Compatibility](#compatibility) for the other fields.
|
||||
|
||||
## Compatibility
|
||||
|
||||
`compatibility` describes request and response quirks of the API a model is served through, such as which field carries
|
||||
reasoning or whether the endpoint accepts `prompt_cache_key`. Each model is served through one API, and a field only
|
||||
takes effect when that API reads it. Other fields are ignored.
|
||||
|
||||
```jsonc title="opencode.jsonc"
|
||||
{
|
||||
"providers": {
|
||||
"local": {
|
||||
"compatibility": { "streamUsage": false },
|
||||
"models": {
|
||||
"reasoner": {
|
||||
"compatibility": { "reasoningField": "reasoning_content", "maxTokensField": "max_tokens" },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Provider `compatibility` applies to every model of that provider. A model's own `compatibility` overrides it field by
|
||||
field: OpenCode starts from the values [models.dev](https://models.dev) publishes for the model's API (`reasoningField`,
|
||||
`maxTokensField`, and `mediaInput`), then applies the model's configuration. Unset fields keep the provider package's
|
||||
built-in default or detection. `supportsThinkingBlockBinding` and `supportsEffortUpdates` are model-only.
|
||||
|
||||
| Field | What it does | Read by | Values and default |
|
||||
| --- | --- | --- | --- |
|
||||
| `reasoningField` | Assistant-message field that carries reasoning. Checked first when reading streamed reasoning and used when sending prior reasoning back. | OpenAI Chat | Any field name except `role`, `content`, `refusal`, or `tool_calls`. Unset uses the field seen in the stream, else `reasoning_content`. |
|
||||
| `requireReasoning` | Sends the reasoning field on every prior assistant message, as an empty string when there was no reasoning. | OpenAI Chat | `true` or `false`. Defaults to `true` when `reasoningField` is set or the model is DeepSeek, otherwise `false`. |
|
||||
| `maxTokensField` | Body field that carries the output token limit. | OpenAI Chat | `max_completion_tokens` or `max_tokens`. Unset detects `max_tokens` for providers that need it, such as DeepSeek, Moonshot, Together AI, Z.AI, and Cerebras, otherwise `max_completion_tokens`. |
|
||||
| `requireFinishReason` | Treats a stream that ends without `finish_reason` as an incomplete response error. `false` accepts it as finished. | OpenAI Chat | `true` or `false`. Defaults to `true`. |
|
||||
| `requireAssistantAfterTool` | Inserts an assistant message between a tool result and the next user message, for endpoints that reject that order. | OpenAI Chat | `true` or `false`. Defaults to `true` for Mistral-family model IDs, otherwise `false`. |
|
||||
| `supportsPromptCacheKey` | Whether the endpoint accepts the `prompt_cache_key` body field. | OpenAI Chat, OpenAI Responses, Mistral | `true` or `false`. OpenAI Chat only sends the key when `true`, which some provider packages set by default. Other APIs send it unless `false`. |
|
||||
| `streamUsage` | Requests token usage in the stream with `stream_options.include_usage`. | OpenAI Chat | `true` or `false`. Defaults to `true`. |
|
||||
| `cacheFormat` | Prompt-cache marker syntax the endpoint accepts. Overrides the provider's automatic breakpoint placement. `alibaba` skips tool definitions. | Every API with prompt-cache markers, including OpenAI Chat, Anthropic Messages, and Bedrock Converse | `anthropic` or `alibaba`. Unset uses the provider default. See [Prompt caching](#prompt-caching). |
|
||||
| `supportsThinkingBlockBinding` | Asks the API to drop thinking blocks whose earlier context changed instead of rejecting the request. | Anthropic Messages, Bedrock Converse | `true` or `false`. Unset detects Claude 5.1 and later. |
|
||||
| `supportsEffortUpdates` | Sends reasoning effort changes as per-message updates, which keep the prompt cache. Otherwise the effort changes for the whole request. | Anthropic Messages, OpenAI Responses | `true` or `false`. Unset detects Claude Opus 5, Claude 5.1 and later, and GPT-6 and later. |
|
||||
| `mediaInput` | Where images and other media go in a decision request. | System One | `assets` (images referenced from the state), `state` (inline in the state), or `root` (top-level `images`, `audio`, and `videos` lists). Unset uses the provider default. |
|
||||
|
||||
## Local
|
||||
|
||||
|
||||
@@ -90,7 +90,7 @@ The `providers` object is keyed by the provider ID used in model references, suc
|
||||
| `env` | Ordered environment variable names that can provide the credential. |
|
||||
| `package` | Runtime provider package. |
|
||||
| `canonical` | Built-in provider ID whose catalog defaults this provider inherits. |
|
||||
| `compatibility` | Request and response compatibility overrides for every model of this provider. Model `compatibility` overrides individual fields. `supportsThinkingBlockBinding` and `supportsEffortUpdates` are model-only. |
|
||||
| `compatibility` | API quirks shared by every model of this provider. See [Compatibility](/models#compatibility). |
|
||||
| `settings` | Typed OpenCode controls and JSON options passed to the runtime package. |
|
||||
| `headers` | String-valued HTTP headers added to requests. |
|
||||
| `body` | JSON fields merged into request bodies. |
|
||||
@@ -300,7 +300,7 @@ ID sent to the provider.
|
||||
| `headers` | Additional string-valued request headers. |
|
||||
| `body` | Additional JSON request body fields. |
|
||||
| `capabilities` | Tool support, accepted input and output media types, temperature support, and reasoning controls. |
|
||||
| `compatibility` | Request and response compatibility overrides. |
|
||||
| `compatibility` | API quirks for this model, overriding the provider's. See [Compatibility](/models#compatibility). |
|
||||
| `variants` | Named variants with their own `settings`, `headers`, and `body`. |
|
||||
| `cost` | Input, output, and optional cache pricing per million tokens. |
|
||||
| `limit` | Context, input, and output token limits. |
|
||||
|
||||
Reference in New Issue
Block a user