Trabalhar com recursos no Workspace Feature Store

Observação

Esta documentação abrange o workspace repositório de recursos. A Databricks recomenda o uso do recurso engenharia no Unity Catalog. workspace repositório de recursos será descontinuado no futuro.

Esta página descreve como criar e trabalhar com tabelas de recursos no workspace Feature Store.

Observação

Se o seu workspace estiver habilitado para o Unity Catalog, qualquer tabela gerenciada pelo Unity Catalog que tenha uma key primária é automaticamente uma tabela de recursos que você pode usar para treinamento e inferência do modelo. Todos os recursos do Unity Catalog, como segurança, tags e acesso entreworkspace , estão automaticamente disponíveis para a tabela de recursos. Para obter informações sobre como trabalhar com tabelas de recursos em um workspace habilitado para o Unity Catalog, consulte engenharia de recursos no Unity Catalog.

Para obter informações sobre linhagem e atualização de recursos de acompanhamento, consulte Descubra recursos e rastreie a linhagem de recursos.

Observação

Os nomes de bancos de dados e tabelas de recursos podem conter apenas caracteres alfanuméricos e sublinhados (_).

Criar um banco de dados para tabelas de recursos

Antes de criar quaisquer tabelas de recursos, você deve criar um banco de dados para armazená-las.

%sql CREATE DATABASE IF NOT EXISTS <database-name>

As tabelas de recursos são armazenadas como tabelas Delta. Ao criar uma tabela de recursos com create_table (cliente Feature Store v0.3.6e acima) ou create_feature_table (v0.3.5 eabaixo), você deve especificar o nome do banco de dados. Por exemplo, este argumento cria uma tabela Delta denominada customer_features no banco de dados recommender_system.

name='recommender_system.customer_features'

Criar uma tabela de recursos no Databricks Feature Store

Observação

Você também pode registrar uma tabela Delta existente como tabela de recursos. Veja registrar uma tabela Delta existente como tabela de recursos.

Os passos básicos para criar uma tabela de recursos são:

  1. Escreva as funções do Python para compute os recursos. A saída de cada função deve ser um Apache Spark DataFrame com uma key primária exclusiva. A key primária pode consistir em uma ou mais colunas.

  2. Crie uma tabela de recursos instanciando um FeatureStoreClient e usando create_table (v0.3.6 e acima) ou create_feature_table (v0.3.5 e abaixo).

  3. Preencha a tabela de recursos usando write_table.

Para obter detalhes sobre o comando e parâmetros usados nos exemplos a seguir, consulte o recurso Store Python API reference.

from databricks.feature_store import feature_table

def compute_customer_features(data):
  ''' Feature computation code returns a DataFrame with 'customer_id' as primary key'''
  pass

# create feature table keyed by customer_id
# take schema from DataFrame output by compute_customer_features
from databricks.feature_store import FeatureStoreClient

customer_features_df = compute_customer_features(df)

fs = FeatureStoreClient()

customer_feature_table = fs.create_table(
  name='recommender_system.customer_features',
  primary_keys='customer_id',
  schema=customer_features_df.schema,
  description='Customer features'
)

# An alternative is to use `create_table` and specify the `df` argument.
# This code automatically saves the features to the underlying Delta table.

# customer_feature_table = fs.create_table(
#  ...
#  df=customer_features_df,
#  ...
# )

# To use a composite key, pass all keys in the create_table call

# customer_feature_table = fs.create_table(
#   ...
#   primary_keys=['customer_id', 'date'],
#   ...
# )

# Use write_table to write data to the feature table
# Overwrite mode does a full refresh of the feature table

fs.write_table(
  name='recommender_system.customer_features',
  df = customer_features_df,
  mode = 'overwrite'
)

from databricks.feature_store import feature_table

def compute_customer_features(data):
  ''' Feature computation code returns a DataFrame with 'customer_id' as primary key'''
  pass

# create feature table keyed by customer_id
# take schema from DataFrame output by compute_customer_features
from databricks.feature_store import FeatureStoreClient

customer_features_df = compute_customer_features(df)

fs = FeatureStoreClient()

