Todos os produtos
Search
Central de documentação

MaxCompute:Custom images

Última atualização: Jun 27, 2026

UDFs em SQL e Python do MaxCompute, tarefas PyODPS e jobs MaxFrame frequentemente exigem pacotes de terceiros ou dependências no nível do sistema. As imagens personalizadas permitem empacotar essas dependências em uma imagem de contêiner docker e utilizá-la como um ambiente de execução autossuficiente.

Casos de uso comuns:

  • Instale versões específicas de bibliotecas Python, como NumPy, pandas ou scikit-learn, para a lógica da UDF.

  • Adicionar pacotes de sistema indisponíveis no runtime padrão do MaxCompute.

  • Padronizar um ambiente de desenvolvimento compartilhado entre equipes.

Limites

Item

Limite

Tamanho da imagem

10 GB por imagem

Imagens por tenant

10

Edição do Container Registry (ACR)

Apenas ACR Enterprise Edition (instâncias Standard ou Premium Edition). A Personal Edition não é compatível.

Arquitetura de CPU

Somente x86_64. As arquiteturas macOS série M e ARM não são compatíveis.

Compatibilidade de SO

O ambiente de execução de jobs do MaxCompute baseia-se no CentOS 7. Todos os pacotes na imagem devem ser compatíveis com o CentOS 7.

Diretórios reservados

Não coloque arquivos em /home/admin, /usr/local/lib, /usr/ali ou /apsara. O MaxCompute monta seu ambiente de execução nesses diretórios durante a inicialização do contêiner, sobrescrevendo qualquer conteúdo existente.

Imagens por job

Cada job de desenvolvimento pode especificar apenas uma imagem. Caso contrário, podem ocorrer conflitos de imagem.

Pré-requisitos

Uma conta Alibaba Cloud possui as permissões necessárias por padrão. Se você utilizar um usuário RAM, conceda as seguintes permissões antes de prosseguir.

Escopo da permissão

Política necessária

Referência

Acesso de leitura à função RAM

AliyunRAMReadOnlyAccess

Grant permissions to a RAM user

Operações do ACR

AliyunContainerRegistryFullAccess

Authorize a RAM user for ACR

Operações de imagem personalizada do MaxCompute

Política personalizada via RAM

RAM permissions for MaxCompute

Etapa 1: Instale o docker

Etapa 2: Crie uma imagem personalizada

Crie uma imagem personalizada a partir de uma das imagens base do MaxCompute usando um Dockerfile.

Imagens base

O MaxCompute fornece duas imagens base:

Imagem base

Endereço

Observações

CentOS

registry.cn-zhangjiakou.aliyuncs.com/maxcompute_image/base_image:latest

Fornece Python 3.7, Python 3.11, pip e yum. A source do yum está configurada para usar o endereço de espelho do Alibaba Cloud CentOS 7.

Ubuntu 20.04

registry.cn-zhangjiakou.aliyuncs.com/maxcompute_image/ubuntu_20.04:latest

--

Crie e compile a imagem

  1. Crie um Dockerfile.

       vim DockerFile
  2. Adicione o seguinte conteúdo ao Dockerfile:

       # Use the MaxCompute CentOS base image
       FROM registry.cn-zhangjiakou.aliyuncs.com/maxcompute_image/base_image:latest
    
       # If you use the Ubuntu image, replace the image address with registry.cn-zhangjiakou.aliyuncs.com/maxcompute_image/ubuntu_20.04:latest
    
       # Install system dependencies
       RUN yum install vi -y
    
       # Install third-party libraries
       RUN /usr/ali/python3.7/bin/python3 -m pip install --no-cache-dir pandas
  3. Compile a imagem.

    • image_name: O nome da imagem personalizada.

    • tag: A versão da imagem personalizada.

       sudo docker build -f DockerFile -t <image_name>:<tag> .

Etapa 3: Enviar a imagem para o ACR

Faça o upload da imagem personalizada para um repositório do ACR Enterprise Edition.

Crie uma instância do ACR Enterprise Edition

  1. Faça login no console do Container Registry e selecione uma região no canto superior esquerdo.

  2. No painel de navegação à esquerda, selecione Instances.

  3. Na página Instances, clique em Create ACR EE. Se já tiver criado uma instância, pule esta etapa.

    Importante

    Envie imagens personalizadas apenas para instâncias Standard Edition ou Premium Edition do ACR Enterprise Edition.

