Methods for creating and using custom images - Platform For AI

Prerequisites

Alibaba Cloud account: Activate PAI and create a workspace.
ACR setup: For Enterprise Edition images, create an ACR Enterprise Edition instance with a namespace and repository.
Permissions:
- Alibaba Cloud accounts have all permissions.
- RAM users must be workspace members with assigned roles. See Manage workspace members and roles.

PAI provides two methods for adding custom images:

Method	Use case	Complexity
Import existing image	Reuse existing images	Medium—manual ACR setup required
Build new image	Create images from scratch in PAI	Low—one-stop workflow

Import existing image: Build an image locally or on ECS, push to ACR, and register in PAI.
Build new image: Configure ACR destination, runtime, and build settings in PAI console. PAI builds, pushes, and registers the image automatically.

Register an image pushed to ACR.

Procedure

Open the PAI console and select your workspace.
Navigate to AI Asset Management > Images.
On the Custom Image tab, click Register Image, and select Import Existing Image.
Configure parameters:

Register Image dialog - Import Existing Image

Parameter	Description
Image Type	Personal Edition Image: Basic container services for individual developers. Speed limits may apply. Enterprise Edition is recommended. See Announcement on usage limits for uploading and downloading images in Container Registry Personal Edition. Enterprise Edition Image: Secure hosting with efficient distribution for enterprise customers. Supports OCI artifacts including container images, Helm charts, and operators.
Enterprise Edition Instance / Namespace / Repository / Version / Custom Domain Name	Select an instance, namespace, repository, version, and custom domain name. To create these resources, go to the Container Registry console. Note Enterprise Edition Instance and Custom Domain Name are required only for Enterprise Edition images. If permission errors occur, grant `AliyunContainerRegistryReadOnlyAccess` to your RAM user. See Manage RAM user permissions.
Visibility	Visible to Me: Only you and workspace administrators can see this image. Visible to Current Workspace: All workspace members can see this image.
Chip Type	Select CPU or GPU to match your target hardware.

Build a custom image in PAI. Only Enterprise Edition images can be built.

Procedure

Open the PAI console and select your workspace.
Navigate to AI Asset Management > Images.
On the Custom Image tab, click Register Image, and select Build New Image.
Configure parameters in Basic Information:

Register Image dialog - Build New Image

Parameter	Description
Basic Information
Image Type	Only Enterprise Edition images can be built. See What is Container Registry (ACR)?.
Enterprise Edition Instance / Namespace / Repository / Custom Domain Name	Select an instance, namespace, repository, and custom domain name. To create these resources, go to the Container Registry console. Note If permission errors occur, grant `AliyunContainerRegistryReadOnlyAccess` to your RAM user. See Manage RAM user permissions.
Visibility	Visible to Me: Only you and workspace administrators can see this image. Visible to Current Workspace: All workspace members can see this image.
Chip Type	Select CPU or GPU to match your target hardware.
Runtime Information
Resources	Compute resources for the build. Use higher specifications for Dockerfiles with compilation steps.
VPC Configuration / Security Group	VPC bound to your Enterprise Edition instance and security group. Note For public internet access to download dependencies, create an Internet NAT gateway, attach an EIP, and configure SNAT rules. See Use a dedicated gateway to improve public network access speed.
Build Configuration
Build Method	Based on Existing Image: Start from an official, custom, or third-party image. Install dependencies with pip2, pip3, yum, or apt. For private repositories, provide authentication credentials. Based on Dockerfile: Write custom Dockerfile instructions. For syntax details, see Dockerfile reference.