@huggingface/transformers 4.0.0-next.0 → 4.0.0-next.10

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@huggingface/transformers",
-  "version": "4.0.0-next.0",
+  "version": "4.0.0-next.10",
   "description": "State-of-the-art Machine Learning for the web. Run 🤗 Transformers directly in your browser, with no need for a server!",
-  "main": "./src/transformers.js",
+  "main": "./dist/transformers.node.cjs",
   "types": "./types/transformers.d.ts",
   "type": "module",
   "exports": {
@@ -43,10 +43,10 @@
   },
   "homepage": "https://github.com/huggingface/transformers.js#readme",
   "dependencies": {
-    "@huggingface/jinja": "^0.5.5",
-    "@huggingface/tokenizers": "^0.1.1",
-    "onnxruntime-node": "1.24.1",
-    "onnxruntime-web": "1.24.1",
+    "@huggingface/jinja": "^0.5.6",
+    "@huggingface/tokenizers": "^0.1.3",
+    "onnxruntime-node": "1.24.3",
+    "onnxruntime-web": "1.25.0-dev.20260323-a99aad9d36",
     "sharp": "^0.34.5"
   },
   "devDependencies": {

package/src/backends/onnx.js

@@ -16,13 +16,15 @@
  * @module backends/onnx
  */
 
-import { env, apis } from '../env.js';
+import { env, apis, LogLevel } from '../env.js';
 
 // NOTE: Import order matters here. We need to import `onnxruntime-node` before `onnxruntime-web`.
 // In either case, we select the default export if it exists, otherwise we use the named export.
 import * as ONNX_NODE from 'onnxruntime-node';
 import * as ONNX_WEB from 'onnxruntime-web/webgpu';
-import { isBlobURL, loadWasmBinary, loadWasmFactory, toAbsoluteURL } from './utils/cacheWasm.js';
+import { loadWasmBinary, loadWasmFactory } from './utils/cacheWasm.js';
+import { isBlobURL, toAbsoluteURL } from '../utils/hub/utils.js';
+import { logger } from '../utils/logger.js';
 export { Tensor } from 'onnxruntime-common';
 
 /**
@@ -46,9 +48,48 @@ const DEVICE_TO_EXECUTION_PROVIDER_MAPPING = Object.freeze({
     'webnn-cpu': { name: 'webnn', deviceType: 'cpu' }, // WebNN CPU
 });
 
-/** @type {Array<'verbose' | 'info' | 'warning' | 'error' | 'fatal'>} */
-const LOG_LEVELS = ['verbose', 'info', 'warning', 'error', 'fatal'];
-const DEFAULT_LOG_LEVEL = 4; // 'fatal';
+/**
+ * Converts any LogLevel value to ONNX Runtime's numeric severity level (0-4).
+ * This handles both standard LogLevel values (10, 20, 30, 40, 50) and custom intermediate values.
+ *
+ * @param {number} logLevel - The LogLevel value to convert
+ * @returns {number} ONNX Runtime severity level (0-4)
+ */
+function getOnnxLogSeverityLevel(logLevel) {
+    // ONNX Runtime's log severity levels are defined as follows:
+    // (0) ORT_LOGGING_LEVEL_VERBOSE: Print all log messages.
+    // (1) ORT_LOGGING_LEVEL_INFO: Print info and higher level log messages.
+    // (2) ORT_LOGGING_LEVEL_WARNING: Print warning and higher level log messages.
+    // (3) ORT_LOGGING_LEVEL_ERROR: Print error log messages.
+    // (4) ORT_LOGGING_LEVEL_FATAL: Print only fatal log messages.
+    //
+    // In practice, ONNX Runtime's logging is extremely verbose (especially on session creation).
+    // For this reason, we map multiple LogLevel values to the same ONNX severity level to avoid
+    // overwhelming users with logs.
+    if (logLevel <= LogLevel.DEBUG) {
+        return 0; // ORT_LOGGING_LEVEL_VERBOSE
+    } else if (logLevel <= LogLevel.INFO) {
+        return 2; // ORT_LOGGING_LEVEL_WARNING
+    } else if (logLevel <= LogLevel.WARNING) {
+        return 3; // ORT_LOGGING_LEVEL_ERROR
+    } else if (logLevel <= LogLevel.ERROR) {
+        return 3; // ORT_LOGGING_LEVEL_ERROR
+    } else {
+        return 4; // ORT_LOGGING_LEVEL_FATAL
+    }
+}
+
+/**
+ * Maps ONNX Runtime numeric severity levels to string log levels.
+ * @type {Record<0 | 1 | 2 | 3 | 4, 'verbose' | 'info' | 'warning' | 'error' | 'fatal'>}
+ */
+const ONNX_LOG_LEVEL_NAMES = {
+    0: 'verbose',
+    1: 'info',
+    2: 'warning',
+    3: 'error',
+    4: 'fatal',
+};
 
 /**
  * The list of supported devices, sorted by priority/performance.
@@ -136,8 +177,6 @@ export function deviceToExecutionProviders(device = null) {
     throw new Error(`Unsupported device: "${device}". Should be one of: ${supportedDevices.join(', ')}.`);
 }
 
-const IS_WEB_ENV = apis.IS_BROWSER_ENV || apis.IS_WEBWORKER_ENV;
-
 /**
  * Currently, Transformers.js doesn't support simultaneous loading of sessions in WASM/WebGPU.
  * For this reason, we need to chain the loading calls.
@@ -164,14 +203,23 @@ async function ensureWasmLoaded() {
         return wasmLoadPromise;
     }
 
+    // Check if we should load the WASM binary
     const shouldUseWasmCache =
         env.useWasmCache &&
         typeof ONNX_ENV?.wasm?.wasmPaths === 'object' &&
         ONNX_ENV?.wasm?.wasmPaths?.wasm &&
         ONNX_ENV?.wasm?.wasmPaths?.mjs;
 
-    // Check if we should load the WASM binary
     if (!shouldUseWasmCache) {
+        // In Deno's web runtime, the WASM factory must be loaded via blob URL so that Node.js detection
+        // can be patched out (see loadWasmFactory). Without caching, the factory is imported directly
+        // from its URL and Deno would crash trying to use Node.js APIs. useWasmCache defaults to true
+        // in this environment, so this only happens if the user explicitly disables it.
+        if (apis.IS_DENO_WEB_RUNTIME) {
+            throw new Error(
+                "env.useWasmCache=false is not supported in Deno's web runtime. Remove the useWasmCache override.",
+            );
+        }
         wasmLoadPromise = Promise.resolve();
         return wasmLoadPromise;
     }
@@ -182,7 +230,10 @@ async function ensureWasmLoaded() {
         // shouldUseWasmCache checks for wasmPaths.wasm and wasmPaths.mjs
         const urls = /** @type {{ wasm: string, mjs: string }} */ (ONNX_ENV.wasm.wasmPaths);
 
-        // Load and cache both the WASM binary and factory
+        // Load both in parallel; the .mjs blob URL is only kept if wasmBinary succeeded.
+        // ORT only sets locateFile when wasmBinary is provided (onnxruntime PR https://github.com/microsoft/onnxruntime/pull/27411), which
+        // prevents new URL(fileName, import.meta.url) from failing inside a blob URL factory.
+        let wasmBinaryLoaded = false;
         await Promise.all([
             // Load and cache the WASM binary
             urls.wasm && !isBlobURL(urls.wasm)
@@ -191,14 +242,15 @@ async function ensureWasmLoaded() {
                           const wasmBinary = await loadWasmBinary(toAbsoluteURL(urls.wasm));
                           if (wasmBinary) {
                               ONNX_ENV.wasm.wasmBinary = wasmBinary;
+                              wasmBinaryLoaded = true;
                           }
                       } catch (err) {
-                          console.warn('Failed to pre-load WASM binary:', err);
+                          logger.warn('Failed to pre-load WASM binary:', err);
                       }
                   })()
                 : Promise.resolve(),
 
-            // Load and cache the WASM factory
+            // Load and cache the WASM factory as a blob URL
             urls.mjs && !isBlobURL(urls.mjs)
                 ? (async () => {
                       try {
@@ -208,11 +260,17 @@ async function ensureWasmLoaded() {
                               ONNX_ENV.wasm.wasmPaths.mjs = wasmFactoryBlob;
                           }
                       } catch (err) {
-                          console.warn('Failed to pre-load WASM factory:', err);
+                          logger.warn('Failed to pre-load WASM factory:', err);
                       }
                   })()
                 : Promise.resolve(),
         ]);
