Rotular imagens usando a API AutoML Vision

Este guia de início rápido aborda os seguintes processos:

  • Copiar imagens e caixas delimitadoras de listagem CSV com marcadores no Google Cloud Storage.
  • Usar o AutoML Vision Object Detection para criar seu conjunto de dados e treinar e implantar seu modelo.

Neste guia de início rápido, você usa comandos cURL para enviar solicitações à API AutoML Vision. Também é possível concluir todas as etapas listadas aqui na interface do usuário consultando o Guia de início rápido usando a interface do usuário. Veja mais instruções sobre como usar a IU ou a API nos guias de instruções.

Antes de começar

Configurar o projeto

  1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.
  2. Instale a CLI do Google Cloud.

  3. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init

  4. Crie ou selecione um projeto do Google Cloud.

    • Crie um projeto do Google Cloud:

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por um nome para o projeto do Google Cloud que você está criando.

    • Selecione o projeto do Google Cloud que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do projeto do Google Cloud.

  5. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

  6. Ative as APIs AutoML and Cloud Storage: 

    gcloud services enable storage-component.googleapis.com automl.googleapis.com storage-api.googleapis.com
    7.
  7. Instale a CLI do Google Cloud.

  8. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init

  9. Crie ou selecione um projeto do Google Cloud.

    • Crie um projeto do Google Cloud:

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por um nome para o projeto do Google Cloud que você está criando.

    • Selecione o projeto do Google Cloud que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do projeto do Google Cloud.

  10. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

  11. Ative as APIs AutoML and Cloud Storage: 

    gcloud services enable storage-component.googleapis.com automl.googleapis.com storage-api.googleapis.com
    12.
  12. Defina a variável de ambiente PROJECT_ID como seu ID do projeto. 
    export PROJECT_ID=PROJECT_ID
    As chamadas de API AutoML e os nomes dos recursos incluem seu código do projeto. A variável de ambiente PROJECT_ID é uma maneira conveniente de especificar o ID.

Como preparar um conjunto de dados

Neste guia de início rápido, você usa um conjunto de dados criado no Open Images Dataset V4 (em inglês). Esse conjunto de dados "Saladas" está disponível ao público em gs://cloud-ml-data/img/openimage/csv/salads_ml_use.csv.

O formato CSV é o seguinte:

TRAINING,gs://cloud-ml-data/img/openimage/3/2520/3916261642_0a504acd60_o.jpg,Salad,0.0,0.0954,,,0.977,0.957,,
VALIDATION,gs://cloud-ml-data/img/openimage/3/2520/3916261642_0a504acd60_o.jpg,Seafood,0.0154,0.1538,,,1.0,0.802,,
TEST,gs://cloud-ml-data/img/openimage/3/2520/3916261642_0a504acd60_o.jpg,Tomato,0.0,0.655,,,0.231,0.839,,
Exemplo de imagem do conjunto de dados
3916261642_0a504acd60_o.jpg

Cada linha corresponde a um objeto localizado em uma imagem maior. Cada objeto é designado especificamente como dados de teste, treinamento ou validação. As três linhas incluídas nesta página indicam três objetos diferentes localizados na mesma imagem disponível em gs://cloud-ml-data/img/openimage/3/2520/3916261642_0a504acd60_o.jpg. Cada linha tem um rótulo diferente: Salad, Seafood e Tomato, além de outras linhas com rótulos Baked goods ou Cheese.

As caixas delimitadoras são especificadas em cada imagem usando os vértices superior à esquerda e inferior à direita:

  • (0,0) corresponde ao vértice superior à esquerda.
  • (1,1) corresponde ao vértice inferior à direita.

Na primeira linha mostrada acima, as coordenadas (x, y) do vértice superior à esquerda do objeto com o rótulo Salad são (0.0,0.0954). Já as coordenadas do vértice inferior à direita do objeto são (0.977,0.957).

Para informações mais detalhadas sobre como formatar o arquivo CSV e os requisitos mínimos para criar um conjunto de dados válido, consulte Como preparar os dados de treinamento.


Crie um conjunto de dados e importe dados de treinamento

O comando curl usa o comando gcloud auth print-access-token para receber um token de acesso da sua Conta do Google.

Para a versão Beta, use us-central1 como a região, independentemente da localização real.

Criar um conjunto de dados

Use o comando curl a seguir para criar um conjunto de dados novo com o nome de exibição que você quiser:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json" \
"https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/datasets" -d '{
    "display_name": "DISPLAY_NAME",
    "image_object_detection_dataset_metadata": {
    }
}'

A resposta retorna um ID de conjunto de dados relativo (como IOD5491013845671477445) que será necessário nas etapas a seguir.

{
  "name": "projects/PROJECT_ID/locations/us-central1/datasets/IOD5491013845671477445",
  "displayName": "DISPLAY_NAME",
  "createTime": "2018-10-29T15:45:53.353442Z",
  "imageObjectDetectionDatasetMetadata": {}
}

Importar dados

