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.

Train any text or vision LLM as a Clef decision model from Studio, with FastDecisionModel.predict and adapter saves (#12876)

Daniel Han4451666e09d5
diff --git a/scripts/clef_train_bench.py b/scripts/clef_train_bench.py
index 752ff341b05..514b79e0b86 100644
--- a/scripts/clef_train_bench.py
+++ b/scripts/clef_train_bench.py
@@ -6,8 +6,8 @@
python scripts/clef_train_bench.py --model Cloudflare/clef-flash --load-in-4bit --seq-len 8192
python scripts/clef_train_bench.py --model tiny --fast off --dtype fp16
---fast on|off sets UNSLOTH_CLEF_FAST (Unsloth's batched, chunked, checkpointed and compiled head
-vs the per-record head). Whatever the arm, the first batch's head is also run both ways on the same
+--fast on|off sets UNSLOTH_CLEF_FAST (Unsloth's batched, chunked and checkpointed head, compiled
+too under UNSLOTH_CLEF_COMPILE=1, vs the per-record head). Whatever the arm, the first batch's head is also run both ways on the same
hidden states, so `parity` compares the two heads' logits and gradients in this process.
"""
diff --git a/studio/backend/assets/configs/model_defaults/decision/llm_decision_defaults.yaml b/studio/backend/assets/configs/model_defaults/decision/llm_decision_defaults.yaml
new file mode 100644
index 00000000000..5ed84e8785b
--- /dev/null
+++ b/studio/backend/assets/configs/model_defaults/decision/llm_decision_defaults.yaml
@@ -0,0 +1,28 @@
+# A text or vision LLM trained as a decision model (fresh Clef head + LoRA), as scripts/train_decision_from_lm.py.
+
+training:
+ max_seq_length: 4096
+ num_epochs: 1
+ learning_rate: 1e-4
+ batch_size: 8
+ gradient_accumulation_steps: 2
+ warmup_steps: 5
+ max_steps: 0
+ weight_decay: 0.01
+ random_seed: 3407
+ packing: false
+ train_on_completions: false
+ gradient_checkpointing: "unsloth"
+ optim: "adamw_8bit"
+ lr_scheduler_type: "linear"
+
+lora:
+ lora_r: 64
+ lora_alpha: 64
+ lora_dropout: 0.0
+
+logging:
+ enable_wandb: false
+ wandb_project: "decision-finetuning"
+ enable_tensorboard: false
+ log_frequency: 1
diff --git a/studio/backend/core/systemone/catalog.py b/studio/backend/core/systemone/catalog.py
index 049e65e6c2f..cf13a5636d8 100644
--- a/studio/backend/core/systemone/catalog.py
+++ b/studio/backend/core/systemone/catalog.py
@@ -111,7 +111,7 @@ def _owner_outputs() -> Path:
def _fine_tune_in(root: Path, folder_name: str) -> Checkpoint | None:
- from utils.models.model_config import CLEF_MARKERS
+ from utils.models.model_config import clef_folder_kind
from .laya_runtime import is_cached
@@ -125,7 +125,7 @@ def _fine_tune_in(root: Path, folder_name: str) -> Checkpoint | None:
except (OSError, RuntimeError, ValueError):
# A NUL byte or a symlink loop in a caller's name.
return None
- if all((folder / name).is_file() for name in CLEF_MARKERS):
+ if clef_folder_kind(folder) is not None:
checkpoint = Checkpoint(
CLEF_FINE_TUNE_PREFIX + folder_name,
str(folder),
diff --git a/studio/backend/core/systemone/clef_runtime.py b/studio/backend/core/systemone/clef_runtime.py
index 3add0cae7e4..547a6414e10 100644
--- a/studio/backend/core/systemone/clef_runtime.py
+++ b/studio/backend/core/systemone/clef_runtime.py
@@ -11,6 +11,7 @@ own process: unloading ends it and the memory goes with it (as core/inference/st
from __future__ import annotations
+import json
import multiprocessing as mp
import os
import sys
@@ -67,7 +68,14 @@ def _load(folder: str):
if not torch.cuda.is_available():
raise ClefWorkerError("Clef needs an NVIDIA GPU; this machine has none torch can use.")
free, _ = torch.cuda.mem_get_info()
- load_in_4bit = free < _weight_bytes(Path(folder)) * _BF16_HEADROOM
+ path = Path(folder)
+ if (path / "config.json").is_file():
+ load_in_4bit = free < _weight_bytes(path) * _BF16_HEADROOM
+ else:
+ # LoRA adapters over a base LLM: served on the base they trained on (4-bit for QLoRA).
+ saved = path / "unsloth_decision_config.json"
+ config = json.loads(saved.read_text(encoding = "utf-8")) if saved.is_file() else {}
+ load_in_4bit = bool(config.get("load_in_4bit"))
model, processor = FastDecisionModel.from_pretrained(
folder,
max_seq_length = MAX_LENGTH,
@@ -79,54 +87,9 @@ def _load(folder: str):
def _decide(model, tokenizer, state, questions: dict[str, dict[str, Any]]) -> dict[str, Any]:
- import torch
-
- from unsloth.models.clef import encode_record, systemone_answer
- from unsloth.models.decision import QUESTION_TYPES, _clef_amp_dtype, _served_temperatures
-
- encoded = encode_record(
- tokenizer, {"state": state, "questions": questions}, max_length = MAX_LENGTH
- )
- device = next(model.parameters()).device
- ids = torch.tensor([encoded.input_ids], device = device)
- amp_dtype = _clef_amp_dtype(model, device)
- with (
- torch.inference_mode(),
- torch.autocast(device.type, dtype = amp_dtype, enabled = amp_dtype is not None),
- ):
- logits, _ = model(input_ids = ids, attention_mask = torch.ones_like(ids), records = [encoded])
- rows = [
- row[: len(question.option_ids)]
- for question, row in zip(encoded.questions, logits.float().cpu())
- ]
# The trainer's own rule: per type, or per (type, option count) bucket, after any folded scale.
- scales = _served_temperatures(
- model.decision_config,
- rows,
- [{"qtype": QUESTION_TYPES.index(q["type"])} for q in questions.values()],
- )
- answers = {}
- for question, row, scale in zip(encoded.questions, rows, scales):
- probabilities = (row / scale).softmax(-1).tolist()
- answers[question.question_id] = systemone_answer(
- questions[question.question_id], dict(zip(question.option_ids, probabilities))
- )
- return {
- "answers": answers,
- "input_tokens": len(encoded.input_ids),
- "truncated": _truncated(tokenizer, state, questions, encoded),
- }
-
-
-def _truncated(tokenizer, state, questions, encoded) -> bool:
- # A cut state fills the budget exactly, but so does one that fits exactly: one more token of
- # room tells them apart, and is only spent on prompts at the limit.
- if len(encoded.input_ids) < MAX_LENGTH:
- return False
- from unsloth.models.clef import encode_record
-
- record = {"state": state, "questions": questions}
- return len(encode_record(tokenizer, record, max_length = MAX_LENGTH + 1).input_ids) > MAX_LENGTH
+ from unsloth.models.decision import _clef_decide
+ return _clef_decide(model, tokenizer, state, questions, max_length = MAX_LENGTH)
def run_clef_worker(conn, folder: str) -> None:
diff --git a/studio/backend/core/systemone/laya_runtime.py b/studio/backend/core/systemone/laya_runtime.py
index 9b420714a67..b08002fe134 100644
--- a/studio/backend/core/systemone/laya_runtime.py
+++ b/studio/backend/core/systemone/laya_runtime.py
@@ -106,10 +106,14 @@ def _wanted(path: str, subfolder: str | None) -> bool:
def _clef_complete(folder: Path) -> bool:
import json
- from utils.models.model_config import CLEF_MARKERS
+ from utils.models.model_config import clef_folder_kind
- if not all((folder / name).is_file() for name in CLEF_MARKERS):
+ kind = clef_folder_kind(folder)
+ if kind is None:
return False
+ if kind == "adapter":
+ # The base LLM the adapters sit on is fetched by the loader, like any Unsloth LoRA.
+ return (folder / "adapter_model.safetensors").is_file()
index = folder / "model.safetensors.index.json"
if not index.is_file():
return (folder / "model.safetensors").is_file()
diff --git a/studio/backend/core/training/decision_trainer.py b/studio/backend/core/training/decision_trainer.py
index 051d91d7ed4..f192d107f58 100644
--- a/studio/backend/core/training/decision_trainer.py
+++ b/studio/backend/core/training/decision_trainer.py
@@ -19,6 +19,8 @@ logger = get_logger(__name__)
EVAL_MAX = 2000
MIN_REPORTED_ITEMS = 50
+# The from-LM recipe's head rate (scripts/train_decision_from_lm.py --head-lr).
+FRESH_HEAD_LEARNING_RATE = 3e-4
STRUCT_COLUMNS_WARNING = (
"The state, questions or gold columns are stored as objects rather than JSON strings, so "
"missing fields come back as nulls and choice options can change order. Store them as JSON "
@@ -306,7 +308,9 @@ def _run(event_queue: Any, stop_queue: Any, config: dict, output_dir: str) -> No
model_name = config["model_name"]
subfolder = config.get("model_subfolder") or None
- clef = config.get("decision_layout") == "clef"
+ # "llm": a plain text or vision LLM that gets a fresh Clef joint schema head.
+ llm = config.get("decision_layout") == "llm"
+ clef = llm or config.get("decision_layout") == "clef"
hf_token = _worker_hf_token(config)
if hf_token:
os.environ["HF_TOKEN"] = hf_token
@@ -315,32 +319,44 @@ def _run(event_queue: Any, stop_queue: Any, config: dict, output_dir: str) -> No
gradient_checkpointing = normalize_gradient_checkpointing(config["gradient_checkpointing"])
status("Loading decision model...")
- try:
- root = laya_runtime._checkpoint_dir(
- Checkpoint("base", model_name, subfolder, "", layout = "clef" if clef else "laya")
+ if llm:
+ model, tokenizer = FastDecisionModel.from_pretrained(
+ model_name,
+ decision_head = "clef",
+ max_seq_length = config.get("max_seq_length") or None,
+ load_in_4bit = use_lora and bool(config.get("load_in_4bit")),
+ full_finetuning = not use_lora,
+ token = hf_token or None,
+ use_gradient_checkpointing = gradient_checkpointing,
+ random_state = seed,
+ )
+ else:
+ try:
+ root = laya_runtime._checkpoint_dir(
+ Checkpoint("base", model_name, subfolder, "", layout = "clef" if clef else "laya")
+ )
+ except LocalEntryNotFoundError as exc:
+ send("error", error = f"Could not download {model_name}: {exc}", stack = "")
+ return
+ except FileNotFoundError as exc:
+ kind = "Clef" if clef else "Laya"
+ send("error", error = f"Not a {kind} decision checkpoint: {exc}", stack = "")
+ return
+ model, tokenizer = FastDecisionModel.from_pretrained(
+ str(root),
+ subfolder = subfolder,
+ full_finetuning = not use_lora,
+ use_gradient_checkpointing = gradient_checkpointing,
+ # Clef trains through Unsloth's Qwen3.5 loader, in 4-bit for QLoRA; Laya is always 16-bit.
+ **(
+ {
+ "load_in_4bit": use_lora and bool(config.get("load_in_4bit")),
+ "max_seq_length": config.get("max_seq_length") or None,
+ }
+ if clef
+ else {}
+ ),
)
- except LocalEntryNotFoundError as exc:
- send("error", error = f"Could not download {model_name}: {exc}", stack = "")
- return
- except FileNotFoundError as exc:
- kind = "Clef" if clef else "Laya"
- send("error", error = f"Not a {kind} decision checkpoint: {exc}", stack = "")
- return
- model, tokenizer = FastDecisionModel.from_pretrained(
- str(root),
- subfolder = subfolder,
- full_finetuning = not use_lora,
- use_gradient_checkpointing = gradient_checkpointing,
- # Clef trains through Unsloth's Qwen3.5 loader, in 4-bit for QLoRA; Laya is always 16-bit.
- **(
- {
- "load_in_4bit": use_lora and bool(config.get("load_in_4bit")),
- "max_seq_length": config.get("max_seq_length") or None,
- }
- if clef
- else {}
- ),
- )
if use_lora:
model = FastDecisionModel.get_peft_model(
model,
@@ -462,6 +478,8 @@ def _run(event_queue: Any, stop_queue: Any, config: dict, output_dir: str) -> No
train_dataset = items,
eval_dataset = eval_items or None,
processing_class = tokenizer,
+ # A fresh head starts from random weights, so it learns faster than a trained Clef head.
+ head_learning_rate = FRESH_HEAD_LEARNING_RATE if llm else None,
callbacks = [
_create_embedding_progress_callback(
event_queue,
@@ -493,6 +511,7 @@ def _run(event_queue: Any, stop_queue: Any, config: dict, output_dir: str) -> No
model.decision_config["training"] = {
"base": model_name,
"subfolder": subfolder,
+ "decision_head": "clef (new)" if llm else None,
"method": ("qlora" if clef and config.get("load_in_4bit") else "lora")
if use_lora
else "full",
diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index 6f3988d4321..317012ff9f3 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -3490,7 +3490,8 @@ def _download_decision_checkpoint(event_queue: Any, config: dict) -> None:
from utils.paths import is_local_path
model_name = config["model_name"]
- if is_local_path(model_name):
+ # An LLM that gets a new decision head downloads through FastModel's own loader in the trainer.
+ if is_local_path(model_name) or config.get("decision_layout") == "llm":
return
hf_token = _worker_hf_token(config)
if hf_token:
@@ -3713,7 +3714,7 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
# Clef decision models are Qwen3.5 backbones and need the same gated-delta / conv kernels.
if (
not config.get("is_decision")
- or config.get("decision_layout") == "clef"
+ or config.get("decision_layout") in ("clef", "llm")
or _decision_has_llm_backbone(model_load_target, _worker_hf_token(config))
):
try:
diff --git a/studio/backend/models/models.py b/studio/backend/models/models.py
index b614e8a4936..49026d3bf9d 100644
--- a/studio/backend/models/models.py
+++ b/studio/backend/models/models.py
@@ -92,8 +92,9 @@ class ModelDetails(BaseModel):
False, description = "Whether model is an embedding/sentence-transformer model"
)
is_decision: bool = Field(False, description = "Whether model is a decision model")
- decision_layout: Optional[Literal["laya", "clef"]] = Field(
- None, description = "Checkpoint layout of a decision model: Laya or Cloudflare Clef"
+ decision_layout: Optional[Literal["laya", "clef", "llm"]] = Field(
+ None,
+ description = "Decision model layout: Laya, Cloudflare Clef, or llm for an LLM trained with a new Clef head",
)
decision_checkpoints: Optional[List[Dict[str, Any]]] = Field(
None, description = "Checkpoints a decision model repo offers for training"
diff --git a/studio/backend/models/training.py b/studio/backend/models/training.py
index a1a67d3d8a0..6a4a2282766 100644
--- a/studio/backend/models/training.py
+++ b/studio/backend/models/training.py
@@ -585,11 +585,14 @@ class TrainingStartRequest(BaseModel):
is_embedding: bool = Field(
False, description = "Whether model is an embedding/sentence-transformer model"
)
- is_decision: bool = Field(False, description = "Whether model is a decision model (Laya or Clef)")
+ is_decision: bool = Field(
+ False,
+ description = "Train a decision model: a Laya or Clef checkpoint, or an LLM with a new Clef head",
+ )
model_subfolder: Optional[str] = Field(
None, description = "Checkpoint subfolder of a decision model repo"
)
- decision_layout: Optional[Literal["laya", "clef"]] = Field(
+ decision_layout: Optional[Literal["laya", "clef", "llm"]] = Field(
None,
description = "Set by the server from the checkpoint files; a caller's value is replaced",
)
diff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.py
index 854b88f7b08..02e8842c5fc 100644
--- a/studio/backend/routes/models.py
+++ b/studio/backend/routes/models.py
@@ -2417,12 +2417,15 @@ async def get_model_config(
hf_token: Optional[str] = Query(None),
prefer_local_cache: bool = False,
local_path: Optional[str] = None,
+ as_decision: bool = False,
header_hf_token: Optional[str] = Depends(get_hf_token),
allow_ambient_token: bool = Depends(allow_ambient_hf_token),
current_subject: str = Depends(get_current_subject),
via_api_key: bool = Depends(authenticated_via_api_key),
):
- """Get configuration for a specific model (wraps load_model_defaults)."""
+ """Get configuration for a specific model (wraps load_model_defaults).
+
+ ``as_decision`` asks for a text or vision LLM as a decision model: a fresh Clef head on it."""
# An API-key caller is shown a filesystem-backed row under an opaque `ref:` handle and hands
# it back here, where it would otherwise read as a Hugging Face id.
from core.inference.npu_backend import is_npu_model_path
@@ -2554,6 +2557,15 @@ async def get_model_config(
except Exception:
pass
+ if (
+ as_decision
+ and not is_decision
+ and not (is_embedding or is_lora or audio_type is not None)
+ ):
+ from utils.models.model_config import load_llm_decision_defaults
+ is_decision, layout = True, "llm"
+ config_dict = load_llm_decision_defaults()
+
logger.info(
f"Model config result for {model_name}: is_vision={is_vision}, is_embedding={is_embedding}, audio_type={audio_type}, audio_type_known={audio_type_definitive}, is_lora={is_lora}, max_position_embeddings={max_position_embeddings}"
)
diff --git a/studio/backend/routes/training.py b/studio/backend/routes/training.py
index bf85643ad3a..6a76ce16713 100644
--- a/studio/backend/routes/training.py
+++ b/studio/backend/routes/training.py
@@ -919,6 +919,11 @@ def _authorize_cache_fallback(model_name: str, repo_type: str = "model") -> None
account_access.require_model_access(reference, repo_type)
+def _is_decision_checkpoint(request: TrainingStartRequest) -> bool:
+ # A Laya or Clef checkpoint, not an LLM that is trained with a new decision head.
+ return bool(request.is_decision) and request.decision_layout != "llm"
+
+
def _reject_untrainable_model_request(
request: TrainingStartRequest,
actual_model_repo_id: Optional[str] = None,
@@ -1043,7 +1048,7 @@ def _reject_untrainable_model_request(
)
refuse_unauthorized_cache(has_cached_model)
- if request.is_decision:
+ if _is_decision_checkpoint(request):
from core.systemone import laya_runtime
from core.systemone.catalog import Checkpoint
@@ -1086,7 +1091,7 @@ def _reject_untrainable_model_request(
# A decision checkpoint is checked at its subfolder below, whatever the repo root holds.
remote_format = (
None
- if request.is_decision
+ if _is_decision_checkpoint(request)
else _remote_untrainable_model_format(
request.model_name,
hf_token,
@@ -1115,7 +1120,7 @@ def _reject_untrainable_model_request(
)
else:
if remote_format is None:
- if request.is_decision and not is_decision_model(
+ if _is_decision_checkpoint(request) and not is_decision_model(
request.model_name, hf_token, subfolder = request.model_subfolder
):
raise _training_start_error(
@@ -1135,7 +1140,7 @@ def _reject_untrainable_model_request(
"training_remote_model_adapter_only",
"Adapter models are inference-only and cannot be trained as base models.",
)
- if request.is_decision:
+ if _is_decision_checkpoint(request):
folder = path / request.model_subfolder if request.model_subfolder else path
if not is_decision_model(str(folder)):
raise _training_start_error(
@@ -1143,7 +1148,8 @@ def _reject_untrainable_model_request(
"training_local_model_not_decision",
"The selected model is not a decision checkpoint: Laya needs "
"rl_agent_config.json, model.safetensors, encoder/ and tokenizer/, and Clef "
- "needs config.json, joint_head.safetensors and joint_head_config.json.",
+ "needs joint_head.safetensors and joint_head_config.json beside config.json "
+ "(or LoRA adapters).",
)
return _ModelPreflightResult(model_name, model_local_path, None)
has_trainable_weights = _has_trainable_local_weights(path, request.model_name)
@@ -1265,12 +1271,25 @@ def _validate_decision_request(request: TrainingStartRequest, via_api_key: bool
hf_token_arg(request.hf_token, allow_ambient_token = via_api_key is not True),
subfolder = request.model_subfolder,
)
- if layout == "clef":
+ # A subfolder or a catalog repo still means Laya, so an uncached Laya checkpoint is not loaded as an LLM.
+ llm = (
+ layout is None
+ and request.model_subfolder is None
+ and request.model_name not in {c.source for c in CHECKPOINTS.values()}
+ )
+ if layout == "clef" or llm:
from core.systemone.catalog import clef_unsupported_reason
+ from utils.hardware import hardware
+ # Runs before _validate_training_platform: name the MLX limit, not a missing GPU.
+ if hardware.get_device() == hardware.DeviceType.MLX:
+ raise HTTPException(
+ status_code = 400,
+ detail = "Decision model training is not supported for MLX training yet.",
+ )
if (reason := clef_unsupported_reason()) is not None:
raise HTTPException(status_code = 400, detail = reason)
- request.decision_layout = "clef"
+ request.decision_layout = "llm" if llm else "clef"
if request.model_subfolder is not None:
raise HTTPException(
status_code = 400,
@@ -1282,9 +1301,13 @@ def _validate_decision_request(request: TrainingStartRequest, via_api_key: bool
detail = "Decision models train with plain LoRA, so DoRA and LoftQ are not "
"available for them.",
)
- defaults = load_model_defaults(request.model_name)
- if defaults == load_model_defaults("default"):
- defaults = load_model_defaults(CLEF_DEFAULTS_REPO)
+ if llm:
+ from utils.models.model_config import load_llm_decision_defaults
+ defaults = load_llm_decision_defaults()
+ else:
+ defaults = load_model_defaults(request.model_name)
+ if defaults == load_model_defaults("default"):
+ defaults = load_model_defaults(CLEF_DEFAULTS_REPO)
for section in ("training", "lora", "logging"):
for key, value in (defaults.get(section) or {}).items():
if key in unset:
diff --git a/studio/backend/tests/test_decision_serving.py b/studio/backend/tests/test_decision_serving.py
index 069da20101c..333bdba62cb 100644
--- a/studio/backend/tests/test_decision_serving.py
+++ b/studio/backend/tests/test_decision_serving.py
@@ -6,7 +6,6 @@ import json
import os
import shutil
import struct
-import sys
import time
from types import SimpleNamespace
@@ -364,6 +363,25 @@ def test_a_clef_fine_tune_serves_through_its_worker(home, client, clef):
assert clef.agents[1].closed
+def test_an_adapter_clef_fine_tune_serves_through_its_worker(home, client, clef):
+ # FastDecisionModel.save_pretrained: LoRA adapters plus the Clef head over the base LLM.
+ path = home / "qwen_decisions_1"
+ path.mkdir(parents = True)
+ for name in ("adapter_config.json", "joint_head.safetensors", "joint_head_config.json"):
+ (path / name).write_text("{}", encoding = "utf-8")
+ served = catalog.CLEF_FINE_TUNE_PREFIX + "qwen_decisions_1"
+ # Not complete until the adapter weights are there.
+ assert _listed(client) == []
+ (path / "adapter_model.safetensors").write_bytes(b"")
+ assert _listed(client) == [served]
+ assert _put(client, enabled = True, model = served).status_code == 200
+
+ answer = _post(client).json()
+ assert answer["model"] == served
+ assert answer["answers"]["urgent"] == {"type": "noul", "noul": 0.25}
+ assert clef.agents[0].folder == path.resolve() or str(clef.agents[0].folder) == str(path)
+
+
def test_a_clef_load_that_training_overtakes_frees_the_gpu(home, clef, monkeypatch):
from core.systemone import clef_runtime
@@ -566,25 +584,3 @@ def test_a_clef_worker_that_died_after_loading_is_a_worker_error():
with pytest.raises(clef_runtime.ClefWorkerError, match = "exited"):
_clef_agent(Conn()).decide("state", {})
-
-
-def test_a_clef_prompt_that_fits_exactly_is_not_truncated(monkeypatch):
- import types
-
- from core.systemone import clef_runtime
-
- def encode(tokenizer, record, max_length):
- # The state needs `natural` tokens; anything over max_length is cut to fit.
- return SimpleNamespace(input_ids = [0] * min(record["state"], max_length))
-
- # Studio's backend CI has no unsloth_zoo, so the real module may not import: stand it in.
- for name in ("unsloth", "unsloth.models"):
- monkeypatch.setitem(sys.modules, name, types.ModuleType(name))
- monkeypatch.setitem(sys.modules, "unsloth.models.clef", SimpleNamespace(encode_record = encode))
- size = clef_runtime.MAX_LENGTH
-
- def truncated(natural):
- encoded = encode(None, {"state": natural}, size)
- return clef_runtime._truncated(None, natural, {}, encoded)
-
- assert (truncated(size - 1), truncated(size), truncated(size + 1)) == (False, False, True)
diff --git a/studio/backend/tests/test_decision_training.py b/studio/backend/tests/test_decision_training.py
index 8bdcc1e01f4..4f3e1e10694 100644
--- a/studio/backend/tests/test_decision_training.py
+++ b/studio/backend/tests/test_decision_training.py
@@ -520,6 +520,38 @@ def test_llm_output_scans_skip_decision_outputs(studio_home):
assert [name for name, _, _ in scan_checkpoints(str(root))] == ["llama_merged_1"]
+def test_model_config_offers_an_llm_as_a_decision_model(studio_home):
+ import asyncio
+
+ from routes.models import get_model_config
+ from utils.models.model_config import load_llm_decision_defaults
+
+ llm = studio_home / "llm"
+ llm.mkdir()
+ config = {
+ "model_type": "llama",
+ "architectures": ["LlamaForCausalLM"],
+ "hidden_size": 64,
+ "num_hidden_layers": 2,
+ "num_attention_heads": 4,
+ "vocab_size": 64,
+ }
+ (llm / "config.json").write_text(json.dumps(config), encoding = "utf-8")
+ (llm / "model.safetensors").write_bytes(b"x")
+
+ def fetch(**kwargs):
+ return asyncio.run(
+ get_model_config(model_name = str(llm), hf_token = None, current_subject = "tester", **kwargs)
+ )
+
+ plain = fetch()
+ assert plain.model_type == "text" and plain.decision_layout is None
+ decision = fetch(as_decision = True)
+ assert decision.model_type == "decision" and decision.is_decision is True
+ assert decision.decision_layout == "llm" and decision.decision_checkpoints is None
+ assert decision.config == load_llm_decision_defaults()
+
+
def test_model_config_classifies_a_local_laya_folder(base):
import asyncio
diff --git a/studio/backend/tests/test_decision_training_route.py b/studio/backend/tests/test_decision_training_route.py
index 7bf0cdefd3b..e776a876d7e 100644
--- a/studio/backend/tests/test_decision_training_route.py
+++ b/studio/backend/tests/test_decision_training_route.py
@@ -3,6 +3,7 @@
import asyncio
import importlib.util
+import json
import os
import sys
import threading
@@ -359,19 +360,90 @@ def test_a_local_checkpoint_is_checked_at_its_subfolder(route, tmp_path):
assert refused.value.detail["code"] == "training_local_model_not_decision"
-def test_a_local_llm_is_not_trained_as_a_decision_model(route, tmp_path):
- llm = tmp_path / "llm"
- llm.mkdir()
- (llm / "config.json").write_text("{}", encoding = "utf-8")
- (llm / "model.safetensors").write_bytes(b"x")
+def _llm_folder(folder: Path) -> Path:
+ folder.mkdir(parents = True)
+ config = {"model_type": "llama", "architectures": ["LlamaForCausalLM"], "hidden_size": 64}
+ (folder / "config.json").write_text(json.dumps(config), encoding = "utf-8")
+ (folder / "model.safetensors").write_bytes(b"x")
+ return folder
- with pytest.raises(HTTPException) as refused:
- route._reject_untrainable_model_request(_request(model_name = str(llm)))
+def test_a_local_llm_is_only_a_decision_checkpoint_when_validated_as_an_llm(route, tmp_path):
+ llm = _llm_folder(tmp_path / "llm")
+
+ # A caller's layout claim is not what makes an LLM pass: its validated layout is.
+ with pytest.raises(HTTPException) as refused:
+ route._reject_untrainable_model_request(
+ _request(model_name = str(llm), decision_layout = "laya")
+ )
assert refused.value.status_code == 400
assert refused.value.detail["code"] == "training_local_model_not_decision"
+def test_an_llm_trains_as_a_decision_model_with_a_new_clef_head(route, device, tmp_path):
+ from utils.models.model_config import load_llm_decision_defaults
+
+ llm = _llm_folder(tmp_path / "llm")
+ request = _request(model_name = str(llm), decision_layout = "laya")
+ route._validate_decision_request(request)
+ assert request.decision_layout == "llm"
+ assert route._reject_untrainable_model_request(request).model_name == str(llm.resolve())
+
+ config = _started_config(route, _request(model_name = str(llm), load_in_4bit = True))
+ recipe = load_llm_decision_defaults()
+ assert config["decision_layout"] == "llm"
+ # QLoRA works for an LLM, unlike Laya.
+ assert config["load_in_4bit"] is True
+ assert float(config["learning_rate"]) == float(recipe["training"]["learning_rate"])
+ assert config["max_seq_length"] == recipe["training"]["max_seq_length"]
+ assert (config["batch_size"], config["gradient_accumulation_steps"]) == (
+ recipe["training"]["batch_size"],
+ recipe["training"]["gradient_accumulation_steps"],
+ )
+ assert (config["lora_r"], config["lora_alpha"]) == (
+ recipe["lora"]["lora_r"],
+ recipe["lora"]["lora_alpha"],
+ )
+
+ full = _request(model_name = str(llm), training_type = "Full Finetuning")
+ route._validate_decision_request(full)
+ assert full.learning_rate == route._DECISION_FULL_FINETUNING_LR
+
+ with pytest.raises(HTTPException) as refused:
+ route._validate_decision_request(_request(model_name = str(llm), use_dora = True))
+ assert "DoRA" in refused.value.detail
+
+
+def test_a_laya_subfolder_or_catalog_repo_never_becomes_an_llm_run(route, device):
+ from utils.models import model_config
+
+ # Offline or without access the layout is unknown; a subfolder or Laya's repo still means Laya.
+ with patch.object(model_config, "decision_layout", return_value = None):
+ for request in (
+ _request(model_name = "org/decisions", model_subfolder = "multilingual"),
+ _request(model_name = LAYA_REPO, model_subfolder = "multilingual"),
+ _request(model_name = LAYA_REPO),
+ ):
+ route._validate_decision_request(request)
+ assert request.decision_layout == "laya", request.model_name
+
+
[email protected]("kind", ["cpu", "xpu"])
+def test_llm_decision_training_needs_an_nvidia_or_amd_gpu(route, device, tmp_path, kind):
+ from core.systemone.catalog import CLEF_NEEDS_GPU
+
+ device(kind)
+ with pytest.raises(HTTPException) as refused:
+ route._validate_decision_request(_request(model_name = str(_llm_folder(tmp_path / "l"))))
+ assert (refused.value.status_code, refused.value.detail) == (400, CLEF_NEEDS_GPU)
+
+
+def test_a_plain_request_carries_no_decision_layout(route):
+ request = _request(is_decision = False, model_name = "org/llm", decision_layout = "llm")
+ route._validate_decision_request(request)
+ assert request.decision_layout is None
+
+
def test_a_hub_checkpoint_downloads_under_the_stall_watchdog(monkeypatch, tmp_path):
from core.systemone import laya_runtime
from core.training import worker
@@ -418,6 +490,10 @@ def test_a_hub_checkpoint_downloads_under_the_stall_watchdog(monkeypatch, tmp_pa
events.clear()
worker._download_decision_checkpoint(queue, {"model_name": str(tmp_path)})
+ # An LLM that gets a new head downloads through FastModel in the trainer.
+ worker._download_decision_checkpoint(
+ queue, {"model_name": "unsloth/Qwen3.5-0.8B", "decision_layout": "llm"}
+ )
assert events == [] and len(downloads) == 1
diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.py
index 0e5329ffe16..c326be46243 100644
--- a/studio/backend/utils/models/model_config.py
+++ b/studio/backend/utils/models/model_config.py
@@ -3752,12 +3752,27 @@ def is_embedding_model(model_name: str, hf_token: Optional[str] = None) -> bool:
_LAYA_MARKER = "rl_agent_config.json"
-# Cloudflare's Clef layout: a Qwen3.5 backbone plus the joint schema head.
-CLEF_MARKERS = ("config.json", "joint_head.safetensors", "joint_head_config.json")
+# Clef: a backbone (merged, or LoRA adapters over the base LLM) plus the joint schema head.
+CLEF_HEAD_MARKERS = ("joint_head.safetensors", "joint_head_config.json")
+CLEF_MARKERS = ("config.json", *CLEF_HEAD_MARKERS)
+CLEF_ADAPTER_MARKERS = ("adapter_config.json", *CLEF_HEAD_MARKERS)
+
+
+def clef_files_kind(has) -> Optional[str]:
+ """ "merged", "adapter" or None, from has(name) -> bool over a folder's files."""
+ if all(has(name) for name in CLEF_MARKERS):
+ return "merged"
+ if all(has(name) for name in CLEF_ADAPTER_MARKERS):
+ return "adapter"
+ return None
+
+
+def clef_folder_kind(folder: Path) -> Optional[str]:
+ return clef_files_kind(lambda name: (folder / name).is_file())
def _folder_decision_layout(folder: Path) -> Optional[str]:
- if all((folder / name).is_file() for name in CLEF_MARKERS):
+ if clef_folder_kind(folder) is not None:
return "clef"
if all((folder / name).is_file() for name in (_LAYA_MARKER, "model.safetensors")) and all(
(folder / name).is_dir() for name in ("encoder", "tokenizer")
@@ -3787,7 +3802,7 @@ def decision_layout(
try:
info = _hub_model_info(model_name, hf_token)
files = {getattr(sibling, "rfilename", None) for sibling in info.siblings or ()}
- if all(prefix + name in files for name in CLEF_MARKERS):
+ if clef_files_kind(lambda name: prefix + name in files) is not None:
return "clef"
return "laya" if prefix + _LAYA_MARKER in files else None
except Exception as e:
@@ -3797,7 +3812,7 @@ def decision_layout(
snapshot = hf_cache_snapshot_dir(model_name)
if snapshot is None:
return None
- if all((snapshot / prefix / name).is_file() for name in CLEF_MARKERS):
+ if clef_folder_kind(snapshot / prefix) is not None:
return "clef"
# The Decision API caches only the checkpoint subfolder it serves.
laya = (snapshot / _LAYA_MARKER, *snapshot.glob(f"*/{_LAYA_MARKER}"))
@@ -3813,6 +3828,22 @@ def is_decision_model(
return decision_layout(model_name, hf_token, local_files_only, subfolder) is not None
+LLM_DECISION_DEFAULTS = (
+ Path(__file__).parent.parent.parent
+ / "assets"
+ / "configs"
+ / "model_defaults"
+ / "decision"
+ / "llm_decision_defaults.yaml"
+)
+
+
+def load_llm_decision_defaults() -> Dict[str, Any]:
+ """The recipe for training a text or vision LLM as a decision model (a new Clef head)."""
+ with open(LLM_DECISION_DEFAULTS, "r", encoding = "utf-8") as f:
+ return yaml.safe_load(f) or {}
+
+
def _has_model_weight_files(model_dir: Path) -> bool:
"""Return True when a directory contains loadable model weights."""
diff --git a/studio/frontend/src/features/studio/wizard/training-wizard.tsx b/studio/frontend/src/features/studio/wizard/training-wizard.tsx
index c5af34b8c15..cfd09fec77c 100644
--- a/studio/frontend/src/features/studio/wizard/training-wizard.tsx
+++ b/studio/frontend/src/features/studio/wizard/training-wizard.tsx
@@ -166,8 +166,11 @@ function TrainingMethodSelect() {
const trainingMethod = useTrainingConfigStore((s) => s.trainingMethod);
const setTrainingMethod = useTrainingConfigStore((s) => s.setTrainingMethod);
const isDecision = useTrainingConfigStore((s) => s.modelType === "decision");
- const isClef = useTrainingConfigStore(
- (s) => s.modelType === "decision" && s.decisionLayout === "clef",
+ // Clef and LLM decision models have an LLM backbone, so they take QLoRA; Laya does not.
+ const decisionTakesQlora = useTrainingConfigStore(
+ (s) =>
+ s.modelType === "decision" &&
+ (s.decisionLayout === "clef" || s.decisionLayout === "llm"),
);
const deviceType = usePlatformStore((state) => state.deviceType);
const activeMeta = TRAINING_METHOD_META[trainingMethod];
@@ -210,7 +213,7 @@ function TrainingMethodSelect() {
!isDecision ||
method === "lora" ||
method === "full" ||
- (isClef && method === "qlora"),
+ (decisionTakesQlora && method === "qlora"),
).map((method) => {
const meta = TRAINING_METHOD_META[method];
const unsupportedOnMlx = !isTrainingMethodSupportedOnDevice(
@@ -255,6 +258,47 @@ function TrainingMethodSelect() {
);
}
+function TrainAsSelect() {
+ const t = useT();
+ const trainAsDecision = useTrainingConfigStore((s) => s.trainAsDecision);
+ const setTrainAsDecision = useTrainingConfigStore(
+ (s) => s.setTrainAsDecision,
+ );
+ const value = trainAsDecision ? "decision" : "language";
+ const label = (option: string) =>
+ option === "decision"
+ ? t("studio.wizard.trainAsDecision")
+ : t("studio.wizard.trainAsLanguage");
+ return (
+ <Select
+ value={value}
+ onValueChange={(next) => setTrainAsDecision(next === "decision")}
+ >
+ <SelectTrigger
+ aria-label={`${t("studio.wizard.trainAsLabel")}: ${label(value)}`}
+ className={cn(PICKER_TRIGGER_CLASS, "w-full justify-between")}
+ >
+ <span className="truncate font-medium text-foreground">
+ {label(value)}
+ </span>
+ </SelectTrigger>
+ <SelectContent
+ position="popper"
+ side="bottom"
+ align="start"
+ sideOffset={8}
+ className="rounded-[14px] ring-0"
+ >
+ {["language", "decision"].map((option) => (
+ <SelectItem key={option} value={option}>
+ {label(option)}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ );
+}
+
function CheckpointSelect({
checkpoints,
}: {
@@ -311,6 +355,14 @@ function ModelPanel() {
const decisionCheckpoints = useTrainingConfigStore((s) =>
s.modelType === "decision" ? s.decisionCheckpoints : null,
);
+ // Text and vision LLMs can also train as decision models; Laya, Clef, audio and embeddings cannot.
+ const canTrainAsDecision = useTrainingConfigStore(
+ (s) =>
+ s.selectedModel !== null &&
+ (s.decisionLayout === "llm" ||
+ s.modelType === "text" ||
+ s.modelType === "vision"),
+ );
return (
<div className="grid grid-cols-1 gap-4 @md/train-section:grid-cols-2 @2xl/train-section:grid-cols-[minmax(0,1fr)_180px_200px]">
<div className="@md/train-section:col-span-2 @2xl/train-section:col-span-1">
@@ -336,6 +388,14 @@ function ModelPanel() {
onOpenSettings={() => openSettings("general")}
/>
</SetupField>
+ {canTrainAsDecision ? (
+ <SetupField
+ label={t("studio.wizard.trainAsLabel")}
+ hint={t("studio.wizard.trainAsTooltip")}
+ >
+ <TrainAsSelect />
+ </SetupField>
+ ) : null}
{decisionCheckpoints && decisionCheckpoints.length > 0 ? (
<SetupField
label={t("studio.wizard.checkpointLabel")}
diff --git a/studio/frontend/src/features/training/api/mappers.ts b/studio/frontend/src/features/training/api/mappers.ts
index cfd1f0f8064..1687bc06e7c 100644
--- a/studio/frontend/src/features/training/api/mappers.ts
+++ b/studio/frontend/src/features/training/api/mappers.ts
@@ -55,11 +55,14 @@ export function buildTrainingStartPayload(
hfToken: string | null,
): TrainingStartRequest {
const isDecision = config.modelType === "decision";
- const isClef = isDecision && config.decisionLayout === "clef";
+ // Laya trains in 16-bit (LoRA or full); Clef and an LLM decision model also take QLoRA.
+ const hasLlmBackbone =
+ isDecision &&
+ (config.decisionLayout === "clef" || config.decisionLayout === "llm");
const trainingMethod =
isDecision &&
config.trainingMethod !== "full" &&
- !(isClef && config.trainingMethod === "qlora")
+ !(hasLlmBackbone && config.trainingMethod === "qlora")
? "lora"
: config.trainingMethod;
const isCpt = trainingMethod === "cpt";
@@ -107,8 +110,8 @@ export function buildTrainingStartPayload(
model_local_path: config.modelKnownCached ? config.modelLocalPath : null,
model_format: config.modelFormat,
load_in_4bit: trainingLoadsIn4Bit({ ...config, trainingMethod }),
- // Hidden for decision runs: Laya always trains at 1024 tokens, Clef at its recipe's length.
- max_seq_length: isDecision && !isClef ? 1024 : config.contextLength,
+ // Hidden for decision runs: Laya always trains at 1024 tokens, Clef and LLMs at the recipe's length.
+ max_seq_length: isDecision && !hasLlmBackbone ? 1024 : config.contextLength,
vision_image_size:
config.isVisionModel && config.isDatasetImage === true && !isDeepseekOcr
? config.visionImageSize
diff --git a/studio/frontend/src/features/training/api/models-api.ts b/studio/frontend/src/features/training/api/models-api.ts
index 42b9449bf81..0cc9f1c5cf4 100644
--- a/studio/frontend/src/features/training/api/models-api.ts
+++ b/studio/frontend/src/features/training/api/models-api.ts
@@ -81,7 +81,7 @@ export interface ModelConfigResponse {
is_embedding?: boolean;
is_decision?: boolean;
decision_checkpoints?: DecisionCheckpoint[] | null;
- decision_layout?: "laya" | "clef" | null;
+ decision_layout?: DecisionLayout | null;
is_audio: boolean;
// False when the repo's tokenizer_config.json was unreadable (gated, offline,
// upstream error), so is_audio false means unknown rather than "not audio".
@@ -93,9 +93,21 @@ export interface ModelConfigResponse {
model_size_bytes?: number | null;
}
+// laya: a Laya checkpoint. clef: Cloudflare Clef. llm: a text or vision LLM trained with a Clef decision head.
+export type DecisionLayout = "laya" | "clef" | "llm";
+
+/** Clef and LLM decision runs have an LLM backbone, so they take QLoRA and the recipe's context; Laya is 16-bit at 1024 tokens. */
+export function decisionLayoutHasLlmBackbone(
+ layout: DecisionLayout | null | undefined,
+): boolean {
+ return layout === "clef" || layout === "llm";
+}
+
export interface ModelConfigRequestOptions {
preferLocalCache?: boolean;
localPath?: string | null;
+ // Ask for an LLM's defaults as a decision model; Laya and Clef are decision models anyway.
+ asDecision?: boolean;
}
export interface LocalModelInfo {
@@ -163,6 +175,9 @@ export async function getModelConfig(
if (options?.localPath) {
params.set("local_path", options.localPath);
}
+ if (options?.asDecision) {
+ params.set("as_decision", "true");
+ }
const query = params.toString();
const response = await authFetch(
`/api/models/config/${encoded}${query ? `?${query}` : ""}`,
diff --git a/studio/frontend/src/features/training/stores/training-config-persistence.ts b/studio/frontend/src/features/training/stores/training-config-persistence.ts
index 27ed53f7d0a..1b2b622dfc1 100644
--- a/studio/frontend/src/features/training/stores/training-config-persistence.ts
+++ b/studio/frontend/src/features/training/stores/training-config-persistence.ts
@@ -445,6 +445,7 @@ export function mergeTrainingConfig(
settingsBeforeDecision: normalizeSettingsBeforeDecision(
persistedState.settingsBeforeDecision,
),
+ trainAsDecision: persistedState.trainAsDecision === true,
};
return {
...merged,
diff --git a/studio/frontend/src/features/training/stores/training-config-policy.ts b/studio/frontend/src/features/training/stores/training-config-policy.ts
index b40f6da211d..23c5147729c 100644
--- a/studio/frontend/src/features/training/stores/training-config-policy.ts
+++ b/studio/frontend/src/features/training/stores/training-config-policy.ts
@@ -61,6 +61,7 @@ export const initialTrainingConfigState: TrainingConfigState = {
modelFormat: null,
modelSubfolder: null,
decisionCheckpoints: null,
+ trainAsDecision: false,
decisionLayout: null,
settingsBeforeDecision: null,
projectName: "",
diff --git a/studio/frontend/src/features/training/stores/training-config-store.ts b/studio/frontend/src/features/training/stores/training-config-store.ts
index 8882a5c1e65..3570e315a2b 100644
--- a/studio/frontend/src/features/training/stores/training-config-store.ts
+++ b/studio/frontend/src/features/training/stores/training-config-store.ts
@@ -15,7 +15,11 @@ import type { ModelType, TrainingMethod } from "@/types/training";
import { create } from "zustand";
import { persist } from "zustand/middleware";
import { DatasetFormatError, checkDatasetFormat } from "../api/datasets-api";
-import { checkVisionModel, getModelConfig } from "../api/models-api";
+import {
+ checkVisionModel,
+ decisionLayoutHasLlmBackbone,
+ getModelConfig,
+} from "../api/models-api";
import type { BackendModelConfig, DecisionCheckpoint } from "../api/models-api";
import { cacheReferenceMatchesSelection } from "../lib/cache-reference";
import {
@@ -77,7 +81,6 @@ export { hasSeparateStreamingEvalSplit } from "./training-config-policy";
// AbortController for in-flight dataset multimodal checks.
let _datasetCheckController: AbortController | null = null;
-
// AbortController for in-flight model default loads.
let _modelConfigController: AbortController | null = null;
@@ -196,8 +199,7 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
const patch = typeof update === "function" ? update(state) : update;
const invariantPatch = datasetSourceInvariantPatch({
datasetSource: patch.datasetSource ?? state.datasetSource,
- datasetStreaming:
- patch.datasetStreaming ?? state.datasetStreaming,
+ datasetStreaming: patch.datasetStreaming ?? state.datasetStreaming,
});
const normalizedPatch = { ...patch, ...invariantPatch };
if (trainingConfigPatchTouchesModelDefaults(normalizedPatch)) {
@@ -249,6 +251,7 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
requestState.selectedModel === modelName
? requestState.modelLocalPath
: null;
+ const requestedAsDecision = requestState.trainAsDecision;
const canApplyTrainingDefaults = () =>
applyTrainingDefaults &&
_modelDefaultsEditGeneration === requestedModelDefaultsEditGeneration;
@@ -276,11 +279,14 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
{
preferLocalCache,
localPath: preferLocalCache ? requestedLocalPath : null,
+ asDecision: requestedAsDecision,
},
)
.then((modelDetails) => {
if (controller.signal.aborted) return;
if (!requestMatchesSelection()) return;
+ // Answered for the other side of the decision switch.
+ if (get().trainAsDecision !== requestedAsDecision) return;
const isDecision = modelDetails.model_type === "decision";
const settingsBeforeDecision = get().settingsBeforeDecision;
@@ -297,16 +303,21 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
const method = get().trainingMethod;
const methodWasEdited =
_trainingMethodEditGeneration !== trainingMethodEditGeneration;
- // Clef has a Qwen3.5 backbone, so it takes QLoRA like a chat model; Laya is 16-bit only.
- const isClef = modelDetails.decision_layout === "clef";
+ // Clef and LLM decision models have an LLM backbone, so they take QLoRA; Laya is 16-bit only.
+ const takesQlora = decisionLayoutHasLlmBackbone(
+ modelDetails.decision_layout,
+ );
const keepMethod =
method === "lora" ||
- (isClef && method === "qlora") ||
+ (takesQlora && method === "qlora") ||
(method === "full" && (!recipeChanged || methodWasEdited));
set({
...(keepMethod
? {}
- : buildTrainingMethodPatch(get(), isClef ? "qlora" : "lora")),
+ : buildTrainingMethodPatch(
+ get(),
+ takesQlora ? "qlora" : "lora",
+ )),
settingsBeforeDecision: settingsBeforeDecision ?? {
trainingMethod: method,
datasetStreaming: get().datasetStreaming,
@@ -355,6 +366,7 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
}
: {}),
modelType: null,
+ decisionLayout: null,
modelFormat: "adapter",
isVisionModel: false,
isEmbeddingModel: false,
@@ -596,6 +608,10 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
decisionLayout: isDecision
? (modelDetails.decision_layout ?? "laya")
: null,
+ // Asked for a decision model the backend cannot make one of (audio, embeddings).
+ ...(requestedAsDecision && !isDecision
+ ? { trainAsDecision: false }
+ : {}),
isVisionModel: modelDetails.is_vision,
isEmbeddingModel: isEmbedding,
isAudioModel: isAudio,
@@ -668,6 +684,10 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
settingsBeforeDecision.trainingMethod,
)
: {}),
+ // The decision switch only holds once the backend answered for it.
+ ...(requestedAsDecision && get().modelType !== "decision"
+ ? { trainAsDecision: false }
+ : {}),
});
if (preferLocalCache) {
@@ -1211,6 +1231,13 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
});
},
setModelSubfolder: (modelSubfolder) => setUserEdit({ modelSubfolder }),
+ setTrainAsDecision: (trainAsDecision) => {
+ if (get().trainAsDecision === trainAsDecision) return;
+ set({ trainAsDecision });
+ const { selectedModel } = get();
+ // Reloading the model's defaults switches the whole recipe, as picking a Laya model does.
+ if (selectedModel) void loadAndApplyModelDefaults(selectedModel);
+ },
setProjectName: (projectName) => setUserEdit({ projectName }),
setTrainingMethod: (trainingMethod) => {
_trainingMethodEditGeneration += 1;
diff --git a/studio/frontend/src/features/training/types/config.ts b/studio/frontend/src/features/training/types/config.ts
index d581cd37736..99a352c29e8 100644
--- a/studio/frontend/src/features/training/types/config.ts
+++ b/studio/frontend/src/features/training/types/config.ts
@@ -10,7 +10,11 @@ import type {
S3Config,
TrainingMethod,
} from "@/types/training";
-import type { BackendModelConfig, DecisionCheckpoint } from "../api/models-api";
+import type {
+ BackendModelConfig,
+ DecisionCheckpoint,
+ DecisionLayout,
+} from "../api/models-api";
export type LoraVariant = "lora" | "rslora" | "loftq" | "dora";
@@ -68,8 +72,10 @@ export interface TrainingConfigState {
modelFormat: ModelInventoryFormat | null;
modelSubfolder: string | null;
decisionCheckpoints: DecisionCheckpoint[] | null;
- /** "clef" for Cloudflare Clef (Qwen3.5 backbone, QLoRA allowed), "laya" otherwise. */
- decisionLayout: "laya" | "clef" | null;
+ // The user's choice to train a text or vision LLM as a decision model.
+ trainAsDecision: boolean;
+ /** "laya" for Laya, "clef" for Cloudflare Clef, "llm" for an LLM trained as a decision model; the last two take QLoRA. */
+ decisionLayout: DecisionLayout | null;
settingsBeforeDecision: {
trainingMethod: TrainingMethod;
datasetStreaming: boolean;
@@ -202,6 +208,7 @@ export interface TrainingConfigActions {
localPath: string | null,
) => void;
setModelSubfolder: (subfolder: string | null) => void;
+ setTrainAsDecision: (value: boolean) => void;
setProjectName: (value: string) => void;
ensureModelDefaultsLoaded: () => void;
ensureDatasetChecked: () => void;
diff --git a/studio/frontend/src/i18n/locales/ar.ts b/studio/frontend/src/i18n/locales/ar.ts
index 1ac5892d365..a1bcca31585 100644
--- a/studio/frontend/src/i18n/locales/ar.ts
+++ b/studio/frontend/src/i18n/locales/ar.ts
@@ -2937,6 +2937,11 @@ export const ar = {
datasetLabel: "مجموعة البيانات",
modelTooltip: "النموذج الأساسي الذي تريد ضبطه.",
methodTooltip: "طريقة تدريب النموذج. يحدّث LoRA وQLoRA محوّلات صغيرة بدلاً من جميع الأوزان.",
+ trainAsLabel: "التدريب كـ",
+ trainAsTooltip:
+ "النموذج اللغوي يكتب نصًا. نموذج القرار يختار أحد الخيارات التي تعطيه إياها مع احتمال، ويعمل في Decision API.",
+ trainAsLanguage: "نموذج لغوي",
+ trainAsDecision: "نموذج قرار",
checkpointLabel: "نقطة التحقق",
checkpointTooltip:
"نقطة تحقق Laya التي سيتم ضبطها. يناسب الإصدار متعدد اللغات معظم مجموعات البيانات.",
diff --git a/studio/frontend/src/i18n/locales/de.ts b/studio/frontend/src/i18n/locales/de.ts
index 4200b143b84..6c7a0ca9310 100644
--- a/studio/frontend/src/i18n/locales/de.ts
+++ b/studio/frontend/src/i18n/locales/de.ts
@@ -2984,6 +2984,11 @@ export const de = {
datasetLabel: "Datensatz",
modelTooltip: "Das Basismodell, das du feinabstimmen möchtest.",
methodTooltip: "Wie das Modell trainiert wird. LoRA und QLoRA aktualisieren kleine Adapter statt aller Gewichte.",
+ trainAsLabel: "Trainieren als",
+ trainAsTooltip:
+ "Ein Sprachmodell schreibt Text. Ein Entscheidungsmodell wählt eine der vorgegebenen Optionen mit einer Wahrscheinlichkeit und läuft in der Decision API.",
+ trainAsLanguage: "Sprachmodell",
+ trainAsDecision: "Entscheidungsmodell",
checkpointLabel: "Checkpoint",
checkpointTooltip:
"Der Laya-Checkpoint, der feinabgestimmt wird. Multilingual passt zu den meisten Datensätzen.",
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index 2ff36f3cac0..bbe9420b60b 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -2970,6 +2970,11 @@ export const en = {
methodLabel: "Method",
methodTooltip:
"How the model is trained. LoRA and QLoRA update small adapters instead of every weight.",
+ trainAsLabel: "Train as",
+ trainAsTooltip:
+ "A language model writes text. A decision model picks one of the options you give it, with a probability, and runs in the Decision API.",
+ trainAsLanguage: "Language model",
+ trainAsDecision: "Decision model",
checkpointLabel: "Checkpoint",
checkpointTooltip:
"The Laya checkpoint to fine-tune. Multilingual suits most datasets.",
diff --git a/studio/frontend/src/i18n/locales/es.ts b/studio/frontend/src/i18n/locales/es.ts
index 5d773514f7c..dc4e73fd546 100644
--- a/studio/frontend/src/i18n/locales/es.ts
+++ b/studio/frontend/src/i18n/locales/es.ts
@@ -2978,6 +2978,11 @@ export const es = {
datasetLabel: "Conjunto de datos",
modelTooltip: "El modelo base que quieres ajustar.",
methodTooltip: "Cómo se entrena el modelo. LoRA y QLoRA actualizan adaptadores pequeños en lugar de todos los pesos.",
+ trainAsLabel: "Entrenar como",
+ trainAsTooltip:
+ "Un modelo de lenguaje escribe texto. Un modelo de decisión elige una de las opciones que le das, con una probabilidad, y funciona en la Decision API.",
+ trainAsLanguage: "Modelo de lenguaje",
+ trainAsDecision: "Modelo de decisión",
checkpointLabel: "Checkpoint",
checkpointTooltip:
"El checkpoint de Laya que se ajustará. Multilingüe sirve para la mayoría de los conjuntos de datos.",
diff --git a/studio/frontend/src/i18n/locales/fr.ts b/studio/frontend/src/i18n/locales/fr.ts
index 77f0bf602f7..be41a892fba 100644
--- a/studio/frontend/src/i18n/locales/fr.ts
+++ b/studio/frontend/src/i18n/locales/fr.ts
@@ -2988,6 +2988,11 @@ export const fr = {
datasetLabel: "Jeu de données",
modelTooltip: "Le modèle de base que vous souhaitez affiner.",
methodTooltip: "Comment le modèle est entraîné. LoRA et QLoRA mettent à jour de petits adaptateurs au lieu de tous les poids.",
+ trainAsLabel: "Entraîner comme",
+ trainAsTooltip:
+ "Un modèle de langage écrit du texte. Un modèle de décision choisit l'une des options que vous lui donnez, avec une probabilité, et fonctionne dans la Decision API.",
+ trainAsLanguage: "Modèle de langage",
+ trainAsDecision: "Modèle de décision",
checkpointLabel: "Checkpoint",
checkpointTooltip:
"Le checkpoint Laya à affiner. Multilingue convient à la plupart des jeux de données.",
diff --git a/studio/frontend/src/i18n/locales/hi.ts b/studio/frontend/src/i18n/locales/hi.ts
index a2d5864e861..88a3f6b9ce5 100644
--- a/studio/frontend/src/i18n/locales/hi.ts
+++ b/studio/frontend/src/i18n/locales/hi.ts
@@ -2945,6 +2945,11 @@ export const hi = {
datasetLabel: "डेटासेट",
modelTooltip: "वह बेस मॉडल जिसे आप फ़ाइन-ट्यून करना चाहते हैं।",
methodTooltip: "मॉडल को कैसे ट्रेन किया जाता है। LoRA और QLoRA सभी वेट्स के बजाय छोटे अडैप्टर अपडेट करते हैं।",
+ trainAsLabel: "इस रूप में ट्रेन करें",
+ trainAsTooltip:
+ "लैंग्वेज मॉडल टेक्स्ट लिखता है। डिसीजन मॉडल आपके दिए विकल्पों में से एक को संभावना के साथ चुनता है और Decision API में चलता है।",
+ trainAsLanguage: "लैंग्वेज मॉडल",
+ trainAsDecision: "डिसीजन मॉडल",
checkpointLabel: "चेकपॉइंट",
checkpointTooltip:
"वह Laya चेकपॉइंट जिसे फ़ाइन-ट्यून करना है। ज़्यादातर डेटासेट के लिए बहुभाषी ठीक रहता है।",
diff --git a/studio/frontend/src/i18n/locales/it.ts b/studio/frontend/src/i18n/locales/it.ts
index 4d34ec2ae8e..badc7d73a40 100644
--- a/studio/frontend/src/i18n/locales/it.ts
+++ b/studio/frontend/src/i18n/locales/it.ts
@@ -2986,6 +2986,11 @@ export const it = {
methodLabel: "Metodo",
methodTooltip:
"Il modo in cui viene addestrato il modello. LoRA e QLoRA aggiornano piccoli adattatori anziché tutti i pesi.",
+ trainAsLabel: "Addestra come",
+ trainAsTooltip:
+ "Un modello linguistico scrive testo. Un modello decisionale sceglie una delle opzioni che gli dai, con una probabilità, e funziona nella Decision API.",
+ trainAsLanguage: "Modello linguistico",
+ trainAsDecision: "Modello decisionale",
checkpointLabel: "Checkpoint",
checkpointTooltip:
"Il checkpoint Laya da sottoporre a fine-tuning. Multilingue va bene per la maggior parte dei dataset.",
diff --git a/studio/frontend/src/i18n/locales/ja.ts b/studio/frontend/src/i18n/locales/ja.ts
index 3cc2e028d7c..4f4ecb81b30 100644
--- a/studio/frontend/src/i18n/locales/ja.ts
+++ b/studio/frontend/src/i18n/locales/ja.ts
@@ -2904,6 +2904,11 @@ export const ja = {
datasetLabel: "データセット",
modelTooltip: "ファインチューニングするベースモデルです。",
methodTooltip: "モデルの学習方法です。LoRA と QLoRA はすべての重みではなく小さなアダプターを更新します。",
+ trainAsLabel: "学習タイプ",
+ trainAsTooltip:
+ "言語モデルはテキストを生成します。意思決定モデルは指定した選択肢から確率付きで1つを選び、Decision API で動作します。",
+ trainAsLanguage: "言語モデル",
+ trainAsDecision: "意思決定モデル",
checkpointLabel: "チェックポイント",
checkpointTooltip:
"ファインチューニングする Laya のチェックポイントです。多くのデータセットには多言語が適しています。",
diff --git a/studio/frontend/src/i18n/locales/ko.ts b/studio/frontend/src/i18n/locales/ko.ts
index 7c7965dc2d7..c602f376a61 100644
--- a/studio/frontend/src/i18n/locales/ko.ts
+++ b/studio/frontend/src/i18n/locales/ko.ts
@@ -2928,6 +2928,11 @@ export const ko = {
datasetLabel: "데이터셋",
modelTooltip: "파인튜닝할 기본 모델입니다.",
methodTooltip: "모델 학습 방식입니다. LoRA와 QLoRA는 전체 가중치 대신 작은 어댑터를 업데이트합니다.",
+ trainAsLabel: "학습 유형",
+ trainAsTooltip:
+ "언어 모델은 텍스트를 생성합니다. 결정 모델은 주어진 옵션 중 하나를 확률과 함께 선택하며 Decision API에서 실행됩니다.",
+ trainAsLanguage: "언어 모델",
+ trainAsDecision: "결정 모델",
checkpointLabel: "체크포인트",
checkpointTooltip:
"파인튜닝할 Laya 체크포인트입니다. 대부분의 데이터셋에는 다국어가 적합합니다.",
diff --git a/studio/frontend/src/i18n/locales/pt-br.ts b/studio/frontend/src/i18n/locales/pt-br.ts
index 1e4c591feb5..7564c3ea2f3 100644
--- a/studio/frontend/src/i18n/locales/pt-br.ts
+++ b/studio/frontend/src/i18n/locales/pt-br.ts
@@ -2958,6 +2958,11 @@ export const ptBR = {
datasetLabel: "Dataset",
modelTooltip: "O modelo base que você quer ajustar.",
methodTooltip: "Como o modelo é treinado. LoRA e QLoRA atualizam adaptadores pequenos em vez de todos os pesos.",
+ trainAsLabel: "Treinar como",
+ trainAsTooltip:
+ "Um modelo de linguagem escreve texto. Um modelo de decisão escolhe uma das opções que você fornece, com uma probabilidade, e funciona na Decision API.",
+ trainAsLanguage: "Modelo de linguagem",
+ trainAsDecision: "Modelo de decisão",
checkpointLabel: "Checkpoint",
checkpointTooltip:
"O checkpoint do Laya que será ajustado. Multilíngue serve para a maioria dos conjuntos de dados.",
diff --git a/studio/frontend/src/i18n/locales/ru.ts b/studio/frontend/src/i18n/locales/ru.ts
index 2e07f42a3ce..51e862addc2 100644
--- a/studio/frontend/src/i18n/locales/ru.ts
+++ b/studio/frontend/src/i18n/locales/ru.ts
@@ -2954,6 +2954,11 @@ export const ru = {
datasetLabel: "Датасет",
modelTooltip: "Базовая модель, которую вы хотите дообучить.",
methodTooltip: "Как обучается модель. LoRA и QLoRA обновляют небольшие адаптеры вместо всех весов.",
+ trainAsLabel: "Обучить как",
+ trainAsTooltip:
+ "Языковая модель пишет текст. Модель решений выбирает один из заданных вариантов с вероятностью и работает в Decision API.",
+ trainAsLanguage: "Языковая модель",
+ trainAsDecision: "Модель решений",
checkpointLabel: "Чекпоинт",
checkpointTooltip:
"Чекпоинт Laya для дообучения. Многоязычная подходит для большинства наборов данных.",
diff --git a/studio/frontend/src/i18n/locales/zh-CN.ts b/studio/frontend/src/i18n/locales/zh-CN.ts
index 9e616aef448..69e6f39f97f 100644
--- a/studio/frontend/src/i18n/locales/zh-CN.ts
+++ b/studio/frontend/src/i18n/locales/zh-CN.ts
@@ -2881,6 +2881,11 @@ export const zhCN = {
datasetLabel: "数据集",
modelTooltip: "要微调的基础模型。",
methodTooltip: "模型的训练方式。LoRA 和 QLoRA 只更新小型适配器,而不是全部权重。",
+ trainAsLabel: "训练为",
+ trainAsTooltip:
+ "语言模型生成文本。决策模型从你给出的选项中选择一个并给出概率,可在 Decision API 中运行。",
+ trainAsLanguage: "语言模型",
+ trainAsDecision: "决策模型",
checkpointLabel: "检查点",
checkpointTooltip: "要微调的 Laya 检查点。多语言版本适合大多数数据集。",
datasetTooltip: "用于微调模型的训练数据。",
diff --git a/studio/frontend/tests/training-llm-decision-model.test.ts b/studio/frontend/tests/training-llm-decision-model.test.ts
new file mode 100644
index 00000000000..2984cebe788
--- /dev/null
+++ b/studio/frontend/tests/training-llm-decision-model.test.ts
@@ -0,0 +1,240 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test, { after } from "node:test";
+
+import {
+ installLocalStorageFake,
+ registerStoreStubResolver,
+} from "./helpers/kit.ts";
+
+registerStoreStubResolver();
+installLocalStorageFake();
+
+const yaml = await import("js-yaml");
+const { setAuthFetchHandler } = await import("./helpers/store-stubs/auth.ts");
+const { useTrainingConfigStore } = await import(
+ "../src/features/training/stores/training-config-store.ts"
+);
+const { buildTrainingStartPayload } = await import(
+ "../src/features/training/api/mappers.ts"
+);
+
+type TrainingState = ReturnType<typeof useTrainingConfigStore.getState>;
+
+const LLM = "unsloth/Qwen3.5-4B";
+const LAYA = "convaiinnovations/laya";
+
+const LLM_DECISION_YAML = yaml.load(
+ readFileSync(
+ new URL(
+ "../../backend/assets/configs/model_defaults/decision/llm_decision_defaults.yaml",
+ import.meta.url,
+ ),
+ "utf8",
+ ),
+) as { training: Record<string, number>; lora: Record<string, number> };
+
+const BASE = {
+ id: LLM,
+ is_vision: true,
+ is_embedding: false,
+ is_audio: false,
+ audio_type_known: true,
+ is_lora: false,
+ model_size_bytes: 9_000_000_000,
+ max_position_embeddings: 262144,
+};
+
+// What /api/models/config answers for the LLM, with and without as_decision.
+const LLM_CONFIG = { ...BASE, config: { training: {} }, model_type: "vision" };
+const LLM_DECISION_CONFIG = {
+ ...BASE,
+ config: LLM_DECISION_YAML,
+ is_decision: true,
+ decision_layout: "llm",
+ decision_checkpoints: null,
+ model_type: "decision",
+};
+const LAYA_CONFIG = {
+ ...BASE,
+ id: LAYA,
+ is_vision: false,
+ config: { training: { learning_rate: 8e-4 }, lora: { lora_r: 64 } },
+ is_decision: true,
+ decision_checkpoints: [
+ { name: "laya-multilingual", subfolder: "multilingual", description: "" },
+ ],
+ model_type: "decision",
+};
+
+const CLEF = "Cloudflare/clef-flash";
+const CLEF_CONFIG = {
+ ...BASE,
+ id: CLEF,
+ is_vision: false,
+ config: { training: { learning_rate: 2e-4, max_seq_length: 4096 } },
+ is_decision: true,
+ decision_layout: "clef",
+ decision_checkpoints: null,
+ model_type: "decision",
+};
+
+function serve(asDecision: object = LLM_DECISION_CONFIG): string[] {
+ const requested: string[] = [];
+ setAuthFetchHandler((input) => {
+ requested.push(input);
+ if (!input.startsWith("/api/models/config/")) {
+ return Response.json({});
+ }
+ if (input.includes("laya")) {
+ return Response.json(LAYA_CONFIG);
+ }
+ if (input.includes("clef")) {
+ return Response.json(CLEF_CONFIG);
+ }
+ return Response.json(
+ input.includes("as_decision=true") ? asDecision : LLM_CONFIG,
+ );
+ });
+ return requested;
+}
+
+async function waitFor(done: (state: TrainingState) => boolean): Promise<void> {
+ for (let attempt = 0; attempt < 200; attempt += 1) {
+ const state = useTrainingConfigStore.getState();
+ if (!state.isLoadingModelDefaults && done(state)) {
+ return;
+ }
+ await new Promise((resolve) => setTimeout(resolve, 5));
+ }
+ throw new Error("the training config did not settle");
+}
+
+async function selectLlm(): Promise<string[]> {
+ const requested = serve();
+ useTrainingConfigStore.getState().selectTrainingModel(LLM, "text");
+ await waitFor((state) => state.modelDefaultsAppliedFor === LLM);
+ return requested;
+}
+
+after(() => setAuthFetchHandler(null));
+
+test("an LLM trained as a decision model gets the decision recipe and keeps QLoRA", async () => {
+ useTrainingConfigStore.getState().reset();
+ const requested = await selectLlm();
+ assert.equal(useTrainingConfigStore.getState().modelType, "vision");
+ useTrainingConfigStore.setState({ trainingMethod: "qlora" });
+
+ useTrainingConfigStore.getState().setTrainAsDecision(true);
+ await waitFor((state) => state.modelType === "decision");
+
+ assert.ok(requested.some((url) => url.includes("as_decision=true")));
+ const state = useTrainingConfigStore.getState();
+ assert.equal(state.decisionLayout, "llm");
+ assert.equal(state.decisionCheckpoints, null);
+ assert.equal(state.trainingMethod, "qlora");
+ assert.equal(state.learningRate, LLM_DECISION_YAML.training.learning_rate);
+ assert.equal(state.epochs, LLM_DECISION_YAML.training.num_epochs);
+ assert.equal(state.loraRank, LLM_DECISION_YAML.lora.lora_r);
+ assert.equal(state.contextLength, LLM_DECISION_YAML.training.max_seq_length);
+ assert.equal(state.datasetStreaming, false);
+
+ const payload = buildTrainingStartPayload(state, null);
+ assert.equal(payload.is_decision, true);
+ assert.equal(payload.training_type, "LoRA/QLoRA");
+ assert.equal(payload.load_in_4bit, true);
+ assert.equal(
+ payload.max_seq_length,
+ LLM_DECISION_YAML.training.max_seq_length,
+ );
+ assert.equal(payload.model_subfolder, null);
+ assert.equal(payload.use_dora, false);
+ assert.equal(payload.train_on_completions, false);
+});
+
+test("switching back to a language model restores the method it had", async () => {
+ useTrainingConfigStore.getState().reset();
+ await selectLlm();
+ useTrainingConfigStore.setState({ trainingMethod: "full" });
+
+ useTrainingConfigStore.getState().setTrainAsDecision(true);
+ await waitFor((state) => state.modelType === "decision");
+ assert.equal(useTrainingConfigStore.getState().trainingMethod, "qlora");
+
+ useTrainingConfigStore.getState().setTrainAsDecision(false);
+ await waitFor((state) => state.modelType === "vision");
+
+ const state = useTrainingConfigStore.getState();
+ assert.equal(state.trainingMethod, "full");
+ assert.equal(state.decisionLayout, null);
+ assert.equal(state.settingsBeforeDecision, null);
+ assert.equal(buildTrainingStartPayload(state, null).is_decision, false);
+});
+
+test("a model the backend cannot train as a decision model turns the choice off", async () => {
+ useTrainingConfigStore.getState().reset();
+ await selectLlm();
+ serve({
+ ...LLM_CONFIG,
+ is_vision: false,
+ is_audio: true,
+ model_type: "audio",
+ });
+
+ useTrainingConfigStore.getState().setTrainAsDecision(true);
+ await waitFor((state) => !state.trainAsDecision);
+
+ assert.equal(useTrainingConfigStore.getState().modelType, "audio");
+});
+
+test("a failed decision config request turns the choice back off", async () => {
+ useTrainingConfigStore.getState().reset();
+ await selectLlm();
+ setAuthFetchHandler((input) =>
+ input.includes("as_decision=true")
+ ? new Response("down", { status: 500 })
+ : Response.json({}),
+ );
+
+ useTrainingConfigStore.getState().setTrainAsDecision(true);
+ await waitFor((state) => state.modelDefaultsError !== null);
+
+ const state = useTrainingConfigStore.getState();
+ assert.equal(state.trainAsDecision, false);
+ assert.equal(buildTrainingStartPayload(state, null).is_decision, false);
+});
+
+test("Laya stays a 16-bit LoRA run whatever the choice", async () => {
+ useTrainingConfigStore.getState().reset();
+ serve();
+ useTrainingConfigStore.setState({ trainAsDecision: true });
+ useTrainingConfigStore.getState().selectTrainingModel(LAYA, "text");
+ await waitFor((state) => state.modelDefaultsAppliedFor === LAYA);
+
+ const state = useTrainingConfigStore.getState();
+ assert.equal(state.decisionLayout, "laya");
+ assert.equal(state.trainingMethod, "lora");
+ const payload = buildTrainingStartPayload(state, null);
+ assert.equal(payload.load_in_4bit, false);
+ assert.equal(payload.max_seq_length, 1024);
+ assert.equal(payload.model_subfolder, "multilingual");
+});
+
+test("Clef keeps its own layout and QLoRA whatever the choice", async () => {
+ useTrainingConfigStore.getState().reset();
+ serve();
+ useTrainingConfigStore.setState({ trainAsDecision: true });
+ useTrainingConfigStore.getState().selectTrainingModel(CLEF, "text");
+ await waitFor((state) => state.modelDefaultsAppliedFor === CLEF);
+
+ const state = useTrainingConfigStore.getState();
+ assert.equal(state.decisionLayout, "clef");
+ assert.equal(state.trainingMethod, "qlora");
+ const payload = buildTrainingStartPayload(state, null);
+ assert.equal(payload.is_decision, true);
+ assert.equal(payload.load_in_4bit, true);
+ assert.equal(payload.max_seq_length, 4096);
+});
diff --git a/tests/test_decision_clef_head.py b/tests/test_decision_clef_head.py
index b12fdfe9bfb..292ce92a76b 100644
--- a/tests/test_decision_clef_head.py
+++ b/tests/test_decision_clef_head.py
@@ -199,17 +199,22 @@ def test_compile_gating(monkeypatch):
import torch.utils._triton as triton_utils
monkeypatch.setattr(triton_utils, "has_triton", lambda: True)
+ cuda = torch.device("cuda")
+ # Eager unless asked for: unset, "auto" and "0" never compile.
+ monkeypatch.delenv("UNSLOTH_CLEF_COMPILE", raising = False)
+ assert not clef._compile_supported(cuda) and clef._compiled_logits(cuda) is None
+ for choice in ("auto", "0"):
+ monkeypatch.setenv("UNSLOTH_CLEF_COMPILE", choice)
+ assert not clef._compile_supported(cuda)
+ monkeypatch.setenv("UNSLOTH_CLEF_COMPILE", "1")
+ assert clef._compile_supported(cuda)
assert not clef._compile_supported(torch.device("cpu"))
- assert clef._compile_supported(torch.device("cuda"))
# ROCm reports cuda devices: compiled when its Triton is present.
monkeypatch.setattr(torch.version, "hip", "6.4", raising = False)
- assert clef._compile_supported(torch.device("cuda"))
+ assert clef._compile_supported(cuda)
# Windows ROCm / CUDA wheels without Triton: eager.
monkeypatch.setattr(triton_utils, "has_triton", lambda: False)
- assert not clef._compile_supported(torch.device("cuda"))
- monkeypatch.setattr(triton_utils, "has_triton", lambda: True)
- monkeypatch.setenv("UNSLOTH_CLEF_COMPILE", "0")
- assert not clef._compile_supported(torch.device("cuda"))
+ assert not clef._compile_supported(cuda)
def test_a_failed_compile_falls_back_to_eager(monkeypatch):
diff --git a/tests/test_decision_from_lm.py b/tests/test_decision_from_lm.py
index ba9122b52e0..b4770abc71b 100644
--- a/tests/test_decision_from_lm.py
+++ b/tests/test_decision_from_lm.py
@@ -93,6 +93,43 @@ def _train(
return losses.losses
+_MODEL_FILES = (
+ "config.json",
+ "generation_config.json",
+ "model.safetensors",
+ "model.safetensors-*-of-*.safetensors",
+ "model-*-of-*.safetensors",
+ "model.safetensors.index.json",
+ "adapter_config.json",
+ "adapter_model.safetensors",
+ "joint_head.safetensors",
+ "joint_head_config.json",
+ "unsloth_decision_config.json",
+ "joint_schema_model.py",
+ "LICENSE",
+ "README.md",
+ "chat_template.jinja",
+ "tokenizer.json",
+ "tokenizer_config.json",
+ "special_tokens_map.json",
+ "added_tokens.json",
+ "vocab.json",
+ "merges.txt",
+ "processor_config.json",
+ "preprocessor_config.json",
+ "video_preprocessor_config.json",
+)
+
+
+def _assert_only_model_files(folder):
+ # Nothing else: no download cache (.cache/huggingface), locks, staging or partial files.
+ import fnmatch
+
+ names = sorted(path.name for path in folder.iterdir())
+ stray = [n for n in names if not any(fnmatch.fnmatch(n, p) for p in _MODEL_FILES)]
+ assert not stray, (stray, names)
+
+
def test_default_head_config_scales_with_the_backbone():
assert default_head_config(4096)["width"] == 1024
assert default_head_config(2048)["width"] == 512
@@ -160,11 +197,55 @@ def test_plain_lm_becomes_a_decision_model_that_trains_saves_and_reloads(base, t
assert min(losses[-5:]) < losses[0] and after["loss"] < before["loss"]
FastDecisionModel.calibrate(model, processor, holdout)
+ state, questions = _rows(1)[0]["state"], _rows(1)[0]["questions"]
+ answers = FastDecisionModel.predict(model, processor, state, questions)
+ assert answers["outage"]["type"] == "noul" and 0 <= answers["outage"]["noul"] <= 1
+ assert answers["team"]["choice"] in ("billing", "tech")
+ assert sum(answers["team"]["probabilities"].values()) == pytest.approx(1, abs = 1e-3)
+ assert answers["mood"]["legend"] == {"0": "calm", "1": "annoyed", "2": "angry"}
+
+ # save_pretrained: only the adapters, the head and the configs; reloaded onto the base.
+ adapters = tmp_path / "adapters"
+ model.save_pretrained(str(adapters))
+ assert (adapters / "adapter_config.json").is_file()
+ assert (adapters / "joint_head.safetensors").is_file()
+ assert not (adapters / "config.json").exists() and not list(adapters.glob("model*.safetensors"))
+ assert (
+ json.loads((adapters / "adapter_config.json").read_text())["base_model_name_or_path"]
+ == base
+ )
+ from_adapters, adapter_processor = FastDecisionModel.from_pretrained(
+ str(adapters), max_seq_length = 512
+ )
+ assert hasattr(from_adapters.encoder, "peft_config")
+ assert from_adapters.decision_config["base_model"] == base
+ again = FastDecisionModel.predict(from_adapters, adapter_processor, state, questions)
+ # The head is stored in bf16; the adapters keep their own dtype.
+ for name in questions:
+ for key, value in answers[name].get("probabilities", {}).items():
+ assert again[name]["probabilities"][key] == pytest.approx(value, abs = 0.03)
+ assert again["outage"]["noul"] == pytest.approx(answers["outage"]["noul"], abs = 0.03)
+ # A merged save from the adapter reload is a complete Clef folder again.
+ remerged = tmp_path / "remerged"
+ from_adapters.save_pretrained_merged(str(remerged))
+ assert (remerged / "config.json").is_file() and not (remerged / "adapter_config.json").exists()
+ del from_adapters
+
out = tmp_path / "out"
model.save_pretrained_merged(str(out))
+ _assert_only_model_files(out)
+ # Saving adapters over a merged folder (or the reverse) leaves no stale weights behind.
+ model.save_pretrained(str(out / "swap"))
+ model.save_pretrained_merged(str(out / "swap"))
+ assert not (out / "swap" / "adapter_config.json").exists()
+ model.save_pretrained(str(out / "swap"))
+ assert not (out / "swap" / "config.json").exists()
+ assert not list((out / "swap").glob("model*.safetensors"))
assert json.loads((out / "joint_head_config.json").read_text())["hidden_size"] == hidden
- reloaded, _ = FastDecisionModel.from_pretrained(str(out), max_seq_length = 512)
+ reloaded, reloaded_processor = FastDecisionModel.from_pretrained(str(out), max_seq_length = 512)
assert reloaded.decision_config["temperature"] == model.decision_config["temperature"]
+ merged_answers = FastDecisionModel.predict(reloaded, reloaded_processor, state, questions)
+ assert merged_answers["outage"]["noul"] == pytest.approx(answers["outage"]["noul"], abs = 0.05)
# calibrate() fits a head temperature that the save folds into the head weights.
head_temperature = model.decision_config.get("head_temperature", 1.0)
assert reloaded.decision_config.get("folded_temperature", 1.0) == pytest.approx(
@@ -276,6 +357,215 @@ def test_unknown_decision_head_is_refused():
FastDecisionModel.from_pretrained(TINY_QWEN3, decision_head = "pointer")
+def _typed_decision_rows(n):
+ # Shaped like LocalLLaMA/typed-decisions: JSON strings for state, questions and gold.
+ import json
+
+ rows = []
+ for i in range(n):
+ outage = i % 2 == 1
+ state = {
+ "ticket": f"T-{i}",
+ "message": "the server is down again" if outage else "my invoice was paid twice",
+ }
+ questions = {
+ "team": {
+ "type": "choice",
+ "instructions": "Which team should handle this?",
+ "criteria": {"billing": "invoices, refunds", "technical": "bugs, outages"},
+ },
+ "refund": {
+ "type": "noul",
+ "instructions": "Does the customer ask for a refund?",
+ "criteria": {"false": "No refund.", "true": "A refund is asked for."},
+ },
+ "urgency": {
+ "type": "score",
+ "instructions": "How urgent is this?",
+ "criteria": ["not urgent", "soon", "today"],
+ },
+ }
+ p = 0.8
+ gold = {
+ "team": {
+ "type": "choice",
+ "label": "technical" if outage else "billing",
+ "probabilities": {
+ "technical": p if outage else 1 - p,
+ "billing": 1 - p if outage else p,
+ },
+ },
+ "refund": {
+ "type": "noul",
+ "label": str(not outage).lower(),
+ "noul": 0.2 if outage else 0.9,
+ },
+ "urgency": {"type": "score", "label": "2" if outage else "0"},
+ }
+ rows.append(
+ {
+ "id": f"row-{i}",
+ "workflow": "customer_service",
+ "state": json.dumps(state),
+ "questions": json.dumps(questions),
+ "gold": json.dumps(gold),
+ "n_questions": 3,
+ }
+ )
+ return rows
+
+
+ not _qwen3_5_runs_here(), reason = "causal_conv1d is installed but there is no CUDA device"
+)
+def test_the_decision_notebook_runs_unchanged_on_a_plain_qwen3_5(tmp_path, monkeypatch):
+ # unslothai/notebooks#380's call sequence, on a tiny Qwen3.5 with no decision_head argument.
+ from datasets import Dataset
+ from real_accelerator import has_real_cuda
+ from transformers import TrainingArguments
+
+ from unsloth import is_bfloat16_supported
+
+ monkeypatch.chdir(tmp_path)
+ four_bit = has_real_cuda() # The notebook loads in 4-bit, which needs a GPU.
+ model, tokenizer = FastDecisionModel.from_pretrained(
+ model_name = TINY_QWEN3_5, max_seq_length = 2048, load_in_4bit = four_bit
+ )
+ assert getattr(model, "is_clef", False)
+ model = FastDecisionModel.get_peft_model(
+ model,
+ r = 16,
+ lora_alpha = 16,
+ lora_dropout = 0,
+ use_gradient_checkpointing = "unsloth",
+ random_state = 3407,
+ )
+ dataset = Dataset.from_list(_typed_decision_rows(40))
+ items, report = FastDecisionModel.build_dataset(dataset, tokenizer, model)
+ assert report["skipped"] == 0 and report["total"] == 120 and report["truncated"] == 0
+ train_items, eval_items = FastDecisionModel.split_holdout(items, seed = 3407)
+ assert train_items and eval_items
+ FastDecisionModel.evaluate(model, tokenizer, eval_items)
+
+ # fp16 = True where bfloat16 is missing (a T4): DecisionTrainer settles Clef's precision.
+ bf16 = is_bfloat16_supported() and has_real_cuda()
+ trainer = DecisionTrainer(
+ model = model,
+ processing_class = tokenizer,
+ train_dataset = train_items,
+ eval_dataset = eval_items,
+ args = TrainingArguments(
+ per_device_train_batch_size = 8,
+ gradient_accumulation_steps = 4,
+ warmup_steps = 1,
+ max_steps = 2,
+ learning_rate = 2e-4,
+ lr_scheduler_type = "cosine",
+ weight_decay = 0.01,
+ bf16 = bf16,
+ fp16 = has_real_cuda() and not bf16,
+ eval_strategy = "epoch",
+ logging_steps = 1,
+ output_dir = "outputs",
+ report_to = "none",
+ seed = 3407,
+ ),
+ )
+ trainer.train()
+ # The trainer's own checkpoint: adapters and the exact float32 head, not the shared-weight backbone.
+ from safetensors.torch import load_file
+
+ checkpoint = tmp_path / "outputs" / "checkpoint-2"
+ assert (checkpoint / "adapter_model.safetensors").is_file()
+ saved = load_file(str(checkpoint / "joint_head.safetensors"))
+ for name, value in model.head.state_dict().items():
+ assert torch.equal(saved[name], value.detach().cpu().float()), name
+ FastDecisionModel.calibrate(model, tokenizer, eval_items)
+ test_items, _ = FastDecisionModel.build_dataset(
+ Dataset.from_list(_typed_decision_rows(6)), tokenizer, model
+ )
+ assert 0 <= FastDecisionModel.evaluate(model, tokenizer, test_items)["accuracy"] <= 1
+
+ FastDecisionModel.for_inference(model)
+ state = "Hi, I was charged twice for invoice #4411. Please refund the duplicate today."
+ questions = {
+ "team": {
+ "type": "choice",
+ "instructions": "Which team should handle this?",
+ "criteria": {
+ "billing": "invoices, payments, refunds",
+ "technical": "bugs, outages, errors",
+ "sales": "pricing, new plans",
+ },
+ },
+ "refund": {"type": "noul", "instructions": "Does the customer ask for a refund?"},
+ "urgency": {
+ "type": "score",
+ "instructions": "How urgent is this?",
+ "criteria": ["not urgent", "soon", "today"],
+ },
+ }
+ answers = FastDecisionModel.predict(model, tokenizer, state, questions)
+ assert answers["team"]["answer"] in ("billing", "technical", "sales")
+ assert isinstance(answers["refund"]["answer"], bool)
+ assert answers["urgency"]["answer"] in (0, 1, 2)
+ for name, result in answers.items():
+ probabilities = {k: round(v, 3) for k, v in result["probabilities"].items()}
+ assert sum(probabilities.values()) == pytest.approx(1, abs = 0.01), name
+ assert set(answers["refund"]["probabilities"]) == {"false", "true"}
+
+ model.save_pretrained("decision_model")
+ assert (tmp_path / "decision_model" / "adapter_config.json").is_file()
+ model, tokenizer = FastDecisionModel.from_pretrained(
+ model_name = "decision_model", max_seq_length = 2048, load_in_4bit = four_bit
+ )
+ again = FastDecisionModel.predict(model, tokenizer, state, questions)
+ for name in questions:
+ assert (
+ again[name]["answer"] == answers[name]["answer"]
+ or max(answers[name]["probabilities"].values()) < 0.6
+ )
+ for key, value in answers[name]["probabilities"].items():
+ assert again[name]["probabilities"][key] == pytest.approx(value, abs = 0.05)
+ model.save_pretrained_merged("decision_model_16bit", tokenizer, save_method = "merged_16bit")
+ _assert_only_model_files(tmp_path / "decision_model_16bit")
+ _assert_only_model_files(tmp_path / "decision_model")
+ assert (tmp_path / "decision_model_16bit" / "config.json").is_file()
+ assert (tmp_path / "decision_model_16bit" / "joint_head.safetensors").is_file()
+
+
+def test_long_states_are_cut_in_training_but_read_in_full_by_predict(monkeypatch):
+ # Training cuts the end of a long state; predict() reads up to CLEF_SERVE_MAX_LEN tokens, like serving.
+ from unsloth.models import decision
+
+ from transformers import AutoConfig
+
+ hidden = AutoConfig.from_pretrained(TINY_QWEN3).hidden_size
+ model, processor = FastDecisionModel.from_pretrained(
+ TINY_QWEN3,
+ decision_head = "clef",
+ head_config = {**HEAD, "hidden_size": hidden},
+ max_seq_length = 512,
+ )
+ long_row = _rows(1)[0]
+ long_row["state"] = "the server is down again. " * 400
+ items, report = FastDecisionModel.build_dataset([long_row] + _rows(3), processor, model)
+ assert report["skipped"] == 0 and report["truncated"] == 1
+ assert len(items[0]["input_ids"]) == 512
+ seen = {}
+ real = decision._clef_decide
+
+ def spy(*args, **kwargs):
+ seen["max_length"] = kwargs["max_length"]
+ result = real(*args, **kwargs)
+ seen["tokens"] = result["input_tokens"]
+ return result
+
+ monkeypatch.setattr(decision, "_clef_decide", spy)
+ FastDecisionModel.predict(model, processor, long_row["state"], long_row["questions"])
+ assert seen["max_length"] == decision.CLEF_SERVE_MAX_LEN and seen["tokens"] > 512
+
+
def test_backbone_stays_on_one_device_unless_the_caller_places_it(monkeypatch):
from unsloth.models import decision, decision_from_lm, loader
@@ -294,7 +584,59 @@ def test_backbone_stays_on_one_device_unless_the_caller_places_it(monkeypatch):
for kwargs in ({}, {"device_map": "auto"}):
with pytest.raises(Captured):
decision_from_lm._load_backbone(TINY_QWEN3, 64, None, False, False, None, False, kwargs)
- assert seen == [{"": f"cuda:{index}"}, "auto"]
+ # The default from-LM path: a plain LLM with no decision_head argument becomes a Clef model.
+ with pytest.raises(Captured):
+ FastDecisionModel.from_pretrained(TINY_QWEN3, max_seq_length = 64)
+ assert seen == [{"": f"cuda:{index}"}, "auto", {"": f"cuda:{index}"}]
+
+
+def _tiny_lm(
+ monkeypatch,
+ name = TINY_QWEN3,
+ **kwargs,
+):
+ monkeypatch.setattr(decision, "_device", lambda: torch.device("cpu"))
+ return FastDecisionModel.from_pretrained(
+ name, decision_head = "clef", head_width = 32, max_seq_length = 256, **kwargs
+ )
+
+
+def test_a_gpt2_style_lm_runs_as_a_decision_model(monkeypatch):
+ model, processor = _tiny_lm(monkeypatch, "trl-internal-testing/tiny-GPT2LMHeadModel")
+ row = _rows(1)[0]
+ answers = FastDecisionModel.predict(model, processor, row["state"], row["questions"])
+ assert answers["team"]["choice"] in ("billing", "tech")
+
+
+def test_adapters_refuse_a_full_finetune_and_keep_the_base_revision(tmp_path, monkeypatch):
+ model, processor = _tiny_lm(monkeypatch, revision = "main")
+ assert model.decision_config["base_revision"] == "main"
+ model = FastDecisionModel.get_peft_model(model, r = 4, lora_alpha = 4)
+ model.save_pretrained(str(tmp_path / "adapters"))
+ adapter = json.loads((tmp_path / "adapters" / "adapter_config.json").read_text())
+ assert adapter["revision"] == "main"
+ with pytest.raises(ValueError, match = "save_pretrained_merged"):
+ FastDecisionModel.from_pretrained(str(tmp_path / "adapters"), full_finetuning = True)
+ reloaded, _ = FastDecisionModel.from_pretrained(str(tmp_path / "adapters"))
+ assert reloaded.decision_config["base_revision"] == "main"
+
+
+def test_a_full_finetune_restores_its_own_checkpoint(tmp_path, monkeypatch):
+ model, processor = _tiny_lm(monkeypatch, full_finetuning = True)
+ trainer = DecisionTrainer(
+ model = model,
+ tokenizer = processor,
+ train_dataset = [],
+ args = TrainingArguments(output_dir = str(tmp_path / "run"), report_to = "none"),
+ )
+ trainer._save(str(tmp_path / "ckpt"))
+ saved = {k: v.clone() for k, v in model.state_dict().items()}
+ with torch.no_grad():
+ for p in model.parameters():
+ p.add_(1.0)
+ decision._load_clef_checkpoint(model, tmp_path / "ckpt")
+ for k, v in model.state_dict().items():
+ assert torch.equal(v, saved[k]), k
def test_full_finetuning_never_gets_a_4bit_config(monkeypatch):
diff --git a/tests/test_decision_model.py b/tests/test_decision_model.py
index fa86f65f2cc..9dc3762f5a7 100644
--- a/tests/test_decision_model.py
+++ b/tests/test_decision_model.py
@@ -419,10 +419,15 @@ def test_train_calibrate_save_and_serve(checkpoint, tmp_path, lora):
encoder_config = (checkpoint / "encoder" / "config.json").read_bytes()
assert (tmp_path / "out" / "encoder" / "config.json").read_bytes() == encoder_config
agent = laya.load(str(tmp_path / "out"), device = "cpu")
- assert agent.predict("the server is down again", QUESTIONS)["answers"]["team"]["choice"] in (
- "outage",
- "billing",
- )
+ served = agent.predict("the server is down again", QUESTIONS)["answers"]
+ assert served["team"]["choice"] in ("outage", "billing")
+ # predict() answers like the served checkpoint, from the model in memory.
+ ours = FastDecisionModel.predict(model, tokenizer, "the server is down again", QUESTIONS)
+ assert set(ours) == set(QUESTIONS)
+ for name, answer in served.items():
+ assert ours[name]["type"] == answer["type"]
+ for key, value in (answer.get("probabilities") or {}).items():
+ assert ours[name]["probabilities"][key] == pytest.approx(value, abs = 0.02)
FastDecisionModel.for_inference(model)
assert not model.training
@@ -1116,6 +1121,21 @@ def test_clef_loads_scores_like_cloudflares_model_and_trains(clef_checkpoint, tm
assert error <= 0.03 * scale + 0.05, (error, scale, folded)
for row, z in enumerate(theirs):
assert int(z.argmax()) == int(again[row, : len(z)].argmax()), (row, z, again[row, : len(z)])
+ # predict() serves the same calibrated answer from memory, the merged reload and the adapters.
+ state = "the server is down again"
+ ours = FastDecisionModel.predict(model, processor, state, QUESTIONS)
+ merged = FastDecisionModel.predict(reloaded, processor, state, QUESTIONS)
+ model.save_pretrained(str(tmp_path / "adapters"))
+ from_adapters, _ = FastDecisionModel.from_pretrained(
+ str(tmp_path / "adapters"), max_seq_length = 512
+ )
+ assert from_adapters.decision_config["base_model"] == str(clef_checkpoint)
+ adapters = FastDecisionModel.predict(from_adapters, processor, state, QUESTIONS)
+ for name in QUESTIONS:
+ for other in (merged, adapters):
+ assert other[name]["type"] == ours[name]["type"]
+ for key, value in (ours[name].get("probabilities") or {}).items():
+ assert other[name]["probabilities"][key] == pytest.approx(value, abs = 0.03)
@pytest.mark.skipif(not has_real_cuda(), reason = "the fast kernels need a CUDA device")
@@ -1416,7 +1436,7 @@ def test_clef_calibration_fits_being_right_and_serves_through_the_head_temperatu
)
-def test_clef_autocasts_only_in_bfloat16_and_never_on_the_float32_path(monkeypatch):
+def test_clef_autocasts_as_it_trains_and_never_on_the_float32_path(monkeypatch):
model = torch.nn.Linear(1, 1)
cuda = torch.device("cuda")
monkeypatch.setattr(decision, "is_bfloat16_supported", lambda: True)
@@ -1424,11 +1444,33 @@ def test_clef_autocasts_only_in_bfloat16_and_never_on_the_float32_path(monkeypat
model._unsloth_forced_float32 = True
assert decision._clef_amp_dtype(model, cuda) is None
model._unsloth_forced_float32 = False
+ # A T4: an fp16 model autocasts like its fp16 training, else its fp32 norms meet fp16 Linears.
monkeypatch.setattr(decision, "is_bfloat16_supported", lambda: False)
+ assert decision._clef_amp_dtype(model, cuda) == torch.float16
+ model._unsloth_forced_float32 = True
assert decision._clef_amp_dtype(model, cuda) is None
+ model._unsloth_forced_float32 = False
assert decision._clef_amp_dtype(model, torch.device("cpu")) is None
+def test_a_clef_prompt_that_fits_exactly_is_not_truncated(monkeypatch):
+ # Serving (Studio's Decision API) and predict share this rule.
+ from unsloth.models import clef
+
+ def encode(tokenizer, record, max_length):
+ # The state needs `natural` tokens; anything over max_length is cut to fit.
+ return types.SimpleNamespace(input_ids = [0] * min(record["state"], max_length))
+
+ monkeypatch.setattr(clef, "encode_record", encode)
+ size = 16384
+
+ def truncated(natural):
+ encoded = encode(None, {"state": natural}, size)
+ return decision._clef_truncated(None, natural, {}, encoded, size)
+
+ assert (truncated(size - 1), truncated(size), truncated(size + 1)) == (False, False, True)
+
+
@pytest.mark.parametrize("forced", [False, True])
def test_clef_trains_under_the_autocast_it_evaluates_in(tmp_path, monkeypatch, forced):
# A previous trainer leaves fp16 in ACCELERATE_MIXED_PRECISION, which transformers 4.x reads.
@@ -1445,6 +1487,18 @@ def test_clef_trains_under_the_autocast_it_evaluates_in(tmp_path, monkeypatch, f
assert getattr(args, "mixed_precision", expected) == expected
+def test_clef_trains_under_fp16_autocast_on_a_gpu_without_bf16(tmp_path, monkeypatch):
+ # A T4: evaluate and serving autocast fp16, so training does too.
+ monkeypatch.setenv("ACCELERATE_MIXED_PRECISION", "no")
+ monkeypatch.setattr(decision, "_amp_dtype", lambda device: torch.float16)
+ model = torch.nn.Linear(1, 1)
+ model._unsloth_forced_float32 = False
+ args = _args(tmp_path)
+ decision._clef_mixed_precision(model, args)
+ assert args.fp16 and not args.bf16, (args.bf16, args.fp16)
+ assert decision.os.environ["ACCELERATE_MIXED_PRECISION"] == "fp16"
+
+
def test_clef_calibration_with_every_holdout_decision_from_one_row():
# A holdout row with many questions passes the item minimum with nothing to cross-validate on.
logits = [torch.tensor([1.0, 0.0, -1.0]) for _ in range(12)]
diff --git a/unsloth/models/clef.py b/unsloth/models/clef.py
index c932d50c4db..b2ec9048802 100644
--- a/unsloth/models/clef.py
+++ b/unsloth/models/clef.py
@@ -43,8 +43,11 @@ def _fast_enabled() -> bool:
_COMPILED = {}
+# Eager unless UNSLOTH_CLEF_COMPILE=1: compiling costs 7-20 minutes per process and is no faster (L4, G4).
+
+
def _compile_supported(device) -> bool:
- if os.environ.get("UNSLOTH_CLEF_COMPILE", "1") == "0" or device.type != "cuda":
+ if os.environ.get("UNSLOTH_CLEF_COMPILE") != "1" or device.type != "cuda":
return False
try:
from torch.utils._triton import has_triton
diff --git a/unsloth/models/decision.py b/unsloth/models/decision.py
index e302e9f1fb0..a10ff3d00e4 100644
--- a/unsloth/models/decision.py
+++ b/unsloth/models/decision.py
@@ -43,6 +43,8 @@ CLEF_RECIPE = {}
_FILES = ("rl_agent_config.json", "model.safetensors")
_DIRS = ("encoder", "tokenizer")
_CLEF_HEAD_FILES = ("joint_head.safetensors", "joint_head_config.json")
+_ADAPTER_CONFIG = "adapter_config.json"
+_DECISION_CONFIG = "unsloth_decision_config.json"
# Copied byte for byte from the checkpoint a Clef fine-tune started from: Cloudflare's loader and
# license, and the tokenizer / processor files, which transformers would otherwise rewrite (a
# re-saved tokenizer_config.json trips transformers' "incorrect regex pattern" warning).
@@ -56,6 +58,8 @@ _CLEF_EXTRA_FILES = (
"generation_config.json",
)
CLEF_MAX_LEN = 4096
+# predict() and serving read this many tokens whatever the training length: cutting a state drops evidence.
+CLEF_SERVE_MAX_LEN = 16384
# laya 0.3.5 ships inside Unsloth for Studio's Decision API (studio/backend/vendor/README.md).
_VENDORED_LAYA = (
Path(__file__).resolve().parents[2] / "studio" / "backend" / "vendor" / "laya" / "__init__.py"
@@ -98,9 +102,16 @@ def is_decision_checkpoint(folder) -> bool:
def is_clef_checkpoint(folder) -> bool:
- # Cloudflare's Clef layout: a Qwen3.5 backbone plus a joint schema head.
+ # Cloudflare's Clef layout: a backbone (merged, or LoRA adapters over a base) plus a joint schema head.
folder = Path(folder)
- return all((folder / name).is_file() for name in ("config.json", *_CLEF_HEAD_FILES))
+ return all((folder / name).is_file() for name in _CLEF_HEAD_FILES) and (
+ (folder / "config.json").is_file() or (folder / _ADAPTER_CONFIG).is_file()
+ )
+
+
+def _is_clef_adapter(folder) -> bool:
+ folder = Path(folder)
+ return not (folder / "config.json").is_file() and (folder / _ADAPTER_CONFIG).is_file()
def _is_clef_repo(model_name, prefix, token, revision) -> Optional[bool]:
@@ -117,6 +128,37 @@ def _is_clef_repo(model_name, prefix, token, revision) -> Optional[bool]:
return prefix + _CLEF_HEAD_FILES[1] in files
+def _is_plain_lm(model_name, subfolder, token, revision, local_files_only) -> bool:
+ # Unknown (offline, no access) answers False, so the checkpoint loader names what is missing.
+ markers = {_FILES[0], _CLEF_HEAD_FILES[1]}
+ if subfolder:
+ return False
+ root = Path(str(model_name)).expanduser()
+ if root.is_dir():
+ has = lambda name: (root / name).is_file()
+ return (has("config.json") or has(_ADAPTER_CONFIG)) and not any(map(has, markers))
+ from huggingface_hub import constants
+
+ if not (local_files_only or constants.HF_HUB_OFFLINE):
+ try:
+ from huggingface_hub import HfApi
+ files = HfApi(token = token).list_repo_files(str(model_name), revision = revision)
+ except Exception:
+ files = None
+ if files is not None:
+ names = {name.rsplit("/", 1)[-1] for name in files}
+ return bool({"config.json", _ADAPTER_CONFIG} & set(files)) and not (names & markers)
+ from huggingface_hub import try_to_load_from_cache
+
+ def cached(name) -> bool:
+ try:
+ return isinstance(try_to_load_from_cache(str(model_name), name, revision = revision), str)
+ except Exception:
+ return False
+
+ return (cached("config.json") or cached(_ADAPTER_CONFIG)) and not any(map(cached, markers))
+
+
def _checkpoint_folder(model_name, subfolder, token, revision, local_files_only) -> Path:
root = Path(model_name).expanduser()
if not root.is_dir():
@@ -511,7 +553,8 @@ class ClefDecisionModel(torch.nn.Module):
):
head = self.head if head is None else head
backbone = self._backbone()
- text_model = backbone.model
+ # GPT-2 style models keep their decoder under base_model_prefix (.transformer), not .model.
+ text_model = getattr(backbone, "model", None) or backbone.base_model
text_model = getattr(text_model, "language_model", text_model)
hidden = text_model(
input_ids = input_ids,
@@ -666,6 +709,125 @@ def _decision_logits(
return _logits(model, items, pad_token_id), items
+def _predicted(question: dict, answer: dict, probabilities: dict) -> dict:
+ # The Decision API answer plus "answer": the option (choice), True / False (noul) or level number (score).
+ kind = question["type"]
+ best = max(probabilities, key = probabilities.__getitem__)
+ return {
+ **answer,
+ "answer": int(best) if kind == "score" else best == "true" if kind == "noul" else best,
+ "probabilities": answer.get("probabilities")
+ or {key: round(float(value), 4) for key, value in probabilities.items()},
+ }
+
+
+def _clef_decide(
+ model,
+ tokenizer,
+ state,
+ questions: dict,
+ max_length = None,
+ predicted = False,
+) -> dict:
+ # One Decision API request over every question in one prefill, at served temperatures.
+ from .clef import encode_record, systemone_answer
+
+ tokenizer = getattr(tokenizer, "tokenizer", tokenizer)
+ max_length = int(max_length or model.decision_config.get("max_len", CLEF_MAX_LEN))
+ encoded = encode_record(
+ tokenizer, {"state": state, "questions": questions}, max_length = max_length
+ )
+ device = next(model.parameters()).device
+ amp_dtype = _clef_amp_dtype(model, device)
+ ids = torch.tensor([encoded.input_ids], device = device)
+ was_training = model.training
+ model.eval()
+ try:
+ with torch.autocast(device.type, dtype = amp_dtype, enabled = amp_dtype is not None):
+ logits, _ = model(input_ids = ids, attention_mask = torch.ones_like(ids), records = [encoded])
+ finally:
+ model.train(was_training)
+ rows = [
+ row[: len(question.option_ids)]
+ for question, row in zip(encoded.questions, logits.float().cpu())
+ ]
+ scales = _served_temperatures(
+ model.decision_config,
+ rows,
+ [
+ {"qtype": QUESTION_TYPES.index(questions[q.question_id]["type"])}
+ for q in encoded.questions
+ ],
+ )
+ answers = {}
+ for question, row, scale in zip(encoded.questions, rows, scales):
+ probabilities = dict(zip(question.option_ids, (row / scale).softmax(-1).tolist()))
+ asked = questions[question.question_id]
+ answer = systemone_answer(asked, probabilities)
+ answers[question.question_id] = (
+ _predicted(asked, answer, probabilities) if predicted else answer
+ )
+ return {
+ "answers": answers,
+ "input_tokens": len(encoded.input_ids),
+ "truncated": _clef_truncated(tokenizer, state, questions, encoded, max_length),
+ }
+
+
+def _clef_truncated(tokenizer, state, questions, encoded, max_length) -> bool:
+ # One spare token tells a cut state from one that fits exactly.
+ if len(encoded.input_ids) < max_length:
+ return False
+ from .clef import encode_record
+
+ record = {"state": state, "questions": questions}
+ return len(encode_record(tokenizer, record, max_length = max_length + 1).input_ids) > max_length
+
+
+def _laya_decide(
+ model,
+ tokenizer,
+ state,
+ questions: dict,
+ predicted = False,
+) -> dict:
+ from .clef import systemone_answer
+
+ common = _laya().common
+ config = model.decision_config
+ max_len = int(config.get("max_len", 512))
+ items, keys = [], []
+ for name, question in questions.items():
+ internal = _internal(question)
+ ids, markers = common.build_sequence(
+ tokenizer, _parsed(state), internal, max_len, int(config.get("head_max_len", 192))
+ )
+ if len(markers) != len(_option_keys(internal)):
+ raise DecisionDataError(f'"{name}" has more options than fit in {max_len} tokens')
+ items.append(
+ {
+ "input_ids": ids,
+ "markers": markers,
+ "qtype": common.QTYPES[internal["t"]],
+ "target": [0.0] * len(markers),
+ }
+ )
+ keys.append(_option_keys(internal))
+ logits = _logits(model, items, tokenizer.pad_token_id)
+ temperatures = _served_temperatures(config, logits, items)
+ answers = {}
+ for (name, question), z, t, options in zip(questions.items(), logits, temperatures, keys):
+ probabilities = dict(zip(options, torch.softmax(z / t, -1).tolist()))
+ answer = systemone_answer(question, probabilities)
+ answers[name] = _predicted(question, answer, probabilities) if predicted else answer
+ return {
+ "answers": answers,
+ "input_tokens": max(len(item["input_ids"]) for item in items),
+ "truncated": any(len(item["input_ids"]) >= max_len for item in items),
+ }
+
+
# Kept in 16-bit like unsloth/Qwen3.8-27B-unsloth-bnb-4bit: Clef's backbone is a merged
# fine-tune, not stock Qwen, so it is quantized on load with the same dynamic list.
CLEF_4BIT_SKIP_MODULES = (
@@ -696,10 +858,9 @@ def _clef_forced_float32(model) -> bool:
def _clef_amp_dtype(model, device):
- # Never fp16 autocast: the gated delta net overflows in pure fp16, so a model on Unsloth's
- # float32 path runs as Unsloth loaded it. Serving uses this too, to match calibration.
- amp_dtype = _amp_dtype(device)
- return None if amp_dtype != torch.bfloat16 or _clef_forced_float32(model) else amp_dtype
+ # As _clef_mixed_precision trains (serving uses it too): the float32 path runs as loaded (Qwen3.5's
+ # gated delta net overflows in fp16); anything else autocasts, fp16 on a T4.
+ return None if _clef_forced_float32(model) else _amp_dtype(device)
def _load_clef(
@@ -711,12 +872,40 @@ def _load_clef(
token,
use_gradient_checkpointing,
kwargs,
+ model_name = None,
):
from safetensors.torch import load_file
from .clef import JointSchemaHead
max_len = int(max_seq_length or CLEF_MAX_LEN)
+ config = {"layout": "clef", "max_len": max_len, "temperature": [1.0] * 3}
+ saved = folder / _DECISION_CONFIG
+ if saved.is_file():
+ config.update(json.loads(saved.read_text(encoding = "utf-8")), max_len = max_len)
+ # The parent run's training record does not describe the next fine-tune, as for Laya.
+ config.pop("training", None)
+ adapter = _is_clef_adapter(folder)
+ if adapter:
+ # LoRA adapters over the base LLM: the base comes from where it was trained from.
+ base = config.get("base_model") or json.loads(
+ (folder / _ADAPTER_CONFIG).read_text(encoding = "utf-8")
+ ).get("base_model_name_or_path")
+ if not base:
+ raise ValueError(f"Unsloth: {folder} has adapters but does not name their base model.")
+ if full_finetuning:
+ # PEFT would freeze the base and the adapters, leaving only the head to train.
+ raise ValueError(
+ f"Unsloth: {folder} holds LoRA adapters. Save it with save_pretrained_merged and "
+ "full finetune the merged folder instead."
+ )
+ config["base_model"] = str(base)
+ if config.get("base_revision"):
+ kwargs.setdefault("revision", config["base_revision"])
+ else:
+ # A later adapter save sits on these merged weights, not on what they were trained from.
+ config["base_model"] = str(model_name or folder)
+ config.pop("base_revision", None)
fast = _device().type != "cpu"
if fast:
from .loader import FastModel
@@ -727,6 +916,7 @@ def _load_clef(
_pin_device_map(kwargs)
# A float16 request (or a GPU without bfloat16) puts Qwen3.5 on Unsloth's float32 path,
# which stores bfloat16 weights: the gated delta net NaNs in pure float16.
+ # An adapter folder loads its base and the adapters through Unsloth's own PEFT path.
backbone, processor = FastModel.from_pretrained(
str(folder),
max_seq_length = max_len,
@@ -740,15 +930,27 @@ def _load_clef(
else:
from transformers import AutoConfig, AutoProcessor, AutoTokenizer
+ source = config["base_model"] if adapter else str(folder)
# Clef's own backbones are vision models; ones converted from a text-only LM are not.
- if getattr(AutoConfig.from_pretrained(str(folder)), "vision_config", None) is not None:
+ revision = {"revision": kwargs["revision"]} if adapter and kwargs.get("revision") else {}
+ if (
+ getattr(
+ AutoConfig.from_pretrained(source, token = token, **revision), "vision_config", None
+ )
+ is not None
+ ):
from transformers import AutoModelForImageTextToText as AutoClass
else:
from transformers import AutoModelForCausalLM as AutoClass
AutoProcessor = AutoTokenizer
- backbone = AutoClass.from_pretrained(str(folder), dtype = dtype or torch.float32)
+ backbone = AutoClass.from_pretrained(
+ source, dtype = dtype or torch.float32, token = token, **revision
+ )
+ if adapter:
+ from peft import PeftModel
+ backbone = PeftModel.from_pretrained(backbone, str(folder), is_trainable = True)
processor = AutoProcessor.from_pretrained(str(folder))
- if not full_finetuning:
+ if not full_finetuning and not adapter:
backbone.requires_grad_(False)
backbone.config.use_cache = False
head_config = json.loads((folder / _CLEF_HEAD_FILES[1]).read_text(encoding = "utf-8"))
@@ -757,21 +959,19 @@ def _load_clef(
device = next(backbone.parameters()).device
# The head trains in fp32 over the 16-bit backbone, as the Laya head does.
model = ClefDecisionModel(backbone, head.to(device = device, dtype = torch.float32))
- config = {"layout": "clef", "max_len": max_len, "temperature": [1.0] * 3}
- saved = folder / "unsloth_decision_config.json"
- if saved.is_file():
- config.update(json.loads(saved.read_text(encoding = "utf-8")), max_len = max_len)
- # The parent run's training record does not describe the next fine-tune, as for Laya.
- config.pop("training", None)
+ config["load_in_4bit"] = bool(load_in_4bit)
model.decision_config = config
_mark_full_finetuning(model, full_finetuning)
model._unsloth_forced_float32 = bool(getattr(backbone, "_unsloth_forced_float32", False))
model._unsloth_fast_backbone = fast
model._saved_temp_tokenizer = processor
- model._unsloth_source_folder = str(folder)
+ source = folder
+ if adapter:
+ from .decision_from_lm import _source_folder
+ source = _source_folder(config["base_model"], token, None, False) or folder
+ model._unsloth_source_folder = str(source)
model._unsloth_source_vocab = len(getattr(processor, "tokenizer", processor))
- model.save_pretrained_merged = types.MethodType(save_pretrained_merged, model)
- model.push_to_hub_merged = types.MethodType(push_to_hub_merged, model)
+ _attach_clef_saving(model)
return model, processor
@@ -880,14 +1080,12 @@ def _stamp_transformers_version(config_file: Path) -> None:
config_file.write_text(json.dumps(config, indent = 2) + "\n", encoding = "utf-8")
-def _save_clef(self, save_directory, tokenizer) -> None:
- import shutil
-
- from safetensors.torch import save_file
-
- output = Path(save_directory)
+def _clef_head_weights(self, exact = False) -> tuple:
+ # exact: a resumable trainer checkpoint, so float32 and no temperature folded in.
config = {**self.decision_config, "fine_tuned": True}
state = {k: v.detach().to("cpu", torch.float32) for k, v in self.head.state_dict().items()}
+ if exact:
+ return config, {k: v.contiguous() for k, v in state.items()}
# Folded in, so Cloudflare's loader serves calibrated confidences too; the per-type
# temperatures Unsloth applies are already relative to it.
temperature = config.pop("head_temperature", None)
@@ -906,12 +1104,43 @@ def _save_clef(self, save_directory, tokenizer) -> None:
f"Unsloth: head weight {name} is not finite, so the model cannot be saved."
)
weights[name] = value
+ return config, weights
+
+
+def _write_clef_head(self, staging: Path, config: dict, weights: dict) -> None:
+ from safetensors.torch import save_file
+
+ (staging / _DECISION_CONFIG).write_text(json.dumps(config, indent = 2), encoding = "utf-8")
+ (staging / _CLEF_HEAD_FILES[1]).write_text(
+ json.dumps(self.head.config, indent = 2), encoding = "utf-8"
+ )
+ save_file(weights, str(staging / _CLEF_HEAD_FILES[0]))
+
+
+# Cloudflare's joint_schema_model.py, vendored unmodified.
+_REFERENCE_CODE = Path(__file__).resolve().parents[1] / "_vendor" / "clef" / "joint_schema_model.py"
+_MERGED_FILES = ("config.json", "model*.safetensors", "model.safetensors.index.json")
+_ADAPTER_FILES = (_ADAPTER_CONFIG, "adapter_model.safetensors", "adapter_model.bin")
+
+
+def _save_clef(
+ self,
+ save_directory,
+ tokenizer,
+ exact = False,
+) -> None:
+ import shutil
+
+ output = Path(save_directory)
+ config, weights = _clef_head_weights(self, exact)
source = Path(getattr(self, "_unsloth_source_folder", "") or output)
with _staging(output) as staging:
encoder = self.encoder
if hasattr(encoder, "save_pretrained_merged"):
# Unsloth's merge dequantizes a 4-bit base and writes the processor files too.
encoder.save_pretrained_merged(str(staging), tokenizer, save_method = "merged_16bit")
+ # A merge with local_dir = the save folder leaves huggingface_hub's .cache behind.
+ shutil.rmtree(staging / ".cache", ignore_errors = True)
else:
if hasattr(encoder, "merge_and_unload"):
encoder = copy.deepcopy(encoder).merge_and_unload()
@@ -925,39 +1154,140 @@ def _save_clef(self, save_directory, tokenizer) -> None:
continue
if (source / name).is_file():
shutil.copyfile(source / name, staging / name)
+ # Cloudflare's loader is for Qwen3.5 vision backbones; ship it so the folder loads there too.
+ architectures = getattr(self._backbone().config, "architectures", None) or []
+ if (
+ "Qwen3_5ForConditionalGeneration" in architectures
+ and _REFERENCE_CODE.is_file()
+ and not (staging / "joint_schema_model.py").exists()
+ ):
+ shutil.copyfile(_REFERENCE_CODE, staging / "joint_schema_model.py")
_stamp_transformers_version(staging / "config.json")
- (staging / "unsloth_decision_config.json").write_text(
- json.dumps(config, indent = 2), encoding = "utf-8"
- )
- (staging / _CLEF_HEAD_FILES[1]).write_text(
- json.dumps(self.head.config, indent = 2), encoding = "utf-8"
- )
- save_file(weights, str(staging / _CLEF_HEAD_FILES[0]))
+ _write_clef_head(self, staging, config, weights)
_commit_staged(
- staging,
- output,
- _CLEF_HEAD_FILES[0],
- stale = ("model*.safetensors", "model.safetensors.index.json"),
+ staging, output, _CLEF_HEAD_FILES[0], stale = _MERGED_FILES[1:] + _ADAPTER_FILES
)
+def _save_clef_adapter(
+ self,
+ save_directory,
+ tokenizer,
+ exact = False,
+) -> None:
+ # Only the LoRA adapters, the head and the configs; from_pretrained puts them back on the base.
+ output = Path(save_directory)
+ config, weights = _clef_head_weights(self, exact)
+ with _staging(output) as staging:
+ self.encoder.save_pretrained(str(staging))
+ adapter_config = staging / _ADAPTER_CONFIG
+ if not adapter_config.is_file():
+ raise RuntimeError(f"Unsloth: the adapters were not saved to {output}.")
+ # Named as the user loaded it, not a local snapshot path or a pre-quantized mirror.
+ if config.get("base_model"):
+ adapter = json.loads(adapter_config.read_text(encoding = "utf-8"))
+ adapter["base_model_name_or_path"] = config["base_model"]
+ if config.get("base_revision"):
+ adapter["revision"] = config["base_revision"]
+ adapter_config.write_text(json.dumps(adapter, indent = 2), encoding = "utf-8")
+ tokenizer.save_pretrained(str(staging))
+ # A processor save can write a config.json of its own; this folder holds no merged weights.
+ (staging / "config.json").unlink(missing_ok = True)
+ _write_clef_head(self, staging, config, weights)
+ _commit_staged(staging, output, _CLEF_HEAD_FILES[0], stale = _MERGED_FILES)
+
+
+def _load_clef_checkpoint(model, folder: Path) -> None:
+ # Resumes a DecisionTrainer checkpoint: the adapters and the float32 head saved by _save.
+ from safetensors.torch import load_file
+
+ if hasattr(model.encoder, "peft_config"):
+ if not (folder / "adapter_model.safetensors").is_file():
+ raise NotImplementedError(
+ f"Unsloth: {folder} holds no LoRA adapters to resume this run from; start a new run."
+ )
+ from peft import set_peft_model_state_dict
+ set_peft_model_state_dict(
+ model.encoder, load_file(str(folder / "adapter_model.safetensors"))
+ )
+ else:
+ # A full finetune checkpoints merged weights (_save); tied embeddings may be stored once.
+ shards = sorted(folder.glob("model*.safetensors"))
+ if not shards:
+ raise NotImplementedError(f"Unsloth: {folder} holds no merged weights to resume from.")
+ state = {}
+ for shard in shards:
+ state.update(load_file(str(shard)))
+ missing, unexpected = model.encoder.load_state_dict(state, strict = False)
+ tied = {k for k in missing if "lm_head" in k or "embed" in k}
+ if unexpected or set(missing) - tied:
+ raise RuntimeError(
+ f"Unsloth: {folder} does not match this model "
+ f"(missing {sorted(set(missing) - tied)[:3]}, unexpected {sorted(unexpected)[:3]})."
+ )
+ device = next(model.head.parameters()).device
+ head = load_file(str(folder / _CLEF_HEAD_FILES[0]), device = str(device))
+ model.head.load_state_dict({k: v.float() for k, v in head.items()}, strict = True)
+
+
+def save_pretrained_clef(
+ self,
+ save_directory,
+ tokenizer = None,
+ **kwargs,
+) -> None:
+ # Adapters plus the head, as Unsloth's other models; a full finetune has none, so it saves merged.
+ tokenizer = self._saved_temp_tokenizer if tokenizer is None else tokenizer
+ if not hasattr(self.encoder, "peft_config"):
+ return _save_clef(self, save_directory, tokenizer)
+ return _save_clef_adapter(self, save_directory, tokenizer)
+
+
+def push_to_hub_clef(
+ self,
+ repo_id,
+ tokenizer = None,
+ token = None,
+ private = None,
+ **kwargs,
+) -> None:
+ from huggingface_hub import HfApi
+
+ api = HfApi(token = token)
+ repo_id = api.create_repo(repo_id, private = private, exist_ok = True).repo_id
+ with tempfile.TemporaryDirectory() as folder:
+ self.save_pretrained(folder, tokenizer)
+ api.upload_folder(folder_path = folder, repo_id = repo_id)
+ print(f"Unsloth: Saved the decision model to https://huggingface.co/{repo_id}")
+
+
+def _attach_clef_saving(model) -> None:
+ model.save_pretrained = types.MethodType(save_pretrained_clef, model)
+ model.save_pretrained_merged = types.MethodType(save_pretrained_merged, model)
+ model.push_to_hub = types.MethodType(push_to_hub_clef, model)
+ model.push_to_hub_merged = types.MethodType(push_to_hub_merged, model)
+
+
def _clef_mixed_precision(model, args) -> None:
# Unsloth's rule for Qwen3.5 (rl.py): on its float32 path a model never autocasts, since
- # float16 NaNs the gated delta net; otherwise its bfloat16 weights pair with bf16 only.
+ # float16 NaNs the gated delta net; bfloat16 weights pair with bf16 only; an fp16 load (T4) keeps fp16.
if _clef_forced_float32(model):
if args.fp16 or args.bf16:
print("Unsloth: Clef trains in float32 here, since Qwen3.5 cannot train in float16.")
args.fp16 = args.bf16 = False
- elif args.fp16:
+ elif args.fp16 and getattr(model._backbone(), "dtype", None) == torch.bfloat16:
print("Unsloth: Clef is in bfloat16, so fp16 = True is switched to bf16 = True.")
args.fp16, args.bf16 = False, True
- elif not args.bf16 and _clef_amp_dtype(model, next(model.parameters()).device) is not None:
- # float32 norms (UNSLOTH_HIGH_PRECISION_LAYERNORM) beside bfloat16 projections only run under autocast.
- args.bf16 = True
+ elif not args.fp16 and not args.bf16:
+ # float32 norms (UNSLOTH_HIGH_PRECISION_LAYERNORM) beside 16-bit projections only run under autocast.
+ amp = _clef_amp_dtype(model, next(model.parameters()).device)
+ args.bf16 = amp == torch.bfloat16
+ args.fp16 = amp == torch.float16
+ precision = "bf16" if args.bf16 else "fp16" if args.fp16 else "no"
# transformers 5 reads args.mixed_precision; 4.x reads this variable, set before the switches above.
- os.environ["ACCELERATE_MIXED_PRECISION"] = "bf16" if args.bf16 else "no"
+ os.environ["ACCELERATE_MIXED_PRECISION"] = precision
if hasattr(args, "mixed_precision"):
- args.mixed_precision = "bf16" if args.bf16 else "no"
+ args.mixed_precision = precision
class _LengthGroupedBatches(torch.utils.data.Sampler):
@@ -1114,6 +1444,37 @@ class DecisionTrainer(Trainer):
with compiled_encoder(self.model, forwards, amp_dtype, max_length):
return super().train(*args, **kwargs)
+ def _save(
+ self,
+ output_dir = None,
+ state_dict = None,
+ ):
+ if not getattr(self.model, "is_clef", False):
+ return super()._save(output_dir, state_dict)
+ # Adapters plus the head, not one state dict holding the (shared-weight) backbone.
+ output = Path(self.args.output_dir if output_dir is None else output_dir)
+ tokenizer = self.processing_class or self.model._saved_temp_tokenizer
+ if hasattr(self.model.encoder, "peft_config"):
+ _save_clef_adapter(self.model, output, tokenizer, exact = True)
+ else:
+ _save_clef(self.model, output, tokenizer, exact = True)
+ torch.save(self.args, str(output / "training_args.bin"))
+
+ def _load_from_checkpoint(
+ self,
+ resume_from_checkpoint,
+ model = None,
+ ):
+ model = self.model if model is None else model
+ if not getattr(model, "is_clef", False):
+ return super()._load_from_checkpoint(resume_from_checkpoint, model)
+ _load_clef_checkpoint(model, Path(resume_from_checkpoint))
+
+ def _load_best_model(self):
+ if not getattr(self.model, "is_clef", False):
+ return super()._load_best_model()
+ _load_clef_checkpoint(self.model, Path(self.state.best_model_checkpoint))
+
def _get_train_sampler(self, train_dataset = None):
dataset = self.train_dataset if train_dataset is None else train_dataset
# With one micro-batch per step, length grouping would make each step one question type.
@@ -1436,6 +1797,10 @@ class FastDecisionModel:
):
if load_in_8bit:
raise NotImplementedError("Unsloth: decision models do not support load_in_8bit.")
+ if kwargs.get("decision_head") is None and _is_plain_lm(
+ model_name, subfolder, token, revision, local_files_only
+ ):
+ kwargs["decision_head"] = "clef"
if kwargs.get("decision_head") is not None:
# A plain language model plus a fresh (or given) decision head: see decision_from_lm.py.
from .decision_from_lm import load_lm_as_decision_model
@@ -1472,6 +1837,7 @@ class FastDecisionModel:
token,
use_gradient_checkpointing,
kwargs,
+ model_name = model_name,
)
config = json.loads((folder / "rl_agent_config.json").read_text(encoding = "utf-8"))
# The base model's training record does not describe the fine-tune.
@@ -1628,7 +1994,7 @@ class FastDecisionModel:
) -> tuple:
max_len = int(model.decision_config.get("max_len", 512))
head_max_len = int(model.decision_config.get("head_max_len", 192))
- items, report, skips = [], {"total": 0, "skipped": 0, "reason": None}, {}
+ items, report, skips = [], {"total": 0, "skipped": 0, "reason": None, "truncated": 0}, {}
def skip(
index,
@@ -1688,6 +2054,14 @@ class FastDecisionModel:
report["reason"] = (
example if count == 1 else f"{example} (and {count - 1:,} more like it)"
)
+ # Over max_seq_length the end of the state is cut, never questions or options.
+ report["truncated"] = sum(len(item["input_ids"]) >= max_len for item in items)
+ if report["truncated"]:
+ print(
+ f"Unsloth: {report['truncated']:,} of {len(items):,} training inputs are longer than "
+ f"max_seq_length = {max_len}, so the end of their state is cut. Raise "
+ "max_seq_length to train on all of it."
+ )
return items, report
@staticmethod
@@ -1715,6 +2089,27 @@ class FastDecisionModel:
[item for item in items if item["row"] in held],
)
+ @staticmethod
+ def predict(model, tokenizer, state, questions: dict) -> dict:
+ """Answers one Decision API request: {name: answer} at the calibrated temperatures.
+ Each answer is the Decision API's (choice / confidence, score / legend, or noul) plus
+ "answer" (the option, True / False for noul, the level number for score) and
+ "probabilities" over every option. Works for Laya, Clef and converted language models."""
+ if not isinstance(questions, dict) or not questions:
+ raise DecisionDataError("questions must be a non-empty dict of name to question")
+ state = _parsed(state)
+ if getattr(model, "is_clef", False):
+ questions = {str(name): _clef_question(q) for name, q in questions.items()}
+ # Read up to CLEF_SERVE_MAX_LEN tokens, like serving, even past the training cut.
+ max_length = max(
+ int(model.decision_config.get("max_len", CLEF_MAX_LEN)), CLEF_SERVE_MAX_LEN
+ )
+ return _clef_decide(
+ model, tokenizer, state, questions, max_length = max_length, predicted = True
+ )["answers"]
+ tokenizer = getattr(tokenizer, "tokenizer", tokenizer)
+ return _laya_decide(model, tokenizer, state, questions, predicted = True)["answers"]
+
@staticmethod
def evaluate(
model,
diff --git a/unsloth/models/decision_from_lm.py b/unsloth/models/decision_from_lm.py
index 0be47e12882..62fdd534636 100644
--- a/unsloth/models/decision_from_lm.py
+++ b/unsloth/models/decision_from_lm.py
@@ -12,7 +12,6 @@ __all__ = [
]
import json
-import types
import warnings
from pathlib import Path
from typing import Optional
@@ -153,9 +152,8 @@ def load_lm_as_decision_model(
from .decision import (
CLEF_MAX_LEN,
ClefDecisionModel,
+ _attach_clef_saving,
_mark_full_finetuning,
- push_to_hub_merged,
- save_pretrained_merged,
)
if decision_head not in DECISION_HEADS:
@@ -206,6 +204,9 @@ def load_lm_as_decision_model(
"max_len": max_len,
"temperature": [1.0] * 3,
"base_model": str(model_name),
+ **({"base_revision": revision} if revision else {}),
+ # How the backbone loaded, so a server puts saved adapters back on the same base.
+ "load_in_4bit": bool(load_in_4bit),
}
_mark_full_finetuning(model, full_finetuning)
model._unsloth_forced_float32 = bool(getattr(backbone, "_unsloth_forced_float32", False))
@@ -214,38 +215,10 @@ def load_lm_as_decision_model(
model._unsloth_source_vocab = len(tokenizer)
source = _source_folder(model_name, token, revision, local_files_only)
model._unsloth_source_folder = str(source) if source is not None else ""
- model.save_pretrained_merged = types.MethodType(_save_with_reference_code, model)
- model.push_to_hub_merged = types.MethodType(push_to_hub_merged, model)
- model._unsloth_save_pretrained_merged = save_pretrained_merged
+ _attach_clef_saving(model)
return model, processor
-# Cloudflare's joint_schema_model.py, vendored unmodified.
-_REFERENCE_CODE = Path(__file__).resolve().parents[1] / "_vendor" / "clef" / "joint_schema_model.py"
-
-
-def _save_with_reference_code(
- self,
- save_directory,
- tokenizer = None,
- save_method = "merged_16bit",
- **kwargs,
-):
- import shutil
-
- self._unsloth_save_pretrained_merged(self, save_directory, tokenizer, save_method, **kwargs)
- # Cloudflare's loader is for Qwen3.5 vision backbones; ship it so the folder loads there too.
- output = Path(save_directory)
- architectures = getattr(self._backbone().config, "architectures", None) or []
- reference = _REFERENCE_CODE
- if (
- reference.is_file()
- and "Qwen3_5ForConditionalGeneration" in architectures
- and not (output / "joint_schema_model.py").exists()
- ):
- shutil.copyfile(reference, output / "joint_schema_model.py")
-
-
def freeze_backbone(model):
# Stage A of the from-LM recipe: train only the decision head on frozen backbone features.
frozen = [name for name, param in model.encoder.named_parameters() if param.requires_grad]