transformers.js/pr_1665/en/api/utils/model_registry.md

utils/model_registry

Model registry for cache and file operations

Provides static methods for:

• Discovering which files a model needs
• Detecting available quantization levels (dtypes)
• Getting file metadata
• Checking cache status

Example: Get all files needed for a model

const files = await ModelRegistry.get_files(
  "onnx-community/all-MiniLM-L6-v2-ONNX",
  { dtype: "fp16" },
);
console.log(files); // [ 'config.json', 'onnx/model_fp16.onnx', 'onnx/model_fp16.onnx_data', 'tokenizer.json', 'tokenizer_config.json' ]

Example: Get all files needed for a specific pipeline task

const files = await ModelRegistry.get_pipeline_files(
  "text-generation",
  "onnx-community/Qwen3-0.6B-ONNX",
  { dtype: "q4" },
);
console.log(files); // [ 'config.json', 'onnx/model_q4.onnx', 'generation_config.json', 'tokenizer.json', 'tokenizer_config.json' ]

Example: Get specific component files

const modelFiles = await ModelRegistry.get_model_files("onnx-community/all-MiniLM-L6-v2-ONNX", { dtype: "q4" });
const tokenizerFiles = await ModelRegistry.get_tokenizer_files("onnx-community/all-MiniLM-L6-v2-ONNX");
const processorFiles = await ModelRegistry.get_processor_files("onnx-community/all-MiniLM-L6-v2-ONNX");
console.log(modelFiles); // [ 'config.json', 'onnx/model_q4.onnx', 'onnx/model_q4.onnx_data' ]
console.log(tokenizerFiles); // [ 'tokenizer.json', 'tokenizer_config.json' ]
console.log(processorFiles); // [ ]

Example: Detect available quantization levels for a model

const dtypes = await ModelRegistry.get_available_dtypes("onnx-community/all-MiniLM-L6-v2-ONNX");
console.log(dtypes); // [ 'fp32', 'fp16', 'int8', 'uint8', 'q8', 'q4' ]

// Use the result to pick the best available dtype
const preferredDtype = dtypes.includes("q4") ? "q4" : "fp32";
const files = await ModelRegistry.get_files("onnx-community/all-MiniLM-L6-v2-ONNX", { dtype: preferredDtype });

Example: Check file metadata without downloading

const metadata = await ModelRegistry.get_file_metadata(
  "onnx-community/Qwen3-0.6B-ONNX",
  "config.json"
);
console.log(metadata); // { exists: true, size: 912, contentType: 'application/json', fromCache: true }

Example: Model cache management

const modelId = "onnx-community/Qwen3-0.6B-ONNX";
const options = { dtype: "q4" };

// Quickly check if the model is cached (probably false)
let cached = await ModelRegistry.is_cached(modelId, options);
console.log(cached); // false

// Get per-file cache detail
let cacheStatus = await ModelRegistry.is_cached_files(modelId, options);
console.log(cacheStatus);
// {
//   allCached: false,
//   files: [ { file: 'config.json', cached: true }, { file: 'onnx/model_q4.onnx', cached: false }, { file: 'generation_config.json', cached: false }, { file: 'tokenizer.json', cached: false }, { file: 'tokenizer_config.json', cached: false } ]
// }

// Download the model by instantiating a pipeline
const generator = await pipeline("text-generation", modelId, options);
const output = await generator(
  [{ role: "user", content: "What is the capital of France?" }],
  { max_new_tokens: 256, do_sample: false },
);
console.log(output[0].generated_text.at(-1).content); // <think>...</think>\n\nThe capital of France is **Paris**.

// Check if the model is cached (should be true now)
cached = await ModelRegistry.is_cached(modelId, options);
console.log(cached); // true

// Clear the cache
const clearResult = await ModelRegistry.clear_cache(modelId, options);
console.log(clearResult);
// {
//   filesDeleted: 5,
//   filesCached: 5,
//   files: [ { file: 'config.json', deleted: true, wasCached: true }, { file: 'onnx/model_q4.onnx', deleted: true, wasCached: true }, { file: 'generation_config.json', deleted: true, wasCached: true }, { file: 'tokenizer.json', deleted: true, wasCached: true }, { file: 'tokenizer_config.json', deleted: true, wasCached: true } ]
// }

// Check if the model is cached (should be false again)
cached = await ModelRegistry.is_cached(modelId, options);
console.log(cached); // false

Classes

ModelRegistry

Static class for cache and file management operations.

ModelRegistry.get_files(modelId, [options])

Get all files (model, tokenizer, processor) needed for a model.

Parameters

• modelId (string) — The model id (e.g., "onnx-community/bert-base-uncased-ONNX")
• options (Object) optional — Optional parameters
  • config (PretrainedConfig) optional — defaults to null — Pre-loaded config
  • dtype (DataType | Record<string, DataType>) optional — defaults to null — Override dtype
  • device (DeviceType | Record<string, DeviceType>) optional — defaults to null — Override device
  • model_file_name (string) optional — defaults to null — Override the model file name (excluding .onnx suffix)
  • include_tokenizer (boolean) optional — defaults to true — Whether to check for tokenizer files
  • include_processor (boolean) optional — defaults to true — Whether to check for processor files

