Jointures de fonctionnalités à un point dans le temps

Cette page explique comment utiliser la correction à un point dans le temps pour créer un jeu de données d’apprentissage qui reflète avec précision les valeurs des caractéristiques à partir du moment où une observation d’étiquette a été enregistrée. Cela est important pour éviter les fuites de données, qui se produisent lorsque vous utilisez des valeurs de fonctionnalité pour l’entraînement du modèle qui n’étaient pas disponibles au moment où l’étiquette a été enregistrée. Ce type d’erreur peut être difficile à détecter et peut affecter négativement les performances du modèle.

Les tables de caractéristiques de série chronologique incluent une colonne clé d’horodatage qui garantit que chaque ligne du jeu de données d’entraînement représente les dernières valeurs connues des caractéristiques à la date de l'horodatage de la ligne. Utilisez systématiquement des tables de caractéristiques de séries chronologiques si les valeurs de caractéristiques changent au fil du temps, par exemple avec des données de séries chronologiques, des données basées sur les événements ou des données agrégées dans le temps.

Le diagramme suivant montre comment la clé d’horodatage est utilisée. La valeur de la caractéristique enregistrée pour chaque horodatage est la dernière valeur avant cet horodatage, indiquée par le cercle orange encadré. Si aucune valeur n’a été enregistrée, la valeur de la fonctionnalité est Null. Pour plus d’informations, consultez le fonctionnement des tables de caractéristiques des séries chronologiques.

Fonctionnement des tables de caractéristiques de série chronologique

Supposons que vous disposez des tables de fonctionnalités suivantes. Ces données sont extraites du notebook d’exemple.

Les tables contiennent des données de capteur mesurant la température, l’humidité relative, la lumière ambiante et le dioxyde de carbone dans une pièce. La table de vérité au sol indique si une personne était présente dans la salle. Chaque table a une clé primaire ('room') et une clé d’horodatage ('ts'). Par souci de simplicité, seules les données d’une valeur unique de la clé primaire ('0') sont affichées.

La figure suivante illustre la façon dont la clé d’horodatage est utilisée pour garantir l’exactitude dans le temps dans un jeu de données d’apprentissage. Les valeurs de fonctionnalité sont mises en correspondance en fonction de la clé primaire (non indiquée dans le diagramme) et de la clé d’horodatage, à l’aide d’une jointure AS OF. La jointure AS OF garantit que la valeur la plus récente de la caractéristique au moment de l’horodatage est utilisée dans l'ensemble d'entraînement.

Comme le montre la figure, le jeu de données d’apprentissage inclut les dernières valeurs des caractéristiques pour chaque capteur avant l’horodatage de la vérité terrain observée.

Si vous avez créé un jeu de données d’apprentissage sans prendre en compte la clé d’horodatage, vous pourriez avoir une ligne avec ces valeurs des caractéristiques et la vérité terrain observée :

Cependant, ce n'est pas une observation valable pour la formation, car la lecture de CO2 de 630 a été prise à 8:52, après l'observation de la valeur réelle à 8:50. Les données futures s'infiltrent dans le jeu d’entraînement, ce qui affectera les performances du modèle.

Spécifications

• Pour l’ingénierie des fonctionnalités dans Unity Catalog : Ingénierie des fonctionnalités dans le client Unity Catalog (toute version).
• Pour le Magasin des fonctionnalités de Workspace (hérité) : client du Magasin des fonctionnalités v0.3.7 et versions ultérieures.

Comment spécifier des clés liées au temps

Pour utiliser la fonctionnalité ponctuelle, vous devez spécifier des clés liées au temps à l'aide de l'argument timeseries_columns (pour Feature Engineering dans Unity Catalog) ou de l'argument timestamp_keys (pour Espace de travail Feature Store). Il indique que les lignes de la table de caractéristiques doivent être jointes en faisant correspondre la valeur la plus récente d’une clé primaire particulière qui n’est pas postérieure à la valeur de la colonne timestamps_keys, et non en fonction d’une correspondance temporelle exacte.

Si vous n'utilisez ni timeseries_columns ni timestamp_keys, et que vous désignez uniquement une colonne de série temporelle comme colonne clé primaire, le stockage de caractéristiques n’applique pas la logique temporaire ponctuelle à la colonne de série temporelle pendant les jointures. Au lieu d’établir une correspondance avec toutes les lignes antérieures à l’horodatage, il ne considère que les lignes présentant une correspondance temporelle exacte.

Créer une table de caractéristiques de séries chronologiques dans Unity Catalog

Dans le catalogue Unity, toute table avec une TIMESERIES clé primaire est une table de caractéristiques temporelles. Pour créer une table de fonctionnalités de série chronologique, consultez Créer une table de fonctionnalités dans le catalogue Unity. Les exemples suivants illustrent les différents types de tables de série chronologique.

Publier des tables de série chronologique dans des magasins en ligne

