A previsão on-line da Vertex AI é um serviço otimizado que executa dados em modelos hospedados com a menor latência possível. Você envia pequenos lotes de dados para o serviço e ele retorna as previsões na resposta.
Antes de começar
Antes de solicitar previsões:
Treine o modelo. No código de treinamento, exporte os artefatos do modelo treinado como um ou mais artefatos do modelo que possam ser implantados na Vertex AI.
Implante na Vertex AI o modelo treinado. Para isso, faça o upload dos artefatos do modelo e implante o modelo em um endpoint da Vertex AI.
Configurar a implantação do modelo
Durante a implantação do modelo, você toma as seguintes decisões importantes sobre como executar a previsão on-line:
Recurso criado | Configuração especificada na criação de recursos |
---|---|
Endpoint | Local onde executar predições |
Modelo | Contêiner a ser usado (ModelContainerSpec ) |
DeployedModel | Máquinas para usar na previsão on-line |
Não é possível atualizar as configurações listadas acima após a criação inicial do modelo ou do endpoint. Não é possível modificá-las na solicitação de previsão on-line. Se você precisar alterar essas configurações, é necessário reimplantar o modelo.
Formatar a entrada para previsão on-line
Se você estiver usando um dos nossos contêineres pré-criados para disponibilizar predições usando o TensorFlow, o scikit-learn ou o XGBoost, as instâncias de entrada da previsão precisarão ser formatadas como JSON.
Se o modelo usa um contêiner personalizado, a entrada
precisa ser formatada como JSON e há um campo parameters
extra que pode ser usado para o contêiner. Saiba mais sobre
como formatar a entrada de previsão com contêineres personalizados.
Nesta seção, você verá como formatar instâncias de entrada de previsão como JSON e como processar dados binários com a codificação base64.
Formatar instâncias como strings JSON
O formato básico da previsão on-line é uma lista de instâncias de dados. Ela pode ser uma lista simples de valores ou membros de um objeto JSON, dependendo de como você configurou as entradas no aplicativo de treinamento. Os modelos do TensorFlow aceitam entradas mais complexas, enquanto a maioria dos modelos do scikit-learn e do XGBoost esperam uma lista de números como entrada.
Este exemplo mostra um Tensor de entrada e uma chave de instância para a um modelo do TensorFlow:
{"values": [1, 2, 3, 4], "key": 1}
A composição da string JSON pode ser complexa, contanto que siga estas regras:
O nível superior dos dados da instância precisa ser um objeto JSON, um dicionário de pares de chave-valor.
Os valores individuais em um objeto de instância podem ser strings, números ou listas. Não é possível incorporar objetos JSON.
As listas devem conter apenas itens do mesmo tipo (incluindo outras listas). Não é possível misturar strings e valores numéricos.
Transmita as instâncias de entrada para previsão on-line como o corpo da mensagem da chamada projects.locations.endpoints.predict
. Saiba mais sobre os
requisitos de formatação do corpo da solicitação.
Torne cada instância um item em uma matriz JSON e forneça a matriz como o
campo instances
de um objeto JSON. Exemplo:
{"instances": [
{"values": [1, 2, 3, 4], "key": 1},
{"values": [5, 6, 7, 8], "key": 2}
]}
Codificar dados binários para entrada de previsão
Os dados binários não podem ser formatados como as strings codificadas em UTF-8 compatíveis com o JSON. Se houver dados binários nas entradas, é preciso usar a codificação base64 para representá-los. É necessária a seguinte formatação especial:
Sua string codificada precisa ser formatada como um objeto JSON com uma única chave chamada
b64
. No Python 3, a codificação base64 gera uma sequência de bytes. É preciso converter essa sequência em uma string para torná-la serializável em JSON:{'image_bytes': {'b64': base64.b64encode(jpeg_data).decode()}}
No código de modelo TensorFlow, é preciso nomear os aliases dos seus tensores binários de entrada e saída para que terminem com "_bytes".
Exemplos de solicitação e resposta
Nesta seção, descreveremos o formato do corpo da solicitação de previsão e da resposta, com exemplos para TensorFlow, scikit-learn e XGBoost.
Detalhes do corpo da solicitação
TensorFlow
O corpo da solicitação contém dados com a seguinte estrutura na representação JSON:
{
"instances": [
<value>|<simple/nested list>|<object>,
...
]
}
O objeto instances[]
é obrigatório e precisa conter a lista de instâncias para as quais você receberá previsões.
A estrutura de cada elemento da lista é determinada pela definição de entrada do modelo. As instâncias podem incluir entradas nomeadas, como objetos, ou conter apenas valores sem rótulo.
Nem todos os dados incluem entradas nomeadas. Algumas instâncias são valores JSON simples como booleanos, números ou strings. No entanto, as instâncias costumam ser listas de valores simples ou listas aninhadas complexas.
Veja abaixo alguns exemplos de corpo de solicitação.
Dados CSV com cada linha codificada como um valor de string:
{"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}
Texto simples:
{"instances": ["the quick brown fox", "the lazy dog"]}
Frases codificadas como listas de palavras (vetores de strings):
{ "instances": [ ["the","quick","brown"], ["the","lazy","dog"], ... ] }
Valores de ponto flutuante escalares:
{"instances": [0.0, 1.1, 2.2]}
Vetores de números inteiros:
{ "instances": [ [0, 1, 2], [3, 4, 5], ... ] }
Tensores (neste caso, bidimensionais):
{ "instances": [ [ [0, 1, 2], [3, 4, 5] ], ... ] }
Imagens, que podem ser representadas de maneiras diferentes. Neste esquema de codificação, as duas primeiras dimensões representam as linhas e colunas da imagem. Já a terceira dimensão contém listas (vetores) dos valores R, G e B de cada pixel:
{ "instances": [ [ [ [138, 30, 66], [130, 20, 56], ... ], [ [126, 38, 61], [122, 24, 57], ... ], ... ], ... ] }
Codificação de dados
As strings JSON precisam ser codificadas em UTF-8. Para enviar dados binários, é necessário codificar os dados em base64 e marcá-los como binários. Para marcar uma string JSON como binária, substitua-a por um objeto JSON com um único atributo denominado b64
:
{"b64": "..."}
O exemplo a seguir mostra duas instâncias tf.Examples
serializadas, que exigem codificação base64 (dados falsos, apenas para fins ilustrativos):
{"instances": [{"b64": "X5ad6u"}, {"b64": "IA9j4nx"}]}
O exemplo a seguir mostra duas strings de byte de imagem JPEG que exigem a codificação base64 (dados meramente ilustrativos):
{"instances": [{"b64": "ASa8asdf"}, {"b64": "JLK7ljk3"}]}
Vários tensores de entrada
Alguns modelos têm um gráfico subjacente do TensorFlow que aceita vários tensores de entrada. Nesse caso, use os nomes dos pares JSON de nome/valor para identificar esses tensores:
Para um gráfico com os aliases de tensor de entrada "tag" (string) e "image" (string codificada em Base64), use o seguinte:
{ "instances": [ { "tag": "beach", "image": {"b64": "ASa8asdf"} }, { "tag": "car", "image": {"b64": "JLK7ljk3"} } ] }
Para um gráfico com os aliases de tensor de entrada "tag" (string) e "image" (matriz tridimensional com ints de 8 bits), use o seguinte:
{ "instances": [ { "tag": "beach", "image": [ [ [138, 30, 66], [130, 20, 56], ... ], [ [126, 38, 61], [122, 24, 57], ... ], ... ] }, { "tag": "car", "image": [ [ [255, 0, 102], [255, 0, 97], ... ], [ [254, 1, 101], [254, 2, 93], ... ], ... ] }, ... ] }
scikit-learn
O corpo da solicitação contém dados com a seguinte estrutura na representação JSON:
{
"instances": [
<simple list>,
...
]
}
O objeto instances[]
é obrigatório e precisa conter a lista de instâncias para as quais você receberá previsões. No exemplo a seguir, cada instância de entrada é uma lista de floats:
{
"instances": [
[0.0, 1.1, 2.2],
[3.3, 4.4, 5.5],
...
]
}
A dimensão das instâncias de entrada precisa corresponder ao que seu modelo espera. Por exemplo, se o modelo precisar de três recursos, o comprimento de cada instância de entrada será 3.
XGBoost
O corpo da solicitação contém dados com a seguinte estrutura na representação JSON:
{
"instances": [
<simple list>,
...
]
}
O objeto instances[]
é obrigatório e precisa conter a lista de instâncias para as quais você receberá previsões. No exemplo a seguir, cada instância de entrada é uma lista de floats:
{
"instances": [
[0.0, 1.1, 2.2],
[3.3, 4.4, 5.5],
...
]
}
A dimensão das instâncias de entrada precisa corresponder ao que seu modelo espera. Por exemplo, se o modelo precisar de três recursos, o comprimento de cada instância de entrada será 3.
A Vertex AI não é compatível com a representação esparsa de instâncias de entrada para XGBoost.
O serviço de previsão on-line interpreta zeros e NaN
s de maneira diferente. Se o valor de um recurso for zero, use 0.0
na entrada correspondente. Se o valor de um elemento estiver ausente, use "NaN"
na entrada correspondente.
O exemplo a seguir representa uma solicitação de previsão com uma única instância de entrada, em que o valor do primeiro recurso é 0.0, o valor do segundo recurso é 1.1 e o valor do terceiro está ausente:
{"instances": [[0.0, 1.1, "NaN"]]}
Detalhes do corpo da resposta
As respostas são muito semelhantes às solicitações.
Se a chamada for bem-sucedida, o corpo da resposta terá uma entrada de previsão por instância no corpo da solicitação, dadas na mesma ordem:
{
"predictions": [
{
object
}
],
"deployedModelId": string
}
Se a previsão falhar em qualquer instância, o corpo da resposta não terá previsões. Em vez disso, ele inclui uma única entrada de erro:
{
"error": string
}
O objeto predictions[]
contém a lista de previsões, uma para cada instância na solicitação.
Em caso de erro, a string error
contém uma mensagem descrevendo o problema. Se ocorrer um erro durante o processamento de qualquer instância, ele será retornado em vez de uma lista de previsão.
Há uma previsão por instância, mas o formato da previsão não está diretamente relacionado ao da instância. As previsões recebem o formato especificado no conjunto de saídas definido no modelo. O conjunto de previsões é retornado em uma lista JSON. Cada membro da lista pode ser um valor simples, uma lista ou um objeto JSON de qualquer complexidade. Caso seu modelo tenha mais de um tensor de saída, cada previsão será um objeto JSON que contém um par de nome/valor para cada saída. Os nomes identificam os aliases de saída no gráfico.
Exemplos de corpo de resposta
TensorFlow
Nos exemplos a seguir, mostramos algumas respostas possíveis:
-
Conjunto simples de previsões de três instâncias de entrada, em que cada previsão é um valor inteiro:
{"predictions": [5, 4, 3], "deployedModelId": 123456789012345678 }
-
Um conjunto mais complexo de previsões, cada uma contendo dois valores nomeados que correspondem aos tensores de saída, denominados
label
escores
, respectivamente. O valor delabel
é a categoria prevista ("carro" ou "praia") escores
contém uma lista de probabilidades para essa instância nas categorias possíveis.{ "predictions": [ { "label": "beach", "scores": [0.1, 0.9] }, { "label": "car", "scores": [0.75, 0.25] } ], "deployedModelId": 123456789012345678 }
-
Resposta quando há um erro ao processar uma instância de entrada:
{"error": "Divide by zero"}
scikit-learn
Nos exemplos a seguir, mostramos algumas respostas possíveis:
-
Conjunto simples de previsões de três instâncias de entrada, em que cada previsão é um valor inteiro:
{"predictions": [5, 4, 3], "deployedModelId": 123456789012345678 }
-
Resposta quando há um erro ao processar uma instância de entrada:
{"error": "Divide by zero"}
XGBoost
Nos exemplos a seguir, mostramos algumas respostas possíveis:
-
Conjunto simples de previsões de três instâncias de entrada, em que cada previsão é um valor inteiro:
{"predictions": [5, 4, 3], "deployedModelId": 123456789012345678 }
-
Resposta quando há um erro ao processar uma instância de entrada:
{"error": "Divide by zero"}
Enviar uma solicitação de previsão on-line
Para solicitar uma previsão on-line, envie instâncias de dados de entrada, como uma string JSON, em uma solicitação de previsão. Para formatar o corpo da solicitação e da resposta, consulte os detalhes da solicitação de previsão.
Se o modelo for implantado em um endpoint público, cada solicitação de previsão precisará ter 1,5 MB ou menos.
gcloud
O exemplo a seguir usa o comando
gcloud ai endpoints predict
:
Grave o objeto JSON a seguir para o arquivo no ambiente local. O nome de arquivo não importa, mas, nesse exemplo, o nome é
request.json
.{ "instances": INSTANCES }
Substitua:
- INSTANCES: uma matriz JSON de instâncias para as quais você quer receber previsões. O formato de cada instância depende das entradas que o modelo de ML treinado específico espera. Consulte a seção Como formatar sua entrada para previsão on-line deste documento.
Execute este comando:
gcloud ai endpoints predict ENDPOINT_ID \ --region=LOCATION \ --json-request=request.json
Substitua:
- ENDPOINT_ID: o ID do endpoint.
- LOCATION: a região em que você está usando a Vertex AI.
REST e linha de comando
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- LOCATION: a região em que você está usando a Vertex AI.
- PROJECT: o ID do projeto
- ENDPOINT_ID: o ID do endpoint.
- INSTANCES: uma matriz JSON de instâncias para as quais você quer receber previsões. O formato de cada instância depende das entradas que o modelo de ML treinado específico espera. Consulte a seção Como formatar sua entrada para previsão on-line deste documento.
Método HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:predict
Corpo JSON da solicitação:
{ "instances": INSTANCES }
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo chamado request.json
e execute o comando a seguir:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:predict"
PowerShell
Salve o corpo da solicitação em um arquivo chamado request.json
e execute o comando a seguir:
$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:predict" | Select-Object -Expand Content
- PREDICTIONS: uma matriz JSON de previsões, uma para cada instância incluída no corpo da solicitação.
-
DEPLOYED_MODEL_ID: o ID do
DeployedModel
que veiculou essas previsões.
{ "predictions": PREDICTIONS, "deployedModelId": "DEPLOYED_MODEL_ID" }
Java
Para saber como instalar e usar a biblioteca de cliente para Vertex AI, consulte Bibliotecas de cliente Vertex AI. Para mais informações, consulte a documentação de referência da API Vertex AI para PythonJava.
Node.js
Para saber como instalar e usar a biblioteca de cliente para Vertex AI, consulte Bibliotecas de cliente Vertex AI. Para mais informações, consulte a documentação de referência da API Vertex AI para PythonNode.js.
Python
Para saber como instalar e usar a biblioteca de cliente para Vertex AI, consulte Bibliotecas de cliente Vertex AI. Para mais informações, consulte a documentação de referência da API Vertex AI para PythonPython.
Enviar uma solicitação de previsão bruta on-line
Outra opção é enviar uma solicitação de previsão bruta. Ela permite que você use um payload HTTP arbitrário em vez de seguir as diretrizes rígidas descritas nas seções anteriores deste guia.
É possível receber previsões brutas se você estiver usando um contêiner personalizado que recebe solicitações e envia respostas diferentes das diretrizes.
gcloud
O exemplo a seguir usa o comando
gcloud ai endpoints raw-predict
:
-
Para solicitar previsões com o objeto JSON em REQUEST especificado na linha de comando:
gcloud ai endpoints raw-predict ENDPOINT_ID \ --region=LOCATION \ --request REQUEST
-
Para solicitar previsões com uma imagem armazenada no arquivo image.jpeg e no cabeçalho
Content-Type
apropriado:gcloud ai endpoints raw-predict ENDPOINT_ID \ --region=LOCATION \ --http-headers=Content-Type=image/jpeg \ --request @image.jpeg
Substitua:
- ENDPOINT_ID: o ID do endpoint.
- LOCATION: a região em que você está usando a Vertex AI.
- REQUEST: o conteúdo da solicitação para a qual você quer receber previsões. O formato da solicitação depende do que o contêiner personalizado espera, que talvez não seja necessariamente um objeto JSON.
A resposta inclui os seguintes cabeçalhos HTTP:
X-Vertex-AI-Endpoint-Id
: ID doEndpoint
que exibiu essa previsão.X-Vertex-AI-Deployed-Model-Id
: ID doDeployedModel
do endpoint que exibiu essa previsão.
Enviar uma solicitação de explicação on-line
Se você tiver configurado seu Model
para
Vertex Explainable AI, será possível
receber explicações on-line. As solicitações de explicação on-line
têm o mesmo formato que as solicitações de previsão on-line e retornam respostas
semelhantes. A única diferença é que as respostas de explicação on-line incluem
atribuições de recursos, bem como previsões.
Os exemplos a seguir são quase idênticos aos da seção anterior, mas usam comandos um pouco diferentes:
gcloud
O exemplo a seguir usa o comando
gcloud ai endpoints explain
:
Grave o objeto JSON a seguir para o arquivo no ambiente local. O nome de arquivo não importa, mas, nesse exemplo, o nome é
request.json
.{ "instances": INSTANCES }
Substitua:
- INSTANCES: uma matriz JSON de instâncias para as quais você quer receber previsões. O formato de cada instância depende das entradas que o modelo de ML treinado específico espera. Consulte a seção Como formatar sua entrada para previsão on-line deste documento.
Execute este comando:
gcloud ai endpoints explain ENDPOINT_ID \ --region=LOCATION \ --json-request=request.json
Substitua:
- ENDPOINT_ID: o ID do endpoint.
- LOCATION: a região em que você está usando a Vertex AI.
Opcionalmente, se você quiser enviar uma solicitação de explicação para um
DeployedModel
específico emEndpoint
, especifique a sinalização--deployed-model-id
:gcloud ai endpoints explain ENDPOINT_ID \ --region=LOCATION \ --deployed-model-id=DEPLOYED_MODEL_ID \ --json-request=request.json
Além dos marcadores de posição descritos anteriormente, substitua o seguinte:
-
DEPLOYED_MODEL_ID (opcional): o ID do modelo implantado que você quer obter explicações. O ID está incluído na resposta do método
predict
. Se você precisar solicitar explicações para um modelo específico e tiver mais de um modelo implantado no mesmo endpoint, use esse ID para garantir que as explicações sejam retornadas.
REST e LINHA DE CMD
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- LOCATION: a região em que você está usando a Vertex AI.
- PROJECT: o ID do projeto
- ENDPOINT_ID: o ID do endpoint.
- INSTANCES: uma matriz JSON de instâncias para as quais você quer receber previsões. O formato de cada instância depende das entradas que o modelo de ML treinado específico espera. Consulte a seção Como formatar sua entrada para previsão on-line deste documento.
Método HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:explain
Corpo JSON da solicitação:
{ "instances": INSTANCES }
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo chamado request.json
e execute o comando a seguir:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:explain"
PowerShell
Salve o corpo da solicitação em um arquivo chamado request.json
e execute o comando a seguir:
$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:explain" | Select-Object -Expand Content
- PREDICTIONS: uma matriz JSON de previsões, uma para cada instância incluída no corpo da solicitação.
- EXPLANATIONS: uma matriz JSON de explicações, uma para cada previsão.
-
DEPLOYED_MODEL_ID: o ID do
DeployedModel
que veiculou essas previsões.
{ "predictions": PREDICTIONS, "explanations": EXPLANATIONS, "deployedModelId": "DEPLOYED_MODEL_ID" }
Python
Para saber como instalar e usar a biblioteca de cliente para Vertex AI, consulte Bibliotecas de cliente Vertex AI. Para mais informações, consulte a documentação de referência da API Vertex AI para PythonPython.