SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsaccel-pytorch-python

accel-pytorch-python

Coding & development

View repository

Updated 10-15 20:08

About this skill

PyTorch Python Environment on Accelerator Platforms (Python layer, name never changes)

How to specialize this skill (rewrite the body at initialization time, do not change the name)

The body below is thecurrently verified instance(MUSA / Moore Threads index, 2026-09). On first initialization for another platform, rewrite according to the research conclusions from accel-init phase 3; after rewriting, this skill is the version for that platform. Machines that are already installed do not chase new repository versions.

  1. The dual-source discipline is retained (vendor source vs public source is essentially the same across platforms): change to this platform's index URL and package family table (which packages must come from the vendor source/which go through the public source/which are vendor forks).
  2. Replace the version matching matrix with actually verified rows (pip index versions --index-url 厂商源), with the query date and re-query command attached.
  3. Use verification commands and expected outputs that have been verified on this machine; mark unverified ones as (未验证)。
  4. The platform name appears only in the content; machine-local facts (env name, paths) are written in the host layer.

Current instance: Python and PyTorch on MUSA

Use this skill after the MUSA user-space Toolkit, muDNN, MCCL, and matching libmusa.so.1 are available. This skill handles Python package selection; it does not install the kernel driver.

Two package indexes

Define the indexes explicitly for each install command:

export MUSA_PIP_INDEX=https://dl.mthreads.com/repo/api/pypi/pypi/simple
export PYPI_INDEX=https://pypi.org/simple

The Moore Threads index contains both MUSA-specific wheels and many ordinary mirrored packages. The presence of a package on that index does not mean it must be installed there.

Use the Moore Threads index for packages that contain MUSA binaries or MUSA-specific patches:

Package family Installation source
torch Moore Threads index; select the MUSA-tagged wheel
torch_musa Moore Threads index; version must match torch
torchvision Prefer the matching MUSA wheel from the Moore Threads index
torchaudio Prefer the matching MUSA wheel from the Moore Threads index
triton Moore Threads Triton-MUSA wheel, despite the package name being triton
tilelang_musa Moore Threads index
mate Moore Threads index
apache-tvm-ffi Moore Threads MUSA build when required by the stack
torch-c-dlpack-ext Moore Threads MUSA build when required
liteccl_ops Moore Threads build when required
vllm_musa, flash_attn_3, flash_mla, deep-gemm, sageattention Moore Threads or project-specific MUSA build; validate exact release compatibility

The current official index has, among other examples:

torchvision 0.24.1.post1+musa5.2.0 for CPython 3.10/3.12
torchaudio 2.9.1+musa5.2.0 for CPython 3.10/3.12
triton 3.6.0 for CPython 3.10/3.12

Do not assume these versions match every torch_musa release. Query the index and use the release matrix.

Install ordinary, device-independent libraries from the public index:

transformers
accelerate
huggingface-hub
safetensors
sentencepiece
numpy, scipy, pandas
requests, packaging, filelock, fsspec
protobuf, pydantic, tqdm, psutil

The torch_musa README identifies Transformers and Accelerate as upstream repositories with MUSA support. That means the upstream Python package is the correct starting point; it does not guarantee that every model, fused kernel, or optional extension works on MUSA.

Do not use ordinary public CUDA wheels for:

torch
torch_musa
torchvision or torchaudio with compiled accelerator operators
triton
flash-attn
xformers CUDA builds
bitsandbytes
NVIDIA CUDA runtime packages
NCCL packages
CUDA-only custom extensions

Some repositories have Moore Threads forks rather than upstream support, including selected pytorch3d, pytorch_sparse, pytorch_scatter, pytorch_cluster, and Lightning branches. Install those only when the application actually requires them and follow the fork's branch/version instructions.

Never mix indexes casually

Do not make the Moore Threads index the permanent global pip index for a normal Python environment. Do not use --extra-index-url for the core accelerator install: pip may resolve an ordinary CUDA/CPU torch from another source.

Use one of these patterns.

Simple pattern

Install the exact accelerator set from the Moore Threads index, then install ordinary packages from public PyPI in a separate command:

python -m pip install \
  --index-url "$MUSA_PIP_INDEX" \
  "torch==<matching-version>" \
  "torch_musa==<matching-version>"

python -m pip install \
  --index-url "$PYPI_INDEX" \
  transformers accelerate datasets safetensors tokenizers

This allows the first command to resolve ordinary transitive dependencies from the Moore Threads mirror. Check the result with pip check.

Strict separation pattern

Use this when the environment must prove which source supplied every ordinary package:

python -m pip install --no-deps \
  --index-url "$MUSA_PIP_INDEX" \
  "torch==<matching-version>" \
  "torch_musa==<matching-version>"

python -m pip install \
  --index-url "$PYPI_INDEX" \
  filelock fsspec jinja2 networkx packaging sympy typing-extensions \
  transformers accelerate datasets safetensors tokenizers

Add the ordinary dependencies reported by pip check from the public index. Use --no-deps for additional MUSA-specific wheels when their dependency set is controlled separately.

Do not install a complete project requirements file until it has been reviewed for torch, torchvision, triton, bitsandbytes, nvidia-*, CUDA extensions, and NCCL pins. A normal CUDA requirements file can silently replace the working MUSA torch.

