coremltools

This documentation describes an old version. See the newest version.

Core ML is an Apple framework that allows developers to easily integrate machine learning (ML) models into apps. Core ML is available on iOS, iPadOS, watchOS, macOS, and tvOS. Core ML introduces a public file format (.mlmodel) for a broad set of ML methods including deep neural networks (convolutional and recurrent), tree ensembles (boosted trees, random forest, decision trees), and generalized linear models. Core ML models can be directly integrated into apps within Xcode.

coremltools is a Python package that can be used to:

  • Convert trained models from popular machine learning tools into Core ML format (.mlmodel).
  • Write models to Core ML format with a simple API.
  • Making predictions using the Core ML framework (on select platforms) to verify conversion.

Installation

coremltools has the following dependencies:

  • numpy (1.12.1+)
  • protobuf (3.1.0+)

In addition, it has the following soft dependencies that are only needed when you are converting models of these formats:

  • Keras (1.2.2, 2.0.4+) with TensorFlow (1.0+)
  • XGBoost (0.6+)
  • scikit-learn (0.15+)
  • LIBSVM

The method for installing coremltools follows the standard python package installation steps. Once you have set up a python environment, run:

pip install --upgrade coremltools

to install coremltools.

Model Conversion

coremltools easily converts trained models from existing libraries. The following example shows how to convert a Caffe model (AlexNet) to Core ML format (.mlmodel).

Supporting files: bvlc_alexnet.caffemodel, deploy.prototxt, class_labels.txt.

import coremltools

# Convert a Caffe model to a classifier in Core ML
coreml_model = coremltools.converters.caffe.convert(
    ('bvlc_alexnet.caffemodel', 'deploy.prototxt'), predicted_feature_name='class_labels.txt'
)

# Now save the model
coreml_model.save('BVLCObjectClassifier.mlmodel')

Here is another example with scikit-learn:

from sklearn.linear_model import LinearRegression
import pandas as pd

# Load data
data = pd.read_csv('houses.csv')

# Train a model
model = LinearRegression()
model.fit(data[["bedroom", "bath", "size"]], data["price"])

# Convert and save the scikit-learn model
import coremltools

coreml_model = coremltools.converters.sklearn.convert(model, ["bedroom", "bath", "size"], "price")

Model Interface

After conversion, you might want to edit the model metadata to make your model easier to consume in Xcode. The license, author, and other metadata get surfaced in the Xcode UI while the input and output descriptions are surfaced as comments in the code generated by Xcode for the model consumer.

# Set model metadata
model.author = 'John Smith'
model.license = 'BSD'
model.short_description = 'Predicts the price of a house in the Seattle area.'

# Set feature descriptions manually
model.input_description['bedroom'] = 'Number of bedrooms'
model.input_description['bathrooms'] = 'Number of bathrooms'
model.input_description['size'] = 'Size (in square feet)'

# Set the output descriptions
model.output_description['price'] = 'Price of the house'

# Save the model
model.save('HousePricer.mlmodel')

Model Evaluation

After conversion, you might want to verify that the predictions made by Core ML match up with the source framework. To facilitate programmatic verification of the conversion, we provide a way for you to easily evaluate Core ML models.

Here is an example using making predictions using the HousePricer.mlmodel that we converted in the previous example:

import coremltools

# Load the model
model = coremltools.models.MLModel('HousePricer.mlmodel')

# Make predictions
predictions = model.predict({'bedroom': 1.0, 'bath': 1.0, 'size': 1240})

Conversion Support

Core ML supports conversion of trained models from a variety of training tools for integration into apps. The following table lists supported tool packages by model type:

Model Family Supported Packages
Neural Networks Keras (1.2.2, 2.0.4+), Caffe (1.0)
Tree Ensembles XGBoost (0.6), scikit-learn (0.18.1)
Generalized Linear Models scikit-learn (0.18.1)
Support Vector Machines LIBSVM (3.22), scikit-learn (0.18.1)
Feature Engineering scikit-learn (0.18.1)
Pipelines scikit-learn (0.18.1)

Model Visualization

Core ML supports visualizing a converted model. This can be used to see all the building blocks of the model.

Here is an example of visualizing the HousePricer.mlmodel:

import coremltools

# Load the model
model = coremltools.models.MLModel('HousePricer.mlmodel')

# Visualize the model
model.visualize_spec()

Model Specification

A key component of Core ML is the public specification for representing machine learning models. This specification is defined in protobuf and can be created using any language supported by protobuf (e.g., Python, C++, Java, C#, Perl, etc.).

At a high level, the protobuf specification consists of:

  • Model description: Encodes names and type information of the inputs and outputs to the model.
  • Model parameters: The set of parameters required to represent a specific instance of the model.
  • Metadata: Information about the origin, license, and author of the model.

For more information, please take a look at the Core ML model specification.

External Tools

In addition to the conversion tools in this package, TensorFlow, MXNet and ONNX have their own conversion tools: