Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Neste tutorial, você criará uma função de tabela definida pelo usuário (UDTF) em Python no Lakeflow Designer que executa o agrupamento K-means com o scikit-learn. UDTFs são adequados para tarefas de aprendizado de máquina que processam conjuntos de dados inteiros. Para informações sobre operadores personalizados, veja Operadores personalizados no Lakeflow Designer.
Visão geral
Este tutorial orienta você passo a passo na criação de um operador personalizado UDTF usando Python. O operador realiza o agrupamento K-Means nas colunas selecionadas, permitindo aos usuários:
- Escolha quais colunas usar como recursos.
- Especifique o número de clusters.
- Retorne uma tabela com atribuições de cluster para cada linha.
Requirements
- Acesso ao Lakeflow Designer em um espaço de trabalho habilitado pelo Unity Catalog. Consulte Pré-requisitos.
-
USE CATALOGno catálogomaineCREATE SCHEMAemmainouUSE SCHEMAeCREATE FUNCTIONem um esquemamain.example_outputexistente. Para usar um catálogo ou esquema diferente, substituamain.example_outputpor completo. Consulte Referência de privilégios do Catálogo do Unity. - Compute que pode rodar UDTFs em Python do Unity Catalog. Consulte funções de tabela definidas pelo usuário (UDTFs) em Python no Unity Catalog.
Etapa 1: Entender o padrão de manipulador UDTF
Um UDTF é implementado como uma classe Python com três métodos principais:
-
__init__(): Chamado uma vez, antes que quaisquer linhas sejam processadas para inicializar o estado. -
eval(row, ...): chamado para cada linha de entrada para acumular dados. -
terminate(): chamado depois que todas as linhas são processadas para produzir resultados.
Esse padrão permite que o UDTF:
- Coletar todos os pontos de dados durante
eval()chamadas - Treine o modelo K-Means em
terminate() - Produzir resultados clusterizados linha por linha
O __init__ método é executado uma vez, antes que qualquer linha seja processada. Define o estado que persiste entre chamadas de eval(): a configuração (coluna de ID, colunas de atributos, número de clusters) e os acumuladores para os dados das linhas e os atributos.
class SklearnKMeans:
def __init__(self):
# State set here persists across eval() calls for use in terminate()
self.id_col = None
self.feature_cols = None
self.k = None
self.rows = []
self.features = []
eval() é executado uma vez para cada linha de entrada. Ele captura a configuração da primeira linha e depois acumula cada linha e seus valores numéricos de características.
def eval(self, row, id_column, columns, k):
if self.id_col is None:
self.id_col = id_column
if self.feature_cols is None:
self.feature_cols = columns
if self.k is None:
self.k = max(1, int(k))
row_dict = row.asDict(recursive=False)
self.rows.append(row_dict)
feats = []
for c in self.feature_cols:
v = row_dict.get(c)
if v is None:
v = 0.0
feats.append(float(v))
self.features.append(feats)
Note
O parâmetro row em eval() é um objeto Row do PySpark. Use .asDict() para convertê-lo em um dicionário para facilitar o acesso.
terminate() é executado após todas as linhas serem acumuladas. Ele treina o modelo K-Means nas características coletadas e gera uma linha de saída por linha de entrada, emparelhando o ID de cada linha com seu cluster atribuído.
def terminate(self):
import numpy as np
from sklearn.cluster import KMeans
if not self.rows:
return
X = np.asarray(self.features, dtype=float)
n_samples = X.shape[0]
n_clusters = min(self.k, n_samples)
model = KMeans(
n_clusters=n_clusters,
n_init=10,
random_state=42
)
labels = model.fit_predict(X)
for row_dict, label in zip(self.rows, labels):
yield str(row_dict[self.id_col]), int(label)
Etapa 2: Criar o YAML para o operador
A configuração yaml define como o operador aparece no Lakeflow Designer. Para este operador:
-
Parâmetro de número (
k): número de clusters a serem criados -
Selecionar widget (
id_column): lista suspensa preenchida com colunas da tabela de entrada -
Widget de seleção múltipla (
columns): seleção de várias colunas de recursos -
optionsSource: preenche automaticamente as listas suspensas do esquema da tabela de entrada - Porta de entrada: especifica que esse operador aceita dados tabulares
schema: custom-operator-v0.2.0
type: uc-udtf
name: K-Means Clustering
id: kmeans
version: '1.0.0'
description: Perform K-Means clustering on selected columns
config:
type: object
properties:
k:
type: number
title: Number of Clusters
default: 3
minimum: 1
maximum: 100
x-ui:
widget: number
id_column:
type: string
title: ID Column
x-ui:
widget: select
optionsSource:
type: inputColumns
port: input_data
columns:
type: array
items:
type: string
title: Feature Columns
x-ui:
widget: multi-select
optionsSource:
type: inputColumns
port: input_data
required:
- k
- id_column
- columns
additionalProperties: false
ports:
input:
- name: input_data
title: Input Data
output:
- name: output
title: Clustered Data
Para todas as propriedades disponíveis, tipos de dados, widgets e opções, veja Referência YAML de operador personalizado.
Etapa 3: Criar a função catálogo do Unity
Combine a configuração YAML e a classe de manipulador Python em uma única instrução CREATE FUNCTION.
O exemplo cria a função em main.example_output. Crie o esquema primeiro se ele não existir:
CREATE SCHEMA IF NOT EXISTS main.example_output
CREATE OR REPLACE FUNCTION main.example_output.k_means(
input_data TABLE,
id_column STRING,
columns ARRAY<STRING>,
k INT
)
RETURNS TABLE (
id STRING,
cluster_id INT
)
LANGUAGE PYTHON
HANDLER 'SklearnKMeans'
AS $$
"""
schema: custom-operator-v0.2.0
type: uc-udtf
name: K-Means Clustering
id: kmeans
version: "1.0.0"
description: Perform K-Means clustering on selected columns
config:
type: object
properties:
k:
type: number
title: Number of Clusters
default: 3
minimum: 1
maximum: 100
x-ui:
widget: number
id_column:
type: string
title: ID Column
x-ui:
widget: select
optionsSource:
type: inputColumns
port: input_data
columns:
type: array
items:
type: string
title: Feature Columns
x-ui:
widget: multi-select
optionsSource:
type: inputColumns
port: input_data
required:
- k
- id_column
- columns
additionalProperties: false
ports:
input:
- name: input_data
title: Input Data
output:
- name: output
title: Clustered Data
"""
class SklearnKMeans:
def __init__(self):
self.id_col = None
self.feature_cols = None
self.k = None
self.rows = []
self.features = []
def eval(self, row, id_column, columns, k):
if self.id_col is None:
self.id_col = id_column
if self.feature_cols is None:
self.feature_cols = columns
if self.k is None:
self.k = max(1, int(k))
row_dict = row.asDict(recursive=False)
self.rows.append(row_dict)
feats = []
for c in self.feature_cols:
v = row_dict.get(c)
if v is None:
v = 0.0
feats.append(float(v))
self.features.append(feats)
def terminate(self):
import numpy as np
from sklearn.cluster import KMeans
if not self.rows:
return
X = np.asarray(self.features, dtype=float)
n_samples = X.shape[0]
n_clusters = min(self.k, n_samples)
model = KMeans(
n_clusters=n_clusters,
n_init=10,
random_state=42
)
labels = model.fit_predict(X)
for row_dict, label in zip(self.rows, labels):
yield str(row_dict[self.id_col]), int(label)
$$
Etapa 4: Testar com dados de exemplo
Crie dados de cliente de exemplo para teste:
CREATE OR REPLACE TEMP VIEW customers AS
SELECT * FROM VALUES
('C001', 25, 35000, 20),
('C002', 45, 85000, 80),
('C003', 35, 55000, 50),
('C004', 50, 95000, 90),
('C005', 23, 30000, 15),
('C006', 40, 75000, 70),
('C007', 60, 100000, 95),
('C008', 30, 45000, 40)
AS t(customer_id, age, annual_income, spending_score);
Teste o K-Means UDTF com três clusters:
SELECT * FROM main.example_output.k_means(
input_data => TABLE(SELECT * FROM customers) WITH SINGLE PARTITION,
k => 3,
id_column => 'customer_id',
columns => array('age', 'annual_income', 'spending_score')
)
Nesse caso, você deseja unir os resultados do clustering de volta com os dados originais para ver as atribuições de cluster:
SELECT
c.*,
k.cluster_id
FROM customers c
INNER JOIN main.example_output.k_means(
input_data => TABLE(SELECT * FROM customers) WITH SINGLE PARTITION,
k => 3,
id_column => 'customer_id',
columns => array('age', 'annual_income', 'spending_score')
) k
ON c.customer_id = k.id
ORDER BY k.cluster_id, c.customer_id
Etapa 5: Registrar o operador
Para usar o operador no Lakeflow Designer, você deve registrá-lo adicionando-o ao seu .custom_operators.yaml arquivo:
operators:
- catalog: main
schema: example_output
functionName: k_means
Note
Se você definir esse arquivo em sua pasta de usuário, ele será exibido apenas para você. Para mais informações, veja como registrar e implantar seu operador no Lakeflow Designer.
Etapa 6: Configurar permissões
Conceda acesso aos usuários que precisam usar este operador:
GRANT USE SCHEMA ON SCHEMA main.example_output TO `<user>`;
GRANT EXECUTE ON FUNCTION main.example_output.k_means TO `<user>`;
Passo 7: Use o operador no Lakeflow Designer
- Em uma preparação visual de dados, abra o menu Operadores no painel esquerdo e encontre o operador de Clustering K-Means .
- Arraste o operador para o canvas e conecte uma entrada a ele.
- Clique duas vezes no operador para abrir seu painel de configuração e então defina seus campos.
- Selecione o operador para visualizar seus resultados no painel de saída.
O operador possui:
- Uma porta de entrada para conectar sua fonte de dados
- Uma lista suspensa para selecionar qual coluna identifica cada linha de forma exclusiva
- Uma seleção múltipla para escolher quais colunas usar como recursos de clustering
- Uma entrada numérica para o número desejado de clusters
Os usuários podem segmentar clientes, produtos ou quaisquer outros dados em grupos significativos sem escrever código.
Dicas para criar UDTFs
-
Inicializar o estado em
__init__: Configurar listas/variáveis vazias para acumular dados -
Acumular em
eval: Não processe ainda, apenas colete os dados -
Processo em
terminate: É aqui que o trabalho real acontece -
Usar
yieldpara retornar linhas: retornar resultados um de cada vez determinate - Lidar com casos extremos: e se houver menos linhas do que clusters?
- Manter os tipos explícitos: os retornos UDTF não podem referenciar tipos de entrada