Use the PPU pip service on ACS

更新时间:
复制 MD 格式

This topic describes how to use the PTG PPU pip service and the Alibaba Cloud PPU pip service on ACS. The PTG PPU pip service requires you to apply for an authentication account and password. Packages are installed over the public network, and you must explicitly provide the credentials during installation. The Alibaba Cloud PPU pip service supports credential-free access within a VPC, so your Pods do not need internet access. This service requires some prerequisite configuration. Both services offer the same pip packages, which are identical in type, number, and name. You can choose the service that best fits your needs.

Use the Alibaba Cloud PPU pip service

Use cases

  1. Use the pip service within a VPC. This eliminates the need for public network access for your Pods, helping you meet compliance and network control requirements.

  2. Install both XPU and CPU pip packages by configuring a single pip source.

  3. Install packages without manual authentication, which aligns with the standard community experience.

  4. After completing the necessary configuration, you can use this service with all ACS PPUs.

Comparison with the PTG PPU pip service

PTG PPU pip service

Alibaba Cloud PPU pip service

Pip source index URL

An index URL in the format of https://art-pub.eng.t-head.cn/artifactory/api/pypi/ptgai-pypi_ppu_ubuntu_cu126_index/simple/

An index URL in the format of https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_cu126/simple/, which directly corresponds to the PTG version.

For detailed index URL information and mapping rules, see Alibaba Cloud PPU pip service index URLs.

Pip source authentication

Requires explicit authentication (apply as needed).

Credential-free (available after configuration).

Usage scope

Users who have applied for an account and password.

All ACS PPU users (requires configuration).

Access method

Internet access

Internet access, access within a VPC

Pre-use configuration

No additional configuration required.

Requires preliminary configuration.

Package usage

Package names, number, and installation methods are the same.

Package names, number, and installation methods are the same (only the pip source index URL needs to be replaced).

Notes

This service may be discontinued in the future.

How to use

Enable credential-free pip authorization

Important
  • Prerequisites: Before you start, check the official PPU-PIP package list provided on the Alibaba Cloud PPU website. You can only install packages from this list. For CUDA-related pip packages not on the list, we recommend building from source. For detailed steps, see Build pip packages from source.

  • Resources and billing: The credential-free authorization for pip feature deploys a three-replica stateless workload named ack-pod-identity-webhook in your cluster. The system resource requests (resources.requests) for each Pod are 100m CPU and 100 Mi Memory. You are billed for the resources used by these three Pods according to the ACS Billing Guide. To ensure that the feature functions correctly, do not remove this workload.

  1. You authorize the credential-free pip service for ACS PPU instances on a per-cluster basis. In the ACS console, navigate to the Cluster List page, find your target cluster, and click its name to go to the Cluster Information page. On the Basic Information tab, locate the Security and Audit panel and follow the instructions to enable Credential-free authorization for pip.

    image.png

    Note
    • Each time you add a credential-free authorization, a Service Account is generated for a specific cluster namespace. All Pods within that namespace can use it. To grant this access to Pods in other namespaces, you must add a new authorization for each.

    • Click Add Authorization and select the desired namespace to verify that the authorization was added and to view existing Service Accounts.

    • The underlying implementation of credential-free authorization for pip is based on Using RRSA to configure RAM permissions for a ServiceAccount to isolate Pod permissions.

  2. Generate the authorization URL and complete the authorization process in a new browser tab.image.png

  3. Note the Service Account name for the ACS cluster. You will need it for subsequent configuration.image.png

  4. After you enable credential-free authorization for the cluster, DinD, Buildah, and standard PPU Pods in the corresponding namespaces meet the prerequisites for credential-free pip access.

Use the PPU pip service

