Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: fit reasoning_effort to a template's enforced allowlist (#16527)

Long Yixing5b219c9a4aca
diff --git a/studio/backend/core/inference/chat_template_helpers.py b/studio/backend/core/inference/chat_template_helpers.py
index 3e48475a976..38da77c681f 100644
--- a/studio/backend/core/inference/chat_template_helpers.py
+++ b/studio/backend/core/inference/chat_template_helpers.py
@@ -2812,6 +2812,22 @@ def apply_chat_template_for_generation(
if reasoning_kwargs:
attempts.append(dict(reasoning_kwargs))
attempts.append({})
+ if reasoning_effort is not None:
+ from core.inference.llama_cpp import _fit_reasoning_effort_to_template
+
+ # Fit per attempt: sanitizing or a tools-less retry can switch tool_use to default.
+ attempts = [
+ {
+ **kw,
+ "reasoning_effort": _fit_reasoning_effort_to_template(
+ "\n".join(_selected_chat_template_strings(tokenizer, kw.get("tools"))),
+ reasoning_effort,
+ ),
+ }
+ if "reasoning_effort" in kw
+ else kw
+ for kw in attempts
+ ]
# A tools=-less retry selects "default", so its messages need that template's profile.
_fallback_markup = _UNPARSED
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 74a6651c222..35556178510 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -3085,6 +3085,27 @@ def _clamp_reasoning_effort_to_levels(effort: Optional[str], levels) -> Optional
return below[-1] if below else offered[0]
+def _fit_reasoning_effort_to_template(
+ chat_template: Optional[str],
+ effort,
+ thinking_off: bool = False,
+):
+ """A level the template's raising allowlist rejects becomes one it accepts, so the render cannot fail."""
+ allowed = _reasoning_effort_allowlist(chat_template or "")
+ if not allowed or effort in allowed:
+ return effort
+ if thinking_off and "none" in allowed:
+ return "none"
+ return _clamp_reasoning_effort_to_levels(effort, allowed) or effort
+
+
+def _rendered_chat_template(backend) -> Optional[str]:
+ # getattr: test doubles skip __init__ and borrow backend methods unbound.
+ return getattr(backend, "_chat_template_override", None) or getattr(
+ backend, "_chat_template", None
+ )
+
+
# Keyed on identity, not name, so a rebuilt GGUF at the same path is logged again.
_GGUF_METADATA_LOGGED: "dict[tuple, bool]" = {}
_GGUF_METADATA_LOGGED_MAX = 32
@@ -9098,9 +9119,13 @@ class LlamaCppBackend:
# GLM-5.2 style: enable_thinking is the on/off gate; when on, keep the template's default effort.
return {"enable_thinking": enable_thinking}
if self._reasoning_style == "reasoning_effort":
+ effort = _fit_reasoning_effort_to_template(
+ _rendered_chat_template(self),
+ effort or ("high" if enable_thinking else "low"),
+ thinking_off = not effort and not enable_thinking,
+ )
return _coerce_reasoning_effort(
- getattr(self, "_architecture", None),
- {"reasoning_effort": effort or ("high" if enable_thinking else "low")},
+ getattr(self, "_architecture", None), {"reasoning_effort": effort}
)
return {"enable_thinking": enable_thinking}
@@ -9248,6 +9273,8 @@ class LlamaCppBackend:
kwargs["reasoning_effort"] = effort
elif self._reasoning_style == "reasoning_effort":
_levels = getattr(self, "_reasoning_effort_levels", None) or ()
+ _template = _rendered_chat_template(self)
+ reasoning_effort = _fit_reasoning_effort_to_template(_template, reasoning_effort)
if reasoning_effort in ("none", "low", "medium", "high") or (
reasoning_effort in _levels
):
@@ -9255,7 +9282,11 @@ class LlamaCppBackend:
elif reasoning_effort == "minimal":
kwargs["reasoning_effort"] = "low"
elif enable_thinking is not None:
- kwargs["reasoning_effort"] = "high" if enable_thinking else "low"
+ kwargs["reasoning_effort"] = _fit_reasoning_effort_to_template(
+ _template,
+ "high" if enable_thinking else "low",
+ thinking_off = not enable_thinking,
+ )
else:
if enable_thinking is not None:
kwargs["enable_thinking"] = enable_thinking
diff --git a/studio/backend/tests/test_reasoning_effort_allowlist.py b/studio/backend/tests/test_reasoning_effort_allowlist.py
index 7a7f32fb405..3d58fcb86d3 100644
--- a/studio/backend/tests/test_reasoning_effort_allowlist.py
+++ b/studio/backend/tests/test_reasoning_effort_allowlist.py
@@ -115,6 +115,138 @@ def test_allowlist_ignores_levels_quoted_elsewhere():
assert detect_reasoning_flags(template)["reasoning_effort_levels"] == ["low", "medium", "high"]
+def _gguf_backend(template: str):
+ from core.inference.llama_cpp import LlamaCppBackend
+
+ backend = object.__new__(LlamaCppBackend)
+ flags = detect_reasoning_flags(template)
+ backend._supports_reasoning = flags["supports_reasoning"]
+ backend._reasoning_always_on = flags["reasoning_always_on"]
+ backend._reasoning_style = flags["reasoning_style"]
+ backend._reasoning_effort_levels = flags["reasoning_effort_levels"]
+ backend._supports_preserve_thinking = False
+ backend._chat_template = template
+ return backend
+
+
+ ("enable_thinking", "effort", "expected"),
+ [
+ (None, "low", "high"),
+ (None, "medium", "high"),
+ (None, "minimal", "high"),
+ (None, "max", "high"),
+ (None, "xhigh", "high"),
+ (None, "none", "none"),
+ (True, None, "high"),
+ (False, None, "none"),
+ ],
+)
+def test_gguf_request_effort_is_fitted_to_the_allowlist(enable_thinking, effort, expected):
+ backend = _gguf_backend(MISTRAL_SMALL_4_TEMPLATE)
+ assert backend._request_reasoning_kwargs(enable_thinking, effort, None) == {
+ "reasoning_effort": expected
+ }
+
+
+def test_gguf_launch_default_with_thinking_off_is_none():
+ backend = _gguf_backend(MISTRAL_SMALL_4_TEMPLATE)
+ assert backend._reasoning_kwargs(False) == {"reasoning_effort": "none"}
+ assert backend._reasoning_kwargs(True, "medium") == {"reasoning_effort": "high"}
+
+
+def test_gguf_effort_without_an_allowlist_passes_through():
+ backend = _gguf_backend(GPT_OSS_TEMPLATE)
+ assert backend._request_reasoning_kwargs(None, "low", None) == {"reasoning_effort": "low"}
+ assert backend._request_reasoning_kwargs(False, None, None) == {"reasoning_effort": "low"}
+
+
+def test_gguf_override_allowlist_wins_over_the_embedded_template():
+ backend = _gguf_backend(GPT_OSS_TEMPLATE)
+ backend._chat_template_override = MISTRAL_SMALL_4_TEMPLATE
+ assert backend._request_reasoning_kwargs(None, "medium", None) == {"reasoning_effort": "high"}
+
+
+def test_transformers_and_mlx_render_fits_the_effort():
+ from jinja2 import Environment
+ from jinja2.exceptions import TemplateError
+
+ from core.inference.chat_template_helpers import apply_chat_template_for_generation
+
+ def _raise(message):
+ raise TemplateError(message)
+
+ class _Tokenizer:
+ chat_template = (
+ MISTRAL_SMALL_4_TEMPLATE.split("{%- if message")[0] + "{{ reasoning_effort }}"
+ )
+
+ def apply_chat_template(
+ self,
+ messages,
+ *,
+ tokenize = False,
+ add_generation_prompt = True,
+ **kw,
+ ):
+ env = Environment()
+ env.globals["raise_exception"] = _raise
+ return env.from_string(self.chat_template).render(messages = messages, **kw)
+
+ messages = [{"role": "user", "content": "hi"}]
+ rendered = apply_chat_template_for_generation(_Tokenizer(), messages, reasoning_effort = "medium")
+ assert rendered.endswith("high")
+
+
+def _guarded_template(allowed):
+ quoted = ", ".join(f"'{level}'" for level in allowed)
+ return (
+ "{%- if reasoning_effort not in [" + quoted + "] %}"
+ "{{- raise_exception('unsupported reasoning_effort') }}{%- endif %}"
+ "{%- for m in messages %}{{ m['content'] }}{% endfor %}[{{ reasoning_effort }}]"
+ )
+
+
+ ("tool_name", "expected"),
+ [
+ # Sanitizing drops a tool whose name is control markup, so default renders.
+ ("<|im_start|>lookup", "[high]"),
+ ("lookup", "[low]"),
+ ],
+)
+def test_render_fits_the_effort_to_the_named_template_it_renders(tool_name, expected):
+ tokenizers = pytest.importorskip("tokenizers")
+ transformers = pytest.importorskip("transformers")
+
+ from core.inference.chat_template_helpers import apply_chat_template_for_generation
+
+ tokenizer = transformers.PreTrainedTokenizerFast(
+ tokenizer_object = tokenizers.Tokenizer(
+ tokenizers.models.WordLevel({"<unk>": 0}, unk_token = "<unk>")
+ ),
+ unk_token = "<unk>",
+ )
+ tokenizer.add_special_tokens({"additional_special_tokens": ["<|im_start|>"]})
+ tokenizer.chat_template = {
+ "default": _guarded_template(["none", "high"]),
+ "tool_use": _guarded_template(["none", "low"]),
+ }
+ tools = [
+ {
+ "type": "function",
+ "function": {"name": tool_name, "parameters": {"type": "object", "properties": {}}},
+ }
+ ]
+ rendered = apply_chat_template_for_generation(
+ tokenizer,
+ [{"role": "user", "content": "hi"}],
+ tools = tools,
+ reasoning_effort = "high",
+ )
+ assert rendered.endswith(expected)
+
+
@pytest.fixture
def mistral_template_loaded(monkeypatch):
monkeypatch.setattr(inference_routes, "_loaded_chat_template", lambda: MISTRAL_SMALL_4_TEMPLATE)