@huggingface/transformers 3.0.0-alpha.0

package/src/utils/constants.js

@@ -0,0 +1,2 @@
+
+export const GITHUB_ISSUE_URL = 'https://github.com/xenova/transformers.js/issues/new/choose';

package/src/utils/core.js

@@ -0,0 +1,149 @@
+
+/**
+ * @file Core utility functions/classes for Transformers.js.
+ * 
+ * These are only used internally, meaning an end-user shouldn't
+ * need to access anything here.
+ * 
+ * @module utils/core
+ */
+
+/**
+ * Helper function to dispatch progress callbacks.
+ *
+ * @param {Function} progress_callback The progress callback function to dispatch.
+ * @param {any} data The data to pass to the progress callback function.
+ * @returns {void}
+ * @private
+ */
+export function dispatchCallback(progress_callback, data) {
+    if (progress_callback) progress_callback(data);
+}
+
+/**
+ * Reverses the keys and values of an object.
+ *
+ * @param {Object} data The object to reverse.
+ * @returns {Object} The reversed object.
+ * @see https://ultimatecourses.com/blog/reverse-object-keys-and-values-in-javascript
+ */
+export function reverseDictionary(data) {
+    // https://ultimatecourses.com/blog/reverse-object-keys-and-values-in-javascript
+    return Object.fromEntries(Object.entries(data).map(([key, value]) => [value, key]));
+}
+
+/**
+ * Escapes regular expression special characters from a string by replacing them with their escaped counterparts.
+ *
+ * @param {string} string The string to escape.
+ * @returns {string} The escaped string.
+ */
+export function escapeRegExp(string) {
+    return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string
+}
+
+/**
+ * Check if a value is a typed array.
+ * @param {*} val The value to check.
+ * @returns {boolean} True if the value is a `TypedArray`, false otherwise.
+ * 
+ * Adapted from https://stackoverflow.com/a/71091338/13989043
+ */
+export function isTypedArray(val) {
+    return val?.prototype?.__proto__?.constructor?.name === 'TypedArray';
+}
+
+
+/**
+ * Check if a value is an integer.
+ * @param {*} x The value to check.
+ * @returns {boolean} True if the value is a string, false otherwise.
+ */
+export function isIntegralNumber(x) {
+    return Number.isInteger(x) || typeof x === 'bigint'
+}
+
+/**
+ * Calculates the dimensions of a nested array.
+ *
+ * @param {any[]} arr The nested array to calculate dimensions for.
+ * @returns {number[]} An array containing the dimensions of the input array.
+ */
+export function calculateDimensions(arr) {
+    const dimensions = [];
+    let current = arr;
+    while (Array.isArray(current)) {
+        dimensions.push(current.length);
+        current = current[0];
+    }
+    return dimensions;
+}
+
+/**
+ * Replicate python's .pop() method for objects.
+ * @param {Object} obj The object to pop from.
+ * @param {string} key The key to pop.
+ * @param {*} defaultValue The default value to return if the key does not exist.
+ * @returns {*} The value of the popped key.
+ * @throws {Error} If the key does not exist and no default value is provided.
+ */
+export function pop(obj, key, defaultValue = undefined) {
+    const value = obj[key];
+    if (value !== undefined) {
+        delete obj[key];
+        return value;
+    }
+    if (defaultValue === undefined) {
+        throw Error(`Key ${key} does not exist in object.`)
+    }
+    return defaultValue;
+}
+
+/**
+ * Efficiently merge arrays, creating a new copy.
+ * Adapted from https://stackoverflow.com/a/6768642/13989043
+ * @param  {Array[]} arrs Arrays to merge.
+ * @returns {Array} The merged array.
+ */
+export function mergeArrays(...arrs) {
+    return Array.prototype.concat.apply([], arrs);
+}
+
+/**
+ * Compute the Cartesian product of given arrays
+ * @param {...Array} a Arrays to compute the product
+ * @returns {Array} Returns the computed Cartesian product as an array
+ * @private
+ */
+export function product(...a) {
+    // Cartesian product of items
+    // Adapted from https://stackoverflow.com/a/43053803
+    return a.reduce((a, b) => a.flatMap(d => b.map(e => [d, e])));
+}
+
+/**
+ * Calculates the index offset for a given index and window size.
+ * @param {number} i The index.
+ * @param {number} w The window size.
+ * @returns {number} The index offset.
+ */
+export function calculateReflectOffset(i, w) {
+    return Math.abs((i + w) % (2 * w) - w);
+}
+
+/**
+ * 
+ * @param {Object} o 
+ * @param {string[]} props 
+ * @returns {Object}
+ */
+export function pick(o, props) {
+    return Object.assign(
+        {},
+        ...props.map((prop) => {
+            if (o[prop] !== undefined) {
+                return { [prop]: o[prop] };
+            }
+        })
+    );
+}

