Installation with Ascend NPU (x86)

Installation with Ascend NPU (x86)#

Required Environment#

CANN == 8.3.RC1

Prepare CANN#

Choose one of the following methods to use CANN:

  1. Install CANN according to the official documentation

  2. Download and use the CANN image

Install with uv or pip#

UV#

Recommend to use uv for faster and easier installation.

git clone https://github.com/ByteDance-Seed/VeOmni.git
cd VeOmni

# use the locked uv env
uv sync --locked  --extra npu
source .venv/bin/activate

You can use --extra to install other optional dependencies. Refer to pyproject.toml for more details.

# eg. install with video/audio processing dependencies (torchcodec, PyAV, librosa, soundfile)
# Note: `video` and `audio` extras are equivalent - both include video and audio processing
uv sync --locked  --extra npu --extra video
# or equivalently:
uv sync --locked  --extra npu --extra audio

Note: For video/audio processing with the video or audio extra, you also need to install ffmpeg separately:

# Ubuntu/Debian/openEuler
sudo apt-get install ffmpeg
# or
sudo yum install ffmpeg

Pip#

git clone https://github.com/ByteDance-Seed/VeOmni.git
cd VeOmni

# Choose one of the following installation options based on your needs:
# Option 1: Stable version (transformers < 5.0)
pip install -e .[npu,transformers-stable]

# Option 2: Experimental version for new models (transformers ≥ 5.0)
# Note: This uses the transformers5-exp extra which includes transformers 5.0+ support
# as specified in pyproject.toml (experimental and under development)
# pip install -e .[npu,transformers5-exp]

Set up CANN environment before installing torchcodec#

Make sure CANN_path is set to your CANN installation directory, e.g., export CANN_path=/usr/local/Ascend

source $CANN_path/ascend-toolkit/set_env.sh

# Add chunkloss feature
export VEOMNI_ENABLE_CHUNK_LOSS=1

Video/Audio Processing Dependencies (Optional)#

For video/audio processing capabilities, you need to install torchcodec separately. Follow these steps:

# Clone the torchcodec repository
cd ..
git clone https://github.com/meta-pytorch/torchcodec.git
cd torchcodec

# Checkout to a specific version for compatibility
git checkout v0.5.0

# Copy the installation script to the torchcodec source directory
cp ../VeOmni/docs/get_started/installation/install_torchcodec_Ascend.sh .

# Note: Ensure Python is installed as a shared library (required for compiling C++ extensions)
# The installation script will automatically verify this requirement

# Run the installation script (replace with your actual CANN path)
bash install_torchcodec_Ascend.sh $CANN_path/ascend-toolkit/set_env.sh

# Verify installation
pip show torchcodec

# Test torchcodec import
python -c "from torchcodec.decoders import VideoDecoder; print('Success')"
# If the terminal outputs'Success', it indicates that the torchcodec installation was successful. If an error message is output, it indicates that the installation was not successful