Select matching versions

Start with the Python ABI and MUSA SDK version:

python -V
python -m pip index versions torch --index-url "$MUSA_PIP_INDEX"
python -m pip index versions torch_musa --index-url "$MUSA_PIP_INDEX"
python -m pip index versions torchvision --index-url "$MUSA_PIP_INDEX"
python -m pip index versions torchaudio --index-url "$MUSA_PIP_INDEX"
python -m pip index versions triton --index-url "$MUSA_PIP_INDEX"

Select a complete row:

Python ABI
MUSA SDK
torch
torch_musa
triton, if needed

For the local 5.2.0 stack, the available core row to validate in a new project environment is:

Python 3.12
MUSA SDK 5.2.0
numpy 1.26.4

Do not copy this row to another SDK without checking the current wheel index.

Required environment variables

Before importing torch, configure the selected MUSA user-space stack:

export MUSA_HOME=/path/to/musa/<version>
export MUSA_INSTALL_PATH="$MUSA_HOME"
export MUSA_DRIVER_LIB_DIR=/path/to/matching/userspace/lib
export PATH="$MUSA_HOME/bin${PATH:+:$PATH}"
export LD_LIBRARY_PATH="$MUSA_DRIVER_LIB_DIR:$MUSA_HOME/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
export MUSA_VISIBLE_DEVICES=0

The matching user-space libmusa.so.1 directory must appear before Toolkit libraries. Do not use a different SDK's libmusa.so.1 just because it has the same SONAME.

Installation workflow

  1. Confirm the Python interpreter and MUSA variables.
  2. Confirm musa_version_query, musaInfo, and mccl_version.
  3. Query available MUSA wheel versions.
  4. Install exact torch and torch_musa wheels from the Moore Threads index.
  5. Install MUSA-specific add-ons from the Moore Threads index only when needed.
  6. Install ordinary libraries from public PyPI.
  7. Run pip check.
  8. Run dynamic-library and MUSA compute checks.

Keep the normal pip and compiler cache paths. On managed homogeneous servers, use filesystem symlinks from those defaults to shared storage instead of adding cache variables to every Python environment. Avoid writing build artifacts into a shared base environment.

Validation

Package metadata:

python -m pip show torch torch_musa
python -m pip check
python -m pip config list

The output must not show a public CUDA torch replacing the MUSA build. The local version usually contains a +musa... suffix.

Dynamic libraries:

TORCH_MUSA_LIB=$(printf '%s\n' "$CONDA_PREFIX"/lib/python*/site-packages/torch_musa/lib/libmusa_python.so.*)
ldd "$TORCH_MUSA_LIB" | awk '/not found/ {print}'
ldd "$CONDA_PREFIX"/lib/python*/site-packages/torch/lib/libtorch_global_deps.so | awk '/not found/ {print}'

No output is expected from either missing-library filter.

Python and device check:

python - <<'PY'
import torch
import torch_musa

print("torch:", torch.__version__)
print("torch_musa:", torch_musa.__version__)
print("torch.version.musa:", getattr(torch.version, "musa", None))
print("musa available:", torch.musa.is_available())
print("musa count:", torch.musa.device_count())
print("cuda available:", torch.cuda.is_available())

x = torch.randn(64, 64, device="musa", dtype=torch.bfloat16)
y = x @ x
torch.musa.synchronize()
print("matmul:", y.shape, y.dtype)

with torch.autocast(device_type="musa", dtype=torch.bfloat16):
    z = x @ x
torch.musa.synchronize()
print("autocast:", z.shape, z.dtype)
PY

torch.cuda.is_available() may be false in native torch_musa mode. Use torch.musa.is_available() for native MUSA code.

Distributed check:

import torch.distributed as dist
dist.init_process_group("mccl", rank=rank, world_size=world_size)

Use a small one-process test first, then a two-process torchrun all-reduce. Do not test on GPUs occupied by another job.

Common failures

No matching distribution found:

  • Check Python ABI, platform tag, and exact package name.
  • Query the Moore Threads index directly.
  • Do not fall back to a public CUDA wheel without changing the compatibility plan.

undefined symbol or libmusa.so/libmudnn.so missing:

  • Check LD_LIBRARY_PATH order.
  • Confirm all MUSA libraries come from one SDK row.
  • Run ldd on the failing extension.

NumPy 1.x/2.x warning:

  • Use the NumPy version expected by the torch wheel and compiled extensions.
  • The validated local 2.9.1 MUSA wheel uses numpy==1.26.4.

torch.musa.is_available() is false:

  • Verify user-space libraries and musaInfo first.
  • Verify that torch_musa imported and the correct libmusa.so.1 was loaded.
  • Check GPU visibility with MUSA_VISIBLE_DEVICES.

torchvision or torchaudio import fails:

  • Check that its version matches torch.
  • Prefer Moore Threads wheels or the documented Moore Threads source fork.
  • Do not use an arbitrary public CUDA wheel.

pip check reports NVIDIA/CUDA packages:

  • Inspect the requirements file that introduced them.
  • Remove CUDA-only packages and reinstall the accelerator row explicitly.