Unlocking the Conversion: From .h5 to ONNX

A complete guide and code example for converting Keras .h5 models to ONNX format

conversion process computer code programming

Key Highlights

Easy Installation: Use pip to install TensorFlow, tf2onnx, and ONNX packages.
Step-by-Step Code: Detailed code examples show how to load a .h5 model, convert it, and save it as an ONNX file.
Customization and Troubleshooting: Understand input signatures and opset numbers for smooth conversion tailored to your model.

Introduction

Converting a Keras model stored in a .h5 file into ONNX (Open Neural Network Exchange) format allows you to deploy and share your trained models across different frameworks and platforms. This comprehensive tutorial provides a robust guide and a complete code example to help you complete this conversion using Python libraries.

Required Libraries and Setup

Installing the Necessary Packages

To successfully convert your .h5 model to ONNX format, you need to install the following libraries using pip:


# Install TensorFlow, tf2onnx, and onnx
pip install tensorflow tf2onnx onnx

These packages allow you to load the Keras model (.h5 file), convert it to ONNX format, and save the converted model on your disk.

Step-by-Step Conversion Process

1. Loading and Building a Sample Model

For demonstration purposes, we will create a simple Keras model, save it as a .h5 file, and then perform the conversion to ONNX format. If you already have a .h5 model, you can skip the model creation and saving steps.

Creating and Saving a Keras Model

Below is the code that creates a basic model for tasks like classification or regression. In this example, the model has three layers, including an input layer defined by input_shape, two hidden layers with activation functions, and an output layer.


import tensorflow as tf
from tensorflow import keras
from tensorflow.keras import layers

def create_model():
    # Define a simple model architecture
    model = keras.Sequential([
        layers.Dense(64, activation='relu', input_shape=(784,)),
        layers.Dense(32, activation='relu'),
        layers.Dense(10)  # Example: output layer for classification into 10 classes
    ])
    
    model.compile(optimizer='adam',
                  loss=tf.keras.losses.SparseCategoricalCrossentropy(from_logits=True),
                  metrics=['accuracy'])
    return model

# Create the model instance
model = create_model()

# Save the model to an H5 file
h5_path = "simple_model.h5"
model.save(h5_path)
print(f"Model saved in H5 format at {h5_path}")

The above code builds a simple neural network and saves it as a .h5 file. You can substitute this with your own model file if you have one.

2. Converting a .h5 Model to ONNX Format

Now we use the tf2onnx library to convert the .h5 model into ONNX format. The important step here is to correctly specify the input signature, which defines the shape and data type of the model's input.

Conversion Code with Input Signature

The following code demonstrates the complete conversion process. We first load the model from the .h5 file, then specify the input shape using tf.TensorSpec, convert the model to ONNX format, and finally save the resulting ONNX model.


import tensorflow as tf
import tf2onnx
import onnx

def convert_h5_to_onnx(h5_model_path, onnx_model_path, opset_version=13):
    # Load the Keras model from the .h5 file
    model = tf.keras.models.load_model(h5_model_path)
    
    # Define the input signature based on the model's input shape
    # Here, we assume the model's input shape excludes the batch size; e.g., (784,)
    input_signature = (tf.TensorSpec(model.input_shape[1:], tf.float32, name="input"),)
    
    # Convert the Keras model to an ONNX model using tf2onnx
    onnx_model, _ = tf2onnx.convert.from_keras(model, input_signature=input_signature, opset=opset_version)
    
    # Save the ONNX model to the specified file
    with open(onnx_model_path, "wb") as f:
        f.write(onnx_model)
    
    print(f"Conversion successful! ONNX model saved at {onnx_model_path}")

# Define the paths for the H5 and ONNX models
h5_model_path = "simple_model.h5"
onnx_model_path = "simple_model.onnx"
convert_h5_to_onnx(h5_model_path, onnx_model_path)

In this code:

Loading the Model: The model is loaded from the .h5 file.
Input Signature: We assume that model.input_shape returns a tuple with the first dimension being the batch size. We define the input signature excluding the batch size. Adjust this if your model has a different setup.
OPSET Specification: The opset parameter (default set as 13) is used to specify the ONNX operator set version. Choose the appropriate version based on your target environment.
Writing the File: The converted ONNX model is written to disk in binary mode.

Detailed Explanation and Best Practices

Here we dive deeper into the crucial aspects of converting a Keras .h5 model to ONNX format. Understanding these concepts is essential for troubleshooting and ensuring compatibility with your deployment environment.

Input Signature

The input signature tells the conversion tool about the shape and data type of the model inputs. For example, if your model takes an input vector of 784 elements, you need to specify this using tf.TensorSpec.

In our conversion code, we used:


input_signature = (tf.TensorSpec(model.input_shape[1:], tf.float32, name="input"),)

This line means the conversion tool expects an input tensor with the shape defined by model.input_shape[1:] and with the data type tf.float32. Always ensure the data type here matches what your model was trained with.

OPSET Version

The opset version determines the set of operations (operators) that can be used in the converted ONNX model. Often, compatibility with your target runtime (e.g., ONNX Runtime) is dependent on using a specific opset version. In our example, we defaulted to 13, but you might need versions like 11 or 14 depending on your scenario.

Changing the opset version is as simple as passing a different number to the function argument opset_version when calling convert_h5_to_onnx.

Model Compatibility and Custom Layers

One common pitfall during conversion is the presence of custom layers. If your Keras model uses custom layers that aren’t part of the basic Keras API, you may encounter issues such as "Unknown layer" errors. To solve this:

Ensure that your custom layer definitions are available when loading the model.
Consider converting the .h5 file to a TensorFlow SavedModel first and then converting that model to ONNX.

Verifying the Converted ONNX Model

After conversion, it is important to verify the integrity of your ONNX model. You can load the ONNX model in your Python environment and use ONNX’s built-in tools to perform a consistency check.

Verification Code

The code snippet below demonstrates how to load and check the ONNX model:


import onnx

# Load the converted ONNX model
onnx_model = onnx.load("simple_model.onnx")

# Verify the model's structure and ensure it is valid
try:
    onnx.checker.check_model(onnx_model)
    print("ONNX model verification successful!")
except onnx.checker.ValidationError as e:
    print("ONNX model verification failed:", e)

A Comprehensive Table Summary

Step	Action	Key Commands/Code
Installation	Install required packages	`pip install tensorflow tf2onnx onnx`
Model Creation	Create and save a Keras model in .h5 format	`model.save("simple_model.h5")`
Conversion	Load .h5 model, define input signature, and convert to ONNX	`tf2onnx.convert.from_keras(model, input_signature, opset=13)`
Save ONNX	Write the converted ONNX model to a file	`with open("simple_model.onnx", "wb") as f: f.write(onnx_model)`
Verification	Load and check the ONNX model	`onnx.checker.check_model(onnx_model)`

Additional Notes and Considerations

When working with model conversion between different frameworks, it is essential to keep the following in mind:

Custom Layers: If your model utilizes custom layers, ensure they are properly imported or consider converting the model to TensorFlow SavedModel format before converting to ONNX.
Version Compatibility: The versions of TensorFlow and tf2onnx you use can affect the conversion process. Always refer to the respective documentation to make sure you are using compatible versions.
Input/Output Consistency: Confirm that the input and output signatures of your model are accurately detected. Mismatch here can lead to conversion errors.
Deployment Environment: Your target environment for deploying the ONNX model might have specific requirements. Test the model in that environment to ensure everything works as expected.