Skip to content

[Workers AI] Document model-specific reasoning controls #33025

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
KastanDay wants to merge 5 commits into from
Closed

[Workers AI] Document model-specific reasoning controls #33025

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
98720d7
[Workers AI] Document GLM-5.2 reasoning effort
KastanDay Aug 25, 2026
f2fcb67
[Workers AI] Use canonical reasoning effort property
KastanDay Aug 25, 2026
e893158
[Workers AI] Show GLM reasoning effort values
KastanDay Aug 25, 2026
bf091a8
[Workers AI] Document model-specific reasoning controls
KastanDay Aug 25, 2026
6b60469
Merge branch 'production' into kastan/reasoning-model-policy-docs
mchenco Aug 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 111 additions & 0 deletions src/components/models/ModelDetailPage.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,12 @@ const authorName = model.authorName;
const requiresWorkersPaid =
model.properties.require_workers_paid === true ||
model.properties.require_workers_paid === "true";
const reasoningEffortGuidance = new Map<string, string>([
["@cf/zai-org/glm-5.2", "glm-5.2"],
["@cf/google/gemma-4-26b-a4b-it", "gemma-4"],
["@cf/deepseek-ai/deepseek-v4-flash-0731", "deepseek-v4-official"],
["@cf/deepseek-ai/deepseek-v4-pro-0813", "deepseek-v4-official"],
]).get(model.name);

// `hasSchema`: input must have at least one key.
const hasSchema = Object.keys(model.schema.input).length > 0;
Expand Down Expand Up @@ -214,6 +220,11 @@ const pageTitle = `${displayName} (${authorName})`;
const headTitle = `${pageTitle} · Cloudflare AI docs`;