Container development environments

  1. Add the credential-free authorization field to the YAML file.

    Modify the YAML file used to create the DinD or Buildah Pod in Best practices for developing container images for ACS PPU users by adding the spec.serviceAccountName field.image.png

  2. Set up the environment and use the pip service based on your scenario.

    DinD

    1. When you start the inner PPU container, mount the necessary environment variables and files for credential-free authentication.

      # To use the pip service provided by PTG
      id=$(docker run --network host -tid --privileged {ppu-image-uri} bash)
      
      # Modify the container startup command as follows: add four ALIBABA_CLOUD* environment variables and one file mount.
      
      # To use the pip service provided by Alibaba Cloud
      id=$(docker run --network host -tid --privileged \
      -e ALIBABA_CLOUD_OIDC_PROVIDER_ARN=$ALIBABA_CLOUD_OIDC_PROVIDER_ARN \
      -e ALIBABA_CLOUD_ROLE_ARN=$ALIBABA_CLOUD_ROLE_ARN \
      -e ALIBABA_CLOUD_OIDC_TOKEN_FILE=$ALIBABA_CLOUD_OIDC_TOKEN_FILE \
      -e ALIBABA_CLOUD_STS_ENDPOINT=$ALIBABA_CLOUD_STS_ENDPOINT \
      -v /var/run/secrets/ack.alibabacloud.com/rrsa-tokens/:/var/run/secrets/ack.alibabacloud.com/rrsa-tokens/ \
      {ppu-image-uri} bash)
    2. Install the credential-free plugin inside the inner PPU container. You can then use the pip service without credentials. Compared to the pip service provided by PTG, you only need to replace the index URL in the installation command.

      # Other Linux package installation steps are omitted.
      
      # The following steps demonstrate how to install pip packages using the service provided by Alibaba Cloud.
      ## 1. First, install the credential-free plugin aiext-pypi-plugin.
      pip install aiext-pypi-plugin -i http://mirrors.cloud.aliyuncs.com/aiext-pypi/aiext-pypi-plugin/simple --trusted-host mirrors.cloud.aliyuncs.com
      
      ## 2. You can then install the required pip wheel packages without credentials. For example:
      pip install torch==2.5.1 vllm==0.7.3 -i https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_cu123/simple/
      
      ## 3. After the pip installation is complete, we recommend cleaning up the environment.
      pip uninstall -y aiext-pypi-plugin
      rm ~/.netrc   # Clean up as needed, or edit the file to remove only the content related to machine aiext-pypi.mirrors.aliyuncs.com.

    Buildah

    1. Make the necessary modifications to your Dockerfile. Install the credential-free plugin, and then you can use the pip service without credentials. Compared to the pip service provided by PTG, you only need to replace the index URL in the installation command.

      # If you use a standard image provided by ACS
      FROM egslingjun-registry.cn-wulanchabu.cr.aliyuncs.com/egslingjun/{image:tag}
      
      # Other Dockerfile steps are omitted.
      
      # The following steps demonstrate how to install pip packages using the service provided by Alibaba Cloud.
      ## 1. Set the credential-free related environment variables.
      ARG ALIBABA_CLOUD_STS_ENDPOINT
      ARG ALIBABA_CLOUD_OIDC_PROVIDER_ARN
      ARG ALIBABA_CLOUD_ROLE_ARN
      ENV ALIBABA_CLOUD_STS_ENDPOINT=${ALIBABA_CLOUD_STS_ENDPOINT}
      ENV ALIBABA_CLOUD_OIDC_PROVIDER_ARN=${ALIBABA_CLOUD_OIDC_PROVIDER_ARN}
      ENV ALIBABA_CLOUD_ROLE_ARN=${ALIBABA_CLOUD_ROLE_ARN}
      ENV ALIBABA_CLOUD_OIDC_TOKEN_FILE=/mount/rrsa-tokens/token
      
      ## 2. Install the credential-free plugin aiext-pypi-plugin. Note: The plugin currently does not support requests executed with 'python -m pip'.
      
      RUN pip install aiext-pypi-plugin -i http://mirrors.cloud.aliyuncs.com/aiext-pypi/aiext-pypi-plugin/simple --trusted-host mirrors.cloud.aliyuncs.com
      
      ## 3. Add the --mount option before each 'pip install' command. For example:
      RUN --mount=type=bind,source=/var/run/secrets/ack.alibabacloud.com/rrsa-tokens,target=/mount/rrsa-tokens \
          pip install torch==2.5.1 -i https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_cu123/simple/
      RUN --mount=type=bind,source=/var/run/secrets/ack.alibabacloud.com/rrsa-tokens,target=/mount/rrsa-tokens \
         pip install vllm==0.7.3 -i https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_cu123/simple/
      
      ## 4. After the pip installation is complete, we recommend cleaning up the environment.
      RUN pip uninstall -y aiext-pypi-plugin
    2. Add the four ALIBABA_CLOUD* build arguments to the buildah build command in the Buildah Pod. Modify the command as follows:

      # To use the pip service provided by PTG
      buildah --storage-driver=overlay build --no-cache -t test:v1 .
      
      # Modify the command as follows, adding four ALIBABA_CLOUD* build arguments:
      
      # To use the pip service provided by Alibaba Cloud
      buildah --storage-driver=overlay build --no-cache \
      --build-arg ALIBABA_CLOUD_OIDC_PROVIDER_ARN=$ALIBABA_CLOUD_OIDC_PROVIDER_ARN \
      --build-arg ALIBABA_CLOUD_ROLE_ARN=$ALIBABA_CLOUD_ROLE_ARN \
      --build-arg ALIBABA_CLOUD_STS_ENDPOINT=$ALIBABA_CLOUD_STS_ENDPOINT \
      -t demo:v1 .

Standard PPU containers

Note

You can find and use an AI container image from the ACS Container Image Release Notes to directly launch a PPU container. This type of container is suitable for one-time task environments. After the task is complete, the container Pod exits automatically, and any changes to its environment are lost.

  1. Add the credential-free authorization field to the YAML file.

    Modify the YAML file used to create the PPU Pod by adding the spec.serviceAccountName field.image.png

  2. Set up the environment and use the pip service inside the standard PPU container.

    # 1. First, install the credential-free plugin aiext-pypi-plugin. Note: The plugin currently does not support requests executed with 'python -m pip'.
    pip install aiext-pypi-plugin -i http://mirrors.cloud.aliyuncs.com/aiext-pypi/aiext-pypi-plugin/simple --trusted-host mirrors.cloud.aliyuncs.com
    
    # 2. You can then install the required pip wheel packages without credentials. For example:
    pip install torch==2.5.1 vllm==0.7.3 -i https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_cu123/simple/

Alibaba Cloud PPU pip service index URLs

The index URLs for the Alibaba Cloud PPU pip service map directly to those of the PTG PPU pip service. The mapping rules are shown in the table below.

Both sets of index URLs provide identical package content.

Alibaba Cloud index URL

PTG index URL

OS-bound index URL

(v1.5.3 and earlier)

Format: https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_<cuda-version>/simple/

Example:

  • https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_cu128/simple/

  • https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_cu129/simple/

Format: https://art-pub.eng.t-head.cn/artifactory/api/pypi/ptgai-pypi_ppu_ubuntu_<cuda-version>_index/simple/

Example:

  • https://art-pub.eng.t-head.cn/artifactory/api/pypi/ptgai-pypi_ppu_ubuntu_cu128_index/simple/

  • https://art-pub.eng.t-head.cn/artifactory/api/pypi/ptgai-pypi_ppu_ubuntu_cu129_index/simple/

OS-free mode index URL

(Introduced in v1.6.x)

Format: https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/<cuda-version>/simple/

Example:

  • https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/cu128/simple/

  • https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/cu129/simple/

Format: https://art-pub.eng.t-head.cn/artifactory/api/pypi/<cuda-version>_index/simple/

Example:

  • https://art-pub.eng.t-head.cn/artifactory/api/pypi/cu128_index/simple/

  • https://art-pub.eng.t-head.cn/artifactory/api/pypi/cu129_index/simple/

OS/CUDA-free mode index URL

(Introduced in v1.7.x)

Fixed URL: https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/pypi_index/simple/

Fixed URL: https://art-pub.eng.t-head.cn/artifactory/api/pypi/pypi_index/simple/

Use the PTG PPU pip service

Use cases

  1. The PTG pip service can only be accessed over the public network.

  2. Before use, you must request authentication credentials for the pip source from your PDSA.

PPU pip

  • The PPU pip source provides frameworks that are suitable for PPU products and open-source libraries that are recompiled based on the PPU SDK, which helps you quickly set up a production environment. If a package you need is not available from the PPU pip source, it is pulled from the official PyPI source by default.

  • The PPU-PIP package list is updated monthly. Optimized Edition packages contain code that has been modified and performance-tuned for PPU. Community Edition packages are open-source libraries and frameworks that are compiled on the PPU SDK.

PPU pip naming conventions

Index URLs for v1.5.3 and earlier

For v1.5.3 and earlier, the naming convention for the Python Package Index base URL of the PPU pip source is: {index-prefix}_{os}_{cuda}_{index-suffix}. The fields are described below:

Component

Value

Description

index-perfix component

Fixed value: https://art-pub.eng.t-head.cn/artifactory/api/pypi/ptgai-pypi_ppu

os component

