Crear un grupo de funciones

Un grupo de funciones es un recurso de Registro de funciones asociado a una tabla o una vista de BigQuery que contiene los datos de tus funciones. Un grupo de características puede contener varias características, donde cada característica está asociada a una columna de la fuente de datos de características. Si quiere registrar su fuente de datos de características en el registro de características, cree un grupo de características y, a continuación, añada características.

Después de crear un grupo de características y asociar la fuente de datos de BigQuery, puede crear características asociadas a las columnas de la fuente de datos. Aunque es opcional asociar una fuente de datos al crear un grupo de características, debes asociar una tabla o una vista de BigQuery antes de crear características en ese grupo. Cada característica se corresponde con una columna de la fuente de datos asociada al grupo de características.

¿Por qué usar grupos de funciones y funciones?

Registrar la fuente de datos de la función es opcional. Sin embargo, debe registrar los datos de sus funciones creando grupos y funciones en los siguientes casos:

  • Usar datos históricos en formato de serie temporal para entrenar un modelo: si la fuente de datos de la característica contiene datos de la característica más recientes e históricos con varios registros de características para el mismo ID de entidad, formatee estos datos como una serie temporal añadiendo la columna feature_timestamp. En este caso, debe registrar la fuente de datos mediante grupos de características y características. A continuación, puede proporcionar funciones de la siguiente manera:

    • Usa el servicio online para ofrecer los valores de las funciones más recientes en función de la marca de tiempo y hacer predicciones en tiempo real.

    • Usa servir offline para servir los valores de las características más recientes, así como los históricos, para entrenar un modelo.

  • Agrega características de varias fuentes: usa grupos de características para agregar columnas específicas de varias fuentes de datos de BigQuery cuando crees una instancia de vista de características.

  • Servir valores de características nulos: durante el servicio online, si solo quiere servir los valores de características más recientes, incluidos los valores nulos, registre su fuente de datos de características creando grupos de características con el parámetro dense configurado en true.

  • Usar la sincronización continua de datos en las vistas de características: para usar la sincronización continua de datos en las vistas de características, primero debes registrar las características.

  • Monitorizar las características para detectar anomalías: debes registrar tus características si quieres configurar la monitorización de características para obtener estadísticas de las características y detectar la deriva de las características.

Cuándo no usar grupos de características y características

Si quieres servir inserciones desde tu fuente de datos de características, no registres la fuente de datos creando grupos y características. En este caso, debes configurar el servicio online asociando directamente la tabla o la vista de BigQuery con tus vistas de características.

Para obtener más información sobre cómo configurar el servicio online sin registrar tu fuente de datos de características, consulta Crear una vista de características a partir de una fuente de BigQuery.

Controlar accesos

Puedes controlar el acceso a un grupo de funciones en los siguientes niveles:

  • Controlar el acceso al recurso FeatureGroup: para controlar el acceso a un grupo de funciones de un usuario, un grupo de Google, un dominio o una cuenta de servicio concretos, configura una política de gestión de identidades y accesos para el grupo de funciones.

  • Controlar el acceso a la fuente de datos de BigQuery: de forma predeterminada, un grupo de funciones usa la cuenta de servicio predeterminada configurada para el proyecto. Vertex AI Feature Store asigna el rol de gestión de identidades y accesos (IAM) Lector de datos de BigQuery a esta cuenta de servicio. De esta forma, cualquier usuario que tenga permiso para crear un grupo de características en el proyecto podrá acceder a la fuente de datos de características en BigQuery. Para restringir el acceso a la fuente de datos de BigQuery o conceder acceso a más usuarios, puedes configurar tu grupo de funciones para que use su propia cuenta de servicio específica. Vertex AI Feature Store genera una dirección de correo de cuenta de servicio única para cada grupo de características configurado para tener una cuenta de servicio dedicada.

Antes de empezar

