Principle:Tensorflow Tfjs Pretrained Model Loading

Knowledge Sources	TensorFlow.js tfjs-converter/src/executor/graph_model.ts tfjs-layers/src/models.ts tfjs-inference/src/file_handler.ts
Domains	Model_Loading, Inference
Implementation	Implementation:Tensorflow_Tfjs_Tf_LoadGraphModel
Type	API Doc
Last Updated	2026-02-10 00:00 GMT

Overview

Loading pre-converted graph models from a URL into the browser or Node.js runtime for inference. Model deserialization reconstructs a trained computation graph and its weights from stored artifacts, making the model available for predictions in the JavaScript environment.

Theory

Graph Model Loading Pipeline

Graph model loading is a multi-step process that transforms serialized model artifacts into an executable in-memory computation graph:

Step 1: Fetch the Model Manifest

The loader makes an HTTP GET request (or uses an IOHandler) to retrieve the model.json file. This file contains:

modelTopology: The serialized computation graph (for graph models) or layer configuration (for layers models)
weightsManifest: An array of weight groups, each specifying shard filenames and tensor metadata
format: The model format identifier (e.g., "graph-model" or "layers-model")
userDefinedMetadata: Optional metadata added during conversion

Step 2: Parse the Computation Graph

For graph models, the modelTopology field contains a serialized TensorFlow GraphDef protocol buffer (encoded as JSON). The parser:

Deserializes the GraphDef into node definitions
Resolves node connections (inputs/outputs)
Validates that all operations in the graph are supported by the TF.js runtime
Constructs an internal execution graph representation

For layers models, the modelTopology contains a Keras-style layer configuration that is reconstructed into a Keras-compatible model using the TF.js layers API.

Step 3: Download Weight Shards

The loader reads the weightsManifest to determine which .bin files to download:

Each weight group lists one or more shard files and the tensors contained within
Shards are fetched in parallel for performance
The onProgress callback (if provided) reports download progress as a fraction

Step 4: Deserialize Weight Data

Binary weight data from the shards is deserialized:

The raw ArrayBuffer data is sliced according to the tensor metadata (offset, shape, dtype)
Each slice is wrapped in the appropriate TypedArray (Float32Array, Int32Array, etc.)
Quantized weights are dequantized using stored scale/offset parameters

Step 5: Construct the Execution Graph

The deserialized weights are assigned to the corresponding graph nodes:

Variable nodes receive their weight tensors
Constant nodes are materialized from the weight data
The complete graph is validated for executability
The resulting GraphModel (or LayersModel) object is returned, ready for inference

Graph Models vs. Layers Models

Aspect	Graph Model (tf.loadGraphModel)	Layers Model (tf.loadLayersModel)
Source format	TF SavedModel, TF Hub, Frozen Graph	Keras HDF5, Keras SavedModel
Internal representation	Frozen TensorFlow computation graph	Keras-style layer graph
Inference API	predict(), execute(), executeAsync()	predict(), evaluate()
Fine-tuning	Not supported (frozen)	Supported (trainable weights)
Custom ops	Supported via registration	Supported via layer registration
Output selection	execute() can select specific output nodes	predict() returns defined outputs
Source file	tfjs-converter/src/executor/graph_model.ts:L624-642	tfjs-layers/src/models.ts:L248-270

Loading Sources

Models can be loaded from multiple sources through the IOHandler abstraction:

Source	Interface	Use Case
HTTP(S) URL	String URL to model.json	Browser: remote model hosting
TF Hub URL	String URL with fromTFHub: true	Browser: TF Hub models
IndexedDB	tf.io.browserFiles() or indexeddb:// scheme	Browser: locally cached models
Local Storage	localstorage:// scheme	Browser: small models
File System	FileHandler (Node.js)	Node.js: local file loading
Custom IOHandler	io.IOHandler interface	Any: custom loading logic

The FileHandler class (tfjs-inference/src/file_handler.ts:L25-142) provides Node.js filesystem loading, reading the model.json and weight shard files directly from disk without HTTP.

Signature

// Load a graph model from URL
tf.loadGraphModel(
  modelUrl: string | io.IOHandler,
  options?: io.LoadOptions
): Promise<GraphModel>

// Load a layers model from URL
tf.loadLayersModel(
  pathOrIOHandler: string | io.IOHandler,
  options?: io.LoadOptions
): Promise<LayersModel>

Full TypeScript Signature

// From tfjs-converter/src/executor/graph_model.ts:L624-642
export async function loadGraphModel(
  modelUrl: string | io.IOHandler,
  options: io.LoadOptions = {},
  tfio = io
): Promise<GraphModel>

Key Parameters

Parameter	Type	Description
modelUrl	string or io.IOHandler	URL to the model.json file, or an IOHandler instance for custom loading
options.fromTFHub	boolean	If true, appends ?tfjs-format=file to TF Hub URLs for direct model.json resolution
options.requestInit	RequestInit	HTTP request configuration (headers, credentials, mode) passed to fetch()
options.onProgress	(fraction: number) => void	Callback invoked during weight download with progress fraction (0.0 to 1.0)
options.fetchFunc	typeof fetch	Custom fetch function for environments without global fetch
options.weightPathPrefix	string	Custom prefix for weight shard URLs (overrides the default base path of model.json)

Inputs and Outputs

Inputs

modelUrl: A string URL pointing to the model.json file, or an IOHandler instance that implements custom loading logic
options (optional): Configuration for HTTP requests, TF Hub loading, progress tracking, and custom weight paths

Outputs

A Promise<GraphModel> that resolves to a GraphModel instance ready for inference
Or a Promise<LayersModel> that resolves to a LayersModel instance ready for inference and optionally fine-tuning

Example

// Load a graph model from a URL
const model = await tf.loadGraphModel(
  'https://storage.googleapis.com/my-bucket/models/model.json'
);

// Load from TF Hub
const hubModel = await tf.loadGraphModel(
  'https://tfhub.dev/google/imagenet/mobilenet_v2_100_224/classification/5',
  { fromTFHub: true }
);

// Load with progress tracking
const trackedModel = await tf.loadGraphModel(
  'https://example.com/model/model.json',
  {
    onProgress: (fraction) => {
      console.log(`Loading: ${(fraction * 100).toFixed(1)}%`);
    }
  }
);

// Load with custom HTTP headers (e.g., for authenticated endpoints)
const authModel = await tf.loadGraphModel(
  'https://private-api.example.com/models/model.json',
  {
    requestInit: {
      headers: { 'Authorization': 'Bearer <token>' },
      credentials: 'include'
    }
  }
);

// Load a layers model
const layersModel = await tf.loadLayersModel(
  'https://example.com/keras-model/model.json'
);

// Node.js: Load from local filesystem using FileHandler
const { FileHandler } = require('@tensorflow/tfjs-inference');
const handler = new FileHandler('/path/to/model/model.json');
const localModel = await tf.loadGraphModel(handler);

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment