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.

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.toml
index 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.py
index 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 q4nx
from 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 list
produces 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.py
index 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.py
new file mode 100644
index 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_dir
diff --git a/studio/backend/core/export/worker.py b/studio/backend/core/export/worker.py
index 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__.py
index 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.py
index 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.py
index 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.py
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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) == 2
diff --git a/studio/frontend/src/features/export/api/export-api.ts b/studio/frontend/src/features/export/api/export-api.ts
index 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.tsx
new file mode 100644
index 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.ts
index 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.tsx
index 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.ts
index 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.py
new file mode 100644
index 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.json
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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",