+
+        // If wasmBinary failed to load, revert wasmPaths.mjs to the original URL (factory can only be loaded from blob if ONNX_ENV.wasm.wasmBinary is set. @see ORT PR #27411)
+        if (!wasmBinaryLoaded) {
+            // @ts-ignore
+            ONNX_ENV.wasm.wasmPaths.mjs = urls.mjs;
+        }
     })();
 
     return wasmLoadPromise;
@@ -227,13 +285,14 @@ async function ensureWasmLoaded() {
  */
 export async function createInferenceSession(buffer_or_path, session_options, session_config) {
     await ensureWasmLoaded();
+    const logSeverityLevel = getOnnxLogSeverityLevel(env.logLevel ?? LogLevel.WARNING);
     const load = () =>
         InferenceSession.create(buffer_or_path, {
-            // Set default log level, but allow overriding through session options
-            logSeverityLevel: DEFAULT_LOG_LEVEL,
+            // Set default log severity level, but allow overriding through session options
+            logSeverityLevel,
             ...session_options,
         });
-    const session = await (IS_WEB_ENV ? (webInitChain = webInitChain.then(load)) : load());
+    const session = await (apis.IS_WEB_ENV ? (webInitChain = webInitChain.then(load)) : load());
     session.config = session_config;
     return session;
 }
@@ -253,8 +312,7 @@ let webInferenceChain = Promise.resolve();
  */
 export async function runInferenceSession(session, ortFeed) {
     const run = () => session.run(ortFeed);
-    const output = await (IS_WEB_ENV ? (webInferenceChain = webInferenceChain.then(run)) : run());
-    return output;
+    return apis.IS_WEB_ENV ? (webInferenceChain = webInferenceChain.then(run)) : run();
 }
 
 /**
@@ -265,42 +323,8 @@ export async function runInferenceSession(session, ortFeed) {
 export function isONNXTensor(x) {
     return x instanceof ONNX.Tensor;
 }
-
 /** @type {import('onnxruntime-common').Env} */
 const ONNX_ENV = ONNX?.env;
-ONNX_ENV.logLevel = LOG_LEVELS[DEFAULT_LOG_LEVEL];
-if (ONNX_ENV?.wasm) {
-    // Initialize wasm backend with suitable default settings.
-
-    // (Optional) Set path to wasm files. This will override the default path search behavior of onnxruntime-web.
-    // By default, we only do this if we are not in a service worker and the wasmPaths are not already set.
-    if (
-        // @ts-ignore Cannot find name 'ServiceWorkerGlobalScope'.ts(2304)
-        !(typeof ServiceWorkerGlobalScope !== 'undefined' && self instanceof ServiceWorkerGlobalScope) &&
-        ONNX_ENV.versions?.web &&
-        !ONNX_ENV.wasm.wasmPaths
-    ) {
-        const wasmPathPrefix = `https://cdn.jsdelivr.net/npm/onnxruntime-web@${ONNX_ENV.versions.web}/dist/`;
-
-        ONNX_ENV.wasm.wasmPaths = apis.IS_SAFARI
-            ? {
-                  mjs: `${wasmPathPrefix}ort-wasm-simd-threaded.mjs`,
-                  wasm: `${wasmPathPrefix}ort-wasm-simd-threaded.wasm`,
-              }
-            : {
-                  mjs: `${wasmPathPrefix}ort-wasm-simd-threaded.asyncify.mjs`,
-                  wasm: `${wasmPathPrefix}ort-wasm-simd-threaded.asyncify.wasm`,
-              };
-    }
-
-    // Users may wish to proxy the WASM backend to prevent the UI from freezing,
-    // However, this is not necessary when using WebGPU, so we default to false.
-    ONNX_ENV.wasm.proxy = false;
-}
-
-if (ONNX_ENV?.webgpu) {
-    ONNX_ENV.webgpu.powerPreference = 'high-performance';
-}
 
 /**
  * Check if ONNX's WASM backend is being proxied.
@@ -311,5 +335,56 @@ export function isONNXProxy() {
     return ONNX_ENV?.wasm?.proxy;
 }
 
-// Expose ONNX environment variables to `env.backends.onnx`
-env.backends.onnx = ONNX_ENV;
+if (ONNX_ENV) {
+    if (ONNX_ENV.wasm) {
+        // Initialize wasm backend with suitable default settings.
+
+        // (Optional) Set path to wasm files. This will override the default path search behavior of onnxruntime-web.
+        // By default, we only do this if we are not in a service worker and the wasmPaths are not already set.
+        if (
+            // @ts-ignore Cannot find name 'ServiceWorkerGlobalScope'.ts(2304)
+            !(typeof ServiceWorkerGlobalScope !== 'undefined' && self instanceof ServiceWorkerGlobalScope) &&
+            ONNX_ENV.versions?.web &&
+            !ONNX_ENV.wasm.wasmPaths
+        ) {
+            const wasmPathPrefix = `https://cdn.jsdelivr.net/npm/onnxruntime-web@${ONNX_ENV.versions.web}/dist/`;
+
+            ONNX_ENV.wasm.wasmPaths = apis.IS_SAFARI
+                ? {
+                      mjs: `${wasmPathPrefix}ort-wasm-simd-threaded.mjs`,
+                      wasm: `${wasmPathPrefix}ort-wasm-simd-threaded.wasm`,
+                  }
+                : {
+                      mjs: `${wasmPathPrefix}ort-wasm-simd-threaded.asyncify.mjs`,
+                      wasm: `${wasmPathPrefix}ort-wasm-simd-threaded.asyncify.wasm`,
+                  };
+        }
+
+        // Users may wish to proxy the WASM backend to prevent the UI from freezing,
+        // However, this is not necessary when using WebGPU, so we default to false.
+        ONNX_ENV.wasm.proxy = false;
+    }
+
+    if (ONNX_ENV.webgpu) {
+        ONNX_ENV.webgpu.powerPreference = 'high-performance';
+    }
+
+    /**
+     * A function to map Transformers.js log levels to ONNX Runtime log severity
+     * levels, and set the log level environment variable in ONNX Runtime.
+     * @param {number} logLevel The log level to set.
+     */
+    function setLogLevel(logLevel) {
+        const severityLevel = getOnnxLogSeverityLevel(logLevel);
+        ONNX_ENV.logLevel = ONNX_LOG_LEVEL_NAMES[severityLevel];
+    }
+
+    // Set the initial log level to be the default Transformers.js log level.
+    setLogLevel(env.logLevel ?? LogLevel.WARNING);
+
+    // Expose ONNX environment variables to `env.backends.onnx`
+    env.backends.onnx = {
+        ...ONNX_ENV,
+        setLogLevel,
+    };
+}

