Unified (TensorFlow and Pytorch)

coremltools.converters._converters_entry.convert(model, source='auto', inputs=None, outputs=None, classifier_config=None, minimum_deployment_target=None, convert_to=None, compute_precision=None, skip_model_load=False, compute_units=ComputeUnit.ALL, useCPUOnly=False, package_dir=None, debug=False)[source]

Convert a TensorFlow or PyTorch model to the Core ML model format as either a neural network or an ML program. To learn about the differences, see ML Programs. Some parameters and requirements differ by TensorFlow and PyTorch frameworks.

Parameters
model :

TensorFlow 1, TensorFlow 2, or PyTorch model in one of the following formats.

sourcestr (optional)

One of [auto, tensorflow, pytorch, milinternal]. auto determines the framework automatically for most cases. Raises ValueError if it fails to determine the source framework.

inputslist of TensorType or ImageType
  • TensorFlow 1 and 2

    • The inputs parameter is optional. If not provided, the inputs are placeholder nodes in the model (if the model is frozen graph) or function inputs (if the model is a tf.function).

    • The inputs must correspond to all or some of the placeholder nodes in the TF model.

    • TensorType and ImageType in inputs must have the name specified. shape is optional.

    • If inputs is provided, it must be a flat list.

  • PyTorch

    • The inputs parameter is required.

    • inputs may be a nested list or tuple.

    • TensorType and ImageType in inputs must have the name and shape specified.

outputslist[str] (optional)
  • TensorFlow 1 and 2

    • The outputs parameter is optional.

    • If specified, outputs is a list of string representing node names.

    • If outputs is not specified, the converter infers outputs to all be terminal identity nodes.

  • PyTorch

    • outputs must not be specified.

classifier_configClassifierConfig class (optional)

The configuration if the MLModel is intended to be a classifier.

minimum_deployment_targetcoremltools.target enumeration (optional)

A member of the coremltools.target enum. The value of this parameter determines the type of the model representation produced by the converter. To learn about the differences between neural networks and ML programs, see ML Programs.

  • The converter produces a neural network (neuralnetwork) if:

    minimum_deployment_target <= coremltools.target.iOS14/
                                 coremltools.target.macOS11/
                                 coremltools.target.watchOS7/
                                 coremltools.target.tvOS14:
    
  • The converter produces an ML program (mlprogram) if:

    minimum_deployment_target >= coremltools.target.iOS15/
                                  coremltools.target.macOS12/
                                  coremltools.target.watchOS8/
                                  coremltools.target.tvOS15:
    
  • If neither the minimum_deployment_target nor the convert_to parameter is specified, the converter produces the neural network model type with as minimum of a deployment target as possible.

  • If this parameter is specified and convert_to is also specified, they must be compatible. The following are examples of invalid values:

    # Invalid:
    convert_to="neuralnetwork", minimum_deployment_target=coremltools.target.iOS15
    # Invalid:
    convert_to="mlprogram", minimum_deployment_target=coremltools.target.iOS14
    
convert_tostr (optional)

Must be one of ['neuralnetwork', 'mlprogram', 'milinternal']. The value of this parameter determines the type of the model representation produced by the converter. To learn about the differences between neural networks and ML programs, see ML Programs.

  • 'neuralnetwork': Returns an MLModel (coremltools.models.MLModel) containing a NeuralNetwork proto, which is the original Core ML format. The model saved from this returned object is executable either on iOS13/macOS10.15/watchOS6/tvOS13 and above, or on iOS14/macOS11/watchOS7/tvOS14 and above, depending on the layers used in the model.

  • 'mlprogram' : Returns an MLModel (coremltools.models.MLModel) containing a MILSpec.Program proto, which is the Core ML program format. The model saved from this returned object is executable on iOS15, macOS12, watchOS8, and tvOS15.

  • 'milinternal': Returns an MIL program object (coremltools.converters.mil.Program). An MIL program is primarily used for debugging and inspection. It can be converted to an MLModel for execution by using one of the following:

    ct.convert(mil_program, convert_to="neuralnetwork")
    ct.convert(mil_program, convert_to="mlprogram")
    
  • If neither the minimum_deployment_target nor the convert_to parameter is specified, the converter produces the neural network model type with as minimum of a deployment target as possible.

compute_precisioncoremltools.precision enumeration or ct.transform.FP16ComputePrecision() (optional)

