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: read adapter_config.json once per inference worker load (#16604)

Daniel Hanc006ec393588
diff --git a/studio/backend/core/export/worker.py b/studio/backend/core/export/worker.py
index e229f7273ac..0ace3dd66a9 100644
--- a/studio/backend/core/export/worker.py
+++ b/studio/backend/core/export/worker.py
@@ -766,7 +766,10 @@ def run_export_process(*, cmd_queue: Any, resp_queue: Any, config: dict) -> None
# The sentinel, not the caller's token: this worker serves whoever exports next.
apply_token_to_child_env(os.environ, False)
- with _offline_window_if_unreachable(step = "activating transformers"):
+ from utils.transformers_version import remote_lora_base_scope
+
+ # One adapter_config.json answer serves activation, the preflight gates and SSM provisioning.
+ with _offline_window_if_unreachable(step = "activating transformers"), remote_lora_base_scope():
try:
# Plain token: _load_config_json refuses the hub cache for the sentinel, so offline a cached model falls to the default sidecar
_activate_transformers_version(checkpoint_path, config.get("hf_token") or None)
@@ -889,17 +892,18 @@ def run_export_process(*, cmd_queue: Any, resp_queue: Any, config: dict) -> None
# Offline window covers this load's Hub preflights (re-probed per load). The
# security gates run before any SSM kernel is provisioned for the checkpoint.
with _offline_window_if_unreachable():
- if not _preflight_security_gates(cmd, resp_queue):
- continue
- if not _provision_ssm_kernels(
- cmd["checkpoint_path"],
- cmd.get("base_model") or None,
- cmd.get("hf_token"),
- resp_queue,
- config.get("device_backend"),
- trust_remote_code = cmd.get("trust_remote_code"),
- ):
- continue
+ with remote_lora_base_scope():
+ if not _preflight_security_gates(cmd, resp_queue):
+ continue
+ if not _provision_ssm_kernels(
+ cmd["checkpoint_path"],
+ cmd.get("base_model") or None,
+ cmd.get("hf_token"),
+ resp_queue,
+ config.get("device_backend"),
+ trust_remote_code = cmd.get("trust_remote_code"),
+ ):
+ continue
_handle_load(backend, cmd, resp_queue)
elif cmd_type == "export":
diff --git a/studio/backend/core/inference/worker.py b/studio/backend/core/inference/worker.py
index 3d4128827fd..bd7438e785c 100644
--- a/studio/backend/core/inference/worker.py
+++ b/studio/backend/core/inference/worker.py
@@ -2508,7 +2508,11 @@ def run_inference_process(
import json as _json
_ensure_backend_on_path()
- from utils.transformers_version import _remote_lora_base, _resolve_base_model
+ from utils.transformers_version import (
+ _remote_lora_base,
+ _resolve_base_model,
+ remote_lora_base_scope,
+ )
_hf_token = _config_hf_token(config)
_lora_base = None
@@ -2523,23 +2527,25 @@ def run_inference_process(
)
except Exception:
_lora_base = None
- if not _lora_base:
- _lora_base = _remote_lora_base(model_name, hf_token = _hf_token)
- # LoRA base, else a full fine-tune's recorded base (its name reveals SSM/sidecar arch).
- _base = _lora_base or _resolve_base_model(model_name)
+ # One adapter_config.json answer serves this lookup and activation's own.
+ with remote_lora_base_scope():
+ if not _lora_base:
+ _lora_base = _remote_lora_base(model_name, hf_token = _hf_token)
+ # LoRA base, else a full fine-tune's recorded base (its name reveals SSM/sidecar arch).
+ _base = _lora_base or _resolve_base_model(model_name)
- try:
- _activate_transformers_version(_base, _hf_token)
- except Exception as exc:
- _send_response(
- resp_queue,
- {
- "type": "error",
- "error": f"Failed to activate transformers version: {exc}",
- "stack": traceback.format_exc(limit = 20),
- },
- )
- return
+ try:
+ _activate_transformers_version(_base, _hf_token)
+ except Exception as exc:
+ _send_response(
+ resp_queue,
+ {
+ "type": "error",
+ "error": f"Failed to activate transformers version: {exc}",
+ "stack": traceback.format_exc(limit = 20),
+ },
+ )
+ return
# Gates (model and genuine LoRA base only, never a full fine-tune's base), then SSM kernels, both before the transformers import, which snapshots backends.
_gate_targets = _native_audio_security_targets_or_error(model_name, _hf_token, resp_queue)
diff --git a/studio/backend/tests/test_remote_lora_base_scope.py b/studio/backend/tests/test_remote_lora_base_scope.py
new file mode 100644
index 00000000000..0ad88a3b773
--- /dev/null
+++ b/studio/backend/tests/test_remote_lora_base_scope.py
@@ -0,0 +1,205 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""One inference or export load reads a repo's adapter_config.json once; only definitive answers are shared."""
+
+import io
+import json
+import os
+import subprocess
+import sys
+import threading
+import urllib.error
+from pathlib import Path
+
+import pytest
+
+import utils.transformers_version as tv
+
+
+def _http_error(url, code):
+ return urllib.error.HTTPError(url, code, "x", {}, io.BytesIO(b""))
+
+
+def hub(monkeypatch):
+ monkeypatch.delenv("HF_HUB_OFFLINE", raising = False)
+ monkeypatch.delenv("TRANSFORMERS_OFFLINE", raising = False)
+ monkeypatch.setattr(tv, "_hf_json_ahead", {})
+ monkeypatch.setattr(tv, "_adapter_base_from_hf_cache", lambda m: "cached/" + m)
+ state = {"answers": {}, "calls": []}
+
+ def read(url, token):
+ state["calls"].append((url, token))
+ queue = state["answers"][url.split("/resolve/")[0].split("/", 3)[-1]]
+ answer = queue.pop(0) if len(queue) > 1 else queue[0]
+ if isinstance(answer, int):
+ raise _http_error(url, answer)
+ if isinstance(answer, Exception):
+ raise answer
+ return answer
+
+ monkeypatch.setattr(tv, "_read_hf_json", read)
+ return state
+
+
+ "answer, expected",
+ [
+ (404, None),
+ ({"base_model_name_or_path": "org/base"}, "org/base"),
+ ({"peft_type": "LORA"}, None),
+ ({"base_model_name_or_path": ""}, None),
+ ],
+)
+def test_definitive_answer_is_read_once_per_scope(hub, answer, expected):
+ hub["answers"]["org/model"] = [answer]
+ with tv.remote_lora_base_scope():
+ first = tv._remote_lora_base("org/model", "tok")
+ second = tv._remote_lora_base("org/model", "tok")
+ assert first == second == expected
+ assert len(hub["calls"]) == 1
+
+
+ "failure",
+ [500, 401, 403, urllib.error.URLError("down"), [1, 2], TimeoutError("slow")],
+)
+def test_failure_is_never_reused(hub, failure):
+ hub["answers"]["org/model"] = [failure, 404]
+ with tv.remote_lora_base_scope():
+ assert tv._remote_lora_base("org/model", None) == "cached/org/model"
+ assert tv._remote_lora_base("org/model", None) is None
+ assert tv._remote_lora_base("org/model", None) is None
+ assert len(hub["calls"]) == 2
+
+
+def test_nothing_is_reused_outside_or_after_a_scope(hub):
+ hub["answers"]["org/model"] = [404]
+ tv._remote_lora_base("org/model", None)
+ tv._remote_lora_base("org/model", None)
+ assert len(hub["calls"]) == 2
+ with tv.remote_lora_base_scope():
+ tv._remote_lora_base("org/model", None)
+ hub["answers"]["org/model"] = [{"base_model_name_or_path": "org/base"}]
+ assert tv._remote_lora_base("org/model", None) == "org/base"
+ assert len(hub["calls"]) == 4
+
+
+def test_answers_are_keyed_by_token_and_repo(hub):
+ hub["answers"]["org/model"] = [404]
+ hub["answers"]["org/other"] = [404]
+ with tv.remote_lora_base_scope():
+ for token in (None, "a", "b", False, None, "a"):
+ tv._remote_lora_base("org/model", token)
+ tv._remote_lora_base("org/other", None)
+ assert len(hub["calls"]) == 5
+
+
+def test_nested_scope_shares_and_outer_exit_clears(hub):
+ hub["answers"]["org/model"] = [404]
+ with tv.remote_lora_base_scope():
+ tv._remote_lora_base("org/model", None)
+ with tv.remote_lora_base_scope():
+ tv._remote_lora_base("org/model", None)
+ tv._remote_lora_base("org/model", None)
+ assert len(hub["calls"]) == 1
+ assert tv._remote_lora_base_answers.get() is None
+
+
+def test_scope_does_not_leak_into_other_threads(hub):
+ hub["answers"]["org/model"] = [404]
+ with tv.remote_lora_base_scope():
+ tv._remote_lora_base("org/model", None)
+ worker = threading.Thread(target = tv._remote_lora_base, args = ("org/model", None))
+ worker.start()
+ worker.join()
+ assert len(hub["calls"]) == 2
+
+
+def test_offline_and_local_names_never_reach_the_scope(hub, monkeypatch):
+ hub["answers"]["org/model"] = [404]
+ with tv.remote_lora_base_scope():
+ monkeypatch.setenv("HF_HUB_OFFLINE", "1")
+ assert tv._remote_lora_base("org/model", None) == "cached/org/model"
+ monkeypatch.delenv("HF_HUB_OFFLINE")
+ assert tv._remote_lora_base("org/model", None) is None
+ assert tv._remote_lora_base("plainname", None) is None
+ assert len(hub["calls"]) == 1
+
+
+def test_activation_reuses_the_worker_lookup(hub, monkeypatch):
+ hub["answers"]["org/model"] = [404]
+ seen = []
+ monkeypatch.setattr(tv, "get_transformers_tier", lambda m, t = None: seen.append(m) or "default")
+ with tv.remote_lora_base_scope():
+ base = tv._remote_lora_base("org/model", "tok") or tv._resolve_base_model("org/model")
+ assert tv.get_transformers_activation_tier(base, "tok") == "default"
+ assert seen == ["org/model"]
+ assert len(hub["calls"]) == 1
+
+
+_WORKER_DRIVER = """
+import faulthandler, io, json, os, queue, sys, urllib.error
+
+faulthandler.dump_traceback_later(120, exit = True)
+import utils.transformers_version as tv
+import utils.utils as uu
+
+uu.hf_dns_dead = lambda *a, **k: False
+tv.hf_endpoint_unreachable = lambda *a, **k: False
+out, worker, model = sys.argv[1:4]
+reads = []
+
+
+def read(url, token):
+ reads.append(url.rsplit("/", 1)[-1])
+ raise urllib.error.HTTPError(url, 404, "x", {}, io.BytesIO(b""))
+
+
+def done(*a, **k):
+ with open(out, "w") as f:
+ json.dump(reads, f)
+ os._exit(0)
+
+
+tv._read_hf_json = read
+config = {"model_name": model, "checkpoint_path": model, "hf_token": None, "device_backend": "cuda"}
+if worker == "inference":
+ import core.inference.worker as w
+
+ w._native_audio_security_targets_or_error = done
+ w.run_inference_process(cmd_queue = queue.Queue(), resp_queue = queue.Queue(), cancel_event = None, config = config)
+else:
+ import core._torchao_stub as stub
+ import core.export.worker as w
+ import utils.ssm_runtime as ssm
+
+ w._run_export_security_gates = lambda *a, **k: True
+ ssm.provision_ssm_kernels = lambda *a, **k: None
+ stub.install_torchao_windows_rocm_real_or_stub = done
+ w.run_export_process(cmd_queue = queue.Queue(), resp_queue = queue.Queue(), config = config)
+"""
+
+
[email protected]("worker", ["inference", "export"])
+def test_worker_load_reads_adapter_config_once(worker, tmp_path):
+ if worker == "inference" and sys.platform == "darwin":
+ pytest.skip("macOS inference takes the MLX command loop, not this activation path")
+ backend = Path(__file__).resolve().parents[1]
+ out = tmp_path / "reads.json"
+ env = {
+ k: v for k, v in os.environ.items() if k not in ("HF_HUB_OFFLINE", "TRANSFORMERS_OFFLINE")
+ }
+ env["PYTHONPATH"] = str(backend)
+ proc = subprocess.run(
+ [sys.executable, "-c", _WORKER_DRIVER, str(out), worker, "org/model"],
+ cwd = tmp_path,
+ env = env,
+ timeout = 240,
+ capture_output = True,
+ text = True,
+ )
+ assert out.exists(), proc.stderr[-4000:]
+ reads = json.loads(out.read_text())
+ assert reads.count("adapter_config.json") == 1, reads
diff --git a/studio/backend/utils/transformers_version.py b/studio/backend/utils/transformers_version.py
index 529443d8143..5fdaa1c6da5 100644
--- a/studio/backend/utils/transformers_version.py
+++ b/studio/backend/utils/transformers_version.py
@@ -37,6 +37,7 @@ import structlog
from loggers import get_logger
import errno
import contextlib
+import contextvars
import os
from concurrent.futures import Future
import re
@@ -754,6 +755,24 @@ def _adapter_base_from_hf_cache(model_name: str) -> str | None:
return None
+_remote_lora_base_answers: "contextvars.ContextVar[dict | None]" = contextvars.ContextVar(
+ "_remote_lora_base_answers", default = None
+)
+
+
+def remote_lora_base_scope():
+ """Within one load only: reuses definitive answers (a read config or a 404), never a failure; re-entrant."""
+ if _remote_lora_base_answers.get() is not None:
+ yield
+ return
+ reset = _remote_lora_base_answers.set({})
+ try:
+ yield
+ finally:
+ _remote_lora_base_answers.reset(reset)
+
+
def _remote_lora_base(model_name: str, hf_token: str | None = None) -> str | None:
"""Raw HTTP so the base is known before ML import; offline or transient failure reads hub cache; definitive 404 returns None, not a stale base."""
if not _is_canonical_repo_id(model_name):
@@ -771,14 +790,27 @@ def _remote_lora_base(model_name: str, hf_token: str | None = None) -> str | Non
import urllib.request
url = _hf_raw_url(model_name, "adapter_config.json")
+ answers = _remote_lora_base_answers.get()
+ if not isinstance(hf_token, (str, bool, type(None))):
+ answers = None
+ key = (url, hf_token)
+ if answers is not None and key in answers:
+ base = answers[key]
+ if base:
+ logger.info("Resolved remote LoRA adapter '%s' → base model '%s'", model_name, base)
+ return base
try:
cfg = _hf_json(url, hf_token)
base = cfg.get("base_model_name_or_path")
if base:
logger.info("Resolved remote LoRA adapter '%s' → base model '%s'", model_name, base)
+ if answers is not None:
+ answers[key] = base or None
return base or None
except urllib.error.HTTPError as exc:
if exc.code == 404:
+ if answers is not None:
+ answers[key] = None
return None # definitively not a LoRA; do not serve a stale cached base
logger.debug("adapter_config.json fetch failed for '%s': %s", model_name, exc)
return _adapter_base_from_hf_cache(model_name)