For the complete documentation index, see llms.txt. This page is also available as Markdown.

Usage

Downloading and loading models from OmniHub — OmniHubUtils API

OmniHub exposes two entry points for loading pretrained models: the Pretrained facade (the recommended path for named models) and the lower-level OmniHubUtils class (useful when you have a filename and framework string and want direct control).


The Pretrained Facade

org.eclipse.deeplearning4j.omnihub.models.Pretrained is the simplest way to load a known model. It provides static accessor methods for the two framework namespaces:

import org.eclipse.deeplearning4j.omnihub.models.Pretrained;

// Load the VGG19 (no-top) DL4J ComputationGraph
ComputationGraph vgg19 = Pretrained.dl4j().vgg19noTop(false);

// Load the AgeGoogLeNet SameDiff model
SameDiff ageGooglenet = Pretrained.samediff().ageGooglenet(false);

// Load ResNet18 SameDiff model
SameDiff resnet18 = Pretrained.samediff().resnet18(false);

The boolean argument is forceDownload. Pass true to delete the cached copy and re-download even if it already exists locally.

Pretrained.dl4j() returns a Dl4jModels instance. Pretrained.samediff() returns a SameDiffModels instance. Both classes are code-generated from the zoo manifest; their methods map directly to named model files.


OmniHubUtils — Loading DL4J Models

Loading a MultiLayerNetwork

loadNetwork downloads the file from the dl4j/ directory of the zoo, stores it in ~/.omnihub/dl4j/, and loads it using MultiLayerNetwork.load(file, true) (with the parameter updater restored).

Loading a ComputationGraph

loadCompGraph is identical to loadNetwork except it calls ComputationGraph.load(file, true).


OmniHubUtils — Loading SameDiff Models

SameDiff models are stored as FlatBuffers files (.fb). They are downloaded from the samediff/ directory of the zoo and cached under ~/.omnihub/samediff/. Loading uses SameDiff.load(file, true).


Direct Download with downloadAndLoadFromZoo

For cases where you want the local File handle rather than an already-loaded model object, call downloadAndLoadFromZoo directly:

The framework string must match the subdirectory name in the zoo repository ("dl4j" or "samediff").


Caching Behavior

Models are cached in the directory returned by OmnihubConfig.getOmnihubHome():

  • Default: ~/.omnihub

  • Custom: set the OMNIHUB_HOME environment variable before the JVM starts.

The cache structure is flat per-framework:

A download is skipped if the destination file already exists (unless forceDownload is true). There is no checksum verification in the current implementation — if you suspect a file is corrupt, pass forceDownload = true to replace it.


Overriding the Zoo URL

By default, models are fetched from:

To point at a private mirror or a local HTTP server (for air-gapped environments), set the OMNIHUB_URL environment variable:

The URL is read by OmnihubConfig.getOmnihubUrl() each time a download is needed. The file is resolved at:

For example, OmniHubUtils.loadSameDiffModel("resnet18.fb") would fetch:


Download Progress

OmniHubUtils wraps the download stream in a ProgressInputStream that prints a progress indicator to the console. The indicator is sized using an HTTP HEAD request to obtain the Content-Length before streaming begins. No configuration is needed; it activates automatically for every download.


Full Example



Custom Model Repositories (ADR 0076)

Out of the box, OmniHub resolves models from two backends: HuggingFace Hub (tried first, priority 10) and the GitHub-hosted omnihub-zoo (fallback, priority 20). The ModelRepository interface and ModelRepositoryRegistry let you register additional backends — private registries, S3 buckets, on-premise mirrors — without modifying any OmniHub code.

How the fallback chain works

OmniHubUtils.downloadAndLoadFromZoo() internally delegates to ModelRepositoryRegistry.getDefault().resolve(modelName, framework, forceDownload). The registry iterates its list of repositories in ascending priority order, calling canResolve() on each. The first repository that returns true and whose resolve() call succeeds provides the local file. If a repository is tried and throws IOException, the registry logs the failure and continues to the next.

The ModelRepository interface

Implementing a custom repository

The following example adds an internal HTTP mirror as a higher-priority source (priority 5 — tried before HuggingFace):

Registering the custom repository

You can also replace the entire default registry (useful in tests or fully air-gapped environments):

Targeting a specific repository by name

Removing a built-in repository

Default repository priorities at a glance

Repository name
Priority
Resolves

huggingface

10

Any GGUF or SafeTensors file on HuggingFace Hub

github

20

Named models in the omnihub-zoo GitHub repository

(custom)

your choice

Whatever your resolve() implementation fetches

DSL integration

When using the OmniHub Kotlin DSL to declare model namespaces, you can pin a model to a specific repository by setting the repository field. GGUFModel and SafeTensorsModel builders default to repository = "huggingface"; DL4JModel and SameDiffModel use the full fallback chain by default.


Next Steps

  • Available Models — full catalog of models in the zoo, with input/output details.

  • OmniHub Overview — architecture, configuration, and comparison with deeplearning4j-zoo.

Last updated

Was this helpful?