Enumerated values: ubuntu, alios, etc. (does not distinguish specific OS versions)

Only Ubuntu images are available in ACS scenarios.

cuda component

Enumerated values: cu126, cu124, cu123, etc. For more information, see the PPU-PIP package list.

index-suffix component

Fixed value: index/simple/

The following are examples of complete Python Package Index base URLs:

  • https://art-pub.eng.t-head.cn/artifactory/api/pypi/ptgai-pypi_ppu_ubuntu_cu126_index/simple/

  • https://art-pub.eng.t-head.cn/artifactory/api/pypi/ptgai-pypi_ppu_ubuntu_cu124_index/simple/

OS-free mode index URLs (v1.6.x)

For the OS-free mode introduced in v1.6.x, the naming convention for the Python Package Index base URL of the PPU pip source is: {os-free-index-prefix}{cuda}{os-free-index-suffix}. The fields are described below:

Component

Value

os-free-index-prefix component

Fixed value: https://art-pub.eng.t-head.cn/artifactory/api/pypi/

cuda component

Enumerated values: cu128, cu126, cuda124, etc. For more information, see the PPU-PIP package list.

os-free-index-suffix component

Fixed value: _index/simple/

Note
  • Packages in OS-free mode are OS-agnostic, so you do not need to specify an OS in the source address.

  • You can still install the new OS-free mode packages by using the older, OS-bound index URLs.

The following are examples of complete OS-free Python Package Index base URLs:

  • https://art-pub.eng.t-head.cn/artifactory/api/pypi/cu128_index/simple/

  • https://art-pub.eng.t-head.cn/artifactory/api/pypi/cu126_index/simple/

OS/CUDA-free mode index URLs (v1.7.x)

For the OS/CUDA-free mode introduced in v1.7.x, the Python Package Index base URL for the PPU pip source is fixed as:

https://art-pub.eng.t-head.cn/artifactory/api/pypi/pypi_index/simple/
Note
  • During installation, OS/CUDA-free mode packages automatically detect the environment's OS, CUDA, Torch, and Python versions to select the appropriate package.

  • The new OS/CUDA-free mode pip packages can still be installed by using the index URLs from the previous OS-free mode (introduced in v1.6.x) and OS-bound mode (v1.5.3 and earlier).

PPU pip package installation

The following example, flash-attn==2.4.3+ppu1.5.2.ce, explains the PPU pip package naming convention:

Component

2.4.3

+ppu1.5.2

.ce

Field description

Software version

Release version

ce/oe field

  • ce: Community Edition

  • oe: Optimized Edition

For the flash-attn==2.4.3+ppu1.5.2.ce package, you can omit the software version, release version, and ce/oe fields. This allows for four theoretical installation methods.

Important

You must choose based on the specific list and version information that is published in the pip list, as not every combination corresponds to an available package.

pip install flash-attn==2.4.3+ppu1.5.2.ce 
pip install flash-attn==2.4.3+ppu1.5.2     # If ce/oe is omitted, pip tries to install the Optimized Edition, then falls back to the Community Edition.
## The following two methods are recommended:
pip install flash-attn==2.4.3              # Release version omitted: By default, the latest build of this version on the pip source is installed.
pip install flash-attn                     # Software version omitted: By default, the latest version is installed.

Examples

The following are complete examples of pip package installation commands:

pip install sglang==0.4.6.post1+ppu1.5.1 -i https://art-pub.eng.t-head.cn/artifactory/api/pypi/ptgai-pypi_ppu_ubuntu_cu126_index/simple/
pip install vllm==0.6.6.post1+ppu1.5.1 -i https://art-pub.eng.t-head.cn/artifactory/api/pypi/ptgai-pypi_ppu_ubuntu_cu126_index/simple/
pip install mmdet3d==1.4.0 -i https://art-pub.eng.t-head.cn/artifactory/api/pypi/ptgai-pypi_ppu_ubuntu_cu126_index/simple/
Note

If you are using the Alibaba Cloud PPU pip service, you only need to replace the index URL in the commands above with https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_cu126/simple/.

Troubleshooting

If you encounter a pip source hash value error, use the --no-cache option to resolve the issue.

image.png

# If you encounter a pip source hash mismatch error, add the --no-cache-dir option.
pip install --no-cache-dir torch==2.1.2+ppu1.5.2

# Alternatively, clear the entire pip cache on your system before you reinstall.
pip cache purge
pip install torch==2.1.2+ppu1.5.2

