@huggingface/transformers 3.0.0-alpha.0

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@huggingface/transformers",
+  "version": "3.0.0-alpha.0",
+  "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",
+  "types": "./types/transformers.d.ts",
+  "type": "module",
+  "exports": {
+    "node": {
+      "import": "./dist/transformers.js",
+      "require": "./dist/transformers.cjs"
+    },
+    "default": "./src/transformers.js"
+  },
+  "scripts": {
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typegen": "tsc ./src/transformers.js --allowJs --declaration --emitDeclarationOnly --declarationMap --outDir types",
+    "dev": "webpack serve --no-client-overlay",
+    "build": "webpack && npm run typegen",
+    "generate-tests": "python -m tests.generate_tests",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --verbose --maxConcurrency 1",
+    "readme": "python ./docs/scripts/build_readme.py",
+    "docs-api": "node ./docs/scripts/generate.js",
+    "docs-preview": "doc-builder preview transformers.js ./docs/source/ --not_python_module",
+    "docs-build": "doc-builder build transformers.js ./docs/source/ --not_python_module --build_dir ./docs/build/ --repo_owner xenova"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xenova/transformers.js.git"
+  },
+  "keywords": [
+    "transformers",
+    "transformers.js",
+    "huggingface",
+    "hugging face",
+    "machine learning",
+    "deep learning",
+    "artificial intelligence",
+    "AI",
+    "ML"
+  ],
+  "author": "Hugging Face",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/xenova/transformers.js/issues"
+  },
+  "homepage": "https://github.com/xenova/transformers.js#readme",
+  "dependencies": {
+    "@huggingface/jinja": "^0.3.0",
+    "onnxruntime-node": "1.18.0",
+    "onnxruntime-web": "1.19.0-dev.20240804-ee2fe87e2d",
+    "sharp": "^0.33.2"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.1",
+    "@webgpu/types": "^0.1.44",
+    "catharsis": "github:xenova/catharsis",
+    "jest": "^29.5.0",
+    "jest-environment-node": "^29.5.0",
+    "jsdoc-to-markdown": "^8.0.1",
+    "prettier": "3.3.3",
+    "typescript": "^5.2.2",
+    "wavefile": "^11.0.0",
+    "webpack": "^5.80.0",
+    "webpack-cli": "^5.0.2",
+    "webpack-dev-server": "^4.13.3"
+  },
+  "overrides": {
+    "semver": "^7.6.3",
+    "protobufjs": "^7.2.6"
+  },
+  "files": [
+    "src",
+    "dist",
+    "types",
+    "README.md",
+    "LICENSE"
+  ],
+  "browser": {
+    "fs": false,
+    "path": false,
+    "url": false,
+    "sharp": false,
+    "onnxruntime-node": false
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "jsdelivr": "./dist/transformers.min.js",
+  "unpkg": "./dist/transformers.min.js"
+}

package/src/backends/onnx.js