customer_feature_table = fs.create_feature_table(
  name='recommender_system.customer_features',
  keys='customer_id',
  schema=customer_features_df.schema,
  description='Customer features'
)

# An alternative is to use `create_feature_table` and specify the `features_df` argument.
# This code automatically saves the features to the underlying Delta table.

# customer_feature_table = fs.create_feature_table(
#  ...
#  features_df=customer_features_df,
#  ...
# )

# To use a composite key, pass all keys in the create_feature_table call

# customer_feature_table = fs.create_feature_table(
#   ...
#   keys=['customer_id', 'date'],
#   ...
# )

# Use write_table to write data to the feature table
# Overwrite mode does a full refresh of the feature table

fs.write_table(
  name='recommender_system.customer_features',
  df = customer_features_df,
  mode = 'overwrite'
)from databricks.feature_store import feature_table

def compute_customer_features(data):
  ''' Feature computation code returns a DataFrame with 'customer_id' as primary key'''
  pass

# create feature table keyed by customer_id
# take schema from DataFrame output by compute_customer_features
from databricks.feature_store import FeatureStoreClient

customer_features_df = compute_customer_features(df)

fs = FeatureStoreClient()

customer_feature_table = fs.create_feature_table(
  name='recommender_system.customer_features',
  keys='customer_id',
  schema=customer_features_df.schema,
  description='Customer features'
)

# An alternative is to use `create_feature_table` and specify the `features_df` argument.
# This code automatically saves the features to the underlying Delta table.

# customer_feature_table = fs.create_feature_table(
#  ...
#  features_df=customer_features_df,
#  ...
# )

# To use a composite key, pass all keys in the create_feature_table call

# customer_feature_table = fs.create_feature_table(
#   ...
#   keys=['customer_id', 'date'],
#   ...
# )

# Use write_table to write data to the feature table
# Overwrite mode does a full refresh of the feature table

fs.write_table(
  name='recommender_system.customer_features',
  df = customer_features_df,
  mode = 'overwrite'
)

registrar uma tabela Delta existente como uma tabela de recursos

Com v0.3.8e acima, você pode registrar uma tabela Delta existente como uma tabela de recursos. A tabela Delta deve existir no metastore.

Observação

Para atualizar uma tabela de recursos cadastrada, deve-se utilizar a API recurso Store Python.

fs.register_table(
  delta_table='recommender.customer_features',
  primary_keys='customer_id',
  description='Customer features'
)

Controle o acesso às tabelas de recursos

Consulte Controle de acesso às tabelas de recursos.

Atualizar uma tabela de recursos

Você pode atualizar uma tabela de recursos adicionando novos recursos ou modificando linhas específicas com base na key primária.

Os seguintes metadados da tabela de recursos não podem ser atualizados:

  • Chave primária

  • keyde partição

  • Nome ou tipo de um recurso existente

Adicionar novos recursos a uma tabela de recursos existente

Você pode adicionar novos recursos a uma tabela de recursos existente de duas maneiras:

  • Atualize a função de computação de recurso existente e a execução write_table com o DataFrame retornado. Isso atualiza o esquema da tabela de recursos e merge novos valores de recursos com base na key primária.

  • Crie uma nova função de cálculo de recursos para calcular os novos valores de recursos. O DataFrame retornado por esta nova função de computação deve conter a key primária e key de partição das tabelas de recursos (se definidas). execução write_table com o DataFrame para gravar os novos recursos na tabela de recursos existente, usando a mesma key primária.

Atualize apenas linhas específicas em uma tabela de recursos

Use mode = "merge" em write_table. As linhas cuja key primária não existe no DataFrame enviado na chamada write_table permanecem inalteradas.

fs.write_table(
  name='recommender.customer_features',
  df = customer_features_df,
  mode = 'merge'
)

programar um Job para atualizar uma tabela de características

Para garantir que os recursos nas tabelas de recursos sempre tenham os valores mais recentes, a Databricks recomenda que você crie um Job que execute um Notebook para atualizar sua tabela de recursos regularmente, como todos os dias. Se você já possui um Job não agendado criado, você pode convertê-lo para um Jobagendado para garantir que os valores do recurso estejam sempre atualizados.

