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.

3.7 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""Keep pinned Hugging Face cache paths out of saved model metadata."""

from __future__ import annotations

import os
from collections.abc import Mapping
from typing import Any, Optional

from core.inference.model_ids import hf_cache_repo_id


def _identifier(value: Any) -> Optional[str]:
    if value is None:
        return None
    try:
        identifier = os.fspath(value)
    except TypeError:
        return None
    identifier = str(identifier).strip()
    return identifier or None


def _cache_path_matches_repo(value: Any, repo_id: str) -> bool:
    cached_repo_id = _snapshot_repo_id(value)
    return bool(cached_repo_id and cached_repo_id.casefold() == repo_id.casefold())


def _snapshot_repo_id(value: Any) -> Optional[str]:
    identifier = _identifier(value)
    if not identifier:
        return None
    parts = identifier.replace("\\", "/").split("/")
    has_revision = any(
        part.startswith("models--")
        and parts[index + 1 : index + 2] == ["snapshots"]
        and bool(parts[index + 2 : index + 3])
        and bool(parts[index + 2])
        for index, part in enumerate(parts)
    )
    return hf_cache_repo_id(identifier) if has_revision else None


def _is_snapshot_root(value: Any) -> bool:
    identifier = _identifier(value)
    if not identifier:
        return False
    parts = identifier.replace("\\", "/").split("/")
    for index, part in enumerate(parts):
        if part.startswith("models--") and parts[index + 1 : index + 2] == ["snapshots"]:
            return not any(parts[index + 3 :])
    return False


def _set_standard_identity(config: Any, attribute: str, repo_id: str) -> bool:
    value = getattr(config, attribute, None) if config is not None else None
    # A path inside the snapshot (Spark-TTS loads <snapshot>/LLM) is not the repo root, so the repo id would lose the
    # subfolder and point PEFT at a root with no config.json (#13411).
    if not _cache_path_matches_repo(value, repo_id) or not _is_snapshot_root(value):
        return False
    try:
        setattr(config, attribute, repo_id)
    except (AttributeError, TypeError):
        return False
    return True


def restore_hf_cache_repo_identity(
    model: Any,
    load_target: Any,
    *,
    expected_repo_id: Optional[str] = None,
) -> Optional[str]:
    """Restores the Hub repo id for an exact snapshot path; loaded weights stay pinned, ordinary local models and custom fields untouched; returns the id if changed."""
    target_repo_id = _snapshot_repo_id(load_target)
    if not target_repo_id:
        return None

    repo_id = target_repo_id
    if expected_repo_id is not None:
        expected = _identifier(expected_repo_id)
        if not expected or expected.casefold() != target_repo_id.casefold():
            return None
        repo_id = expected

    changed = _set_standard_identity(
        getattr(model, "config", None),
        "_name_or_path",
        repo_id,
    )
    # PreTrainedModel copies name_or_path onto the instance, so updating only the config leaves it stale; PEFT writes that slot to adapter_config.
    changed = _set_standard_identity(model, "name_or_path", repo_id) or changed
    changed = _set_standard_identity(model, "_hf_repo", repo_id) or changed

    peft_config = getattr(model, "peft_config", None)
    if isinstance(peft_config, Mapping):
        for adapter_config in peft_config.values():
            changed = (
                _set_standard_identity(
                    adapter_config,
                    "base_model_name_or_path",
                    repo_id,
                )
                or changed
            )

    return repo_id if changed else None