Uniões de recursos de ponto no tempo

A correção pontual cria um conjunto de dados de treinamento que reflete os valores dos recursos no momento em que cada observação do 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 recursos de série temporal contam com uma coluna de chave de carimbo de data/hora que garante que cada linha no conjunto de dados de treinamento represente os valores de recurso conhecidos e mais recentes a partir do 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 timestamp é usada. O valor da característica registrado para cada timestamp é o valor mais recente antes desse timestamp, 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 características 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 carimbo de data/hora ('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 timestamp é usada para garantir a correção de ponto no tempo 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" para o 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 pontual à coluna de série temporal durante as junções. Em vez disso, ele corresponderá apenas às linhas com uma correspondência exata de tempo, em vez de corresponder a todas as linhas anteriores ao carimbo de data/hora.

Criar uma tabela de características de série temporal no Unity Catalog

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 características que contêm dados de timestamp, você precisa considerar se deseja designar a coluna de timestamp como uma timeseries_column ou tratá-la como uma coluna regular, dependendo dos requisitos de fornecimento 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.

API de FeatureEngineeringClient

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

Atualizar uma tabela de características 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 Atributos 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 fazer uma pesquisa pontual de valores de recurso em uma tabela de recursos de série temporal, é preciso especificar um timestamp_lookup_key no FeatureLookup do recurso, o que indica o nome da coluna de DataFrame que contém os carimbos de data/hora em relação aos quais os recursos da série temporal devem ser pesquisados. 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 Atributos 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 características

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 Atributos 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 temporal e exclui valores de característica mais antigos que 7 dias.

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

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 características de séries temporais em um repositório online

Use FeatureEngineeringClient.publish_table (para Engenharia de Características no Catálogo do Unity) ou FeatureStoreClient.publish_table (para o Repositório de Características do Workspace) para publicar tabelas de características de séries temporais em repositórios online. O Repositório de Recursos do Databricks publica um instantâneo dos valores de recursos mais recentes para cada chave primária na tabela de recursos para o 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 consultas pontuais em tabelas de recursos de séries temporais.

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

Notebook de exemplo de tabela de recursos de séries temporais (Unity Catalog)

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 Repositório de Recursos do Workspace.

Exemplo de notebook de tabela de recursos de série temporal (workspaces não habilitados para o Unity Catalog)

Obter notebook