Must be one of the following.

  • coremltools.precision.FLOAT16
    • The following transform is applied:

      coremltools.transform.FP16ComputePrecision(op_selector=
                                              lambda op:True)
      

      The above transform injects cast ops to convert the float32 dtypes of intermediate tensors to float16.

  • coremltools.precision.FLOAT32
    • No transform is applied. The original float32 tensor dtype in the source model is preserved.

  • coremltools.transform.FP16ComputePrecision(op_selector=...)
    • Use the above to control which tensors are cast to float16.

    • For example:

      coremltools.transform.FP16ComputePrecision(op_selector=
                              lambda op: op.op_type != "linear")
      

      The above casts all the float32 tensors to be float16, except the input/output tensors to any linear op.

  • None
    • When convert_to="mlprogram", compute_precision parameter defaults to coremltools.precision.FLOAT16.

    • When convert_to="neuralnetwork", compute_precision parameter needs to be None and has no meaning.

skip_model_loadbool

Set to True to prevent coremltools from calling into the Core ML framework to compile and load the model, post-conversion. In that case, the returned model object cannot be used to make a prediction, but can be used to save via "model.save()". This flag may be used to convert to a newer model type on an older Mac, which if done without turning this flag on, may raise a runtime warning.

Example: Use this flag to suppress runtime warning when converting to ML program model type on a macOS 11, since ML program can only be compiled and loaded from macOS12+.

Defaults to False.

compute_units: coremltools.ComputeUnit

An enum with three possible values.

  • coremltools.ComputeUnit.ALL: Use all compute units available, including the neural engine.

  • coremltools.ComputeUnit.CPU_ONLY: Limit the model to only use the CPU.

  • coremltools.ComputeUnit.CPU_AND_GPU: Use both the CPU and GPU, but not the neural engine.

useCPUOnly: bool

Deprecated, to be removed in coremltools 6.0. Please use compute_units instead. - if True, identical to setting compute_units to coremltools.ComputeUnit.CPU_ONLY` - if False, identical to setting compute_units to coremltools.ComputeUnit.ALL`

package_dirstr

Post conversion, the model is compiled to form the MLModel object ready for prediction. This requires a temporary directory to hold the mlmodelc archive. - if not None, must be a path to a directory that is used for

temporarily storing the compiled model assets. If None, a temporary directory is created.

debugbool

This flag should generally be False except for debugging purposes Setting this flag to True:

  • For Torch conversion, it will print the list of supported and unsupported ops found in the model if conversion fails due to an unsupported op.

  • For Tensorflow conversion, it will cause to display extra logging and visualizations

Returns
modelcoremltools.models.MLModel or coremltools.converters.mil.Program

A Core ML MLModel object or MIL Program object (see convert_to).

Examples

TensorFlow 1, 2 (model is a frozen graph):

>>> with tf.Graph().as_default() as graph:
>>>     x = tf.placeholder(tf.float32, shape=(1, 2, 3), name="input")
>>>     y = tf.nn.relu(x, name="output")

Automatically infer inputs and outputs:

>>> mlmodel = ct.convert(graph)
>>> test_input = np.random.rand(1, 2, 3) - 0.5
>>> results = mlmodel.predict({"input": test_input})
>>> print(results['output'])

TensorFlow 2 (model is tf.Keras model path):

>>> x = tf.keras.Input(shape=(32,), name='input')
>>> y = tf.keras.layers.Dense(16, activation='softmax')(x)
>>> keras_model = tf.keras.Model(x, y)
>>> keras_model.save(h5_path)
>>> mlmodel = ct.convert(h5_path)
>>> test_input = np.random.rand(2, 32)
>>> results = mlmodel.predict({'input': test_input})
>>> print(results['Identity'])

PyTorch:

>>> model = torchvision.models.mobilenet_v2()
>>> model.eval()
>>> example_input = torch.rand(1, 3, 256, 256)
>>> traced_model = torch.jit.trace(model, example_input)
>>> input = ct.TensorType(name='input_name', shape=(1, 3, 256, 256))
>>> mlmodel = ct.convert(traced_model, inputs=[input])
>>> results = mlmodel.predict({"input": example_input.numpy()})
>>> print(results['1651']) # 1651 is the node name given by PyTorch's JIT

See neural-network-conversion for more advanced options.