Entrega en línea

La entrega en línea te permite entregar valores de atributos para lotes pequeños de entidades con baja latencia. Para cada solicitud, solo puedes entregar valores de atributos de un único tipo de entidad. Vertex AI Feature Store (Heredado) solo muestra el valor no nulo más reciente de cada atributo.

Por lo general, debes usar la entrega en línea a fin de entregar valores de atributos a modelos implementados para realizar predicciones en línea. Por ejemplo, es posible que tengas una empresa de arriendo de bicicletas y desees predecir cuánto tiempo un usuario en particular alquilará una bicicleta. Puedes incluir entradas en tiempo real del usuario y datos del almacén de atributos para realizar una predicción en línea. De esta manera, puedes determinar la asignación de recursos en tiempo real.

Valores nulos

Para los resultados de entrega en línea, si el valor más reciente de un atributo es nulo, Vertex AI Feature Store (Heredado) muestra el valor más reciente que no sea nulo. Si no hay un valor anterior, Vertex AI Feature Store (Heredado) muestra un valor nulo.

Antes de comenzar

Verifica que el almacén de atributos desde el que realizas las llamadas tenga una tienda en línea (la cantidad de nodos debe ser mayor que 0). De lo contrario, las solicitudes de entrega en línea mostrarán un error. Para obtener más información, consulta Administra almacenes de atributos.

Entrega valores de una sola entidad

Entrega valores de atributos de una sola entidad para un tipo de entidad determinado.

REST

Para obtener valores de atributos de una entidad, envía una solicitud POST mediante el método featurestores.entityTypes.readFeatureValues.

En el siguiente ejemplo, se obtienen los valores más recientes de dos funciones diferentes para una entidad en particular. Ten en cuenta que, para el campo ids, puedes especificar ["*"] en lugar de los ID de funciones a fin de seleccionar todos los atributos de la entidad.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

LOCATION_ID: Región en la que se crea el featurestore. Por ejemplo, us-central1
PROJECT_ID: El ID del proyecto.
FEATURESTORE_ID: ID del featurestore.
ENTITY_TYPE_ID: ID del tipo de entidad.
ENTITY_ID: ID de la entidad para la que se obtienen los valores de atributos
FEATURE_ID: ID de la función para la que se obtienen los valores

Método HTTP y URL:

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:readFeatureValues

Cuerpo JSON de la solicitud:

{
  "entityId": "ENTITY_ID",
  "featureSelector": {
    "idMatcher": {
      "ids": ["FEATURE_ID_1", "FEATURE_ID_2"]
    }
  }
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

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/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:readFeatureValues"

PowerShell

Nota: El siguiente comando supone que accediste a la CLI de gcloud con tu cuenta de usuario mediante la ejecución de gcloud init o gcloud auth login. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

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/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:readFeatureValues" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "header": {
    "entityType": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID",
    "featureDescriptors": [
      {
        "id": "FEATURE_ID_1"
      },
      {
        "id": "FEATURE_ID_2"
      }
    ]
  },
  "entityView": {
    "entityId": "ENTITY_ID",
    "data": [
      {
        "value": {
          "VALUE_TYPE_1": "FEATURE_VALUE_1",
          "metadata": {
            "generateTime": "2019-10-28T15:38:10Z"
          }
        }
      },
      {
        "value": {
          "VALUE_TYPE_2": "FEATURE_VALUE_2",
          "metadata": {
            "generateTime": "2019-10-28T15:38:10Z"
          }
        }
      }
    ]
  }
}

Python

Si deseas obtener información para instalar o actualizar el SDK de 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.

from typing import List, Union

from google.cloud import aiplatform

def read_feature_values_sample(
    project: str,
    location: str,
    entity_type_id: str,
    featurestore_id: str,
    entity_ids: Union[str, List[str]],
    feature_ids: Union[str, List[str]] = "*",
):

    aiplatform.init(project=project, location=location)

    my_entity_type = aiplatform.featurestore.EntityType(
        entity_type_name=entity_type_id, featurestore_id=featurestore_id
    )

    my_dataframe = my_entity_type.read(entity_ids=entity_ids, feature_ids=feature_ids)

    return my_dataframe

Python

La biblioteca cliente de Vertex AI se incluye cuando instalas el SDK de Vertex AI para Python. Si deseas obtener información sobre cómo instalar 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 del SDK de AI de Vertex para la API de Python.

from google.cloud import aiplatform