Importe os dados de treinamento para o conjunto de dados. O comando importData toma como entrada o URI do conjunto de dados. Aqui, você fornecerá o endereço do Google Cloud Storage disponível publicamente em que o conjunto de dados "Salads" está armazenado. Esse processo pode levar até 30 minutos.

  • Substitua DATASET_ID pelo identificador do conjunto de dados (e não pelo nome de exibição). Por exemplo, IOD5491013845671477445.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/datasets/DATASET_ID:importData \
-d '{
  "input_config": {
    "gcs_source": {
       "input_uris": [
         "gs://cloud-ml-data/img/openimage/csv/salads_ml_use.csv"
        ]
    }
  }
}'

A resposta retorna um ID de operação relativo (por exemplo, IOD1555149246326374411) que pode ser usado para ver o status da operação.

{
  "name": "projects/PROJECT_NUMBER/locations/us-central1/operations/IOD1555149246326374411",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.automl.v1beta1.OperationMetadata",
    "createTime": "2018-10-29T15:56:29.176485Z",
    "updateTime": "2018-10-29T15:56:29.176485Z",
    "importDataDetails": {}
  }
}

Ver o status da operação de importação

Consulte o status da operação de importação de dados usando o seguinte comando curl.

  • Substitua OPERATION_ID pelo ID de operação retornado da operação de importação de dados.
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID

Essa operação pode levar algum tempo para ser concluída. Quando a tarefa de importação for concluída, você verá done: true no status da operação sem erros listados, conforme mostrado no exemplo a seguir.

Essa solicitação também retornará todos os avisos para a importação do conjunto de dados. Foram adicionados erros a este conjunto de dados para mostrar um exemplo desses avisos. Usar essa operação para ver esses avisos é uma forma útil de encontrar erros nos dados.

{
  "name": "projects/PROJECT_NUMBER/locations/us-central1/operations/IOD1555149246326374411",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.automl.v1beta1.OperationMetadata",
    "createTime": "2018-10-29T15:56:29.176485Z",
    "updateTime": "2018-10-29T16:10:41.326614Z",
    "importDataDetails": {}
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Receber uma lista de conjuntos de dados

Receba uma lista dos conjuntos de dados usando o comando a seguir.

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/datasets

O resultado será assim:

{
  "datasets": [
    {
      "name": "projects/PROJECT_NUMBER/locations/us-central1/datasets/DATASET_ID1",
      "displayName": "DISPLAY_NAME1",
      "createTime": "2018-10-29T15:45:53.353442Z",
      "exampleCount": 227,
      "imageObjectDetectionDatasetMetadata": {}
    },
    {
      "name": "projects/PROJECT_NUMBER/locations/us-central1/datasets/DATASET_ID2",
      "displayName": "DISPLAY_NAME2",
      "createTime": "2018-10-24T21:06:05.390059Z",
      "exampleCount": 227,
      "imageObjectDetectionDatasetMetadata": {}
    }
  ]
}

Treinar o modelo

Iniciar um aplicativo de treinamento de modelo

Depois de criar o conjunto de dados e importar seus dados de treinamento para seu conjunto de dados, você poderá treinar seu modelo personalizado.

Treine seu modelo usando o comando curl a seguir.

  • Substitua DATASET_ID pelo identificador do conjunto de dados (e não pelo nome de exibição).
  • Substitua DISPLAY_NAME por um nome escolhido para o modelo.
  • Especifique image_object_detection_model_metadata.model_type. Duas opções disponíveis são otimizar a latência ou a acurácia:
    • cloud-low-latency-1: otimiza o treinamento para diminuir a latência.
    • cloud-high-accuracy-1: otimiza o treinamento para aumentar a acurácia.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/models -d '{
  "datasetId": "DATASET_ID",
  "displayName": "DISPLAY_NAME",
  "image_object_detection_model_metadata": {},
}'

Você receberá um ID de operação do modelo de treinamento (por exemplo, IOD5644417707978784777), que poderá ser usado para verificar o status da operação de treinamento.

{
  "name": "projects/PROJECT_NUMBER/locations/us-central1/operations/IOD5644417707978784777",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.automl.v1beta1.OperationMetadata",
    "createTime": "2018-10-29T16:41:23.902167Z",
    "updateTime": "2018-10-29T16:41:23.902167Z",
    "createModelDetails": {}
  }
}

O processo de treinamento pode levar várias horas para ser concluído.

Ver o status da operação de treinamento do modelo

Consulte o status da operação de treinamento de modelo usando o seguinte comando curl.

  • Substitua OPERATION_ID pelo ID da operação de treinamento.
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID

Será exibido um código semelhante a este. Quando a operação estiver concluída, você verá done: true sem erros listados.


{
  "name": "projects/PROJECT_NUMBER/locations/us-central1/operations/IOD5644417707978784777",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.automl.v1beta1.OperationMetadata",
    "createTime": "2018-10-24T22:08:23.327323Z",
    "updateTime": "2018-10-24T23:41:18.452855Z",
    "createModelDetails": {}
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.automl.v1beta1.Model",
    "name": "projects/PROJECT_NUMBER/locations/us-central1/models/IOD5644417707978784777"
  }
}

