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.

13.3 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

"""Weights are HF cache files (Model Hub and deletion see them); materialize hardlinks them by real
name into a farm beside the cache, since audio.cpp picks loaders by extension after resolving
symlinks. Real-file caches skip it, except on Windows, where the short farm path avoids the
260-char limit."""

from __future__ import annotations

import json
import os
import shutil
import sys
import time
import uuid
from pathlib import Path
from typing import Optional

from core.inference.audio_cpp_models import AudioCppModel, snapshot_dirs
from loggers import get_logger

logger = get_logger(__name__)

_LINK_FARM_DIRNAME = "unsloth-audiocpp-links"
# Records which repo files a farm entry mirrors, so pruning needs no catalog.
_SOURCE_MARKER = ".unsloth-source.json"
# The Windows audiocpp_server cannot open longer model paths, even with the long-path prefix.
_WINDOWS_MAX_MODEL_PATH = 259


def _hub_cache() -> Path:
    from utils.hf_cache_settings import active_hf_hub_cache
    return Path(active_hf_hub_cache())


def _file_complete(path: Path, size: int = 0) -> bool:
    try:
        if not path.is_file():
            return False
        actual = path.stat().st_size
        return actual > 0 and (size <= 0 or actual == size)
    except OSError:
        return False


def _find(model: AudioCppModel, hub_cache: Path) -> Optional[tuple[Path, list[Path]]]:
    """The first snapshot holding every file of the model's variant, with those files."""
    if model.local_path:
        path = Path(model.local_path)
        return (path.parent, [path]) if _file_complete(path) else None
    for snapshot in snapshot_dirs(model.repo_id, hub_cache):
        found = []
        for f in model.variant.files:
            path = snapshot / f.path
            if not _file_complete(path, f.size):
                break
            found.append(path)
        else:
            return snapshot, found
    return None


def cached_files(model: AudioCppModel, *, hub_cache: Optional[Path] = None) -> Optional[list[Path]]:
    """The variant's files in the HF cache (snapshot paths), or None when not fully downloaded."""
    root = hub_cache if hub_cache is not None else _hub_cache()
    try:
        found = _find(model, root)
    except OSError:
        return None
    return found[1] if found else None


def is_downloaded(model: AudioCppModel) -> bool:
    try:
        return cached_files(model) is not None
    except Exception:  # noqa: BLE001 - a probe never fails its caller
        return False


def missing_files(
    model: AudioCppModel, *, hub_cache: Optional[Path] = None
) -> list[tuple[str, int]]:
    """``(repo path, size)`` of the variant's files the best snapshot still lacks."""
    if model.local_path:
        return []
    root = hub_cache if hub_cache is not None else _hub_cache()
    snapshots = snapshot_dirs(model.repo_id, root)
    first: Optional[list[tuple[str, int]]] = None
    for snapshot in snapshots:
        missing = [
            (f.path, f.size)
            for f in model.variant.files
            if not _file_complete(snapshot / f.path, f.size)
        ]
        if not missing:
            return []
        if first is None:
            first = missing
    # Measured on refs/main (unpinned downloads land there), not the older snapshot with fewest misses.
    return first if first is not None else [(f.path, f.size) for f in model.variant.files]


def _relative(model: AudioCppModel, repo_path: str) -> Path:
    """A variant file's path below the model's own folder: the umbrella folder prefix dropped."""
    path = repo_path.replace("\\", "/")
    prefix = f"{model.folder}/" if model.folder else ""
    if prefix and path.startswith(prefix):
        path = path[len(prefix) :]
    parts = path.split("/")
    # Repo file names are untrusted: "embeddings/..\\..\\x" would land outside the farm.
    if any(p in ("", ".", "..") or ":" in p for p in parts):
        from core.inference.audio_cpp_server import AudioCppUnavailableError
        raise AudioCppUnavailableError(f"Refusing the model file path {repo_path!r}.")
    return Path(*parts)


def _served_path(model: AudioCppModel, farm: Path) -> Path:
    return farm if model.is_package else farm / _relative(model, model.variant.primary)