Crie um repositório

  1. Na página Instances, localize a instância Enterprise Edition desejada e clique em Gerencie para abrir a página de visão geral da instância.

  2. No painel de navegação à esquerda, selecione Repository > Repositories.

  3. Na página Repository > Repositories, clique em Create Repository. Na caixa de diálogo Create Repository, insira as informações abaixo e clique em Next.

    Parâmetro

    Obrigatório

    Descrição

    Region

    Sim

    A região da instância atual é selecionada automaticamente.

    Namespace

    Sim

    Namespace do repositório de imagens. Este parâmetro não pode ser modificado após a definição. Crie um namespace correspondente a uma empresa, organização ou usuário individual, como Aliyun. Não crie um namespace correspondente a um módulo ou sistema, como Tomcat, CentOS, um aplicativo ou um módulo.

    Repository Name

    Sim

    O nome deve ter entre 2 e 120 caracteres e pode conter letras minúsculas, dígitos e separadores. Os separadores podem ser sublinhados (_), hífens (-), pontos (.) e barras (/). Um separador não pode ser o primeiro ou o último caractere.

    Repository Type

    Não

    Para fazer pull de uma imagem pública, faça login na instância Enterprise Edition. Para permitir pulls anônimos, ative os pulls anônimos na instância. Para fazer pull de uma imagem privada de uma instância Enterprise Edition, faça login na instância e tenha a permissão de pull. O valor padrão é Private.

    Tags

    Não

    Quando selecionado, todas as tags exceto a mais recente no repositório não podem ser sobrescritas, garantindo a consistência das imagens de contêiner.

    Accelerated Image

    Não

    Quando selecionado, todas as imagens no repositório geram automaticamente imagens aceleradas com o sufixo "_accelerated". Full Mode: Oferece um efeito de aceleração significativo. O tamanho de uma imagem acelerada é aproximadamente 130% do tamanho da imagem original. O sistema leva cerca de 25 segundos para gerar uma imagem acelerada de 1 GB. Se uma camada de imagem acelerada já foi gerada para uma camada de imagem, o sistema não gera novamente a camada acelerada para essa mesma camada. Index-only Mode (Public Preview): Fornece cerca de 70% do efeito de aceleração do modo completo. O tamanho da imagem acelerada é cerca de 3% do tamanho da imagem original. Leva aproximadamente 3 segundos para gerar uma imagem acelerada de 1 GB. Camadas de imagem para as quais um índice já foi gerado não são geradas novamente.

    Summary

    Sim

    Máximo de 100 caracteres.

    Description

    Não

    Suporta formato Markdown.

  4. Configure a source do código:

    Para Code Source, selecione Local Repository e clique em Create Repository.

Fazer upload da imagem

  1. Na página Repository Repositories, clique em Gerencie na coluna Actions do repositório alvo.

  2. No painel de navegação à esquerda, selecione Details.

  3. Siga as instruções em Instructions on Images na parte inferior da página Details para enviar uma imagem personalizada do seu ambiente docker para o repositório de imagens do Container Registry.

  4. (Opcional) Se sua máquina estiver em uma VPC, execute as seguintes etapas:

    1. Configure o acesso à VPC para a instância Enterprise Edition. Para mais informações, consulte Configure access over a VPC.

    2. Ao realizar operações na instância do ACR Enterprise Edition no seu ambiente docker, adicione vpc ao nome de domínio. Por exemplo, altere acr-test-registry.cn-wulanchabu.cr.aliyuncs.com para acr-test-registry-vpc.cn-wulanchabu.cr.aliyuncs.com no comando a seguir:

      $ docker login --username=***@test.aliyunid.com acr-test-registry.cn-wulanchabu.cr.aliyuncs.com
    Nota

    Se ocorrer um erro ao fazer login na instância, verifique se o acesso à rede pública está ativado para o repositório.

Etapa 4: Registrar a imagem no MaxCompute

Associe uma imagem do ACR ao MaxCompute para gerenciar suas imagens de desenvolvimento.

  1. Faça login no console do MaxCompute e selecione uma região no canto superior esquerdo.

  2. No painel de navegação à esquerda, escolha Manage Configurations > Images .

  3. Na página Images, clique na aba Custom Image.

  4. Na aba Custom Image, clique em Create Image. Na caixa de diálogo Add Image, configure os seguintes parâmetros:

    Nota

    Ao criar uma imagem pela primeira vez, a caixa de diálogo MaxCompute Service Linked Role aparece. Clique em OK para criar automaticamente uma função vinculada ao serviço e acessar recursos do ACR.

  5. Na caixa de diálogo Add Image, configure os seguintes parâmetros:

    Parâmetro

    Descrição

    Image Name

    Obrigatório. Nome da imagem personalizada. O nome da imagem deve começar com uma letra minúscula e pode conter apenas letras minúsculas, dígitos, hífens (-) e sublinhados (_). Este nome é usado no desenvolvimento com MaxCompute SQL, PyODPS e MaxFrame.

    Image Type

    Obrigatório. Tipo da imagem ACR. Apenas imagens do ACR Enterprise Edition são compatíveis.

    Enterprise Edition Image Instance

    Obrigatório. Selecione a instância de imagem Enterprise Edition criada no ACR.

    Image Namespace

    Obrigatório. Selecione o namespace de imagem Enterprise Edition criado no ACR.

    Image Repository

    Obrigatório. Selecione o repositório de imagens Enterprise Edition criado no ACR.

    Image Version

    Obrigatório. Selecione a versão da imagem enviada para o ACR.

    Image Description

    Opcional. Adicione uma descrição para a imagem.

  6. Clique em OK. A nova imagem personalizada aparecerá na lista de imagens personalizadas.

Etapa 5: Usar a imagem personalizada

Após registrar a imagem, referencie-a em UDFs do MaxCompute SQL, PyODPS ou jobs MaxFrame.

Importante

Cada job de desenvolvimento pode especificar apenas uma imagem. Caso contrário, podem ocorrer conflitos de imagem.

Desenvolvimento de UDF

Especifique a imagem e a versão do Python no nível da sessão SQL usando flags:

set odps.sql.python.version=cp37;
set odps.session.image = <image_name>;

Desenvolvimento com PyODPS

Especifique a imagem usando o parâmetro image do método execute ou persist:

image='<image_name>'
Nota

Para referenciar uma imagem no desenvolvimento com PyODPS, atualize o PyODPS para a versão 0.11.5 ou posterior.

Desenvolvimento com MaxFrame

Especifique a imagem para o job atual nas configurações:

config.options.sql.settings = {
    "odps.session.image": "<image_name>"
}