Conceitos de materialização de conjuntos de funcionalidades

A materialização calcula valores de características a partir dos dados de origem. Os valores de hora de início e hora de término definem uma janela de recurso. Um trabalho de materialização calcula características nesta janela de características. Os valores de funcionalidades materializados são então armazenados numa loja de materialização online ou offline. Após a materialização dos dados, todas as consultas de características podem então usar esses valores do repositório de materialização.

Sem materialização, uma consulta offline de conjunto de funcionalidades aplica as transformações nos dados de origem em tempo real, para calcular as funcionalidades antes de a consulta devolver os valores. Este processo funciona bem na fase de prototipagem. No entanto, para operações de treinamento e inferência, em um ambiente de produção, as características devem ser materializadas antes do treinamento ou inferência. A materialização nesta fase proporciona uma maior fiabilidade e disponibilidade.

Explorando a materialização de características

A interface de trabalhos de materialização exibe o estado da materialização de dados em repositórios de materialização offline e online, e uma lista dos trabalhos de materialização.

Em uma janela de recurso:

• O gráfico de séries temporais na parte superior mostra os intervalos de dados que estão incluídos na janela de funcionalidades, com o status de materialização, para lojas offline e online.
• A lista de trabalhos na parte inferior mostra todos os trabalhos de materialização com janelas de processamento que se sobrepõem à janela de recursos selecionada.

Estado e intervalo de materialização dos dados

Um intervalo de dados é uma janela de tempo na qual o conjunto de recursos materializa seus valores de recurso para um destes status:

• Completo (verde) - materialização de dados bem-sucedida
• Incompleto (vermelho) - um ou mais trabalhos de materialização cancelados ou com falha para este intervalo de dados
• Pendente (azul) - um ou mais trabalhos de materialização para este intervalo de dados estão em andamento
• Nenhum (cinza) - nenhum trabalho de materialização foi enviado para este intervalo de dados

À medida que os trabalhos de materialização são executados para o conjunto de recursos, eles criam ou mesclam intervalos de dados:

• Quando dois intervalos de dados são contínuos na linha do tempo e têm o mesmo status de materialização de dados, eles se tornam um intervalo de dados
• Em um intervalo de dados, quando uma parte das características é rematerializada e essa parte obtém um status de materialização diferente, esse intervalo de dados é dividido em vários intervalos.

Quando um usuário seleciona uma janela de recurso, vários intervalos de dados, com diferentes status de materialização de dados, podem aparecer nessa janela. Além disso, podem também aparecer múltiplos intervalos de dados, que estão desconexos na linha temporal. Por exemplo, a captura anterior tem 16 intervalos de dados para a janela de funcionalidades definida no armazenamento offline de materialização.

A qualquer momento, um conjunto de recursos pode ter no máximo 2.000 intervalos de dados. Quando um conjunto de recursos atinge esse limite, não é possível executar mais trabalhos de materialização. Os usuários devem então criar uma nova versão do conjunto de recursos, com a materialização habilitada. Para a nova versão do conjunto de funcionalidades, materialize as funcionalidades nas lojas offline e online a partir do zero.

Para evitar o limite, os utilizadores devem executar processos de backfill antecipadamente para preencher as lacunas nos intervalos de dados. Isso mescla os intervalos de dados e reduz a contagem total.

Trabalhos de materialização de dados

Antes de executar um trabalho de materialização de dados, habilite as materializações de dados offline e/ou online no nível do conjunto de recursos.

from azure.ai.ml.entities import (
    MaterializationSettings,
    MaterializationComputeResource,
)

# Turn on both offline and online materialization on the "accounts" featureset.

accounts_fset_config = fs_client._featuresets.get(name="accounts", version="1")

accounts_fset_config.materialization_settings = MaterializationSettings(
    offline_enabled=True,
    online_enabled=True,
    resource=MaterializationComputeResource(instance_type="standard_e8s_v3"),
    spark_configuration={
        "spark.driver.cores": 4,
        "spark.driver.memory": "36g",
        "spark.executor.cores": 4,
        "spark.executor.memory": "36g",
        "spark.executor.instances": 2,
    },
    schedule=None,
)

fs_poller = fs_client.feature_sets.begin_create_or_update(accounts_fset_config)
print(fs_poller.result())

Você pode enviar os trabalhos de materialização de dados como:

• um trabalho de preenchimento - um trabalho de materialização em lote enviado manualmente
• Um trabalho de materialização recorrente - um trabalho de materialização automática acionado em um intervalo programado.

Você pode enviar trabalhos de backfill da seguinte forma:

• Estado de materialização dos dados
• O ID de um trabalho de materialização cancelado ou com falha

Reposição de dados segundo o estado da materialização de dados

Os usuários podem enviar uma solicitação de preenchimento com:

• Uma lista de valores de status de materialização de dados - Incompleto, Completo ou Nenhum
• Uma janela de recurso (opcional)

