skip to content

In Transformers.js, how do you drive a model-loading progress bar from the `progress_callback` option of `pipeline()`, and which events does it send?

level: middleimportance: nice to knowfreq 4%

answer

  1. several files, one bar
  2. a status field on every event
  3. initiate, download, progress, done
  4. progress_total sums every file
  5. ready carries task and model

basics

~20 s

Pass progress_callback to pipeline() and switch on each event's status: initiate, download, progress and done arrive per file, progress_total sums bytes across all files, and ready fires once when the pipeline can run. Drive a single bar from progress_total.

solid answer

~40 s

The callback receives plain objects with a `status` field. For each file you get `initiate`, `download`, repeated `progress` events carrying `file`, `progress` (0 to 100), `loaded` and `total` bytes, and finally `done`. A pipeline loads several files (config, tokenizer and one or more ONNX files), so a bar fed from per-file `progress` jumps back to zero at each new file. In Transformers.js 4.3, `pipeline()` wraps your callback and also emits `progress_total`, with summed `loaded` and `total` and a `files` map, after first looking up every expected file's size; that is the event to drive one bar from. `ready` fires once, with `task` and `model`, when the pipeline is usable. On a later visit the same events still fire, fed from the cache, so they are quick but not absent.

go deeper

for a junior

Know that pipeline() accepts a progress_callback and that each event has a status such as progress or ready.

for a middle

Explain the per-file sequence, why per-file progress resets, and why progress_total and ready are the events a single loading bar should use.

for a senior

Design the loading UX: warn before a large first download using is_pipeline_cached, show bytes rather than a bare percentage, and forward events from a worker without treating download as network proof.

for a principal

Decide what first-load experience a model feature can afford and whether it should start on page load, on demand, or behind an explicit opt-in sized from the known file totals.

## Why a loading bar needs this A Transformers.js `pipeline()` call downloads its model from the Hugging Face Hub before it can run, and on a first visit that can take many seconds. Without feedback the page simply looks broken. The `progress_callback` option is how the library reports what it is doing: you pass a function, and it is called with a small, plain object every time something happens during the load. ```javascript const classifier = await pipeline('text-classification', 'your-org/your-model', { progress_callback: (info) => { if (info.status === 'progress_total') bar.value = info.progress; if (info.status === 'ready') bar.hidden = true; }, }); ``` ## The events Every event has a `status` field that tells you which shape it has: | `status` | When it fires | Main fields | |---|---|---| | `initiate` | a file load is about to start | `name` (model id), `file` | | `download` | reading the file's bytes has started | `name`, `file` | | `progress` | bytes of one file have arrived | `file`, `progress` (0-100), `loaded`, `total` | | `progress_total` | alongside each `progress` event | `progress`, `loaded`, `total`, `files` | | `done` | one file has finished loading | `name`, `file` | | `ready` | the pipeline object is built | `task`, `model` | ## The order for a typical load 1. When a callback is passed, and before any weight bytes move, `pipeline()` works out the list of files the model needs and asks for each file's size, from the cache entry when there is one and otherwise with a one-byte Range request to the Hub. Those sizes seed the running totals; if the lookup fails, a warning is logged and the totals fill in as files report. 2. For each file: `initiate`, then `download`, then a stream of `progress` events, each paired with a `progress_total` event, then `done`. 3. Files load in parallel, so per-file events from different files interleave. 4. Once the tokenizer, any processor and the model session are built, a single `ready` event arrives and the awaited Promise resolves. ## One bar for many files - **Per-file `progress` resets.** Each file counts from 0 to 100 on its own, so a bar bound to `info.progress` of `progress` events climbs, drops and climbs again. - **`progress_total` is the aggregate.** It sums `loaded` and `total` over every file seen so far and carries a `files` map of per-file bytes, which also makes a per-file list easy to render. - **Bytes are better than percentages for big models.** Showing `loaded` and `total` tells the user whether this is 30 MB or 300 MB. - **Use `ready`, not the last `done`, to enable the UI.** `done` marks one file; `ready` marks the pipeline. ## Second visits On a returning visit the files come from the browser's Cache API, but the events still fire: `initiate`, `download`, `progress` and `done` arrive quickly as the bytes are read back. In other words `download` means "reading has started", not "the network is being used". One browser quirk is handled for you: in Firefox, progress cannot be reported while reading from the cache, so the library sends a single final `progress` event at 100 percent. ## Knowing before you start Because the events cannot tell you up front whether a download is coming, Transformers.js 4.3 offers `ModelRegistry.is_pipeline_cached(task, model, options)`, which returns a boolean, and `ModelRegistry.is_pipeline_cached_files(...)`, which returns per-file detail. Pass the same `dtype` and `revision` you will load with, because they change the file list. ## Pitfalls - Treating `download` as proof of network traffic. - Hiding the spinner on the first `done` while the largest file is still loading. - Forgetting that a pipeline running in a Web Worker calls the callback inside the worker; the events must be forwarded to the page. ## Rendering tips - **Throttle the redraw.** `progress` and `progress_total` arrive for every chunk read, many times per second on a fast connection; update the DOM at most once per animation frame. - **Show the file list from `files`.** The map in `progress_total` gives bytes per file, which is enough for a detailed view. - **Format bytes, not just percent.** Rendering `loaded` and `total` in megabytes sets expectations on slow networks. - **Keep the bar until `ready`.** Session creation follows the last byte, and on large models it is noticeable.

  • How can a Transformers.js page decide, before calling `pipeline()`, whether the user is about to download the model?
    Call `await ModelRegistry.is_pipeline_cached(task, model, { dtype, revision })`; it returns `true` only when every required file is cached. `is_pipeline_cached_files` gives per-file detail. Use the answer to ask before a large first download, and pass the same options you will load with, since they decide the file list.
  • In Transformers.js, is a `progress_callback` event with status `'download'` proof that the network was used?
    No. It fires after the cache lookup whether the bytes come from the Cache API or from the Hub; it marks the start of reading. Cached loads are simply fast. To know in advance, ask `ModelRegistry.is_pipeline_cached`.

  • progress_callback reports one overall percentage and nothing per file
  • A download event means the bytes came over the network
  • No events fire when the model loads from the cache
  • The ready event fires once per finished file
  • Hide the loader on the first done event

Assumes Transformers.js 4.3; the aggregate progress_total event and the ModelRegistry cache checks were verified against that release.