Uniões de recursos de ponto no tempo

Este artigo descreve como usar a correção pontual para criar um conjunto de dados de treinamento que reflita com precisão os valores de recursos no momento em que uma observação de rótulo foi registrada. Isso é importante para evitar vazamento de dados, que ocorre quando você usa valores de recursos para treinamento de modelo que não estavam disponíveis no momento em que o rótulo foi registrado. Esse tipo de erro pode ser difícil de detectar e pode afetar negativamente o desempenho do modelo.

As tabelas de características de séries temporais incluem uma coluna de chave de carimbo de data/hora que garante que cada linha no conjunto de dados de treinamento represente os valores mais recentes de características conhecidos até o carimbo de data/hora da linha. Você deve usar tabelas de recursos de série temporal sempre que os valores de recurso mudarem ao longo do tempo, por exemplo, com dados de série temporal, dados baseados em eventos ou dados agregados por tempo.

O diagrama a seguir mostra como a chave de carimbo de data/hora é usada. O valor do recurso registrado para cada carimbo de data/hora é o valor mais recente antes desse carimbo de data/hora, indicado pelo círculo laranja contornado. Se nenhum valor tiver sido registrado, o valor do recurso será nulo. Para obter mais detalhes, consulte Como funcionam as tabelas de recursos de série temporal.

Como funcionam as tabelas de recursos de séries temporais

Suponha que você tenha as tabelas de recursos a seguir. Esses dados são obtidos do notebook de exemplo.

As tabelas contêm dados do sensor que medem a temperatura, a umidade relativa, a luz ambiente e o dióxido de carbono em uma sala. A tabela de verdade terrestre indica se uma pessoa estava presente na sala. Cada uma das tabelas tem uma chave primária ('room') e uma chave de marca temporal ('ts'). Para simplificar, apenas os dados de um único valor da chave primária ('0') são mostrados.

A figura a seguir ilustra como a chave de carimbo de data/hora é usada para garantir a correção pontual em um conjunto de dados de treinamento. Os valores de recurso são correspondidos com base na chave primária (não mostrada no diagrama) e na chave de carimbo de data/hora, usando uma junção AS OF. A junção AS OF garante que o valor mais recente do recurso no momento do carimbo de data/hora seja usado no conjunto de treinamento.

Conforme mostrado na figura, o conjunto de dados de treinamento inclui os valores de recurso mais recentes para cada sensor antes do carimbo de data/hora na verdade terrestre observada.

Se você criou um conjunto de dados de treinamento sem levar em conta a chave de carimbo de data/hora, talvez tenha uma linha com esses valores de recurso e a verdade terrestre observada:

No entanto, esta não é uma observação válida para treinamento, pois a leitura de co2 de 630 foi feita às 8h52, após a observação da verdade terrestre às 8h50. Os dados futuros estão "vazando" no conjunto de treinamento, o que prejudicará o desempenho do modelo.

Requisitos

• Para a Engenharia de Recursos no Catálogo do Unity: cliente da Engenharia de Recursos no Catálogo do Unity (qualquer versão).
• Para o Workspace Feature Store (legado): cliente do Feature Store v0.3.7 ou superior.

Como especificar chaves relacionadas ao tempo

Para usar a funcionalidade de ponto no tempo, especifique chaves relacionadas ao tempo usando o argumento timeseries_columns (no caso da Engenharia de Recursos no Catálogo do Unity) ou o argumento timestamp_keys (no caso do Repositório de Recursos do Workspace). Isso indica que as linhas da tabela de recursos devem ser unidas por meio da correspondência do valor mais recente para uma chave primária específica que não seja posterior ao valor da coluna timestamps_keys em vez da união com base em uma correspondência de hora exata.

Se você não usar timeseries_columns ou timestamp_keys, e designar apenas uma coluna de série temporal como uma coluna de chave primária, o repositório de recursos não aplicará lógica de ponto no tempo à coluna de série temporal durante as junções. Em vez disso, ele corresponderá apenas a linhas com uma correspondência de tempo exata em vez de todas as linhas antes do carimbo de data/hora.

Criar uma tabela de recursos de série temporal no Catálogo do Unity

No Catálogo do Unity, qualquer tabela com uma TIMESERIES chave primária é uma tabela de características de série temporal. Para criar uma tabela de recursos de série temporal, consulte Criar uma tabela de recursos no Catálogo do Unity. Os exemplos a seguir ilustram os diferentes tipos de tabelas de série temporal.

Publicar tabelas de série temporal em lojas online

Ao trabalhar com tabelas de recursos que contêm dados de carimbo de data/hora, você precisa considerar se deseja designar a coluna de carimbo de data/hora como uma timeseries_column ou tratá-la como uma coluna regular, dependendo dos requisitos de serviço online.

Colunas de timestamp marcadas com designação de série temporal

Use timeseries_column quando precisar de correção pontual para conjuntos de dados de treinamento e quiser pesquisar os valores de recursos mais recentes a partir de um carimbo de data/hora específico em aplicativos online. Uma tabela de recursos de série temporal precisa ter uma chave de carimbo de data/hora e não pode ter nenhuma coluna de partição. A coluna da chave de carimbo de data/hora deve ser TimestampType ou DateType.

O Databricks recomenda que as tabelas de recursos de série temporal não tenham mais do que duas colunas de chave primária para garantir gravações e pesquisas com alto desempenho.

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'
);

Colunas de carimbo de data/hora sem designação de série temporal

Para publicar todos os valores de série temporal no repositório online (não apenas os valores mais recentes), inclua as colunas de carimbo de data/hora como parte da chave primária, mas não as designe como timeseries_column.

