Como implantar um modelo do R registrado em um ponto de extremidade online (em tempo real)

Artigo
04/04/2023

APLICA-SE A:Extensão do ML da CLI do Azure v2 (atual)

Neste artigo, você aprenderá a implantar um modelo do R em um ponto de extremidade gerenciado (API Web) para que o seu aplicativo possa pontuar novos dados no modelo quase em tempo real.

Pré-requisitos

Um workspace do Azure Machine Learning.
CLI do Azure e extensão do ML instaladas. Ou, então, use uma instância de computação no workspace, que tenha a CLI pré-instalada.
Pelo menos um ambiente personalizado associado ao workspace. Crie um ambiente do R ou qualquer outro ambiente personalizado, caso não tenha um.
Uma compreensão do pacote plumber do R
Um modelo que você treinou e empacotou com crate e registrou no workspace

Criar uma pasta com esta estrutura

Crie esta estrutura de pastas para seu projeto:

📂 r-deploy-azureml
 ├─📂 docker-context
 │  ├─ Dockerfile
 │  └─ start_plumber.R
 ├─📂 src
 │  └─ plumber.R
 ├─ deployment.yml
 ├─ endpoint.yml

O conteúdo de cada um desses arquivos é mostrado e explicado neste artigo.

Dockerfile

Este é o arquivo que define o ambiente de contêiner. Você também definirá a instalação de todos os pacotes adicionais do R aqui.

Um exemplo de Dockerfile será parecido com este:

# REQUIRED: Begin with the latest R container with plumber
FROM rstudio/plumber:latest

# REQUIRED: Install carrier package to be able to use the crated model (whether from a training job
# or uploaded)
RUN R -e "install.packages('carrier', dependencies = TRUE, repos = 'https://cloud.r-project.org/')"

# OPTIONAL: Install any additional R packages you may need for your model crate to run
RUN R -e "install.packages('<PACKAGE-NAME>', dependencies = TRUE, repos = 'https://cloud.r-project.org/')"
RUN R -e "install.packages('<PACKAGE-NAME>', dependencies = TRUE, repos = 'https://cloud.r-project.org/')"

# REQUIRED
ENTRYPOINT []

COPY ./start_plumber.R /tmp/start_plumber.R 

CMD ["Rscript", "/tmp/start_plumber.R"]

Modifique o arquivo para adicionar os pacotes necessários para o script de pontuação.

plumber.R

Importante

Esta seção mostra como estruturar o script de plumber.R. Para obter informações detalhadas sobre o pacote plumber, confira a documentação do plumber.

O arquivo plumber.R é o script R em que você definirá a função para pontuação. Esse script também executa as tarefas necessárias para fazer seu ponto de extremidade funcionar. O script:

Obtém o caminho em que o modelo é montado com base na variável de ambiente AZUREML_MODEL_DIR no contêiner.
Carrega um objeto de modelo criado com a função crate por meio do pacote carrier, que foi salvo como crate.bin quando ele foi empacotado.
Desserializa o objeto de modelo
Define a função de pontuação

Dica

Verifique se o que a função de pontuação produz pode ser convertido novamente em JSON. Alguns objetos do R não são convertidos com facilidade.

# plumber.R
# This script will be deployed to a managed endpoint to do the model scoring

# REQUIRED
# When you deploy a model as an online endpoint, Azure Machine Learning mounts your model
# to your endpoint. Model mounting enables you to deploy new versions of the model without
# having to create a new Docker image.

model_dir <- Sys.getenv("AZUREML_MODEL_DIR")

# REQUIRED
# This reads the serialized model with its respecive predict/score method you 
# registered. The loaded load_model object is a raw binary object.
load_model <- readRDS(paste0(model_dir, "/models/crate.bin"))

# REQUIRED
# You have to unserialize the load_model object to make it its function
scoring_function <- unserialize(load_model)

# REQUIRED
# << Readiness route vs. liveness route >>
# An HTTP server defines paths for both liveness and readiness. A liveness route is used to
# check whether the server is running. A readiness route is used to check whether the 
# server's ready to do work. In machine learning inference, a server could respond 200 OK 
# to a liveness request before loading a model. The server could respond 200 OK to a
# readiness request only after the model has been loaded into memory.

#* Liveness check
#* @get /live
function() {
  "alive"
}

#* Readiness check
#* @get /ready
function() {
  "ready"
}

