Endpoints regionais

Para usar a previsão on-line, interaja com a API AI Platform Training and Prediction por meio do endpoint global (ml.googleapis.com) ou de um dos endpoints regionais (REGION-ml.googleapis.com). O uso de um endpoint regional para previsão on-line fornece mais proteção para seu modelo contra interrupções em outras regiões, porque isola os recursos de modelo e versão de outras regiões.

Atualmente, o AI Platform Prediction é compatível com os seguintes endpoints regionais:

  • us-central1
  • us-east1
  • us-east4
  • us-west1
  • northamerica-northeast1
  • europe-west1
  • europe-west2
  • europe-west3
  • europe-west4
  • asia-east1
  • asia-northeast1
  • asia-southeast1
  • australia-southeast1

Neste guia, comparamos os benefícios e as limitações do uso de endpoints regionais com o endpoint global. O guia também usa um endpoint regional para previsão on-line.

Noções básicas sobre endpoints regionais

Os endpoints regionais têm várias diferenças importantes em relação ao endpoint global:

  • Os endpoints regionais só são compatíveis com os tipos de máquina do Compute Engine (N1). Não é possível usar tipos de máquina legados (MLS1) em endpoints regionais. Isso significa que todos os benefícios e limitações do uso de tipos de máquina do Compute Engine (N1) se aplicam. Por exemplo, é possível usar GPUs em endpoints regionais, mas não é possível ativar a geração de registros de stream (console).

    Para usar um tipo de máquina N1 do Compute Engine, é necessário usar um endpoint regional.

  • Os endpoints regionais são compatíveis apenas com a previsão on-line e o AI Explanations. Os modelos implantados em endpoints regionais não são compatíveis com previsão em lote.

    O AI Platform Prediction compartilha a API AI Platform Training and Prediction com o AI Platform Training e o AI Platform Vizier. No momento, os endpoints regionais não são compatíveis com o AI Platform Training. Somente o endpoint us-central1 é compatível com o AI Platform Vizier.

    Consulte a referência da API para mais detalhes sobre quais métodos da API estão disponíveis em quais endpoints.

Os nomes de recurso do AI Platform Prediction são exclusivos para seu projeto do Google Cloud em qualquer endpoint, mas podem ser duplicados em vários deles. Por exemplo, é possível criar um modelo chamado "hello-world" no endpoint europe-west4 e outro modelo chamado "hello-world" no endpoint us-central1.

Ao listar modelos em um endpoint regional, você só vê os modelos criados nesse endpoint. Da mesma forma, ao listar modelos no endpoint global, você verá apenas os modelos criados no endpoint global.

Regiões de endpoints regionais e globais

Ao criar um recurso de modelo no endpoint global, é possível especificar uma região para o modelo. Quando você cria versões nesse modelo e exibe previsões, os nós de previsão são executados na região especificada.

Quando você usa um endpoint regional, o AI Platform Prediction executa os nós de previsão na região do endpoint. No entanto, neste caso, o AI Platform Prediction fornece mais isolamento por meio da execução de toda a infraestrutura dele nessa região.

Por exemplo, se você usar a região us-east1 no endpoint global, seus nós de previsão serão executados em us-east1. Mas a infraestrutura do AI Platform Prediction que gerencia recursos (solicitações de roteamento, manipulação de modelos e versões, atualizações e exclusões etc.) não é executada necessariamente em us-east1. Por outro lado, se você usar o endpoint regional europe-west4, os nós de previsão e toda a infraestrutura do AI Platform Prediction serão executados em europe-west4.

Como usar endpoints regionais

Para usar um endpoint regional, primeiro é preciso criar um modelo no endpoint regional. Em seguida, execute todas as ações relacionadas a esse modelo (como a criação de uma versão de modelo e o envio de solicitações de previsão) no mesmo endpoint.

Se você estiver usando o Console do Google Cloud, marque a caixa de seleção Usar endpoint regional ao criar o modelo. Realize todas as outras ações do console do Google Cloud conforme você faria no endpoint global.

