Principle:Tensorflow Tfjs Model Format Conversion

Knowledge Sources	TensorFlow.js TensorFlow.js Conversion Guide tfjs-converter/README.md
Domains	Model_Persistence, Deployment
Implementation	Implementation:Tensorflow_Tfjs_Tensorflowjs_Converter_CLI
Type	External Tool Doc
Last Updated	2026-02-10 00:00 GMT

Overview

Converting ML models between serialization formats, specifically from Python TensorFlow formats to browser-compatible TensorFlow.js format. Format conversion transforms model artifacts from one framework's representation to another while preserving the computation graph and weights, enabling models trained in one environment to run in another.

Theory

The Conversion Pipeline

Model format conversion is a multi-stage process that transforms a model from its source representation to a target representation. For TensorFlow-to-TensorFlow.js conversion, the pipeline involves five key stages:

Stage 1: Source Format Parsing

The converter reads the source model format and extracts the computation graph and weight data:

SavedModel: Parses the saved_model.pb protocol buffer to extract the MetaGraphDef, resolves the serving signature (default: "serving_default"), and reads checkpoint shards from the variables/ directory
Keras HDF5: Extracts the model architecture JSON from HDF5 attributes and reads weight arrays from HDF5 datasets
TF Hub: Downloads the module from the TF Hub URL, which is itself a SavedModel, and parses it as above
Frozen Graph: Reads the frozen GraphDef protocol buffer where weights are embedded as constant nodes

Stage 2: Operation Mapping

Each operation in the source computation graph must be mapped to a corresponding TensorFlow.js operation:

The converter maintains an op registry that maps TensorFlow op names to TF.js op implementations
Operations not in the registry are flagged as unsupported and will cause conversion to fail
Some operations are decomposed into multiple TF.js operations (e.g., a fused batch normalization may become separate multiply and add operations)
Custom operations require explicit registration in the TF.js runtime

Stage 3: Weight Conversion

Weight data is converted from the source format's binary representation to TF.js typed arrays:

Weights are read from checkpoint shards (SavedModel) or HDF5 datasets (Keras)
Data types are preserved or converted (e.g., float32 remains float32, int64 may be downcast to int32)
Weight tensors are serialized into a flat binary format that can be deserialized into JavaScript TypedArray objects

Stage 4: Weight Quantization (Optional)

Quantization reduces the precision of weight values to decrease model size:

Quantization Type	Original Dtype	Quantized Dtype	Size Reduction	Accuracy Impact
float16	float32 (32-bit)	float16 (16-bit)	~50%	Minimal
uint8	float32 (32-bit)	uint8 (8-bit)	~75%	Low to moderate
uint16	float32 (32-bit)	uint16 (16-bit)	~50%	Low

Quantization works by mapping the range of weight values to the reduced precision range, storing scale and offset metadata for dequantization at load time.

Stage 5: Weight Sharding

Weight data is split into fixed-size binary files ("shards") for efficient network transfer:

Default shard size: 4,194,304 bytes (4 MB)
Sharding enables parallel downloads of weight data in the browser
Sharding enables incremental loading for large models
The model.json manifest references each shard by filename and byte ranges

Output Formats

The converter produces two distinct output formats:

Output Format	Source Formats	Use Case	model.json Contains
tfjs_graph_model	SavedModel, TF Hub, Frozen Graph	Inference only (frozen graph)	Graph topology + weight manifest
tfjs_layers_model	Keras HDF5, Keras SavedModel	Inference + optional fine-tuning	Keras-style layer config + weight manifest

Output File Structure

The conversion produces:

model.json: The model manifest file containing:
- modelTopology: The computation graph (graph model) or layer configuration (layers model)
- weightsManifest: An array describing weight groups, shard files, and tensor metadata (name, shape, dtype)
- format: The model format identifier
- generatedBy: The converter version
- convertedBy: The TF.js version
group1-shard1of3.bin, group1-shard2of3.bin, etc.: Binary weight shard files

Key Parameters

Parameter	Description	Values
--input_format	Source model format	tf_saved_model, keras, keras_saved_model, tf_hub, tfjs_layers_model, tf_frozen_model
--output_format	Target model format	tfjs_graph_model, tfjs_layers_model
--signature_name	Serving signature to export (SavedModel only)	String (default: "serving_default")
--saved_model_tags	MetaGraphDef tags (SavedModel only)	Comma-separated (default: "serve")
--quantize_float16	Quantize weights to float16	Flag (no value)
--quantize_uint8	Quantize weights to uint8	Flag (no value)
--quantize_uint16	Quantize weights to uint16	Flag (no value)
--weight_shard_size_bytes	Maximum shard file size	Integer (default: 4194304)
--output_node_names	Output nodes (frozen graph only)	Comma-separated node names
--control_flow_v2	Enable Control Flow V2 ops	Flag (default: true)
--strip_debug_ops	Remove debug operations	Flag (default: true)

Inputs and Outputs

Inputs

A Python model in one of the supported source formats:
- SavedModel directory (containing saved_model.pb + variables/)
- Keras HDF5 file (.h5)
- TF Hub module URL (https://tfhub.dev/...)
- Frozen graph protobuf file (.pb)
- TF.js layers model directory (for reverse or format-to-format conversion)

Outputs

model.json: The model manifest file with graph topology and weight metadata
One or more .bin weight shard files containing the serialized weight data
These files together constitute a complete TF.js model ready for deployment

Source Reference

The CLI interface and parameter definitions are documented in: tfjs-converter/README.md:L87-171

Page Connections

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

Principle

Implementation

Heuristic

Environment