Antes de crear un grupo de funciones, debes cumplir los siguientes requisitos previos:

  • Asegúrate de que haya al menos una instancia de tienda online creada en tu proyecto, aunque quieras crear una nueva. Si usas un proyecto nuevo, crea una instancia de tienda online antes de crear el grupo de funciones.

  • Da formato a los datos de las funciones de la tabla o la vista de BigQuery para que cumplan las directrices de preparación de fuentes de datos.

  • Verifica que tu fuente de datos de BigQuery contenga al menos una columna de ID de entidad con valores string o int.

  • Autentícate en Vertex AI, a menos que ya lo hayas hecho.

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    Python

    Para usar las Python muestras de esta página en un entorno de desarrollo local, instala e inicializa la CLI de gcloud y, a continuación, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.

      Instala Google Cloud CLI.

      Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

      If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    Para obtener más información, consulta Set up authentication for a local development environment.

    REST

    Para usar las muestras de la API REST de esta página en un entorno de desarrollo local, debes usar las credenciales que proporciones a la CLI de gcloud.

      Instala Google Cloud CLI.

      Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

    Para obtener más información, consulta el artículo Autenticarse para usar REST de la documentación sobre autenticación de Google Cloud .

Crear un grupo de funciones para registrar una fuente de datos de funciones

Usa los siguientes ejemplos para crear un grupo de características y asociar una fuente de datos de características, como una tabla o una vista de BigQuery.

Consola

Sigue estas instrucciones para crear un grupo de funciones con la consola Google Cloud :

  1. En la sección Vertex AI de la Google Cloud consola, ve a la página Feature Store.

    Ir a la página Feature Store

  2. En la sección Grupos de funciones, haz clic en Crear para abrir el panel Información básica en la página Crear grupo de funciones.

  3. Especifica el nombre del grupo de funciones.

  4. Opcional: Para añadir etiquetas, haz clic en Añadir etiqueta y especifica el nombre y el valor de la etiqueta. Puedes añadir varias etiquetas a un grupo de funciones.

  5. En el campo Ruta de BigQuery, haga clic en Examinar para seleccionar la tabla o vista de origen de BigQuery que quiera asociar al grupo de funciones.

  6. En la lista de la columna ID de entidad, seleccione las columnas de ID de entidad de la tabla o vista de origen de BigQuery.

    Ten en cuenta que este paso es opcional si la tabla o la vista de origen de BigQuery tiene una columna llamada entity_id. En ese caso, si no selecciona una columna de ID de entidad, el grupo de funciones usará la columna entity_id como columna de ID de entidad predeterminada.

  7. Haz clic en Continuar.

  8. En el panel Registrar, haga clic en una de las siguientes opciones para indicar si quiere añadir funciones al nuevo grupo de funciones:

    • Incluir todas las columnas de la tabla de BigQuery: crea características en el grupo de características para todas las columnas de la tabla o vista de origen de BigQuery.

    • Introducir las funciones manualmente: crea funciones basadas en columnas específicas de la fuente de BigQuery. En cada función, introduzca un Nombre de la función y haga clic en el nombre de la columna de origen de BigQuery correspondiente en la lista.

      Para añadir más funciones, haz clic en Añadir otra función.

    • Crear un grupo de funciones vacío: crea el grupo de funciones sin añadirle ninguna.

  9. Haz clic en Crear.

Python

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python. 


from google.cloud import aiplatform
from vertexai.resources.preview import feature_store
from typing import List


def create_feature_group_sample(
    project: str,
    location: str,
    feature_group_id: str,
    bq_table_uri: str,
    entity_id_columns: List[str],
):
    aiplatform.init(project=project, location=location)
    fg = feature_store.FeatureGroup.create(
        name=feature_group_id,
        source=feature_store.utils.FeatureGroupBigQuerySource(
            uri=bq_table_uri, entity_id_columns=entity_id_columns
        ),
    )
    return fg
  • project: tu ID de proyecto.
  • location: región en la que quieres crear el grupo de características, como us-central1.
  • feature_group_id: el nombre del nuevo grupo de funciones que quieres crear.
  • bq_table_uri: URI de la tabla o vista de origen de BigQuery que quieras registrar en el grupo de características.
  • entity_id_columns: los nombres de las columnas que contienen los IDs de las entidades. Puedes especificar una o varias columnas.
    • Para especificar solo una columna de ID de entidad, indique el nombre de la columna con el siguiente formato:
      "entity_id_column_name".
    • Para especificar varias columnas de ID de entidad, indique los nombres de las columnas con el siguiente formato:
      ["entity_id_column_1_name", "entity_id_column_2_name", ...].

