Get up and running with Kimi, GLM, MiniMax, DeepSeek, gpt-oss, Qwen, Gemma and other models.
docs: document thinking control discovery (#18501)
Parth Sareenc1737589973d
diff --git a/docs/api/anthropic-compatibility.mdx b/docs/api/anthropic-compatibility.mdxindex 676514817..b57bd26b6 100644--- a/docs/api/anthropic-compatibility.mdx+++ b/docs/api/anthropic-compatibility.mdx@@ -303,6 +303,8 @@ See the [Claude Code guide](/integrations/claude-code) for Ollama Launch and [di- [x] `stop_sequences`- [x] `tools`- [x] `thinking`+- [x] `output_config`+ - [x] `effort` (model-defined names)- [ ] `tool_choice`- [ ] `metadata`@@ -327,6 +329,8 @@ See the [Claude Code guide](/integrations/claude-code) for Ollama Launch and [di- [x] `ping`- [x] `error`+Use `/api/show` to discover a model's supported thinking values and default. `thinking.type: "enabled"` and `"disabled"` act as explicit on/off controls. When a model uses its metadata to resolve named levels, supported `output_config.effort` names are applied exactly and unsupported names resolve to the model default. Models without metadata keep the existing compatibility behavior, which trims and lowercases effort names and maps `"xhigh"` to `"high"`.+## ModelsOllama supports both local and cloud models.diff --git a/docs/api/openai-compatibility.mdx b/docs/api/openai-compatibility.mdxindex c12bda912..272f98ea7 100644--- a/docs/api/openai-compatibility.mdx+++ b/docs/api/openai-compatibility.mdx@@ -242,14 +242,16 @@ curl -X POST http://localhost:11434/v1/chat/completions \- [x] `top_p`- [x] `max_tokens`- [x] `tools`-- [x] `reasoning_effort` (`"high"`, `"medium"`, `"low"`, `"max"`, `"none"`)+- [x] `reasoning_effort` (model-defined names and compatibility aliases)- [x] `reasoning`- - [x] `effort` (`"high"`, `"medium"`, `"low"`, `"max"`, `"none"`)+ - [x] `effort` (model-defined names and compatibility aliases)- [ ] `tool_choice`- [ ] `logit_bias`- [ ] `user`- [ ] `n`+`reasoning_effort` and `reasoning.effort` control model thinking. Use `/api/show` to discover each model's supported values and default. When a model uses its metadata to resolve named levels, supported names are applied exactly and unsupported names resolve to the model default. Boolean-only models that support enabling thinking map recognized compatibility efforts to `true`, while `"none"` requests `false`. Models without metadata retain the existing compatibility aliases: `"minimal"` maps to `"low"`, and `"xhigh"` or `"ultra"` map to `"max"`. GPT-OSS keeps its existing OpenAI compatibility conversion: `"minimal"` uses `"low"`, `"xhigh"` or `"ultra"` use `"high"`, and `"none"` requests no thinking output.+### `/v1/completions`#### Supported features@@ -338,6 +340,9 @@ Ollama supports the [OpenAI Responses API](https://platform.openai.com/docs/api-- [x] `temperature`- [x] `top_p`- [x] `max_output_tokens`+- [x] `reasoning`+ - [x] `effort` (model-defined names and compatibility aliases)+- [x] `think` (Ollama extension; boolean, model-defined string, or `null`)- [ ] `previous_response_id` (stateful v1/responses not supported)- [ ] `conversation` (stateful v1/responses not supported)- [ ] `truncation`diff --git a/docs/capabilities/thinking.mdx b/docs/capabilities/thinking.mdxindex 4e58c1d73..b357ccd86 100644--- a/docs/capabilities/thinking.mdx+++ b/docs/capabilities/thinking.mdx@@ -6,21 +6,46 @@ Thinking-capable models emit a `thinking` field that separates their reasoning tUse this capability to audit model steps, animate the model *thinking* in a UI, or hide the trace entirely when you only need the final response.-## Supported models+See the [full list of thinking models](https://ollama.com/search?c=thinking).-- [Qwen 3](https://ollama.com/library/qwen3)-- [GPT-OSS](https://ollama.com/library/gpt-oss) *(use `think` levels: `low`, `medium`, `high` — the trace cannot be fully disabled)*-- [DeepSeek-v3.1](https://ollama.com/library/deepseek-v3.1)-- [DeepSeek R1](https://ollama.com/library/deepseek-r1)-- Browse the latest additions under [thinking models](https://ollama.com/search?c=thinking)+## Discover a model's thinking controls++Thinking controls vary by model. Use `/api/show` to discover the values a model supports and the value Ollama uses by default:++```shell+curl http://localhost:11434/api/show -d '{+ "model": "gpt-oss"+}'+```++The response includes a top-level `thinking` object:++```json+{+ "thinking": {+ "values": ["low", "medium", "high"],+ "default": "medium"+ }+}+```++- `values` can contain booleans (`true` or `false`) for on/off controls. It can also contain model-defined strings for named levels.+- `default` is used when `think` is not set.+- `values: [false]` means the model does not support thinking.+- If `thinking` is omitted, the model has no thinking metadata. The model might conduct thinking based on its existing behavior.## Enable thinking in API calls-Set the `think` field on chat or generate requests. Most models accept booleans (`true`/`false`) or levels (`low`, `medium`, `high`, `max`), where `max` requests the highest thinking level.+Set the `think` field on a chat or generate request:-GPT-OSS instead expects one of `low`, `medium`, or `high` to tune the trace length.+- `true`: request thinking output.+- `false`: request no thinking output, if the model permits it.+- `null`: use the model default.+- A string: select a supported level from `thinking.values`. Use the exact value from `/api/show`. Numbers are not supported.-The `message.thinking` (chat endpoint) or `thinking` (generate endpoint) field contains the reasoning trace while `message.content` / `response` holds the final answer.+If the model resolves named levels from `/api/show` metadata, Ollama applies supported names exactly. Unsupported names use the model default.++The reasoning output and answer use separate fields. Chat returns `message.thinking` and `message.content`. Generate returns `thinking` and `response`.<Tabs><Tab title="cURL">@@ -68,10 +93,6 @@ The `message.thinking` (chat endpoint) or `thinking` (generate endpoint) field c</Tab></Tabs>-<Note>- GPT-OSS requires `think` to be set to `"low"`, `"medium"`, or `"high"`. Passing `true`/`false` is ignored for that model.-</Note>-## Stream the reasoning traceThinking streams interleave reasoning tokens before answer tokens. Detect the first `thinking` chunk to render a "thinking" section, then switch to the final reply once `message.content` arrives.@@ -141,13 +162,3 @@ Thinking streams interleave reasoning tokens before answer tokens. Detect the fi```</Tab></Tabs>--## CLI quick reference--- Enable thinking for a single run: `ollama run deepseek-r1 --think "Where should I visit in Lisbon?"`-- Disable thinking: `ollama run deepseek-r1 --think=false "Summarize this article"`-- Hide the trace while still using a thinking model: `ollama run deepseek-r1 --hidethinking "Is 9.9 bigger or 9.11?"`-- Inside interactive sessions, toggle with `/set think` or `/set nothink`.-- GPT-OSS only accepts levels: `ollama run gpt-oss --think=low "Draft a headline"` (replace `low` with `medium` or `high` as needed).--<Note>Thinking is enabled by default in the CLI and API for supported models.</Note>diff --git a/docs/openapi.yaml b/docs/openapi.yamlindex 8ef988e18..86fc5e9dc 100644--- a/docs/openapi.yaml+++ b/docs/openapi.yaml@@ -96,11 +96,7 @@ components:type: booleandefault: truethink:- oneOf:- - type: boolean- - type: string- enum: [high, medium, low, max]- description: When true, returns separate thinking output in addition to content. Can be a boolean (true/false) or a string ("high", "medium", "low", "max") for supported models, with "max" requesting the highest thinking level.+ $ref: "#/components/schemas/ThinkValue"raw:type: booleandescription: When true, returns the raw response from the model without any prompt templating@@ -294,11 +290,7 @@ components:type: booleandefault: truethink:- oneOf:- - type: boolean- - type: string- enum: [high, medium, low, max]- description: When true, returns separate thinking output in addition to content. Can be a boolean (true/false) or a string ("high", "medium", "low", "max") for supported models, with "max" requesting the highest thinking level.+ $ref: "#/components/schemas/ThinkValue"keep_alive:oneOf:- type: string@@ -410,6 +402,29 @@ components:done:type: booleandescription: True for the final event in the stream+ ThinkValue:+ description: Controls a model's thinking output. Use `/api/show` to discover the supported values and default for the selected model. `true` requests thinking, `false` requests no thinking output, and `null` uses the model default. String values are model-defined; supported names must match `/api/show` exactly. Numbers are not supported.+ oneOf:+ - type: boolean+ - type: string+ - type: "null"+ Thinking:+ type: object+ required: [values, default]+ description: Thinking controls advertised by a model. Models without thinking metadata omit this field.+ properties:+ values:+ type: array+ description: Values explicitly supported by the model's `think` request field. Booleans represent on/off controls and strings represent model-defined levels. An array containing only `false` identifies a model without thinking support.+ items:+ oneOf:+ - type: boolean+ - type: string+ default:+ description: Value used when `think` is not set. For models that use this metadata for named thinking levels, unsupported names resolve to this default.+ oneOf:+ - type: boolean+ - type: stringStatusEvent:type: objectproperties:@@ -597,6 +612,8 @@ components:ShowResponse:type: objectproperties:+ thinking:+ $ref: "#/components/schemas/Thinking"parameters:type: stringdescription: Model parameter settings serialized as text@@ -836,6 +853,15 @@ paths:"prompt": "Why is the sky blue?","stream": false}'+ - lang: bash+ label: Thinking+ source: |+ curl http://localhost:11434/api/generate -d '{+ "model": "gpt-oss",+ "prompt": "What is 1+1?",+ "think": "low",+ "stream": false+ }'- lang: bashlabel: With optionssource: |@@ -1245,6 +1271,18 @@ paths:"model": "gemma4","verbose": true}'+ - lang: bash+ label: Thinking controls+ source: |+ curl http://localhost:11434/api/show -d '{+ "model": "gpt-oss"+ }'+ - lang: bash+ label: Thinking controls+ source: |+ curl http://localhost:11434/api/show -d '{+ "model": "gpt-oss"+ }'requestBody:required: truecontent:@@ -1265,7 +1303,13 @@ paths:license: "Gemma Terms of Use \n\nLast modified: February 21, 2024..."capabilities:- "completion"+ - "thinking"- "vision"+ thinking:+ values:+ - false+ - true+ default: truemodified_at: "2025-08-14T15:49:43.634137516-07:00"details:parent_model: ""