/onnxruntime

ONNX Runtime: cross-platform, high performance scoring engine for ML models

Primary LanguageC++MIT LicenseMIT

Build Status Build Status Build Status Build Status Build Status

ONNX Runtime is a performance-focused inference engine for ONNX (Open Neural Network Exchange) models.

Models in the Tensorflow, Keras, PyTorch, scikit-learn, CoreML, and other popular supported formats can be converted to the standard ONNX format, providing framework interoperability and helping to maximize the reach of hardware optimization investments. This provides a solution for systems to integrate a single inference engine to support models trained from a variety of frameworks, while taking advantage of specific hardware accelerators where available.

ONNX Runtime was designed with a focus on performance and scalability in order to support heavy workloads in high-scale production scenarios. It also has extensibility options for compatibility with emerging hardware developments.

ONNX Runtime stays up to date with the ONNX standard and supports all operators from the ONNX v1.2+ spec and is backwards compatible with older versions. Please refer to this page for ONNX opset compatibility details.


Table of Contents


Functional Overview

Key Features

  • Cross Platform: The runtime provides a cross platform API compatible with Windows, Linux, and Mac and a variety of architectures. Both CPU and GPUs are supported, and language bindings are available for a variety of languages and architectures See more details (below). If you have specific scenarios that are not supported, please share your suggestions and scenario details via Github Issues.
  • Run any ONNX model: ONNX Runtime provides comprehensive support of the ONNX spec and can be used to run all models based on ONNX v1.2.1 and higher. Both ONNX (DNN) and ONNX-ML (traditional ML) operator sets are supported. The full set of operators and types supported is listed here. Some operators not supported in the current ONNX version may be available as a Contrib Operator.
  • Backwards Compatible: Newer versions of ONNX Runtime support all models that worked with prior versions, so updates should not break integrations. See version compatibility details here.

Performance Focused Design

High level architectural design

Using various graph optimizations and accelerators, ONNX Runtime can provide lower latency compared to other runtimes for faster end-to-end customer experiences and minimized machine utilization costs. See Performance Tuning guidance.

Supported Accelerators

The list of currently supported accelerators (termed Execution Providers) is below. Please see BUILD.md for build instructions. If you are interested in contributing a new execution provider, please see this page.

Please refer to Roadmap for a list of upcoming accelerators.

CPU

GPU

IoT/Edge/Mobile

Other

Extensibility Options


Installation

Quick Start: The ONNX-Ecosystem Docker container image is available on Dockerhub and includes ONNX Runtime (CPU, Python), dependencies, tools to convert from various frameworks, and Jupyter notebooks to help get started. Additional dockerfiles can be found here.

API Documentation

Language Supported Versions Samples
Python 3.5, 3.6, 3.7
Python Dev Notes
Samples
C# Samples
C++ Samples
C Samples
WinRT Windows.AI.MachineLearning Samples
Java 8-13 Samples
Ruby (external project) 2.4-2.7 Samples

Builds and Packages

Official builds are available for:

  • Default CPU Provider (Eigen + MLAS)
  • GPU Provider - NVIDIA CUDA
    • note: If your deployment target is Windows, the DirectML execution provider is recommended for optimal performance and compatibility with a broad set of GPUs. This will be an official package soon. In the meantime, see the build instructions at BUILD.md.

Python packages can be found on PyPi, and C#/C/C++ packages on Nuget. Please view the table on aka.ms/onnxruntime for instructions for different build combinations.

For additional build flavors and/or dockerfiles, please carefully read through BUILD.md. If you encounter problems, please provide as much information as possible when filing an issue.

For production scenarios, it's strongly recommended to build only from an official release branch.

PyPi (Python):

If using pip to download the Python binaries, run pip install --upgrade pip prior to downloading.

Nuget (C#/C/C++):

Other package repositories:

Contributed non-official packages (including Homebrew, Linuxbrew, and nixpkgs) are listed here. These are not maintained by the core ONNX Runtime team and will have limited support; use at your discretion.

System Requirements

These system requirements must be met for using the compiled binaries.

System language

  • Installation of the English language package and configuring en_US.UTF-8 locale is required, as certain operators makes use of system locales.
  • For Ubuntu, install language-pack-en package
    • Run the following commands: locale-gen en_US.UTF-8 update-locale LANG=en_US.UTF-8
    • Follow similar procedure to configure other locales on other platforms.

Default CPU

  • Requires Visual C++ 2019 runtime
  • ONNX Runtime binaries in the CPU packages use OpenMP and depend on the library being available at runtime in the system.
    • For Windows, OpenMP support comes as part of VC runtime. It is also available as redist packages: vc_redist.x64.exe and vc_redist.x86.exe
    • For Linux, the system must have libgomp.so.1 which can be installed using apt-get install libgomp1.

Default GPU (CUDA)

  • Requires Visual C++ 2019 runtime
  • The default GPU build requires CUDA runtime libraries being installed on the system:
    • Version: CUDA 10.1 and cuDNN 7.6.5
  • Version dependencies from older ONNX Runtime releases can be found in prior release notes.

Other Execution Providers

  • For requirements and dependencies of other build options, see detailed build instructions on the BUILD.md page.

Usage

Getting ONNX Models

To get an ONNX model, please view these ONNX Tutorials. ONNX Runtime supports all versions of ONNX 1.2+. Full versioning compatibility information can be found under Versioning.

Deploying ONNX Runtime

Cloud

ONNX Runtime can be deployed to the cloud for model inferencing using Azure Machine Learning Services. See detailed instructions and sample notebooks.

ONNX Runtime Server (beta) is a hosted application for serving ONNX models using ONNX Runtime, providing a REST API for prediction. Usage details can be found here, and image installation instructions are here.

IoT and edge devices

The expanding focus and selection of IoT devices with sensors and consistent signal streams introduces new opportunities to move AI workloads to the edge.

This is particularly important when there are massive volumes of incoming data/signals that may not be efficient or useful to push to the cloud due to storage or latency considerations. Consider: surveillance tapes where 99% of footage is uneventful, or real-time person detection scenarios where immediate action is required. In these scenarios, directly executing model inferencing on the target device is crucial for optimal assistance.

To deploy AI workloads to these edge devices and take advantage of hardware acceleration capabilities on the target device, see these reference implementations.

Client applications

Install or build the package you need to use in your application. Check this page for installation/package guidance. See sample implementations using the C++ API.

On newer Windows 10 devices (1809+), ONNX Runtime is available by default as part of the OS and is accessible via the Windows Machine Learning APIs. Find tutorials here for building a Windows Desktop or UWP application using WinML.

Data/Telemetry

This project may collect usage data and send it to Microsoft to help improve our products and services. See the privacy statement for more details.


Contribute

We welcome contributions! Please see the contribution guidelines.

Feedback

For any feedback or to report a bug, please file a GitHub Issue.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.


License

MIT License