coremltools

Core ML is an Apple framework that allows developers to easily integrate machine learning (ML) models into apps. Core ML is availiable on iOS, 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 directly integrate into apps within Xcode.

coremltools is a Python package that can be used to:

  • Convert trained models from popular machine learning tools (including Keras, Caffe, scikit-learn, libsvm, and XGBoost) 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.0+) with Tensorflow (1.0.x, 1.1.x)
  • 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 -U coremltools

to install coremltools.

Model Conversion

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

Supporing 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
coreml_model.author = 'John Smith'
coreml_model.license = 'BSD'
coreml_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 programatic 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.0+), 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 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.