def read_feature_values_sample(
    project: str,
    featurestore_id: str,
    entity_type_id: str,
    entity_id: str,
    location: str = "us-central1",
    api_endpoint: str = "us-central1-aiplatform.googleapis.com",
):
    # The AI Platform services require regional API endpoints, which need to be
    # in the same region or multi-region overlap with the Feature Store location.
    client_options = {"api_endpoint": api_endpoint}
    # Initialize client that will be used to create and send requests.
    # This client only needs to be created once, and can be reused for multiple requests.
    client = aiplatform.gapic.FeaturestoreOnlineServingServiceClient(
        client_options=client_options
    )
    entity_type = f"projects/{project}/locations/{location}/featurestores/{featurestore_id}/entityTypes/{entity_type_id}"
    feature_selector = aiplatform.gapic.FeatureSelector(
        id_matcher=aiplatform.gapic.IdMatcher(ids=["age", "gender", "liked_genres"])
    )
    read_feature_values_request = aiplatform.gapic.ReadFeatureValuesRequest(
        entity_type=entity_type, entity_id=entity_id, feature_selector=feature_selector
    )
    read_feature_values_response = client.read_feature_values(
        request=read_feature_values_request
    )
    print("read_feature_values_response:", read_feature_values_response)

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.


import com.google.cloud.aiplatform.v1.EntityTypeName;
import com.google.cloud.aiplatform.v1.FeatureSelector;
import com.google.cloud.aiplatform.v1.FeaturestoreOnlineServingServiceClient;
import com.google.cloud.aiplatform.v1.FeaturestoreOnlineServingServiceSettings;
import com.google.cloud.aiplatform.v1.IdMatcher;
import com.google.cloud.aiplatform.v1.ReadFeatureValuesRequest;
import com.google.cloud.aiplatform.v1.ReadFeatureValuesResponse;
import java.io.IOException;
import java.util.Arrays;
import java.util.List;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeoutException;

public class ReadFeatureValuesSample {

  public static void main(String[] args)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    // Feature Store ID
    String featurestoreId = "YOUR_FEATURESTORE_ID";
    // Entity Type ID
    String entityTypeId = "YOUR_ENTITY_TYPE_ID";
    // Entity ID
    String entityId = "YOUR_ENTITY_ID";
    // Features to read with batch or online serving.
    List<String> featureSelectorIds = Arrays.asList("title", "genres", "average_rating");
    String location = "us-central1";
    String endpoint = "us-central1-aiplatform.googleapis.com:443";
    int timeout = 300;

    readFeatureValuesSample(
        project,
        featurestoreId,
        entityTypeId,
        entityId,
        featureSelectorIds,
        location,
        endpoint,
        timeout);
  }

  /*
   * Reads Feature values of a specific entity of an EntityType.
   * See: https://cloud.google.com/vertex-ai/docs/featurestore/serving-online
   */
  public static void readFeatureValuesSample(
      String project,
      String featurestoreId,
      String entityTypeId,
      String entityId,
      List<String> featureSelectorIds,
      String location,
      String endpoint,
      int timeout)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    FeaturestoreOnlineServingServiceSettings featurestoreOnlineServiceSettings =
        FeaturestoreOnlineServingServiceSettings.newBuilder().setEndpoint(endpoint).build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (FeaturestoreOnlineServingServiceClient featurestoreOnlineServiceClient =
        FeaturestoreOnlineServingServiceClient.create(featurestoreOnlineServiceSettings)) {
      ReadFeatureValuesRequest readFeatureValuesRequest =
          ReadFeatureValuesRequest.newBuilder()
              .setEntityType(
                  EntityTypeName.of(project, location, featurestoreId, entityTypeId).toString())
              .setEntityId(entityId)
              .setFeatureSelector(
                  FeatureSelector.newBuilder()
                      .setIdMatcher(IdMatcher.newBuilder().addAllIds(featureSelectorIds)))
              .build();

      ReadFeatureValuesResponse readFeatureValuesResponse =
          featurestoreOnlineServiceClient.readFeatureValues(readFeatureValuesRequest);
      System.out.println("Read Feature Values Response" + readFeatureValuesResponse);
    }
  }
}

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.

/**
 * TODO(developer): Uncomment these variables before running the sample.\
 * (Not necessary if passing values as arguments)
 */

// const project = 'YOUR_PROJECT_ID';
// const featurestoreId = 'YOUR_FEATURESTORE_ID';
// const entityTypeId = 'YOUR_ENTITY_TYPE_ID';
// const entityId = 'ENTITY_ID_TO_SERVE';
// const location = 'YOUR_PROJECT_LOCATION';
// const apiEndpoint = 'YOUR_API_ENDPOINT';
// const timeout = <TIMEOUT_IN_MILLI_SECONDS>;

