Extensibilidade de pacotes Python para imagens predefinidas do Docker (versão prévia)

APLICA-SE A: SDK do Python do AzureML v1

Importante

Este artigo fornece informações sobre como usar o SDK do Azure Machine Learning v1. O SDK v1 foi preterido a partir de 31 de março de 2025 e o suporte para ele terminará em 30 de junho de 2026. Você pode instalar e usar o SDK v1 até essa data.

Recomendamos que você faça a transição para o SDK v2 antes de 30 de junho de 2026. Para obter mais informações sobre o SDK v2, consulte O que é o SDK do Python do Azure Machine Learning v2 e a referência do SDK v2.

As imagens predefinidas do Docker para inferência de modelo contêm pacotes para estruturas populares de machine learning. Há dois métodos que podem ser usados para adicionar pacotes Python sem recriar a imagem do Docker:

• Instalação dinâmica: essa abordagem usa um arquivo de requisitos para restaurar automaticamente os pacotes Python quando o contêiner do Docker é inicializado.

  Considere esse método para a criação rápida de protótipos. Quando a imagem é iniciada, os pacotes são restaurados usando o arquivo requirements.txt. Esse método aumenta a inicialização da imagem e você precisa aguardar mais até que a implantação possa processar as solicitações.

• Pacotes Python pré-instalados: você fornece um diretório que contém pacotes Python pré-instalados. Durante a implantação, esse diretório é montado no contêiner para ser usado pelo script de entrada (score.py).

  Use essa abordagem para implantações de produção. Como o diretório que contém os pacotes é montado na imagem, ele pode ser usado mesmo quando as implantações não têm acesso público à Internet. Por exemplo, quando ele é implantado em uma Rede Virtual do Azure protegida.

Importante

O uso da extensibilidade de pacote do Python para imagens predefinidas do Docker com o Azure Machine Learning está em versão prévia no momento. A funcionalidade de visualização é fornecida "no estado em que se encontra", sem garantia de suporte ou contrato de nível de serviço. Para saber mais, confira os Termos de Uso Complementares das Versões Prévias do Microsoft Azure.

Pré-requisitos

• Um Workspace do Azure Machine Learning. Para obter um tutorial sobre como criar um workspace, confira Introdução ao Azure Machine Learning.
• Familiaridade com o uso de ambientes do Azure Machine Learning.
• Saber como e onde implantar modelos com o Azure Machine Learning.

Instalação dinâmica

Essa abordagem usa um arquivo de requisitos para restaurar automaticamente os pacotes Python quando a imagem é iniciada.

Para estender a imagem de contêiner predefinida do Docker com um requirements.txt, siga estas etapas:

1. Crie um arquivo requirements.txt junto com o script score.py.
2. Adicione todos os pacotes necessários ao arquivo requirements.txt.
3. Defina a variável de ambiente AZUREML_EXTRA_REQUIREMENTS_TXT no ambiente do Azure Machine Learning como o local do arquivo requirements.txt.

Depois de implantados, os pacotes serão restaurados automaticamente para o script de pontuação.

Dica

Mesmo durante a criação de protótipo, recomendamos que você fixe cada versão do pacote no requirements.txt. Por exemplo, use scipy == 1.2.3 em vez de apenas scipy ou mesmo scipy > 1.2.3. Se você não fixar uma versão exata e o scipy lançar uma nova versão, isso poderá interromper o script de pontuação e causar falhas durante a implantação e o dimensionamento.

O seguinte exemplo demonstra como definir a variável de ambiente AZUREML_EXTRA_REQUIRMENTS_TXT:

from azureml.core import Environment
from azureml.core.conda_dependencies import CondaDependencies 

myenv = Environment(name="my_azureml_env")
myenv.docker.enabled = True
myenv.docker.base_image = <MCR-path>
myenv.python.user_managed_dependencies = True

myenv.environment_variables = {
    "AZUREML_EXTRA_REQUIREMENTS_TXT": "requirements.txt"
}

O seguinte diagrama é uma representação visual do processo de instalação dinâmica:

Pacotes Python pré-instalados

Essa abordagem monta um diretório que você fornece na imagem. Os pacotes Python desse diretório podem ser usados pelo script de entrada (score.py).

Para estender a imagem de contêiner predefinida do Docker por meio de pacotes Python pré-instalados, siga estas etapas:

Importante

Você deve usar pacotes compatíveis com o Python 3.8 ou 3.8, dependendo da imagem usada.

1. Crie um ambiente virtual usando virtualenv.

2. Instale as dependências. Se, por exemplo, você tem uma lista de dependências em um requirements.txt, use-a para fazer a instalação com o pip install -r requirements.txt ou instale apenas as dependências individuais pip install.

3. Quando você especificar a variável de ambiente AZUREML_EXTRA_PYTHON_LIB_PATH, aponte para o diretório de pacotes do site correto, que vai variar dependendo do nome do ambiente e da versão do Python. O código a seguir demonstra como definir o caminho para um ambiente virtual chamado myenv Python 3.8:

   from azureml.core import Environment
   from azureml.core.conda_dependencies import CondaDependencies 
   
   myenv = Environment(name='my_azureml_env')
   myenv.docker.enabled = True
   myenv.docker.base_image = <MCR-path>
   myenv.python.user_managed_dependencies = True
   
   myenv.environment_variables = {
       "AZUREML_EXTRA_PYTHON_LIB_PATH": "myenv/lib/python3.8/site-packages"
   }
   