def materialize(model: AudioCppModel, *, hub_cache: Optional[Path] = None) -> str:
    """Server-config path: the GGUF under its real name, or a package directory. Raises FileNotFoundError if not downloaded."""
    root = hub_cache if hub_cache is not None else _hub_cache()
    found = _find(model, root)
    if found is None:
        raise FileNotFoundError(f"{model.display_name} ({model.variant.key}) is not downloaded.")
    snapshot, files = found
    windows = sys.platform == "win32"
    if model.local_path:
        problem = served_path_problem(model, hub_cache = root)
        if problem:
            from core.inference.audio_cpp_server import AudioCppUnavailableError
            raise AudioCppUnavailableError(problem)
        return str(files[0])
    if not windows and not any(p.is_symlink() for p in files):
        base = snapshot / model.folder if model.folder else snapshot
        return str(base if model.is_package else snapshot / model.variant.primary)
    prune_link_farm(root)
    # One short dir per model/variant; files keep their layout (PocketTTS reads embeddings/ beside GGUF).
    farm_root = _link_farm_root(root)
    if _is_link(farm_root):
        _unlink_link(farm_root)
    farm = farm_root / model.key
    problem = served_path_problem(model, hub_cache = root)
    if problem:
        from core.inference.audio_cpp_server import AudioCppUnavailableError
        raise AudioCppUnavailableError(problem)
    for src, entry in zip(files, model.variant.files):
        rel = _relative(model, entry.path)
        dst = farm / rel
        blob = Path(os.path.realpath(src))
        # A link planted anywhere between the farm and the file would take the write elsewhere.
        for parent in [dst.parent, *dst.parent.parents]:
            if parent == farm_root.parent:
                break
            if _is_link(parent):
                _unlink_link(parent)
        if _already_materialized(dst, blob):
            continue
        try:
            dst.parent.mkdir(parents = True, exist_ok = True)
        except OSError as exc:
            from core.inference.audio_cpp_server import AudioCppUnavailableError
            raise AudioCppUnavailableError(
                f"The audio runtime needs a writable folder beside the Hugging Face cache ({farm_root}): "
                f"{exc}. Move the Hugging Face cache in Settings."
            ) from exc
        # Unique per call: concurrent first loads (dictation skips the load lock) must not unlink each other.
        tmp = dst.with_name(f"{dst.name}.unsloth-tmp-{os.getpid()}-{uuid.uuid4().hex[:8]}")
        try:
            try:
                os.link(blob, tmp)
            except OSError as exc:
                # Another volume or a filesystem without hardlinks: a copy is the only way to give the file its name.
                logger.info("audio.cpp: hardlink failed for %s (%s); copying", rel, exc)
                shutil.copyfile(blob, tmp)
                shutil.copystat(blob, tmp)
            os.replace(tmp, dst)
        finally:
            tmp.unlink(missing_ok = True)
    try:
        (farm / _SOURCE_MARKER).write_text(
            json.dumps(
                {
                    "repo_id": model.repo_id,
                    "files": [[f.path, f.size] for f in model.variant.files],
                }
            ),
            encoding = "utf-8",
        )
    except OSError as exc:
        logger.debug("audio.cpp: could not record the farm entry's source: %s", exc)
    return str(_served_path(model, farm))


def served_path_problem(model: AudioCppModel, *, hub_cache: Optional[Path] = None) -> Optional[str]:
    """Why the Windows server could not open the path ``materialize`` would hand it, or None. Checked
    before any download or eviction, so a refused model costs nothing."""
    if sys.platform != "win32":
        return None
    if model.local_path:
        longest = Path(model.local_path)
    else:
        root = hub_cache if hub_cache is not None else _hub_cache()
        farm = _link_farm_root(root) / model.key
        longest = max(
            (farm / _relative(model, f.path) for f in model.variant.files),
            key = lambda p: len(str(p)),
            default = _served_path(model, farm),
        )
    if len(str(longest)) <= _WINDOWS_MAX_MODEL_PATH:
        return None
    return (
        f"The path the audio runtime would load {model.display_name} from is {len(str(longest))} "
        f"characters, over the {_WINDOWS_MAX_MODEL_PATH} Windows allows. Move the Hugging Face cache "
        "to a shorter path in Settings and download the model again."
    )