from datetime import datetime
from azure.ai.ml.entities import DataAvailabilityStatus

st = datetime(2022, 1, 1, 0, 0, 0, 0)
et = datetime(2023, 6, 30, 0, 0, 0, 0)

poller = fs_client.feature_sets.begin_backfill(
    name="transactions",
    version="1",
    feature_window_start_time=st,
    feature_window_end_time=et,
    data_status=[DataAvailabilityStatus.NONE],
)
print(poller.result().job_ids)

Após o envio da solicitação de preenchimento, um novo trabalho de materialização é criado para cada intervalo de dados que tem um status de materialização de dados correspondente (Incompleto, Completo ou Nenhum). Além disso, os intervalos de dados relevantes devem estar dentro da janela de recurso definida. Se o status de materialização de dados for Pending para um intervalo de dados, nenhum trabalho de materialização será enviado para esse intervalo.

A hora de início e a hora de término da janela de recurso são opcionais na solicitação de preenchimento:

• Se o tempo de início da janela de funcionalidades não for fornecido, o tempo de início será determinado como o tempo de início do primeiro intervalo de dados que não possui um estado de materialização de dados de None.
• Se a hora de término da janela de funcionalidades não for fornecida, a hora de término será definida como a hora de término do último intervalo de dados que não possui um estado de materialização de dados de None.

Este exemplo tem estes valores atuais de intervalo de dados e status de materialização:

Esta solicitação de preenchimento tem estes valores:

• Materialização de dados data_status=[DataAvailabilityStatus.Complete, DataAvailabilityStatus.Incomplete]
• Início da janela de funcionalidades = 2025-04-02T12:00:00.000
• Fim da janela de recurso = 2025-04-04T12:00:00.000

Cria os seguintes postos de trabalho de materialização:

• Tarefa 1: janela de atributos do processo [2025-04-02T12:00:00.000, 2025-04-03T04:00:00.000)
• Trabalho 2: janela de características do processo [2025-04-04T04:00:00.000, 2025-04-04T12:00:00.000)

Se ambos os trabalhos forem concluídos com êxito, os novos valores de intervalo de dados e status de materialização se tornarão:

Um novo intervalo de dados é criado no dia 2025-04-02, porque metade desse dia tem agora um estado de materialização diferente: Complete. Embora um novo trabalho de materialização tenha corrido durante metade do dia de 2025-04-04, o intervalo de dados não foi alterado (dividido) porque o estado da materialização não mudou.

Se o utilizador fizer uma solicitação de backfill apenas com a materialização de dados data_status=[DataAvailabilityStatus.Complete, DataAvailabilityStatus.Incomplete], sem definir o tempo de início e fim da janela de recurso, a solicitação usará o valor padrão dos parâmetros mencionados anteriormente nesta secção e cria estes trabalhos:

• Tarefa 1: janela de características do processo [2025-04-02T04:00:00.000, 2025-04-03T04:00:00.000)
• Trabalho 2: janela de característica do processo [2025-04-04T04:00:00.000, 2025-04-05T04:00:00.000)

Compare a janela de recursos para esses trabalhos de solicitação mais recentes e os trabalhos de solicitação mostrados no exemplo anterior.

Preenchimento de dados por ID de tarefa

Uma solicitação de preenchimento também pode ser criada com uma ID de trabalho. Esta é uma maneira conveniente de tentar novamente um trabalho de materialização fracassado ou cancelado. Primeiro, encontre o ID do trabalho para tentar novamente:

• Navegue para a interface de utilizador Trabalhos de Materialização do Conjunto de Funcionalidades
• Selecione o Nome para exibição de um trabalho específico que tenha um valor Status com falha
• Na página Visão geral do trabalho, localize o valor de ID do trabalho relevante na propriedade Name. Começa com Featurestore-Materialization-.

poller = fs_client.feature_sets.begin_backfill(
    name="transactions",
    version=version,
    job_id="<JOB_ID_OF_FAILED_MATERIALIZATION_JOB>",
)
print(poller.result().job_ids)

az ml feature-set backfill --by-job-id <JOB_ID_OF_FAILED_MATERIALIZATION_JOB> --name <FEATURE_SET_NAME> --version <VERSION>  --feature-store-name <FEATURE_STORE_NAME> --resource-group <RESOURCE_GROUP>

Você pode enviar uma tarefa de reposição com a ID da tarefa de uma tarefa de materialização reprovada ou cancelada. Nesse caso, o estado de dados da janela de funcionalidades para o trabalho de materialização original com falha ou que foi cancelado deve ser Incomplete. Se essa condição não for atendida, o trabalho de preenchimento por ID resultará em um erro do usuário. Por exemplo, um trabalho de materialização com falha pode ter um valor de hora de início da feature window2025-04-01T04:00:00.000 e um valor de hora de término 2025-04-09T04:00:00.000. Um trabalho de preenchimento enviado usando a ID deste trabalho com falha só será bem-sucedido se o estado dos dados em todo o lado, no intervalo de tempo de 2025-04-01T04:00:00.000 a 2025-04-09T04:00:00.000, for Incomplete.

