Skip to content

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

studio: 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.tsx
index 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.ts
index 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.ts
index 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);
+});