Esta página mostra-lhe como obter inferências online (em tempo real) dos seus modelos com preparação personalizada através da CLI Google Cloud ou da API Vertex AI.
Formate a sua entrada para inferência online
Esta secção mostra como formatar e codificar as suas instâncias de entrada de inferência como JSON, o que é necessário se estiver a usar o método predict
ou explain
. Este passo não é obrigatório
se usar o método rawPredict
. Para obter informações sobre o método a escolher, consulte o artigo Enviar pedido para o
ponto final.
Se estiver a usar o SDK do Vertex AI para Python para enviar pedidos de inferência, especifique a lista de instâncias sem o campo instances
. Por exemplo, especifique [
["the","quick","brown"], ... ]
em vez de { "instances": [
["the","quick","brown"], ... ] }
.
Se o seu modelo usar um contentor personalizado, a entrada tem de estar formatada como JSON e existe um campo parameters
adicional que pode ser usado para o seu contentor. Saiba mais sobre a entrada de inferência de formato
com contentores personalizados.
Formate instâncias como strings JSON
O formato básico para a inferência online é uma lista de instâncias de dados. Podem ser listas simples de valores ou membros de um objeto JSON, consoante a forma como configurou as entradas na sua aplicação de preparação. Os modelos do TensorFlow podem aceitar entradas mais complexas, enquanto a maioria dos modelos do scikit-learn e do XGBoost espera uma lista de números como entrada.
Este exemplo mostra um tensor de entrada e uma chave de instância para um modelo do TensorFlow:
{"values": [1, 2, 3, 4], "key": 1}
A composição da string JSON pode ser complexa, desde que siga estas regras:
O nível superior dos dados de instâncias tem de ser um objeto JSON: um dicionário de pares de chave/valor.
Os valores individuais num objeto de instância podem ser strings, números ou listas. Não pode incorporar objetos JSON.
As listas só podem conter itens do mesmo tipo (incluindo outras listas). Não pode misturar valores de string e numéricos.
Transmite instâncias de entrada para a inferência online como o corpo da mensagem para a chamada projects.locations.endpoints.predict
. Saiba mais acerca dos requisitos de formatação do corpo do pedido.
Faça de cada instância um item numa matriz JSON e forneça a matriz como o campo instances
de um objeto JSON. Por exemplo:
{"instances": [
{"values": [1, 2, 3, 4], "key": 1},
{"values": [5, 6, 7, 8], "key": 2}
]}
Codifique dados binários para entrada de inferência
Não é possível formatar dados binários como as strings codificadas em UTF-8 que o JSON suporta. Se tiver dados binários nas suas entradas, tem de usar a codificação base64 para os representar. É necessária a seguinte formatação especial:
A string codificada tem de ser formatada como um objeto JSON com uma única chave denominada
b64
. No Python 3, a codificação base64 gera uma sequência de bytes. Tem de converter este valor numa string para o tornar serializável em JSON:{'image_bytes': {'b64': base64.b64encode(jpeg_data).decode()}}
No código do modelo do TensorFlow, tem de dar nomes aos alias dos tensores de entrada e saída binários para que terminem com "_bytes".
Exemplos de pedidos e respostas
Esta secção descreve o formato do corpo do pedido de inferência e do corpo da resposta, com exemplos para o TensorFlow, o scikit-learn e o XGBoost.
Detalhes do corpo do pedido
TensorFlow
O corpo do pedido contém dados com a seguinte estrutura (representação JSON):
{
"instances": [
<value>|<simple/nested list>|<object>,
...
]
}
O objeto instances[]
é obrigatório e tem de conter a lista de instâncias para obter inferências.
A estrutura de cada elemento da lista de instâncias é determinada pela definição de entrada do seu modelo. As instâncias podem incluir entradas com nome (como objetos) ou podem conter apenas valores sem etiqueta.
Nem todos os dados incluem entradas com nome. Algumas instâncias são valores JSON simples (booleanos, numéricos ou de string). No entanto, as instâncias são frequentemente listas de valores simples ou listas aninhadas complexas.
Seguem-se alguns exemplos de corpos de pedidos.
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 escalares de vírgula flutuante:
{"instances": [0.0, 1.1, 2.2]}
Vetores de números inteiros:
{ "instances": [ [0, 1, 2], [3, 4, 5], ... ] }
Tensores (neste caso, tensores bidimensionais):
{ "instances": [ [ [0, 1, 2], [3, 4, 5] ], ... ] }
Imagens, que podem ser representadas de diferentes formas. Neste esquema de codificação, as duas primeiras dimensões representam as linhas e as colunas da imagem e a terceira dimensão contém listas (vetores) dos valores R, G e B para cada píxel:
{ "instances": [ [ [ [138, 30, 66], [130, 20, 56], ... ], [ [126, 38, 61], [122, 24, 57], ... ], ... ], ... ] }
Codificação de dados
As strings JSON têm de ser codificadas como UTF-8. Para enviar dados binários, tem de
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 seguinte mostra duas instâncias serializadas de tf.Examples
, que requerem codificação base64 (dados falsos, apenas para fins
ilustrativos):
{"instances": [{"b64": "X5ad6u"}, {"b64": "IA9j4nx"}]}
O exemplo seguinte mostra duas strings de bytes de imagens JPEG, que requerem a codificação base64 (dados falsos, apenas para fins ilustrativos):
{"instances": [{"b64": "ASa8asdf"}, {"b64": "JLK7ljk3"}]}
Vários tensores de entrada
Alguns modelos têm um gráfico do TensorFlow subjacente que aceita vários tensores de entrada. Neste caso, use os nomes dos pares de nome/valor JSON para identificar os tensores de entrada.
Para um gráfico com aliases de tensores de entrada "tag" (string) e "image" (string codificada em base64):
{ "instances": [ { "tag": "beach", "image": {"b64": "ASa8asdf"} }, { "tag": "car", "image": {"b64": "JLK7ljk3"} } ] }
Para um gráfico com aliases de tensores de entrada "tag" (string) e "image" (matriz tridimensional de números inteiros de 8 bits):
{ "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 do pedido contém dados com a seguinte estrutura (representação JSON):
{
"instances": [
<simple list>,
...
]
}
O objeto instances[]
é obrigatório e tem de conter a lista de instâncias para obter inferências. No exemplo seguinte, cada instância de entrada é uma lista de números de vírgula flutuante:
{
"instances": [
[0.0, 1.1, 2.2],
[3.3, 4.4, 5.5],
...
]
}
A dimensão das instâncias de entrada tem de corresponder ao que o seu modelo espera. Por exemplo, se o seu modelo exigir três caraterísticas, o comprimento de cada instância de entrada tem de ser 3.
XGBoost
O corpo do pedido contém dados com a seguinte estrutura (representação JSON):
{
"instances": [
<simple list>,
...
]
}
O objeto instances[]
é obrigatório e tem de conter a lista de instâncias para obter inferências. No exemplo seguinte, cada instância de entrada é uma lista de números de vírgula flutuante:
{
"instances": [
[0.0, 1.1, 2.2],
[3.3, 4.4, 5.5],
...
]
}
A dimensão das instâncias de entrada tem de corresponder ao que o seu modelo espera. Por exemplo, se o seu modelo exigir três caraterísticas, o comprimento de cada instância de entrada tem de ser 3.
A Vertex AI não suporta a representação esparsa de instâncias de entrada para o XGBoost.
O serviço de inferência online interpreta os zeros e os NaN
s de forma diferente. Se o valor de uma funcionalidade for zero, use 0.0
na entrada correspondente. Se o valor de uma funcionalidade estiver em falta, use "NaN"
na entrada correspondente.
O exemplo seguinte representa um pedido de inferência com uma única instância de entrada, em que o valor da primeira caraterística é 0,0, o valor da segunda caraterística é 1,1 e o valor da terceira caraterística está em falta:
{"instances": [[0.0, 1.1, "NaN"]]}
PyTorch
Se o seu modelo usar um contentor pré-criado do PyTorch, os controladores predefinidos do TorchServe esperam que cada instância esteja envolvida num campo data
. Por exemplo:
{
"instances": [
{ "data": , <value> },
{ "data": , <value> }
]
}
Detalhes do corpo da resposta
Se a chamada for bem-sucedida, o corpo da resposta contém uma entrada de inferência por instância no corpo do pedido, apresentada na mesma ordem:
{
"predictions": [
{
object
}
],
"deployedModelId": string
}
Se a inferência falhar para qualquer instância, o corpo da resposta não contém inferências. Em alternativa, contém uma única entrada de erro:
{
"error": string
}
O objeto predictions[]
contém a lista de inferências, uma para cada instância no pedido.
Em caso de erro, a string error
contém uma mensagem que descreve o problema. O erro é devolvido em vez de uma lista de inferências se ocorrer um erro durante o processamento de qualquer instância.
Embora exista uma inferência por instância, o formato de uma inferência não está diretamente relacionado com o formato de uma instância. As inferências usam o formato especificado na coleção de resultados definida no modelo. A coleção de inferências é devolvida numa lista JSON. Cada membro da lista pode ser um valor simples, uma lista ou um objeto JSON de qualquer complexidade. Se o seu modelo tiver mais de um tensor de saída, cada inferência será um objeto JSON que contém um par nome-valor para cada saída. Os nomes identificam os alias de saída no gráfico.
Exemplos de corpos de respostas
TensorFlow
Os exemplos seguintes mostram algumas respostas possíveis:
-
Um conjunto simples de previsões para 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 com nomes que correspondem a tensores de saída, denominados
label
escores
, respetivamente. O valor delabel
é a categoria prevista ("carro" ou "praia") escores
contém uma lista de probabilidades para essa instância nas possíveis categorias.{ "predictions": [ { "label": "beach", "scores": [0.1, 0.9] }, { "label": "car", "scores": [0.75, 0.25] } ], "deployedModelId": 123456789012345678 }
-
Uma resposta quando existe um erro ao processar uma instância de entrada:
{"error": "Divide by zero"}
scikit-learn
Os exemplos seguintes mostram algumas respostas possíveis:
-
Um conjunto simples de previsões para três instâncias de entrada, em que cada previsão é um valor inteiro:
{"predictions": [5, 4, 3], "deployedModelId": 123456789012345678 }
-
Uma resposta quando existe um erro ao processar uma instância de entrada:
{"error": "Divide by zero"}
XGBoost
Os exemplos seguintes mostram algumas respostas possíveis:
-
Um conjunto simples de previsões para três instâncias de entrada, em que cada previsão é um valor inteiro:
{"predictions": [5, 4, 3], "deployedModelId": 123456789012345678 }
-
Uma resposta quando existe um erro ao processar uma instância de entrada:
{"error": "Divide by zero"}
Envie um pedido para um ponto final
Existem quatro formas de enviar uma solicitação:
Pedido de inferência: envie um pedido para
predict
para obter uma inferência online.Pedido de inferência não processado: envia um pedido para
rawPredict
, que lhe permite usar uma carga útil HTTP arbitrária em vez de seguir as diretrizes descritas nas secções Formate a sua entrada desta página. Pode ser útil obter inferências não processadas se:- Está a usar um contentor personalizado que recebe pedidos e envia respostas diferentes das diretrizes.
- Precisa de uma latência mais baixa.
rawPredict
ignora os passos de serialização e encaminha diretamente o pedido para o contentor de inferência. - Está a publicar inferências com o NVIDIA Triton.
Pedido de explicação: envia um pedido a
explain
. Se configurou o seuModel
para o Vertex Explainable AI, pode receber explicações online. Os pedidos de explicações online têm o mesmo formato que os pedidos de inferências online e devolvem respostas semelhantes. A única diferença é que as respostas de explicações online incluem atribuições de funcionalidades, bem como inferências.Invocar pedido: encaminha um pedido arbitrário para o servidor de modelos. Por exemplo, "/invoke/foo/bar" seria encaminhado como "/foo/bar" para o servidor do modelo. Esta funcionalidade está em pré-visualização pública e apenas suporta chamadas HTTP em pontos finais dedicados. Para criar um modelo com invocação ativada, siga as instruções para usar rotas personalizadas arbitrárias.
Envie um pedido de inferência online para um ponto final público dedicado
Os pontos finais dedicados facilitam a comunicação através dos protocolos HTTP e gRPC.
Para pedidos gRPC, a inclusão do cabeçalho x-vertex-ai-endpoint-id
é obrigatória para garantir a identificação precisa do ponto final. As seguintes APIs são suportadas através destes pontos finais dedicados:
- Prever
- RawPredict
- StreamRawPredict
- Conclusão de chat (apenas no Model Garden)
- Invocar
Os pontos finais dedicados usam um novo caminho de URL. Pode obter este caminho a partir do campo dedicatedEndpointDns
na API REST ou a partir de Endpoint.dedicated_endpoint_dns
no SDK Vertex AI para Python. Também pode
construir o caminho do ponto final manualmente através do seguinte código:
f"https://ENDPOINT_ID.LOCATION_ID-PROJECT_NUMBER.prediction.vertexai.goog/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict"
Substitua o seguinte:
- ENDPOINT_ID: o ID do ponto final.
- LOCATION_ID: a região onde está a usar o Vertex AI.
- PROJECT_NUMBER: o número do projeto. É diferente do ID do projeto. Pode encontrar o número do projeto na página Definições do projeto do Google Cloud projeto na consola.
Para enviar uma inferência para um ponto final dedicado através do SDK Vertex AI para Python,
defina o parâmetro use_dedicated_endpoint
como True
:
endpoint.predict(instances=instances, use_dedicated_endpoint=True)
Envie um pedido de inferência online para um ponto final público partilhado
gcloud
O exemplo seguinte usa o comando gcloud ai endpoints predict
:
Escreva o seguinte objeto JSON no ficheiro no seu ambiente local. O nome do ficheiro não é importante, mas, para este exemplo, atribua o nome
request.json
ao ficheiro.{ "instances": INSTANCES }
Substitua o seguinte:
- INSTANCES: uma matriz JSON de instâncias para as quais quer obter inferências. O formato de cada instância depende das entradas que o modelo de ML preparado espera. Para mais informações, consulte o artigo Formatar a entrada para inferência online.
Execute o seguinte comando:
gcloud ai endpoints predict ENDPOINT_ID \ --region=LOCATION_ID \ --json-request=request.json
Substitua o seguinte:
- ENDPOINT_ID: o ID do ponto final.
- LOCATION_ID: a região onde está a usar o Vertex AI.
REST
Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
- LOCATION_ID: a região onde está a usar o Vertex AI.
- PROJECT_ID: o seu ID do projeto
- ENDPOINT_ID: o ID do ponto final.
- INSTANCES: uma matriz JSON de instâncias para as quais quer obter inferências. O formato de cada instância depende das entradas que o modelo de ML preparado espera. Para mais informações, consulte o artigo Formatar a entrada para inferência online.
Método HTTP e URL:
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict
Corpo JSON do pedido:
{ "instances": INSTANCES }
Para enviar o seu pedido, escolha uma destas opções:
curl
Guarde o corpo do pedido num ficheiro com o nome request.json
,
e execute o seguinte comando:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict"
PowerShell
Guarde o corpo do pedido num ficheiro com o nome request.json
,
e execute o seguinte comando:
$cred = gcloud auth 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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict" | Select-Object -Expand Content
- PREDICTIONS: uma matriz JSON de previsões, uma para cada instância que incluiu no corpo do pedido.
-
DEPLOYED_MODEL_ID: o ID do
DeployedModel
que publicou as previsões.
{ "predictions": PREDICTIONS, "deployedModelId": "DEPLOYED_MODEL_ID" }
Java
Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do Vertex AI com bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Java Vertex AI.
Para se autenticar no Vertex AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Node.js
Antes de experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do Vertex AI com bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Node.js Vertex AI.
Para se autenticar no Vertex AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Python
Para saber como instalar ou atualizar o SDK Vertex AI para Python, consulte o artigo Instale o SDK Vertex AI para Python. Para mais informações, consulte a Python documentação de referência da API.
Envie um pedido de inferência raw online
gcloud
Os exemplos seguintes usam o comando gcloud ai endpoints raw-predict
:
-
Para pedir a inferência com o objeto JSON em REQUEST especificado na linha de comandos:
gcloud ai endpoints raw-predict ENDPOINT_ID \ --region=LOCATION_ID \ --request=REQUEST
Para pedir inferências com uma imagem armazenada no ficheiro
image.jpeg
e o cabeçalhoContent-Type
adequado:gcloud ai endpoints raw-predict ENDPOINT_ID \ --region=LOCATION_ID \ --http-headers=Content-Type=image/jpeg \ --request=@image.jpeg
Substitua o seguinte:
- ENDPOINT_ID: o ID do ponto final.
- LOCATION_ID: a região onde está a usar o Vertex AI.
- REQUEST: o conteúdo do pedido para o qual quer obter inferências. O formato do pedido depende do que o seu contentor personalizado espera, que pode não ser necessariamente um objeto JSON.
Python
Para saber como instalar ou atualizar o SDK Vertex AI para Python, consulte o artigo Instale o SDK Vertex AI para Python. Para mais informações, consulte a Python documentação de referência da API.
A resposta inclui os seguintes cabeçalhos HTTP:
X-Vertex-AI-Endpoint-Id
: ID doEndpoint
que publicou esta inferência.X-Vertex-AI-Deployed-Model-Id
: ID doDeployedModel
do ponto final que serviu esta inferência.
Envie um pedido de explicação online
gcloud
O exemplo seguinte usa o comando gcloud ai endpoints explain
:
Escreva o seguinte objeto JSON no ficheiro no seu ambiente local. O nome do ficheiro não é importante, mas, para este exemplo, atribua o nome
request.json
ao ficheiro.{ "instances": INSTANCES }
Substitua o seguinte:
- INSTANCES: uma matriz JSON de instâncias para as quais quer obter inferências. O formato de cada instância depende das entradas que o modelo de ML preparado espera. Para mais informações, consulte o artigo Formatar a entrada para inferência online.
Execute o seguinte comando:
gcloud ai endpoints explain ENDPOINT_ID \ --region=LOCATION_ID \ --json-request=request.json
Substitua o seguinte:
- ENDPOINT_ID: o ID do ponto final.
- LOCATION_ID: a região onde está a usar o Vertex AI.
Opcionalmente, se quiser enviar um pedido de explicação a um
DeployedModel
específico noEndpoint
, pode especificar a flag--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 implementado para o qual quer obter
explicações. O ID está incluído na resposta do método
predict
. Se precisar de pedir explicações para um modelo específico e tiver mais do que um modelo implementado no mesmo ponto final, pode usar este ID para garantir que as explicações são devolvidas para esse modelo específico.
REST
Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
- LOCATION_ID: a região onde está a usar o Vertex AI.
- PROJECT_ID:
- ENDPOINT_ID: o ID do ponto final.
- INSTANCES: uma matriz JSON de instâncias para as quais quer obter inferências. O formato de cada instância depende das entradas que o modelo de ML preparado espera. Para mais informações, consulte o artigo Formatar a entrada para inferência online.
Método HTTP e URL:
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:explain
Corpo JSON do pedido:
{ "instances": INSTANCES }
Para enviar o seu pedido, escolha uma destas opções:
curl
Guarde o corpo do pedido num ficheiro com o nome request.json
,
e execute o seguinte comando:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:explain"
PowerShell
Guarde o corpo do pedido num ficheiro com o nome request.json
,
e execute o seguinte comando:
$cred = gcloud auth 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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:explain" | Select-Object -Expand Content
- PREDICTIONS: uma matriz JSON de previsões, uma para cada instância que incluiu no corpo do pedido.
- EXPLANATIONS: uma matriz JSON de explicações, uma para cada previsão.
-
DEPLOYED_MODEL_ID: o ID do
DeployedModel
que publicou as previsões.
{ "predictions": PREDICTIONS, "explanations": EXPLANATIONS, "deployedModelId": "DEPLOYED_MODEL_ID" }
Python
Para saber como instalar ou atualizar o SDK Vertex AI para Python, consulte o artigo Instale o SDK Vertex AI para Python. Para mais informações, consulte a Python documentação de referência da API.
Envie um pedido de invocação online
A rota de invocação permite o acesso a todos os caminhos de pedidos não raiz na implementação.
Por exemplo, /invoke/foo/bar
vai ser encaminhado como /foo/bar
para o servidor do modelo. Existem duas formas de aceder ao trajeto.
encaminhar pedidos personalizados para um ponto final dedicado
Python
Para saber como instalar ou atualizar o SDK Vertex AI para Python, consulte o artigo Instale o SDK Vertex AI para Python. Para mais informações, consulte a Python documentação de referência da API.
Encaminhe o pedido de rota personalizada diretamente para o modelo implementado
Python
Para saber como instalar ou atualizar o SDK Vertex AI para Python, consulte o artigo Instale o SDK Vertex AI para Python. Para mais informações, consulte a Python documentação de referência da API.
O que se segue?
- Saiba mais sobre o registo de inferências online.