Se você estiver usando a Google Cloud CLI, use a sinalização --region da região do endpoint em todos os comandos que interagem com o modelo e os recursos filhos dele. Isso inclui o seguinte:

Como alternativa, defina a propriedade ai_platform/region como uma região específica para garantir que a gcloud CLI sempre use o endpoint regional correspondente para comandos do AI Platform Prediction, mesmo quando você não especificar a sinalização --region. Essa configuração não se aplica a comandos no grupo de comandos gcloud ai-platform operations.

Se você estiver interagindo diretamente com a API AI Platform Training and Prediction, por exemplo, usando a biblioteca de cliente de APIs do Google para Python, faça todas as solicitações de API como faria para o endpoint global, mas use o endpoint regional. Consulte a referência da API para mais detalhes sobre quais métodos de API estão disponíveis em endpoints regionais.

Os exemplos a seguir demonstram como usar um endpoint regional para criar um modelo, criar uma versão e enviar uma solicitação de previsão on-line. Para usar os exemplos, substitua REGION sempre que ele aparecer em uma das regiões em que os endpoints regionais estão disponíveis:

  • us-central1
  • us-east1
  • us-east4
  • us-west1
  • northamerica-northeast1
  • europe-west1
  • europe-west2
  • europe-west3
  • europe-west4
  • asia-east1
  • asia-northeast1
  • asia-southeast1
  • australia-southeast1

Como criar um modelo

Console do Google Cloud

  1. No console do Google Cloud, acesse a página Criar modelo e selecione seu projeto do Google Cloud:

    Acessar a página "Criar modelo"

  2. Atribua um nome ao modelo e marque a caixa de seleção Usar endpoint regional. Em seguida, selecione a região do endpoint que você quer usar na lista suspensa Região.

  3. Clique no botão Criar.

gcloud

Execute este comando:

gcloud ai-platform models create MODEL_NAME \
  --region=REGION

No comando, substitua os seguintes marcadores:

  • MODEL_NAME: um nome que você escolhe para o modelo.
  • REGION: a região do endpoint que você quer usar.

Python

Neste exemplo, usamos a biblioteca de cliente de APIs do Google para Python. Antes de usá-la, instale a biblioteca de cliente de APIs do Google para Python e configure a autenticação no seu ambiente de desenvolvimento.

Execute o seguinte código Python:

from google.api_core.client_options import ClientOptions
from googleapiclient import discovery

endpoint = 'https://REGION-ml.googleapis.com'
client_options = ClientOptions(api_endpoint=endpoint)
ml = discovery.build('ml', 'v1', client_options=client_options)

request_body = { 'name': 'MODEL_NAME' }
request = ml.projects().models().create(parent='projects/PROJECT_ID',
    body=request_body)

response = request.execute()
print(response)

No código, substitua os seguintes marcadores:

  • REGION: a região do endpoint que você quer usar.
  • MODEL_NAME: um nome que você escolhe para o modelo.
  • PROJECT_ID: o ID do projeto do Google Cloud.

Saiba mais sobre como criar um modelo.

Como criar uma versão de modelo

Neste exemplo, presumimos que você já tenha enviado artefatos de modelo compatíveis para o Cloud Storage.

Console do Google Cloud

Usando o modelo que você criou na seção anterior, siga o guia para criar uma versão de modelo no console do Google Cloud.

gcloud

Neste exemplo, presumimos que você já tenha enviado artefatos de modelo compatíveis para o Cloud Storage. Execute este comando:

gcloud ai-platform versions create VERSION_NAME \
  --region=REGION \
  --model=MODEL_NAME \
  --framework=FRAMEWORK \
  --machine-type=MACHINE_TYPE \
  --origin=MODEL_DIRECTORY \
  --python-version=3.7 \
  --runtime-version=2.11