O seguinte diagrama é uma representação visual do processo de pacotes pré-instalados:

Problemas comuns

A solução de montagem só funcionará quando o diretório de pacotes myenv do site contiver todas as dependências. Se o ambiente local estiver usando dependências instaladas em um local diferente, elas não estarão disponíveis na imagem.

Veja algumas coisas que podem causar esse problema:

• virtualenv cria um ambiente isolado por padrão. Depois que você ativa o ambiente virtual, as dependências globais não podem ser usadas.
• Se houver uma variável de ambiente PYTHONPATH apontando para as dependências globais, ela poderá interferir no ambiente virtual. Execute pip list e pip freeze depois de ativar o ambiente para garantir que não haja nenhuma dependência indesejada no ambiente.
• Os ambientes Conda e virtualenv podem interferir. Não use o ambiente Conda e o virtualenv ao mesmo tempo.

Limitações

Model.package()

• O método Model.package() permite que você crie um pacote de modelo em forma de imagem do Docker ou de contexto de build do Dockerfile. O uso de Model.package() com imagens predefinidas de inferência do Docker dispara um build de imagem intermediário que altera o usuário não raiz para usuário raiz.

• Incentivamos você a usar nossas soluções de extensibilidade de pacotes Python. Se outras dependências forem necessárias (como pacotes apt), crie seu Dockerfile por meio da extensão da imagem de inferência.

Perguntas frequentes

• Na abordagem de extensibilidade de requirements.txt, é obrigatório que o nome do arquivo seja requirements.txt?

  myenv.environment_variables = {
      "AZUREML_EXTRA_REQUIREMENTS_TXT": "name of your pip requirements file goes here"
  }
  

• Você pode comparar a abordagem requirements.txt com a abordagem de montagem?

  Comece a criar protótipos com a abordagem requirements.txt. Após algumas iterações, quando você tiver certeza sobre quais pacotes (e versões) precisa para uma implantação de modelo bem-sucedida, mude para a solução de montagem.

  Veja uma comparação detalhada.

  Item comparado	Requirements.txt (instalação dinâmica)	Montagem de pacote
  Solução	Crie um requirements.txt que instala os pacotes especificados quando o contêiner é iniciado.	Crie um ambiente Python local com todas as dependências. Monte esse diretório no contêiner no runtime.
  Instalação do pacote	Nenhuma instalação extra (supondo que o pip já esteja instalado)	Instalação do ambiente virtual ou do ambiente Conda.
  Configuração do ambiente virtual	Não é necessária nenhuma configuração extra do ambiente virtual, pois os usuários podem efetuar pull do ambiente do usuário local atual com o congelamento do pip, conforme o necessário, para criar o requirements.txt.	A necessidade de configurar um ambiente virtual limpo pode exigir etapas adicionais, dependendo do ambiente local do usuário atual.
  Depuração	Fácil de configurar e depurar o servidor, pois as dependências são listadas com clareza.	Um ambiente virtual que não está claro pode causar problemas durante a depuração do servidor. Por exemplo, talvez não fique claro se os erros são do ambiente ou do código do usuário.
  Consistência durante a escala horizontal	Não consistente, pois depende de pacotes PyPi externos e de que os usuários fixem as dependências. Esses downloads externos podem ser instáveis.	Depende exclusivamente do ambiente do usuário, portanto, não há problemas de consistência.

• Por que o requirements.txt e o diretório de dependências montado não se encontram no contêiner?

  Localmente, verifique se as variáveis de ambiente estão definidas corretamente. Depois, verifique se os caminhos especificados estão escritos corretamente e existem. Verifique se você definiu o diretório de origem corretamente no construtor de configuração de inferência.

• Posso substituir as dependências de pacote Python na imagem predefinida de inferência do Docker?

  Sim. Se você quer usar outra versão do pacote Python que já está instalada em uma imagem de inferência, nossa solução de extensibilidade respeita sua versão. Verifique se não há nenhum conflito entre as duas versões.

Práticas Recomendadas

• Confira o doc Carregar o modelo registrado. Ao registrar um diretório de modelos, não inclua o script de pontuação, o diretório de dependências montado nem o requirements.txt nesse diretório.

• Para obter mais informações sobre como carregar um modelo registrado ou local, confira Onde e como fazer a implantação.

Correções de bugs

26-07-2021

• AZUREML_EXTRA_REQUIREMENTS_TXT e AZUREML_EXTRA_PYTHON_LIB_PATH agora são sempre relativos ao diretório do script de pontuação. Por exemplo, se tanto o requirements.txt quanto o script de pontuação estiverem em my_folder, será necessário definir AZUREML_EXTRA_REQUIREMENTS_TXT como requirements.txt. O AZUREML_EXTRA_REQUIREMENTS_TXT não será mais definido como my_folder/requirements.txt.

Próximas etapas

Para saber mais sobre como implantar um modelo, confira Como implantar um modelo.

Para saber como solucionar problemas de implantações de imagem predefinida do Docker, confira Como solucionar problemas de implantações de imagem predefinida do Docker.