// Imports the Google Cloud Featurestore Service Client library
const {FeaturestoreOnlineServingServiceClient} =
  require('@google-cloud/aiplatform').v1;

// Specifies the location of the api endpoint
const clientOptions = {
  apiEndpoint: apiEndpoint,
};

// Instantiates a client
const featurestoreOnlineServingServiceClient =
  new FeaturestoreOnlineServingServiceClient(clientOptions);

async function readFeatureValues() {
  // Configure the entityType resource
  const entityType = `projects/${project}/locations/${location}/featurestores/${featurestoreId}/entityTypes/${entityTypeId}`;

  const featureSelector = {
    idMatcher: {
      ids: ['age', 'gender', 'liked_genres'],
    },
  };

  const request = {
    entityType: entityType,
    entityId: entityId,
    featureSelector: featureSelector,
  };

  // Read Feature Values Request
  const [response] =
    await featurestoreOnlineServingServiceClient.readFeatureValues(request, {
      timeout: Number(timeout),
    });

  console.log('Read feature values response');
  console.log('Raw response:');
  console.log(JSON.stringify(response, null, 2));
}
readFeatureValues();

Entrega valores de varias entidades

Entrega valores de atributos de una o más entidades para un tipo de entidad determinado. Para obtener un mejor rendimiento, usa el método streamingReadFeatureValues en lugar de enviar solicitudes paralelas al método readFeatureValues.

REST

Para obtener valores de atributos de varias entidades, envía una solicitud POST con el método featurestores.entityTypes.streamingReadFeatureValues.

En el siguiente ejemplo, se obtienen los valores más recientes de dos atributos diferentes para dos entidades diferentes. Ten en cuenta que, para el campo ids, puedes especificar ["*"] en lugar de los ID de funciones a fin de seleccionar todos los atributos de la entidad.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

LOCATION_ID: Región en la que se crea el featurestore. Por ejemplo, us-central1
PROJECT_ID: El ID del proyecto.
FEATURESTORE_ID: ID del featurestore.
ENTITY_TYPE_ID: ID del tipo de entidad.
ENTITY_ID: ID de la entidad para la que se obtienen los valores de atributos
FEATURE_ID: ID de la función para la que se obtienen los valores

Método HTTP y URL:

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:streamingReadFeatureValues

Cuerpo JSON de la solicitud:

{
  "entityIds": ["ENTITY_ID_1", "ENTITY_ID_2"],
  "featureSelector": {
    "idMatcher": {
      "ids": ["FEATURE_ID_1", "FEATURE_ID_2"]
    }
  }
}

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/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:streamingReadFeatureValues"

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/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:streamingReadFeatureValues" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

[{
  "header": {
    "entityType": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID",
    "featureDescriptors": [
      {
        "id": "FEATURE_ID_1"
      },
      {
        "id": "FEATURE_ID_2"
      }
    ]
  }
},
{
  "entityView": {
    "entityId": "ENTITY_ID_1",
    "data": [
      {
        "value": {
          "VALUE_TYPE_1": "FEATURE_VALUE_A",
          "metadata": {
            "generateTime": "2019-10-28T15:38:10Z"
          }
        }
      },
      {
        "value": {
          "VALUE_TYPE_2": "FEATURE_VALUE_B",
          "metadata": {
            "generateTime": "2019-10-28T15:38:10Z"
          }
        }
      }
    ]
  }
},
{
  "entityView": {
    "entityId": "ENTITY_ID_2",
    "data": [
      {
        "value": {
          "VALUE_TYPE_1": "FEATURE_VALUE_C",
          "metadata": {
            "generateTime": "2019-10-28T21:21:37Z"
          }
        }
      },
      {
        "value": {
          "VALUE_TYPE_2": "FEATURE_VALUE_D",
          "metadata": {
            "generateTime": "2019-10-28T21:21:37Z"
          }
        }
      }
    ]
  }
}]

Idiomas adicionales

Puedes instalar y usar las siguientes bibliotecas cliente de Vertex AI para llamar a la API de Vertex AI. Las bibliotecas cliente de Cloud proporcionan una experiencia optimizada para los desarrolladores, mediante el uso de las convenciones y estilos naturales de cada lenguaje compatible.

¿Qué sigue?

Descubre cómo transferir por lotes los valores de atributos.
Obtén información sobre cómo entregar atributos a través de la entrega por lotes.
Consulta las cuotas de entrega en línea de Vertex AI Feature Store (Heredado).
Soluciona problemas comunes de Vertex AI Feature Store (Heredado).