[docker, doc] feat: add Ascend NPU Dockerfiles and install guide

docker/Dockerfile.a2.npu

@@ -0,0 +1,163 @@
+FROM quay.io/ascend/cann:9.0.0-910b-ubuntu22.04-py3.12
+
+ARG PIP_INDEX_URL="https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"
+ARG ASCEND_PIP_INDEX_URL="https://mirrors.huaweicloud.com/ascend/repos/pypi"
+ARG PYTORCH_CPU_INDEX_URL="https://download.pytorch.org/whl/cpu/"
+
+ARG VLLM_REPO="https://github.com/vllm-project/vllm.git"
+ARG VLLM_REF="v0.22.0"
+
+ARG VLLM_ASCEND_REPO="https://github.com/vllm-project/vllm-ascend.git"
+ARG VLLM_ASCEND_REF="bb4d0776eee8fc45c3484a45c971a7049f1a2bbf"
+
+ARG VLLM_OMNI_REPO="https://github.com/vllm-project/vllm-omni.git"
+ARG VLLM_OMNI_REF="v0.22.0"
+
+ARG VERL_REPO="https://github.com/verl-project/verl.git"
+# Default: read from .github/verl_pin.txt at build time.
+# Override with: --build-arg VERL_REF=<commit-or-tag>
+ARG VERL_REF=""
+
+ARG VERL_OMNI_REPO="https://github.com/verl-project/verl-omni.git"
+ARG VERL_OMNI_REF="main"
+
+ARG SOC_VERSION="ascend910b1"
+ARG COMPILE_CUSTOM_KERNELS=1
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    SOC_VERSION=${SOC_VERSION} \
+    COMPILE_CUSTOM_KERNELS=${COMPILE_CUSTOM_KERNELS} \
+    TASK_QUEUE_ENABLE=1 \
+    OMP_NUM_THREADS=1 \
+    VLLM_WORKER_MULTIPROC_METHOD=spawn \
+    PATH=/usr/local/bin:/usr/local/sbin:/usr/local/Ascend/driver/tools:${PATH} \
+    LD_LIBRARY_PATH=/usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64/common:/usr/local/Ascend/driver/lib64/driver:${LD_LIBRARY_PATH}
+
+WORKDIR /workspace
+
+RUN mkdir -p /workspace/src /workspace/pins
+
+# .dockerignore only allows .github/verl_pin.txt, matching Dockerfile.cuda behavior.
+COPY .github/verl_pin.txt /workspace/pins/verl_pin.txt
+
+RUN apt-get update -y && \
+    apt-get install -y --no-install-recommends \
+        git \
+        vim \
+        wget \
+        curl \
+        ca-certificates \
+        net-tools \
+        gcc \
+        g++ \
+        cmake \
+        make \
+        build-essential \
+        numactl \
+        libnuma-dev \
+        libjemalloc2 \
+        clang-15 \
+        ninja-build && \
+    update-alternatives --install /usr/bin/clang clang /usr/bin/clang-15 20 && \
+    update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-15 20 && \
+    rm -rf /var/lib/apt/lists/*
+
+RUN python3 -m pip config set global.index-url ${PIP_INDEX_URL} && \
+    python3 -m pip config set global.trusted-host "mirrors.tuna.tsinghua.edu.cn mirrors.huaweicloud.com download.pytorch.org download-r2.pytorch.org github.com raw.githubusercontent.com files.pythonhosted.org pypi.org" && \
+    python3 -m pip install --upgrade pip setuptools wheel packaging
+
+# Match useful runtime dependencies from the official vLLM-Ascend A3 Dockerfile.
+# modelscope is useful for model download, and ray is required by distributed workloads.
+RUN python3 -m pip install \
+        modelscope \
+        'ray>=2.47.1,<=2.48.0' \
+        'protobuf>3.20.0'
+
+# Align torch stack for Ascend.
+RUN python3 -m pip install --force-reinstall \
+        torch==2.10.0+cpu \
+        torchvision==0.25.0+cpu \
+        torchaudio==2.10.0+cpu \
+        --index-url ${PYTORCH_CPU_INDEX_URL} && \
+    python3 -m pip install --force-reinstall \
+        torch-npu==2.10.0 \
+        --extra-index-url ${ASCEND_PIP_INDEX_URL} \
+        --extra-index-url ${PYTORCH_CPU_INDEX_URL}
+
+# Install vLLM.
+# Use VLLM_TARGET_DEVICE=empty so vLLM itself does not build CUDA backend.
+# Ascend backend is provided by vllm-ascend.
+RUN git clone --depth 1 -b ${VLLM_REF} ${VLLM_REPO} /workspace/src/vllm && \
+    cd /workspace/src/vllm && \
+    VLLM_TARGET_DEVICE="empty" python3 -m pip install -e ".[audio]" \
+        --extra-index-url ${PYTORCH_CPU_INDEX_URL} && \
+    python3 -m pip uninstall -y triton || true
+
+# Install vLLM-Ascend.
+RUN git clone ${VLLM_ASCEND_REPO} /workspace/src/vllm-ascend && \
+    cd /workspace/src/vllm-ascend && \
+    git checkout ${VLLM_ASCEND_REF} && \
+    git submodule update --init --recursive && \
+    export PIP_EXTRA_INDEX_URL="${ASCEND_PIP_INDEX_URL}" && \
+    export VLLM_BATCH_INVARIANT=1 && \
+    . /usr/local/Ascend/ascend-toolkit/set_env.sh && \
+    . /usr/local/Ascend/nnal/atb/set_env.sh && \
+    python3 -m pip install -e /workspace/src/vllm-ascend \
+        --extra-index-url ${ASCEND_PIP_INDEX_URL} \
+        --extra-index-url ${PYTORCH_CPU_INDEX_URL} && \
+    python3 -m pip uninstall -y triton triton-ascend || true && \
+    python3 -m pip install triton-ascend==3.2.1 \
+        --extra-index-url ${ASCEND_PIP_INDEX_URL}
+
+# Install vLLM-Omni.
+RUN git clone --depth 1 -b ${VLLM_OMNI_REF} ${VLLM_OMNI_REPO} /workspace/src/vllm-omni && \
+    cd /workspace/src/vllm-omni && \
+    VLLM_OMNI_TARGET_DEVICE=npu python3 -m pip install -e . \
+        --extra-index-url ${ASCEND_PIP_INDEX_URL} \
+        --extra-index-url ${PYTORCH_CPU_INDEX_URL}
+
+# Install verl from source.
+# If VERL_REF is empty, read the pinned commit from .github/verl_pin.txt.
+RUN VERL_REF="${VERL_REF:-$(tr -d '[:space:]' < /workspace/pins/verl_pin.txt)}" && \
+    echo "Installing verl from ${VERL_REPO}@${VERL_REF}" && \
+    git clone ${VERL_REPO} /workspace/src/verl && \
+    cd /workspace/src/verl && \
+    git checkout ${VERL_REF} && \
+    python3 -m pip install -e . \
+        --extra-index-url ${ASCEND_PIP_INDEX_URL} \
+        --extra-index-url ${PYTORCH_CPU_INDEX_URL}
+
+# Install verl-omni.
+# Do NOT install the train extra here, because train installs verl again.
+# verl has already been installed from /workspace/src/verl using .github/verl_pin.txt.
+RUN git clone --depth 1 -b ${VERL_OMNI_REF} ${VERL_OMNI_REPO} /workspace/src/verl-omni && \
+    cd /workspace/src/verl-omni && \
+    python3 -m pip install -e ".[ocr]" \
+        --extra-index-url ${ASCEND_PIP_INDEX_URL} \
+        --extra-index-url ${PYTORCH_CPU_INDEX_URL}
+
+# Re-align torch / torch-npu / numpy after dependency resolution.
+# This prevents downstream extras from upgrading torch/numpy to incompatible versions.
+RUN python3 -m pip install --force-reinstall \
+        torch==2.10.0+cpu \
+        torchvision==0.25.0+cpu \
+        torchaudio==2.10.0+cpu \
+        --index-url ${PYTORCH_CPU_INDEX_URL} && \
+    python3 -m pip install --force-reinstall \
+        torch-npu==2.10.0 \
+        --extra-index-url ${ASCEND_PIP_INDEX_URL} \
+        --extra-index-url ${PYTORCH_CPU_INDEX_URL} && \
+    python3 -m pip install --force-reinstall numpy==1.26.4
+
+
+RUN echo "export VLLM_WORKER_MULTIPROC_METHOD=spawn" >> /root/.bashrc && \
+    echo "export LD_PRELOAD=/usr/lib/$(uname -m)-linux-gnu/libjemalloc.so.2:\$LD_PRELOAD" >> /root/.bashrc && \
+    echo "export LD_LIBRARY_PATH=\$LD_LIBRARY_PATH:/usr/local/lib" >> /root/.bashrc
+
+WORKDIR /workspace
+
+ENTRYPOINT ["/bin/bash", "-c", "source /usr/local/Ascend/ascend-toolkit/set_env.sh && source /usr/local/Ascend/nnal/atb/set_env.sh && exec \"$@\"", "--"]
+CMD ["/bin/bash"]

docker/Dockerfile.a3.npu

@@ -0,0 +1,163 @@
+FROM quay.io/ascend/cann:9.0.0-a3-ubuntu22.04-py3.12
+
+ARG PIP_INDEX_URL="https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"
+ARG ASCEND_PIP_INDEX_URL="https://mirrors.huaweicloud.com/ascend/repos/pypi"
+ARG PYTORCH_CPU_INDEX_URL="https://download.pytorch.org/whl/cpu/"
+
+ARG VLLM_REPO="https://github.com/vllm-project/vllm.git"
+ARG VLLM_REF="v0.22.0"
+
+ARG VLLM_ASCEND_REPO="https://github.com/vllm-project/vllm-ascend.git"
+ARG VLLM_ASCEND_REF="bb4d0776eee8fc45c3484a45c971a7049f1a2bbf"
+
+ARG VLLM_OMNI_REPO="https://github.com/vllm-project/vllm-omni.git"
+ARG VLLM_OMNI_REF="v0.22.0"
+
+ARG VERL_REPO="https://github.com/verl-project/verl.git"
+# Default: read from .github/verl_pin.txt at build time.
+# Override with: --build-arg VERL_REF=<commit-or-tag>
+ARG VERL_REF=""
+
+ARG VERL_OMNI_REPO="https://github.com/verl-project/verl-omni.git"
+ARG VERL_OMNI_REF="main"
+
+ARG SOC_VERSION="ascend910_9391"
+ARG COMPILE_CUSTOM_KERNELS=1
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    SOC_VERSION=${SOC_VERSION} \
+    COMPILE_CUSTOM_KERNELS=${COMPILE_CUSTOM_KERNELS} \
+    TASK_QUEUE_ENABLE=1 \
+    OMP_NUM_THREADS=1 \
+    VLLM_WORKER_MULTIPROC_METHOD=spawn \
+    PATH=/usr/local/bin:/usr/local/sbin:/usr/local/Ascend/driver/tools:${PATH} \
+    LD_LIBRARY_PATH=/usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64/common:/usr/local/Ascend/driver/lib64/driver:${LD_LIBRARY_PATH}
+
+WORKDIR /workspace
+
+RUN mkdir -p /workspace/src /workspace/pins
+
+# .dockerignore only allows .github/verl_pin.txt, matching Dockerfile.cuda behavior.
+COPY .github/verl_pin.txt /workspace/pins/verl_pin.txt
+
+RUN apt-get update -y && \
+    apt-get install -y --no-install-recommends \
+        git \
+        vim \
+        wget \
+        curl \
+        ca-certificates \
+        net-tools \
+        gcc \
+        g++ \
+        cmake \
+        make \
+        build-essential \
+        numactl \
+        libnuma-dev \
+        libjemalloc2 \
+        clang-15 \
+        ninja-build && \
+    update-alternatives --install /usr/bin/clang clang /usr/bin/clang-15 20 && \
+    update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-15 20 && \
+    rm -rf /var/lib/apt/lists/*
+
+RUN python3 -m pip config set global.index-url ${PIP_INDEX_URL} && \
+    python3 -m pip config set global.trusted-host "mirrors.tuna.tsinghua.edu.cn mirrors.huaweicloud.com download.pytorch.org download-r2.pytorch.org github.com raw.githubusercontent.com files.pythonhosted.org pypi.org" && \
+    python3 -m pip install --upgrade pip setuptools wheel packaging
+
+# Match useful runtime dependencies from the official vLLM-Ascend A3 Dockerfile.
+# modelscope is useful for model download, and ray is required by distributed workloads.
+RUN python3 -m pip install \
+        modelscope \
+        'ray>=2.47.1,<=2.48.0' \
+        'protobuf>3.20.0'
+
+# Align torch stack for Ascend.
+RUN python3 -m pip install --force-reinstall \
+        torch==2.10.0+cpu \
+        torchvision==0.25.0+cpu \
+        torchaudio==2.10.0+cpu \
+        --index-url ${PYTORCH_CPU_INDEX_URL} && \
+    python3 -m pip install --force-reinstall \
+        torch-npu==2.10.0 \
+        --extra-index-url ${ASCEND_PIP_INDEX_URL} \
+        --extra-index-url ${PYTORCH_CPU_INDEX_URL}
+
+# Install vLLM.
+# Use VLLM_TARGET_DEVICE=empty so vLLM itself does not build CUDA backend.
+# Ascend backend is provided by vllm-ascend.
+RUN git clone --depth 1 -b ${VLLM_REF} ${VLLM_REPO} /workspace/src/vllm && \
+    cd /workspace/src/vllm && \
+    VLLM_TARGET_DEVICE="empty" python3 -m pip install -e ".[audio]" \
+        --extra-index-url ${PYTORCH_CPU_INDEX_URL} && \
+    python3 -m pip uninstall -y triton || true
+
+# Install vLLM-Ascend.
+RUN git clone ${VLLM_ASCEND_REPO} /workspace/src/vllm-ascend && \
+    cd /workspace/src/vllm-ascend && \
+    git checkout ${VLLM_ASCEND_REF} && \
+    git submodule update --init --recursive && \
+    export PIP_EXTRA_INDEX_URL="${ASCEND_PIP_INDEX_URL}" && \
+    export VLLM_BATCH_INVARIANT=1 && \
+    . /usr/local/Ascend/ascend-toolkit/set_env.sh && \
+    . /usr/local/Ascend/nnal/atb/set_env.sh && \
+    python3 -m pip install -e /workspace/src/vllm-ascend \
+        --extra-index-url ${ASCEND_PIP_INDEX_URL} \
+        --extra-index-url ${PYTORCH_CPU_INDEX_URL} && \
+    python3 -m pip uninstall -y triton triton-ascend || true && \
+    python3 -m pip install triton-ascend==3.2.1 \
+        --extra-index-url ${ASCEND_PIP_INDEX_URL}
+
+# Install vLLM-Omni.
+RUN git clone --depth 1 -b ${VLLM_OMNI_REF} ${VLLM_OMNI_REPO} /workspace/src/vllm-omni && \
+    cd /workspace/src/vllm-omni && \
+    VLLM_OMNI_TARGET_DEVICE=npu python3 -m pip install -e . \
+        --extra-index-url ${ASCEND_PIP_INDEX_URL} \
+        --extra-index-url ${PYTORCH_CPU_INDEX_URL}
+
+# Install verl from source.
+# If VERL_REF is empty, read the pinned commit from .github/verl_pin.txt.
+RUN VERL_REF="${VERL_REF:-$(tr -d '[:space:]' < /workspace/pins/verl_pin.txt)}" && \
+    echo "Installing verl from ${VERL_REPO}@${VERL_REF}" && \
+    git clone ${VERL_REPO} /workspace/src/verl && \
+    cd /workspace/src/verl && \
+    git checkout ${VERL_REF} && \
+    python3 -m pip install -e . \
+        --extra-index-url ${ASCEND_PIP_INDEX_URL} \
+        --extra-index-url ${PYTORCH_CPU_INDEX_URL}
+
+# Install verl-omni.
+# Do NOT install the train extra here, because train installs verl again.
+# verl has already been installed from /workspace/src/verl using .github/verl_pin.txt.
+RUN git clone --depth 1 -b ${VERL_OMNI_REF} ${VERL_OMNI_REPO} /workspace/src/verl-omni && \
+    cd /workspace/src/verl-omni && \
+    python3 -m pip install -e ".[ocr]" \
+        --extra-index-url ${ASCEND_PIP_INDEX_URL} \
+        --extra-index-url ${PYTORCH_CPU_INDEX_URL}
+
+# Re-align torch / torch-npu / numpy after dependency resolution.
+# This prevents downstream extras from upgrading torch/numpy to incompatible versions.
+RUN python3 -m pip install --force-reinstall \
+        torch==2.10.0+cpu \
+        torchvision==0.25.0+cpu \
+        torchaudio==2.10.0+cpu \
+        --index-url ${PYTORCH_CPU_INDEX_URL} && \
+    python3 -m pip install --force-reinstall \
+        torch-npu==2.10.0 \
+        --extra-index-url ${ASCEND_PIP_INDEX_URL} \
+        --extra-index-url ${PYTORCH_CPU_INDEX_URL} && \
+    python3 -m pip install --force-reinstall numpy==1.26.4
+
+
+RUN echo "export VLLM_WORKER_MULTIPROC_METHOD=spawn" >> /root/.bashrc && \
+    echo "export LD_PRELOAD=/usr/lib/$(uname -m)-linux-gnu/libjemalloc.so.2:\$LD_PRELOAD" >> /root/.bashrc && \
+    echo "export LD_LIBRARY_PATH=\$LD_LIBRARY_PATH:/usr/local/lib" >> /root/.bashrc
+
+WORKDIR /workspace
+
+ENTRYPOINT ["/bin/bash", "-c", "source /usr/local/Ascend/ascend-toolkit/set_env.sh && source /usr/local/Ascend/nnal/atb/set_env.sh && exec \"$@\"", "--"]
+CMD ["/bin/bash"]