REST

Para crear un recurso FeatureGroup, envía una solicitud POST mediante el método featureGroups.create.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • LOCATION_ID: región en la que quieres crear el grupo de características, como us-central1.
  • SERVICE_AGENT_TYPE: opcional. Configuración de la cuenta de servicio del grupo de funciones. Para usar una cuenta de servicio específica para el grupo de funciones, introduce SERVICE_AGENT_TYPE_FEATURE_GROUP.
  • PROJECT_ID: tu ID de proyecto.
  • ENTITY_ID_COLUMNS: los nombres de las columnas que contienen los IDs de las entidades. Puedes especificar una o varias columnas.
    • Para especificar solo una columna de ID de entidad, indique el nombre de la columna con el siguiente formato:
      "entity_id_column_name".
    • Para especificar varias columnas de ID de entidad, indique los nombres de las columnas con el siguiente formato:
      ["entity_id_column_1_name", "entity_id_column_2_name", ...].
  • FEATUREGROUP_NAME: el nombre del nuevo grupo de funciones que quieres crear.
  • BIGQUERY_SOURCE_URI: URI de la tabla o vista de origen de BigQuery que quieras registrar en el grupo de características.
  • TIMESTAMP_COLUMN: opcional. Especifica el nombre de la columna que contiene las marcas de tiempo de las características en la tabla o vista de origen de BigQuery.
    Solo tienes que especificar el nombre de la columna de marca de tiempo si los datos tienen el formato de una serie temporal y la columna que contiene las marcas de tiempo de las características no se llama feature_timestamp.
  • STATIC_DATA_SOURCE: opcional. Introduce true si los datos no tienen formato de serie temporal. El valor predeterminado es false.
  • DENSE: opcional. Indica cómo gestiona Vertex AI Feature Store los valores nulos al servir datos de vistas de características asociadas al grupo de características:
    • false: este es el ajuste predeterminado. Vertex AI Feature Store solo proporciona los valores de características no nulos más recientes. Si el valor más reciente de una característica es nulo, Vertex AI Feature Store proporciona el valor histórico no nulo más reciente. Sin embargo, si los valores actuales e históricos de esa característica son nulos, Vertex AI Feature Store devuelve un valor nulo como valor de la característica.
    • true—En el caso de las vistas de características con sincronización de datos programada, Vertex AI Feature Store solo proporciona los valores de características más recientes, incluidos los valores nulos. En el caso de las vistas de características con sincronización de datos continua, Vertex AI Feature Store solo proporciona los valores de características más recientes que no sean nulos. Sin embargo, si los valores actuales e históricos de la característica son nulos, Vertex AI Feature Store devuelve un valor nulo como valor de la característica. Para obtener más información sobre los tipos de sincronización de datos y cómo configurar el tipo de sincronización de datos en una vista de entidad, consulte Sincronizar los datos de una vista de entidad.

Método HTTP y URL: 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups?feature_group_id=FEATUREGROUP_NAME

Cuerpo JSON de la solicitud: 

{
  "service_agent_type": "SERVICE_AGENT_TYPE",
  "big_query": {
    "entity_id_columns": "ENTITY_ID_COLUMNS",
    "big_query_source": {
      "input_uri": "BIGQUERY_SOURCE_URI",
    }
    "time_series": {
      "timestamp_column": ""TIMESTAMP_COLUMN"",
    },
    "static_data_source": STATIC_DATA_SOURCE,
    "dense": DENSE
  }
}

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/featureGroups?feature_group_id=FEATUREGROUP_NAME"

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/featureGroups?feature_group_id=FEATUREGROUP_NAME" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la siguiente:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UpdateFeatureGroupOperationMetadata",
    "genericMetadata": {
      "createTime": "2023-09-18T03:00:13.060636Z",
      "updateTime": "2023-09-18T03:00:13.060636Z"
    }
  }
}

Siguientes pasos