> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Models

> Versioned ONNX models: upload one, read its topology, download it anywhere.

export const Scope = ({type, href}) => {
  const scopes = {
    workflow: ['the ', 'Workflow', ' blob type', '/blob-types/introduction#workflow'],
    scheduler: ['the ', 'Scheduler', ' blob type', '/blob-types/scheduler/overview'],
    onnx: ['the ', 'ONNX Model', ' blob type', '/blob-types/introduction#onnx'],
    worker: ['', 'blobhub-worker', ', which runs on your machines', '/worker/introduction']
  };
  const scope = scopes[type];
  if (!scope) {
    return <p>Unknown scope: {type}</p>;
  }
  return <p className="text-sm text-gray-600 dark:text-gray-400">
      Provided by {scope[0]}<strong>{scope[1]}</strong>{scope[2]}. · <a href={href || scope[3]}>Reference</a>
    </p>;
};

export const Shot = ({src, alt, caption}) => <Frame caption={caption}>
    <img className="block dark:hidden" src={src} alt={alt} />
    <img className="hidden dark:block" src={src.replace(/\.(png|svg)$/, '.dark.$1')} alt={alt} />
  </Frame>;

<Scope type="onnx" />

An ONNX model is uploaded once, described, and downloaded wherever it is needed. BlobHub stores it, describes it and
hands it back; running it is up to you.

Each model is stored as a versioned blob of type `blobhub.model.onnx`, and each revision of it holds one model.
[How BlobHub works](/general/how-it-works) covers blobs, revisions and the type behind them.

## Uploading a model

A model travels as an archive, `model.tar.gz`, holding a single file named `model.onnx`. An archive of up to 4 MiB
goes in the body of one [upload](/blob-types/onnx/upload) request. A larger one goes
[in parts](/blob-types/onnx/multipart-upload): the platform hands back a presigned URL for each 10 MiB part, you send
the parts straight to storage, and one more call completes the upload.

Either way, the call returns an operation id instead of waiting. The platform unpacks the archive in the background,
and you poll the operation until it is `completed`, or `failed` when the archive does not hold a model that parses as
ONNX.

Uploads go to a draft revision, and committing the draft freezes its model. A new revision starts with a copy of the
stored model, so a retrained model is uploaded to the new draft while the committed revision keeps the old one.

## Topology

Once the archive is in, the platform extracts the model file and parses its graph into a JSON topology: the nodes,
inputs, outputs and initializers ONNX defines, without the coefficients. It is the model's shape without its
weights, and it is how you look at a large model without fetching it.

<Shot src="/general/images/models/topology.png" alt="An ONNX model's topology graph" caption="The platform parses every uploaded model into a topology you can read without its weights." />

A revision therefore holds the model in three forms, each fetched on its own: the archive as uploaded
(`model.tar.gz`), the extracted model file (`model.onnx`) and the topology (`model.json`).

## Downloading

[`download`](/blob-types/onnx/download) returns one artifact's bytes inline, in the response. An artifact larger
than 4 MiB comes in ranged parts over presigned URLs instead. [`describe`](/blob-types/onnx/describe) lists the
three artifacts by name and size without fetching any of them, so you know which way to fetch one before you start.

## From Python

The [Python SDK](/sdk/onnx)'s `onnx` module does all of this in a call each. `upload()` packs a `.onnx` file,
sends it in one request or in parts by its size, and waits on the operation. `download()` fetches the extracted
model and caches it for a committed revision. `topology()` returns the parsed graph.

```python theme={null}
import blobhub
from blobhub.types.onnx import Onnx

hub = blobhub.connect(anonymous=True)
model = Onnx(hub.blob("onnx-vision-models", "super-resolution").revision())
path = model.download()      # model.onnx, cached under ~/.cache/blobhub
graph = model.topology()     # the model's graph, without its weights
```

A public model needs no account. The web app's [Labs](https://blobhub.io/labs) page lists the public ones: Object
Detection, Super Resolution and BiDAF. Four [notebooks](/sdk/notebooks) ship in the `blobhub` package: three
download those models and run them on your machine with ONNX Runtime, and the fourth exports a model with PyTorch
and uploads it to a blob of yours.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.