FeatureEngineeringClient API

fe = FeatureEngineeringClient()

# Create a regular table with timestamp column (no point-in-time logic)
fe.create_table(
    name="catalog.schema.user_current_features",
    primary_keys=["user_id", "event_timestamp"],
    # Note: event_timestamp is not marked as a time series column
    df=features_df # DataFrame must contain primary keys columns
)

SQL API

-- Create table with timestamp column but no time series constraint
CREATE TABLE catalog.schema.user_current_features (
    user_id STRING NOT NULL,
    event_timestamp TIMESTAMP NOT NULL,   -- part of primary key, but NOT designated as TIMESERIES
    current_balance DOUBLE,
    subscription_status STRING,
    last_login_days_ago INT,
    CONSTRAINT pk_user_current PRIMARY KEY (user_id, event_timestamp)
) USING DELTA
TBLPROPERTIES (
    'delta.enableChangeDataFeed' = 'true'
);

Atualizar uma tabela de recursos de série temporal

Ao gravar recursos nas tabelas de recursos de série temporal, o DataFrame precisa fornecer valores para todos os recursos da tabela de recursos, ao contrário das tabelas de recursos comuns. Essa restrição reduz a dispersão de valores de recursos entre os carimbos de data/hora na tabela de recursos de série temporal.

Engenharia de Recursos no Catálogo do 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"
)

Cliente Workspace Feature Store v0.13.4 e superior

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"
)

Há suporte para gravações de streaming em tabelas de recursos de série temporal.

Criar um conjunto de treinamento com uma tabela de recursos de série temporal

Para executar uma pesquisa pontual para valores de características de uma tabela de características de série temporal, você deve especificar um timestamp_lookup_key na característica FeatureLookup, que indica o nome da coluna DataFrame que contém carimbos de data/hora utilizados para a pesquisa de características de série temporal. O Databricks Feature Store recupera os valores de características mais recentes antes dos carimbos de data/hora especificados na coluna timestamp_lookup_key do DataFrame e cujas chaves primárias (exceto as chaves de carimbo de data/hora) correspondem aos valores nas colunas lookup_key do DataFrame, ou null caso não exista nenhum valor de características.

Engenharia de Recursos no Catálogo do 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()

Repositório de Recursos do Workspace

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()

Qualquer FeatureLookup em uma tabela de recursos de série temporal precisa ser uma pesquisa pontual. Portanto, ela precisa especificar uma coluna timestamp_lookup_key a ser usada no DataFrame. A pesquisa pontual não ignora linhas com valores de recursos null armazenados na tabela de recursos de série temporal.

Definir um limite de tempo para valores históricos de recursos

Com o cliente do Repositório de Recursos v0.13.0 ou superior ou qualquer versão do cliente da Engenharia de Recursos no Catálogo do Unity, você pode excluir valores de recursos com carimbos de data/hora mais antigos do conjunto de treinamento. Para fazer isso, use o parâmetro lookback_window no FeatureLookup.

O tipo de dados de lookback_window deve ser datetime.timedelta, e o valor padrão é None (todos os valores de recurso são usados, independentemente da idade).

Por exemplo, o código a seguir exclui todos os valores de recurso com mais de 7 dias de idade:

Engenharia de Recursos no Catálogo do 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)
  )
]

Repositório de Recursos do Workspace

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)
  )
]

Quando você chama create_training_set com o FeatureLookup acima, ele executa automaticamente a junção pontual e exclui valores de recurso com mais de 7 dias.

A janela de pesquisa é aplicada durante o treinamento e a inferência em lote. Durante a inferência online, o valor do recurso mais recente é sempre usado, independentemente da janela de pesquisa.

Pontuar modelos com tabelas de recursos de série temporal

Quando você pontua um modelo treinado com recursos de tabelas de recursos de série temporal, o Repositório de Recursos do Databricks recupera os recursos apropriados usando pesquisas pontuais com metadados empacotados com o modelo durante o treinamento. O DataFrame fornecido para FeatureEngineeringClient.score_batch (no caso da Engenharia de Recursos no Catálogo do Unity) ou para FeatureStoreClient.score_batch (no caso do Repositório de Recursos do workspace) precisa conter uma coluna de carimbo de data/hora com o mesmo nome e DataType como a timestamp_lookup_key do FeatureLookup fornecido para FeatureEngineeringClient.create_training_set ou FeatureStoreClient.create_training_set.

Publicar recursos de série temporal em um repositório online

Use FeatureEngineeringClient.publish_table (no caso da Engenharia de Recursos no Catálogo do Unity) ou FeatureStoreClient.publish_table (no caso do Repositório de Recursos do Workspace) para publicar tabelas de recursos de série temporal em repositórios online. O Feature Store do Databricks publica um instantâneo dos valores de recursos mais recentes para cada chave primária na tabela de recursos no repositório online. O repositório online dá suporte à pesquisa de chave primária, mas não à pesquisa pontual.

Exemplo de notebook: tabela de recursos de série temporal

Esses notebooks de exemplo ilustram PROCs pontuais em tabelas de recursos de série temporal.

Use esses notebooks em espaços de trabalho habilitados para o Catálogo do Unity.

Exemplo de notebook da tabela de recursos de série temporal (Catálogo do Unity)

Obter notebook

O notebook a seguir é projetado para espaços de trabalho que não estão habilitados para o Catálogo do Unity. Ele usa o Feature Store do espaço de trabalho.

Exemplo de notebook de tabela de recursos de série temporal (espaços de trabalho não habilitados para o Catálogo do Unity)

Obter notebook