Verificar se o modelo está disponível

Após a operação de treinamento de modelo ser concluída com sucesso, você pode verificar que o modelo está disponível usando o comando a seguir para listar os modelos do seu projeto.

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/models

Você receberá um ID de modelo (por exemplo, IOD5644417707978784778), que poderá ser usado para conseguir as métricas de avaliação do modelo quando o modelo tiver concluído o treinamento. A resposta será assim:

{
  "model": [
    {
      "name": "projects/PROJECT_NUMBER/locations/us-central1/models/IOD5644417707978784778",
      "displayName": "DISPLAY_NAME",
      "datasetId": "IOD5491013845671477445",
      "createTime": "2018-10-24T23:37:00.858493Z",
      "updateTime": "2018-10-24T23:37:00.858493Z",
      "deploymentState": "DEPLOYED",
      "imageObjectDetectionModelMetadata": {
          "modelType": "cloud-low-latency-1",
          "nodeCount": "1",
          "nodeQps": 1.2987012987012987
      }
    }
  ]
}

Avaliar o modelo

Depois que o modelo terminar o treinamento, será possível listar as métricas de avaliação do modelo usando o seguinte comando curl.

  • Substitua MODEL_ID pelo identificador do modelo.
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/models/MODEL_ID/modelEvaluations

O AutoML Vision Object Detection oferece um conjunto agregado de métricas de avaliação que indica o desempenho geral do modelo, bem como métricas de avaliação de cada rótulo, indicando o desempenho do modelo nesse rótulo em diferentes limites.

Implantar seu modelo

Antes de fazer uma previsão, implante manualmente seu modelo.

Use o comando a seguir para implantar seu modelo:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "x-goog-user-project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/models/MODEL_ID:deploy \
  -d '{
      "imageObjectDetectionModelDeploymentMetadata": {
        "nodeCount": 2
      }
    }'

Fazer uma previsão

Enviar uma solicitação de previsão

É possível usar seu modelo implantado para fazer uma previsão em uma imagem local usando o arquivo JSON e o seguinte comando curl.

  • Crie um arquivo JSON de solicitação chamado predict_request.json e forneça uma imagem codificada em base64 no campo "imageBytes".

predict_request.json 

{
    "payload": {
        "image": {
            "image_bytes": "/9j/4QAYRXhpZgAA...base64-encoded-image...9tAVx/zDQDlGxn//2Q=="
        }
    }
}

  • Substitua MODEL_ID pelo identificador do modelo.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json" \
"https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/models/MODEL_ID:predict" -d @PATH_TO_JSON_FILE/predict_request.json

Uma solicitação bem-sucedida retorna uma resposta com uma ou mais caixas delimitadoras especificadas por dois normalizedVertices diagonalmente opostos. Cada caixa delimitadora identificada tem uma score de confiança e uma anotação (displayName) associadas.

{
  "payload": [
    {
      "imageObjectDetection": {
        "boundingBox": {
          "normalizedVertices": [
            {
              "x": 0.034553755,
              "y": 0.015524037
            },
            {
              "x": 0.941527,
              "y": 0.9912563
            }
          ]
        },
        "score": 0.9997793
      },
      "displayName": "Salad"
    },
    {
      "imageObjectDetection": {
        "boundingBox": {
          "normalizedVertices": [
            {
              "x": 0.11737197,
              "y": 0.7098793
            },
            {
              "x": 0.510878,
              "y": 0.87987
            }
          ]
        },
        "score": 0.63219965
      },
      "displayName": "Tomato"
    }
  ]
}

Remover a implantação do modelo (opcional)

O modelo gera cobranças enquanto está implantado. Para evitar esse custo pela hospedagem do modelo, remova a implantação do modelo.

Execute o comando a seguir para remover a implantação do modelo:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "x-goog-user-project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  "https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/models/MODEL_ID:undeploy"

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados nesta página, exclua o projeto do Google Cloud com esses recursos.

Se você não precisa mais do modelo personalizado e o respectivo conjunto de dados, é possível excluí-los.

Listar modelos

Você pode listar os modelos do projeto, junto seus identificadores, usando o comando a seguir:

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/models

Excluir um modelo

Você pode excluir um modelo usando o comando a seguir.

  • Substitua MODEL_ID pelo identificador do modelo.
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/models/MODEL_ID

Listar conjuntos de dados

Você pode listar os conjuntos de dados do projeto, junto com os identificadores, usando o comando a seguir:

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/datasets

Excluir um conjunto de dados

Você pode excluir um conjunto de dados usando o comando a seguir.

  • Substitua DATASET_ID pelo identificador do modelo.
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json" \
https://automl.googleapis.com/v1beta1/projects/PROJECT_ID/locations/us-central1/datasets/DATASET_ID

A seguir