package/src/backends/utils/cacheWasm.js

@@ -1,10 +1,11 @@
+import { apis, env } from '../../env.js';
 import { getCache } from '../../utils/cache.js';
-import { isValidUrl } from '../../utils/hub/utils.js';
+import { logger } from '../../utils/logger.js';
 
 /**
  * Loads and caches a file from the given URL.
  * @param {string} url The URL of the file to load.
- * @returns {Promise<Response|import('../../utils/hub/files.js').FileResponse|null|string>} The response object, or null if loading failed.
+ * @returns {Promise<Response|import('../../utils/hub/FileResponse.js').FileResponse|null|string>} The response object, or null if loading failed.
  */
 async function loadAndCacheFile(url) {
     const fileName = url.split('/').pop();
@@ -22,11 +23,11 @@ async function loadAndCacheFile(url) {
             }
         }
     } catch (error) {
-        console.warn(`Failed to load ${fileName} from cache:`, error);
+        logger.warn(`Failed to load ${fileName} from cache:`, error);
     }
 
     // If not in cache, fetch it
-    const response = await fetch(url);
+    const response = await env.fetch(url);
 
     if (!response.ok) {
         throw new Error(`Failed to fetch ${fileName}: ${response.status} ${response.statusText}`);
@@ -37,7 +38,7 @@ async function loadAndCacheFile(url) {
         try {
             await cache.put(url, response.clone());
         } catch (e) {
-            console.warn(`Failed to cache ${fileName}:`, e);
+            logger.warn(`Failed to cache ${fileName}:`, e);
         }
     }
 
@@ -57,63 +58,44 @@ export async function loadWasmBinary(wasmURL) {
     try {
         return await response.arrayBuffer();
     } catch (error) {
-        console.warn('Failed to read WASM binary:', error);
+        logger.warn('Failed to read WASM binary:', error);
         return null;
     }
 }
 
 /**
- * Loads and caches the WASM Factory for ONNX Runtime.
+ * Loads and caches the WASM Factory (.mjs file) for ONNX Runtime.
+ * Creates a blob URL from cached content (when safe) to bridge Cache API with dynamic imports used in ORT.
  * @param {string} libURL The URL of the WASM Factory to load.
- * @returns {Promise<string|null>} The blob URL of the WASM Factory, or null if loading failed.
+ * @returns {Promise<string|null>} The blob URL (if enabled), original URL (if disabled), or null if loading failed.
  */
 export async function loadWasmFactory(libURL) {
+    // We can't use Blob URLs in some environments (Service Workers, Chrome extensions) due to security restrictions on dynamic import() of blob URLs.
+    // In such cases, just return the original URL and don't bother caching since dynamic import() won't use the Cache API anyway.
+    // See https://github.com/huggingface/transformers.js/issues/1532.
+    if (apis.IS_SERVICE_WORKER_ENV || apis.IS_CHROME_AVAILABLE) {
+        return libURL;
+    }
+
+    // Fetch from cache or network, then create blob URL
     const response = await loadAndCacheFile(libURL);
     if (!response || typeof response === 'string') return null;
 
     try {
         let code = await response.text();
-        // Fix relative paths when loading factory from blob, overwrite import.meta.url with actual baseURL
-        const baseUrl = libURL.split('/').slice(0, -1).join('/');
-        code = code.replace(/import\.meta\.url/g, `"${baseUrl}"`);
+
+        // Handle the case where we are importing the bundled version of the library in Deno (e.g., via CDN or local file),
+        // where we need to patch out Node.js detection in the factory. Without this, Deno (which exposes globalThis.process.versions.node)
+        // would enter the Node.js branch and try to use Node.js APIs (worker_threads, fs, etc.) that aren't used in the bundled web version.
+        // Only needed for the asyncify (single-threaded) variant loaded via blob URL. The module-level pthread auto-start code is unreachable since asyncify never spawns workers.
+        // See https://github.com/huggingface/transformers.js/pull/1546/ for more information.
+        //
+        // NOTE: This does not affect default usage via Deno (i.e., imported via npm: prefix), since we'll be using onnxruntime-node (Native) instead of onnxruntime-web (WASM).
+        code = code.replaceAll('globalThis.process?.versions?.node', 'false');
         const blob = new Blob([code], { type: 'text/javascript' });
         return URL.createObjectURL(blob);
     } catch (error) {
-        console.warn('Failed to read WASM binary:', error);
+        logger.warn('Failed to read WASM factory:', error);
         return null;
     }
 }
-
-/**
- * Checks if the given URL is a blob URL (created via URL.createObjectURL).
- * Blob URLs should not be cached as they are temporary in-memory references.
- * @param {string} url - The URL to check.
- * @returns {boolean} True if the URL is a blob URL, false otherwise.
- */
-export function isBlobURL(url) {
-    return isValidUrl(url, ['blob:']);
-}
-
-/**
- * Converts any URL to an absolute URL if needed.
- * If the URL is already absolute (http://, https://, or blob:), returns it unchanged (handled by new URL(...)).
- * Otherwise, resolves it relative to the current page location (browser) or module location (Node/Bun/Deno).
- * @param {string} url - The URL to convert (can be relative or absolute).
- * @returns {string} The absolute URL.
- */
-export function toAbsoluteURL(url) {
-    let baseURL;
-
-    if (typeof location !== 'undefined' && location.href) {
-        // Browser environment: use location.href
-        baseURL = location.href;
-    } else if (typeof import.meta !== 'undefined' && import.meta.url) {
-        // Node.js/Bun/Deno module environment: use import.meta.url
-        baseURL = import.meta.url;
-    } else {
-        // Fallback: if no base is available, return the URL unchanged
-        return url;
-    }
-
-    return new URL(url, baseURL).href;
-}

package/src/cache_utils.js

@@ -0,0 +1,62 @@
+import { Tensor } from './utils/tensor.js';
+
+/**
+ * A cache class that stores past key values as named tensors.
+ */
+class _DynamicCache {
+    /**
+     * Create a DynamicCache, optionally pre-populated with entries.
+     * @param {Record<string, Tensor>} [entries] Initial name→Tensor mappings.
+     */
+    constructor(entries) {
+        if (!entries) return;
+        for (const key in entries) {
+            if (key in this) {
+                throw new TypeError(`Key "${key}" conflicts with an existing property on DynamicCache`);
+            }
+            const value = entries[key];
+            if (!(value instanceof Tensor)) {
+                throw new TypeError(`Expected a Tensor for key "${key}", got ${typeof value}`);
+            }
+            this[key] = value;
+        }
+    }
+
+    /**
+     * Get the cached sequence length. This requires at least one attention cache entry to be present.
+     * @returns {number} The past sequence length.
+     */
+    get_seq_length() {
+        /** @type {Record<string, Tensor>} */
+        const self = /** @type {any} */ (this);
+        for (const name in self) {
+            if (name.startsWith('past_key_values.')) {
+                return self[name].dims.at(-2);
+            }
+        }
+        throw new Error('Unable to determine sequence length from the cache.');
+    }
+
+    /**
+     * Dispose all contained tensors whose data resides on the GPU.
+     * Returns a promise that resolves when all disposals are complete.
+     * @returns {Promise<void>} Promise that resolves when all GPU tensors are disposed.
+     */
+    async dispose() {
+        const promises = [];
+        for (const t of /** @type {Tensor[]} */ (Object.values(this))) {
+            if (t.location === 'gpu-buffer') {
+                promises.push(t.dispose());
+            }
+        }
+        await Promise.all(promises);
+    }
+}
+
+/**
+ * @typedef {_DynamicCache & Record<string, Tensor>} DynamicCache
+ */
+
+export const DynamicCache = /** @type {new (entries?: Record<string, Tensor>) => DynamicCache} */ (
+    /** @type {unknown} */ (_DynamicCache)
+);