# << The scoring function >>
# This is the function that is deployed as a web API that will score the model
# Make sure that whatever you are producing as a score can be converted 
# to JSON to be sent back as the API response
# in the example here, forecast_horizon (the number of time units to forecast) is the input to scoring_function.  
# the output is a tibble
# we are converting some of the output types so they work in JSON


#* @param forecast_horizon 
#* @post /score
function(forecast_horizon) {
  scoring_function(as.numeric(forecast_horizon)) |> 
    tibble::as_tibble() |> 
    dplyr::transmute(period = as.character(yr_wk),
                     dist = as.character(logmove),
                     forecast = .mean) |> 
    jsonlite::toJSON()
}

start_plumber.R

O arquivo start_plumber.R é o script R que é executado quando o contêiner é iniciado e ele chama o script do plumber.R. Use o script a seguir no estado em que se encontra.

entry_script_path <- paste0(Sys.getenv('AML_APP_ROOT'),'/', Sys.getenv('AZUREML_ENTRY_SCRIPT'))

pr <- plumber::plumb(entry_script_path)

args <- list(host = '0.0.0.0', port = 8000); 

if (packageVersion('plumber') >= '1.0.0') {
  pr$setDocs(TRUE)
} else { 
  args$swagger <- TRUE 
} 

do.call(pr$run, args)

Criar um contêiner

Estas etapas pressupõem que você tenha um Registro de Contêiner do Azure associado ao workspace, que é criado quando você cria seu primeiro ambiente personalizado. Para ver se você tem um ambiente personalizado:

Entre no Estúdio do Azure Machine Learning.
Selecione seu workspace, se necessário.
No painel de navegação à esquerda, selecione Ambientes.
Na parte superior, selecione Ambientes personalizados.
Se você vir ambientes personalizados, nada mais será necessário.
Se você não vir nenhum ambiente personalizado, crie um ambiente do R ou qualquer outro ambiente personalizado. (Você não usará esse ambiente para implantação, mas usará o registro de contêiner que também é criado para você).

Depois de verificar se você tem, pelo menos, um ambiente personalizado, use as etapas a seguir para criar um contêiner.

Abra uma janela do terminal e entre no Azure. Se estiver fazendo isso em uma instância de computação do Azure Machine Learning, use:
```
az login --identity
```
Se você não estiver na instância de computação, omita --identity e siga o prompt para abrir uma janela do navegador para autenticar.
Verifique se você tem as versões mais recentes da CLI e da extensão ml:
```
az upgrade
```
Se você tiver várias assinaturas do Azure, defina a assinatura ativa como aquela que você está usando em seu workspace. (Você pode ignorar esta etapa se tiver acesso apenas a uma única assinatura.) Substitua <SUBSCRIPTION-NAME> pelo nome da assinatura. Remova também os colchetes <>.
```
az account set --subscription "<SUBSCRIPTION-NAME>"
```
Defina o workspace padrão. Se estiver fazendo isso em uma instância de computação, use o comando a seguir no estado em que se encontra. Se estiver em qualquer outro computador, substitua o grupo de recursos e o nome do workspace. (Encontre esses valores no Estúdio do Azure Machine Learning).
```
az configure --defaults group=$CI_RESOURCE_GROUP workspace=$CI_WORKSPACE
```
Verifique se você está no diretório de projeto.
```
cd r-deploy-azureml
```
Para compilar a imagem na nuvem, execute os comandos do Bash a seguir no terminal. Substitua <IMAGE-NAME> pelo nome que deseja dar à imagem.

Se o workspace estiver em uma rede virtual, confira Habilitar o ACR (Registro de Contêiner do Azure) para obter mais etapas para adicionar --image-build-compute ao comando az acr build na última linha desse código.
```
WORKSPACE=$(az config get --query "defaults[?name == 'workspace'].value" -o tsv)
ACR_NAME=$(az ml workspace show -n $WORKSPACE --query container_registry -o tsv | cut -d'/' -f9-)
IMAGE_TAG=${ACR_NAME}.azurecr.io/<IMAGE-NAME>

az acr build ./docker-context -t $IMAGE_TAG -r $ACR_NAME
```

Importante

Serão necessários alguns minutos para que a imagem seja compilada. Aguarde até que o processo de build seja concluído antes de prosseguir para a próxima seção. Não feche este terminal. Você o usará a seguir para criar a implantação.