Documentação de orientação e melhores práticas

Definir source_delay um cronograma adequado e recorrente

A source_delay propriedade para os dados de origem indica o atraso entre o tempo de aquisição de dados prontos para consumo, em comparação com o tempo de evento da geração de dados. Um evento que aconteceu no momento t é inserido na tabela de dados de origem no momento t + x, devido à latência do pipeline de dados a montante. O valor de x é o atraso de origem.

Para uma configuração adequada, o cronograma de trabalho de materialização recorrente leva em conta a latência. O trabalho recorrente produz funcionalidades para a janela temporal de [schedule_trigger_time - source_delay - schedule_interval, schedule_trigger_time - source_delay).

materialization_settings:
  schedule:
    type: recurrence
    interval: 1
    frequency: Day
    start_time: "2025-04-15T04:00:00.000"

Este exemplo define um trabalho diário que é ativado às 4 da manhã, começando a 15/04/2025. Dependendo da source_delay definição, a execução do trabalho de 01/05/2025 produz funcionalidades em diferentes janelas temporais:

• source_delay=0 produz valores de características na janela [2025-04-30T04:00:00.000, 2025-05-01T04:00:00.000)
• source_delay=2hours produz valores de características na janela [2025-04-30T02:00:00.000, 2025-05-01T02:00:00.000)
• source_delay=4hours Produz valores de características na janela [2025-04-30T00:00:00.000, 2025-05-01T00:00:00.000)

Atualizar armazenamento de materialização

Antes de atualizar uma loja de recursos online ou uma loja de materialização offline, todos os conjuntos de recursos nessa loja de recursos devem ter a materialização offline e/ou online correspondente desabilitada. A operação de atualização falha como UserError se alguns conjuntos de funcionalidades tiverem a materialização habilitada.

O estado de materialização dos dados na loja de materialização offline e/ou online é reiniciado se a materialização offline e/ou online estiver desativada num conjunto de características. A redefinição torna os dados materializados inutilizáveis. Se a materialização offline e/ou online no conjunto de recursos for habilitada posteriormente, os usuários deverão reenviar seus trabalhos de materialização.

Bootstrap de dados online

O bootstrap de dados online é aplicável somente se as tarefas de materialização offline enviadas tiverem sido concluídas com sucesso. Se apenas a materialização offline foi inicialmente habilitada para um conjunto de recursos e a materialização online é habilitada posteriormente, então:

• O estado padrão de materialização dos dados na loja online é None

• Quando um trabalho de materialização online é enviado, os dados com o estado de materialização Complete na loja offline são usados para calcular funcionalidades online. Isso é chamado de arranque de dados online. A inicialização de dados online economiza custo computacional porque reutiliza características já computadas e salvas no repositório de materialização offline. Esta tabela resume os valores de status de dados offline e online em intervalos de dados que resultam na inicialização de dados online.

  Hora de início	Hora de fim	Estado dos dados offline	Estado dos dados online	Inicialização de dados online
  2025-04-01T04:00:00.000	2025-04-02T04:00:00.000	None	None	Não
  2025-04-02T04:00:00.000	2025-04-03T04:00:00.000	Incomplete	None	Não
  2025-04-03T04:00:00.000	2025-04-04T04:00:00.000	Pending	None	Nenhuma tarefa de materialização foi submetida
  2025-04-04T04:00:00.000	2025-04-05T04:00:00.000	Complete	None	Sim

Corrigir erros e modificações de dados de origem

Alguns cenários modificam os dados de origem devido a um erro, ou outros motivos, após a materialização dos dados. Nesses casos, uma atualização de dados de recurso, para uma janela de recurso específica em vários intervalos de dados, pode resolver dados de recurso errados ou obsoletos. Envie a solicitação de materialização para a resolução de dados de recursos incorretos ou obsoletos na janela de recurso, para os estados dos dados None, Complete e Incomplete.

Você deve enviar uma solicitação de materialização para uma atualização de dados da funcionalidade somente quando a janela da funcionalidade não contiver nenhum intervalo de dados com um status de Pending dados.

Preencher as lacunas

No armazenamento de materialização, os dados materializados podem ter lacunas porque:

• um trabalho de materialização nunca foi submetido para a janela de funcionalidades
• Os trabalhos de materialização enviados para a janela de recursos falharam ou foram cancelados

Neste caso, envie uma solicitação de materialização na janela de recursos para data_status=[DataAvailabilityStatus.NONE,DataAvailabilityStatus.Incomplete] preencher as lacunas. Uma única solicitação de materialização preenche todas as lacunas na janela de recursos.

Próximos passos

• Tutorial 1: Desenvolver e registrar um conjunto de recursos com o repositório de recursos gerenciados
• Repositório de exemplo do GitHub