def _link_farm_root(hub_cache: Path) -> Path:
    return hub_cache.parent / _LINK_FARM_DIRNAME


def _already_materialized(dst: Path, blob: Path) -> bool:
    """The farm already holds ``blob`` at ``dst``: the same inode, or (a copy) the same size and mtime."""
    try:
        if not dst.is_file():
            return False
        if os.path.samefile(dst, blob):
            return True
        a, b = dst.stat(), blob.stat()
        return a.st_size == b.st_size and int(a.st_mtime) == int(b.st_mtime)
    except OSError:
        return False


def _source_still_cached(model_dir: Path, hub_cache: Path) -> bool:
    """Whether the repo files a farm entry mirrors are all still in the cache."""
    try:
        source = json.loads((model_dir / _SOURCE_MARKER).read_text(encoding = "utf-8"))
        repo_id = str(source["repo_id"])
        files = [(str(path), int(size)) for path, size in source["files"]]
    except (OSError, ValueError, KeyError, TypeError):
        return False
    if not files:
        return False
    for snapshot in snapshot_dirs(repo_id, hub_cache):
        if all(_file_complete(snapshot / path, size) for path, size in files):
            return True
    return False


def prune_link_farm(hub_cache: Optional[Path] = None) -> int:
    """Drops farm entries whose model left the cache (a hardlink would keep its disk alive); entries with no source record too. Never raises."""
    removed = 0
    try:
        root = hub_cache if hub_cache is not None else _hub_cache()
        farm = _link_farm_root(root)
        if _is_link(farm) or not farm.is_dir():
            return 0
        for model_dir in list(farm.iterdir()):
            if _is_link(model_dir):
                # Never materialize's work: drop the link itself, never what it points at.
                _unlink_link(model_dir)
                continue
            if not model_dir.is_dir():
                continue
            keep = _source_still_cached(model_dir, root)
            if not keep and not (model_dir / _SOURCE_MARKER).exists():
                # A materialize in flight writes its marker last; only an old entry lacks one for long.
                try:
                    if time.time() - model_dir.stat().st_mtime < 3600:
                        keep = True
                except OSError:
                    pass
            files, dirs = _walk_no_links(model_dir)
            for path in files:
                try:
                    # Staging files of a live materialize are young; only a crashed one is old.
                    stale_tmp = (
                        ".unsloth-tmp" in path.name and time.time() - path.stat().st_mtime > 3600
                    )
                    if not keep or stale_tmp:
                        path.unlink()
                        removed += 1
                except OSError:
                    continue
            if keep:
                # A kept model's empty folders may be ones a concurrent materialize has just made.
                continue
            for directory in sorted([*dirs, model_dir], key = lambda p: -len(p.parts)):
                try:
                    directory.rmdir()
                except OSError:
                    pass
    except Exception as exc:  # noqa: BLE001 - housekeeping never fails a load or delete
        logger.debug("audio.cpp: link farm prune failed: %s", exc)
    return removed


def _is_link(path: Path) -> bool:
    """A symlink or (Windows) junction: something the farm must never traverse or write through."""
    try:
        if path.is_symlink():
            return True
        attrs = getattr(os.lstat(path), "st_file_attributes", 0)
        return bool(attrs & getattr(os, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)) if attrs else False
    except OSError:
        return False


def _unlink_link(path: Path) -> None:
    try:
        path.unlink()
    except OSError:
        try:
            os.rmdir(path)
        except OSError:
            pass


def _walk_no_links(top: Path) -> tuple[list[Path], list[Path]]:
    """Files and directories under ``top``, never descending into (or returning) a link."""
    files: list[Path] = []
    dirs: list[Path] = []
    pending = [top]
    while pending:
        try:
            entries = list(pending.pop().iterdir())
        except OSError:
            continue
        for entry in entries:
            if _is_link(entry):
                _unlink_link(entry)
            elif entry.is_dir():
                dirs.append(entry)
                pending.append(entry)
            elif entry.is_file():
                files.append(entry)
    return files, dirs