Lorsque vous travaillez avec des tables de fonctionnalités qui contiennent des données d’horodatage, vous devez déterminer s’il faut désigner la colonne d’horodatage comme une timeseries_column colonne normale ou la traiter comme une colonne normale, en fonction de vos exigences de service en ligne.

Colonnes de timestamp marquées par la désignation de série temporelle

Utilisez timeseries_column quand vous avez besoin de correctitude ponctuelle pour les jeux de données d'entraînement et que vous souhaitez consulter les valeurs caractéristiques les plus récentes à un moment précis dans des applications en ligne. Une table de fonctionnalités de série chronologique doit avoir une clé de timestamp et ne peut pas avoir de colonne de partition. La colonne de clé timestamp doit être de TimestampType ou DateType.

Databricks recommande que les tables de caractéristiques de série chronologique n’aient pas plus de deux colonnes clés primaires pour garantir des écritures et des recherches performantes.

FeatureEngineeringClient API

fe = FeatureEngineeringClient()

# Create a time series table for point-in-time joins
fe.create_table(
    name="catalog.schema.user_behavior_features",
    primary_keys=["user_id", "event_timestamp"],
    timeseries_columns="event_timestamp",  # Enables point-in-time logic
    df=features_df # DataFrame must contain primary keys and time series columns
)

SQL API

-- Create table with time series constraint for point-in-time joins
CREATE TABLE catalog.schema.user_behavior_features (
    user_id STRING NOT NULL,
    event_timestamp TIMESTAMP NOT NULL,  -- part of primary key and designated as TIMESERIES
    purchase_amount DOUBLE,
    page_views_last_hour INT,
    CONSTRAINT pk_user_behavior PRIMARY KEY (user_id, event_timestamp TIMESERIES)
) USING DELTA
TBLPROPERTIES (
    'delta.enableChangeDataFeed' = 'true'
);

Mettre à jour une table de caractéristiques de série chronologique

Lors de l’écriture de caractéristiques dans les tables de caractéristiques de série chronologique, votre DataFrame doit fournir des valeurs pour toutes les caractéristiques de la table de caractéristiques, contrairement aux tables de caractéristiques standard. Cette contrainte réduit la densité des valeurs de caractéristiques entre les horodatages dans la table de caractéristiques de série chronologique.

Ingénierie des fonctionnalités dans le catalogue Unity

fe = FeatureEngineeringClient()
# daily_users_batch_df DataFrame contains the following columns:
# - user_id
# - ts
# - purchases_30d
# - is_free_trial_active
fe.write_table(
  "ml.ads_team.user_features",
  daily_users_batch_df,
  mode="merge"
)

Client de Workspace Feature Store v0.13.4 et ultérieures

fs = FeatureStoreClient()
# daily_users_batch_df DataFrame contains the following columns:
# - user_id
# - ts
# - purchases_30d
# - is_free_trial_active
fs.write_table(
  "ads_team.user_features",
  daily_users_batch_df,
  mode="merge"
)

Le streaming d’écritures dans les tables de caractéristiques de série chronologique est pris en charge.

Créer un jeu d’entraînement avec une table des caractéristiques de séries temporelles

Pour effectuer une recherche à un point dans le temps pour les valeurs de fonctionnalité à partir d’une timestamp_lookup_keytable de fonctionnalités de série chronologique, vous devez spécifier une FeatureLookup dans la fonctionnalité, qui indique le nom de la colonne DataFrame qui contient des horodatages sur lesquels rechercher des fonctionnalités de série chronologique. Databricks Feature Store récupère les dernières valeurs de fonctionnalité avant les horodatages spécifiés dans la colonne du timestamp_lookup_key DataFrame et dont les clés primaires (à l’exclusion des clés d’horodatage) correspondent aux valeurs dans les colonnes du lookup_key DataFrame, ou null si aucune valeur de fonctionnalité de ce type n’existe.

Ingénierie des fonctionnalités dans le catalogue Unity

feature_lookups = [
  FeatureLookup(
    table_name="ml.ads_team.user_features",
    feature_names=["purchases_30d", "is_free_trial_active"],
    lookup_key="u_id",
    timestamp_lookup_key="ad_impression_ts"
  ),
  FeatureLookup(
    table_name="ml.ads_team.ad_features",
    feature_names=["sports_relevance", "food_relevance"],
    lookup_key="ad_id",
  )
]

# raw_clickstream DataFrame contains the following columns:
# - u_id
# - ad_id
# - ad_impression_ts
training_set = fe.create_training_set(
  df=raw_clickstream,
  feature_lookups=feature_lookups,
  exclude_columns=["u_id", "ad_id", "ad_impression_ts"],
  label="did_click",
)
training_df = training_set.load_df()

Magasin de fonctionnalités de l'espace de travail

