transformers-js
Run state-of-the-art machine learning models directly in JavaScript. `@huggingface/transformers` supports text, vision, audio, and multimodal tasks in browsers and Node.js / Bun / Deno, with WebGPU or WASM execution.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
Run 🤗 Transformers directly in your browser, with no need for a server!
Transformers.js is designed to be functionally equivalent to Hugging Face's transformers python library, meaning you can run the same pretrained models using a very similar API. These models support common tasks in different modalities, such as:
- 📝 Natural Language Processing: text classification, named entity recognition, question answering, language modeling, summarization, translation, multiple choice, and text generation.
- 🖼️ Computer Vision: image classification, object detection, segmentation, and depth estimation.
- 🗣️ Audio: automatic speech recognition, audio classification, and text-to-speech.
- 🐙 Multimodal: embeddings, zero-shot audio classification, zero-shot image classification, and zero-shot object detection.
Transformers.js uses ONNX Runtime to run models in the browser. The best part about it, is that you can easily convert your pretrained PyTorch, TensorFlow, or JAX models to ONNX using 🤗 Optimum.
For more information, check out the full documentation.
Installation
To install via NPM, run:
npm i @huggingface/transformers
Alternatively, you can use it in vanilla JS, without any bundler, by using a CDN or static hosting. For example, using ES Modules, you can import the library with:
<script type="module">
import { pipeline } from 'https://cdn.jsdelivr.net/npm/@huggingface/[email protected]';
</script>
Quick tour
It's super simple to translate from existing code! Just like the python library, we support the pipeline API. Pipelines group together a pretrained model with preprocessing of inputs and postprocessing of outputs, making it the easiest way to run models with the library.
from transformers import pipeline
# Allocate a pipeline for sentiment-analysis
pipe = pipeline('sentiment-analysis')
out = pipe('I love transformers!')
# [{'label': 'POSITIVE', 'score': 0.999806941}]
import { pipeline } from '@huggingface/transformers';
// Allocate a pipeline for sentiment-analysis
const pipe = await pipeline('sentiment-analysis');
const out = await pipe('I love transformers!');
// [{'label': 'POSITIVE', 'score': 0.999817686}]
You can also use a different model by specifying the model id or path as the second argument to the pipeline function. For example:
// Use a different model for sentiment-analysis
const pipe = await pipeline('sentiment-analysis', 'Xenova/bert-base-multilingual-uncased-sentiment');
By default, when running in the browser, the model will be run on your CPU (via WASM). If you would like
to run the model on your GPU (via WebGPU), you can do this by setting device: 'webgpu', for example:
// Run the model on WebGPU
const pipe = await pipeline('sentiment-analysis', 'Xenova/distilbert-base-uncased-finetuned-sst-2-english', {
device: 'webgpu',
});
For more information, check out the WebGPU guide.
[!WARNING] The WebGPU API is still experimental in many browsers, so if you run into any issues, please file a bug report.
In resource-constrained environments, such as web browsers, it is advisable to use a quantized version of
the model to lower bandwidth and optimize performance. This can be achieved by adjusting the dtype option,
which allows you to select the appropriate data type for your model. While the available options may vary
depending on the specific model, typical choices include "fp32" (default for WebGPU), "fp16", "q8"
(default for WASM), and "q4". For more information, check out the quantization guide.
// Run the model at 4-bit quantization
const pipe = await pipeline('sentiment-analysis', 'Xenova/distilbert-base-uncased-finetuned-sst-2-english', {
dtype: 'q4',
});
Ready to dive in? Explore our wide variety of demo applications and templates here. You can also launch your own project instantly using the official Transformers.js template on Hugging Face!
Custom usage
By default, Transformers.js uses hosted pretrained models and precompiled WASM binaries, which should work out-of-the-box. You can customize this as follows:
Settings
import { env } from '@huggingface/transformers';
// Specify a custom location for models (defaults to '/models/').
env.localModelPath = '/path/to/models/';
// Disable the loading of remote models from the Hugging Face Hub:
env.allowRemoteModels = false;
// Set location of .wasm files. Defaults to use a CDN.
env.backends.onnx.wasm.wasmPaths = '/path/to/files/';
For a full list of available settings, check out the API Reference.
Convert your models to ONNX
We recommend using Optimum to convert your PyTorch models to ONNX in a single command. For the full list of supported architectures, check out the Optimum documentation.
Supported tasks/models
Here is the list of all tasks and architectures currently supported by Transformers.js. If you don't see your task/model listed here
// HOW IT'S BUILT
// FILES
5 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
.ai/skills/transformers-js/SKILL.md9.8 KBc555715c9a19upstream ↗
--- name: transformers-js description: Run state-of-the-art machine learning models directly in JavaScript. `@huggingface/transformers` supports text, vision, audio, and multimodal tasks in browsers and Node.js / Bun / Deno, with WebGPU or WASM execution. license: Apache-2.0 metadata: author: huggingface repository: https://github.com/huggingface/transformers.js compatibility: Node.js 20+ (or equivalent Bun / Deno), or a modern browser with ES modules. WebGPU requires runtime and hardware support; WASM is the fallback. Model downloads from the Hugging Face Hub require network access unless you ship models locally. --- # transformers.js ML inference for JavaScript, without a Python server. Supports text, vision, audio, and multimodal tasks through a single `pipeline()` entry point. ## Install ```bash npm install @huggingface/transformers ``` ## Quick start ```javascript import { pipeline } from "@huggingface/transformers"; const classifier = await pipeline("sentiment-analysis"); const output = await classifier("I love transformers!"); // [{ label: "POSITIVE", score: 0.9998 }] ``` `pipeline(task, model?, options?)` is the one function you need 90% of the time. Passing no `model` uses the default for that task. ## Supported tasks <!-- @generated:start id=task-list --> - [`text-classification`](references/TASKS.md#text-classification) _(alias: `sentiment-analysis`)_ — default model: `Xenova/distilbert-base-uncased-finetuned-sst-2-english` - [`token-classification`](references/TASKS.md#token-classification) _(alias: `ner`)_ — default model: `Xenova/bert-base-multilingual-cased-ner-hrl` - [`question-answering`](references/TASKS.md#question-answering) — default model: `Xenova/distilbert-base-cased-distilled-squad` - [`fill-mask`](references/TASKS.md#fill-mask) — default model: `onnx-community/ettin-encoder-32m-ONNX` - [`summarization`](references/TASKS.md#summarization) — default model: `Xenova/distilbart-cnn-6-6` - [`translation`](references/TASKS.md#translation) — default model: `Xenova/t5-small` - [`text2text-generation`](references/TASKS.md#text2text-generation) — default model: `Xenova/flan-t5-small` - [`text-generation`](references/TASKS.md#text-generation) — default model: `onnx-community/Qwen3-0.6B-ONNX` - [`zero-shot-classification`](references/TASKS.md#zero-shot-classification) — default model: `Xenova/distilbert-base-uncased-mnli` - [`audio-classification`](references/TASKS.md#audio-classification) — default model: `Xenova/wav2vec2-base-superb-ks` - [`zero-shot-audio-classification`](references/TASKS.md#zero-shot-audio-classification) — default model: `Xenova/clap-htsat-unfused` - [`automatic-speech-recognition`](references/TASKS.md#automatic-speech-recognition) _(alias: `asr`)_ — default model: `Xenova/whisper-tiny.en` - [`text-to-audio`](references/TASKS.md#text-to-audio) _(alias: `text-to-speech`)_ — default model: `onnx-community/Supertonic-TTS-ONNX` - [`image-to-text`](references/TASKS.md#image-to-text) — default model: `Xenova/vit-gpt2-image-captioning` - [`image-classification`](references/TASKS.md#image-classification) — default model: `Xenova/vit-base-patch16-224` - [`image-segmentation`](references/TASKS.md#image-segmentation) — default model: `Xenova/detr-resnet-50-panoptic` - [`background-removal`](references/TASKS.md#background-removal) — default model: `Xenova/modnet` - [`zero-shot-image-classification`](references/TASKS.md#zero-shot-image-classification) — default model: `Xenova/clip-vit-base-patch32` - [`object-detection`](references/TASKS.md#object-detection) — default model: `Xenova/detr-resnet-50` - [`zero-shot-object-detection`](references/TASKS.md#zero-shot-object-detection) — default model: `Xenova/owlvit-base-patch32` - [`document-question-answering`](references/TASKS.md#document-question-answering) — default model: `Xenova/donut-base-finetuned-docvqa` - [`image-to-image`](references/TASKS.md#image-to-image) — default model: `Xenova/swin2SR-classical-sr-x2-64` - [`depth-estimation`](references/TASKS.md#depth-estimation) — default model: `onnx-community/depth-anything-v2-small` - [`feature-extraction`](references/TASKS.md#feature-extraction) _(alias: `embeddings`)_ — default model: `onnx-community/all-MiniLM-L6-v2-ONNX` - [`image-feature-extraction`](references/TASKS.md#image-feature-extraction) — default model: `onnx-community/dinov3-vits16-pretrain-lvd1689m-ONNX` <!-- @generated:end id=task-list --> For full recipes — every task, grouped by modality, with runnable code — see [`references/TASKS.md`](references/TASKS.md). ## Choosing a model Browse models compatible with transformers.js on the Hub: <https://huggingface.co/models?library=transformers.js> Filter by task with the `pipeline_tag` parameter, e.g. <https://huggingface.co/models?library=transformers.js&pipeline_tag=text-generation>. **Before recommending a model**, confirm it actually has ONNX weights — the library cannot load a model without them. Two ways to check: 1. Open the model page on the Hub and look for an `onnx/` directory in the "Files and versions" tab. 2. Programmatically, with `ModelRegistry.get_available_dtypes(modelId)` — returns the list of dtypes shipped. An empty array means the model exists but ships no ONNX files. It throws a `ModelFileNotFoundError` if the model does not exist or is not accessible (private/gated — the Hub cannot tell these apart), and a regular error on network failures, so an unreachable model is never mistaken for one without ONNX files. ```javascript import { ModelRegistry, ModelFileNotFoundError } from "@huggingface/transformers"; // "Xenova/some-model" is a placeholder — substitute the ID you want to check. try { const dtypes = await ModelRegistry.get_available_dtypes("Xenova/some-model"); if (dtypes.length === 0) { // Model exists but has no ONNX files — not usable with transformers.js. } } catch (e) { if (e instanceof ModelFileNotFoundError) { // Model does not exist, or is private/gated without a token. } else { throw e; // network failure — retry rather than blacklisting the model } } ``` Don't suggest a model without verifying this; the failure mode at runtime is a download error that's harder to diagnose than a pre-flight check. For a fuller pre-flight pattern (cache checks, dtype fallback), see [`references/CONFIGURATION.md`](references/CONFIGURATION.md#inspecting-models-before-loading). ### Quantization Most pipelines accept a `dtype` option. Smaller dtypes download and run faster at the cost of some accuracy: | `dtype` | Size | Use when | |----------|-----------|----------------------------------------------------| | `fp32` | Largest | Maximum accuracy, Node.js with lots of RAM | | `fp16` | ~50% of fp32 | GPU / WebGPU inference | | `q8` | ~25% of fp32 | Good default for browsers | | `q4` | ~12% of fp32 | Tight memory budgets, large language models | | `q4f16` | ~12% of fp32 | Like `q4` but with fp16 activations — pairs well with WebGPU LLMs | ```javascript const pipe = await pipeline("text-generation", "onnx-community/Qwen3-0.6B-ONNX", { dtype: "q4", }); ``` ### Device Default is CPU/WASM. Pass `device: "webgpu"` to run on the GPU when available: ```javascript const pipe = await pipeline("sentiment-analysis", null, { device: "webgpu" }); ``` ## Memory management Pipelines hold onto model weights and backend sessions. **Always call `pipe.dispose()`** when you're done with one — especially in long-running servers, before loading a replacement, or on component unmount. ```javascript const pipe = await pipeline("sentiment-analysis"); try { const result = await pipe("Great!"); } finally { await pipe.dispose(); } ``` ## Configuration The [`env`](https://huggingface.co/docs/transformers.js/api/env) export lets you control model sources, caching, logging, and the fetch function. ```javascript import { env, LogLevel } from "@huggingface/transformers"; env.allowRemoteModels = true; env.useFSCache = true; // Node.js: cache downloaded models on disk env.useBrowserCache = true; // Browser: cache via the Cache API env.logLevel = LogLevel.WARNING; ``` See [`references/CONFIGURATION.md`](references/CONFIGURATION.md) for the full set of environment options, cache management, and private / gated models. ## Pipeline options Every pipeline accepts a `progress_callback` for download progress plus options controlling device, dtype, and caching. The per-task recipes in [`references/TASKS.md`](references/TASKS.md) show common call options (e.g. `top_k`, `max_new_tokens`) in use; shared loading options, generation parameters, streaming, and KV-cache reuse are documented in [`references/PIPELINE_OPTIONS.md`](references/PIPELINE_OPTIONS.md). For the exhaustive per-task option types, see the [API reference](https://huggingface.co/docs/transformers.js/api/pipelines). ## Things to never do - **Don't reuse a disposed pipeline.** Create a new one with `pipeline(...)` after `dispose()`. - **Don't recreate pipelines inside hot loops.** Create once, call many times. - **Don't block startup on model downloads.** Show progress via `progress_callback`. - **Don't fabricate model IDs.** Confirm a model exists on the Hub and has ONNX files (look for an `onnx/` directory in the repo) before suggesting it to a user. ## Reference documentation - Official site: <https://huggingface.co/docs/transformers.js> - API reference: <https://huggingface.co/docs/transformers.js/api/pipelines> - Examples repo: <https://github.com/huggingface/transformers.js-examples> This skill's local references: - [`TASKS.md`](references/TASKS.md) — recipes for every task, grouped by modality _(generated)_ - [`CONFIGURATION.md`](references/CONFIGURATION.md) — `env` options, caching, model inspection - [`PIPELINE_OPTIONS.md`](references/PIPELINE_OPTIONS.md) — common pipeline options, dtype, device, generation parameters.ai/skills/transformers-js/references/CONFIGURATION.md9.5 KB9baa9acb7291upstream ↗
# Configuration All global configuration lives on the `env` object exported from the package. Mutating fields on `env` changes library-wide behavior at runtime. ```javascript import { env, LogLevel } from "@huggingface/transformers"; ``` ## Quick examples <!-- @generated:start id=examples:env --> **Example:** Load models from your own server and disable remote downloads. ```javascript import { env } from '@huggingface/transformers'; env.allowRemoteModels = false; env.localModelPath = '/path/to/local/models/'; ``` **Example:** Point the filesystem cache at a custom directory (Node.js). ```javascript import { env } from '@huggingface/transformers'; env.cacheDir = '/path/to/cache/directory/'; ``` <!-- @generated:end id=examples:env --> ## All options <!-- @generated:start id=typedef:TransformersEnvironment --> | Option | Type | Description | |--------|------|-------------| | `version` | `string` | This version of Transformers.js. | | `backends` | `object` | Exposes backend environment settings that users can override. | | `logLevel` | `number` | The logging level. Use LogLevel enum values. Defaults to LogLevel.WARNING. | | `allowRemoteModels` | `boolean` | Whether to allow loading of remote files, defaults to `true`. If set to `false`, it will have the same effect as setting `local_files_only=true` when loading pipelines, models, tokenizers, processors, etc. | | `remoteHost` | `string` | Host URL to load models from. Defaults to the Hugging Face Hub. | | `remotePathTemplate` | `string` | Path template to fill in and append to `remoteHost` when loading models. | | `allowLocalModels` | `boolean` | Whether to allow loading of local files, defaults to `false` if running in-browser, and `true` otherwise. If set to `false`, it will skip the local file check and try to load the model from the remote host. | | `localModelPath` | `string` | Path to load local models from. By default, it is `/models/` relative to the library's installed location when a file system is available (e.g., Node.js), and the `/models/` URL path otherwise (e.g., browsers). | | `useFS` | `boolean` | Whether to use the file system to load files. By default, it is `true` if available. | | `useBrowserCache` | `boolean` | Whether to use Cache API to cache models. By default, it is `true` if available. | | `useFSCache` | `boolean` | Whether to use the file system to cache files. By default, it is `true` if available. | | `cacheDir` | `string\|null` | The directory to use for caching files with the file system. By default, it is `.cache` relative to the library's installed location when a file system is available (e.g., Node.js), and `null` otherwise (e.g., browsers). | | `useCustomCache` | `boolean` | Whether to use a custom cache system (defined by `customCache`), defaults to `false`. | | `customCache` | `CacheInterface\|null` | The custom cache to use. Defaults to `null`. This must be an object that implements the `match` and `put` functions of the Web Cache API. For more information, see https://developer.mozilla.org/en-US/docs/Web/API/Cache. | | `useWasmCache` | `boolean` | Whether to pre-load and cache WASM binaries and the WASM factory (.mjs) for ONNX Runtime. Defaults to `true` when cache is available. This can improve performance and enables offline usage by avoiding repeated downloads. | | `cacheKey` | `string` | The cache key to use for storing models and WASM binaries. Defaults to `transformers-cache`. | | `experimental_useCrossOriginStorage` | `boolean` | Whether to use the Cross-Origin Storage API to cache model files across origins, allowing different sites to share the same cached model weights. Defaults to `false`. Requires the Cross-Origin Storage Chrome extension: https://chromewebstore.google.com/detail/cross-origin-storage/denpnpcgjgikjpoglpjefakmdcbmlgih. The `experimental_` prefix indicates that the underlying browser API is not yet standardized and may change or be removed without a major version bump. For more information, see https://github.com/WICG/cross-origin-storage. | | `fetch` | `(input: string \| URL, init?: any) => Promise<any>` | The fetch function to use. Defaults to `fetch`. | <!-- @generated:end id=typedef:TransformersEnvironment --> ## Log levels Pass one of these values to `env.logLevel`: | Value | Numeric | |----------------|---------| | `LogLevel.DEBUG` | `10` | | `LogLevel.INFO` | `20` | | `LogLevel.WARNING` | `30` (default) | | `LogLevel.ERROR` | `40` | | `LogLevel.NONE` | `50` | Higher numbers suppress more output. Setting `env.logLevel` also propagates to ONNX Runtime, so you get matching verbosity from the inference backend. ## Common patterns **Development (fast iteration with remote models):** ```javascript env.allowRemoteModels = true; env.useFSCache = true; env.logLevel = LogLevel.INFO; ``` **Production Node.js server (air-gapped, local only):** ```javascript env.allowRemoteModels = false; env.allowLocalModels = true; env.localModelPath = "/opt/models"; ``` **Browser app with a CDN mirror:** ```javascript env.remoteHost = "https://cdn.example.com"; env.useBrowserCache = true; ``` **Browser app, no CDN, just persist downloads via the Cache API:** ```javascript env.useBrowserCache = true; // default when Cache API is available // First visit downloads from the Hub; subsequent visits hit the cache. ``` ## Private / gated models and custom fetch In Node.js, no configuration is needed for private or gated models: the library automatically sends `Authorization: Bearer $HF_TOKEN` with requests to the Hugging Face Hub, so setting that environment variable is enough. In browsers — or for retry logic and abort signals anywhere — override `env.fetch`: ```javascript // Obtain the token from your own backend at runtime; never hard-code one in // shipped client code. const token = await getHuggingFaceToken(); env.fetch = (url, init) => fetch(url, { ...init, headers: { ...init?.headers, Authorization: `Bearer ${token}` }, }); ``` ## Custom cache backends ```javascript env.useCustomCache = true; env.customCache = { async match(key) { /* return Response or undefined */ }, async put(key, response) { /* persist */ }, }; ``` The cache must implement the Web Cache API's `match` and `put` methods. ## Inspecting models before loading `ModelRegistry` reports which files a model needs, whether they're cached locally, which dtypes the model ships with, and can clear caches selectively. Useful for pre-flight UI and disk management. Note that `get_available_dtypes` returns `[]` only when the model exists but ships no ONNX files; it throws a `ModelFileNotFoundError` for missing or inaccessible (private/gated) models, and a regular error on network failures. ```javascript import { ModelRegistry, pipeline } from "@huggingface/transformers"; const task = "feature-extraction"; const modelId = "onnx-community/all-MiniLM-L6-v2-ONNX"; const cached = await ModelRegistry.is_pipeline_cached(task, modelId); if (!cached) { const files = await ModelRegistry.get_pipeline_files(task, modelId); // ask the user to confirm before `pipeline(...)` downloads these. } const dtypes = await ModelRegistry.get_available_dtypes(modelId); const dtype = ["q4", "q8", "fp16", "fp32"].find((d) => dtypes.includes(d)); const pipe = await pipeline(task, modelId, { dtype }); ``` <!-- @generated:start id=class:ModelRegistry --> Static class for cache and file management operations. **Methods** - `get_files(modelId, [options])` → `Promise<string[]>` — Get all files (model, tokenizer, processor) needed for a model. - `get_pipeline_files(task, modelId, [options])` → `Promise<string[]>` — Get all files needed for a specific pipeline task. - `get_model_files(modelId, [options])` → `Promise<string[]>` — Get model files needed for a specific model. - `get_tokenizer_files(modelId)` → `Promise<string[]>` — Get tokenizer files needed for a specific model. - `get_processor_files(modelId)` → `Promise<string[]>` — Get processor files needed for a specific model. - `get_available_dtypes(modelId, [options])` → `Promise<string[]>` — Detects which quantization levels (dtypes) are available for a model by checking which ONNX files exist on the hub or locally. - `is_cached(modelId, [options])` → `Promise<boolean>` — Quickly checks if a model is fully cached by verifying `config.json` is present, then confirming all required files are cached. - `is_cached_files(modelId, [options])` → `Promise<CacheCheckResult>` — Checks if all files for a given model are already cached, with per-file detail. - `is_pipeline_cached(task, modelId, [options])` → `Promise<boolean>` — Quickly checks if all files for a specific pipeline task are cached by verifying `config.json` is present, then confirming all required files are cached. - `is_pipeline_cached_files(task, modelId, [options])` → `Promise<CacheCheckResult>` — Checks if all files for a specific pipeline task are already cached, with per-file detail. - `get_file_metadata(path_or_repo_id, filename, [options])` → `Promise<{exists: boolean, size?: number, contentType?: string, fromCache?: boolean}>` — Get metadata for a specific file without downloading it. - `clear_cache(modelId, [options])` → `Promise<CacheClearResult>` — Clears all cached files for a given model. - `clear_pipeline_cache(task, modelId, [options])` → `Promise<CacheClearResult>` — Clears all cached files for a specific pipeline task. <!-- @generated:end id=class:ModelRegistry --> To reclaim disk space for a specific model or task: ```javascript await ModelRegistry.clear_cache(modelId); await ModelRegistry.clear_pipeline_cache(task, modelId); ```.ai/skills/transformers-js/references/PIPELINE_OPTIONS.md20 KB11e7a937d54cupstream ↗
# Pipeline options The `pipeline(task, model?, options?)` factory accepts a common set of options across every task. Task-specific call options are documented on each pipeline class in the [API reference](https://huggingface.co/docs/transformers.js/api/pipelines). ## Common options <!-- @generated:start id=typedef:PretrainedModelOptions --> | Option | Type | Description | |--------|------|-------------| | `progress_callback`? | `ProgressCallback` | If specified, this function is called during model construction with progress updates. _(default: `null`)_ | | `config`? | `PretrainedConfig` | Configuration to use for the model instead of an automatically loaded configuration. Configuration can be automatically loaded when:<br />- The model is provided by the library and loaded with the *model ID* string of a pretrained model.<br />- The model is loaded by supplying a local directory as `pretrained_model_name_or_path` and a configuration JSON file named *config.json* is found in the directory. _(default: `null`)_ | | `cache_dir`? | `string` | Path to a directory where downloaded model files should be cached if the standard cache should not be used. _(default: `null`)_ | | `local_files_only`? | `boolean` | Whether to only look at local files (e.g., not try downloading the model). _(default: `false`)_ | | `revision`? | `string` | The model revision to use. This can be a branch name, tag name, or commit ID. Because the Hub uses Git-based storage, `revision` can be any identifier accepted by Git. Ignored for local requests. _(default: `'main'`)_ | | `subfolder`? | `string` | In case the relevant files are located inside a subfolder of the model repo on huggingface.co, you can specify the folder name here. _(default: `'onnx'`)_ | | `model_file_name`? | `string` | Override the base ONNX model file name, excluding dtype and `.onnx` suffixes. This is most useful for single-session models. _(default: `null`)_ | | `device`? | `DeviceType\|Record<string, DeviceType>` | The device to run the model on. If not specified, the device will be chosen from the environment settings. _(default: `null`)_ | | `dtype`? | `DataType\|Record<string, DataType>` | The data type to use for the model. If not specified, the data type will be chosen from the environment settings. _(default: `null`)_ | | `use_external_data_format`? | `ExternalData\|Record<string, ExternalData>` | Whether to load external data files. `null` uses the model configuration; `false` disables external data; `true` uses one chunk; a number selects the chunk count. _(default: `null`)_ | | `session_options`? | `InferenceSession.SessionOptions` | User-specified ONNX Runtime session options. Suitable defaults are filled in when omitted. _(default: `{}`)_ | <!-- @generated:end id=typedef:PretrainedModelOptions --> ## Progress tracking The `progress_total` event reports aggregate progress across every file the model needs, which is what a loading bar usually wants: ```javascript const pipe = await pipeline("sentiment-analysis", null, { progress_callback: (info) => { if (info.status === "progress_total") { console.log(`Loading model: ${info.progress.toFixed(1)}%`); } }, }); ``` For per-file detail, listen for `progress` events instead: ```javascript const pipe = await pipeline("sentiment-analysis", null, { progress_callback: (info) => { if (info.status === "progress") { console.log(`${info.file}: ${info.progress.toFixed(1)}%`); } }, }); ``` ### `ProgressInfo` shape <!-- @generated:start id=typedef:ProgressInfo --> **`InitiateProgressInfo`** | Option | Type | Description | |--------|------|-------------| | `status` | `'initiate'` | A file load is about to start. | | `name` | `string` | The model ID or directory path. | | `file` | `string` | The name of the file. | **`DownloadProgressInfo`** | Option | Type | Description | |--------|------|-------------| | `status` | `'download'` | A file download has started. | | `name` | `string` | The model ID or directory path. | | `file` | `string` | The name of the file. | **`ProgressStatusInfo`** | Option | Type | Description | |--------|------|-------------| | `status` | `'progress'` | A file download has reported byte progress. | | `name` | `string` | The model ID or directory path. | | `file` | `string` | The name of the file. | | `progress` | `number` | A number between 0 and 100. | | `loaded` | `number` | The number of bytes loaded. | | `total` | `number` | The total number of bytes to be loaded. | **`DoneProgressInfo`** | Option | Type | Description | |--------|------|-------------| | `status` | `'done'` | A file has finished loading. | | `name` | `string` | The model ID or directory path. | | `file` | `string` | The name of the file. | **`ReadyProgressInfo`** | Option | Type | Description | |--------|------|-------------| | `status` | `'ready'` | The requested pipeline is ready to use. | | `task` | `string` | The loaded task. | | `model` | `string` | The loaded model. | **`TotalProgressInfo`** | Option | Type | Description | |--------|------|-------------| | `status` | `'progress_total'` | Aggregate progress across all files being loaded. | | `name` | `string` | The model ID or directory path. | | `progress` | `number` | A number between 0 and 100. | | `loaded` | `number` | The number of bytes loaded. | | `total` | `number` | The total number of bytes to be loaded. | | `files` | `FilesLoadingMap` | A mapping of file names to their loading progress. | <!-- @generated:end id=typedef:ProgressInfo --> ## Device selection ```javascript // Default — CPU (onnxruntime-node in Node.js, WASM in browsers) await pipeline("sentiment-analysis", null); // GPU via WebGPU (Chrome 113+, fastest for big models) await pipeline("text-generation", "onnx-community/Qwen3-0.6B-ONNX", { device: "webgpu", dtype: "fp16", }); // Node.js with onnxruntime-node await pipeline("sentiment-analysis", null, { device: "cpu" }); ``` Detect WebGPU support before attempting to use it: ```javascript const hasWebGPU = typeof navigator !== "undefined" && "gpu" in navigator; const pipe = await pipeline("text-generation", "onnx-community/Qwen3-0.6B-ONNX", { device: hasWebGPU ? "webgpu" : "wasm", dtype: hasWebGPU ? "fp16" : "q8", }); ``` ## Task-specific call options Once created, each pipeline is itself callable with task-specific options: ```javascript const classifier = await pipeline("text-classification"); await classifier("great movie", { top_k: 3 }); const generator = await pipeline("text-generation"); await generator("Once upon a time", { max_new_tokens: 100, do_sample: true, temperature: 0.7 }); const translator = await pipeline("translation", "Xenova/nllb-200-distilled-600M"); await translator("Hello", { src_lang: "eng_Latn", tgt_lang: "fra_Latn" }); ``` The per-task recipes in [`TASKS.md`](./TASKS.md) show the most common call options in use. For the exhaustive option types of a specific pipeline, see the [API reference](https://huggingface.co/docs/transformers.js/api/pipelines). ## Generation parameters Every field below can be passed as an option to a `text-generation`, `text2text-generation`, `translation`, or `summarization` pipeline call, or anywhere `generate()` is invoked directly. **Pairs of fields with overlapping meanings:** - `max_new_tokens` overrides `max_length`. Pass one, not both — `max_new_tokens` is usually what you want because it doesn't depend on the prompt length. - `min_new_tokens` overrides `min_length` for the same reason. - Sampling vs. greedy: `temperature` and `top_k` only take effect with `do_sample: true`. Under greedy decoding (the default) they are silently ignored. - Beam search is not yet implemented: `num_beams > 1` is accepted but generation still keeps a single sequence, so leave it at the default. <!-- @generated:start id=fields:GenerationConfig --> | Option | Type | Description | |--------|------|-------------| | `max_length`? | `number` | The maximum length the generated tokens can have. Corresponds to the length of the input prompt + `max_new_tokens`. Its effect is overridden by `max_new_tokens`, if also set. _(default: `20`)_ | | `max_new_tokens`? | `number` | The maximum number of tokens to generate, ignoring the number of tokens in the prompt. _(default: `null`)_ | | `min_length`? | `number` | The minimum length of the sequence to be generated. Corresponds to the length of the input prompt + `min_new_tokens`. Its effect is overridden by `min_new_tokens`, if also set. _(default: `0`)_ | | `min_new_tokens`? | `number` | The minimum number of tokens to generate, ignoring the number of tokens in the prompt. _(default: `null`)_ | | `early_stopping`? | `boolean\|"never"` | Controls the stopping condition for beam-based methods, like beam-search. It accepts the following values:<br />- `true`, where the generation stops as soon as there are `num_beams` complete candidates;<br />- `false`, where a heuristic is applied and the generation stops when it is very unlikely to find better candidates;<br />- `"never"`, where the beam search procedure only stops when there cannot be better candidates (canonical beam search algorithm). _(default: `false`)_ | | `max_time`? | `number` | The maximum time, in seconds, allowed for generation. Generation will still finish the current pass after the allocated time has passed. _(default: `null`)_ | | `do_sample`? | `boolean` | Whether to use sampling; use greedy decoding otherwise. _(default: `false`)_ | | `num_beams`? | `number` | Number of beams for beam search. 1 means no beam search. _(default: `1`)_ | | `num_beam_groups`? | `number` | Number of groups to divide `num_beams` into to encourage diversity among different groups of beams. See [this paper](https://huggingface.co/papers/1610.02424) for more details. _(default: `1`)_ | | `penalty_alpha`? | `number` | Balance model confidence against the degeneration penalty during contrastive search decoding. _(default: `null`)_ | | `use_cache`? | `boolean` | Whether the model should reuse past key/value states, when supported, to speed up decoding. _(default: `true`)_ | | `temperature`? | `number` | The value used to modulate the next token probabilities. _(default: `1.0`)_ | | `top_k`? | `number` | The number of highest-probability vocabulary tokens to keep for top-k filtering. _(default: `50`)_ | | `top_p`? | `number` | If set to a float below 1, only the smallest set of most probable tokens with probabilities that add up to `top_p` or higher are kept for generation. _(default: `1.0`)_ | | `typical_p`? | `number` | Local typicality measures how similar the conditional probability of predicting a target token next is to the expected conditional probability of predicting a random token next, given the partial text already generated. If set to a float below 1, the smallest set of the most locally typical tokens with probabilities that add up to `typical_p` or higher are kept for generation. See [this paper](https://huggingface.co/papers/2202.00666) for more details. _(default: `1.0`)_ | | `epsilon_cutoff`? | `number` | If set to a float strictly between 0 and 1, only tokens with a conditional probability greater than `epsilon_cutoff` will be sampled. In the paper, suggested values range from 3e-4 to 9e-4, depending on the size of the model. See [Truncation Sampling as Language Model Desmoothing](https://huggingface.co/papers/2210.15191) for more details. _(default: `0.0`)_ | | `eta_cutoff`? | `number` | Eta sampling is a hybrid of locally typical sampling and epsilon sampling. If set to a float strictly between 0 and 1, a token is only considered if it is greater than either `eta_cutoff` or `sqrt(eta_cutoff) * exp(-entropy(softmax(next_token_logits)))`. The latter term is intuitively the expected next token probability, scaled by `sqrt(eta_cutoff)`. In the paper, suggested values range from 3e-4 to 2e-3, depending on the size of the model. See [Truncation Sampling as Language Model Desmoothing](https://huggingface.co/papers/2210.15191) for more details. _(default: `0.0`)_ | | `diversity_penalty`? | `number` | This value is subtracted from a beam's score if it generates the same token as any beam from another group at a particular time. Note that `diversity_penalty` is only effective if `group beam search` is enabled. _(default: `0.0`)_ | | `repetition_penalty`? | `number` | Penalty applied to repeated tokens. 1.0 means no penalty. See [this paper](https://huggingface.co/papers/1909.05858) for more details. _(default: `1.0`)_ | | `encoder_repetition_penalty`? | `number` | Penalty applied to sequences that are not in the original input. 1.0 means no penalty. _(default: `1.0`)_ | | `length_penalty`? | `number` | Exponential penalty applied to sequence length during beam-based generation. It is applied as an exponent to the sequence length, which in turn is used to divide the score of the sequence. Since the score is the log likelihood of the sequence (i.e. negative), `length_penalty` > 0.0 promotes longer sequences, while `length_penalty` < 0.0 encourages shorter sequences. _(default: `1.0`)_ | | `no_repeat_ngram_size`? | `number` | If set to an integer greater than 0, all n-grams of that size can only occur once. _(default: `0`)_ | | `bad_words_ids`? | `number[][]` | List of token IDs that are not allowed to be generated. In order to get the token IDs of the words that should not appear in the generated text, use `tokenizer(bad_words, { add_prefix_space: true, add_special_tokens: false }).input_ids`. _(default: `null`)_ | | `force_words_ids`? | `number[][]\|number[][][]` | List of token IDs that must be generated. If given a `number[][]`, this is treated as a simple list of words that must be included, the opposite of `bad_words_ids`. If given `number[][][]`, this triggers a [disjunctive constraint](https://github.com/huggingface/transformers/issues/14081), which allows different forms of each word. _(default: `null`)_ | | `renormalize_logits`? | `boolean` | Whether to renormalize the logits after applying all the logits processors or warpers (including the custom ones). It's highly recommended to set this flag to `true` because search algorithms assume the score logits are normalized, but some logit processors or warpers break the normalization. _(default: `false`)_ | | `constraints`? | `Object[]` | Custom constraints that guide generation to include certain tokens as defined by `Constraint` objects. _(default: `null`)_ | | `forced_bos_token_id`? | `number` | The ID of the token to force as the first generated token after the `decoder_start_token_id`. Useful for multilingual models like mBART where the first generated token needs to be the target language token. _(default: `null`)_ | | `forced_eos_token_id`? | `number\|number[]` | The ID of the token to force as the last generated token when `max_length` is reached. Optionally, use a list to set multiple *end-of-sequence* tokens. _(default: `null`)_ | | `remove_invalid_values`? | `boolean` | Whether to remove possible *nan* and *inf* outputs of the model to prevent the generation method from crashing. Note that using `remove_invalid_values` can slow down generation. _(default: `false`)_ | | `exponential_decay_length_penalty`? | `[number, number]` | This tuple adds an exponentially increasing length penalty after a certain number of tokens have been generated. The tuple consists of: `(start_index, decay_factor)` where `start_index` indicates where the penalty starts and `decay_factor` represents the factor of exponential decay. _(default: `null`)_ | | `suppress_tokens`? | `number[]` | A list of tokens to suppress during generation. The `SuppressTokens` logit processor sets their log probabilities to `-inf` so that they are not sampled. _(default: `null`)_ | | `streamer`? | `TextStreamer` | Streamer used to yield generated text incrementally. _(default: `null`)_ | | `begin_suppress_tokens`? | `number[]` | A list of tokens to suppress at the beginning of the generation. The `SuppressBeginTokens` logit processor sets their log probabilities to `-inf` so that they are not sampled. _(default: `null`)_ | | `forced_decoder_ids`? | `[number, number][]` | A list of integer pairs that maps generation indices to token indices that will be forced before sampling. For example, `[[1, 123]]` means the second generated token will always be a token of index 123. _(default: `null`)_ | | `guidance_scale`? | `number` | The guidance scale for classifier-free guidance (CFG). CFG is enabled by setting `guidance_scale > 1`. Higher guidance scale encourages the model to generate samples that are more closely tied to the input prompt, usually at the expense of poorer quality. _(default: `null`)_ | | `num_return_sequences`? | `number` | The number of independently computed returned sequences for each element in the batch. _(default: `1`)_ | | `output_attentions`? | `boolean` | Whether to return attention tensors from all attention layers. See `attentions` under returned tensors for more details. _(default: `false`)_ | | `output_hidden_states`? | `boolean` | Whether to return the hidden states of all layers. See `hidden_states` under returned tensors for more details. _(default: `false`)_ | | `output_scores`? | `boolean` | Whether to return the prediction scores. See `scores` under returned tensors for more details. _(default: `false`)_ | | `return_dict_in_generate`? | `boolean` | Whether to return a `ModelOutput` instead of a plain tuple. _(default: `false`)_ | | `pad_token_id`? | `number` | The ID of the *padding* token. _(default: `null`)_ | | `bos_token_id`? | `number` | The ID of the *beginning-of-sequence* token. _(default: `null`)_ | | `eos_token_id`? | `number\|number[]` | The ID of the *end-of-sequence* token. Optionally, use a list to set multiple *end-of-sequence* tokens. _(default: `null`)_ | | `encoder_no_repeat_ngram_size`? | `number` | If set to an integer greater than 0, all n-grams of that size that occur in the `encoder_input_ids` cannot occur in the `decoder_input_ids`. _(default: `0`)_ | | `decoder_start_token_id`? | `number` | If an encoder-decoder model starts decoding with a token other than *bos*, the ID of that token. _(default: `null`)_ | | `generation_kwargs`? | `Object` | Additional generation kwargs forwarded to the model's `generate` function. Kwargs that are not present in `generate`'s signature are used in the model forward pass. _(default: `{}`)_ | <!-- @generated:end id=fields:GenerationConfig --> ### Streaming tokens as they're produced ```javascript import { pipeline, TextStreamer } from "@huggingface/transformers"; const generator = await pipeline("text-generation", "onnx-community/Qwen3-0.6B-ONNX"); const streamer = new TextStreamer(generator.tokenizer, { skip_prompt: true, skip_special_tokens: true, callback_function: (text) => process.stdout.write(text), }); await generator("Tell me a short story.", { max_new_tokens: 200, streamer }); ``` For whisper-style chunk / token / finalize callbacks, use `WhisperTextStreamer`. ### KV cache reuse across calls For multi-turn chat, pass the same `DynamicCache` to every call **and re-send the full conversation each turn**. The pipeline uses the cache to skip re-encoding the tokens it has already processed (the shared prefix). Do not pass only the new message: the model needs the full sequence to compute token positions, so incremental-only input produces wrong results. ```javascript import { pipeline, DynamicCache } from "@huggingface/transformers"; const generator = await pipeline("text-generation", "onnx-community/Qwen3-0.6B-ONNX"); const past_key_values = new DynamicCache(); const messages = [{ role: "user", content: "What is the capital of France?" }]; // Turn 1 const turn1 = await generator(messages, { max_new_tokens: 128, past_key_values }); messages.push(turn1[0].generated_text.at(-1)); // append the assistant reply // Turn 2: send the full conversation again — only the new tokens are encoded messages.push({ role: "user", content: "What about Germany?" }); const turn2 = await generator(messages, { max_new_tokens: 128, past_key_values }); console.log(turn2[0].generated_text.at(-1).content); await past_key_values.dispose(); // free the cache tensors when the conversation ends ```.ai/skills/transformers-js/references/TASKS.md38 KB5ce17a39ebb7upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/huggingface-transformers-js-ai-skills-transformers-js.md