No comando, substitua os seguintes marcadores:

  • REGION: a região do endpoint que você usou na seção anterior.
  • VERSION_NAME: um nome que você escolhe para a versão.
  • MODEL_NAME: o nome do modelo que você criou na seção anterior.
  • FRAMEWORK: o framework usado para criar os artefatos do modelo.
  • MACHINE_TYPE: um tipo de máquina (N1) do Compute Engine.
  • MODEL_DIRECTORY: um URI do Cloud Storage para o diretório do modelo (começando com "gs://").

Python

Execute o seguinte código Python:

from google.api_core.client_options import ClientOptions
from googleapiclient import discovery

endpoint = 'https://REGION-ml.googleapis.com'
client_options = ClientOptions(api_endpoint=endpoint)
ml = discovery.build('ml', 'v1', client_options=client_options)

request_body = { 'name': 'VERSION_NAME',
    'deploymentUri': 'MODEL_DIRECTORY',
    'runtimeVersion': '2.11',
    'machineType': 'MACHINE_TYPE',
    'framework': 'FRAMEWORK',
    'pythonVersion': '3.7'}
request = ml.projects().models().versions().create(
    parent='projects/PROJECT_ID/models/MODEL_NAME',
    body=request_body)

response = request.execute()
print(response)

No código, substitua os seguintes marcadores:

  • REGION: a região do endpoint que você usou na seção anterior.
  • VERSION_NAME: um nome que você escolhe para a versão.
  • MODEL_DIRECTORY: um URI do Cloud Storage para o diretório do modelo (começando com "gs://").
  • MACHINE_TYPE: um tipo de máquina (N1) do Compute Engine.
  • FRAMEWORK: o framework usado para criar os artefatos do modelo.
  • PROJECT_ID: o ID do projeto do Google Cloud.
  • MODEL_NAME: o nome do modelo que você criou na seção anterior.

Saiba mais sobre como criar uma versão de modelo.

Como enviar uma solicitação de previsão on-line

Console do Google Cloud

  1. No console do Google Cloud, acesse a página Modelos:

    Acessar a página de modelos

  2. Na lista suspensa Região, selecione a região do endpoint que o modelo usa. Clique no nome do modelo que você criou em uma seção anterior para acessar a página Detalhes do modelo.

  3. Clique no nome da versão que você criou em uma seção anterior para acessar a página Detalhes da versão.

  4. Clique na guia Testar e usar. Insira uma ou mais instâncias dos dados de entrada e clique no botão Testar para enviar uma solicitação de previsão on-line.

gcloud

Nestes exemplos, presumimos que você salvou a entrada de previsão em um arquivo JSON delimitado por nova linha no ambiente local. Execute este comando:

gcloud ai-platform predict \
  --region=REGION \
  --model=MODEL_NAME \
  --version=VERSION_NAME \
  --json-request=INPUT_PATH

No comando, substitua os seguintes marcadores:

  • REGION: a região do endpoint que você usou nas seções anteriores.
  • MODEL_NAME: o nome do modelo que você criou em uma seção anterior.
  • VERSION_NAME: o nome da versão do modelo que você criou na seção anterior.
  • INPUT_PATH: o caminho no sistema de arquivos local para um arquivo JSON com entrada de previsão.

Python

Execute o seguinte código Python:

from google.api_core.client_options import ClientOptions
from googleapiclient import discovery

endpoint = 'https://REGION-ml.googleapis.com'
client_options = ClientOptions(api_endpoint=endpoint)
ml = discovery.build('ml', 'v1', client_options=client_options)

request_body = { 'instances': INSTANCES }
request = ml.projects().predict(
    name='projects/PROJECT_ID/models/MODEL_NAME/VERSION_NAME',
    body=request_body)

response = request.execute()
print(response)

No código, substitua os seguintes marcadores:

  • REGION: a região do endpoint que você usou nas seções anteriores.
  • INSTANCES: uma lista de instâncias de entrada de previsão.
  • MODEL_NAME: o nome do modelo que você criou em uma seção anterior.
  • VERSION_NAME: o nome da versão que você criou na seção anterior.

Saiba mais sobre como receber previsões on-line.

A seguir