Crea un grupo de atributos

Un grupo de atributos es un recurso de Feature Registry que está asociado con una tabla o vista de BigQuery que contiene tus datos de atributos. Un grupo de atributos puede contener varios atributos, en los que cada atributo está asociado con una columna en la fuente de datos de atributos. Si deseas registrar tu fuente de datos de atributos en Feature Registry, crea un grupo de atributos y, luego, agrégale atributos.

Después de crear un grupo de atributos y asociar la fuente de datos de BigQuery, puedes crear atributos asociados con las columnas de la fuente de datos. Ten en cuenta que, aunque es opcional asociar una fuente de datos mientras creas un grupo de atributos, debes asociar una tabla o vista de BigQuery antes de crear atributos dentro de ese grupo de atributos. Cada atributo corresponde a una columna en la fuente de datos asociada con el grupo de atributos.

¿Por qué usar grupos de atributos y atributos?

El registro de tu fuente de datos de atributos es opcional. Sin embargo, debes registrar tus datos de atributos creando grupos de atributos y atributos en las siguientes situaciones:

  • Usa datos históricos en formato de series temporales para entrenar un modelo: Si la fuente de datos de atributos contiene datos de atributos históricos y más recientes con varios registros de atributos para el mismo ID de entidad, da formato a estos datos como una serie temporal agregando la columna feature_timestamp. En este caso, debes registrar la fuente de datos con grupos de atributos y atributos. Luego, puedes entregar atributos de la siguiente manera:

    • Usa la entrega en línea para entregar los valores de atributos más recientes según la marca de tiempo para realizar predicciones en tiempo real.

    • Usa la entrega sin conexión para entregar los valores de atributos históricos y más recientes para entrenar un modelo.

  • Agrega atributos de varias fuentes: Usa grupos de atributos para agregar columnas específicas de varias fuentes de datos de BigQuery cuando creas una instancia de vista de atributos.

  • Entrega valores de atributos nulos: Durante la entrega en línea, si deseas entregar solo los valores de atributos más recientes, incluidos los valores nulos, registra tu fuente de datos de atributos creando grupos de atributos con el dense parámetro establecido en true.

  • Usa la sincronización continua de datos en tus vistas de atributos: El registro de tus atributos es un requisito previo para usar la sincronización continua de datos en tus vistas de atributos.

  • Supervisa los atributos en busca de anomalías: Debes registrar tus atributos si deseas configurar la supervisión de atributos para recuperar estadísticas de atributos y detectar la desviación de atributos.

Cuándo no usar grupos de atributos y atributos

Si deseas entregar incorporaciones desde tu fuente de datos de atributos, no registres la fuente de datos creando grupos de atributos y atributos. En este caso, debes configurar la entrega en línea asociando directamente la tabla o vista de BigQuery con tus vistas de atributos.

Para obtener más información sobre cómo configurar la entrega en línea sin registrar tu fuente de datos de atributos, consulta Crea una vista de atributos desde una fuente de BigQuery.

Controle el acceso

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

  • Controla el acceso al recurso FeatureGroup: Para controlar el acceso a un grupo de atributos para una persona, un grupo de Google, un dominio o una cuenta de servicio específicos, configura una política de IAM para el grupo de atributos.

  • Controla el acceso a la fuente de datos de BigQuery: De forma predeterminada, un grupo de atributos usa la cuenta de servicio predeterminada configurada para el proyecto. Vertex AI Feature Store asigna el rol de Visualizador de datos de BigQuery de Identity and Access Management (IAM) a esta cuenta de servicio. Esto permite que cualquier usuario con permiso para crear un grupo de atributos en el proyecto acceda a la fuente de datos de atributos en BigQuery. Para restringir el acceso a la fuente de datos de BigQuery o para otorgar acceso a usuarios adicionales, puedes configurar tu grupo de atributos para que use su propia cuenta de servicio dedicada. Vertex AI Feature Store genera una dirección de correo electrónico de la cuenta de servicio única para cada grupo de atributos configurado para tener una cuenta de servicio dedicada.

Antes de comenzar

Antes de crear un grupo de atributos, completa los siguientes requisitos previos:

  • Asegúrate de que haya al menos una instancia de tienda en línea creada en tu proyecto, incluso si deseas crear una instancia de tienda en línea nueva. Si usas un proyecto nuevo, crea una instancia de tienda en línea antes de crear el grupo de atributos.

  • Da formato a tus datos de atributos en la tabla o vista de BigQuery para que cumplan con los lineamientos de preparación de la fuente 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 Gemini Enterprise Agent Platform, a menos que ya lo hayas hecho.

    Selecciona la pestaña según cómo planeas usar las muestras de esta página:

    Console

    Cuando usas la Google Cloud consola para acceder a Google Cloud servicios y APIs, no necesitas configurar la autenticación.

    Python

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

    1. Instala Google Cloud CLI.

    2. Si usas un proveedor de identidad (IdP) externo, primero debes acceder a la gcloud CLI con tu identidad federada.

    3. Si usas un shell local, crea credenciales de autenticación locales para tu cuenta de usuario: 

      gcloud auth application-default login

      No es necesario que lo hagas si usas Cloud Shell.

      Si se muestra un error de autenticación y usas un proveedor de identidad (IdP) externo, confirma que accediste a la gcloud CLI con tu identidad federada.

    Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

    REST

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

      Instala Google Cloud CLI.

      Si usas un proveedor de identidad (IdP) externo, primero debes acceder a la gcloud CLI con tu identidad federada.

    Para obtener más información, consulta Autentícate para usar REST en la documentación de autenticación de. Google Cloud