O comando az acr carregará automaticamente a pasta docker-context, que contém os artefatos necessários para criar a imagem, na nuvem em que a imagem será compilada e hospedada em um Registro de Contêiner do Azure.

Implantar modelo

Nesta seção do artigo, você definirá e criará um ponto de extremidade e uma implantação para implantar o modelo e a imagem compilados nas etapas anteriores em um ponto de extremidade online gerenciado.

Um ponto de extremidade é um ponto de extremidade HTTPS que os clientes (como um aplicativo) podem chamar para receber a saída da pontuação de um modelo treinado. Ele fornece:

Autenticação baseada em “chave e token”
Terminação SSL
Um URI de pontuação estável (endpoint-name.region.inference.ml.Azure.com)

Uma implantação é um conjunto de recursos necessários para hospedar o modelo que executa a pontuação real. Um sóponto de extremidade pode conter váriasimplantações. As funcionalidades de balanceamento de carga dos pontos de extremidade gerenciados do Azure Machine Learning permitem que você forneça qualquer percentual de tráfego para cada implantação. A alocação de tráfego pode ser usada para executar implantações azul/verde de distribuição segura balanceando as solicitações entre instâncias diferentes.

Criar um ponto de extremidade online gerenciado

No diretório do projeto, adicione o arquivo endpoint.yml com o código a seguir. Substitua <ENDPOINT-NAME> pelo nome que deseja dar ao ponto de extremidade gerenciado.
```
$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: <ENDPOINT-NAME>
auth_mode: aml_token
```
Usando o mesmo terminal em que você compilou a imagem, execute o seguinte comando da CLI para criar um ponto de extremidade:
```
az ml online-endpoint create -f endpoint.yml
```
Mantenha o terminal aberto para continuar usando-o na próxima seção.

Criar implantação

Para criar sua implantação, adicione o código a seguir ao arquivo deployment.yml.

Substitua <ENDPOINT-NAME> pelo nome do ponto de extremidade definido no arquivo endpoint.yml
Substitua <DEPLOYMENT-NAME> pelo nome que deseja dar à implantação
Substitua <MODEL-URI> pelo URI do modelo registrado no formato azureml:modelname@latest
Substitua <IMAGE-TAG> pelo valor de:
```
echo $IMAGE_TAG
```

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: <DEPLOYMENT-NAME>
endpoint_name: <ENDPOINT-NAME>
code_configuration:
  code: ./src
  scoring_script: plumber.R
model: <MODEL-URI>
environment:
  image: <IMAGE-TAG>
  inference_config:
    liveness_route:
      port: 8000
      path: /live
    readiness_route:
      port: 8000
      path: /ready
    scoring_route:
      port: 8000
      path: /score
instance_type: Standard_DS2_v2
instance_count: 1

Em seguida, no terminal, execute o seguinte comando da CLI para criar a implantação (observe que você está definindo 100% do tráfego para esse modelo):
```
az ml online-deployment create -f deployment.yml --all-traffic --skip-script-validation
```

Observação

Podem ser necessários vários minutos para que o serviço seja implantado. Aguarde até que a implantação seja concluída antes de prosseguir para a próxima seção.

Teste

Depois que a implantação tiver sido criada com sucesso, você poderá testar o ponto de extremidade usando o estúdio ou a CLI:

Estúdio
CLI do Azure

Navegue até o Estúdio do Azure Machine Learning e selecione-o no menu à esquerda Pontos de Extremidade. Em seguida, selecione o r-endpoint-iris criado anteriormente.

Insira o seguinte JSON na caixa de texto Dados de entrada para a ponto de extremidade em tempo real da REST:

{
    "forecast_horizon" : [2]
}

Selecione Testar. Você deve ver o seguinte resultado:

Criar um exemplo de solicitação

Na pasta pai do projeto, crie um arquivo chamado sample_request.json e preencha-o com:

{
    "forecast_horizon" : [2]
}

Invocar o ponto de extremidade

Invoque a solicitação. Este exemplo usa o nome r-endpoint-forecast:

az ml online-endpoint invoke --name r-endpoint-forecast --request-file sample_request.json

Recursos de limpeza

Agora que você pontuou com sucesso seu ponto de extremidade, exclua-o para não gerar custos contínuos:

az ml online-endpoint delete --name r-endpoint-forecast

Próximas etapas

Para obter mais informações sobre como usar o R com o Azure Machine Learning, confira Visão geral das funcionalidades do R no Azure Machine Learning