O código para atualizar uma tabela de recursos usa mode='merge', conforme mostrado no exemplo a seguir.

fs = FeatureStoreClient()

customer_features_df = compute_customer_features(data)

fs.write_table(
  df=customer_features_df,
  name='recommender_system.customer_features',
  mode='merge'
)

Armazenar valores anteriores de recursos diários

Defina uma tabela de recursos com uma key primária composta. Inclua a data na key primária. Por exemplo, para uma tabela de recursos store_purchases, você pode usar uma key primária composta (date, user_id) e key de partição date para leituras eficientes.

fs.create_table(
  name='recommender_system.customer_features',
  primary_keys=['date', 'customer_id'],
  partition_columns=['date'],
  schema=customer_features_df.schema,
  description='Customer features'
)

Você pode então criar um código para ler da tabela de recursos filtrando date para o período de interesse.

Você também pode criar uma tabela de recursos de série temporal especificando a coluna date como uma key de carimbo de data/hora usando o argumento timestamp_keys.

fs.create_table(
  name='recommender_system.customer_features',
  primary_keys=['date', 'customer_id'],
  timestamp_keys=['date'],
  schema=customer_features_df.schema,
  description='Customer timeseries features'
)

Isso permite pesquisas pontuais quando você usa create_training_set ou score_batch. O sistema executa uma join de carimbo de data/hora a partir de, usando o timestamp_lookup_key que você especificar.

Para manter a tabela de recursos atualizada, configure um Job agendado regularmente para gravar recursos ou transmita novos valores de recursos para a tabela de recursos.

Crie um pipeline de computação de recursos transmitidos para atualizar os recursos

Para criar um pipeline de computação de recurso de transmissão, passe um DataFrame de transmissão como um argumento para write_table. Este método retorna um objeto StreamingQuery .

def compute_additional_customer_features(data):
  ''' Returns Streaming DataFrame
  '''
  pass  # not shown

customer_transactions = spark.readStream.load("dbfs:/events/customer_transactions")
stream_df = compute_additional_customer_features(customer_transactions)

fs.write_table(
  df=stream_df,
  name='recommender_system.customer_features',
  mode='merge'
)

Ler de uma tabela de recursos

Use read_table para ler os valores do recurso.

fs = feature_store.FeatureStoreClient()
customer_features_df = fs.read_table(
  name='recommender.customer_features',
)

Pesquise e navegue nas tabelas de recursos

Use a interface do usuário do Feature Store para pesquisar ou navegar nas tabelas de recursos.

  1. Na barra lateral, selecione Machine Learning > Armazenamento de recursos para exibir a IU do armazenamento de recursos.

  2. Na caixa de pesquisa, insira todo ou parte do nome de uma tabela de recursos, um recurso ou uma fonte de dados usada para cálculo de recursos. Você também pode inserir toda ou parte da key ou valor de uma tag. O texto de pesquisa não diferencia maiúsculas de minúsculas.

    Exemplo de pesquisa de recursos

Obter metadados da tabela de recursos

A API para obter metadados da tabela de recursos depende da versão do Databricks Runtime que você está usando. Com v0.3.6e acima, use get_table. Com v0.3.5 e abaixo, use get_feature_table.

# this example works with v0.3.6 and above
# for v0.3.5, use `get_feature_table`
from databricks.feature_store import FeatureStoreClient
fs = FeatureStoreClient()
fs.get_table("feature_store_example.user_feature_table")

Trabalhar com tags de tabela de recursos

tags são valores- keypar que você pode criar e usar para pesquisar tabelas de recursos. Você pode criar, editar e excluir tags usando o recurso Store UI ou o recurso Store Python API.

Trabalhar com tags de tabela de recursos na interface do usuário

Use a interface do usuário do Feature Store para pesquisar ou navegar nas tabelas de recursos. Para acessar a IU, na barra lateral, selecione Machine Learning > recurso Store.

Adicionar tags usando a interface do usuário da loja de recursos

  1. Clique ícone tags se ainda não estiver aberto. A tabela de tags é exibida.

    tabela de tags

  2. Clique nos campos Nome e Valor e insira a key e o valor de suas tags.

  3. Clique em Adicionar.

