Improvements on Exposed ORT support

src/backends/onnx.js

@@ -54,12 +54,22 @@ const supportedDevices = [];
 /** @type {ONNXExecutionProviders[]} */
 let defaultDevices;
 let ONNX;
-const ORT_SYMBOL = Symbol.for('onnxruntime');
 
-if (ORT_SYMBOL in globalThis) {
-  // If the JS runtime exposes their own ONNX runtime, use it
-  ONNX = globalThis[ORT_SYMBOL];
+// If the JS runtime exposes their own ONNX runtime, use it
+if (apis.IS_EXPOSED_RUNTIME_ENV) {
+    const onnxruntime = globalThis[apis.EXPOSED_RUNTIME_SYMBOL];
 
+    // ensure that the runtime implements the necessary functions
+    // consider use array map if need to check more required members.
+    ['Tensor', 'InferenceSession', 'InferenceSession.create'].forEach(propPath => {
+        const hasProp = propPath.split('.').reduce((acc, key) => acc?.[key], onnxruntime) !== undefined;
+
+        if (!hasProp) {
+            throw new Error(`Invalid "globalThis[${String(apis.EXPOSED_RUNTIME_SYMBOL)}]" definition. Missing required exported member "${propPath}".`)
+        }
+    });
+
+    ONNX = onnxruntime;
 } else if (apis.IS_NODE_ENV) {
     ONNX = ONNX_NODE.default ?? ONNX_NODE;
 

src/env.js

@@ -40,6 +40,14 @@ const IS_NODE_ENV = IS_PROCESS_AVAILABLE && process?.release?.name === 'node';
 const IS_FS_AVAILABLE = !isEmpty(fs);
 const IS_PATH_AVAILABLE = !isEmpty(path);
 
+const IS_DENO_ENV = typeof Deno !== 'undefined';
+
+const EXPOSED_RUNTIME_SYMBOL = Symbol.for('onnxruntime');
+const IS_EXPOSED_RUNTIME_ENV = EXPOSED_RUNTIME_SYMBOL in globalThis && (
+  IS_PROCESS_AVAILABLE && process?.env?.HF_TRANSFORMERS_USE_EXPOSED_RUNTIME
+  || IS_DENO_ENV && Deno?.env?.get('HF_TRANSFORMERS_USE_EXPOSED_RUNTIME')
+);
+
 /**
  * A read-only object containing information about the APIs available in the current environment.
  */
@@ -59,6 +67,12 @@ export const apis = Object.freeze({
     /** Whether the WebNN API is available */
     IS_WEBNN_AVAILABLE,
 
+    /** Symbol from JS environment that exposes their own ONNX runtime */
+    EXPOSED_RUNTIME_SYMBOL,
+
+    /** Whether we are running in a JS environment that exposes their own ONNX runtime */
+    IS_EXPOSED_RUNTIME_ENV,
+
     /** Whether the Node.js process API is available */
     IS_PROCESS_AVAILABLE,
 

src/models.js

@@ -165,9 +165,12 @@ async function getSession(pretrained_model_name_or_path, fileName, options) {
     }
 
     // If the device is not specified, we use the default (supported) execution providers.
-    const selectedDevice = /** @type {import("./utils/devices.js").DeviceType} */(
-        device ?? (apis.IS_NODE_ENV ? 'cpu' : 'wasm')
+    let selectedDevice = /** @type {import("./utils/devices.js").DeviceType} */ (
+      // Do not asign default device if 'IS_EXPOSED_RUNTIME_ENV'
+      device ?? (apis.IS_EXPOSED_RUNTIME_ENV ? undefined
+        : (apis.IS_NODE_ENV ? 'cpu' : 'wasm'))
     );
+
     const executionProviders = deviceToExecutionProviders(selectedDevice);
 
     // If options.dtype is specified, we use it to choose the suffix for the model file.
@@ -235,7 +238,7 @@ async function getSession(pretrained_model_name_or_path, fileName, options) {
     const free_dimension_overrides = custom_config.free_dimension_overrides;
     if (free_dimension_overrides) {
         session_options.freeDimensionOverrides ??= free_dimension_overrides;
-    } else if (selectedDevice.startsWith('webnn') && !session_options.freeDimensionOverrides) {
+    } else if (selectedDevice?.startsWith('webnn') && !session_options.freeDimensionOverrides) {
         console.warn(
             'WebNN does not currently support dynamic shapes and requires `free_dimension_overrides` to be set in config.json as a field within "transformers.js_config". ' +
             'When `free_dimension_overrides` is not set, you may experience significant performance degradation.'