package/src/utils/data-structures.js

@@ -0,0 +1,445 @@
+
+/**
+ * @file Custom data structures.
+ * 
+ * These are only used internally, meaning an end-user shouldn't
+ * need to access anything here.
+ * 
+ * @module utils/data-structures
+ */
+
+
+/**
+ * Efficient Heap-based Implementation of a Priority Queue.
+ * It uses an array-based binary heap, where the root is at index `0`, and the
+ * children of node `i` are located at indices `2i + 1` and `2i + 2`, respectively.
+ * 
+ * Adapted from the following sources:
+ * - https://stackoverflow.com/a/42919752/13989043 (original)
+ * - https://github.com/belladoreai/llama-tokenizer-js (minor improvements)
+ */
+export class PriorityQueue {
+
+    /**
+     * Create a new PriorityQueue.
+     * @param {function(any, any): boolean} comparator Comparator function to determine priority. Defaults to a MaxHeap.
+     */
+    constructor(comparator = (a, b) => a > b, maxSize = Infinity) {
+        this._heap = [];
+        this._comparator = comparator;
+        this._maxSize = maxSize;
+    }
+
+    /**
+     * The size of the queue
+     */
+    get size() {
+        return this._heap.length;
+    }
+
+    /**
+     * Check if the queue is empty.
+     * @returns {boolean} `true` if the queue is empty, `false` otherwise.
+     */
+    isEmpty() {
+        return this.size === 0;
+    }
+
+    /**
+     * Return the element with the highest priority in the queue.
+     * @returns {any} The highest priority element in the queue.
+     */
+    peek() {
+        return this._heap[0];
+    }
+
+    /**
+     * Add one or more elements to the queue.
+     * @param  {...any} values The values to push into the queue.
+     * @returns {number} The new size of the queue.
+     */
+    push(...values) {
+        return this.extend(values);
+    }
+
+    /**
+     * Add multiple elements to the queue.
+     * @param {any[]} values The values to push into the queue.
+     * @returns {number} The new size of the queue.
+     */
+    extend(values) {
+        for (const value of values) {
+            if (this.size < this._maxSize) {
+                this._heap.push(value);
+                this._siftUp();
+            } else {
+                // Get index of value with the lowest priority
+                const smallest = this._smallest();
+
+                // If the new value has higher priority than the smallest value in the heap
+                // then replace the smallest value with the new value and update the heap
+                if (this._comparator(value, this._heap[smallest])) {
+                    this._heap[smallest] = value;
+                    this._siftUpFrom(smallest);
+                }
+            }
+        }
+        return this.size;
+    }
+
+    /**
+     * Remove and return the element with the highest priority in the queue.
+     * @returns {any} The element with the highest priority in the queue.
+     */
+    pop() {
+        const poppedValue = this.peek();
+        const bottom = this.size - 1;
+        if (bottom > 0) {
+            this._swap(0, bottom);
+        }
+        this._heap.pop();
+        this._siftDown();
+        return poppedValue;
+    }
+
+    /**
+     * Replace the element with the highest priority in the queue with a new value.
+     * @param {*} value The new value.
+     * @returns {*} The replaced value.
+     */
+    replace(value) {
+        const replacedValue = this.peek();
+        this._heap[0] = value;
+        this._siftDown();
+        return replacedValue;
+    }
+
+    /**
+     * Compute the index for the parent of the node at index `i`.
+     * @param {number} i The index of the node to get the parent of.
+     * @returns {number} The index of the parent node.
+     * @private
+     */
+    _parent(i) {
+        return ((i + 1) >>> 1) - 1;
+    }
+
+    /**
+     * Compute the index for the left child of the node at index `i`.
+     * @param {number} i The index of the node to get the left child of.
+     * @returns {number} The index of the left child.
+     * @private
+     */
+    _left(i) {
+        return (i << 1) + 1;
+    }
+
+    /**
+     * Compute the index for the right child of the node at index `i`.
+     * @param {number} i The index of the node to get the right child of.
+     * @returns {number} The index of the right child.
+     * @private
+     */
+    _right(i) {
+        return (i + 1) << 1;
+    }
+
+    /**
+     * Check if the element at index `i` is greater than the element at index `j`.
+     * @param {number} i The index of the first element to compare.
+     * @param {number} j The index of the second element to compare.
+     * @returns {boolean} `true` if the element at index `i` is greater than the element at index `j`, `false` otherwise.
+     * @private
+     */
+    _greater(i, j) {
+        return this._comparator(this._heap[i], this._heap[j]);
+    }
+
+    /**
+     * Swap the elements at indices `i` and `j`.
+     * @param {number} i The index of the first element to swap.
+     * @param {number} j The index of the second element to swap.
+     * @private
+     */
+    _swap(i, j) {
+        const temp = this._heap[i];
+        this._heap[i] = this._heap[j];
+        this._heap[j] = temp;
+    }
+
+    /**
+     * Maintain the heap property by updating positions in the heap,
+     * starting at the last element and moving up the heap.
+     * @private
+     */
+    _siftUp() {
+        this._siftUpFrom(this.size - 1);
+    }
+
+    /**
+     * Helper function to sift up from a given node.
+     * @param {number} node The index of the node to start sifting up from.
+     */
+    _siftUpFrom(node) {
+        while (node > 0 && this._greater(node, this._parent(node))) {
+            this._swap(node, this._parent(node));
+            node = this._parent(node);
+        }
+    }
+
+    /**
+     * Maintain the heap property by updating positions in the heap,
+     * starting at the first element and moving down the heap.
+     * @private
+     */
+    _siftDown() {
+        let node = 0;
+        while (
+            (this._left(node) < this.size && this._greater(this._left(node), node)) ||
+            (this._right(node) < this.size && this._greater(this._right(node), node))
+        ) {
+            const maxChild = (this._right(node) < this.size && this._greater(this._right(node), this._left(node)))
+                ? this._right(node)
+                : this._left(node);
+            this._swap(node, maxChild);
+            node = maxChild;
+        }
+    }
+
+    /**
+     * Get the index of the smallest element in the heap. Since we use an array-based heap,
+     * the index can be computed without needing to traverse the heap.
+     * @private
+     */
+    _smallest() {
+        return (2 ** (Math.floor(Math.log2(this.size))) - 1);
+    }
+}
+
+/**
+ * A trie structure to efficiently store and search for strings.
+ */
+export class CharTrie {
+    constructor() {
+        this.root = CharTrieNode.default();
+    }
+
+    /**
+     * Adds one or more `texts` to the trie.
+     * @param {string[]} texts The strings to add to the trie.
+     */
+    extend(texts) {
+        for (let text of texts) {
+            this.push(text);
+        }
+    }
+
+    /**
+     * Adds text to the trie.
+     * @param {string} text The string to add to the trie.
+     */
+    push(text) {
+        let node = this.root;
+        for (let ch of text) {
+            let child = node.children.get(ch);
+            if (child === undefined) {
+                child = CharTrieNode.default();
+                node.children.set(ch, child);
+            }
+            node = child;
+        }
+        node.isLeaf = true;
+    }
+
+    /**
+     * Searches the trie for all strings with a common prefix of `text`.
+     * @param {string} text The common prefix to search for.
+     * @yields {string} Each string in the trie that has `text` as a prefix.
+     */
+    *commonPrefixSearch(text) {
+        let node = this.root;
+        let prefix = "";
+        for (let i = 0; i < text.length && node !== undefined; ++i) {
+            const ch = text[i];
+            prefix += ch;
+            node = node.children.get(ch);
+            if (node !== undefined && node.isLeaf) {
+                yield prefix;
+            }
+        }
+    }
+}
+
+/**
+ * Represents a node in a character trie.
+ */
+class CharTrieNode {
+    /**
+     * Create a new CharTrieNode.
+     * @param {boolean} isLeaf Whether the node is a leaf node or not.
+     * @param {Map<string, CharTrieNode>} children A map containing the node's children, where the key is a character and the value is a `CharTrieNode`.
+     */
+    constructor(isLeaf, children) {
+        this.isLeaf = isLeaf;
+        this.children = children;
+    }
+
+    /**
+     * Returns a new `CharTrieNode` instance with default values.
+     * @returns {CharTrieNode} A new `CharTrieNode` instance with `isLeaf` set to `false` and an empty `children` map.
+     */
+    static default() {
+        return new CharTrieNode(false, new Map());
+    }
+}
+
+/**
+ * A lattice data structure to be used for tokenization.
+ */
+export class TokenLattice {
+    /**
+     * Creates a new TokenLattice instance.
+     *
+     * @param {string} sentence The input sentence to be tokenized.
+     * @param {number} bosTokenId The beginning-of-sequence token ID.
+     * @param {number} eosTokenId The end-of-sequence token ID.
+     */
+    constructor(sentence, bosTokenId, eosTokenId) {
+        this.sentence = sentence;
+        this.len = sentence.length;
+        this.bosTokenId = bosTokenId;
+        this.eosTokenId = eosTokenId;
+        this.nodes = [];
+        this.beginNodes = Array.from({ length: this.len + 1 }, () => []);
+        this.endNodes = Array.from({ length: this.len + 1 }, () => []);
+
+        const bos = new TokenLatticeNode(this.bosTokenId, 0, 0, 0, 0.0);
+        const eos = new TokenLatticeNode(this.eosTokenId, 1, this.len, 0, 0.0);
+        this.nodes.push(bos.clone());
+        this.nodes.push(eos.clone());
+        this.beginNodes[this.len].push(eos);
+        this.endNodes[0].push(bos);
+    }
+
+    /**
+     * Inserts a new token node into the token lattice.
+     *
+     * @param {number} pos The starting position of the token.
+     * @param {number} length The length of the token.
+     * @param {number} score The score of the token.
+     * @param {number} tokenId The token ID of the token.
+     */
+    insert(pos, length, score, tokenId) {
+        const nodeId = this.nodes.length;
+        const node = new TokenLatticeNode(tokenId, nodeId, pos, length, score);
+        this.beginNodes[pos].push(node);
+        this.endNodes[pos + length].push(node);
+        this.nodes.push(node);
+    }
+
+    /**
+     * Implements the Viterbi algorithm to compute the most likely sequence of tokens.
+     *
+     * @returns {TokenLatticeNode[]} The array of nodes representing the most likely sequence of tokens.
+     */
+    viterbi() {
+        const len = this.len;
+        let pos = 0;
+        while (pos <= len) {
+            if (this.beginNodes[pos].length == 0) {
+                return [];
+            }
+            for (let rnode of this.beginNodes[pos]) {
+                rnode.prev = null;
+                let bestScore = 0.0;
+                let bestNode = null;
+                for (let lnode of this.endNodes[pos]) {
+                    const score = lnode.backtraceScore + rnode.score;
+                    if (bestNode === null || score > bestScore) {
+                        bestNode = lnode.clone();
+                        bestScore = score;
+                    }
+                }
+
+                if (bestNode !== null) {
+                    rnode.prev = bestNode;
+                    rnode.backtraceScore = bestScore;
+                } else {
+                    return [];
+                }
+            }
+            ++pos;
+        }
+
+        const results = [];
+        const root = this.beginNodes[len][0];
+        const prev = root.prev;
+        if (prev === null) {
+            return [];
+        }
+
+        let node = prev.clone();
+        while (node.prev !== null) {
+            results.push(node.clone());
+            const n = node.clone();
+            node = n.prev.clone();
+        }
+
+        results.reverse();
+        return results;
+    }
+
+    /**
+     * @param {TokenLatticeNode} node
+     * @returns {string} The array of nodes representing the most likely sequence of tokens.
+     */
+    piece(node) {
+        return this.sentence.slice(node.pos, node.pos + node.length);
+    }
+
+    /**
+     * @returns {Array} The array of nodes representing the most likely sequence of tokens.
+     */
+    tokens() {
+        const nodes = this.viterbi();
+        return nodes.map(x => this.piece(x));
+    }
+
+    /**
+     * @returns {Array} The array of nodes representing the most likely sequence of tokens.
+     */
+    tokenIds() {
+        const nodes = this.viterbi();
+        return nodes.map(x => x.tokenId);
+    }
+}
+class TokenLatticeNode {
+    /**
+     * Represents a node in a token lattice for a given sentence.
+     * @param {number} tokenId The ID of the token associated with this node.
+     * @param {number} nodeId The ID of this node.
+     * @param {number} pos The starting position of the token in the sentence.
+     * @param {number} length The length of the token.
+     * @param {number} score The score associated with the token.
+     */
+    constructor(tokenId, nodeId, pos, length, score) {
+        this.tokenId = tokenId;
+        this.nodeId = nodeId;
+        this.pos = pos;
+        this.length = length;
+        this.score = score;
+        this.prev = null;
+        this.backtraceScore = 0.0;
+    }
+
+    /**
+     * Returns a clone of this node.
+     * @returns {TokenLatticeNode} A clone of this node.
+     */
+    clone() {
+        const n = new TokenLatticeNode(this.tokenId, this.nodeId, this.pos, this.length, this.score);
+        n.prev = this.prev;
+        n.backtraceScore = this.backtraceScore;
+        return n;
+    }
+}

