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: expose image text encoder precision (#10788)

Michael Han4eb965fe0dd0
diff --git a/.github/workflows/studio-ui-smoke.yml b/.github/workflows/studio-ui-smoke.yml
index 92156da6382..e3bc4a99084 100644
--- a/.github/workflows/studio-ui-smoke.yml
+++ b/.github/workflows/studio-ui-smoke.yml
@@ -679,6 +679,23 @@ jobs:
mkdir -p logs/playwright_image_cancel_retry_cold
python tests/studio/playwright_image_download_cancel_retry.py
+ # The Text encoder precision control: what the select sends to the plan and to the load, that
+ # Default omits the field entirely, that a refresh race cannot leave a stale reading, and that
+ # the select follows the build the backend reports back, downgrade or decline included.
+ - name: Image text encoder precision regression (Playwright)
+ if: matrix.shard == 'extra'
+ env:
+ BASE_URL: http://127.0.0.1:18894
+ STUDIO_PW: ${{ env.STUDIO_EXTRA_NEW_PW }}
+ PW_ART_DIR: logs/playwright_image_text_encoder
+ run: |
+ mkdir -p logs/playwright_image_text_encoder
+ PW_ART_DIR="$PW_ART_DIR/applied" python tests/studio/playwright_image_text_encoder.py
+ PW_ART_DIR="$PW_ART_DIR/completion-first" PW_COMPLETION_FIRST=1 \
+ python tests/studio/playwright_image_text_encoder.py
+ PW_ART_DIR="$PW_ART_DIR/declined" PW_DECLINE=1 \
+ python tests/studio/playwright_image_text_encoder.py
+
- name: Tool activity collapse regression (Playwright)
if: matrix.shard == 'extra'
run: |
@@ -871,6 +888,7 @@ jobs:
logs/playwright_image_footprint
logs/playwright_image_cancel_retry
logs/playwright_image_cancel_retry_cold
+ logs/playwright_image_text_encoder
logs/playwright_modelcfg
logs/playwright_memory_estimate
logs/playwright_ime
diff --git a/studio/frontend/src/features/images/images-page.tsx b/studio/frontend/src/features/images/images-page.tsx
index 953d7eda76c..901d28cf898 100644
--- a/studio/frontend/src/features/images/images-page.tsx
+++ b/studio/frontend/src/features/images/images-page.tsx
@@ -682,7 +682,7 @@ function AdvancedSelect({
{badge}
</span>
<Select value={value} onValueChange={onValueChange}>
- <SelectTrigger className="h-8 w-[160px] text-xs">
+ <SelectTrigger aria-label={label} className="h-8 w-[160px] text-xs">
<SelectValue />
</SelectTrigger>
<SelectContent>
@@ -1145,6 +1145,7 @@ type LoadAdvanced = Pick<
| "cpu_offload"
| "speed_mode"
| "transformer_quant"
+ | "text_encoder_quant"
| "attention_backend"
| "memory_mode"
| "transformer_cache"
@@ -1269,6 +1270,9 @@ export function ImagesPage({
const [transformerQuant, setTransformerQuant] = useState<
"none" | "auto" | "int8" | "fp8" | "nvfp4" | "mxfp8"
>("auto");
+ const [textEncoderQuant, setTextEncoderQuant] = useState<
+ "auto" | NonNullable<DiffusionLoadRequest["text_encoder_quant"]>
+ >("auto");
const [attentionBackend, setAttentionBackend] = useState<"auto" | "native" | "cudnn" | "flash3" | "sage">(
"auto",
);
@@ -2326,6 +2330,13 @@ export function ImagesPage({
) ?? null,
);
if (quant) setTransformerQuant(quant);
+ const encoder = resolvedSelectValue(record.text_encoder_quant, (v) =>
+ // A declined request runs dense: "off" (or "none", older backend) is the select's Default.
+ (["auto", "fp8", "fp8_dynamic", "int8", "nvfp4"] as const).find(
+ (o) => o === v || (o === "auto" && (v === "none" || v === "off")),
+ ) ?? null,
+ );
+ if (encoder) setTextEncoderQuant(encoder);
const memory = resolvedSelectValue(record.memory_mode, (v) =>
(["auto", "fast", "balanced", "low_vram"] as const).find((o) => o === v) ?? null,
);
@@ -2359,6 +2370,7 @@ export function ImagesPage({
cpu_offload: cpuOffload,
speed_mode: speedMode === "auto" ? undefined : speedMode,
transformer_quant: transformerQuant === "auto" ? undefined : transformerQuant,
+ text_encoder_quant: textEncoderQuant === "auto" ? undefined : textEncoderQuant,
attention_backend: attentionBackend === "auto" ? undefined : attentionBackend,
memory_mode: memoryMode === "auto" ? undefined : memoryMode,
transformer_cache: transformerCache === "auto" ? undefined : transformerCache,
@@ -2376,6 +2388,7 @@ export function ImagesPage({
cpuOffload,
speedMode,
transformerQuant,
+ textEncoderQuant,
attentionBackend,
memoryMode,
transformerCache,
@@ -2446,6 +2459,7 @@ export function ImagesPage({
// its checkpoint's own precision. The control is hidden there but the state persists across
// picks, so a stale scheme would reach a load that can only decline it.
transformer_quant: opts.kind === "gguf" ? advanced.transformer_quant : undefined,
+ text_encoder_quant: advanced.text_encoder_quant,
attention_backend: advanced.attention_backend,
memory_mode: advanced.memory_mode,
transformer_cache: advanced.transformer_cache,
@@ -2581,6 +2595,7 @@ export function ImagesPage({
speed_mode: advanced.speed_mode,
// Non-GGUF loads ignore this control; the plan must describe the same request as handleLoad.
transformer_quant: opts.kind === "gguf" ? advanced.transformer_quant : undefined,
+ text_encoder_quant: advanced.text_encoder_quant,
memory_mode: advanced.memory_mode,
// The backend prefetch decision reads the adapter selection too: a baked LoRA always runs the
// dense build path, and omitting it staged too little.
@@ -3438,6 +3453,20 @@ export function ImagesPage({
<span className="text-xs text-muted-foreground/60">GGUF models only</span>
</div>
)}
+ <AdvancedSelect
+ label="Text encoder precision"
+ hint="Lower precision reduces text-encoder memory but can change image quality. Supported modes depend on the GPU and model. Default keeps the existing encoder precision; the loaded build below reports what was applied."
+ badge={<ResolvedBadge status={status} controlKey="text_encoder_quant" />}
+ value={textEncoderQuant}
+ onValueChange={(v) => setTextEncoderQuant(v as typeof textEncoderQuant)}
+ options={[
+ ["auto", "Default"],
+ ["fp8", "FP8 (storage)"],
+ ["fp8_dynamic", "FP8 (compute)"],
+ ["int8", "INT8"],
+ ["nvfp4", "NVFP4 (Blackwell)"],
+ ]}
+ />
<AdvancedSelect
label="Attention"
hint="Attention kernel. Auto upgrades to cuDNN fused attention on NVIDIA when a speed profile is active. sage is INT8 attention: fast (10-40%) but can black-frame some families (Qwen, Wan), so it never engages automatically."
diff --git a/studio/frontend/src/lib/resolved-precision.ts b/studio/frontend/src/lib/resolved-precision.ts
index def704ce961..5eb02cd6788 100644
--- a/studio/frontend/src/lib/resolved-precision.ts
+++ b/studio/frontend/src/lib/resolved-precision.ts
@@ -153,6 +153,9 @@ export function resolvedSelectValue<T extends string>(
* whole blob re-ran the reseed mid-session and overwrote a Precision the user had picked but not
* yet loaded. An edit made after the load is meant to survive until the next LOAD replaces it.
*
+ * The text-encoder entry carries its engaged value because a request can be DOWNGRADED there (an
+ * int8 ask resolves to fp8) or declined to dense, and the select has to follow what ran.
+ *
* Only the controls the reseed writes are in the key, and for attention only the REQUEST side:
* `value` is the field the generation-time rewrite touches. A reload still re-fires, including a
* Reapply with new options, because that always lands a different request or engaged value.
@@ -168,6 +171,7 @@ export function resolvedSeedKey(
};
return [
part(resolved.transformer_quant, true),
+ part(resolved.text_encoder_quant, true),
part(resolved.memory_mode, true),
part(resolved.attention_backend, false),
].join("|");
diff --git a/studio/frontend/tests/resolved-precision.test.ts b/studio/frontend/tests/resolved-precision.test.ts
index 70a8fec8bfe..4d4e7f702c9 100644
--- a/studio/frontend/tests/resolved-precision.test.ts
+++ b/studio/frontend/tests/resolved-precision.test.ts
@@ -313,3 +313,76 @@ test("a precision refusal is recognised so it can be shown as an actionable toas
assert.equal(isPrecisionRefusal("A diffusion load is already in progress."), false);
assert.equal(PRECISION_REFUSAL_TITLE, "Requested precision is not available");
});
+
+const ENCODER_OPTIONS = ["auto", "fp8", "fp8_dynamic", "int8", "nvfp4"] as const;
+const toEncoderOption = (v: string) =>
+ ENCODER_OPTIONS.find((o) => o === v || (o === "auto" && (v === "none" || v === "off"))) ?? null;
+
+test("the text encoder select follows what the loaded build actually ran", () => {
+ // "off" (and "none", from an older backend) both mean dense, so both seed Default.
+ assert.equal(
+ resolvedSelectValue({ value: "off", source: "auto", reason: "" }, toEncoderOption),
+ "auto",
+ );
+ assert.equal(
+ resolvedSelectValue({ value: "none", source: "auto", reason: "" }, toEncoderOption),
+ "auto",
+ );
+ assert.equal(
+ resolvedSelectValue(
+ { value: "fp8_dynamic", requested: "fp8_dynamic", source: "explicit", status: "applied", reason: "" },
+ toEncoderOption,
+ ),
+ "fp8_dynamic",
+ );
+ // Downgraded: the select follows what engaged, not what was asked.
+ assert.equal(
+ resolvedSelectValue(
+ { value: "fp8", requested: "int8", source: "explicit", status: "fell_back", reason: "int8 needs resident weights" },
+ toEncoderOption,
+ ),
+ "fp8",
+ );
+ assert.equal(
+ resolvedSelectValue(
+ { value: "off", requested: "nvfp4", source: "explicit", status: "fell_back", reason: "no Blackwell GPU" },
+ toEncoderOption,
+ ),
+ "auto",
+ );
+});
+
+test("the reseed key moves when the text encoder build changes, and only then", () => {
+ const atLoad = {
+ transformer_quant: { value: "fp8", requested: "fp8", source: "explicit", status: "applied", reason: "" },
+ text_encoder_quant: { value: "fp8", requested: "fp8", source: "explicit", status: "applied", reason: "" },
+ memory_mode: { value: "balanced", source: "auto", reason: "" },
+ attention_backend: { value: "native", source: "auto", reason: "" },
+ } satisfies Record<string, ResolvedControl>;
+ const key = resolvedSeedKey(atLoad);
+
+ // Same build, new wording: keying on the whole serialized entry re-seeded here and lost the edit.
+ assert.equal(
+ resolvedSeedKey({
+ ...atLoad,
+ text_encoder_quant: { ...atLoad.text_encoder_quant, reason: "re-measured after the first image" },
+ }),
+ key,
+ "a reason rewrite must not re-seed",
+ );
+ assert.notEqual(
+ resolvedSeedKey({
+ ...atLoad,
+ text_encoder_quant: { value: "off", requested: "fp8", source: "explicit", status: "fell_back", reason: "declined" },
+ }),
+ key,
+ "a declined encoder must re-seed",
+ );
+ assert.notEqual(
+ resolvedSeedKey({
+ ...atLoad,
+ text_encoder_quant: { value: "int8", requested: "int8", source: "explicit", status: "applied", reason: "" },
+ }),
+ key,
+ );
+});
diff --git a/tests/studio/playwright_image_text_encoder.py b/tests/studio/playwright_image_text_encoder.py
new file mode 100644
index 00000000000..7235ae4bd9b
--- /dev/null
+++ b/tests/studio/playwright_image_text_encoder.py
@@ -0,0 +1,291 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Exercise encoder precision through the rendered UI without model downloads."""
+
+import json
+import os
+import re
+from pathlib import Path
+from urllib.parse import parse_qs, urlparse
+
+from playwright.sync_api import expect, sync_playwright
+
+from playwright_image_model_footprint import BASE_URL, REPO_ID, _api_payload, _json, klein_row
+
+# A refusal: value "off", status "fell_back". The only shape the echoing stub cannot produce.
+DECLINE = os.environ.get("PW_DECLINE", "0") == "1"
+ART = Path(os.environ.get("PW_ART_DIR", "logs/playwright_image_text_encoder"))
+ART.mkdir(parents = True, exist_ok = True)
+
+
+def _record(page, state, loads, plans, errors):
+ """State, requests and a screenshot, so a failed CI run uploads something readable."""
+ (ART / "result.json").write_text(
+ json.dumps(
+ {
+ "state": state,
+ "loads": loads,
+ "plans": plans,
+ "page_errors": errors,
+ "declined": DECLINE,
+ },
+ indent = 2,
+ ),
+ encoding = "utf-8",
+ )
+ page.screenshot(path = str(ART / "text-encoder.png"), full_page = True)
+
+
+def main():
+ state = {"cached": False, "complete": False, "started": False, "loaded": False}
+ plans, loads, errors = [], [], []
+ hold_status = False
+ held_status = []
+
+ def status():
+ result = _api_payload("/api/inference/images/status", {}, full_footprint = True)
+ if state["loaded"]:
+ requested = loads[-1].get("text_encoder_quant")
+ value = "fp8" if requested == "int8" else requested
+ if DECLINE and requested:
+ value = "off"
+ result.update(
+ loaded = True,
+ repo_id = REPO_ID,
+ base_repo = "black-forest-labs/FLUX.2-klein-4B",
+ family = "flux.2-klein",
+ model_kind = "gguf",
+ dtype = "bfloat16",
+ text_encoder_quant = value,
+ resolved = {
+ "text_encoder_quant": {
+ "value": value,
+ "requested": requested,
+ "source": "explicit" if requested else "auto",
+ "status": (
+ "fell_back"
+ if (requested == "int8" or (DECLINE and requested))
+ else "applied"
+ ),
+ "reason": "Test precision outcome",
+ }
+ },
+ )
+ return result
+
+ with sync_playwright() as playwright:
+ engine = getattr(playwright, os.environ.get("PW_BROWSER", "chromium"))
+ executable = os.environ.get("PW_EXECUTABLE")
+ browser = engine.launch(
+ headless = True, **({"executable_path": executable} if executable else {})
+ )
+ context = browser.new_context(
+ viewport = {"width": 1440, "height": 1000}, reduced_motion = "reduce"
+ )
+ context.add_init_script(
+ "localStorage.setItem('unsloth_auth_token', 'rendered-ui-test');"
+ "localStorage.setItem('unsloth_download_transport', 'http');"
+ )
+
+ def route_request(route):
+ parsed = urlparse(route.request.url)
+ path, query = parsed.path, parse_qs(parsed.query)
+ if not path.startswith("/api/"):
+ if parsed.hostname not in ("127.0.0.1", "localhost"):
+ _json(route, [])
+ else:
+ route.continue_()
+ return
+ payload = json.loads(route.request.post_data or "{}")
+ if path == "/api/inference/images/download-plan":
+ plans.append(payload)
+ _json(
+ route,
+ {
+ "entries": []
+ if state["cached"]
+ else [
+ {
+ "repo_id": "test/encoder",
+ "files": ["text_encoder/model.safetensors"],
+ "bytes": 1024,
+ "checkpoint": False,
+ }
+ ],
+ "total_bytes": 1024,
+ },
+ )
+ elif path == "/api/studio/download-transport-capabilities":
+ _json(
+ route,
+ {
+ "http": {"available": True},
+ "xet": {"available": False},
+ "auto_resolves_to": "http",
+ },
+ )
+ elif path == "/api/hub/transport-status":
+ _json(route, {"has_partial": False, "last_transport": None, "resumable": False})
+ elif path == "/api/hub/download":
+ state["started"] = True
+ _json(
+ route,
+ {"accepted": True, "state": "running", "generation": 1, "transport": "http"},
+ )
+ elif path == "/api/hub/download-status":
+ state["cached"] = state["complete"]
+ _json(
+ route,
+ {
+ "state": "complete"
+ if state["complete"]
+ else "running"
+ if state["started"]
+ else "idle",
+ "generation": 1,
+ },
+ )
+ elif path == "/api/hub/download-progress":
+ _json(
+ route,
+ {
+ "status": "complete" if state["complete"] else "downloading",
+ "downloaded_bytes": 1024 if state["complete"] else 0,
+ "expected_bytes": 1024,
+ "progress": 1 if state["complete"] else 0,
+ },
+ )
+ elif path == "/api/inference/images/load":
+ loads.append(payload)
+ state["loaded"] = True
+ _json(route, status())
+ elif path == "/api/inference/images/status":
+ if hold_status:
+ held_status.append(route)
+ else:
+ _json(route, status())
+ elif path == "/api/inference/images/load-progress":
+ _json(
+ route,
+ {
+ "phase": "ready" if state["loaded"] else None,
+ "bytes_downloaded": 0,
+ "bytes_total": 0,
+ "error": None,
+ },
+ )
+ else:
+ _json(route, _api_payload(path, query, full_footprint = True))
+
+ context.route("**/*", route_request)
+ page = context.new_page()
+ page.on("pageerror", lambda error: errors.append(str(error)))
+ page.goto(f"{BASE_URL}/images", wait_until = "domcontentloaded")
+ page.get_by_role("button", name = "Advanced", exact = True).click()
+ encoder = page.get_by_role("combobox", name = "Text encoder precision", exact = True)
+ expect(encoder).to_have_text("Default")
+
+ def choose(label):
+ encoder.click()
+ page.get_by_role("option", name = label, exact = True).click()
+
+ choose("FP8 (storage)")
+ page.get_by_role("button", name = "Select image model").click()
+ klein_row(page).click()
+ gguf = page.get_by_text("GGUF", exact = True)
+ if gguf.count() == 1:
+ gguf.click()
+ with page.expect_request(lambda request: urlparse(request.url).path == "/api/hub/download"):
+ page.locator("button[data-model-picker-option]").filter(has_text = "Q4_K_M").click()
+ assert plans and all(plan.get("text_encoder_quant") == "fp8" for plan in plans), plans
+ assert not loads
+ choose("INT8")
+ state["complete"] = True
+ expect(page.get_by_role("button", name = "Reapply to loaded model")).to_be_enabled(
+ timeout = 20_000
+ )
+ if DECLINE:
+ # The select must show what RAN, or the page advertises a precision nothing is using.
+ expect(encoder).to_have_text("Default")
+ assert loads[-1]["text_encoder_quant"] == "fp8", loads
+ assert not errors, errors
+ _record(page, state, loads, plans, errors)
+ print(f"Passed: a declined encoder precision reseeds to Default ({browser.version})")
+ context.close()
+ browser.close()
+ return
+ expect(encoder).to_have_text("FP8 (storage)")
+ assert loads[-1]["text_encoder_quant"] == "fp8", loads
+
+ for label, requested, displayed in [
+ ("FP8 (compute)", "fp8_dynamic", "FP8 (compute)"),
+ ("NVFP4 (Blackwell)", "nvfp4", "NVFP4 (Blackwell)"),
+ ("INT8", "int8", "FP8 (storage)"),
+ ("Default", None, "Default"),
+ ]:
+ choose(label)
+ with page.expect_request(
+ lambda request: urlparse(request.url).path == "/api/inference/images/load"
+ ):
+ page.get_by_role("button", name = "Reapply to loaded model").click()
+ expect(page.get_by_role("button", name = "Reapply to loaded model")).to_be_enabled()
+ expect(encoder).to_have_text(displayed)
+ assert loads[-1].get("text_encoder_quant") == requested, loads[-1]
+ if requested is None:
+ assert "text_encoder_quant" not in loads[-1]
+ # A completed reload can have the same precision record as its predecessor.
+ state.update(cached = False, complete = False, started = False)
+ page.get_by_role("button", name = "Reapply to loaded model").scroll_into_view_if_needed()
+ page.locator(".unsloth-model-selector-trigger:visible").click()
+ klein_row(page).click()
+ gguf = page.get_by_text("GGUF", exact = True)
+ if gguf.count() == 1:
+ gguf.click()
+ with page.expect_request(lambda request: urlparse(request.url).path == "/api/hub/download"):
+ page.locator("button[data-model-picker-option]").filter(has_text = "Q4_K_M").click()
+ choose("FP8 (storage)")
+ hold_status = True
+ with page.expect_request(
+ lambda request: urlparse(request.url).path == "/api/inference/images/load"
+ ):
+ state["complete"] = True
+ for _ in range(200):
+ if held_status:
+ break
+ page.wait_for_timeout(50)
+ assert len(held_status) == 1
+ page.get_by_test_id("nav-row-hub").click()
+ # Path only: the Hub appends its own ?tab= on mount and an exact-URL assertion loses that race.
+ expect(page).to_have_url(re.compile(r"/hub(\?|$)"))
+ page.get_by_test_id("nav-row-images").click()
+ expect(page).to_have_url(re.compile(r"/images(\?|$)"))
+ for _ in range(200):
+ if len(held_status) >= 2:
+ break
+ page.wait_for_timeout(50)
+ assert len(held_status) == 2
+ hold_status = False
+ replies = (
+ held_status if os.environ.get("PW_COMPLETION_FIRST") == "1" else reversed(held_status)
+ )
+ for response in replies:
+ _json(response, status())
+ held_status.clear()
+ # The staged load carries the precision pinned when it was queued, so this one is Default.
+ assert "text_encoder_quant" not in loads[-1], loads[-1]
+ # Either order ends the same, and the edit made while the load staged survives: the reseed
+ # follows a change of BUILD, not every completed load, and Reapply is how the user applies it.
+ expect(encoder).to_have_text("FP8 (storage)")
+ expect(page.get_by_role("button", name = "Reapply to loaded model")).to_be_enabled()
+ assert not errors, errors
+ _record(page, state, loads, plans, errors)
+ print(
+ f"Passed: planned and pinned precision, four explicit modes, fallback reseeding and default omission ({browser.version})"
+ )
+ context.close()
+ browser.close()
+
+
+if __name__ == "__main__":
+ main()