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
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Saved source (HF or ModelScope) sets HF_ENDPOINT and HF_DATASETS_SERVER; operator-exported env
holds until saved; restricted HF with nothing set defaults to ModelScope"""
from __future__ import annotations
import json
import os
import sys
import threading
import weakref
from contextlib import closing
from dataclasses import dataclass
from functools import partial
from urllib.parse import urlsplit
from loggers import get_logger
from storage import sqlite_gate
from utils.hf_endpoint import (
DEFAULTS_BY_HEALTH_KEY,
get_hf_datasets_server,
get_hf_endpoint,
normalize_hf_endpoint_env,
validate_hub_endpoint,
)
logger = get_logger(__name__)
HF_ENDPOINT_KEY = "hub_hf_endpoint"
DATASETS_SERVER_FOLLOWS_KEY = "hub_datasets_server_follows_endpoint"
SOURCE_KEY = "hub_source"
HUGGINGFACE = "huggingface"
MODELSCOPE = "modelscope"
SOURCES = (HUGGINGFACE, MODELSCOPE)
_ENV_VARS = ("HF_ENDPOINT", "HF_DATASETS_SERVER")
SOURCE_ENV = "UNSLOTH_STUDIO_HUB_SOURCE"
_operator_env: dict[str, str | None] | None = None
_operator_endpoints: tuple[str, ...] | None = None
_saved_only_endpoints: frozenset[str] = frozenset()
_apply_lock = threading.Lock()
@dataclass(frozen = True)
class HubSettings:
hf_endpoint: str
datasets_server_follows_endpoint: bool
saved: bool
source: str = HUGGINGFACE
source_automatic: bool = False
def _capture_operator_env() -> dict[str, str | None]:
global _operator_env
if _operator_env is None:
_operator_env = {name: os.environ.get(name) for name in _ENV_VARS}
return _operator_env
def _operator_endpoint() -> str:
raw = _capture_operator_env()["HF_ENDPOINT"] or ""
try:
return validate_hub_endpoint(raw)
except ValueError:
return ""
def operator_hf_endpoint() -> str:
"""The endpoint the environment configured: the one state recorded before saved settings refers to."""
return _operator_endpoint() or DEFAULTS_BY_HEALTH_KEY["hf_endpoint"]
def _read_stored() -> dict | None:
"""The saved hub settings: ``{}`` before the database exists, None when it cannot be read."""
keys = [HF_ENDPOINT_KEY, DATASETS_SERVER_FOLLOWS_KEY, SOURCE_KEY]
try:
from utils.account_context import OWNER, run_as
# get_app_settings creates and migrates studio.db; the startup read must leave it untouched.
if "storage.studio_db" not in sys.modules:
from utils.paths.storage_roots import studio_db_path
path = run_as(OWNER, studio_db_path)
if not path.exists():
return {}
uri = f"{path.resolve().as_uri()}?mode=ro"
with closing(sqlite_gate.connect(uri, uri = True)) as conn:
rows = conn.execute(
"SELECT key, value_json FROM app_settings WHERE key IN (?, ?, ?)", keys
).fetchall()
return {key: json.loads(value) for key, value in rows}
from storage.studio_db import get_app_settings
return run_as(OWNER, get_app_settings, keys)
except Exception as exc: # noqa: BLE001 - a missing or unreadable db keeps the environment's values
logger.debug("hub settings read failed (%s)", exc)
return None
def _automatic_modelscope(stored: dict) -> bool:
"""ModelScope by default where Hugging Face is restricted, until a source or an endpoint is saved or exported."""
from utils.region import mirror_fallback_enabled
return (
SOURCE_KEY not in stored
and HF_ENDPOINT_KEY not in stored
and not (_capture_operator_env()["HF_ENDPOINT"] or "").strip()
and mirror_fallback_enabled()
)
def get_hub_settings() -> HubSettings:
stored = _read_stored()
# A failed read may hide a saved choice, so it never selects the automatic default.
automatic = stored is not None and _automatic_modelscope(stored)
stored = stored or {}
if automatic:
source = MODELSCOPE
else:
source = stored.get(SOURCE_KEY) if stored.get(SOURCE_KEY) in SOURCES else HUGGINGFACE
endpoint = stored.get(HF_ENDPOINT_KEY)
if not isinstance(endpoint, str):
return HubSettings(
_operator_endpoint(), False, saved = False, source = source, source_automatic = automatic
)
try:
endpoint = validate_hub_endpoint(endpoint)
except ValueError:
endpoint = ""
return HubSettings(
endpoint, stored.get(DATASETS_SERVER_FOLLOWS_KEY) is True, saved = True, source = source
)
def active_source() -> str:
return MODELSCOPE if os.environ.get(SOURCE_ENV) == MODELSCOPE else HUGGINGFACE
def active_source_label() -> str:
return "ModelScope" if active_source() == MODELSCOPE else "Hugging Face"
def hugging_face_endpoint() -> str:
"""The Hugging Face endpoint the settings select, also while ModelScope serves."""
return (get_hub_settings().hf_endpoint or DEFAULTS_BY_HEALTH_KEY["hf_endpoint"]).rstrip("/")
def set_hub_source(source: str) -> HubSettings:
"""Persist and apply the model source. Raises ValueError on an unknown one."""
if source not in SOURCES:
raise ValueError(f"Unknown model source {source!r}.")
from storage.studio_db import upsert_app_settings
upsert_app_settings({SOURCE_KEY: source}, read_back = False)
apply_hub_settings()
return get_hub_settings()
def claim_automatic_source() -> bool:
"""Save the automatic ModelScope default. True only for the call that saved it, whose client tells the owner."""
if not get_hub_settings().source_automatic or active_source() != MODELSCOPE:
return False
from storage.studio_db import compare_and_set_app_setting
# An endpoint saved since the read above is a choice too: the claim must not override it.
return compare_and_set_app_setting(SOURCE_KEY, None, MODELSCOPE, absent = (HF_ENDPOINT_KEY,))
def set_hub_settings(hf_endpoint: str, datasets_server_follows_endpoint: bool) -> HubSettings:
"""Validate, persist and apply. Raises ValueError on an unusable endpoint."""
endpoint = validate_hub_endpoint(hf_endpoint)
from storage.studio_db import upsert_app_settings
upsert_app_settings(
{
HF_ENDPOINT_KEY: endpoint,
DATASETS_SERVER_FOLLOWS_KEY: bool(datasets_server_follows_endpoint),
},
read_back = False,
)
apply_hub_settings()
return get_hub_settings()
def _effective_env(settings: HubSettings) -> tuple[dict[str, str | None], str]:
"""The environment for ``settings``, and the source it actually selects."""
operator = _capture_operator_env()
if settings.source == MODELSCOPE:
try:
from hub.modelscope.router import internal_endpoint
env = {
"HF_ENDPOINT": internal_endpoint(),
"HF_DATASETS_SERVER": operator["HF_DATASETS_SERVER"],
}
return env, MODELSCOPE
except Exception: # noqa: BLE001 - a dead adapter must not take the backend down
logger.exception("ModelScope adapter failed to start; using Hugging Face")
if not settings.saved:
return dict(operator), HUGGINGFACE
datasets_server = operator["HF_DATASETS_SERVER"]
if settings.datasets_server_follows_endpoint and settings.hf_endpoint:
datasets_server = settings.hf_endpoint
env = {"HF_ENDPOINT": settings.hf_endpoint or None, "HF_DATASETS_SERVER": datasets_server}
return env, HUGGINGFACE
def apply_hub_settings() -> None:
"""Safe before or after huggingface_hub import; running workers keep the endpoint they started with."""
global _operator_endpoints, _saved_only_endpoints
with _apply_lock:
if _operator_endpoints is None:
_operator_endpoints = (get_hf_endpoint(), get_hf_datasets_server())
env, source = _effective_env(get_hub_settings())
for name, value in env.items():
if value:
os.environ[name] = value
else:
os.environ.pop(name, None)
os.environ[SOURCE_ENV] = source
if source == MODELSCOPE:
_bypass_proxy_for(env["HF_ENDPOINT"])
normalize_hf_endpoint_env()
_saved_only_endpoints = frozenset(
endpoint
for endpoint in (get_hf_endpoint(), get_hf_datasets_server())
if endpoint not in _operator_endpoints
and endpoint not in DEFAULTS_BY_HEALTH_KEY.values()
)
_refresh_imported_hub_libraries()
utils_module = sys.modules.get("utils.utils")
if utils_module is not None:
utils_module.reset_hf_reachability_cache()
endpoint = get_hf_endpoint()
if source == HUGGINGFACE and endpoint != DEFAULTS_BY_HEALTH_KEY["hf_endpoint"]:
try:
from utils.hub_mirror_probe import warn_if_mirror_redirects_to_official
warn_if_mirror_redirects_to_official(endpoint)
except Exception: # noqa: BLE001 - a log-only probe must never fail applying settings
logger.debug("Hugging Face endpoint probe did not start", exc_info = True)
def saved_only_endpoints() -> frozenset[str]:
"""Endpoints only saved settings name, which the browser reaches through the backend relay."""
return _saved_only_endpoints
def _bypass_proxy_for(url: str) -> None:
"""Keep the loopback adapter off a configured proxy: httpx proxies 127.0.0.1 too unless NO_PROXY lists it."""
# Env proxies only: on macOS/Windows env no_proxy makes getproxies() skip system proxy.
from urllib.request import getproxies_environment
host = urlsplit(url).hostname
proxies = getproxies_environment()
if not host or not any(proxies.get(k) for k in ("http", "all")):
return
names = [n for n in ("no_proxy", "NO_PROXY") if n in os.environ] or ["no_proxy", "NO_PROXY"]
changed = False
for name in names:
entries = [e.strip() for e in os.environ.get(name, "").split(",") if e.strip()]
if host not in entries:
os.environ[name] = ",".join([*entries, host])
changed = True
http = sys.modules.get("huggingface_hub.utils._http")
lock = getattr(http, "_CLIENT_LOCK", None)
if changed and lock is not None and hasattr(http, "_GLOBAL_CLIENT"):
# The 1.x shared client read proxies once: drop it, never close it (aborts live downloads).
with lock:
http._GLOBAL_CLIENT = None
# huggingface_hub closes its client in forked children, which can deadlock on httpx locks.
_inherited_hub_clients: list = []
def _close_if_owner(client_ref: weakref.ref, owner_pid: int) -> None:
client = client_ref()
if client is None:
return
if os.getpid() == owner_pid:
type(client).close(client)
else:
_inherited_hub_clients.append(client)
def _keep_hub_client_open_in_forks() -> None:
http = sys.modules.get("huggingface_hub.utils._http")
client = getattr(http, "_GLOBAL_CLIENT", None)
if client is not None and "close" not in vars(client):
# A weak reference, so the client is still freed by refcount once dropped.
client.close = partial(_close_if_owner, weakref.ref(client), os.getpid())
if hasattr(os, "register_at_fork"):
os.register_at_fork(before = _keep_hub_client_open_in_forks)
def _refresh_imported_hub_libraries() -> None:
constants = sys.modules.get("huggingface_hub.constants")
if constants is None or getattr(constants, "_staging_mode", False):
return
endpoint = os.environ.get("HF_ENDPOINT", constants._HF_DEFAULT_ENDPOINT).rstrip("/")
constants.ENDPOINT = endpoint
constants.HUGGINGFACE_CO_URL_TEMPLATE = endpoint + "/{repo_id}/resolve/{revision}/{filename}"
host = urlsplit(endpoint).hostname
hosts = getattr(constants, "HF_URL_HOSTS", None)
if host and isinstance(hosts, frozenset):
constants.HF_URL_HOSTS = hosts | {host.lower()}
hf_api = sys.modules.get("huggingface_hub.hf_api")
if hf_api is not None and getattr(hf_api, "api", None) is not None:
hf_api.api.endpoint = endpoint
hf_file_system = sys.modules.get("huggingface_hub.hf_file_system")
if hf_file_system is not None:
# fsspec hands back the cached instance, which kept the old endpoint.
hf_file_system.HfFileSystem.clear_instance_cache()
datasets_config = sys.modules.get("datasets.config")
if datasets_config is not None:
datasets_config.HF_ENDPOINT = endpoint
datasets_config.HUB_DATASETS_URL = (
endpoint + "/datasets/{repo_id}/resolve/{revision}/{path}"
)