AMD MIGraphX

AMD MIGraphX is AMD's graph inference engine, which accelerates machine learning model inference.

[!NOTE] The published documentation is available at MIGraphX in an organized, easy-to-read format, with search and a table of contents. The documentation source files reside in the docs folder of this repository. As with all ROCm projects, the documentation is open source. For more information on contributing to the documentation, see Contribute to ROCm documentation.

[!NOTE] You must install ROCm before installing MIGraphX.

Installing from binaries

Install binaries using:

sudo apt update && sudo apt install -y migraphx

Header files and libraries are installed under /opt/rocm-<version>, where <version> is the ROCm version.

Building from source

You have three options for building from source:

• ROCm build tool: Uses rbuild to install prerequisites, then you can build the libraries with a single command.

• CMake: Uses a script to install prerequisites, then you can use CMake to build the source.

• Docker: Builds a Docker image with all prerequisites installed, then you can build the MIGraphX sources inside a Docker container.

Build prerequisites

The following is a list of prerequisites for building MIGraphX.

• ROCm CMake modules required
• MIOpen for running on the GPU
• rocBLAS for running on the GPU
• HIP for running on the GPU
• Protobuf for reading onnx files
• Half, an IEEE 754-based half-precision floating point library
• pybind11 for python bindings
• JSON for model serialization to json string format
• MessagePack for model serialization to binary format
• SQLite3 to create database of kernels' tuning information or run queries on existing database

Installing the ROCm build tool rbuild.

1. Install rocm-cmake, pip3, rocblas, and miopen-hip:

   sudo apt install -y rocm-cmake python3-pip rocblas miopen-hip
   

2. Set up and activate python venv for rbuild:

   python3 -m venv venv_rbuild
   source venv_rbuild/bin/activate
   

3. Install rbuild in the python venv:

   pip install https://github.com/RadeonOpenCompute/rbuild/archive/master.tar.gz
   

[!NOTE] You can deactivate the python virtual environment with deactivate.

Compile using the ROCm build tool rbuild.

1. Follow instructions in installing rbuild

2. Build MIGraphX source code:

   rbuild build -d depend -B build -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*')
   

Once completed, all prerequisites are in the depend folder and MIGraphX is in the build directory.

[!NOTE] If you get an rbuild: command not found error, it's because rbuild is installed in $HOME/.local/bin, which is not in PATH. You can either export PATH as export PATH=$HOME/.local/bin:$PATH to add the folder to PATH, or add the option --prefix /usr/local in the pip3 command when installing rbuild.

Use CMake to build MIGraphX

1. Follow instructions in installing rbuild

2. Install the prerequisites:

   rbuild prepare -d depend
   

   This puts all the prerequisites are in depend the folder. They can be used in the cmake configuration as -DCMAKE_PREFIX_PATH=depend.

   If you have sudo access, as an alternative to the rbuild command, you can install the prerequisites in the same way as a Dockerfile, by calling ./tools/install_prereqs.sh.

   By default, all prerequisites are installed at the default location (/usr/local) and are accessible by all users. For the default location, sudo is required to run the script. You can also specify a different location using ./tools/install_prereqs.sh $custom_location.

3. Go to the project folder and create a build directory:

   mkdir build
   cd build
   

4. Configure CMake. If the prerequisites are installed at the default location /usr/local, use:

   CXX=/opt/rocm/llvm/bin/clang++ cmake .. -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*')
   

   Otherwise, you need to set -DCMAKE_PREFIX_PATH=$your_loc to configure CMake.

   The default build type is Release. To build MIGraphX in debug mode, pass -DCMAKE_BUILD_TYPE=Debug when configuring CMake:

   CXX=/opt/rocm/llvm/bin/clang++ cmake .. \
       -DCMAKE_BUILD_TYPE=Debug \
       -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*')
   

   For optimized binaries with debug symbols, use -DCMAKE_BUILD_TYPE=RelWithDebInfo.