Edite ou exclua tags usando a interface do usuário da loja de recursos

Para editar ou excluir tags existentes, use os ícones na coluna Ações .

ações tags

Trabalhe com tags de tabela de recursos usando a API Python do Feature Store

Em clusters executando v0.4.1e acima, você pode criar, editar e excluir tags usando o recurso Store Python API.

Requisitos

cliente da loja de recurso v0.4.1e acima

Criar tabela de recursos com tags usando a API Python do Feature Store 

from databricks.feature_store import FeatureStoreClient
fs = FeatureStoreClient()

customer_feature_table = fs.create_table(
  ...
  tags={"tag_key_1": "tag_value_1", "tag_key_2": "tag_value_2", ...},
  ...
)

Adicione, atualize e exclua tags usando o recurso Store Python API 

from databricks.feature_store import FeatureStoreClient
fs = FeatureStoreClient()

# Upsert a tag
fs.set_feature_table_tag(table_name="my_table", key="quality", value="gold")

# Delete a tag
fs.delete_feature_table_tag(table_name="my_table", key="quality")

Atualizar fonte de dados para uma tabela de recursos

repositório de recursos rastreia automaticamente a fonte de dados usada para compute recursos. Você também pode atualizar manualmente a fonte de dados usando o recurso Store Python API.

Requisitos

cliente da loja de recurso v0.5.0e acima

Adicionar fonte de dados usando o recurso Store Python API

abaixo estão alguns exemplos de comandos. Para obter detalhes, consulte a documentação da API.

from databricks.feature_store import FeatureStoreClient
fs = FeatureStoreClient()

# Use `source_type="table"` to add a table in the metastore as data source.
fs.add_data_sources(feature_table_name="clicks", data_sources="user_info.clicks", source_type="table")

# Use `source_type="path"` to add a data source in path format.
fs.add_data_sources(feature_table_name="user_metrics", data_sources="dbfs:/FileStore/user_metrics.json", source_type="path")

# Use `source_type="custom"` if the source is not a table or a path.
fs.add_data_sources(feature_table_name="user_metrics", data_sources="user_metrics.txt", source_type="custom")

Excluir fonte de dados usando o recurso Store Python API

Para obter detalhes, consulte a documentação da API.

Observação

O comando a seguir exclui fonte de dados de todos os tipos (“tabela”, “caminho” e “personalizado”) que correspondem aos nomes de origem.

from databricks.feature_store import FeatureStoreClient
fs = FeatureStoreClient()
fs.delete_data_sources(feature_table_name="clicks", sources_names="user_info.clicks")

Excluir uma tabela de recursos

Você pode excluir uma tabela de recursos usando a interface do usuário do Feature Store ou a API Python do Feature Store.

Observação

  • A exclusão de uma tabela de recursos pode levar a falhas inesperadas em produtores upstream e consumidores downstream (modelos, endpoint e Job agendado).

  • Quando você exclui uma tabela de recursos usando a API, a tabela Delta subjacente também é descartada. Ao excluir uma tabela de recursos da interface do usuário, você deve descartar a tabela Delta subjacente separadamente.

Excluir uma tabela de recursos usando a IU

  1. Na página da tabela de recursos, clique em Botão para baixo à direita do nome da tabela de recursos e selecione Delete (Excluir). Se o senhor não tiver a permissão CAN gerenciar para a tabela de recursos, não verá essa opção.

    Selecione excluir no menu suspenso

  2. Na caixa de diálogo Excluir tabela de recursos, clique em Excluir para confirmar.

  3. Se você também deseja eliminar a tabela Delta subjacente, execute o seguinte comando em um Notebook.

    %sql DROP TABLE IF EXISTS <feature-table-name>;

Excluir uma tabela de recursos usando a API Python do Feature Store

Com o cliente Feature Store v0.4.1e acima, você pode usar drop_table para excluir uma tabela de recursos. Quando você exclui uma tabela com drop_table, a tabela Delta subjacente também é descartada.

fs.drop_table(
  name='recommender_system.customer_features'
)