Implementation:Tensorflow Tfjs Tf LoadGraphModel
| Knowledge Sources | |
|---|---|
| Domains | Model_Loading, Inference |
| Principle | Principle:Tensorflow_Tfjs_Pretrained_Model_Loading |
| Type | API Doc |
| Last Updated | 2026-02-10 00:00 GMT |
Environment:Tensorflow_Tfjs_Browser_Runtime Heuristic:Tensorflow_Tfjs_Backend_Selection_Strategy Heuristic:Tensorflow_Tfjs_WebGL_Shader_Warmup Heuristic:Tensorflow_Tfjs_WASM_Cross_Origin_Isolation
Overview
This implementation documents the tf.loadGraphModel() API for loading pre-converted TensorFlow.js graph models from a URL or IOHandler into the browser or Node.js runtime. It also covers tf.loadLayersModel() for loading Keras-converted layers models and the FileHandler class for local Node.js file loading.
Source References
- tf.loadGraphModel: tfjs-converter/src/executor/graph_model.ts:L624-642
- tf.loadLayersModel: tfjs-layers/src/models.ts:L248-270
- FileHandler: tfjs-inference/src/file_handler.ts:L25-142
API: tf.loadGraphModel
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>
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| modelUrl | string or io.IOHandler | Yes | URL to the model.json file, or an IOHandler instance for custom loading (IndexedDB, filesystem, etc.) |
| options | io.LoadOptions | No | Configuration options for model loading (see below) |
LoadOptions Fields
| Field | Type | Default | Description |
|---|---|---|---|
| fromTFHub | boolean | false | If true, the URL is treated as a TF Hub module URL. Appends ?tfjs-format=file to resolve the model.json location. |
| requestInit | RequestInit | undefined | HTTP request configuration passed to fetch(). Use for custom headers, credentials, CORS mode, etc. |
| onProgress | (fraction: number) => void | undefined | Callback invoked during weight shard downloads. fraction ranges from 0.0 to 1.0. |
| fetchFunc | typeof fetch | global fetch | Custom fetch function for environments without a global fetch (e.g., older Node.js versions). |
| weightPathPrefix | string | base path of modelUrl | Custom prefix for weight shard URLs. Overrides the default behavior of resolving shard paths relative to model.json. |
| weightUrlConverter | (weightFileName: string) => Promise<string> | undefined | Async function to transform individual weight shard URLs before fetching. |
Return Value
Returns a Promise<GraphModel> that resolves to a fully loaded GraphModel instance. The GraphModel has the following key properties and methods:
| Property/Method | Type | Description |
|---|---|---|
| inputs | NodeDef[] | The model's input node definitions (name, shape, dtype) |
| outputs | NodeDef[] | The model's output node definitions |
| predict() | Function | Run synchronous inference (see Implementation:Tensorflow_Tfjs_GraphModel_Predict) |
| execute() | Function | Run synchronous inference with named output selection |
| executeAsync() | Function | Run async inference for models with dynamic control flow |
| dispose() | Function | Release all model resources (weight tensors, etc.) |
| modelVersion | string | The model format version |
| modelSignature | SignatureDef | The model's serving signature metadata |
Example
// Basic loading from a URL
const model = await tf.loadGraphModel(
'https://storage.googleapis.com/my-bucket/models/v1/model.json'
);
console.log('Model loaded successfully');
console.log('Inputs:', model.inputs.map(i => `${i.name}: ${i.shape}`));
console.log('Outputs:', model.outputs.map(o => `${o.name}: ${o.shape}`));
// Run inference
const input = tf.zeros([1, 224, 224, 3]);
const output = model.predict(input);
output.print();
// Clean up
input.dispose();
output.dispose();
model.dispose();
Loading from TF Hub
TF Hub models use a special URL format. The fromTFHub option instructs the loader to append the ?tfjs-format=file query parameter to resolve the model.json location:
// Load a MobileNet V2 model from TF Hub
const model = await tf.loadGraphModel(
'https://tfhub.dev/google/imagenet/mobilenet_v2_100_224/classification/5',
{ fromTFHub: true }
);
// The loader internally fetches:
// https://tfhub.dev/google/imagenet/mobilenet_v2_100_224/classification/5/model.json?tfjs-format=file
Loading with Progress Tracking
// Display loading progress (useful for large models)
const model = await tf.loadGraphModel(
'https://example.com/models/large-model/model.json',
{
onProgress: (fraction) => {
const percent = (fraction * 100).toFixed(1);
console.log(`Loading model: ${percent}%`);
// Update a progress bar in the UI
document.getElementById('progress').style.width = `${percent}%`;
}
}
);
Loading with Authentication
// Load from an authenticated endpoint
const model = await tf.loadGraphModel(
'https://private-api.example.com/models/model.json',
{
requestInit: {
headers: {
'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIs...',
'X-Custom-Header': 'value'
},
credentials: 'include' // Include cookies for CORS requests
}
}
);
API: tf.loadLayersModel
Signature
// From tfjs-layers/src/models.ts:L248-270
export async function loadLayersModel(
pathOrIOHandler: string | io.IOHandler,
options?: io.LoadOptions
): Promise<LayersModel>
Description
tf.loadLayersModel() loads models that were converted from Keras HDF5 or Keras SavedModel format. The resulting LayersModel provides the full Keras-compatible API including predict(), evaluate(), compile(), and fit() for fine-tuning.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| pathOrIOHandler | string or io.IOHandler | Yes | URL to the model.json file (with scheme:// prefix for non-HTTP sources like indexeddb:// or localstorage://), or an IOHandler instance. |
| options | io.LoadOptions | No | Same LoadOptions as tf.loadGraphModel(): requestInit, onProgress, etc. |
Example
// Load a Keras-converted layers model from URL
const layersModel = await tf.loadLayersModel(
'https://example.com/keras-model/model.json'
);
// Layers models support the full Keras API
layersModel.summary(); // Print model architecture
// Run inference
const input = tf.tensor2d([[1, 2, 3, 4]], [1, 4]);
const prediction = layersModel.predict(input);
prediction.print();
// Fine-tune the model (layers models only)
layersModel.compile({
optimizer: 'adam',
loss: 'categoricalCrossentropy',
metrics: ['accuracy']
});
await layersModel.fit(xTrain, yTrain, { epochs: 5 });
// Save to IndexedDB for offline use
await layersModel.save('indexeddb://my-model');
// Load back from IndexedDB
const cachedModel = await tf.loadLayersModel('indexeddb://my-model');
FileHandler for Node.js
Source Reference
tfjs-inference/src/file_handler.ts:L25-142
Description
The FileHandler class provides an IOHandler implementation for loading models from the local filesystem in Node.js, without HTTP. It reads the model.json file and weight shard files directly from disk.
Usage
// Node.js: Load a model from the local filesystem
const tf = require('@tensorflow/tfjs-node'); // or @tensorflow/tfjs-node-gpu
const { FileHandler } = require('@tensorflow/tfjs-inference');
// Create a FileHandler pointing to the model.json file
const handler = new FileHandler('/path/to/converted_model/model.json');
// Load the graph model using the FileHandler
const model = await tf.loadGraphModel(handler);
// Run inference
const input = tf.tensor4d([...data], [1, 224, 224, 3]);
const output = model.predict(input);
const result = await output.data();
console.log('Prediction:', result);
// Clean up
input.dispose();
output.dispose();
model.dispose();
Loading from Other Sources
IndexedDB (Browser Persistence)
// Save a loaded model to IndexedDB
await model.save('indexeddb://my-cached-model');
// Later, load from IndexedDB (no network request)
const cachedModel = await tf.loadGraphModel('indexeddb://my-cached-model');
Browser File Upload
// Load from user-uploaded files via file input
const jsonUpload = document.getElementById('json-upload');
const weightsUpload = document.getElementById('weights-upload');
const model = await tf.loadGraphModel(
tf.io.browserFiles([jsonUpload.files[0], ...weightsUpload.files])
);
Custom IOHandler
// Implement a custom IOHandler for any loading source
const customHandler = {
async load() {
// Fetch model topology
const modelJSON = await fetchModelFromCustomSource();
// Fetch weight data
const weightData = await fetchWeightsFromCustomSource();
return {
modelTopology: modelJSON.modelTopology,
weightSpecs: modelJSON.weightsManifest[0].weights,
weightData: weightData
};
}
};
const model = await tf.loadGraphModel(customHandler);
Error Handling
try {
const model = await tf.loadGraphModel('https://example.com/model/model.json');
} catch (error) {
if (error.message.includes('Failed to fetch')) {
console.error('Network error: Could not reach the model server');
console.error('Check the URL, CORS headers, and network connectivity');
} else if (error.message.includes('Unsupported op')) {
console.error('Model contains operations not supported by TF.js');
console.error('Unsupported operations:', error.message);
} else if (error.message.includes('JSON')) {
console.error('Invalid model.json format');
} else {
console.error('Model loading failed:', error.message);
}
}
Performance Considerations
| Consideration | Recommendation |
|---|---|
| First load | Models are fetched over the network; use onProgress to show loading state to the user |
| Subsequent loads | Cache models in IndexedDB using model.save('indexeddb://name') for instant offline loading |
| Large models | Use smaller weight shards (via --weight_shard_size_bytes during conversion) for parallel downloads |
| Mobile devices | Use quantized models (uint8 or float16) to reduce download size and memory usage |
| CDN hosting | Serve from a CDN close to users for lower latency; use immutable cache headers on weight shards |
See Also
- Principle:Tensorflow_Tfjs_Pretrained_Model_Loading — The principle this implementation fulfills
- Implementation:Tensorflow_Tfjs_Model_Hosting_Pattern — Previous step: hosting the model files
- Implementation:Tensorflow_Tfjs_GraphModel_Predict — Next step: running inference on the loaded model
Environments
- Environment:Tensorflow_Tfjs_Browser_Runtime -- Browser runtime (WebGL / WebGPU / WASM / CPU backends)
Heuristics
- Heuristic:Tensorflow_Tfjs_Backend_Selection_Strategy -- Choose the optimal compute backend for your environment
- Heuristic:Tensorflow_Tfjs_WebGL_Shader_Warmup -- Warm up WebGL shaders with a dummy predict call to avoid first-inference latency
- Heuristic:Tensorflow_Tfjs_WASM_Cross_Origin_Isolation -- Enable Cross-Origin Isolation headers for WASM multi-threading
Page Connections
Double-click a node to navigate. Hold to expand connections.
Principle
Implementation
Heuristic
Environment