En esta página, se muestra cómo obtener predicciones en línea (en tiempo real) de tus modelos entrenados personalizados mediante la consola de Google Cloud o la API de Vertex AI.
Dale formato a tu entrada para la predicción en línea
En esta sección, se muestra cómo formatear y codificar las instancias de entrada de predicción como JSON, lo que es necesario si usas el método predict
o explain
. Esto no es necesario
si usas el método rawPredict
. Para obtener información sobre qué método elegir, consulta Enviar solicitud al extremo.
Si usas el SDK de Vertex AI para Python a fin de enviar solicitudes de predicción, especifica la lista de instancias sin el campo instances
. Por ejemplo, especifica [
["the","quick","brown"], ... ]
en lugar de { "instances": [
["the","quick","brown"], ... ] }
.
Si tu modelo usa un contenedor personalizado, la entrada debe tener el formato JSON y hay un campo parameters
adicional que se puede usar para tu contenedor. Obtén más información para formatear entradas de predicción con contenedores personalizados.
Dales formato a tus instancias como strings JSON
El formato básico de la predicción en línea es una lista de instancias de datos. Pueden ser listas sin formato de valores o miembros de un objeto JSON, según cómo configuraste las entradas en la aplicación de entrenamiento. Los modelos de TensorFlow pueden aceptar entradas más complejas, mientras que la mayoría de los modelos de scikit-learn y XGBoost esperan una lista de números como entrada.
En este ejemplo, se muestra un tensor de entrada y una clave de instancia para un modelo de TensorFlow:
{"values": [1, 2, 3, 4], "key": 1}
La composición de la string JSON puede ser compleja, siempre y cuando siga estas reglas:
El nivel superior de los datos de instancia debe ser un objeto JSON: un diccionario de pares clave-valor.
Los valores individuales en un objeto de instancia pueden ser strings, números o listas. No puedes incorporar objetos JSON.
Las listas deben contener solo elementos del mismo tipo (incluidas otras listas). No puedes mezclar valores numéricos y strings.
Pasa instancias de entrada para la predicción en línea como el cuerpo del mensaje de la llamada projects.locations.endpoints.predict
. Obtén más información sobre los requisitos de formato del cuerpo de la solicitud.
Convierte cada instancia en un array JSON y proporciona el array como el campo instances
de un objeto JSON. Por ejemplo:
{"instances": [
{"values": [1, 2, 3, 4], "key": 1},
{"values": [5, 6, 7, 8], "key": 2}
]}
Codifica datos binarios para la entrada de predicción
No es posible darles a los datos binarios el formato de strings codificadas en UTF-8 que admite JSON. Si tienes datos binarios en tus entradas, debes usar la codificación base64 para representarlos. Se requiere el siguiente formato especial:
La string codificada debe tener el formato de un objeto JSON con una sola clave llamada
b64
. En Python 3, la codificación base64 genera una secuencia de bytes. Debes convertir esto en una string para que pueda serializarse con JSON.{'image_bytes': {'b64': base64.b64encode(jpeg_data).decode()}}
En tu código de modelo TensorFlow, debes asignar los alias de los tensores de entrada y salida binarios de modo que finalicen con “_bytes”.
Ejemplos de solicitud y respuesta
En esta sección, se describe el formato del cuerpo de la solicitud de predicción y del cuerpo de la respuesta, con ejemplos para TensorFlow, scikit-learn y XGBoost.
Solicitar detalles del cuerpo
TensorFlow
El cuerpo de la solicitud contiene datos con la siguiente estructura (representación JSON):
{
"instances": [
<value>|<simple/nested list>|<object>,
...
]
}
El objeto instances[]
es obligatorio y debe contener la lista de instancias para las que se pueden obtener predicciones.
La estructura de cada elemento de la lista de instancias se determina con la definición de entrada del modelo. En las instancias, se pueden incluir entradas con nombre (como objetos) o solo valores sin etiqueta.
No en todos los datos se incluyen entradas con nombre. Algunas instancias son valores JSON sencillos (booleano, número o string). Sin embargo, las instancias suelen ser listas de valores sencillos o listas anidadas complejas.
A continuación, se presentan algunos ejemplos de cuerpos de solicitud.
Datos CSV con cada fila codificada como un valor de string:
{"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}
Texto sin formato:
{"instances": ["the quick brown fox", "the lazy dog"]}
Oraciones codificadas como listas de palabras (vectores de strings):
{ "instances": [ ["the","quick","brown"], ["the","lazy","dog"], ... ] }
Valores escalares de punto flotante:
{"instances": [0.0, 1.1, 2.2]}
Vectores de números enteros:
{ "instances": [ [0, 1, 2], [3, 4, 5], ... ] }
Tensores (en este caso, tensores de dos dimensiones):
{ "instances": [ [ [0, 1, 2], [3, 4, 5] ], ... ] }
Imágenes que se pueden representar de diferentes maneras. En este esquema de codificación, las dos primeras dimensiones representan las filas y columnas de la imagen, y la tercera dimensión contiene listas (vectores) de los valores R, G y B para cada píxel:
{ "instances": [ [ [ [138, 30, 66], [130, 20, 56], ... ], [ [126, 38, 61], [122, 24, 57], ... ], ... ], ... ] }
Codificación de datos
Las strings JSON se deben codificar como UTF-8. Para enviar datos binarios, debes codificar los datos en base64 y marcarlos como binarios. Para marcar una string JSON como binaria, reemplázala por un objeto JSON con un atributo único denominado b64
:
{"b64": "..."}
En el siguiente ejemplo, se muestran dos instancias serializadas tf.Examples
que requieren codificación base64 (se usan datos falsos solo para fines ilustrativos):
{"instances": [{"b64": "X5ad6u"}, {"b64": "IA9j4nx"}]}
En el siguiente ejemplo, se muestran dos strings de bytes de imagen JPEG, que requieren codificación base64 (se usan datos falsos solo para fines ilustrativos):
{"instances": [{"b64": "ASa8asdf"}, {"b64": "JLK7ljk3"}]}
Tensores de varias entradas
Algunos modelos tienen un grafo de TensorFlow subyacente con el que se aceptan varios tensores de entrada. En este caso, usa los nombres de los pares nombre-valor JSON para identificar los tensores de entrada.
Para un grafo con alias de tensor de entrada "image" (string codificada en base64) y "tag" (string), utiliza lo siguiente:
{ "instances": [ { "tag": "beach", "image": {"b64": "ASa8asdf"} }, { "tag": "car", "image": {"b64": "JLK7ljk3"} } ] }
Para un grafo con alias de tensor de entrada "image" (arreglo de 3 dimensiones de entradas de 8 bits) y "tag" (string):
{ "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
El cuerpo de la solicitud contiene datos con la siguiente estructura (representación JSON):
{
"instances": [
<simple list>,
...
]
}
El objeto instances[]
es obligatorio y debe contener la lista de instancias para las que se pueden obtener predicciones. En el siguiente ejemplo, cada instancia de entrada es una lista de números de puntos flotantes:
{
"instances": [
[0.0, 1.1, 2.2],
[3.3, 4.4, 5.5],
...
]
}
La dimensión de las instancias de entrada debe coincidir con lo que espera el modelo. Por ejemplo, si el modelo requiere tres atributos, la longitud de cada instancia de entrada debe ser 3.
XGBoost
El cuerpo de la solicitud contiene datos con la siguiente estructura (representación JSON):
{
"instances": [
<simple list>,
...
]
}
El objeto instances[]
es obligatorio y debe contener la lista de instancias para las que se pueden obtener predicciones. En el siguiente ejemplo, cada instancia de entrada es una lista de números de puntos flotantes:
{
"instances": [
[0.0, 1.1, 2.2],
[3.3, 4.4, 5.5],
...
]
}
La dimensión de las instancias de entrada debe coincidir con lo que espera el modelo. Por ejemplo, si el modelo requiere tres atributos, la longitud de cada instancia de entrada debe ser 3.
Vertex AI no admite la representación dispersa de instancias de entrada para XGBoost.
Con el servicio de predicción en línea, los ceros y los NaN
se interpretan de manera diferente. Si el valor de un atributo es cero, usa 0.0
en la entrada correspondiente. Si falta el valor de una función, usa "NaN"
en la entrada correspondiente.
En el siguiente ejemplo, se representa una solicitud de predicción con una instancia de entrada única, en la que el valor del primer atributo es 0.0, el del segundo es 1.1 y falta el del tercero:
{"instances": [[0.0, 1.1, "NaN"]]}
PyTorch
Si tu modelo usa un contenedor compilado previamente de PyTorch, los controladores predeterminados de TorchServe esperan que cada instancia esté unida a un campo data
. Por ejemplo:
{
"instances": [
{ "data": , <value> },
{ "data": , <value> }
]
}
Detalles del cuerpo de la respuesta
Si la llamada se realiza de forma correcta, el cuerpo de la respuesta contiene una entrada de predicción por instancia en el cuerpo de la solicitud, que se da en el mismo orden:
{
"predictions": [
{
object
}
],
"deployedModelId": string
}
Si en la predicción se producen errores para alguna instancia, el cuerpo de la respuesta no contiene predicciones. En su lugar, contiene una entrada de error:
{
"error": string
}
El objeto predictions[]
contiene la lista de predicciones, una para cada instancia de la solicitud.
En caso de que se produzca un error, la string error
contiene un mensaje que describe el problema. Se muestra el error en lugar de una lista de predicciones si este se produjo mientras se procesaban las instancias.
A pesar de que hay una predicción por instancia, el formato de una predicción no está relacionado directamente con el formato de una instancia. Con las predicciones, se toma cualquier formato que se especifique en la colección de salidas definida en el modelo. La colección de predicciones se muestra en una lista JSON. Cada miembro de la lista puede ser un valor sencillo, una lista o un objeto JSON de cualquier complejidad. Si el modelo tiene más de un tensor de salida, cada predicción será un objeto JSON que contiene un par nombre/valor para cada salida. Con los nombres, se pueden identificar los alias de salida en el grafo.
Ejemplos del cuerpo de la respuesta
TensorFlow
En los siguientes ejemplos, se muestran algunas respuestas posibles:
-
Un conjunto de predicciones sencillo para tres instancias de entrada, en el que cada predicción es un valor de número entero:
{"predictions": [5, 4, 3], "deployedModelId": 123456789012345678 }
-
Un conjunto de predicciones más complejo, en el que cada predicción contiene dos valores con nombre que corresponden a los tensores de salida, con los nombres respectivos
label
yscores
. El valor delabel
es la categoría predicha (“automóvil” o “playa”) yscores
contiene una lista de probabilidades para esa instancia en todas las categorías posibles.{ "predictions": [ { "label": "beach", "scores": [0.1, 0.9] }, { "label": "car", "scores": [0.75, 0.25] } ], "deployedModelId": 123456789012345678 }
-
Una respuesta cuando se produce un error en el procesamiento de una instancia de entrada:
{"error": "Divide by zero"}
scikit-learn
En los siguientes ejemplos, se muestran algunas respuestas posibles:
-
Un conjunto de predicciones sencillo para tres instancias de entrada, en el que cada predicción es un valor de número entero:
{"predictions": [5, 4, 3], "deployedModelId": 123456789012345678 }
-
Una respuesta cuando se produce un error en el procesamiento de una instancia de entrada:
{"error": "Divide by zero"}
XGBoost
En los siguientes ejemplos, se muestran algunas respuestas posibles:
-
Un conjunto de predicciones sencillo para tres instancias de entrada, en el que cada predicción es un valor de número entero:
{"predictions": [5, 4, 3], "deployedModelId": 123456789012345678 }
-
Una respuesta cuando se produce un error en el procesamiento de una instancia de entrada:
{"error": "Divide by zero"}
Envía una solicitud a un extremo
Existen tres maneras de enviar una solicitud:
Solicitud de predicción: Envía una solicitud a
predict
para obtener una predicción en línea.Solicitud de predicción sin procesar: Envía una solicitud a
rawPredict
, que te permite usar una carga útil de HTTP arbitraria en lugar de seguir los lineamientos que se describen en las secciones de Dale formato a tu entrada de esta página. Es posible que desees obtener predicciones sin procesar si:- Usas un contenedor personalizado que recibe solicitudes y envía respuestas que difieren de los lineamientos.
- Necesitas una latencia más baja.
rawPredict
omite los pasos de serialización y reenvía directamente la solicitud al contenedor de predicción. - Entregas predicciones con Triton de NVIDIA.
Solicitud de explicación: Envía una solicitud a
explain
. Si configuraste tuModel
para Vertex Explainable AI, puedes obtener explicaciones en línea. Las solicitudes de explicación en línea tienen el mismo formato que las solicitudes de predicción en línea y muestran respuestas similares; la única diferencia es que las respuestas en las explicaciones en línea incluyen atribuciones de funciones y predicciones.
Envía una solicitud de predicción en línea
gcloud
En el siguiente ejemplo, se usa el comando gcloud ai endpoints predict
:
Escribe el siguiente objeto JSON para archivarlo en tu entorno local. El nombre del archivo no es importante, pero en este ejemplo se lo llama
request.json
.{ "instances": INSTANCES }
Reemplaza lo siguiente:
- INSTANCES: un array JSON de instancias para las que deseas obtener predicciones. El formato de cada instancia depende de qué entradas espera tu modelo de AA entrenado. Si deseas obtener más información, consulta Da formato a tu entrada para la predicción en línea.
Ejecuta el siguiente comando:
gcloud ai endpoints predict ENDPOINT_ID \ --region=LOCATION_ID \ --json-request=request.json
Reemplaza lo siguiente:
- ENDPOINT_ID: Es el ID del extremo.
- LOCATION_ID: la región en la que usas Vertex AI.
REST
Antes de usar cualquiera de los datos de solicitud a continuación, haz los siguientes reemplazos:
- LOCATION_ID: la región en la que usas Vertex AI.
- PROJECT_ID: el ID del proyecto
- ENDPOINT_ID: Es el ID del extremo.
- INSTANCES: un array JSON de instancias para las que deseas obtener predicciones. El formato de cada instancia depende de qué entradas espera tu modelo de AA entrenado. Si deseas obtener más información, consulta Da formato a tu entrada para la predicción en línea.
Método HTTP y URL:
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict
Cuerpo JSON de la solicitud:
{ "instances": INSTANCES }
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente 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
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente 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: un arreglo de predicciones JSON, uno para cada instancia que incluiste en el cuerpo de la solicitud.
-
DEPLOYED_MODEL_ID: el ID de
DeployedModel
que entregó las predicciones.
{ "predictions": PREDICTIONS, "deployedModelId": "DEPLOYED_MODEL_ID" }
Java
Antes de probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de Vertex AI sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Vertex AI Java.
Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Antes de probar este ejemplo, sigue las instrucciones de configuración para Node.js incluidas en la guía de inicio rápido de Vertex AI sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Vertex AI Node.js.
Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Si deseas obtener información para instalar o actualizar el SDK de Vertex AI para Python, consulta Instala el SDK de Vertex AI para Python. Si deseas obtener más información, consulta la documentación de referencia de la API de Python.
Envía una solicitud de predicción sin procesar en línea
gcloud
En los siguientes ejemplos, se usa el comando gcloud ai endpoints raw-predict
.
-
Para solicitar predicciones con el objeto JSON en REQUEST especificado en la línea de comandos, usa este comando:
gcloud ai endpoints raw-predict ENDPOINT_ID \ --region=LOCATION_ID \ --request=REQUEST
Para solicitar predicciones con una imagen almacenada en el archivo
image.jpeg
y en el encabezadoContent-Type
adecuado, usa el siguiente comando:gcloud ai endpoints raw-predict ENDPOINT_ID \ --region=LOCATION_ID \ --http-headers=Content-Type=image/jpeg \ --request=@image.jpeg
Reemplaza lo siguiente:
- ENDPOINT_ID: Es el ID del extremo.
- LOCATION_ID: la región en la que usas Vertex AI.
- REQUEST: Es el contenido de la solicitud para la que deseas obtener predicciones. El formato de la solicitud depende de lo que espera tu contenedor personalizado, que puede no ser necesariamente un objeto JSON.
Python
Si deseas obtener información para instalar o actualizar el SDK de Vertex AI para Python, consulta Instala el SDK de Vertex AI para Python. Si deseas obtener más información, consulta la documentación de referencia de la API de Python.
La respuesta incluye los siguientes encabezados HTTP:
X-Vertex-AI-Endpoint-Id
: Es el ID deEndpoint
que entregó esta predicción.X-Vertex-AI-Deployed-Model-Id
: Es el ID delDeployedModel
del extremo que entregó esta predicción.
Envía una solicitud de explicación en línea
gcloud
En el siguiente ejemplo, se usa el comando gcloud ai endpoints explain
:
Escribe el siguiente objeto JSON para archivarlo en tu entorno local. El nombre del archivo no es importante, pero en este ejemplo se lo llama
request.json
.{ "instances": INSTANCES }
Reemplaza lo siguiente:
- INSTANCES: un array JSON de instancias para las que deseas obtener predicciones. El formato de cada instancia depende de qué entradas espera tu modelo de AA entrenado. Si deseas obtener más información, consulta Da formato a tu entrada para la predicción en línea.
Ejecuta el siguiente comando:
gcloud ai endpoints explain ENDPOINT_ID \ --region=LOCATION_ID \ --json-request=request.json
Reemplaza lo siguiente:
- ENDPOINT_ID: Es el ID del extremo.
- LOCATION_ID: la región en la que usas Vertex AI.
De forma opcional, si deseas enviar una solicitud de explicación a un
DeployedModel
preciso en elEndpoint
, puedes especificar la marca--deployed-model-id
:gcloud ai endpoints explain ENDPOINT_ID \ --region=LOCATION \ --deployed-model-id=DEPLOYED_MODEL_ID \ --json-request=request.json
Además de los marcadores de posición descritos anteriormente, reemplaza lo siguiente:
-
DEPLOYED_MODEL_ID Opcional: El ID del modelo implementado para el que deseas obtener explicaciones. Se incluye el ID en la respuesta del método
predict
. Si necesitas solicitar explicaciones para un modelo en particular y tienes más de un modelo implementado en el mismo extremo, puedes usar este ID a fin de garantizar que se muestren las explicaciones para ese modelo en particular.
REST
Antes de usar cualquiera de los datos de solicitud a continuación, haz los siguientes reemplazos:
- LOCATION_ID: la región en la que usas Vertex AI.
- PROJECT_ID: el ID del proyecto
- ENDPOINT_ID: Es el ID del extremo.
- INSTANCES: un array JSON de instancias para las que deseas obtener predicciones. El formato de cada instancia depende de qué entradas espera tu modelo de AA entrenado. Si deseas obtener más información, consulta Da formato a tu entrada para la predicción en línea.
Método HTTP y URL:
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:explain
Cuerpo JSON de la solicitud:
{ "instances": INSTANCES }
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente 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
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente 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: un arreglo de predicciones JSON, uno para cada instancia que incluiste en el cuerpo de la solicitud.
- EXPLANATIONS: Un arreglo JSON de explicaciones, una para cada predicción.
-
DEPLOYED_MODEL_ID: el ID de
DeployedModel
que entregó las predicciones.
{ "predictions": PREDICTIONS, "explanations": EXPLANATIONS, "deployedModelId": "DEPLOYED_MODEL_ID" }
Python
Si deseas obtener información para instalar o actualizar el SDK de Vertex AI para Python, consulta Instala el SDK de Vertex AI para Python. Si deseas obtener más información, consulta la documentación de referencia de la API de Python.
¿Qué sigue?
- Obtén más información sobre el Registro de predicciones en línea.