@@ -0,0 +1,151 @@
+/**
+ * @file Handler file for choosing the correct version of ONNX Runtime, based on the environment.
+ * Ideally, we could import the `onnxruntime-web` and `onnxruntime-node` packages only when needed,
+ * but dynamic imports don't seem to work with the current webpack version and/or configuration.
+ * This is possibly due to the experimental nature of top-level await statements.
+ * So, we just import both packages, and use the appropriate one based on the environment:
+ *   - When running in node, we use `onnxruntime-node`.
+ *   - When running in the browser, we use `onnxruntime-web` (`onnxruntime-node` is not bundled).
+ * 
+ * This module is not directly exported, but can be accessed through the environment variables:
+ * ```javascript
+ * import { env } from '@huggingface/transformers';
+ * console.log(env.backends.onnx);
+ * ```
+ * 
+ * @module backends/onnx
+ */
+
+import { env, apis } 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';
+
+export { Tensor } from 'onnxruntime-common';
+
+/** @type {import('../utils/devices.js').DeviceType[]} */
+const supportedExecutionProviders = [];
+
+/** @type {import('../utils/devices.js').DeviceType[]} */
+let defaultExecutionProviders;
+let ONNX;
+if (apis.IS_NODE_ENV) {
+    ONNX = ONNX_NODE.default ?? ONNX_NODE;
+    supportedExecutionProviders.push('cpu');
+    defaultExecutionProviders = ['cpu'];
+} else {
+    ONNX = ONNX_WEB;
+    if (apis.IS_WEBGPU_AVAILABLE) {
+        supportedExecutionProviders.push('webgpu');
+    }
+    supportedExecutionProviders.push('wasm');
+    defaultExecutionProviders = ['wasm'];
+}
+
+// @ts-ignore
+const InferenceSession = ONNX.InferenceSession;
+
+/**
+ * Map a device to the execution providers to use for the given device.
+ * @param {import("../utils/devices.js").DeviceType} [device=null] (Optional) The device to run the inference on.
+ * @returns {import("../utils/devices.js").DeviceType[]} The execution providers to use for the given device.
+ */
+export function deviceToExecutionProviders(device) {
+    // TODO: Use mapping from device to execution providers for overloaded devices (e.g., 'gpu' or 'cpu').
+    let executionProviders = defaultExecutionProviders;
+    if (device) { // User has specified a device
+        if (!supportedExecutionProviders.includes(device)) {
+            throw new Error(`Unsupported device: "${device}". Should be one of: ${supportedExecutionProviders.join(', ')}.`)
+        }
+        executionProviders = [device];
+    }
+    return executionProviders;
+}
+
+
+/**
+ * To prevent multiple calls to `initWasm()`, we store the first call in a Promise
+ * that is resolved when the first InferenceSession is created. Subsequent calls
+ * will wait for this Promise to resolve before creating their own InferenceSession.
+ * @type {Promise<any>|null}
+ */
+let wasmInitPromise = null;
+
+/**
+ * Create an ONNX inference session.
+ * @param {Uint8Array} buffer The ONNX model buffer.
+ * @param {Object} session_options ONNX inference session options.
+ * @returns {Promise<import('onnxruntime-common').InferenceSession>} The ONNX inference session.
+ */
+export async function createInferenceSession(buffer, session_options) {
+    if (wasmInitPromise) {
+        // A previous session has already initialized the WASM runtime
+        // so we wait for it to resolve before creating this new session.
+        await wasmInitPromise;
+    }
+
+    const sessionPromise = InferenceSession.create(buffer, session_options);
+    wasmInitPromise ??= sessionPromise;
+    return await sessionPromise;
+}
+
+/**
+ * Check if an object is an ONNX tensor.
+ * @param {any} x The object to check
+ * @returns {boolean} Whether the object is an ONNX tensor.
+ */
+export function isONNXTensor(x) {
+    return x instanceof ONNX.Tensor;
+}
+
+// @ts-ignore
+const ONNX_ENV = ONNX?.env;
+if (ONNX_ENV?.wasm) {
+    // Initialize wasm backend with suitable default settings.
+
+    // (Optional) Set path to wasm files. This is needed when running in a web worker.
+    // https://onnxruntime.ai/docs/api/js/interfaces/Env.WebAssemblyFlags.html#wasmPaths
+    // We use remote wasm files by default to make it easier for newer users.
+    // In practice, users should probably self-host the necessary .wasm files.
+    // ONNX_ENV.wasm.wasmPaths = 'https://cdn.jsdelivr.net/npm/onnxruntime-web@1.19.0-dev.20240804-ee2fe87e2d/dist/';
+
+    // TODO: Add support for loading WASM files from cached buffer when we upgrade to onnxruntime-web@1.19.0
+    // https://github.com/microsoft/onnxruntime/pull/21534
+
+    // Proxy the WASM backend to prevent the UI from freezing
+    // NOTE: This is only needed when running in a non-worker browser environment.
+    ONNX_ENV.wasm.proxy = !apis.IS_WEBWORKER_ENV;
+
+    // https://developer.mozilla.org/en-US/docs/Web/API/crossOriginIsolated
+    if (typeof crossOriginIsolated === 'undefined' || !crossOriginIsolated) {
+        ONNX_ENV.wasm.numThreads = 1;
+    }
+
+    // Running in a browser-environment
+    // TODO: Check if 1.17.1 fixes this issue.
+    // SIMD for WebAssembly does not operate correctly in some recent versions of iOS (16.4.x).
+    // As a temporary fix, we disable it for now.
+    // For more information, see: https://github.com/microsoft/onnxruntime/issues/15644
+    const isIOS = typeof navigator !== 'undefined' && /iP(hone|od|ad).+16_4.+AppleWebKit/.test(navigator.userAgent);
+    if (isIOS) {
+        ONNX_ENV.wasm.simd = false;
+    }
+}
+
+if (ONNX_ENV?.webgpu) {
+    ONNX_ENV.webgpu.powerPreference = 'high-performance';
+}
+
+/**
+ * Check if ONNX's WASM backend is being proxied.
+ * @returns {boolean} Whether ONNX's WASM backend is being proxied.
+ */
+export function isONNXProxy() {
+    // TODO: Update this when allowing non-WASM backends.
+    return ONNX_ENV?.wasm?.proxy;
+}
+
+// Expose ONNX environment variables to `env.backends.onnx`
+env.backends.onnx = ONNX_ENV;