Appendix

Pip configuration file

The pip.config file requires different configurations for the Alibaba Cloud and PTG pip services. Use the configuration that matches your service.

AI container images (v25.07 and earlier)

Note

AI container images v25.07 and earlier have a built-in PIP_INDEX_URL=http://mirrors.cloud.aliyuncs.com/pypi/simple/ environment variable. By default, this overrides any new settings in the pip.config file. Keep the following in mind:

  • If you run the pip install command without the -i <index-url> option, an environment variable overrides the settings in the pip.config configuration file and causes an incorrect Index URL to be used. To ensure that you can properly use the pip service provided by Alibaba Cloud and the pip service provided by PTG, you need to run the unset PIP_INDEX_URL or export PIP_INDEX_URL= command to disable this environment variable.

  • If you explicitly specify the -i <index-url> option when you run the pip install command, the operation is not affected.

Alibaba Cloud pip service

The Alibaba Cloud pip service provides a one-stop solution for installing PPU-related CUDA pip packages and non-CUDA pip packages from the PyPI community. Before you begin, you must complete the "Enable credential-free authorization for pip" setup as described in the previous sections. This allows you to install all pip packages from a single pip source.

The following is the recommended configuration file for the pip service provided by Alibaba Cloud. You can use it to replace the default configuration file for the image. This allows you to install pip packages without adding the -i <index-url> option.

Note

Set <cuda-version> in the configuration file to the CUDA version of your container image, which you can find by running the nvcc --version command. Valid values include cu126, cu124, and cu123.

[global]
index-url = https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_<cuda-version>/simple/
# For example: index-url = https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_cu126/simple/

[install]
trusted-host = aiext-pypi.mirrors.aliyuncs.com

PTG pip service

The PTG pip service provides a one-stop solution for installing PPU-related CUDA pip packages and non-CUDA pip packages from the PyPI community. Before you begin, you must obtain the account and password for the PTG pip service from your PDSA. This allows you to install all pip packages from a single pip source.

The following is the recommended configuration file for the pip service provided by PTG, which can replace the default configuration file in an image. With this configuration file, you can install pip packages without adding the -i <index-url> option.

Note

In the following configuration file, set <cuda-version> to the CUDA version of your container image, which you can check by running the nvcc --version command. Valid values include cu126, cu124, and cu123.

[global]
index-url = https://art-pub.eng.t-head.cn/artifactory/api/pypi/ptgai-pypi_ppu_ubuntu_<cuda-version>_index/simple/
# For example: index-url = https://art-pub.eng.t-head.cn/artifactory/api/pypi/ptgai-pypi_ppu_ubuntu_cu126_index/simple/

[install]
trusted-host = art-pub.eng.t-head.cn mirrors.cloud.aliyuncs.com

AI container images (v25.08 and later)

AI container images v25.08 and later have built-in configuration files for both the Alibaba Cloud pip service and the PTG pip service. You can switch between configurations by modifying a symbolic link.

# Use the pip service provided by Alibaba Cloud in AI container images v25.08 and later (this is the default configuration in the image, so no action is needed).
## If you are switching from the PTG service to the Alibaba Cloud service, you must first remove the pip.config symbolic link (rm ~/.pip/pip.config).
ln -s ~/.pip/pip.config.aiext-pypi ~/.pip/pip.config

# Use the pip service provided by PTG in AI container images v25.08 and later.
ln -s ~/.pip/pip.config.art-pub ~/.pip/pip.config

Configure a .netrc file for automatic authentication

To avoid the inconvenience of entering your PTG pip credentials for each installation, you can use a .netrc file for automatic authentication.

# PIP .netrc
cat > ~/.netrc << EOF
machine art-pub.eng.t-head.cn
login <pip-username>
password <pip-passwd>
EOF
Note
  • AI container images v25.07 and earlier use a mix of two sources: mirrors.cloud.aliyuncs.com (which does not require credentials and is used for non-CUDA pip packages) and art-pub.eng.t-head.cn (which requires credentials and is used for PPU versions of CUDA-related pip packages). You can continue to use them as before or modify the configuration as recommended in this document.

  • AI container images from version 25.08 onward include two built-in pip.config configuration files. You can switch between these files based on the specific pip service that you use.

Because the ~/.netrc file contains your username and password in plain text, set its permissions to 600 (read/write for owner only). We also recommend that you delete this file after use.