const headings: MarkdownHeading[] = [
reasoningEffortGuidance && {
depth: 2,
slug: "reasoning-effort",
text: "Reasoning effort",
},
hasPlayground && { depth: 2, slug: "playground", text: "Playground" },
hasCodeExamples && { depth: 2, slug: "usage", text: "Usage" },
hasRemainingExamples && { depth: 2, slug: "examples", text: "Examples" },
Expand Down Expand Up @@ -343,6 +354,106 @@ const headings: MarkdownHeading[] = [

<ModelFeatures model={model} />

{
reasoningEffortGuidance === "glm-5.2" && (
<Fragment>
<AnchorHeading
depth={2}
title="Reasoning effort"
slug="reasoning-effort"
/>
<p>
GLM-5.2 supports <code>high</code> and <code>max</code> reasoning
effort, or you can turn reasoning off. For compatibility with Chat
Completions and other protocols in the ecosystem, other reasoning
efforts will be mapped to these modes:
</p>
<ul>
<li>
<code>none</code> and <code>minimal</code> turn reasoning off.
</li>
<li>
<code>low</code> and <code>medium</code> map to <code>high</code>.
</li>
<li>
<code>xhigh</code> maps to <code>max</code>.
</li>
</ul>
<p>
This is the same mapping used by Z.ai's API, and{" "}
<a href="https://docs.z.ai/api-reference/llm/chat-completion#body-one-of-0-reasoning-effort">
in their <code>reasoning_effort</code> documentation
</a>
.
</p>
</Fragment>
)
}

{
reasoningEffortGuidance === "deepseek-v4-official" && (
<Fragment>
<AnchorHeading
depth={2}
title="Reasoning effort"
slug="reasoning-effort"
/>
<p>
DeepSeek V4 Flash 0731 and Pro 0813 support <code>low</code>,{" "}
<code>high</code>, and <code>max</code> reasoning effort. You can also
turn reasoning off. Reasoning is off by default.
</p>
<p>Other reasoning efforts map to these modes:</p>
<ul>
<li>
<code>none</code> and <code>minimal</code> turn reasoning off.
</li>
<li>
<code>medium</code> and <code>auto</code> map to <code>high</code>.
</li>
<li>
<code>xhigh</code> maps to <code>max</code>.
</li>
</ul>
<p>
A request without reasoning controls remains off. If a prior assistant
message contains non-empty <code>reasoning_content</code>, the model
continues reasoning at <code>high</code> to preserve that context.
</p>
</Fragment>
)
}

{
reasoningEffortGuidance === "gemma-4" && (
<Fragment>
<AnchorHeading
depth={2}
title="Reasoning effort"
slug="reasoning-effort"
/>
<p>
Gemma 4 supports turning reasoning on or off. It does not support
different reasoning intensity levels. Reasoning is off by default.
</p>
<ul>
<li>
<code>none</code> and <code>minimal</code> turn reasoning off.
</li>
<li>
<code>low</code>, <code>medium</code>, <code>high</code>,{" "}
<code>xhigh</code>, <code>max</code>, and <code>auto</code> turn
reasoning on.
</li>
</ul>
<p>
These values provide API compatibility. They do not change the amount
of reasoning Gemma 4 performs.
</p>
</Fragment>
)
}

{
/* Defensive dead branch (model not in slice): nova-3 transport pricing. */
model.name === "@cf/deepgram/nova-3" && (
Expand Down
2 changes: 1 addition & 1 deletion src/components/models/ModelFeatures.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,7 @@ const price = Array.isArray(properties.price)
{properties.reasoning && (
<tr>
<td>Reasoning</td>
<td>Yes</td>
<td>{properties.reasoning_effort ?? "Yes"}</td>
</tr>
)}
{properties.vision && (
Expand Down
8 changes: 7 additions & 1 deletion src/components/models/SchemaDisplay.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,6 +171,7 @@ function collectRows(
let isNullable = false;
let nullableType: string | undefined;
let nullableChildDescription: string | undefined;
let nullableChildEnumValues: unknown[] | undefined;
if ((hasOneOf || hasAnyOf) && reg.children?.length === 2) {
const childTypes = reg.children.map((c) =>
String((c as RegularNode).primaryType ?? ""),
Expand All @@ -183,6 +184,10 @@ function collectRows(
nullableType = childTypes[nonNullIndex];
nullableChildDescription = nonNullChild.annotations?.description as
string | undefined;
nullableChildEnumValues =
(nonNullChild.validations?.enum as unknown[]) ??
((nonNullChild.fragment as Record<string, unknown>)
?.enum as unknown[]);
isNullable = true;
}
}
Expand All @@ -207,7 +212,8 @@ function collectRows(
// Check both validations and fragment for enum (different schema parsers put it in different places)
const enumValues = (
(reg.validations?.enum as unknown[]) ??
((reg.fragment as Record<string, unknown>)?.enum as unknown[])
((reg.fragment as Record<string, unknown>)?.enum as unknown[]) ??
nullableChildEnumValues
)?.map(String);

// Collect all metadata from fragment and validations
Expand Down
58 changes: 41 additions & 17 deletions src/content/workers-ai-models/deepseek-v4-flash-0731.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,10 @@
"property_id": "reasoning",
"value": "true"
},
{
"property_id": "reasoning_effort",
"value": "Off, Low, High, Max"
},
{
"property_id": "price",
"value": [
Expand Down Expand Up @@ -295,24 +299,29 @@
{
"type": "string",
"enum": [
"none",
"minimal",
"low",
"medium",
"high"
"high",
"xhigh",
"max",
"auto"
]
},
{
"type": "null"
}
],
"description": "Constrains effort on reasoning for reasoning models (o1, o3-mini, etc.)."
"description": "Controls reasoning effort. none and minimal turn reasoning off; medium and auto map to high; xhigh maps to max."
},
"chat_template_kwargs": {
"type": "object",
"properties": {
"enable_thinking": {
"type": "boolean",
"default": true,
"description": "Whether to enable reasoning, enabled by default."
"default": false,
"description": "Whether to turn reasoning on. Reasoning is off by default."
},
"clear_thinking": {
"type": "boolean",
Expand Down Expand Up @@ -1561,24 +1570,29 @@
{
"type": "string",
"enum": [
"none",
"minimal",
"low",
"medium",
"high"
"high",
"xhigh",
"max",
"auto"
]
},
{
"type": "null"
}
],
"description": "Constrains effort on reasoning for reasoning models (o1, o3-mini, etc.)."
"description": "Controls reasoning effort. none and minimal turn reasoning off; medium and auto map to high; xhigh maps to max."
},
"chat_template_kwargs": {
"type": "object",
"properties": {
"enable_thinking": {
"type": "boolean",
"default": true,
"description": "Whether to enable reasoning, enabled by default."
"default": false,
"description": "Whether to turn reasoning on. Reasoning is off by default."
},
"clear_thinking": {
"type": "boolean",
Expand Down Expand Up @@ -2397,24 +2411,29 @@
{
"type": "string",
"enum": [
"none",
"minimal",
"low",
"medium",
"high"
"high",
"xhigh",
"max",
"auto"
]
},
{
"type": "null"
}
],
"description": "Constrains effort on reasoning for reasoning models (o1, o3-mini, etc.)."
"description": "Controls reasoning effort. none and minimal turn reasoning off; medium and auto map to high; xhigh maps to max."
},
"chat_template_kwargs": {
"type": "object",
"properties": {
"enable_thinking": {
"type": "boolean",
"default": true,
"description": "Whether to enable reasoning, enabled by default."
"default": false,
"description": "Whether to turn reasoning on. Reasoning is off by default."
},
"clear_thinking": {
"type": "boolean",
Expand Down Expand Up @@ -3663,24 +3682,29 @@
{
"type": "string",
"enum": [
"none",
"minimal",
"low",
"medium",
"high"
"high",
"xhigh",
"max",
"auto"
]
},
{
"type": "null"
}
],
"description": "Constrains effort on reasoning for reasoning models (o1, o3-mini, etc.)."
"description": "Controls reasoning effort. none and minimal turn reasoning off; medium and auto map to high; xhigh maps to max."
},
"chat_template_kwargs": {
"type": "object",
"properties": {
"enable_thinking": {
"type": "boolean",
"default": true,
"description": "Whether to enable reasoning, enabled by default."
"default": false,
"description": "Whether to turn reasoning on. Reasoning is off by default."
},
"clear_thinking": {
"type": "boolean",
Expand Down Expand Up @@ -4767,4 +4791,4 @@
}
},
"deprecated": false
}
}
Loading