feature_lookups = [
  FeatureLookup(
    table_name="ads_team.user_features",
    feature_names=["purchases_30d", "is_free_trial_active"],
    lookup_key="u_id",
    timestamp_lookup_key="ad_impression_ts"
  ),
  FeatureLookup(
    table_name="ads_team.ad_features",
    feature_names=["sports_relevance", "food_relevance"],
    lookup_key="ad_id",
  )
]

# raw_clickstream DataFrame contains the following columns:
# - u_id
# - ad_id
# - ad_impression_ts
training_set = fs.create_training_set(
  df=raw_clickstream,
  feature_lookups=feature_lookups,
  exclude_columns=["u_id", "ad_id", "ad_impression_ts"],
  label="did_click",
)
training_df = training_set.load_df()

Tout FeatureLookup sur une table de caractéristiques de série chronologique doit être une recherche à un point dans le temps. Il doit donc spécifier une colonne timestamp_lookup_key à utiliser dans votre DataFrame. La recherche à un point dans le temps n’ignore pas les lignes avec des valeurs de caractéristiques null stockées dans la table de caractéristiques de série chronologique.

Définir une limite de temps pour les valeurs de fonctionnalité historiques

Avec le client Feature Store v0.13.0 ou supérieur, ou toute version de Feature Engineering dans le client Unity Catalog, vous pouvez exclure les valeurs de fonctionnalités avec des horodatages plus anciens de l'ensemble de formation. Pour ce faire, utilisez le paramètre lookback_window dans .FeatureLookup

Le type de données de lookback_window doit être datetime.timedelta, et la valeur par défaut est None (toutes les valeurs de fonctionnalité sont utilisées, quel que soit l’âge).

Par exemple, le code suivant exclut toutes les valeurs de fonctionnalité qui datent de plus de 7 jours :

Ingénierie des fonctionnalités dans le catalogue Unity

from datetime import timedelta

feature_lookups = [
  FeatureLookup(
    table_name="ml.ads_team.user_features",
    feature_names=["purchases_30d", "is_free_trial_active"],
    lookup_key="u_id",
    timestamp_lookup_key="ad_impression_ts",
    lookback_window=timedelta(days=7)
  )
]

Magasin de fonctionnalités de l'espace de travail

from datetime import timedelta

feature_lookups = [
  FeatureLookup(
    table_name="ads_team.user_features",
    feature_names=["purchases_30d", "is_free_trial_active"],
    lookup_key="u_id",
    timestamp_lookup_key="ad_impression_ts",
    lookback_window=timedelta(days=7)
  )
]

Lorsque vous appelez create_training_set avec la FeatureLookup ci-dessus, il réalise automatiquement la jointure temporelle et exclut les valeurs des caractéristiques plus anciennes que 7 jours.

La fenêtre de recherche arrière est appliquée pendant l’apprentissage et l’inférence par lots. Pendant l’inférence en ligne, la dernière valeur de fonctionnalité est toujours utilisée, quelle que soit la fenêtre de recherche arrière.

Évaluer des modèles avec des tableaux de caractéristiques de séries temporelles

Quand vous évaluez un modèle entraîné avec des caractéristiques de tables de séries chronologiques, le magasin de caractéristiques Databricks récupère les caractéristiques appropriées en effectuant des recherches temporelles avec les métadonnées associées au modèle pendant l'entraînement. Le DataFrame que vous fournissez à FeatureEngineeringClient.score_batch (pour le Feature Engineering dans Unity Catalog) ou à FeatureStoreClient.score_batch (pour le Workspace Feature Store) doit contenir une colonne horodatage avec le même nom et DataType que le timestamp_lookup_key du FeatureLookup fourni à FeatureEngineeringClient.create_training_set ou FeatureStoreClient.create_training_set.

Publier des fonctionnalités de série chronologique dans un magasin en ligne

Vous pouvez utiliser FeatureEngineeringClient.publish_table (pour Feature Engineering dans Unity Catalog) ou FeatureStoreClient.publish_table (pour Espace de travail Feature Store) pour publier des tableaux de fonctionnalités de séries chronologiques dans des magasins en ligne. Databricks Feature Store publie un instantané des dernières valeurs de caractéristiques pour chaque clé primaire de la table de caractéristiques dans le magasin en ligne. Le magasin en ligne prend en charge la recherche de clé primaire, mais ne prend pas en charge la recherche à un point dans le temps.

Exemple de notebook : tableau de caractéristiques de série chronologique

Ces exemples de notebooks illustrent les recherches à un instant dans le passé sur les tables de caractéristiques de série chronologique.

Utilisez ce notebook dans les espaces de travail activés pour Unity Catalog.

Exemple de notebook de table des séries chronologiques (Unity Catalog)

Obtenir le notebook

Le notebook suivant est conçu pour les espaces de travail qui ne sont pas activés pour Unity Catalog. Il utilise le Feature Store de l’espace de travail.

Exemple de notebook de tableau des caractéristiques des séries chronologiques (les espaces de travail non activés avec Unity Catalog)

Obtenir le notebook