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.

Unsloth Studio: Cosmos3 guardrail refusal names the gated nvidia/Cosmos-1.0-Guardrail repo (#16742)

Leo Borcherding997441a41c4a
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index 4f068441bfd..53becb3191a 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -9755,11 +9755,28 @@ class VideoBackend:
device = target.torch_device if target.device == "cuda" else None,
)
# The pre-downloaded snapshot dir keeps from_pretrained off the hub; hub id when pre-download was skipped.
- pipe = pipeline_cls.from_pretrained(
- _base_local_dir or fetch_base,
- **_pinned_base_kwargs(),
- **pipe_kwargs,
- )
+ if fam.name in COSMOS3_FAMILIES:
+ from .video_cosmos3 import guardrail_access_refusal, guardrail_hub_token
+ hub_token_scope = guardrail_hub_token(hf_token)
+ else:
+ hub_token_scope = contextlib.nullcontext()
+ try:
+ with hub_token_scope:
+ pipe = pipeline_cls.from_pretrained(
+ _base_local_dir or fetch_base,
+ **_pinned_base_kwargs(),
+ **pipe_kwargs,
+ )
+ except Exception as exc:
+ refusal = (
+ guardrail_access_refusal(str(repo_id), exc)
+ if fam.name in COSMOS3_FAMILIES
+ else None
+ )
+ if refusal is None:
+ raise
+ logger.warning("video.cosmos3: guardrail download refused: %s", exc)
+ raise ValueError(refusal) from exc
if cast_missed:
from .diffusion_cast_cache import defer_writes
diff --git a/studio/backend/core/inference/video_cosmos3.py b/studio/backend/core/inference/video_cosmos3.py
index 7382fdb1491..e1d78cf256c 100644
--- a/studio/backend/core/inference/video_cosmos3.py
+++ b/studio/backend/core/inference/video_cosmos3.py
@@ -6,9 +6,13 @@
from __future__ import annotations
import contextlib
+import contextvars
+import functools
+import importlib
import importlib.util
import json
import os
+import threading
from pathlib import Path
from typing import Any, Iterable, Optional
@@ -20,6 +24,11 @@ SAFETY_CHECKER_ENV = "UNSLOTH_COSMOS3_SAFETY_CHECKER"
# Passed as None to from_pretrained: Studio renders video only.
NONE_COMPONENTS = ("sound_tokenizer",)
GUARDRAIL_PACKAGE = "cosmos_guardrail"
+GUARDRAIL_REPO = "nvidia/Cosmos-1.0-Guardrail"
+_GUARDRAIL_STEPS = (
+ f"accept its licence at https://huggingface.co/{GUARDRAIL_REPO}, add that account's Hugging Face token in "
+ f"Settings, and load again. Or set {SAFETY_CHECKER_ENV}=0 to run without it at your own responsibility."
+)
# Fallback when the index is not on disk yet (validation is network-free).
_BASE_SAFETY_CHECKER = {
"nvidia/cosmos3-nano": True,
@@ -105,12 +114,62 @@ def guardrail_refusal(repo_id: str, index: Optional[dict] = None) -> Optional[st
return None
if not checkpoint_enables_safety_checker(repo_id, index):
return None
- return (
- f"'{repo_id}' runs NVIDIA's Cosmos guardrail (its model_index.json does not turn enable_safety_checker off, and "
- f"the pipeline's default is on), which needs the cosmos_guardrail package: pip install cosmos-guardrail into "
- f"Studio's Python environment, restart Studio, and retry. To run without it, set {SAFETY_CHECKER_ENV}=0; the "
- f"model card's terms and safe use stay your responsibility."
- )
+ return f"'{repo_id}' needs NVIDIA's gated Cosmos guardrail: pip install cosmos-guardrail, restart, {_GUARDRAIL_STEPS}"
+
+
+def guardrail_access_refusal(repo_id: str, exc: BaseException) -> Optional[str]:
+ """The load error for a gated-repo refusal of the guardrail's own weights, else None."""
+ from .diffusion import _HUB_REPO_RE, _gated_in_chain
+
+ gated = _gated_in_chain(exc)
+ found = _HUB_REPO_RE.search(str(gated)) if gated is not None else None
+ if found is None or found.group(1).rstrip(".").lower() != GUARDRAIL_REPO.lower():
+ return None
+ return f"'{repo_id}' needs NVIDIA's gated Cosmos guardrail: {_GUARDRAIL_STEPS}"
+
+
+_UNSET = object()
+_load_hub_token: contextvars.ContextVar[Any] = contextvars.ContextVar(
+ "cosmos3_guardrail_token", default = _UNSET
+)
+_wrap_lock = threading.Lock()
+
+
+def _token_bound(download: Any) -> Any:
+ @functools.wraps(download)
+ def snapshot_download(*args: Any, **kwargs: Any) -> Any:
+ token = _load_hub_token.get()
+ if token is not _UNSET:
+ kwargs.setdefault("token", token)
+ return download(*args, **kwargs)
+
+ snapshot_download._unsloth_load_token = True
+ return snapshot_download
+
+
+def guardrail_hub_token(token: Any):
+ """cosmos_guardrail downloads without a token argument; a permanent wrapper sends this load's token from a
+ context variable, so overlapping loads never share one. None keeps the ambient login."""
+ if isinstance(token, str):
+ token = token.strip() or None
+ module = None
+ if token is not None:
+ try:
+ module = importlib.import_module(f"{GUARDRAIL_PACKAGE}.{GUARDRAIL_PACKAGE}")
+ with _wrap_lock:
+ if not getattr(module.snapshot_download, "_unsloth_load_token", False):
+ module.snapshot_download = _token_bound(module.snapshot_download)
+ except (ImportError, AttributeError):
+ module = None
+ if module is None:
+ yield
+ return
+ reset = _load_hub_token.set(token)
+ try:
+ yield
+ finally:
+ _load_hub_token.reset(reset)
def pipeline_kwargs(repo_id: str, index: Optional[dict] = None) -> dict[str, Any]:
diff --git a/studio/backend/tests/test_video_cosmos3.py b/studio/backend/tests/test_video_cosmos3.py
index 520091b3b74..3f8fb8bb808 100644
--- a/studio/backend/tests/test_video_cosmos3.py
+++ b/studio/backend/tests/test_video_cosmos3.py
@@ -403,7 +403,13 @@ def test_guardrail_refusal_and_pipeline_kwargs(monkeypatch, repo, guardrail):
monkeypatch.setattr(vc3, "logger", log)
refusal = vc3.guardrail_refusal(repo)
if repo == NANO and guardrail == "absent":
- for part in (f"'{NANO}'", "pip install cosmos-guardrail", f"{_OPT_OUT_ENV}=0"):
+ for part in (
+ f"'{NANO}'",
+ "pip install cosmos-guardrail",
+ f"https://huggingface.co/{_GUARDRAIL_REPO}",
+ "token in Settings",
+ f"{_OPT_OUT_ENV}=0",
+ ):
assert part in refusal, part
assert vc3.guardrail_refusal(NANO, index = _ckpt(EDGE)["model_index"]) is None
else:
@@ -767,6 +773,125 @@ def test_a_wan_load_keeps_the_stock_encode(cosmos3_runtime, monkeypatch):
assert not getattr(backend._state.pipe.vae.encode, "_unsloth_untiled_encode", False)
+_GUARDRAIL_REPO = "nvidia/Cosmos-1.0-Guardrail"
+
+
+def _gated_load(repo):
+ """The guardrail's real 401 text, wrapped in an OSError."""
+ from huggingface_hub.errors import GatedRepoError
+
+ class _Gated(GatedRepoError):
+ def __init__(self, message):
+ Exception.__init__(self, message)
+
+ def from_pretrained(cls, source, **kwargs):
+ try:
+ raise _Gated(
+ f"401 Client Error. Cannot access gated repo for url https://huggingface.co/{repo}/resolve/cf03c03/"
+ f"blocklist/custom/notable.\nAccess to model {repo} is restricted. Please log in."
+ )
+ except _Gated as exc:
+ raise OSError("could not build the safety checker") from exc
+
+ return classmethod(from_pretrained)
+
+
+def test_a_gated_guardrail_download_is_refused_with_the_access_steps(cosmos3_runtime, monkeypatch):
+ _set_guardrail(monkeypatch, "installed")
+ monkeypatch.setattr(_FakeCosmos3Pipeline, "from_pretrained", _gated_load(_GUARDRAIL_REPO))
+ with pytest.raises(ValueError) as refused:
+ _loaded(NANO)
+ message = str(refused.value)
+ for part in (
+ f"'{NANO}'",
+ f"https://huggingface.co/{_GUARDRAIL_REPO}",
+ "token in Settings",
+ f"{_OPT_OUT_ENV}=0",
+ ):
+ assert part in message, part
+ assert "401 Client Error" not in message and "pip install" not in message
+ monkeypatch.setattr(_FakeCosmos3Pipeline, "from_pretrained", _gated_load("nvidia/Cosmos3-Nano"))
+ with pytest.raises(OSError, match = "safety checker"):
+ _loaded(NANO)
+
+
+def _guardrail_downloads(monkeypatch):
+ """Records the token each guardrail snapshot_download sends."""
+ seen = []
+
+ def snapshot_download(
+ repo_id,
+ token = "ambient",
+ **kwargs,
+ ):
+ seen.append(token)
+ return "/nonexistent"
+
+ inner = types.ModuleType("cosmos_guardrail.cosmos_guardrail")
+ inner.snapshot_download = snapshot_download
+ monkeypatch.setitem(sys.modules, "cosmos_guardrail.cosmos_guardrail", inner)
+ return inner, seen
+
+
+ "token, sent",
+ [("hf_settings", "hf_settings"), (False, False), (None, "ambient"), (" ", "ambient")],
+)
+def test_the_guardrail_download_gets_the_loads_token(cosmos3_runtime, monkeypatch, token, sent):
+ _set_guardrail(monkeypatch, "installed")
+ inner, seen = _guardrail_downloads(monkeypatch)
+ real_from_pretrained = _FakeCosmos3Pipeline.__dict__["from_pretrained"]
+
+ def from_pretrained(cls, source, **kwargs):
+ inner.snapshot_download(_GUARDRAIL_REPO, allow_patterns = ["blocklist/*"])
+ return real_from_pretrained.__func__(cls, source, **kwargs)
+
+ monkeypatch.setattr(_FakeCosmos3Pipeline, "from_pretrained", classmethod(from_pretrained))
+ VideoBackend().load_pipeline(NANO, model_kind = "pipeline", hf_token = token)
+ inner.snapshot_download(_GUARDRAIL_REPO)
+ assert seen == [sent, "ambient"]
+
+
+def test_the_guardrail_token_scope_ends_with_a_failed_load(monkeypatch):
+ inner, seen = _guardrail_downloads(monkeypatch)
+ with pytest.raises(RuntimeError):
+ with vc3.guardrail_hub_token("hf_x"):
+ inner.snapshot_download(_GUARDRAIL_REPO)
+ raise RuntimeError("load failed")
+ inner.snapshot_download(_GUARDRAIL_REPO)
+ assert seen == ["hf_x", "ambient"]
+
+
+def test_overlapping_guardrail_loads_keep_their_own_tokens(monkeypatch):
+ """A cancel-and-reload overlaps two loads; exits out of order must not leave either token behind."""
+ import threading
+
+ inner, seen = _guardrail_downloads(monkeypatch)
+ a_in, b_in, a_out = threading.Event(), threading.Event(), threading.Event()
+
+ def load_a():
+ with vc3.guardrail_hub_token("hf_a"):
+ a_in.set()
+ b_in.wait(5)
+ inner.snapshot_download(_GUARDRAIL_REPO)
+ a_out.set()
+
+ def load_b():
+ a_in.wait(5)
+ with vc3.guardrail_hub_token("hf_b"):
+ b_in.set()
+ a_out.wait(5)
+ inner.snapshot_download(_GUARDRAIL_REPO)
+
+ threads = [threading.Thread(target = load_a), threading.Thread(target = load_b)]
+ for t in threads:
+ t.start()
+ for t in threads:
+ t.join(10)
+ inner.snapshot_download(_GUARDRAIL_REPO)
+ assert seen == ["hf_a", "hf_b", "ambient"]
+
+
def test_nano_without_the_guardrail_is_refused_before_the_load_starts(cosmos3_runtime, monkeypatch):
_set_guardrail(monkeypatch, "absent")
started = []
@@ -775,7 +900,7 @@ def test_nano_without_the_guardrail_is_refused_before_the_load_starts(cosmos3_ru
with pytest.raises(ValueError, match = f"{_OPT_OUT_ENV}=0"):
backend.begin_load(NANO, model_kind = "pipeline")
assert started == [] and backend.loading_repo_ids() == ()
- with pytest.raises(ValueError, match = "cosmos_guardrail"):
+ with pytest.raises(ValueError, match = "pip install cosmos-guardrail"):
backend.load_pipeline(NANO, model_kind = "pipeline")
assert _FakeCosmos3Pipeline.loads == []
with pytest.raises(ValueError, match = "limited to"):