5. Build MIGraphX source code:

   make -j$(nproc)
   

   You can verify this using:

   make -j$(nproc) check
   

6. Install MIGraphX libraries:

   make install
   

Use Docker

The easiest way to set up the development environment is to use Docker. ROCm's underlying drivers and libraries, known as "TheRock", now support multi-arch packaging, meaning it only installs device-code packages for the GPU architecture present on the system. Setting GPU_ARCH reduces the image size; leaving it unset installs device code for all supported architectures, which is useful when the same Docker image needs to run on different ROCm-supported GPUs.

1. With the Dockerfile, build a Docker image:

       docker build -t migraphx .
   

   or

       docker build -t migraphx --build-arg GPU_ARCH=$(rocminfo | grep -o -m1 'gfx.*') .
   

2. Enter the development environment using docker run:

       docker run --device='/dev/kfd' --device='/dev/dri' -v=`pwd`:/code/AMDMIGraphX -w /code/AMDMIGraphX --group-add video -it migraphx
   

3. In the Docker container, all required prerequisites are already installed, so you can go to the folder /code/AMDMIGraphX and follow the steps (starting from 2) in the Use CMake to build MIGraphX.

Using the MIGraphX Python module

To use MIGraphX's Python module, you can set PYTHONPATH or use the .deb package:

• Setting PYTHONPATH:

  export PYTHONPATH=/opt/rocm/lib:$PYTHONPATH
  

• Creating the deb package:

  make package
  

  This provides the path for .deb package.

  To install:

  dpkg -i <path_to_deb_file>
  

Calling MIGraphX APIs

To use MIGraphX's C/C++ API in your CMake project, you must set CMAKE_PREFIX_PATH to the MIGraphX installation location and run:

find_package(migraphx)
target_link_libraries(myApp migraphx::c)

Where myApp is the CMake target in your project.

Other Dockerfiles

The default Dockerfile builds against ROCm 7.13 and newer using TheRock (amdrocm-*) packages. To build against ROCm 7.2.x and older, use the legacy dockerfile instead:

docker build -t migraphx:legacy -f tools/docker/legacy.dockerfile .

Alternative Dockerfiles are available under tools/docker/:

• tools/docker/legacy.dockerfile — ROCm 7.2.x and older (Ubuntu 22.04); use this when building against ROCm releases that predate TheRock packages
• tools/docker/ubuntu_2404.dockerfile — Ubuntu 24.04 with ROCm 7.1.1
• tools/docker/ubuntu_2204.dockerfile — Ubuntu 22.04 with ROCm 6.4.2

To build with one of these, use the -f flag. For example:

docker build -t migraphx:2404 -f tools/docker/ubuntu_2404.dockerfile .

Then follow the same docker run and build steps described in the Use Docker section.

Building for development

Using rbuild, you can install the dependencies for development with:

rbuild develop -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*')

This installs development dependencies in the deps directory and configures cmake to use those dependencies in the build directory. You can change these directories by passing the --deps-dir and --build-dir flags to the rbuild command:

rbuild develop --build-dir build_rocm_55 --deps-dir /home/user/deps_dir

Building the documentation

HTML and PDF documentation can be built using:

cmake --build . --config Release --target doc OR make doc

This will build a local searchable web site inside the docs/html folder.

Documentation is built using Doxygen and rocm-docs-core

Run the steps below to build documentation locally. You can reuse the same venv from installing rbuild.

cd docs

pip3 install -r sphinx/requirements.txt

python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html

Depending on your setup sudo may be required for the pip install.

Formatting the code

All the code is formatted using clang-format. To format a file, use:

clang-format-10 -style=file -i <path-to-source-file>

Also, githooks can be installed to format the code per-commit:

./.githooks/install

AI Tool Use Policy

Follow the LLVM AI Tool Use Policy for contributions that use AI.