Returns: Promise<string[]> — Array of file paths

Example:

const files = await ModelRegistry.get_files('onnx-community/gpt2-ONNX');
console.log(files); // ['config.json', 'tokenizer.json', 'onnx/model_q4.onnx', ...]

ModelRegistry.get_pipeline_files(task, modelId, [options])

Get all files needed for a specific pipeline task. Automatically determines which components are needed based on the task.

Parameters

• task (string) — The pipeline task (e.g., "text-generation", "background-removal")
• modelId (string) — The model id (e.g., "onnx-community/bert-base-uncased-ONNX")
• options (Object) optional — Optional parameters
  • config (PretrainedConfig) optional — defaults to null — Pre-loaded config
  • dtype (DataType | Record<string, DataType>) optional — defaults to null — Override dtype
  • device (DeviceType | Record<string, DeviceType>) optional — defaults to null — Override device
  • model_file_name (string) optional — defaults to null — Override the model file name (excluding .onnx suffix)

Returns: Promise<string[]> — Array of file paths

Example:

const files = await ModelRegistry.get_pipeline_files('text-generation', 'onnx-community/gpt2-ONNX');
console.log(files); // ['config.json', 'tokenizer.json', 'onnx/model_q4.onnx', ...]

ModelRegistry.get_model_files(modelId, [options])

Get model files needed for a specific model.

Parameters

• modelId (string) — The model id
• options (Object) optional — Optional parameters
  • config (PretrainedConfig) optional — defaults to null — Pre-loaded config
  • dtype (DataType | Record<string, DataType>) optional — defaults to null — Override dtype
  • device (DeviceType | Record<string, DeviceType>) optional — defaults to null — Override device
  • model_file_name (string) optional — defaults to null — Override the model file name (excluding .onnx suffix)

Returns: Promise<string[]> — Array of model file paths

Example:

const files = await ModelRegistry.get_model_files('onnx-community/bert-base-uncased-ONNX');
console.log(files); // ['config.json', 'onnx/model_q4.onnx', 'generation_config.json']

ModelRegistry.get_tokenizer_files(modelId)

Get tokenizer files needed for a specific model.

Parameters

• modelId (string) — The model id

Returns: Promise<string[]> — Array of tokenizer file paths

Example:

const files = await ModelRegistry.get_tokenizer_files('onnx-community/gpt2-ONNX');
console.log(files); // ['tokenizer.json', 'tokenizer_config.json']

ModelRegistry.get_processor_files(modelId)

Get processor files needed for a specific model.

Parameters

• modelId (string) — The model id

Returns: Promise<string[]> — Array of processor file paths

Example:

const files = await ModelRegistry.get_processor_files('onnx-community/vit-base-patch16-224-ONNX');
console.log(files); // ['preprocessor_config.json']

ModelRegistry.get_available_dtypes(modelId, [options])

Detects which quantization levels (dtypes) are available for a model by checking which ONNX files exist on the hub or locally.

A dtype is considered available if all required model session files exist for that dtype.

Parameters

• modelId (string) — The model id (e.g., "onnx-community/all-MiniLM-L6-v2-ONNX")
• options (Object) optional — Optional parameters
  • config (PretrainedConfig) optional — defaults to null — Pre-loaded config
  • model_file_name (string) optional — defaults to null — Override the model file name (excluding .onnx suffix)
  • revision (string) optional — defaults to 'main' — Model revision
  • cache_dir (string) optional — defaults to null — Custom cache directory
  • local_files_only (boolean) optional — defaults to false — Only check local files

Returns: Promise<string[]> — Array of available dtype strings (e.g., ['fp32', 'fp16', 'q4', 'q8'])

Example:

const dtypes = await ModelRegistry.get_available_dtypes('onnx-community/all-MiniLM-L6-v2-ONNX');
console.log(dtypes); // ['fp32', 'fp16', 'int8', 'uint8', 'q8', 'q4']

ModelRegistry.is_cached(modelId, [options])

Quickly checks if a model is fully cached by verifying config.json is present, then confirming all required files are cached. Returns a plain boolean — use is_cached_files if you need per-file detail.

Parameters

• modelId (string) — The model id
• options (Object) optional — Optional parameters
  • cache_dir (string) optional — Custom cache directory
  • revision (string) optional — Model revision (default: 'main')
  • config (PretrainedConfig) optional — Pre-loaded config
  • dtype (DataType | Record<string, DataType>) optional — defaults to null — Override dtype
  • device (DeviceType | Record<string, DeviceType>) optional — defaults to null — Override device

Returns: Promise<boolean> — Whether all required files are cached

Example:

const cached = await ModelRegistry.is_cached('onnx-community/bert-base-uncased-ONNX');
console.log(cached); // true or false

ModelRegistry.is_cached_files(modelId, [options])

Checks if all files for a given model are already cached, with per-file detail. Automatically determines which files are needed using get_files().

Parameters

