Como implantar um modelo R registrado em um endpoint online (tempo real)

Artigo
01/10/2024

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

Neste artigo, você aprenderá como implantar um modelo R em um ponto de extremidade gerenciado (API da Web) para que seu aplicativo possa pontuar novos dados em relação ao modelo quase em tempo real.

Pré-requisitos

Um espaço de trabalho do Azure Machine Learning.
CLI do Azure e extensão ml instalada. Ou use uma instância de computação em seu espaço de trabalho, que tem a CLI pré-instalada.
Pelo menos um ambiente personalizado associado ao seu espaço de trabalho. Crie um ambiente R ou qualquer outro ambiente personalizado, se não tiver um.
Compreensão do pacote R plumber
Um modelo que você treinou e empacotou com crateo , e registrou em seu espaço de trabalho

Criar uma pasta com esta estrutura

Crie esta estrutura de pastas para o 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 quaisquer pacotes R adicionais aqui.

Um exemplo de Dockerfile terá esta aparência:

# 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 seu script de pontuação.

canalizador. R

Importante

Esta seção mostra como estruturar o encanador. Script R . Para obter informações detalhadas sobre o pacote, consulte plumber a plumber documentação .

O encanador de arquivos . R é o script R onde você definirá a função para pontuação. Esse script também executa tarefas que são necessárias para fazer seu ponto de extremidade funcionar. O script:

Obtém o caminho onde o modelo é montado a AZUREML_MODEL_DIR partir da variável de ambiente no contêiner.
Carrega um objeto de modelo criado com a cratecarrier função do pacote, que foi salvo como caixote.bin quando foi empacotado.
Desserializa o objeto de modelo
Define a função de pontuação

Gorjeta

Certifique-se de que tudo o que sua função de pontuação produz pode ser convertido de volta para JSON. Alguns objetos R não são facilmente convertidos.

# 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 chama seu encanador. Script R . Use o seguinte script 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)

Construir contêiner

Essas etapas pressupõem que você tenha um Registro de Contêiner do Azure associado ao seu espaço de trabalho, 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 espaço de trabalho, se necessário.
Na navegação à esquerda, selecione Ambientes.
Na parte superior, selecione Ambientes personalizados.
Se você vir ambientes personalizados, nada mais é necessário.
Se você não vir nenhum ambiente personalizado, crie um ambiente 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 foi criado para você.)

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

Abra uma janela de terminal e entre no Azure. Se você estiver fazendo isso a partir de 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 ml extensão:
```
az upgrade
```
Se tiver várias subscrições do Azure, defina a subscrição ativa como a que está a utilizar para a sua área de trabalho. (Pode ignorar este passo se só tiver acesso a uma única subscrição.) Substitua <SUBSCRIPTION-NAME> pelo nome da sua subscrição. Remova também os suportes <>.
```
az account set --subscription "<SUBSCRIPTION-NAME>"
```
Defina o espaço de trabalho padrão. Se você estiver fazendo isso a partir de uma instância de computação, poderá usar o comando a seguir como está. Se você estiver em qualquer outro computador, substitua o nome do grupo de recursos e do espaço de trabalho. (Pode encontrar estes valores em Estúdio do Azure Machine Learning.)
```
az configure --defaults group=$CI_RESOURCE_GROUP workspace=$CI_WORKSPACE
```
Certifique-se de que está no diretório do seu projeto.
```
cd r-deploy-azureml
```
Para construir a imagem na nuvem, execute os seguintes comandos bash no seu terminal. Substitua <IMAGE-NAME> pelo nome que deseja dar à imagem.

Se o seu espaço de trabalho estiver em uma rede virtual, consulte Habilitar o Registro de Contêiner do Azure (ACR) para obter etapas adicionais a serem adicionadas --image-build-compute ao az acr build comando na última linha deste 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

Levará alguns minutos para que a imagem seja construída. Aguarde até que o processo de compilação seja concluído antes de prosseguir para a próxima seção. Não feche este terminal, você o usará ao lado para criar a implantação.

O az acr comando carregará automaticamente sua pasta de contexto do docker - que contém os artefatos para criar a imagem - na nuvem onde a imagem será criada e hospedada em um Registro de Contêiner do Azure.

Implementar o 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 criados 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 de pontuação de um modelo treinado. Fornece:

Autenticação usando autenticação baseada em "key & token"
Terminação de 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 faz a pontuação real. Um únicoponto de extremidade pode conter váriasimplantações. Os recursos de balanceamento de carga dos pontos de extremidade gerenciados do Azure Machine Learning permitem que você forneça qualquer porcentagem de tráfego para cada implantação. A alocação de tráfego pode ser usada para fazer implantações azuis/verdes de implantação segura, equilibrando solicitações entre diferentes instâncias.

Criar endpoint online gerenciado

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

Criar implementação

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

Substitua <ENDPOINT-NAME> pelo nome do ponto de extremidade definido no arquivo endpoint.yml
Substitua <DEPLOYMENT-NAME> pelo nome que você deseja dar à implantação
Substitua <MODEL-URI> pelo URI do modelo registrado na forma de 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 seu terminal, execute o seguinte comando da CLI para criar a implantação (observe que você está definindo 100% do tráfego para este modelo):
```
az ml online-deployment create -f deployment.yml --all-traffic --skip-script-validation
```

Nota

Pode levar 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 sua implantação tiver sido criada com êxito, 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 no menu à esquerda Pontos de extremidade. Em seguida, selecione o r-endpoint-iris que você criou anteriormente.

Insira o seguinte json na caixa de texto Input data to rest real-time endpoint end:

{
    "forecast_horizon" : [2]
}

Selecione Teste. Deverá ver o seguinte resultado:

Criar uma solicitação de exemplo

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

{
    "forecast_horizon" : [2]
}

Invoque 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ê obteve uma pontuação bem-sucedida com seu endpoint, você pode excluí-lo para não incorrer em custos contínuos:

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

Próximos passos

Para obter mais informações sobre como usar o R com o Azure Machine Learning, consulte Visão geral dos recursos do R no Azure Machine Learning