or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdmodels-tokenizers.mdpipelines.mdprocessors.mdutilities.md
tile.json

tessl/npm-xenova--transformers

State-of-the-art Machine Learning for the web that runs Transformers directly in browsers with no server needed.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@xenova/transformers@2.17.x

To install, run

npx @tessl/cli install tessl/npm-xenova--transformers@2.17.0

index.mddocs/

Transformers.js

Transformers.js is a JavaScript/TypeScript library that brings state-of-the-art machine learning models to web browsers and Node.js environments without requiring server-side processing. It provides functionally equivalent APIs to Hugging Face's Python transformers library, enabling developers to run pretrained models for natural language processing, computer vision, audio processing, and multimodal tasks directly in client-side applications.

Package Information

  • Package Name: @xenova/transformers
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install @xenova/transformers

Core Imports

import { pipeline, AutoTokenizer, AutoModel, AutoProcessor, env } from "@xenova/transformers";

For CommonJS environments:

const { pipeline, AutoTokenizer, AutoModel, AutoProcessor, env } = require("@xenova/transformers");

Basic Usage

import { pipeline } from "@xenova/transformers";

// Create a text classification pipeline
const classifier = await pipeline("sentiment-analysis");

// Classify text
const result = await classifier("I love this library!");
// Output: [{ label: 'POSITIVE', score: 0.999 }]

// Create a text generation pipeline
const generator = await pipeline("text-generation", "gpt2");

// Generate text
const output = await generator("The future of AI is", {
  max_new_tokens: 50,
  do_sample: true,
  temperature: 0.7,
});

Architecture

Transformers.js is built around several key components:

  • Pipeline API: High-level interface (pipeline()) providing task-specific implementations for common ML operations
  • Auto Classes: Automatic model, tokenizer, and processor selection (AutoModel, AutoTokenizer, AutoProcessor, AutoConfig, etc.)
  • Processors: Input preprocessing for images, audio, and multimodal data
  • Specific Classes: Direct access to model implementations (BERT, GPT-2, T5, etc.)
  • Utilities: Tensor operations, image/audio processing, and mathematical functions
  • Environment Configuration: Global settings for model caching, backends, and runtime options

The library leverages ONNX Runtime for efficient model execution and supports both browser and Node.js environments.

Capabilities

Pipeline Interface

High-level API providing ready-to-use implementations for common machine learning tasks including text classification, text generation, translation, image classification, object detection, and audio processing.

function pipeline(
  task: string,
  model?: string,
  options?: PipelineOptions
): Promise<Pipeline>;

interface PipelineOptions {
  quantized?: boolean;
  progress_callback?: (progress: any) => void;
  config?: any;
  cache_dir?: string;
  local_files_only?: boolean;
  revision?: string;
  model_file_name?: string;
}

Pipelines

Models and Tokenizers

Auto classes for automatic model and tokenizer selection, plus direct access to specific model implementations for fine-grained control over model loading and inference.

class AutoModel {
  static async from_pretrained(
    model_name_or_path: string,
    options?: ModelOptions
  ): Promise<PreTrainedModel>;
}

class AutoTokenizer {
  static async from_pretrained(
    model_name_or_path: string,
    options?: TokenizerOptions
  ): Promise<PreTrainedTokenizer>;
}

interface ModelOptions {
  quantized?: boolean;
  progress_callback?: (progress: any) => void;
  config?: any;
  cache_dir?: string;
  local_files_only?: boolean;
  revision?: string;
}

interface TokenizerOptions {
  quantized?: boolean;
  progress_callback?: (progress: any) => void;
  config?: any;
  cache_dir?: string;
  local_files_only?: boolean;
  revision?: string;
}

Models and Tokenizers

Processors

Input preprocessing classes for non-textual data including images, audio, and multimodal inputs. Processors handle format conversion, normalization, and feature extraction.

class AutoProcessor {
  static async from_pretrained(
    model_name_or_path: string,
    options?: ProcessorOptions
  ): Promise<Processor>;
}

interface ProcessorOptions {
  quantized?: boolean;
  progress_callback?: (progress: any) => void;
  config?: any;
  cache_dir?: string;
  local_files_only?: boolean;
  revision?: string;
}

Processors

Utilities

Comprehensive utility functions for tensor operations, image processing, audio processing, and mathematical computations that support the core ML functionality.

class Tensor {
  constructor(type: string, data: any, dims: number[]);
  
  // Core tensor operations
  mean(dim?: number | number[]): Tensor;
  permute(dims: number[]): Tensor;
  squeeze(dim?: number): Tensor;
  unsqueeze(dim: number): Tensor;
}

class RawImage {
  static async read(input: string | URL | Buffer): Promise<RawImage>;
  static async fromURL(url: string | URL): Promise<RawImage>;
  
  resize(width: number, height: number): RawImage;
  crop(left: number, top: number, width: number, height: number): RawImage;
}

Utilities

Environment Configuration

Global environment settings for controlling model caching, backend selection, local file usage, and runtime behavior.

const env: {
  /** Directory for caching downloaded models and tokenizers */
  cacheDir: string;
  
  /** Only use local files, disable remote downloads */
  localFilesOnly: boolean;
  
  /** Allow downloading models from remote sources */
  allowRemoteModels: boolean;
  
  /** Base URL for remote model downloads */
  remoteURL: string;
  
  /** Template for remote model paths */
  remotePathTemplate: string;
  
  /** Allow loading models from local filesystem */
  allowLocalModels: boolean;
  
  /** Base URL for local model loading */
  localURL: string;
  
  /** Template for local model paths */
  localPathTemplate: string;
  
  /** ONNX Runtime backend configuration */
  backends: {
    onnx: {
      wasm: {
        /** Path to ONNX Runtime WASM files */
        wasmPaths: string;
        
        /** Number of threads for WASM execution (default: 1) */
        numThreads: number;
        
        /** Enable SIMD optimizations (default: true) */
        simd: boolean;
        
        /** Use multithreaded WASM (default: false) */
        multiThread: boolean;
      };
    };
  };
  
  /** Current library version */
  readonly VERSION: string;
  
  /** Whether web cache is available (browser only) */
  readonly WEB_CACHE_AVAILABLE: boolean;
  
  /** Whether file system access is available */
  readonly FS_AVAILABLE: boolean;
  
  /** Whether running in local environment with file system */
  readonly RUNNING_LOCALLY: boolean;
};

Configuration Examples:

import { env } from "@xenova/transformers";

// Disable remote model downloads
env.allowRemoteModels = false;

// Set custom cache directory
env.cacheDir = "/path/to/custom/cache";

// Use only local files
env.localFilesOnly = true;

// Configure WASM backend
env.backends.onnx.wasm.numThreads = 4;
env.backends.onnx.wasm.simd = true;

// Set custom remote URL for model downloads
env.remoteURL = "https://custom-model-server.com/";
env.remotePathTemplate = "models/{model}/";

The env object provides comprehensive configuration for the library's runtime behavior including model storage locations, backend preferences, performance settings, and environment detection.

Types

interface Pipeline {
  (input: any, options?: any): Promise<any>;
  dispose(): Promise<void>;
}

interface PreTrainedModel {
  config: any;
  forward(model_inputs: any): Promise<any>;
  dispose(): Promise<void>;
}

interface PreTrainedTokenizer {
  encode(text: string, options?: any): any;
  decode(token_ids: number[] | Tensor, options?: any): string;
  batch_decode(sequences: number[][] | Tensor[], options?: any): string[];
  dispose(): Promise<void>;
}