• modelId (string) — The model id
• options (Object) optional — Optional parameters
  • cache_dir (string) optional — Custom cache directory
  • revision (string) optional — Model revision (default: 'main')
  • config (PretrainedConfig) optional — Pre-loaded config
  • dtype (DataType | Record<string, DataType>) optional — defaults to null — Override dtype
  • device (DeviceType | Record<string, DeviceType>) optional — defaults to null — Override device

Returns: Promise<CacheCheckResult> — Object with allCached boolean and files array with cache status

Example:

const status = await ModelRegistry.is_cached_files('onnx-community/bert-base-uncased-ONNX');
console.log(status.allCached); // true or false
console.log(status.files); // [{ file: 'config.json', cached: true }, ...]

ModelRegistry.is_pipeline_cached(task, modelId, [options])

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. Returns a plain boolean — use is_pipeline_cached_files if you need per-file detail.

Parameters

• task (string) — The pipeline task (e.g., "text-generation", "background-removal")
• modelId (string) — The model id
• options (Object) optional — Optional parameters
  • cache_dir (string) optional — Custom cache directory
  • revision (string) optional — Model revision (default: 'main')
  • config (PretrainedConfig) optional — Pre-loaded config
  • dtype (DataType | Record<string, DataType>) optional — defaults to null — Override dtype
  • device (DeviceType | Record<string, DeviceType>) optional — defaults to null — Override device

Returns: Promise<boolean> — Whether all required files are cached

Example:

const cached = await ModelRegistry.is_pipeline_cached('text-generation', 'onnx-community/gpt2-ONNX');
console.log(cached); // true or false

ModelRegistry.is_pipeline_cached_files(task, modelId, [options])

Checks if all files for a specific pipeline task are already cached, with per-file detail. Automatically determines which components are needed based on the task.

Parameters

• task (string) — The pipeline task (e.g., "text-generation", "background-removal")
• modelId (string) — The model id
• options (Object) optional — Optional parameters
  • cache_dir (string) optional — Custom cache directory
  • revision (string) optional — Model revision (default: 'main')
  • config (PretrainedConfig) optional — Pre-loaded config
  • dtype (DataType | Record<string, DataType>) optional — defaults to null — Override dtype
  • device (DeviceType | Record<string, DeviceType>) optional — defaults to null — Override device

Returns: Promise<CacheCheckResult> — Object with allCached boolean and files array with cache status

Example:

const status = await ModelRegistry.is_pipeline_cached_files('text-generation', 'onnx-community/gpt2-ONNX');
console.log(status.allCached); // true or false
console.log(status.files); // [{ file: 'config.json', cached: true }, ...]

ModelRegistry.get_file_metadata(path_or_repo_id, filename, [options])

Get metadata for a specific file without downloading it.

Parameters

• path_or_repo_id (string) — Model id or path
• filename (string) — The file name
• options (PretrainedOptions) optional — Optional parameters

Returns: Promise<object> — File metadata

Example:

const metadata = await ModelRegistry.get_file_metadata('onnx-community/gpt2-ONNX', 'config.json');
console.log(metadata.exists, metadata.size); // true, 665

ModelRegistry.clear_cache(modelId, [options])

Clears all cached files for a given model. Automatically determines which files are needed and removes them from the cache.

Parameters

• modelId (string) — The model id (e.g., "onnx-community/gpt2-ONNX")
• options (Object) optional — Optional parameters
  • cache_dir (string) optional — Custom cache directory
  • revision (string) optional — Model revision (default: 'main')
  • config (PretrainedConfig) optional — Pre-loaded config
  • dtype (DataType | Record<string, DataType>) optional — Override dtype
  • device (DeviceType | Record<string, DeviceType>) optional — Override device
  • include_tokenizer (boolean) optional — defaults to true — Whether to clear tokenizer files
  • include_processor (boolean) optional — defaults to true — Whether to clear processor files

Returns: Promise<CacheClearResult> — Object with deletion statistics and file status

Example:

const result = await ModelRegistry.clear_cache('onnx-community/bert-base-uncased-ONNX');
console.log(`Deleted ${result.filesDeleted} of ${result.filesCached} cached files`);

ModelRegistry.clear_pipeline_cache(task, modelId, [options])

Clears all cached files for a specific pipeline task. Automatically determines which components are needed based on the task.

Parameters

• task (string) — The pipeline task (e.g., "text-generation", "image-classification")
• modelId (string) — The model id (e.g., "onnx-community/gpt2-ONNX")
• options (Object) optional — Optional parameters
  • cache_dir (string) optional — Custom cache directory
  • revision (string) optional — Model revision (default: 'main')
  • config (PretrainedConfig) optional — Pre-loaded config
  • dtype (DataType | Record<string, DataType>) optional — Override dtype
  • device (DeviceType | Record<string, DeviceType>) optional — Override device

Returns: Promise<CacheClearResult> — Object with deletion statistics and file status

Example:

const result = await ModelRegistry.clear_pipeline_cache('text-generation', 'onnx-community/gpt2-ONNX');
console.log(`Deleted ${result.filesDeleted} of ${result.filesCached} cached files`);