> For the complete documentation index, see [llms.txt](https://deeplearning4j.konduit.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://deeplearning4j.konduit.ai/en-1.0.0-rewrite/omnihub/usage.md). # Usage 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: ```java 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 ```java 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 ```java 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 ```java 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: ```java 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: ```bash 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 ```java 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 ```java 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): ```java 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 ```java 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): ```java 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 ```java 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 ```java // 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 // 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](/en-1.0.0-rewrite/omnihub/available-models.md) — full catalog of models in the zoo, with input/output details. * [OmniHub Overview](/en-1.0.0-rewrite/omnihub/overview.md) — architecture, configuration, and comparison with deeplearning4j-zoo. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://deeplearning4j.konduit.ai/en-1.0.0-rewrite/omnihub/usage.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.