Installation#

Prerequisites#

The current version of OpenVINO™ Training Extensions was tested in the following environment:

  • Ubuntu 20.04

  • Python >= 3.10

Install OpenVINO™ Training Extensions for users (CUDA/CPU)#

1. Install OpenVINO™ Training Extensions package:

  • A local source in development mode

pip install otx

# Clone the training_extensions repository with the following command:
git clone https://github.com/openvinotoolkit/training_extensions.git
cd training_extensions

# Set up a virtual environment.
python -m venv .otx
source .otx/bin/activate

pip install -e .

2. Install PyTorch & Requirements for training according to your system environment.

pip install '.[base]'

Note

Models from mmlab are not available for this environment. If you want to use mmlab models, you must install them with Full Requirements. Also, some tasks may not be supported by minimum requirements.

otx install -v --option full

[Optional] Refer to the torch official installation guide

Note

Currently, only torch==2.2 was fully validated. (older versions are not supported due to security issues).

3. Once the package is installed in the virtual environment, you can use full OpenVINO™ Training Extensions command line functionality.

Install OpenVINO™ Training Extensions for users (XPU devices)#

1. Install OpenVINO™ Training Extensions from source to use XPU functionality.

# Clone the training_extensions repository with the following command:
git clone https://github.com/openvinotoolkit/training_extensions.git
cd training_extensions

pip install -e '.[base]' --extra-index-url https://download.pytorch.org/whl/test/xpu

Note

Please, refer to the PyTorch official documentation guide to install prerequisites and resolve possible issues.

2. Once the package is installed in the virtual environment, you can use full OpenVINO™ Training Extensions command line functionality.

otx --help

Install OpenVINO™ Training Extensions for developers#

Install tox and create a development environment:

pip install tox
# -- need to replace '310' below if another python version needed
tox devenv venv/otx -e unit-test-py310
source venv/otx/bin/activate

Then you may change code, and all fixes will be directly applied to the editable package.

Install OpenVINO™ Training Extensions by using Docker#

1. By executing the following commands, it will build two Docker images: otx:${OTX_VERSION}-cuda and otx:${OTX_VERSION}-cuda-pretrained-ready.

git clone https://github.com/openvinotoolkit/training_extensions.git
cd docker
./build.sh

2. After that, you can check whether the images are built correctly such as

docker image ls | grep otx

Example:

otx                                           2.0.0-cuda-pretrained-ready                    4f3b5f98f97c   3 minutes ago   14.5GB
otx                                           2.0.0-cuda                                     8d14caccb29a   8 minutes ago   10.4GB

otx:${OTX_VERSION}-cuda is a minimal Docker image where OTX is installed with CUDA supports. On the other hand, otx:${OTX_VERSION}-cuda-pretrained-ready includes all the model pre-trained weights that OTX provides in addition to otx:${OTX_VERSION}-cuda.

Run tests#

To run some tests, need to have development environment on your host. The development requirements file (requirements/dev.txt) would be used to setup them.

$ otx install --option dev
$ pytest tests/

Another option to run the tests is using the testing automation tool tox. Following commands will install the tool tox to your host and run all test codes inside of tests/integration folder.

$ pip install tox
$ tox -e integration-test-all

Note

When running the tox command above first time, it will create virtual env by installing all dependencies of this project into the newly created environment for your testing before running the actual testing. So, it is expected to wait more than 10 minutes before to see the actual testing results.

Troubleshooting#

1. If you have problems when you try to use pip install command, please update pip version by following command:

python -m pip install --upgrade pip

2. If you’re facing a problem with torch or mmcv installation, please check that your CUDA version is compatible with torch version. Consider updating CUDA and CUDA drivers if needed. Check the command example to install CUDA 11.8 with drivers on Ubuntu 20.04.

3. If you have access to the Internet through the proxy server only, please use pip with proxy call as demonstrated by command below:

python -m pip install --proxy http://<usr_name>:<password>@<proxyserver_name>:<port#> <pkg_name>

4. If you’re facing a problem with CLI side of the OTX, please check the help message of the command by using --help option. If you still want to see more jsonargparse-related messages, you can set the environment variables like below.

export JSONARGPARSE_DEBUG=1 # 0: Off, 1: On