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: expose image text encoder precision (#10788)
Michael Han4eb965fe0dd0
diff --git a/.github/workflows/studio-ui-smoke.yml b/.github/workflows/studio-ui-smoke.ymlindex 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_coldpython 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_footprintlogs/playwright_image_cancel_retrylogs/playwright_image_cancel_retry_cold+ logs/playwright_image_text_encoderlogs/playwright_modelcfglogs/playwright_memory_estimatelogs/playwright_imediff --git a/studio/frontend/src/features/images/images-page.tsx b/studio/frontend/src/features/images/images-page.tsxindex 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)"],+ ]}+ /><AdvancedSelectlabel="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.tsindex 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.tsindex 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 toasassert.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.pynew file mode 100644index 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()