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

import org.eclipse.deeplearning4j.omnihub.OmniHubUtils;
import org.deeplearning4j.nn.multilayer.MultiLayerNetwork;

// Load from cache (download if not cached)
MultiLayerNetwork net = OmniHubUtils.loadNetwork("mymodel.zip");

// Force re-download even if cached
MultiLayerNetwork net = OmniHubUtils.loadNetwork("mymodel.zip", true);

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

import org.deeplearning4j.nn.graph.ComputationGraph;

ComputationGraph graph = OmniHubUtils.loadCompGraph("vgg19_weights_tf_dim_ordering_tf_kernels_notop.zip");

// With force download
ComputationGraph graph = OmniHubUtils.loadCompGraph(
    "vgg19_weights_tf_dim_ordering_tf_kernels_notop.zip",
    true
);

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

---

OmniHubUtils — Loading SameDiff Models

import org.nd4j.autodiff.samediff.SameDiff;

SameDiff model = OmniHubUtils.loadSameDiffModel("age_googlenet.fb");

// With force download
SameDiff model = OmniHubUtils.loadSameDiffModel("age_googlenet.fb", true);

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:

import java.io.File;

File modelFile = OmniHubUtils.downloadAndLoadFromZoo(
    "samediff",           // framework subdirectory
    "resnet18.fb",        // filename
    false                 // forceDownload
);

// Now load it yourself
SameDiff sd = SameDiff.load(modelFile, true);

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:

~/.omnihub/
  dl4j/
    vgg19_weights_tf_dim_ordering_tf_kernels_notop.zip
  samediff/
    age_googlenet.fb
    resnet18.fb

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:

https://raw.githubusercontent.com/KonduitAI/omnihub-zoo/main

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

export OMNIHUB_URL=http://internal-mirror.example.com/omnihub

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

${OMNIHUB_URL}/${framework}/${name}

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

http://internal-mirror.example.com/omnihub/samediff/resnet18.fb

---

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

import org.eclipse.deeplearning4j.omnihub.models.Pretrained;
import org.deeplearning4j.nn.graph.ComputationGraph;
import org.nd4j.linalg.factory.Nd4j;
import org.nd4j.linalg.api.ndarray.INDArray;

public class OmniHubExample {
    public static void main(String[] args) throws Exception {
        // Load VGG19 (no top layers) — downloads on first run, cached thereafter
        ComputationGraph vgg19 = Pretrained.dl4j().vgg19noTop(false);

        // VGG19 no-top expects input shape [batch, 3, 224, 224] (channels-first)
        INDArray input = Nd4j.rand(new int[]{1, 3, 224, 224});
        INDArray[] output = vgg19.output(input);

        System.out.println("VGG19 feature map shape: " + output[0].shapeInfoToString());
    }
}

---

---

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

package org.eclipse.deeplearning4j.omnihub.repository;

public interface ModelRepository {

    /** Human-readable identifier, e.g. "github", "huggingface", "internal-s3". */
    String name();

    /** Priority: lower values are tried first. Built-ins use 10 (HF) and 20 (GitHub). */
    int priority();

    /**
     * Quick check: can this repository potentially serve modelName / framework?
     * Returning true does not guarantee success — resolve() may still throw.
     */
    boolean canResolve(String modelName, String framework);

    /**
     * Download or retrieve from cache the model with the given name and framework.
     * Returns the local File on success; throws IOException if not available.
     */
    File resolve(String modelName, String framework, boolean forceDownload) throws IOException;

    /** Whether this repository supports HuggingFace-style repo ID resolution. */
    boolean supportsHuggingFace();

    /**
     * Resolve a HuggingFace repo by ID (e.g. "TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF")
     * and optional file glob pattern. Returns the local directory.
     */
    File resolveHuggingFace(String huggingFaceId, String filePattern, boolean forceDownload)
            throws IOException;
}

Implementing a custom repository

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

import org.eclipse.deeplearning4j.omnihub.repository.ModelRepository;

import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.net.URI;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;

public class InternalMirrorRepository implements ModelRepository {

    private final String baseUrl;
    private final File cacheDir;

    public InternalMirrorRepository(String baseUrl, File cacheDir) {
        this.baseUrl = baseUrl;                        // e.g. "http://ml-mirror.corp.example.com/models"
        this.cacheDir = cacheDir;
    }

    @Override
    public String name() { return "internal-mirror"; }

    @Override
    public int priority() { return 5; }               // tried before HuggingFace (10) and GitHub (20)

    @Override
    public boolean canResolve(String modelName, String framework) {
        // Optimistic: assume this mirror has everything. Replace with a HEAD request if desired.
        return true;
    }

    @Override
    public File resolve(String modelName, String framework, boolean forceDownload) throws IOException {
        File dest = new File(new File(cacheDir, framework), modelName);

        if (dest.exists() && !forceDownload) {
            return dest;
        }

        String url = baseUrl + "/" + framework + "/" + modelName;
        dest.getParentFile().mkdirs();

        try (InputStream in = URI.create(url).toURL().openStream()) {
            Files.copy(in, dest.toPath(), StandardCopyOption.REPLACE_EXISTING);
        }
        return dest;
    }

    @Override
    public boolean supportsHuggingFace() { return false; }

    @Override
    public File resolveHuggingFace(String huggingFaceId, String filePattern, boolean forceDownload) {
        throw new UnsupportedOperationException("Internal mirror does not support HuggingFace IDs");
    }
}

Registering the custom repository

import org.eclipse.deeplearning4j.omnihub.repository.ModelRepositoryRegistry;

ModelRepositoryRegistry registry = ModelRepositoryRegistry.getDefault();

registry.addRepository(new InternalMirrorRepository(
        "http://ml-mirror.corp.example.com/models",
        new File(System.getProperty("user.home"), ".omnihub")
));

// The registry is now: internal-mirror (5) → huggingface (10) → github (20)
// All subsequent OmniHubUtils calls go through the updated registry.

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

ModelRepositoryRegistry offline = new ModelRepositoryRegistry();
offline.addRepository(new InternalMirrorRepository("http://airgap-server/models",
        new File("/data/model-cache")));

ModelRepositoryRegistry.setDefault(offline);

Targeting a specific repository by name

import org.eclipse.deeplearning4j.omnihub.OmniHubUtils;

// Bypass the fallback chain and go directly to the named repository.
// Throws IOException if the named repository is not registered or cannot resolve the model.
File modelFile = OmniHubUtils.loadFromRepository("internal-mirror", "resnet18.fb", "samediff", false);

Removing a built-in repository

// Remove the GitHub fallback to prevent any outbound traffic to github.com
ModelRepositoryRegistry.getDefault().removeRepository("github");

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.

// Kotlin DSL example
GGUFModel(
    name = "llama-3-8b-q4",
    huggingFaceId = "meta-llama/Meta-Llama-3-8B-GGUF",
    filePattern = "*Q4_K_M*.gguf",
    repository = "huggingface"   // explicit; same as default for GGUFModel
)

SameDiffModel(
    name = "resnet18",
    filename = "resnet18.fb",
    repository = null            // null → use the full fallback chain
)

---

Next Steps

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

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