package/src/utils/devices.js

@@ -0,0 +1,11 @@
+
+export const DEVICE_TYPES = Object.freeze({
+    cpu: 'cpu',
+    gpu: 'gpu',
+    wasm: 'wasm',
+    webgpu: 'webgpu',
+});
+
+/**
+ * @typedef {keyof typeof DEVICE_TYPES} DeviceType
+ */

package/src/utils/dtypes.js

@@ -0,0 +1,62 @@
+import { apis } from "../env.js";
+
+import { DEVICE_TYPES } from "./devices.js";
+
+// TODO: Use the adapter from `env.backends.onnx.webgpu.adapter` to check for `shader-f16` support,
+// when available in https://github.com/microsoft/onnxruntime/pull/19940.
+// For more information, see https://github.com/microsoft/onnxruntime/pull/19857#issuecomment-1999984753
+
+/**
+ * Checks if WebGPU fp16 support is available in the current environment.
+ */
+export const isWebGpuFp16Supported = (function () {
+    /** @type {boolean} */
+    let cachedResult;
+
+    return async function () {
+        if (cachedResult === undefined) {
+            if (!apis.IS_WEBGPU_AVAILABLE) {
+                cachedResult = false;
+            } else {
+                try {
+                    const adapter = await navigator.gpu.requestAdapter();
+                    cachedResult = adapter.features.has('shader-f16');
+                } catch (e) {
+                    cachedResult = false;
+                }
+            }
+        }
+        return cachedResult;
+    };
+})();
+
+export const DATA_TYPES = Object.freeze({
+    fp32: 'fp32',
+    fp16: 'fp16',
+    q8: 'q8',
+    int8: 'int8',
+    uint8: 'uint8',
+    q4: 'q4',
+    bnb4: 'bnb4',
+    q4f16: 'q4f16', // fp16 model with int4 block weight quantization
+});
+/** @typedef {keyof typeof DATA_TYPES} DataType */
+
+export const DEFAULT_DEVICE_DTYPE_MAPPING = Object.freeze({
+    [DEVICE_TYPES.cpu]: DATA_TYPES.q8,
+    [DEVICE_TYPES.gpu]: DATA_TYPES.fp32,
+    [DEVICE_TYPES.wasm]: DATA_TYPES.q8,
+    [DEVICE_TYPES.webgpu]: DATA_TYPES.fp32,
+});
+
+/** @type {Record<DataType, string>} */
+export const DEFAULT_DTYPE_SUFFIX_MAPPING = Object.freeze({
+    [DATA_TYPES.fp32]: '',
+    [DATA_TYPES.fp16]: '_fp16',
+    [DATA_TYPES.int8]: '_int8',
+    [DATA_TYPES.uint8]: '_uint8',
+    [DATA_TYPES.q8]: '_quantized',
+    [DATA_TYPES.q4]: '_q4',
+    [DATA_TYPES.q4f16]: '_q4f16',
+    [DATA_TYPES.bnb4]: '_bnb4',
+});

package/src/utils/generic.js

@@ -0,0 +1,35 @@
+
+/**
+ * A base class for creating callable objects.
+ * See [here](https://stackoverflow.com/q/76073890) for more information.
+ * 
+ * @type {new () => {(...args: any[]): any, _call(...args: any[]): any}}
+ */
+export const Callable = /** @type {any} */ (class {
+    /**
+    * Creates a new instance of the Callable class.
+    */
+    constructor() {
+        /**
+         * Creates a closure that delegates to a private method '_call' with the given arguments.
+         * @type {any}
+         * @param {...any} args Zero or more arguments to pass to the '_call' method.
+         * @returns {*} The result of calling the '_call' method.
+         */
+        let closure = function (...args) {
+            return closure._call(...args)
+        }
+        return Object.setPrototypeOf(closure, new.target.prototype)
+    }
+
+    /**
+     * This method should be implemented in subclasses to provide the
+     * functionality of the callable object.
+     *
+     * @param {any[]} args
+     * @throws {Error} If the subclass does not implement the `_call` method.
+     */
+    _call(...args) {
+        throw Error('Must implement _call method in subclass')
+    }
+});