Crea un grupo de atributos para registrar una fuente de datos de atributos

Usa las siguientes muestras para crear un grupo de atributos y asociar una fuente de datos de atributos, como una tabla o vista de BigQuery.

Console

Importante: No puedes crear un grupo de atributos con una cuenta de servicio dedicada desde la Google Cloud consola. Para crear un grupo de atributos con una cuenta de servicio dedicada, usa la API de REST o el SDK de Agent Platform para Python.

Usa las siguientes instrucciones para crear un grupo de atributos con la Google Cloud consola:

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

    Ir a la página de Feature Store

  2. En la sección Feature groups, haz clic en Create para abrir el panel Basic info en la página Create Feature Group.

  3. Especifica el nombre del grupo de atributos.

  4. Opcional: Para agregar etiquetas, haz clic en Agregar etiqueta y especifica el nombre y el valor de la etiqueta. Puedes agregar varias etiquetas a un grupo de atributos.

  5. En el campo Ruta de acceso de BigQuery, haz clic en Explorar para seleccionar la tabla o vista de origen de BigQuery que deseas asociar con el grupo de atributos.

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

    Ten en cuenta que esto es opcional si la tabla o vista de origen de BigQuery tiene una columna llamada entity_id. En ese caso, si no seleccionas una columna de ID de entidad, el grupo de atributos usa la columna entity_id como la columna de ID de entidad predeterminada.

  7. Haz clic en Continuar.

  8. En el panel Registrar, haz clic en una de las siguientes opciones para indicar si deseas agregar atributos al nuevo grupo de atributos:

    • Incluir todas las columnas de la tabla de BigQuery: Crea atributos dentro del grupo de atributos para todas las columnas de la tabla o vista de origen de BigQuery.

    • Ingresar los atributos manualmente: Crea atributos basados en columnas específicas en la fuente de BigQuery. Para cada atributo, ingresa un Nombre del atributo y haz clic en el nombre de la columna de origen de BigQuery correspondiente en la lista.

      Para agregar más atributos, haz clic en Agregar otro atributo.

    • Crear un grupo de atributos vacío: crea el grupo de funciones sin agregarle atributos.

  9. Haz clic en Crear.

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. Para obtener más información, consulta la Python documentación de referencia de la API.

Nota: En este ejemplo, se crea un grupo de atributos con la configuración de la cuenta de servicio predeterminada. 

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: ID del proyecto
  • location: La región en la que deseas crear el grupo de atributos, como us-central1.
  • feature_group_id: El nombre del grupo de atributos nuevo que deseas crear.
  • bq_table_uri: El URI de la vista o tabla de origen de BigQuery que deseas registrar para el grupo de funciones.
  • 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 la entidad, especifica el nombre de la columna en el siguiente formato:
      "entity_id_column_name".
    • Para especificar varias columnas de ID de entidad, especifica los nombres de las columnas en el siguiente formato:
      ["entity_id_column_1_name", "entity_id_column_2_name", ...].

REST

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

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

  • LOCATION_ID: La región en la que deseas crear el grupo de atributos, como us-central1.
  • SERVICE_AGENT_TYPE: Opcional. Configuración de la cuenta de servicio para el grupo de atributos. Para usar una cuenta de servicio dedicada para el grupo de atributos, ingresa SERVICE_AGENT_TYPE_FEATURE_GROUP.
  • PROJECT_ID: ID del proyecto
  • ENTITY_ID_COLUMNS: Los nombres de las columnas que contienen los ID de las entidades. Puedes especificar una o varias columnas.
    • Para especificar solo una columna de ID de la entidad, especifica el nombre de la columna en el siguiente formato:
      "entity_id_column_name".
    • Para especificar varias columnas de ID de entidad, especifica los nombres de las columnas en el siguiente formato:
      ["entity_id_column_1_name", "entity_id_column_2_name", ...].
  • FEATUREGROUP_NAME: El nombre del grupo de atributos nuevo que deseas crear.
  • BIGQUERY_SOURCE_URI: El URI de la vista o tabla de origen de BigQuery que deseas registrar para el grupo de funciones.
  • TIMESTAMP_COLUMN: Opcional. Especifica el nombre de la columna que contiene las marcas de tiempo de los atributos en la tabla o vista de origen de BigQuery.
    Debes especificar el nombre de la columna de marca de tiempo solo si los datos tienen el formato de una serie temporal y la columna que contiene las marcas de tiempo de los atributos no se llama feature_timestamp.
  • STATIC_DATA_SOURCE: Opcional. Ingresa true si los datos no tienen el formato como una serie temporal. La configuración predeterminada es false.
  • DENSE: Opcional Indica cómo Vertex AI Feature Store controla los valores nulos mientras entrega datos de vistas de atributos asociadas con el grupo de atributos:
    • false: Esta es la configuración predeterminada. Vertex AI Feature Store solo entrega los valores de atributos más recientes que no sean nulos. Si el valor más reciente de un atributo es nulo, Vertex AI Feature Store entrega el valor histórico más reciente que no sea nulo. Sin embargo, si los valores actuales e históricos de ese atributo son nulos, Vertex AI Feature Store entrega un valor nulo como valor del atributo.
    • true: Para las vistas de atributos con sincronización de datos programada, Vertex AI Feature Store solo entrega los valores de atributos más recientes, incluidos los valores nulos. Para las vistas de atributos con sincronización continua de datos, Vertex AI Feature Store solo entrega los valores de atributos 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 entrega 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 atributos, consulta Sincroniza los datos en una vista de atributos.

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 que se muestra a continuación:

{
  "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"
    }
  }
}

¿Qué sigue?