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
studio: allow local imatrix files for gguf export (#11350)
Maheswar Kumare3cd413f7d5c
diff --git a/studio/frontend/src/features/export/export-page.tsx b/studio/frontend/src/features/export/export-page.tsxindex 334926ee261..2118298deda 100644--- a/studio/frontend/src/features/export/export-page.tsx+++ b/studio/frontend/src/features/export/export-page.tsx@@ -213,6 +213,7 @@ export function ExportPage() {});// GGUF importance matrix (required for the IQ quants) and merged-export precision.const [useImatrix, setUseImatrix] = 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[]>(() => {const s = useExportRuntimeStore.getState();@@ -583,6 +584,14 @@ export function ExportPage() {const estimatedSize = getEstimatedSize(exportMethod, quantLevels, fp16Bytes);const selectedExportSource =sourceMode === "checkpoint" ? checkpoint : selectedSourceModel;+ // Derived, not reset in an effect: an imatrix is calibrated for one model, so another source must not inherit it.+ const imatrixSourceKey = JSON.stringify([+ sourceTab,+ sourceMode === "checkpoint" ? selectedModelIdx : null,+ selectedExportSource,+ ]);+ const imatrixPath =+ customImatrix.sourceKey === imatrixSourceKey ? customImatrix.path : "";const defaultSaveDirectory = useMemo(() => {const relative = buildRelativeSaveDirectory(exportMethod,@@ -778,6 +787,7 @@ export function ExportPage() {isAdapter: adapterExport,quantLevels,useImatrix: effectiveImatrix,+ imatrixPath,mergedSelections: selectedFormats.map((v) => ({...mergedFormatPayload(v),label: MERGED_FORMATS.find((f) => f.value === v)?.label ?? v,@@ -812,6 +822,7 @@ export function ExportPage() {isAdapter,quantLevels,effectiveImatrix,+ imatrixPath,selectedFormats,hubMultiFormat,ggufAsLora,@@ -1656,16 +1667,50 @@ export function ExportPage() {</div><div className="text-xs text-muted-foreground">{requiresImatrix- ? "Required for the selected IQ low-bit quant. Auto-downloads the upstream Unsloth imatrix for the base model."- : "Improves quant quality and unlocks the IQ low-bit quants. Auto-downloads the upstream Unsloth imatrix for the base model."}+ ? "Required for the selected IQ low-bit quant."+ : "Improves quant quality and unlocks the IQ low-bit quants."}</div></div><Switch+ aria-label="Importance matrix (imatrix)"checked={effectiveImatrix}onCheckedChange={setUseImatrix}disabled={requiresImatrix}/></div>+ {effectiveImatrix && (+ <div className="space-y-1.5">+ <label+ htmlFor="export-imatrix-path"+ className="text-sm font-medium"+ >+ Local imatrix file (optional)+ </label>+ <InputGroup>+ <InputGroupInput+ id="export-imatrix-path"+ aria-describedby="export-imatrix-path-help"+ placeholder="/path/to/imatrix.gguf"+ value={imatrixPath}+ onChange={(e) =>+ setCustomImatrix({+ sourceKey: imatrixSourceKey,+ path: e.target.value,+ })+ }+ />+ </InputGroup>+ <p+ id="export-imatrix-path-help"+ className="text-xs text-muted-foreground"+ >+ Absolute path to a .dat or .gguf imatrix file on the+ machine running Unsloth. Leave blank to+ auto-download the upstream Unsloth imatrix for the+ base model, if one exists.+ </p>+ </div>+ )}</>)}</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 f512df47c25..62774d11f7c 100644--- a/studio/frontend/src/features/export/stores/export-runtime-store.ts+++ b/studio/frontend/src/features/export/stores/export-runtime-store.ts@@ -139,8 +139,9 @@ export interface RunExportParams {exportMethod: ExportMethod;isAdapter: boolean;quantLevels: string[];- /** GGUF: use an importance matrix (auto-download); required for the IQ quants. */+ /** GGUF: use an importance matrix, auto-downloaded unless imatrixPath is set; required for the IQ quants. */useImatrix?: boolean;+ imatrixPath?: string;/** 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?: {@@ -494,6 +495,9 @@ export const useExportRuntimeStore = create<ExportRuntimeStore>()((set, get) =>// token when there is no hub-upload token (both are the same HF token).hf_token: params.token ?? params.loadToken ?? null,imatrix: params.useImatrix,+ imatrix_path: params.useImatrix+ ? params.imatrixPath?.trim() || null+ : null,private: params.privateRepo,}),);diff --git a/studio/frontend/tests/export-gguf-token-fallback.test.ts b/studio/frontend/tests/export-gguf-token-fallback.test.tsindex a1b73bd0faa..55dccb32920 100644--- a/studio/frontend/tests/export-gguf-token-fallback.test.ts+++ b/studio/frontend/tests/export-gguf-token-fallback.test.ts@@ -102,3 +102,49 @@ test("the load phase keeps using the load token on its own", async () => {assert.ok(load, "no load request was made");assert.equal((load.args[0] as Record<string, unknown>).hf_token, "hf_load");});++test("a local model forwards its trimmed custom imatrix path", async () => {+ const body = await ggufRequest({+ modelSource: "local",+ source: "/models/merged-model",+ useImatrix: true,+ imatrixPath: " /models/calibration data/imatrix.gguf ",+ quantLevels: ["iq2_xxs", "q4_k_m"],+ });++ assert.equal(body.imatrix_path, "/models/calibration data/imatrix.gguf");+ assert.deepEqual(body.quantization_method, ["iq2_xxs", "q4_k_m"]);+});++test("a checkpoint hub export preserves a Windows imatrix path", async () => {+ const path = String.raw`C:\models\校准 data\imatrix.dat`;+ const body = await ggufRequest({+ sourceMode: "checkpoint",+ checkpointPath: "/checkpoints/run/checkpoint-10",+ useImatrix: true,+ imatrixPath: path,+ destination: "hub",+ repoId: "org/model",+ });++ assert.equal(body.imatrix_path, path);+ assert.equal(body.push_to_hub, true);+});++test("an empty custom path keeps automatic imatrix download", async () => {+ for (const imatrixPath of [undefined, "", " "]) {+ const body = await ggufRequest({ useImatrix: true, imatrixPath });+ assert.equal(body.imatrix, true);+ assert.equal(body.imatrix_path, null);+ }+});++test("disabling imatrix excludes a previously entered path", async () => {+ const body = await ggufRequest({+ useImatrix: false,+ imatrixPath: "/models/imatrix.gguf",+ });++ assert.equal(body.imatrix, false);+ assert.equal(body.imatrix_path, null);+});