ImageVision.ModelCache (image_vision v0.2.0)

Copy Markdown View Source

On-disk cache for ONNX model weights downloaded from HuggingFace.

Image.Segmentation and Image.Detection use this cache to fetch their default models on first call. Files are downloaded once and reused for the lifetime of the cache directory.

Cache directory

The cache root is resolved in this order:

  • Application.get_env(:image_vision, :cache_dir) if set.

  • Otherwise, :filename.basedir(:user_cache, "image_vision") — on macOS this is ~/Library/Caches/image_vision, on Linux it's $XDG_CACHE_HOME/image_vision (typically ~/.cache/image_vision).

Configure explicitly in config/runtime.exs:

config :image_vision, :cache_dir, "/var/lib/image_vision/models"

Layout

Cached files are stored under {cache_root}/{repo}/{filename}, preserving the HuggingFace repository hierarchy. For example, the SAM 2.1 Tiny encoder lives at:

{cache_root}/facebook/sam2.1-hiera-tiny/sam2.1_hiera_tiny.encoder.onnx

Offline use

Pre-populate the cache with the expected layout to operate fully offline. cached?/2 reports whether a given file is present without triggering a download.

Summary

Functions

cache_root()

Returns the absolute path to the cache root directory, creating it if it does not yet exist.

cached?(repo, filename)

Returns true if the given HuggingFace file is already present in the local cache.

fetch!(repo, filename)

Returns the local path for a HuggingFace model file, downloading it on cache miss.

path(repo, filename)

Returns the local path that a given HuggingFace file would be cached at, without checking whether it exists or downloading it.

Functions

cache_root()

@spec cache_root() :: Path.t()

Returns the absolute path to the cache root directory, creating it if it does not yet exist.

Returns

  • The absolute path as a binary.

cached?(repo, filename)

@spec cached?(String.t(), String.t()) :: boolean()

Returns true if the given HuggingFace file is already present in the local cache.

Arguments

  • repo is the HuggingFace repository.

  • filename is the path within the repository.

Returns

  • A boolean.

fetch!(repo, filename)

@spec fetch!(String.t(), String.t()) :: Path.t()

Returns the local path for a HuggingFace model file, downloading it on cache miss.

Arguments

  • repo is the HuggingFace repository, e.g. "facebook/sam2.1-hiera-tiny".

  • filename is the path within the repository, e.g. "sam2.1_hiera_tiny.encoder.onnx". Sub-directories are supported ("onnx/encoder.onnx").

Returns

  • The absolute local path to the file as a binary.

Raises if the download fails.

Examples

iex> path = ImageVision.ModelCache.fetch!("facebook/sam2.1-hiera-tiny", "config.json")
iex> File.exists?(path)
true

path(repo, filename)

@spec path(String.t(), String.t()) :: Path.t()

Returns the local path that a given HuggingFace file would be cached at, without checking whether it exists or downloading it.

Arguments

  • repo is the HuggingFace repository.

  • filename is the path within the repository.

Returns

  • The absolute local path as a binary.