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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Unsloth Studio: export or convert a GGUF to FastFlowLM Q4NX for the AMD Ryzen AI NPU (#12541)
Leo Borcherding214f4e222893
diff --git a/pyproject.toml b/pyproject.tomlindex b5c0d687d52..a9efe4532cd 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -56,6 +56,7 @@ studio = ["*.bat","node_prebuilt_pins.json","lemonade_prebuilt_pins.json",+ "q4nx_converter_pins.json","src-tauri/icons/icon.icns","src-tauri/icons/icon.png","frontend/dist/**/*",diff --git a/studio/backend/core/export/export.py b/studio/backend/core/export/export.pyindex 0c30fce50e5..74b8b8b4e8c 100644--- a/studio/backend/core/export/export.py+++ b/studio/backend/core/export/export.py@@ -40,6 +40,7 @@ from utils.paths import (resolve_output_dir,)from core.inference import get_inference_backend+from core.export import q4nxfrom utils.paths.path_utils import any_not_appledouble_metadata, drop_appledouble_metadata# GPU/PyTorch-only imports, skipped on MLX and --no-torch installs so the module stays importable.@@ -1432,12 +1433,14 @@ class ExportBackend:hf_token: HfTokenArg = None,imatrix_file = None,private: bool = False,+ npu_q4nx: bool = False,) -> Tuple[bool, str, Optional[str]]:"""Export the model in GGUF format.``quantization_method`` is a single GGUF quant method ("Q4_K_M") or a list of them; a listproduces one GGUF per quant from a single model load, since unsloth save_to_gguf loops- internally. ``imatrix_file`` is an importance matrix path or boolean.+ internally. ``imatrix_file`` is an importance matrix path or boolean. ``npu_q4nx`` also+ converts one Q4_0 / Q4_1 / Q4_K_M GGUF to FastFlowLM's Q4NX for the AMD Ryzen AI NPU."""if not _export_runtime_available():return False, _export_runtime_message(), None@@ -1479,6 +1482,14 @@ class ExportBackend:if not quant_methods:quant_methods = ["q4_k_m"]quant_method = quant_methods if len(quant_methods) > 1 else quant_methods[0]+ if npu_q4nx and not save_directory:+ return False, "The AMD NPU (Q4NX) export needs a local save directory.", None+ if npu_q4nx and not any(q in q4nx.SOURCE_QUANTS for q in quant_methods):+ return (+ False,+ "The AMD NPU (Q4NX) export needs a Q4_0, Q4_1 or Q4_K_M GGUF in the selection.",+ None,+ )if save_directory:save_directory = str(resolve_export_write_dir(save_directory))@@ -1626,6 +1637,23 @@ class ExportBackend:self._write_export_metadata(abs_save_dir)output_path = str(Path(abs_save_dir).resolve())+ if npu_q4nx:+ source = q4nx.source_gguf(exported_ggufs, quant_methods)+ try:+ if source is None:+ raise RuntimeError("no Q4_0, Q4_1 or Q4_K_M GGUF was written")+ with q4nx.staged_output(Path(abs_save_dir) / "npu-q4nx") as staging:+ q4nx.convert_gguf_to_q4nx(source, staging)+ self._write_q4nx_companions(staging, exported_config)+ except Exception as exception:+ logger.error(f"Q4NX conversion failed: {exception}")+ return (+ False,+ f"GGUF files were saved to {output_path}, but the AMD NPU (Q4NX) "+ f"conversion failed: {exception}",+ output_path,+ )+if push_to_hub:if not repo_id or not hf_token:return (@@ -1716,6 +1744,22 @@ class ExportBackend:)return False, f"GGUF export failed: {str(e)}", None+ def _write_q4nx_companions(self, q4nx_dir: Path, config: Optional[bytes]) -> None:+ """The tokenizer files FastFlowLM loads next to model.q4nx (see q4nx.CONFIG_FILES)."""+ with tempfile.TemporaryDirectory(prefix = "_tmp_tokenizer_", dir = q4nx_dir) as scratch:+ self.current_tokenizer.save_pretrained(scratch)+ for name in q4nx.TOKENIZER_FILES:+ # The converter rebuilds tokenizer.json from the GGUF; the HF one is what FLM ships.+ if (Path(scratch) / name).is_file():+ shutil.copyfile(Path(scratch) / name, q4nx_dir / name)+ # generation_config holds stop ids config.json lacks (Phi-4-mini's <|end|>, 200020).+ generation = getattr(self.current_model, "generation_config", None)+ q4nx.write_flm_tokenizer_config(+ q4nx_dir,+ json.loads(config) if config else None,+ {"eos_token_id": getattr(generation, "eos_token_id", None)},+ )+def _save_mlx_adapter(self,destination: str,diff --git a/studio/backend/core/export/orchestrator.py b/studio/backend/core/export/orchestrator.pyindex 6e295db8a3f..bbf3a630d5e 100644--- a/studio/backend/core/export/orchestrator.py+++ b/studio/backend/core/export/orchestrator.py@@ -646,6 +646,7 @@ class ExportOrchestrator:hf_token: HfTokenArg = None,imatrix_file = None,private: bool = False,+ npu_q4nx: bool = False,) -> Tuple[bool, str, Optional[str]]:"""Export model in GGUF format. `quantization_method` may be a single method or a list."""return self._run_export(@@ -658,6 +659,7 @@ class ExportOrchestrator:"hf_token": hf_token,"imatrix_file": imatrix_file,"private": private,+ "npu_q4nx": npu_q4nx,},)diff --git a/studio/backend/core/export/q4nx.py b/studio/backend/core/export/q4nx.pynew file mode 100644index 00000000000..fd6959cf8db--- /dev/null+++ b/studio/backend/core/export/q4nx.py@@ -0,0 +1,261 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""FastFlowLM Q4NX output for the AMD Ryzen AI NPU (XDNA 2).++Kept free of torch/unsloth imports: the backend process converts an existing GGUF directly,+without loading a model into the export worker.+"""++from __future__ import annotations++import contextlib+import importlib.util+import json+import os+import shutil+import subprocess+import sys+import tempfile+import threading+from pathlib import Path+from typing import List, Optional++from loggers import get_logger++logger = get_logger(__name__)++# GGUF types FastFlowLM's Q4NX packs directly; any other quant is dequantized and rounded again.+SOURCE_QUANTS = ("q4_0", "q4_1", "q4_k_m")+# Loaded beside model.q4nx; FLM hard-exits without tokenizer_config.json.+TOKENIZER_FILES = ("tokenizer.json", "tokenizer_config.json", "chat_template.jinja")+# Read for token ids only. No config.json is written: FLM's own carries the flm_version its+# catalog checks, and one without it makes FLM delete the folder's weights and re-pull stock.+CONFIG_FILES = ("config.json", "generation_config.json")+CONVERTER_MODULES = ("torch", "gguf", "einops", "safetensors", "numpy", "mpmath")+++def _installer():+ studio_dir = Path(__file__).resolve().parents[3]+ if str(studio_dir) not in sys.path:+ sys.path.insert(0, str(studio_dir))+ import install_q4nx_converter++ return install_q4nx_converter+++def source_gguf(ggufs: List[str], quant_methods: List[str]) -> Optional[str]:+ """The exported GGUF to convert: the first selected quant Q4NX packs directly."""+ for quant in quant_methods:+ if quant not in SOURCE_QUANTS:+ continue+ for path in ggufs:+ if os.path.basename(path).lower().endswith(f".{quant}.gguf"):+ return path+ return None+++def require_converter_deps() -> None:+ """Raise before any download when this env cannot run the converter (e.g. --no-torch)."""+ missing = [m for m in CONVERTER_MODULES if importlib.util.find_spec(m) is None]+ if missing:+ raise RuntimeError(+ f"The Q4NX converter needs {', '.join(missing)}, which this Unsloth Studio install "+ "lacks (a GGUF-only install has no torch)."+ )+++def _gguf_architecture(gguf_path: str) -> str:+ import gguf+ field = gguf.GGUFReader(gguf_path).fields.get("general.architecture")+ return field.contents() if field is not None else ""+++# convert.py's __main__ overwrites sys.argv at the older pin, and importing it first is circular+# (q4nx.models.phi4 imports convert), so drive the package's own entry point.+_RUN_CONVERTER = (+ "import sys; from q4nx import create_converter; "+ "create_converter(sys.argv[1], '').convert(q4nx_path = sys.argv[2], weights_type = 'language')"+)+++def staged_output(out_dir: Path):+ """Yield a fresh folder to build into; its files replace ``out_dir``'s only on success,+ so a failed re-conversion keeps the previous export."""++ # Only the save directory is account-checked; a planted symlink here would redirect writes.+ def refuse_symlink():+ if out_dir.is_symlink():+ raise RuntimeError(f"Refusing to write Q4NX output through the symlink {out_dir}")++ refuse_symlink()+ out_dir.parent.mkdir(parents = True, exist_ok = True)+ staging = Path(tempfile.mkdtemp(prefix = f".{out_dir.name}-", dir = out_dir.parent))+ try:+ yield staging+ out_dir.mkdir(exist_ok = True)+ # Again at publish: the conversion is long enough for the folder to be swapped.+ refuse_symlink()+ # The last model's companions must not survive beside the new weights.+ for name in ("model.q4nx", "config.json", *TOKENIZER_FILES):+ (out_dir / name).unlink(missing_ok = True)+ for path in staging.iterdir():+ os.replace(path, out_dir / path.name)+ finally:+ shutil.rmtree(staging, ignore_errors = True)+++def convert_gguf_to_q4nx(gguf_path: str, out_dir: Path) -> None:+ from utils.paths.storage_roots import studio_root++ require_converter_deps()+ installer = _installer()+ name = installer.converter_for_architecture(_gguf_architecture(gguf_path))+ script = installer.install(studio_root() / "q4nx_converter", name = name)+ out_dir.mkdir(parents = True, exist_ok = True)+ logger.info(+ f"Converting {os.path.basename(gguf_path)} to Q4NX ({name}) for the AMD NPU in {out_dir}"+ )+ from utils.child_stdio import utf8_child_env+ from utils.process_lifetime import child_popen_kwargs, spawn_on_lifetime_thread+ from utils.subprocess_compat import windows_hidden_subprocess_kwargs++ # Dies with its parent: a cancelled export's worker must not leave a converter holding a model.+ process = spawn_on_lifetime_thread(+ lambda: subprocess.Popen(+ [sys.executable, "-c", _RUN_CONVERTER, gguf_path, str(out_dir)],+ cwd = str(script.parent),+ env = utf8_child_env(),+ stderr = subprocess.PIPE,+ text = True,+ encoding = "utf-8",+ errors = "replace",+ **windows_hidden_subprocess_kwargs(),+ **child_popen_kwargs(),+ )+ )+ _, stderr = process.communicate()+ if process.returncode != 0:+ tail = (stderr or "").strip().splitlines()+ raise RuntimeError(+ f"The Q4NX converter exited with code {process.returncode}"+ + (f": {tail[-1]}" if tail else "")+ )+ if not (out_dir / "model.q4nx").is_file():+ raise RuntimeError(f"The Q4NX converter wrote no model.q4nx to {out_dir}")+++def _fetch_base_file(base_model: str, name: str, token) -> Optional[Path]:+ local = Path(base_model).expanduser()+ if local.is_dir():+ from core.training.account_jobs import account_path++ candidate = local / name+ if not candidate.is_file():+ return None+ # Only the folder was account-checked; a file in it may link to another account's.+ account_path(candidate)+ return candidate+ from huggingface_hub import hf_hub_download+ from huggingface_hub.errors import EntryNotFoundError++ try:+ return Path(hf_hub_download(base_model, name, token = token))+ except EntryNotFoundError:+ return None+++def _gguf_chat_template(gguf_path: Path) -> Optional[str]:+ import gguf+ field = gguf.GGUFReader(str(gguf_path)).fields.get("tokenizer.chat_template")+ return field.contents() if field is not None else None+++def _token_ids(value) -> List[int]:+ values = value if isinstance(value, list) else [value]+ return [v for v in values if isinstance(v, int) and not isinstance(v, bool)]+++def _vocab_id(tokenizer_json: dict, token) -> Optional[int]:+ if isinstance(token, dict):+ token = token.get("content")+ if not isinstance(token, str):+ return None+ for added in tokenizer_json.get("added_tokens") or []:+ if added.get("content") == token:+ return added.get("id")+ vocab = (tokenizer_json.get("model") or {}).get("vocab")+ return vocab.get(token) if isinstance(vocab, dict) else None+++def write_flm_tokenizer_config(out_dir: Path, *configs: Optional[dict]) -> None:+ """Add the ids FastFlowLM exits without (an ``eos_token_id`` array, ``bos_token_id`` with a+ ``bos_token``); its uploads list the configs' stop ids too (Llama 3.2: 128001, 128008, 128009).+ """+ path = out_dir / "tokenizer_config.json"+ tokenizer_config = json.loads(path.read_text(encoding = "utf-8"))+ tokenizer_path = out_dir / "tokenizer.json"+ tokenizer_json = (+ json.loads(tokenizer_path.read_text(encoding = "utf-8")) if tokenizer_path.is_file() else {}+ )+ eos = _token_ids(_vocab_id(tokenizer_json, tokenizer_config.get("eos_token")))+ eos += _token_ids(tokenizer_config.get("eos_token_id"))+ for config in configs:+ eos += _token_ids((config or {}).get("eos_token_id"))+ if not eos:+ raise RuntimeError("FastFlowLM needs the end-of-sequence token id, and none was found.")+ tokenizer_config["eos_token_id"] = list(dict.fromkeys(eos))+ if tokenizer_config.get("bos_token") is not None and not _token_ids(+ tokenizer_config.get("bos_token_id")+ ):+ bos = _token_ids(_vocab_id(tokenizer_json, tokenizer_config["bos_token"]))+ for config in configs:+ bos += _token_ids((config or {}).get("bos_token_id"))+ if not bos:+ raise RuntimeError("FastFlowLM needs the bos_token id, and none was found.")+ tokenizer_config["bos_token_id"] = bos[0]+ path.write_text(+ json.dumps(tokenizer_config, indent = 2, ensure_ascii = False) + "\n", encoding = "utf-8"+ )+++# One conversion at a time: each holds a whole model in RAM, and retries must not interleave.+_CONVERT_LOCK = threading.Lock()+++def _read_json(path: Optional[Path]) -> Optional[dict]:+ return json.loads(path.read_text(encoding = "utf-8")) if path is not None else None+++def convert_existing_gguf(+ gguf_path: Path,+ base_model: str,+ save_directory: Path,+ token = None,+) -> Path:+ """Convert a GGUF already on disk; tokenizer files come from ``base_model``.++ ``base_model`` is the original (non-GGUF) Hub repo or a local model folder. Returns the+ folder to copy over a FastFlowLM catalog model of the same family and size.+ """+ out_dir = Path(save_directory) / f"{gguf_path.stem}-q4nx"+ found = {+ name: _fetch_base_file(base_model, name, token)+ for name in (*CONFIG_FILES, *TOKENIZER_FILES)+ }+ if found["tokenizer_config.json"] is None:+ raise RuntimeError(f"{base_model} has no tokenizer_config.json, which FastFlowLM needs.")+ with _CONVERT_LOCK, staged_output(out_dir) as staging:+ convert_gguf_to_q4nx(str(gguf_path), staging)+ for name in TOKENIZER_FILES:+ # The HF tokenizer.json replaces the one the converter rebuilds from the GGUF.+ if found[name] is not None:+ shutil.copyfile(found[name], staging / name)+ if found["chat_template.jinja"] is None:+ config = json.loads((staging / "tokenizer_config.json").read_text(encoding = "utf-8"))+ template = config.get("chat_template") or _gguf_chat_template(gguf_path)+ if template and not config.get("chat_template"):+ (staging / "chat_template.jinja").write_text(template, encoding = "utf-8")+ write_flm_tokenizer_config(staging, *(_read_json(found[name]) for name in CONFIG_FILES))+ return out_dirdiff --git a/studio/backend/core/export/worker.py b/studio/backend/core/export/worker.pyindex a76c60cb0e8..3a814b3e1bb 100644--- a/studio/backend/core/export/worker.py+++ b/studio/backend/core/export/worker.py@@ -459,6 +459,7 @@ def _handle_export(backend, cmd: dict, resp_queue: Any) -> None:hf_token = cmd.get("hf_token"),imatrix_file = cmd.get("imatrix_file"),private = cmd.get("private", False),+ npu_q4nx = cmd.get("npu_q4nx", False),)elif export_type == "lora":success, message, output_path = backend.export_lora_adapter(diff --git a/studio/backend/models/__init__.py b/studio/backend/models/__init__.pyindex e5d423ef6b1..42c03255b62 100644--- a/studio/backend/models/__init__.py+++ b/studio/backend/models/__init__.py@@ -40,6 +40,7 @@ from .export import (ExportMergedModelRequest,ExportBaseModelRequest,ExportGGUFRequest,+ ConvertQ4NXRequest,ExportLoRAAdapterRequest,LlmCompressorExportProbeResponse,)@@ -98,6 +99,7 @@ __all__ = ["ExportMergedModelRequest","ExportBaseModelRequest","ExportGGUFRequest",+ "ConvertQ4NXRequest","ExportLoRAAdapterRequest","LlmCompressorExportProbeResponse","Token",diff --git a/studio/backend/models/export.py b/studio/backend/models/export.pyindex 96806c43eea..6d42fc0189e 100644--- a/studio/backend/models/export.py+++ b/studio/backend/models/export.py@@ -230,6 +230,32 @@ class ExportGGUFRequest(BaseModel):False,description = "If True, create a private Hugging Face Hub repository",)+ npu_q4nx: bool = Field(+ False,+ description = "Also convert one Q4_0 / Q4_1 / Q4_K_M GGUF to FastFlowLM's Q4NX for the "+ "AMD Ryzen AI NPU, written to <save_directory>/npu-q4nx.",+ )+++class ConvertQ4NXRequest(BaseModel):+ """Convert a GGUF that already exists to FastFlowLM Q4NX, without loading a model."""++ save_directory: str = Field(..., description = "Directory the Q4NX folder is written into")++ @field_validator("save_directory", mode = "before")+ @classmethod+ def _check_save_directory(cls, v):+ return _validate_save_directory(v)++ gguf_path: Optional[str] = Field(None, description = "A local .gguf file")+ repo_id: Optional[str] = Field(None, description = "Hub repo holding the GGUF, with filename")+ filename: Optional[str] = Field(None, description = "GGUF file in repo_id")+ base_model: str = Field(+ ...,+ description = "The original (non-GGUF) Hub repo or local model folder; FastFlowLM needs "+ "its config.json and tokenizer files.",+ )+ hf_token: Optional[str] = Field(None, description = "Hugging Face token for gated repos")class ExportLoRAAdapterRequest(ExportCommonOptions):diff --git a/studio/backend/routes/export.py b/studio/backend/routes/export.pyindex 0df873c1314..6894ee95ec2 100644--- a/studio/backend/routes/export.py+++ b/studio/backend/routes/export.py@@ -5,6 +5,7 @@from core.training.account_jobs import (account_event_stream,+ account_path,job_busy,job_is_foreign,require_job_owner,@@ -49,6 +50,7 @@ from models import (ExportBaseModelRequest,ExportGGUFRequest,ExportLoRAAdapterRequest,+ ConvertQ4NXRequest,LlmCompressorExportProbeResponse,)@@ -496,6 +498,7 @@ async def export_gguf(),imatrix_file = imatrix_file,private = request.private,+ npu_q4nx = request.npu_q4nx,)if not success:@@ -520,6 +523,65 @@ async def export_gguf()[email protected]("/convert/q4nx", response_model = ExportOperationResponse)+async def convert_q4nx(+ request: ConvertQ4NXRequest,+ current_subject: str = Depends(get_current_subject),+ allow_ambient: bool = Depends(allow_ambient_hf_token),+):+ """Convert an existing GGUF (local file or Hub repo) to FastFlowLM Q4NX for the AMD NPU.++ Needs no loaded checkpoint or GPU, so it runs here rather than in the export worker.+ """+ validate_job_paths(request.model_dump())+ # A managed account may only read a GGUF inside its own workspace.+ account_path(request.gguf_path)+ if bool(request.gguf_path) == bool(request.repo_id and request.filename):+ raise HTTPException(+ status_code = 400,+ detail = "Give either a local gguf_path or a repo_id with a filename.",+ )+ token = _resolve_export_hf_token(request.hf_token, allow_ambient = allow_ambient)+ base_model = request.base_model.strip()+ # The shared HF cache can hold another account's private repo: check this caller's access.+ hub_repos = [request.repo_id] if request.repo_id else []+ if not Path(base_model).expanduser().is_dir():+ hub_repos.append(base_model)+ for repo in hub_repos:+ await asyncio.to_thread(account_access.authorize_download, repo, "model", token)++ def run() -> str:+ from core.export import q4nx+ from utils.paths import resolve_export_write_dir++ q4nx.require_converter_deps()+ if request.gguf_path:+ source = Path(request.gguf_path)+ if not source.is_file() or source.suffix.lower() != ".gguf":+ raise ValueError(f"{source} is not a .gguf file.")+ else:+ from huggingface_hub import hf_hub_download+ source = Path(hf_hub_download(request.repo_id, request.filename, token = token))+ out = q4nx.convert_existing_gguf(+ source,+ base_model,+ Path(resolve_export_write_dir(request.save_directory)),+ token = token,+ )+ return str(out.resolve())++ try:+ output_path = await asyncio.to_thread(run)+ except Exception as e:+ logger.error(f"Q4NX conversion failed: {e}", exc_info = True)+ raise HTTPException(status_code = 400, detail = f"Q4NX conversion failed: {e}")+ return ExportOperationResponse(+ success = True,+ message = "Converted to Q4NX for the AMD NPU",+ details = await asyncio.to_thread(_export_details, output_path, refresh_index = True),+ )++@router.post("/export/lora", response_model = ExportOperationResponse)async def export_lora_adapter(request: ExportLoRAAdapterRequest,diff --git a/studio/backend/tests/test_export_absolute_paths.py b/studio/backend/tests/test_export_absolute_paths.pyindex 6005a559867..6110ed3a2d2 100644--- a/studio/backend/tests/test_export_absolute_paths.py+++ b/studio/backend/tests/test_export_absolute_paths.py@@ -116,6 +116,7 @@ def _install_lightweight_backend_stubs(monkeypatch):monkeypatch.setitem(sys.modules, "core", core_pkg)monkeypatch.setitem(sys.modules, "core.export", core_export)monkeypatch.setitem(sys.modules, "core.inference", core_inference)+ core_export.q4nx = _load_module("core.export.q4nx", "core/export/q4nx.py", monkeypatch)_load_module("core.inference.model_ids","core/inference/model_ids.py",@@ -207,6 +208,7 @@ def _install_lightweight_backend_stubs(monkeypatch):"ExportMergedModelRequest","ExportBaseModelRequest","ExportGGUFRequest",+ "ConvertQ4NXRequest","ExportLoRAAdapterRequest","LlmCompressorExportProbeResponse",):diff --git a/studio/backend/tests/test_export_npu_q4nx.py b/studio/backend/tests/test_export_npu_q4nx.pynew file mode 100644index 00000000000..b66e4fb8ce5--- /dev/null+++ b/studio/backend/tests/test_export_npu_q4nx.py@@ -0,0 +1,421 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""GGUF export can also write a FastFlowLM Q4NX folder for the AMD Ryzen AI NPU.++Reuses the harness in test_export_gguf_discovery.py; the converter itself is stubbed.+"""++from __future__ import annotations++import json+import sys+from pathlib import Path++import pytest++_TESTS_DIR = Path(__file__).resolve().parent+if str(_TESTS_DIR) not in sys.path:+ sys.path.insert(0, str(_TESTS_DIR))++from test_export_gguf_discovery import _backend, _gguf # noqa: E402+++_HF_TOKENIZER = {"added_tokens": [{"id": 7, "content": "<|im_end|>"}], "model": {"vocab": {}}}+++class _Tokenizer:+ def save_pretrained(self, path):+ path = Path(path)+ (path / "tokenizer.json").write_text(json.dumps(_HF_TOKENIZER))+ (path / "tokenizer_config.json").write_text(+ '{"eos_token": "<|im_end|>", "bos_token": null}'+ )+ for name in ("chat_template.jinja", "special_tokens_map.json"):+ (path / name).write_text(f"hf {name}")+++class _Model:+ # Like Phi-4-mini: the chat-turn stop id is only in generation_config.+ generation_config = type("G", (), {"eos_token_id": [7, 9]})()++ def __init__(self):+ self.calls = 0++ def save_pretrained_gguf(self, model_save_path, tokenizer, quantization_method):+ self.calls += 1+ out = Path(model_save_path)+ out.mkdir(parents = True)+ (out / "config.json").write_text('{"model_type": "qwen3"}')+ quants = (+ quantization_method if isinstance(quantization_method, list) else [quantization_method]+ )+ return {"gguf_files": [str(_gguf(out / f"Model.{q.upper()}.gguf")) for q in quants]}+++def _fake_converter(+ export_mod,+ monkeypatch,+ calls,+ fail = False,+):+ def convert(gguf_path, out_dir):+ if fail:+ raise RuntimeError("unsupported architecture")+ calls.append(Path(gguf_path).name)+ out_dir.mkdir(parents = True, exist_ok = True)+ (out_dir / "model.q4nx").write_bytes(b"q4nx")+ (out_dir / "tokenizer.json").write_text('{"added_tokens": []}')++ monkeypatch.setattr(export_mod.q4nx, "convert_gguf_to_q4nx", convert)+++def test_q4nx_folder_matches_the_flm_layout(monkeypatch, tmp_path):+ model = _Model()+ export_mod, backend, save_dir, _cwd = _backend(monkeypatch, tmp_path, model)+ backend.current_tokenizer = _Tokenizer()+ calls = []+ _fake_converter(export_mod, monkeypatch, calls)++ success, message, output_path = backend.export_gguf(+ str(save_dir), ["q8_0", "q4_1", "q4_k_m"], npu_q4nx = True+ )++ assert success is True, message+ assert calls == ["Model.Q4_1.gguf"]+ q4nx = save_dir / "npu-q4nx"+ # No config.json: copied over a catalog model it would drop FLM's flm_version.+ assert sorted(p.name for p in q4nx.iterdir()) == [+ "chat_template.jinja",+ "model.q4nx",+ "tokenizer.json",+ "tokenizer_config.json",+ ]+ assert json.loads((q4nx / "tokenizer.json").read_text()) == _HF_TOKENIZER+ tokenizer_config = json.loads((q4nx / "tokenizer_config.json").read_text())+ assert tokenizer_config["eos_token_id"] == [7, 9]+ assert output_path == str(save_dir.resolve())+++def test_no_q4nx_source_quant_fails_before_exporting(monkeypatch, tmp_path):+ model = _Model()+ _m, backend, save_dir, _cwd = _backend(monkeypatch, tmp_path, model)++ success, message, output_path = backend.export_gguf(str(save_dir), ["q8_0"], npu_q4nx = True)++ assert success is False+ assert "Q4_0, Q4_1 or Q4_K_M" in message+ assert model.calls == 0+ assert output_path is None+++def test_a_failed_conversion_keeps_and_reports_the_ggufs(monkeypatch, tmp_path):+ export_mod, backend, save_dir, _cwd = _backend(monkeypatch, tmp_path, _Model())+ backend.current_tokenizer = _Tokenizer()+ _fake_converter(export_mod, monkeypatch, [], fail = True)++ success, message, output_path = backend.export_gguf(str(save_dir), "q4_0", npu_q4nx = True)++ assert success is False+ assert "GGUF files were saved" in message and "unsupported architecture" in message+ assert (save_dir / "Model.Q4_0.gguf").is_file()+ assert output_path == str(save_dir.resolve())+++def test_without_the_flag_nothing_is_converted(monkeypatch, tmp_path):+ export_mod, backend, save_dir, _cwd = _backend(monkeypatch, tmp_path, _Model())+ calls = []+ _fake_converter(export_mod, monkeypatch, calls)++ success, message, _out = backend.export_gguf(str(save_dir), "q4_1")++ assert success is True, message+ assert calls == []+ assert not (save_dir / "npu-q4nx").exists()+++def test_source_follows_the_selection_order(monkeypatch, tmp_path):+ export_mod, _b, _s, _c = _backend(monkeypatch, tmp_path, object())+ ggufs = ["/x/M.Q4_0.gguf", "/x/M.Q4_K_M.gguf", "/x/M.Q8_0.gguf"]+ assert export_mod.q4nx.source_gguf(ggufs, ["q8_0", "q4_k_m", "q4_0"]) == "/x/M.Q4_K_M.gguf"+ assert export_mod.q4nx.source_gguf(ggufs, ["q8_0"]) is None+++def _stub_installer(+ export_mod,+ monkeypatch,+ tmp_path,+ architecture = "qwen3",+):+ """Installer stub recording which pinned converter each architecture asked for."""+ real = export_mod.q4nx._installer()+ installed = []++ class _Installer:+ converter_for_architecture = staticmethod(real.converter_for_architecture)++ @staticmethod+ def install(root, name):+ installed.append(name)+ script = tmp_path / name / "convert.py"+ script.parent.mkdir(exist_ok = True)+ return script++ monkeypatch.setattr(export_mod.q4nx, "_installer", lambda: _Installer)+ monkeypatch.setattr(export_mod.q4nx, "_gguf_architecture", lambda _p: architecture)+ monkeypatch.setattr(export_mod.q4nx, "require_converter_deps", lambda: None)+ return installed+++def _fake_popen(+ export_mod,+ monkeypatch,+ returncode = 0,+ stderr = "",+):+ ran = {}++ class _Popen:+ def __init__(self, cmd, cwd, **kwargs):+ ran.update(cmd = cmd, cwd = cwd, preexec_fn = kwargs.get("preexec_fn"), env = kwargs.get("env"))+ self.returncode = returncode+ if returncode == 0:+ (Path(cmd[-1]) / "model.q4nx").write_bytes(b"q4nx")++ def communicate(self):+ return None, stderr++ monkeypatch.setattr(export_mod.q4nx.subprocess, "Popen", _Popen)+ return ran+++ "architecture, converter", [("qwen3", "q4nx"), ("llama", "q4nx"), ("qwen35", "q4k")]+)+def test_converter_runs_in_this_interpreter(monkeypatch, tmp_path, architecture, converter):+ export_mod, _b, _s, _c = _backend(monkeypatch, tmp_path, object())+ installed = _stub_installer(export_mod, monkeypatch, tmp_path, architecture)+ ran = _fake_popen(export_mod, monkeypatch)+ out = tmp_path / "out"+ export_mod.q4nx.convert_gguf_to_q4nx("/x/M.Q4_1.gguf", out)++ assert installed == [converter]+ assert ran["cmd"][:2] == [sys.executable, "-c"]+ assert ran["cmd"][3:] == ["/x/M.Q4_1.gguf", str(out)]+ assert ran["cwd"] == str(tmp_path / converter)+ assert ran["env"]["PYTHONIOENCODING"] == "utf-8"+ if sys.platform.startswith("linux"):+ # Dies with its parent: cancelling an export must not orphan a converter.+ assert callable(ran["preexec_fn"])+++def test_a_symlinked_output_folder_is_refused(monkeypatch, tmp_path):+ export_mod, _b, _s, _c = _backend(monkeypatch, tmp_path, object())+ elsewhere = tmp_path / "elsewhere"+ elsewhere.mkdir()+ link = tmp_path / "exports" / "M.Q4_1-q4nx"+ link.parent.mkdir()+ link.symlink_to(elsewhere, target_is_directory = True)++ with pytest.raises(RuntimeError, match = "symlink"):+ with export_mod.q4nx.staged_output(link) as staging:+ (staging / "model.q4nx").write_bytes(b"q4nx")+ assert list(elsewhere.iterdir()) == []+++def test_a_symlink_planted_during_conversion_is_refused_at_publish(monkeypatch, tmp_path):+ export_mod, _b, _s, _c = _backend(monkeypatch, tmp_path, object())+ elsewhere = tmp_path / "elsewhere"+ elsewhere.mkdir()+ (elsewhere / "model.q4nx").write_bytes(b"someone else's")+ out = tmp_path / "exports" / "M.Q4_1-q4nx"++ with pytest.raises(RuntimeError, match = "symlink"):+ with export_mod.q4nx.staged_output(out) as staging:+ (staging / "model.q4nx").write_bytes(b"q4nx")+ out.symlink_to(elsewhere, target_is_directory = True)+ assert (elsewhere / "model.q4nx").read_bytes() == b"someone else's"+++def test_a_reconversion_replaces_the_previous_model_files(monkeypatch, tmp_path):+ export_mod, _b, _s, _c = _backend(monkeypatch, tmp_path, object())+ out = tmp_path / "out"+ out.mkdir()+ for stale in ("chat_template.jinja", "config.json", "model.q4nx", "notes.txt"):+ (out / stale).write_text("previous model")++ with export_mod.q4nx.staged_output(out) as staging:+ (staging / "model.q4nx").write_bytes(b"new")++ assert sorted(p.name for p in out.iterdir()) == ["model.q4nx", "notes.txt"]+ assert (out / "model.q4nx").read_bytes() == b"new"+ assert [p.name for p in tmp_path.iterdir() if p.name.startswith(".out-")] == []+++def test_a_failed_reconversion_keeps_the_previous_export(monkeypatch, tmp_path):+ export_mod, _b, _s, _c = _backend(monkeypatch, tmp_path, object())+ out = tmp_path / "out"+ out.mkdir()+ (out / "model.q4nx").write_bytes(b"previous")+ (out / "tokenizer_config.json").write_text("previous")++ with pytest.raises(RuntimeError, match = "converter died"):+ with export_mod.q4nx.staged_output(out) as staging:+ (staging / "model.q4nx").write_bytes(b"partial")+ raise RuntimeError("converter died")++ assert (out / "model.q4nx").read_bytes() == b"previous"+ assert (out / "tokenizer_config.json").read_text() == "previous"+ assert [p.name for p in tmp_path.iterdir() if p.name.startswith(".out-")] == []+++def test_converter_failure_names_its_last_stderr_line(monkeypatch, tmp_path):+ export_mod, _b, _s, _c = _backend(monkeypatch, tmp_path, object())+ _stub_installer(export_mod, monkeypatch, tmp_path)++ _fake_popen(+ export_mod,+ monkeypatch,+ returncode = 1,+ stderr = "Traceback ...\nValueError: Unsupported model architecture: mistral3\n",+ )++ with pytest.raises(RuntimeError, match = "Unsupported model architecture: mistral3"):+ export_mod.q4nx.convert_gguf_to_q4nx("/x/M.Q4_1.gguf", tmp_path / "out")+++def test_missing_converter_deps_fail_before_installing(monkeypatch, tmp_path):+ export_mod, _b, _s, _c = _backend(monkeypatch, tmp_path, object())+ q4nx = export_mod.q4nx+ real_find_spec = q4nx.importlib.util.find_spec+ monkeypatch.setattr(+ q4nx.importlib.util,+ "find_spec",+ lambda name, *a: None if name in ("torch", "einops") else real_find_spec(name, *a),+ )+ monkeypatch.setattr(q4nx, "_installer", lambda: pytest.fail("installer must not run"))++ with pytest.raises(RuntimeError, match = "torch, einops"):+ q4nx.convert_gguf_to_q4nx("/x/M.Q4_1.gguf", tmp_path / "out")+++def _base_folder(tmp_path, files):+ base = tmp_path / "base"+ base.mkdir()+ for name, text in files.items():+ (base / name).write_text(text)+ return base+++def test_existing_gguf_takes_companions_from_the_base_model(monkeypatch, tmp_path):+ export_mod, _b, _s, _c = _backend(monkeypatch, tmp_path, object())+ _fake_converter(export_mod, monkeypatch, calls := [])+ monkeypatch.setattr(export_mod.q4nx, "_gguf_chat_template", lambda _p: "{{ gguf }}")+ tokenizer = json.dumps({"added_tokens": [{"id": 3, "content": "x"}]})+ base = _base_folder(+ tmp_path,+ {+ "config.json": '{"eos_token_id": 5}',+ "generation_config.json": '{"eos_token_id": [5, 6]}',+ "tokenizer.json": tokenizer,+ "tokenizer_config.json": '{"eos_token": "x"}',+ },+ )+ gguf = _gguf(tmp_path / "hub" / "Qwen3-0.6B-Q4_1.gguf")++ out = export_mod.q4nx.convert_existing_gguf(gguf, str(base), tmp_path / "exports")++ assert out == tmp_path / "exports" / "Qwen3-0.6B-Q4_1-q4nx"+ assert calls == ["Qwen3-0.6B-Q4_1.gguf"]+ assert (out / "tokenizer.json").read_text() == tokenizer+ assert not (out / "config.json").exists()+ # FLM exits without an eos_token_id array; the tokenizer's eos comes first, then the configs'.+ assert json.loads((out / "tokenizer_config.json").read_text())["eos_token_id"] == [3, 5, 6]+ # Neither the base folder nor its tokenizer_config carries a template, so the GGUF's is used.+ assert (out / "chat_template.jinja").read_text() == "{{ gguf }}"+++def test_existing_gguf_keeps_a_template_already_in_tokenizer_config(monkeypatch, tmp_path):+ export_mod, _b, _s, _c = _backend(monkeypatch, tmp_path, object())+ _fake_converter(export_mod, monkeypatch, [])+ base = _base_folder(+ tmp_path,+ {"config.json": '{"eos_token_id": 2}', "tokenizer_config.json": '{"chat_template": "t"}'},+ )++ out = export_mod.q4nx.convert_existing_gguf(_gguf(tmp_path / "m.gguf"), str(base), tmp_path)++ assert not (out / "chat_template.jinja").exists()+++def test_a_bos_token_gets_the_id_flm_requires(monkeypatch, tmp_path):+ q4nx = _backend(monkeypatch, tmp_path, object())[0].q4nx+ (tmp_path / "tokenizer.json").write_text(+ json.dumps({"added_tokens": [{"id": 128000, "content": "<|begin_of_text|>"}]})+ )+ (tmp_path / "tokenizer_config.json").write_text(+ '{"bos_token": "<|begin_of_text|>", "eos_token": "<|eot_id|>"}'+ )++ q4nx.write_flm_tokenizer_config(tmp_path, {"eos_token_id": [128001, 128008, 128009]})++ config = json.loads((tmp_path / "tokenizer_config.json").read_text())+ assert config["bos_token_id"] == 128000+ assert config["eos_token_id"] == [128001, 128008, 128009]+++def test_no_eos_id_anywhere_fails(monkeypatch, tmp_path):+ q4nx = _backend(monkeypatch, tmp_path, object())[0].q4nx+ (tmp_path / "tokenizer_config.json").write_text('{"eos_token": "<unknown>"}')+ with pytest.raises(RuntimeError, match = "end-of-sequence"):+ q4nx.write_flm_tokenizer_config(tmp_path, None, {})+++def test_standalone_conversions_do_not_overlap(monkeypatch, tmp_path):+ import threading+ import time++ export_mod, _b, _s, _c = _backend(monkeypatch, tmp_path, object())+ active, overlaps = [0], []++ def convert(gguf_path, out_dir):+ active[0] += 1+ overlaps.append(active[0])+ time.sleep(0.2)+ out_dir.mkdir(parents = True, exist_ok = True)+ (out_dir / "model.q4nx").write_bytes(b"q4nx")+ active[0] -= 1++ monkeypatch.setattr(export_mod.q4nx, "convert_gguf_to_q4nx", convert)+ monkeypatch.setattr(export_mod.q4nx, "_gguf_chat_template", lambda _p: None)+ base = _base_folder(+ tmp_path, {"config.json": '{"eos_token_id": 2}', "tokenizer_config.json": "{}"}+ )+ gguf = _gguf(tmp_path / "m.gguf")+ threads = [+ threading.Thread(+ target = export_mod.q4nx.convert_existing_gguf,+ args = (gguf, str(base), tmp_path / f"out{i % 2}"),+ )+ for i in range(3)+ ]+ for t in threads:+ t.start()+ for t in threads:+ t.join()++ assert overlaps == [1, 1, 1]+++def test_existing_gguf_without_tokenizer_config_fails_before_converting(monkeypatch, tmp_path):+ export_mod, _b, _s, _c = _backend(monkeypatch, tmp_path, object())+ _fake_converter(export_mod, monkeypatch, calls := [])+ base = _base_folder(tmp_path, {"config.json": "{}"})++ try:+ export_mod.q4nx.convert_existing_gguf(_gguf(tmp_path / "m.gguf"), str(base), tmp_path)+ except RuntimeError as e:+ assert "tokenizer_config.json" in str(e)+ else:+ raise AssertionError("expected a RuntimeError")+ assert calls == []diff --git a/studio/backend/tests/test_export_q4nx_accounts.py b/studio/backend/tests/test_export_q4nx_accounts.pynew file mode 100644index 00000000000..0d98e71b4f4--- /dev/null+++ b/studio/backend/tests/test_export_q4nx_accounts.py@@ -0,0 +1,118 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""A managed account converts to Q4NX only from GGUFs inside its own workspace."""++from __future__ import annotations++import asyncio++import pytest+from fastapi import HTTPException++from models import ConvertQ4NXRequest+from routes import export as export_routes+from utils.account_context import OWNER, AccountContext, arun_as+from utils.paths import workspace_root++ALICE = AccountContext("alice-q4nx-account", "alice")+BOB = AccountContext("bob-q4nx-account", "bob")+++def _convert(+ account,+ gguf_path = None,+ **fields,+):+ request = ConvertQ4NXRequest(+ save_directory = "q4nx",+ gguf_path = str(gguf_path) if gguf_path else None,+ base_model = fields.pop("base_model", "unsloth/Qwen3-0.6B"),+ hf_token = "own-token",+ **fields,+ )+ return asyncio.run(+ arun_as(account, export_routes.convert_q4nx(request, "subject", allow_ambient = False))+ )+++def authorized(monkeypatch):+ checked = []+ monkeypatch.setattr(+ export_routes.account_access,+ "authorize_download",+ lambda repo, repo_type, token: checked.append(repo),+ )+ return checked+++def converted(monkeypatch, authorized):+ calls = []+ real_to_thread = asyncio.to_thread++ async def to_thread(fn, *args, **kwargs):+ if fn is export_routes.account_access.authorize_download:+ return await real_to_thread(fn, *args, **kwargs)+ calls.append(fn)+ raise RuntimeError("stop before converting")++ monkeypatch.setattr(export_routes.asyncio, "to_thread", to_thread)+ return calls+++def test_hub_repos_are_authorized_for_the_caller_before_converting(converted, authorized):+ with pytest.raises(HTTPException):+ _convert(ALICE, repo_id = "org/private-GGUF", filename = "m.Q4_1.gguf")+ assert authorized == ["org/private-GGUF", "unsloth/Qwen3-0.6B"]+++def test_a_refused_hub_repo_stops_before_converting(monkeypatch, converted):+ def refuse(repo, repo_type, token):+ raise HTTPException(status_code = 404, detail = "Repository not found")++ monkeypatch.setattr(export_routes.account_access, "authorize_download", refuse)+ with pytest.raises(HTTPException) as exc:+ _convert(ALICE, repo_id = "org/private-GGUF", filename = "m.Q4_1.gguf")+ assert exc.value.status_code == 404+ assert converted == []+++def test_a_companion_symlink_out_of_the_workspace_is_refused(tmp_path):+ from core.export import q4nx+ from utils.account_context import run_as++ base = run_as(ALICE, workspace_root) / "models" / "base"+ base.mkdir(parents = True, exist_ok = True)+ secret = tmp_path / "other_account_template.jinja"+ secret.write_text("private")+ link = base / "chat_template.jinja"+ link.unlink(missing_ok = True)+ link.symlink_to(secret)++ with pytest.raises(HTTPException) as exc:+ run_as(ALICE, q4nx._fetch_base_file, str(base), "chat_template.jinja", None)+ assert exc.value.status_code == 403+ assert run_as(OWNER, q4nx._fetch_base_file, str(base), "chat_template.jinja", None) == link+++def test_managed_account_cannot_convert_another_accounts_gguf(converted):+ from utils.account_context import run_as++ foreign = run_as(BOB, workspace_root) / "exports" / "private.Q4_1.gguf"+ with pytest.raises(HTTPException) as exc:+ _convert(ALICE, foreign)+ assert exc.value.status_code == 403+ assert converted == []+++def test_managed_account_and_owner_reach_the_converter_for_allowed_paths(converted):+ from utils.account_context import run_as++ own = run_as(ALICE, workspace_root) / "exports" / "mine.Q4_1.gguf"+ for account, path in ((ALICE, own), (OWNER, "/anywhere/model.Q4_1.gguf")):+ with pytest.raises(HTTPException) as exc:+ _convert(account, path)+ assert exc.value.status_code == 400 and "stop before converting" in exc.value.detail+ assert len(converted) == 2diff --git a/studio/frontend/src/features/export/api/export-api.ts b/studio/frontend/src/features/export/api/export-api.tsindex 2b67d3faeab..8d2a5cd168b 100644--- a/studio/frontend/src/features/export/api/export-api.ts+++ b/studio/frontend/src/features/export/api/export-api.ts@@ -176,6 +176,8 @@ export async function exportGGUF(params: {imatrix?: boolean;imatrix_path?: string | null;private?: boolean;+ /** Also convert a Q4_0/Q4_1/Q4_K_M GGUF to Q4NX for the AMD NPU, into <save_directory>/npu-q4nx. */+ npu_q4nx?: boolean;}): Promise<ExportOperationResponse> {const response = await authFetch("/api/export/export/gguf", {method: "POST",@@ -185,6 +187,24 @@ export async function exportGGUF(params: {return parseJson<ExportOperationResponse>(response);}+/** Convert a GGUF that already exists (local file or Hub repo) to Q4NX for the AMD NPU. */+export async function convertGgufToQ4nx(params: {+ save_directory: string;+ gguf_path?: string | null;+ repo_id?: string | null;+ filename?: string | null;+ /** Original (non-GGUF) repo or local folder that supplies config.json and the tokenizer files. */+ base_model: string;+ hf_token?: string | null;+}): Promise<ExportOperationResponse> {+ const response = await authFetch("/api/export/convert/q4nx", {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify(params),+ });+ return parseJson<ExportOperationResponse>(response);+}+export async function exportLoRA(params: {save_directory: string;push_to_hub?: boolean;diff --git a/studio/frontend/src/features/export/components/q4nx-convert-card.tsx b/studio/frontend/src/features/export/components/q4nx-convert-card.tsxnew file mode 100644index 00000000000..94eaca3e657--- /dev/null+++ b/studio/frontend/src/features/export/components/q4nx-convert-card.tsx@@ -0,0 +1,155 @@+// 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 { SectionCard } from "@/components/section-card";+import { Button } from "@/components/ui/button";+import { Input } from "@/components/ui/input";+import { Spinner } from "@/components/ui/spinner";+import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";+import { hfApiToken, useHfTokenStore } from "@/features/hub";+import { CpuIcon } from "@hugeicons/core-free-icons";+import { HugeiconsIcon } from "@hugeicons/react";+import { useState } from "react";+import { convertGgufToQ4nx } from "../api/export-api";++type Source = "hub" | "local";++// unsloth/Qwen3-0.6B-GGUF -> unsloth/Qwen3-0.6B, the repo holding config.json and the tokenizer.+function baseRepoFor(repoId: string): string {+ return repoId.trim().replace(/-GGUF$/i, "");+}++function Field({+ id,+ label,+ ...props+}: { id: string; label: string } & React.ComponentProps<typeof Input>) {+ return (+ <div className="space-y-1.5">+ <label htmlFor={id} className="text-sm font-medium">+ {label}+ </label>+ <Input id={id} {...props} />+ </div>+ );+}++export function Q4nxConvertCard() {+ const hfToken = useHfTokenStore((s) => s.token);+ const [source, setSource] = useState<Source>("hub");+ const [repoId, setRepoId] = useState("");+ const [filename, setFilename] = useState("");+ const [ggufPath, setGgufPath] = useState("");+ const [baseModel, setBaseModel] = useState<string | null>(null);+ const [saveDirectory, setSaveDirectory] = useState("q4nx");+ const [running, setRunning] = useState(false);+ const [result, setResult] = useState<{ ok: boolean; text: string } | null>(+ null,+ );++ const effectiveBase =+ baseModel ?? (source === "hub" ? baseRepoFor(repoId) : "");+ const sourceReady =+ source === "hub" ? repoId.trim() && filename.trim() : ggufPath.trim();+ const canConvert =+ !running && sourceReady && effectiveBase.trim() && saveDirectory.trim();++ async function handleConvert() {+ setRunning(true);+ setResult(null);+ try {+ const response = await convertGgufToQ4nx({+ save_directory: saveDirectory.trim(),+ gguf_path: source === "local" ? ggufPath.trim() : null,+ repo_id: source === "hub" ? repoId.trim() : null,+ filename: source === "hub" ? filename.trim() : null,+ base_model: effectiveBase.trim(),+ hf_token: hfApiToken(hfToken) ?? null,+ });+ setResult({+ ok: true,+ text: `Saved to ${response.details?.output_path ?? saveDirectory}`,+ });+ } catch (error) {+ setResult({+ ok: false,+ text: error instanceof Error ? error.message : String(error),+ });+ } finally {+ setRunning(false);+ }+ }++ return (+ <SectionCard+ icon={<HugeiconsIcon icon={CpuIcon} className="size-5" />}+ title="Convert a GGUF to Q4NX (AMD NPU)"+ description="Turn a Q4_0, Q4_1 or Q4_K_M GGUF you already have into a FastFlowLM folder for Ryzen AI NPUs (XDNA 2). No training or GPU needed."+ className="mt-6"+ >+ <Tabs value={source} onValueChange={(v) => setSource(v as Source)}>+ <TabsList>+ <TabsTrigger value="hub">Hugging Face</TabsTrigger>+ <TabsTrigger value="local">Local file</TabsTrigger>+ </TabsList>+ </Tabs>+ <div className="grid gap-4 sm:grid-cols-2">+ {source === "hub" ? (+ <>+ <Field+ id="q4nx-repo"+ label="GGUF repo"+ placeholder="unsloth/Qwen3-0.6B-GGUF"+ value={repoId}+ onChange={(e) => setRepoId(e.target.value)}+ />+ <Field+ id="q4nx-file"+ label="GGUF file"+ placeholder="Qwen3-0.6B-Q4_1.gguf"+ value={filename}+ onChange={(e) => setFilename(e.target.value)}+ />+ </>+ ) : (+ <Field+ id="q4nx-path"+ label="GGUF file path"+ placeholder="/path/to/model.Q4_1.gguf"+ value={ggufPath}+ onChange={(e) => setGgufPath(e.target.value)}+ />+ )}+ <Field+ id="q4nx-base"+ label="Original model (config and tokenizer)"+ placeholder="unsloth/Qwen3-0.6B"+ value={effectiveBase}+ onChange={(e) => setBaseModel(e.target.value)}+ />+ <Field+ id="q4nx-save"+ label="Save directory"+ value={saveDirectory}+ onChange={(e) => setSaveDirectory(e.target.value)}+ />+ </div>+ <div className="flex items-center justify-between gap-3">+ <p+ className={+ result?.ok === false+ ? "text-xs text-destructive"+ : "text-xs text-muted-foreground"+ }+ >+ {result?.text ??+ "Runs as a drop-in for a FastFlowLM catalog model of the same family and size."}+ </p>+ <Button disabled={!canConvert} onClick={handleConvert}>+ {running && <Spinner />}+ Convert+ </Button>+ </div>+ </SectionCard>+ );+}diff --git a/studio/frontend/src/features/export/constants.ts b/studio/frontend/src/features/export/constants.tsindex 93ab3576da4..92f8af52151 100644--- a/studio/frontend/src/features/export/constants.ts+++ b/studio/frontend/src/features/export/constants.ts@@ -47,6 +47,8 @@ export const QUANT_OPTIONS: {{ value: "iq4_xs", label: "IQ4_XS", imatrix: true },{ value: "q2_k_l", label: "Q2_K_L" },{ value: "q3_k_m", label: "Q3_K_M" },+ { value: "q4_0", label: "Q4_0" },+ { value: "q4_1", label: "Q4_1" },{ value: "q4_k_m", label: "Q4_K_M", recommended: true },{ value: "q5_k_m", label: "Q5_K_M" },{ value: "q6_k", label: "Q6_K" },@@ -221,6 +223,9 @@ export function mergedFormatPayload(value: string): {return { formatType: "16-bit (FP16)", compressedMethod: opt.value };}+/** GGUF quants FastFlowLM's Q4NX converter packs directly for the AMD Ryzen AI NPU. */+export const Q4NX_SOURCE_QUANTS = ["q4_0", "q4_1", "q4_k_m"];+/*** llama.cpp effective bits-per-weight per quant; GGUF size ~= fp16_bytes * bpw / 16.* K-quant values are published average bit-rates (Q2_K_L = Unsloth Q2_K + Q8_0@@ -233,6 +238,8 @@ export const GGUF_BPW: Record<string, number> = {iq4_xs: 4.25,q2_k_l: 3.35,q3_k_m: 3.91,+ q4_0: 4.5,+ q4_1: 5.0,q4_k_m: 4.83,q5_k_m: 5.67,q6_k: 6.56,diff --git a/studio/frontend/src/features/export/export-page.tsx b/studio/frontend/src/features/export/export-page.tsxindex c3754bb64e4..96e7a0298cf 100644--- a/studio/frontend/src/features/export/export-page.tsx+++ b/studio/frontend/src/features/export/export-page.tsx@@ -67,6 +67,7 @@ import type { ModelCheckpoints } from "./api/export-api";import { adapterCompatibilityTip, type AdapterFormat } from "./constants";import { ExportRunPanel } from "./components/export-run-panel";import { MethodPicker } from "./components/method-picker";+import { Q4nxConvertCard } from "./components/q4nx-convert-card";import { QuantPicker } from "./components/quant-picker";import {EXPORT_METHODS,@@ -74,6 +75,7 @@ import {GUIDE_STEPS,MERGED_FORMATS,type MergedFormatOption,+ Q4NX_SOURCE_QUANTS,QUANT_OPTIONS,buildQuantSizeLabels,getEstimatedSize,@@ -215,6 +217,7 @@ export function ExportPage() {});// GGUF importance matrix (required for the IQ quants) and merged-export precision.const [useImatrix, setUseImatrix] = useState(false);+ const [npuQ4nx, setNpuQ4nx] = useState(false);const [customImatrix, setCustomImatrix] = useState({ sourceKey: "", path: "" });// Merged precision: one or more MERGED_FORMATS values exported in one run; seeded like exportMethod.const [selectedFormats, setSelectedFormats] = useState<string[]>(() => {@@ -276,12 +279,18 @@ export function ExportPage() {(q) => QUANT_OPTIONS.find((o) => o.value === q)?.imatrix,);const effectiveImatrix = useImatrix || requiresImatrix;+ const q4nxSourceSelected = quantLevels.some((q) =>+ Q4NX_SOURCE_QUANTS.includes(q),+ );// Whether the inline export panel is expanded. The panel also shows itself whenever a run is// active/terminal (see `panelActive`), so it survives navigation even though this flag resets.const [panelOpen, setPanelOpen] = useState(false);const [destination, setDestination] = useState<"local" | "hub">("local");+ // The converter writes beside the GGUFs, so a Hub-only export has nowhere to put it.+ const effectiveNpuQ4nx =+ npuQ4nx && q4nxSourceSelected && destination === "local";const [customSaveDirectory, setCustomSaveDirectory] = useState<string | null>(null,);@@ -819,6 +828,7 @@ export function ExportPage() {quantLevels,useImatrix: effectiveImatrix,imatrixPath,+ npuQ4nx: effectiveNpuQ4nx,mergedSelections: selectedFormats.map((v) => ({...mergedFormatPayload(v),label: MERGED_FORMATS.find((f) => f.value === v)?.label ?? v,@@ -856,6 +866,7 @@ export function ExportPage() {quantLevels,effectiveImatrix,imatrixPath,+ effectiveNpuQ4nx,selectedFormats,hubMultiFormat,ggufAsLora,@@ -1793,6 +1804,26 @@ export function ExportPage() {</p></div>)}+ <div className="flex items-center justify-between gap-3 rounded-lg border p-3">+ <div className="space-y-0.5">+ <div className="text-sm font-medium">+ Also convert to Q4NX (AMD NPU)+ </div>+ <div className="text-xs text-muted-foreground">+ {destination !== "local"+ ? "Saves locally only: pick a local destination."+ : q4nxSourceSelected+ ? "Converts the Q4 GGUF into a FastFlowLM folder for Ryzen AI NPUs (XDNA 2), next to the GGUFs."+ : "Needs Q4_0, Q4_1 or Q4_K_M in the selection."}+ </div>+ </div>+ <Switch+ aria-label="Also convert to Q4NX (AMD NPU)"+ checked={effectiveNpuQ4nx}+ onCheckedChange={setNpuQ4nx}+ disabled={!q4nxSourceSelected || destination !== "local"}+ />+ </div></>)}</div>@@ -1872,6 +1903,7 @@ export function ExportPage() {</>)}</SectionCard>+ <Q4nxConvertCard /></main></div>);diff --git a/studio/frontend/src/features/export/stores/export-runtime-store.ts b/studio/frontend/src/features/export/stores/export-runtime-store.tsindex 2394a4ec7b9..5fb43052122 100644--- a/studio/frontend/src/features/export/stores/export-runtime-store.ts+++ b/studio/frontend/src/features/export/stores/export-runtime-store.ts@@ -142,6 +142,8 @@ export interface RunExportParams {/** GGUF: use an importance matrix, auto-downloaded unless imatrixPath is set; required for the IQ quants. */useImatrix?: boolean;imatrixPath?: string;+ /** GGUF: also write a FastFlowLM Q4NX folder for the AMD Ryzen AI NPU. */+ npuQ4nx?: boolean;/** Merged: precision formats, each exported to its own sibling directory. Defaults to 16-bit.* `label` is the display name for the success banner's per-format output line. */mergedSelections?: {@@ -504,9 +506,14 @@ export const useExportRuntimeStore = create<ExportRuntimeStore>()((set, get) =>? params.imatrixPath?.trim() || null: null,private: params.privateRepo,+ npu_q4nx: params.npuQ4nx,}),);if (outputPath) outputs.push({ label: "GGUF", path: outputPath });+ if (outputPath && params.npuQ4nx) {+ const sep = outputPath.includes("\\") ? "\\" : "/";+ outputs.push({ label: "AMD NPU (Q4NX)", path: `${outputPath}${sep}npu-q4nx` });+ }if (!isCurrent()) return;set({ quantIndex: get().quantTotal });} else if (params.exportMethod === "lora") {diff --git a/studio/install_q4nx_converter.py b/studio/install_q4nx_converter.pynew file mode 100644index 00000000000..44e2651d3b3--- /dev/null+++ b/studio/install_q4nx_converter.py@@ -0,0 +1,183 @@+#!/usr/bin/env python3+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Install the pinned FLM Q4NX converter the first time an NPU export asks for it.++The converter is pure Python and runs in Studio's own environment (torch, gguf, einops,+safetensors), so this only fetches and verifies its source archive at a pinned commit.++Two commits are pinned. "q4nx" writes the Q4_0 / Q4_1 layout FastFlowLM's aie2p catalog+models use (it reproduces Qwen3-0.6B-NPU2/model.q4nx byte for byte); the later "q4k" commit+adds the Q4_K layout of the Qwen3.5 / 3.6 catalog but re-packs Q4_0 / Q4_1 in an order those+older engines read as noise.+"""++from __future__ import annotations++import argparse+import hashlib+import json+import os+import shutil+import sys+import tempfile+import threading+import urllib.request+from pathlib import Path+from typing import Optional++_STUDIO_DIR = os.path.dirname(os.path.abspath(__file__))+if _STUDIO_DIR not in sys.path:+ sys.path.insert(0, _STUDIO_DIR)++import prebuilt_core as core # noqa: E402+from backend.utils.auth_safe import auth_safe_open # noqa: E402++PINS_PATH = Path(_STUDIO_DIR) / "q4nx_converter_pins.json"+MARKER_NAME = "UNSLOTH_Q4NX_CONVERTER_INFO.json"+_CHUNK = 1 << 20+_DOWNLOAD_TIMEOUT_S = 60+++class Q4nxInstallCancelled(RuntimeError):+ pass+++def _read_pins(path: Path) -> dict:+ with open(path, encoding = "utf-8") as handle:+ pins = json.load(handle)+ if pins.get("schema_version") != 2:+ raise RuntimeError(f"{path} has an unsupported schema_version.")+ return pins+++def load_pins(path: Path = PINS_PATH, name: str = "q4nx") -> dict:+ """The named converter's pin, flattened with the repo."""+ pins = _read_pins(path)+ return {"repo": pins["repo"], "name": name, **pins["converters"][name]}+++def converter_for_architecture(architecture: str, path: Path = PINS_PATH) -> str:+ """Name of the pinned converter for a GGUF ``general.architecture``."""+ q4k = _read_pins(path).get("q4k_architectures", [])+ return "q4k" if (architecture or "").lower() in q4k else "q4nx"+++def archive_url(pins: dict) -> str:+ return f"https://codeload.github.com/{pins['repo']}/tar.gz/{pins['commit']}"+++def install_dir(root: Path, pins: Optional[dict] = None) -> Path:+ pins = pins or load_pins()+ return Path(root) / pins["commit"][:12]+++def installed_converter(root: Path, pins: Optional[dict] = None) -> Optional[Path]:+ """convert.py of a complete install matching the pin, else None."""+ pins = pins or load_pins()+ target = install_dir(root, pins)+ try:+ marker = json.loads((target / MARKER_NAME).read_text(encoding = "utf-8"))+ except (OSError, ValueError):+ return None+ if marker.get("commit") != pins["commit"] or marker.get("sha256") != pins["archive_sha256"]:+ return None+ script = target / "convert.py"+ return script if script.is_file() and (target / "q4nx").is_dir() else None+++def _download(+ url: str, destination: Path, *, expected_sha256: str, cancel: Optional[threading.Event]+) -> None:+ digest = hashlib.sha256()+ request = urllib.request.Request(url, headers = {"User-Agent": "unsloth-studio"})+ with (+ auth_safe_open(request, timeout = _DOWNLOAD_TIMEOUT_S) as response,+ open(destination, "wb") as handle,+ ):+ while True:+ if cancel is not None and cancel.is_set():+ raise Q4nxInstallCancelled("Q4NX converter download cancelled.")+ chunk = response.read(_CHUNK)+ if not chunk:+ break+ handle.write(chunk)+ digest.update(chunk)+ actual = digest.hexdigest()+ if actual != expected_sha256:+ raise core.ReleaseIntegrityError(+ f"{url} has sha256 {actual}, expected {expected_sha256}; refusing to install it."+ )+++def install(+ root: Path,+ *,+ name: str = "q4nx",+ cancel: Optional[threading.Event] = None,+ pins_path: Path = PINS_PATH,+ url: Optional[str] = None,+) -> Path:+ """Install the named pinned converter under root/<commit>, reusing a matching install."""+ pins = load_pins(pins_path, name)+ root = Path(root)+ target = install_dir(root, pins)+ with core.install_lock(core.install_lock_path(target)):+ existing = installed_converter(root, pins)+ if existing is not None:+ return existing+ root.mkdir(parents = True, exist_ok = True)+ with tempfile.TemporaryDirectory(prefix = ".q4nx-install-", dir = root) as scratch:+ scratch_dir = Path(scratch)+ archive = scratch_dir / "converter.tar.gz"+ _download(+ url or archive_url(pins),+ archive,+ expected_sha256 = pins["archive_sha256"],+ cancel = cancel,+ )+ extracted = scratch_dir / "extracted"+ extracted.mkdir()+ core.extract_archive(archive, extracted)+ scripts = sorted(extracted.rglob("convert.py"))+ if not scripts:+ raise RuntimeError("The Q4NX converter archive does not contain convert.py.")+ payload = scripts[0].parent+ (payload / MARKER_NAME).write_text(+ json.dumps(+ {+ "repo": pins["repo"],+ "commit": pins["commit"],+ "sha256": pins["archive_sha256"],+ },+ indent = 2,+ )+ + "\n",+ encoding = "utf-8",+ )+ if target.exists():+ shutil.rmtree(target)+ os.replace(payload, target)+ script = installed_converter(root, pins)+ if script is None:+ raise RuntimeError(f"Q4NX converter install at {target} did not verify.")+ return script+++def main(argv: Optional[list[str]] = None) -> int:+ parser = argparse.ArgumentParser(description = __doc__.splitlines()[0])+ parser.add_argument(+ "--root",+ type = Path,+ default = Path.home() / ".unsloth" / "studio" / "q4nx_converter",+ help = "Directory that holds one subdirectory per pinned converter commit.",+ )+ parser.add_argument("--name", choices = ("q4nx", "q4k"), default = "q4nx")+ args = parser.parse_args(argv)+ print(install(args.root, name = args.name))+ return 0+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/studio/q4nx_converter_pins.json b/studio/q4nx_converter_pins.jsonnew file mode 100644index 00000000000..1463ffc6f0d--- /dev/null+++ b/studio/q4nx_converter_pins.json@@ -0,0 +1,17 @@+{+ "schema_version": 2,+ "repo": "ROCm/FLM_Q4NX_Converter",+ "converters": {+ "q4nx": {+ "commit": "dd0993cc0801c6ef98fbd57d64b8895c0730517f",+ "archive_sha256": "08e610e638e0bed5b07b22c97c8127b7ebea6d191f42428a5f11ca5a7e773e79",+ "archive_size": 41472+ },+ "q4k": {+ "commit": "d1d5232d0b82871bf5265e990fa2d26cdad22327",+ "archive_sha256": "eddec67fa3a2d8441b403d490b2ff83278b1aac17b6e5887951fd15b06af7d4b",+ "archive_size": 49414+ }+ },+ "q4k_architectures": ["qwen35", "qwen35moe"]+}diff --git a/tests/studio/install/test_install_q4nx_converter.py b/tests/studio/install/test_install_q4nx_converter.pynew file mode 100644index 00000000000..44f9aed1f64--- /dev/null+++ b/tests/studio/install/test_install_q4nx_converter.py@@ -0,0 +1,144 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Test pin verification, atomic install and reuse of the Q4NX converter with a local server."""++from __future__ import annotations++import hashlib+import io+import json+import re+import sys+import tarfile+import threading+from functools import partial+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer+from pathlib import Path++import pytest++STUDIO_DIR = Path(__file__).resolve().parents[3] / "studio"+if str(STUDIO_DIR) not in sys.path:+ sys.path.insert(0, str(STUDIO_DIR))++import install_q4nx_converter as qc # noqa: E402++COMMIT = "c" * 40+++def _archive(directory: Path) -> Path:+ top = f"FLM_Q4NX_Converter-{COMMIT}"+ files = {f"{top}/convert.py": b"print('ok')\n", f"{top}/q4nx/__init__.py": b""}+ path = directory / "converter.tar.gz"+ with tarfile.open(path, "w:gz") as archive:+ for name, data in files.items():+ info = tarfile.TarInfo(name)+ info.size = len(data)+ archive.addfile(info, io.BytesIO(data))+ return path+++def served(tmp_path):+ archive = _archive(tmp_path)+ sha = hashlib.sha256(archive.read_bytes()).hexdigest()+ httpd = ThreadingHTTPServer(+ ("127.0.0.1", 0), partial(SimpleHTTPRequestHandler, directory = str(tmp_path))+ )+ httpd.requests = 0+ original = httpd.finish_request++ def counted(*args, **kwargs):+ httpd.requests += 1+ return original(*args, **kwargs)++ httpd.finish_request = counted+ thread = threading.Thread(target = httpd.serve_forever, daemon = True)+ thread.start()+ url = f"http://127.0.0.1:{httpd.server_address[1]}/{archive.name}"++ def pins(digest: str = sha, commit: str = COMMIT) -> Path:+ path = tmp_path / "pins.json"+ pin = {"commit": commit, "archive_sha256": digest, "archive_size": archive.stat().st_size}+ path.write_text(+ json.dumps(+ {+ "schema_version": 2,+ "repo": "ROCm/FLM_Q4NX_Converter",+ "converters": {"q4nx": pin, "q4k": {**pin, "commit": "e" * 40}},+ "q4k_architectures": ["qwen35", "qwen35moe"],+ }+ )+ )+ return path++ yield pins, url, httpd+ httpd.shutdown()+ httpd.server_close()+++def test_install_verifies_and_marks(tmp_path, served):+ pins, url, _ = served+ path = pins()+ script = qc.install(tmp_path / "root", pins_path = path, url = url)+ assert script == qc.installed_converter(tmp_path / "root", qc.load_pins(path))+ assert script.parent.name == COMMIT[:12]+ assert (script.parent / "q4nx" / "__init__.py").is_file()+++def test_a_complete_install_is_not_downloaded_again(tmp_path, served):+ pins, url, httpd = served+ path = pins()+ qc.install(tmp_path / "root", pins_path = path, url = url)+ before = httpd.requests+ qc.install(tmp_path / "root", pins_path = path, url = url)+ assert httpd.requests == before+++def test_digest_mismatch_installs_nothing(tmp_path, served):+ pins, url, _ = served+ path = pins(digest = "0" * 64)+ with pytest.raises(qc.core.ReleaseIntegrityError):+ qc.install(tmp_path / "root", pins_path = path, url = url)+ assert qc.installed_converter(tmp_path / "root", qc.load_pins(path)) is None+++def test_a_new_pin_replaces_the_install(tmp_path, served):+ pins, url, _ = served+ qc.install(tmp_path / "root", pins_path = pins(), url = url)+ repinned = qc.load_pins(pins(commit = "d" * 40))+ assert qc.installed_converter(tmp_path / "root", repinned) is None+++def test_each_named_converter_installs_into_its_own_commit_dir(tmp_path, served):+ pins, url, _ = served+ path = pins()+ q4nx = qc.install(tmp_path / "root", name = "q4nx", pins_path = path, url = url)+ q4k = qc.install(tmp_path / "root", name = "q4k", pins_path = path, url = url)+ assert (q4nx.parent.name, q4k.parent.name) == (COMMIT[:12], "e" * 12)+++def test_only_qwen35_architectures_take_the_q4k_converter(tmp_path, served):+ pins, _, _ = served+ path = pins()+ assert qc.converter_for_architecture("qwen35", path) == "q4k"+ assert qc.converter_for_architecture("qwen35moe", path) == "q4k"+ for architecture in ("qwen3", "llama", "gemma3", "lfm2", "phi3", "qwen2", ""):+ assert qc.converter_for_architecture(architecture, path) == "q4nx"++[email protected]("name", ["q4nx", "q4k"])+def test_shipped_pins_are_full_commits_and_digests(name):+ pins = qc.load_pins(name = name)+ assert pins["repo"] == "ROCm/FLM_Q4NX_Converter"+ assert re.fullmatch(r"[0-9a-f]{40}", pins["commit"])+ assert re.fullmatch(r"[0-9a-f]{64}", pins["archive_sha256"])+ assert qc.archive_url(pins).endswith(f"/tar.gz/{pins['commit']}")+++def test_shipped_q4nx_pin_predates_the_q4_1_repack():+ # d1d5232 re-packed Q4_0 / Q4_1 in an order FastFlowLM's aie2p engines read as noise; the+ # q4nx pin must stay on the commit that reproduces Qwen3-0.6B-NPU2/model.q4nx.+ assert qc.load_pins(name = "q4nx")["commit"].startswith("dd0993c")+ assert qc.load_pins(name = "q4k")["commit"].startswith("d1d5232")diff --git a/tests/test_installer_interactive_prompts.py b/tests/test_installer_interactive_prompts.pyindex 1695aea267c..2271670dfe3 100644--- a/tests/test_installer_interactive_prompts.py+++ b/tests/test_installer_interactive_prompts.py@@ -51,6 +51,7 @@ SCANNED_SCRIPTS = ENTRY_POINTS + ("studio/install_mxc_prebuilt.py","studio/install_node_prebuilt.py","studio/install_python_stack.py",+ "studio/install_q4nx_converter.py","studio/install_sd_cpp_prebuilt.py","studio/install_whisper_prebuilt.py","studio/nvidia_probe.py",