models

Model checkpoint resolution and caching for eval metrics.

Single public function — :func:ensure_checkpoint — that hands a metric a local path to its weights, downloading on miss. Three source kinds:

an existing local path → returned as-is;
an HTTP(S) URL → downloaded to get_cache_dir() / name via huggingface_hub.http_get (resume + retries built in);
an HF repo id ("org/repo") → :func:huggingface_hub.hf_hub_download if filename is given, else :func:huggingface_hub.snapshot_download. name is ignored in HF mode — HF manages its own cache key under ~/.cache/huggingface/hub.

All download paths are filelock-safe (cooperative across threads, processes, and SLURM ranks) via :func:fastvideo.utils.get_lock.

`fastvideo.eval.models.get_lock`

get_lock(model_name_or_path: str)

`fastvideo.eval.models.get_cache_dir`

get_cache_dir() -> Path

Eval cache root.

Layout::

get_cache_dir() / models /   ← URL-fetched checkpoints (LAION head,
                               AMT, GRiT, …)
get_cache_dir() / torch  /   ← redirected ``TORCH_HOME`` (DINO etc.)
get_cache_dir() / clip   /   ← passed as ``download_root`` to
                               ``clip.load(...)`` callsites
~/.cache/huggingface/hub /   ← left at HF's default; widely shared
                               with other ML projects

Override priority: FASTVIDEO_EVAL_CACHE > ${FASTVIDEO_CACHE_ROOT}/eval.

Metric authors writing new code: when wrapping a third-party loader that has its own cache convention (CLIP's download_root, pyiqa's cache_dir, etc.), pass str(get_cache_dir() / "<library>") so users get a single FASTVIDEO_EVAL_CACHE knob to redirect them all.

Source

def get_cache_dir() -> Path:
    """Eval cache root.
Layout::

    get_cache_dir() / models /   ← URL-fetched checkpoints (LAION head,
                                   AMT, GRiT, …)
    get_cache_dir() / torch  /   ← redirected ``TORCH_HOME`` (DINO etc.)
    get_cache_dir() / clip   /   ← passed as ``download_root`` to
                                   ``clip.load(...)`` callsites
    ~/.cache/huggingface/hub /   ← left at HF&#x27;s default; widely shared
                                   with other ML projects

Override priority: ``FASTVIDEO_EVAL_CACHE`` &gt; ``$&#123;FASTVIDEO_CACHE_ROOT&#125;/eval``.

Metric authors writing new code: when wrapping a third-party loader
that has its own cache convention (CLIP&#x27;s ``download_root``, pyiqa&#x27;s
``cache_dir``, etc.), pass ``str(get_cache_dir() / &quot;&lt;library&gt;&quot;)`` so
users get a single ``FASTVIDEO_EVAL_CACHE`` knob to redirect them all.
&quot;&quot;&quot;
return Path(envs.FASTVIDEO_EVAL_CACHE.get())</code></pre></details>
fastvideo.eval.models.ensure_checkpoint
ensure_checkpoint(name: str, source: str, filename: str | None = None) -> str
Resolve a model checkpoint path, downloading on miss.
See module docstring for the full source contract. name is used
only as the local cache filename for URL sources; ignored otherwise.
Source
def ensure_checkpoint(
    name: str,
    source: str,
    filename: str | None = None,
) -> str:
    """Resolve a model checkpoint path, downloading on miss.
See module docstring for the full source contract. *name* is used
only as the local cache filename for URL sources; ignored otherwise.
&quot;&quot;&quot;
if os.path.exists(source):
    return source

if source.startswith((&quot;http://&quot;, &quot;https://&quot;)):
    return _ensure_url(name, source)

if &quot;/&quot; in source:
    return _ensure_hf(source, filename)

raise ValueError(f&quot;Cannot resolve checkpoint: source &#123;source!r&#125; is neither a &quot;
                 &quot;path, URL, nor HF repo id&quot;)</code></pre></details>