package/src/configs.js

@@ -0,0 +1,360 @@
+
+/**
+ * @file Helper module for using model configs. For more information, see the corresponding
+ * [Python documentation](https://huggingface.co/docs/transformers/main/en/model_doc/auto#transformers.AutoConfig).
+ * 
+ * **Example:** Load an `AutoConfig`.
+ * 
+ * ```javascript
+ * import { AutoConfig } from '@huggingface/transformers';
+ * const config = await AutoConfig.from_pretrained('bert-base-uncased');
+ * console.log(config);
+ * // PretrainedConfig {
+ * //   "model_type": "bert",
+ * //   "is_encoder_decoder": false,
+ * //   "architectures": [
+ * //       "BertForMaskedLM"
+ * //   ],
+ * //   "vocab_size": 30522
+ * //   "num_attention_heads": 12,
+ * //   "num_hidden_layers": 12,
+ * //   "hidden_size": 768,
+ * //   "max_position_embeddings": 512,
+ * //   ...
+ * // }
+ * ```
+ * 
+ * @module configs
+ */
+
+import { pick } from './utils/core.js';
+import {
+    getModelJSON,
+} from './utils/hub.js';
+
+/**
+ * @typedef {import('./utils/hub.js').PretrainedOptions} PretrainedOptions
+ */
+
+
+/**
+ * Loads a config from the specified path.
+ * @param {string} pretrained_model_name_or_path The path to the config directory.
+ * @param {PretrainedOptions} options Additional options for loading the config.
+ * @returns {Promise<Object>} A promise that resolves with information about the loaded config.
+ */
+async function loadConfig(pretrained_model_name_or_path, options) {
+    return await getModelJSON(pretrained_model_name_or_path, 'config.json', true, options);
+}
+
+/**
+ * 
+ * @param {PretrainedConfig} config 
+ * @returns {Object} The normalized configuration.
+ */
+function getNormalizedConfig(config) {
+    const mapping = {};
+
+    let init_normalized_config = {};
+    switch (config.model_type) {
+        // Sub-configs
+        case 'llava':
+        case 'paligemma':
+        case 'florence2':
+            init_normalized_config = getNormalizedConfig(config.text_config);
+            break;
+        case 'moondream1':
+            init_normalized_config = getNormalizedConfig(config.phi_config);
+            break;
+        case 'musicgen':
+            init_normalized_config = getNormalizedConfig(config.decoder);
+            break;
+
+        // Decoder-only models
+        case 'gpt2':
+        case 'gptj':
+        case 'codegen':
+        case 'gpt_bigcode':
+            mapping['num_heads'] = 'n_head';
+            mapping['num_layers'] = 'n_layer';
+            mapping['hidden_size'] = 'n_embd';
+            break;
+        case 'gpt_neox':
+        case 'stablelm':
+        case 'opt':
+        case 'phi':
+        case 'phi3':
+        case 'falcon':
+            mapping['num_heads'] = 'num_attention_heads';
+            mapping['num_layers'] = 'num_hidden_layers';
+            mapping['hidden_size'] = 'hidden_size';
+            break;
+        case 'llama':
+        case 'cohere':
+        case 'mistral':
+        case 'starcoder2':
+        case 'qwen2':
+            mapping['num_heads'] = 'num_key_value_heads';
+            mapping['num_layers'] = 'num_hidden_layers';
+            mapping['hidden_size'] = 'hidden_size';
+            mapping['num_attention_heads'] = 'num_attention_heads';
+            break;
+        case 'gemma':
+        case 'gemma2':
+            mapping['num_heads'] = 'num_key_value_heads';
+            mapping['num_layers'] = 'num_hidden_layers';
+            mapping['dim_kv'] = 'head_dim';
+            break;
+        case 'openelm':
+            mapping['num_heads'] = 'num_kv_heads';
+            mapping['num_layers'] = 'num_transformer_layers';
+            mapping['dim_kv'] = 'head_dim';
+            break;
+        case 'gpt_neo':
+        case 'donut-swin':
+            mapping['num_heads'] = 'num_heads';
+            mapping['num_layers'] = 'num_layers';
+            mapping['hidden_size'] = 'hidden_size';
+            break;
+        case 'bloom':
+            mapping['num_heads'] = 'n_head';
+            mapping['num_layers'] = 'n_layer';
+            mapping['hidden_size'] = 'hidden_size';
+            break;
+        case 'mpt':
+            mapping['num_heads'] = 'n_heads';
+            mapping['num_layers'] = 'n_layers';
+            mapping['hidden_size'] = 'd_model';
+            break;
+
+        // Encoder-decoder models
+        case 't5':
+        case 'mt5':
+        case 'longt5':
+            mapping['num_decoder_layers'] = 'num_decoder_layers';
+            mapping['num_decoder_heads'] = 'num_heads';
+            mapping['decoder_dim_kv'] = 'd_kv';
+            mapping['num_encoder_layers'] = 'num_layers';
+            mapping['num_encoder_heads'] = 'num_heads';
+            mapping['encoder_dim_kv'] = 'd_kv';
+            break;
+        case 'bart':
+        case 'mbart':
+        case 'marian':
+        case 'whisper':
+        case 'm2m_100':
+        case 'blenderbot':
+        case 'blenderbot-small':
+        case 'florence2_language':
+            mapping['num_decoder_layers'] = 'decoder_layers';
+            mapping['num_decoder_heads'] = 'decoder_attention_heads';
+            mapping['decoder_hidden_size'] = 'd_model';
+            mapping['num_encoder_layers'] = 'encoder_layers';
+            mapping['num_encoder_heads'] = 'encoder_attention_heads';
+            mapping['encoder_hidden_size'] = 'd_model';
+            break;
+        case 'speecht5':
+            mapping['num_decoder_layers'] = 'decoder_layers';
+            mapping['num_decoder_heads'] = 'decoder_attention_heads';
+            mapping['decoder_hidden_size'] = 'hidden_size';
+            mapping['num_encoder_layers'] = 'encoder_layers';
+            mapping['num_encoder_heads'] = 'encoder_attention_heads';
+            mapping['encoder_hidden_size'] = 'hidden_size';
+            break;
+        case 'trocr':
+            mapping['num_encoder_layers'] = mapping['num_decoder_layers'] = 'decoder_layers';
+            mapping['num_encoder_heads'] = mapping['num_decoder_heads'] = 'decoder_attention_heads';
+            mapping['encoder_hidden_size'] = mapping['decoder_hidden_size'] = 'd_model';
+            break;
+        case 'musicgen_decoder':
+            mapping['num_encoder_layers'] = mapping['num_decoder_layers'] = 'num_hidden_layers';
+            mapping['num_encoder_heads'] = mapping['num_decoder_heads'] = 'num_attention_heads';
+            mapping['encoder_hidden_size'] = mapping['decoder_hidden_size'] = 'hidden_size';
+            break;
+
+        case 'vision-encoder-decoder':
+            const decoderConfig = getNormalizedConfig(config.decoder);
+
+            const add_encoder_pkv = 'num_decoder_layers' in decoderConfig;
+            const result = pick(config, ['model_type', 'is_encoder_decoder']);
+            if (add_encoder_pkv) {
+                // Decoder is part of an encoder-decoder model
+                result.num_decoder_layers = decoderConfig.num_decoder_layers;
+                result.num_decoder_heads = decoderConfig.num_decoder_heads;
+                result.decoder_hidden_size = decoderConfig.decoder_hidden_size;
+
+                result.num_encoder_layers = decoderConfig.num_encoder_layers;
+                result.num_encoder_heads = decoderConfig.num_encoder_heads;
+                result.encoder_hidden_size = decoderConfig.encoder_hidden_size;
+            } else {
+                // Decoder is a decoder-only model
+                result.num_layers = decoderConfig.num_layers;
+                result.num_heads = decoderConfig.num_heads;
+                result.hidden_size = decoderConfig.hidden_size;
+            }
+            return result;
+
+    }
+
+    // NOTE: If `num_attention_heads` is not set, it is assumed to be equal to `num_heads`
+    const normalized_config = {
+        ...init_normalized_config,
+        ...pick(config, ['model_type', 'multi_query', 'is_encoder_decoder']),
+    };
+    for (const key in mapping) {
+        normalized_config[key] = config[mapping[key]];
+    }
+    return normalized_config;
+}
+
+/**
+ * 
+ * @param {PretrainedConfig} config 
+ * @returns {Record<string, number[]>}
+ */
+export function getKeyValueShapes(config, {
+    prefix = 'past_key_values',
+} = {}) {
+    /** @type {Record<string, number[]>} */
+    const decoderFeeds = {};
+    const normalized_config = config.normalized_config;
+
+    // TODO support batches (i.e., batch_size > 1)
+    const batch_size = 1;
+
+    if (normalized_config.is_encoder_decoder && (
+        'num_encoder_heads' in normalized_config && 'num_decoder_heads' in normalized_config
+    )) {
+        const encoder_dim_kv = normalized_config.encoder_dim_kv ?? (
+            normalized_config.encoder_hidden_size / normalized_config.num_encoder_heads
+        );
+        const decoder_dim_kv = normalized_config.decoder_dim_kv ?? (
+            normalized_config.decoder_hidden_size / normalized_config.num_decoder_heads
+        );
+
+        const encoder_dims = [batch_size, normalized_config.num_encoder_heads, 0, encoder_dim_kv];
+        const decoder_dims = [batch_size, normalized_config.num_decoder_heads, 0, decoder_dim_kv];
+        for (let i = 0; i < normalized_config.num_decoder_layers; ++i) {
+            decoderFeeds[`${prefix}.${i}.encoder.key`] = encoder_dims;
+            decoderFeeds[`${prefix}.${i}.encoder.value`] = encoder_dims;
+            decoderFeeds[`${prefix}.${i}.decoder.key`] = decoder_dims;
+            decoderFeeds[`${prefix}.${i}.decoder.value`] = decoder_dims;
+        }
+    } else { // Decoders
+        const num_heads = normalized_config.num_heads;
+        const num_layers = normalized_config.num_layers;
+        const dim_kv = normalized_config.dim_kv ?? (
+            normalized_config.hidden_size /
+            (normalized_config.num_attention_heads ?? num_heads)
+        );
+
+        if (normalized_config.model_type === 'falcon') {
+            // NOTE: Custom implementation for Falcon
+            const dims = [batch_size * num_heads, 0, dim_kv]
+            for (let i = 0; i < num_layers; ++i) {
+                decoderFeeds[`${prefix}.${i}.key`] = dims;
+                decoderFeeds[`${prefix}.${i}.value`] = dims;
+            }
+        } else if (normalized_config.multi_query) { // e.g., for `gpt_bigcode`
+            const dims = [batch_size * num_heads, 0, 2 * dim_kv]
+
+            for (let i = 0; i < num_layers; ++i) {
+                decoderFeeds[`${prefix}.${i}.key_value`] = dims;
+            }
+        } else if (normalized_config.model_type === 'bloom') {
+            // NOTE: Custom implementation for Bloom
+
+            const keyDims = [batch_size * num_heads, dim_kv, 0] // [batch_size x num_heads,64,past_sequence_length]
+            const valueDims = [batch_size * num_heads, 0, dim_kv] // [batch_size x num_heads,past_sequence_length,64]
+            for (let i = 0; i < num_layers; ++i) {
+                decoderFeeds[`${prefix}.${i}.key`] = keyDims;
+                decoderFeeds[`${prefix}.${i}.value`] = valueDims;
+            }
+        } else if (normalized_config.model_type === 'openelm') {
+            for (let i = 0; i < num_layers; ++i) {
+                const dims = [batch_size, num_heads[i], 0, dim_kv]
+
+                decoderFeeds[`${prefix}.${i}.key`] = dims;
+                decoderFeeds[`${prefix}.${i}.value`] = dims;
+            }
+        } else { // Decoder-only
+            const dims = [batch_size, num_heads, 0, dim_kv]
+            for (let i = 0; i < num_layers; ++i) {
+                decoderFeeds[`${prefix}.${i}.key`] = dims;
+                decoderFeeds[`${prefix}.${i}.value`] = dims;
+            }
+        }
+    }
+
+    return decoderFeeds;
+}
+/**
+ * Base class for all configuration classes. For more information, see the corresponding
+ * [Python documentation](https://huggingface.co/docs/transformers/main/en/main_classes/configuration#transformers.PretrainedConfig).
+ */
+export class PretrainedConfig {
+    // NOTE: Typo in original
+
+    max_position_embeddings;
+
+    /**
+     * Create a new PreTrainedTokenizer instance.
+     * @param {Object} configJSON The JSON of the config.
+     */
+    constructor(configJSON) {
+        this.model_type = null;
+        this.is_encoder_decoder = false;
+
+        Object.assign(this, configJSON);
+        this.normalized_config = getNormalizedConfig(this);
+    }
+
+    /**
+     * Loads a pre-trained config from the given `pretrained_model_name_or_path`. 
+     * 
+     * @param {string} pretrained_model_name_or_path The path to the pre-trained config.
+     * @param {PretrainedOptions} options Additional options for loading the config.
+     * @throws {Error} Throws an error if the config.json is not found in the `pretrained_model_name_or_path`.
+     * 
+     * @returns {Promise<PretrainedConfig>} A new instance of the `PretrainedConfig` class.
+     */
+    static async from_pretrained(pretrained_model_name_or_path, {
+        progress_callback = null,
+        config = null,
+        cache_dir = null,
+        local_files_only = false,
+        revision = 'main',
+    } = {}) {
+        if (config && !(config instanceof PretrainedConfig)) {
+            config = new PretrainedConfig(config);
+        }
+
+        const data = config ?? await loadConfig(pretrained_model_name_or_path, {
+            progress_callback,
+            config,
+            cache_dir,
+            local_files_only,
+            revision,
+        })
+        return new this(data);
+    }
+}
+
+/**
+ * Helper class which is used to instantiate pretrained configs with the `from_pretrained` function.
+ * 
+ * @example
+ * const config = await AutoConfig.from_pretrained('Xenova/bert-base-uncased'); 
+ */
+export class AutoConfig {
+    /** @type {typeof PretrainedConfig.from_pretrained} */
+    static async from_pretrained(...args) {
+        return PretrainedConfig.from_pretrained(...args);
+    }
+}
+
+/**
+ * Transformers.js-specific configuration, possibly present in config.json under the key `transformers.js_config`.
+ * @typedef {Object} TransformersJSConfig
+ * @property {import('./transformers.js').DataType} [kv_cache_dtype]
+ */