Snowflake Data Clean Rooms : Créez un modèle d’analyse personnalisé avec une interface utilisateur¶

Mise en place de l’environnement¶

Avant d’utiliser les APIs du développeur, vous devez assumer le rôle SAMOOHA_APP_ROLE et spécifier l’entrepôt utilisé pour exécuter les APIs. Si vous n’avez pas le rôle SAMOOHA_APP_ROLE, contactez votre administrateur de compte.

Exécutez les commandes suivantes pour configurer votre environnement :

USE ROLE samooha_app_role;
USE WAREHOUSE app_wh;

Créer la salle blanche¶

Avant de créer une salle blanche, vous devez spécifier un nom alphanumérique pour la salle blanche. Le nom ne peut pas contenir de caractères spéciaux, à l’exception des espaces et des traits de soulignement. Veillez à ce que le nom de la salle blanche ne vienne pas dupliquer une salle blanche existante.

Pour spécifier le nom de la salle blanche, exécutez la commande suivante :

SET cleanroom_name = 'UI Registration ML Clean room';

Vous êtes maintenant prêt à exécuter la commande provider.cleanroom_init pour créer la salle blanche. Le deuxième argument définit la distribution de la salle blanche. Dans cet exemple, vous choisirez INTERNAL pour contourner l’analyse de sécurité automatisée qui a lieu avant que la salle blanche puisse être publiée aux collaborateurs. Les comptes du fournisseur et du consommateur doivent faire partie de la même organisation pour utiliser la méthode de distribution INTERNAL. Pour les salles blanches distribuées à un compte dans une autre organisation, vous devez utiliser une distribution EXTERNAL.

Pour créer la salle blanche, exécutez la commande suivante :

CALL samooha_by_snowflake_local_db.provider.cleanroom_init($cleanroom_name, 'INTERNAL');

Après avoir créé une salle blanche, vous devez définir sa directive de version avant de pouvoir la partager avec un collaborateur.

CALL samooha_by_snowflake_local_db.provider.view_cleanroom_scan_status($cleanroom_name);

Pour définir la directive de version pour la salle blanche, exécutez la commande suivante :

CALL samooha_by_snowflake_local_db.provider.set_default_release_directive($cleanroom_name, 'V1_0', '0');

Ajouter vos données et définir des politiques de jointure¶

Liez les tables Snowflake à la salle blanche, parcourez la liste des tables de votre compte Snowflake et saisissez les noms de table entièrement qualifiés (Database.Schema.Table) sous la forme d’un tableau. La procédure rend automatiquement la table accessible à la salle blanche en créant une vue sécurisée de la table depuis l’intérieur de la salle blanche, évitant ainsi tout besoin de faire une copie de votre table.

CALL samooha_by_snowflake_local_db.provider.link_datasets($cleanroom_name, ['samooha_provider_sample_database.lookalike_modeling.customers']);

USE ROLE accountadmin;
CALL samooha_by_snowflake_local_db.provider.register_db('<DATABASE_NAME>');
USE ROLE samooha_app_role;

Vous pouvez voir les noms des ensembles de données liés à la salle blanche en appelant la procédure suivante.

CALL samooha_by_snowflake_local_db.provider.view_provider_datasets($cleanroom_name);

Vous pouvez voir les ensembles de données liés à la salle blanche en utilisant la requête suivante :

SELECT * FROM <PROVIDER_TABLE> LIMIT 10;

Indiquez quelles colonnes le consommateur est autorisé à joindre lors de l’exécution de modèles dans la salle blanche. Cette procédure doit être appelée sur les colonnes d’identité comme l’adresse e-mail. La politique de jointure est de type « remplacement uniquement », donc si la fonction est appelée à nouveau, la politique de jointure précédemment définie est entièrement remplacée par la nouvelle.

CALL samooha_by_snowflake_local_db.provider.set_join_policy($cleanroom_name, ['samooha_provider_sample_database.lookalike_modeling.customers:hashed_email']);

Si vous souhaitez voir toutes les colonnes pour décider des colonnes de la politique de jointure, appelez la procédure suivante.

CALL samooha_by_snowflake_local_db.provider.view_join_policy($cleanroom_name);

Ajouter votre code personnalisé¶

CALL samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
    $cleanroom_name,
    'lookalike_train',
    ['input_data variant', 'labels variant'],
    ['pandas', 'numpy', 'xgboost'],
    'variant',
    'train',
$$
import numpy as np
import pandas as pd
import xgboost
from sklearn import preprocessing
import sys
import os
import pickle
import codecs
import threading


class TrainXGBoostClassifier(object):
    def __init__(self):
        self.model = None
        self._params = {
            "objective": "binary:logistic",
            "max_depth": 3,
            "nthread": 1,
            "eval_metric": "auc",
        }
        self.num_boosting_rounds = 10

    def get_params(self):
        if self.model is not None and "updater" not in self._params:
            self._params.update(
                {"process_type": "update", "updater": "refresh", "refresh_leaf": True}
            )
        return self._params

    def train(self, X, y):
        # Train the model in a threadsafe way

        # pick only the categorical attributes
        categorical = X.select_dtypes(include=[object])

        # fit a one-hot-encoder to convert categorical features to binary features (required by XGBoost)
        ohe = preprocessing.OneHotEncoder()
        categorical_ohe = ohe.fit_transform(categorical)
        self.ohe = ohe

        # get the rest of the features and add them to the binary features
        non_categorical = X.select_dtypes(exclude=[object])
        train_x = np.concatenate((categorical_ohe.toarray(), non_categorical.to_numpy()), axis=1)

        xg_train = xgboost.DMatrix(train_x, label=y)

        params = self.get_params()
        params["eval_metric"] = "auc"
        evallist = [(xg_train, "train")]
        evals_result = {}

        self.model = xgboost.train(
            params, xg_train, self.num_boosting_rounds, evallist, evals_result=evals_result
        )

        self.evals_result = evals_result

    def __dump_model(self, model):
        # Save down the model as a json string to load up for scoring/inference

        pickle_jar = codecs.encode(pickle.dumps([model, self.ohe]), "base64").decode()
        return pickle_jar

    def dump_model(self):
        # Save down the model as a json string to load up for scoring/inference
        if self.model is not None:
            return self.__dump_model(self.model)
        else:
            raise ValueError("Model needs to be trained first")


def train(d1, l1):
    # get take training features and put them in a pandas dataframe
    X = pd.DataFrame(d1)

    # get the labels into a Numpy array
    y = np.array(l1)

    trainer = TrainXGBoostClassifier()
    trainer.train(X, y)

    # return training stats, accuracy, and the pickled model and pickled one-hot-encoder
    return {
        "total_rows": len(d1),
        "total_bytes_in": sys.getsizeof(d1),
        "model": trainer.dump_model(),
        "iteration": trainer.num_boosting_rounds,
        "auc": np.max(trainer.evals_result["train"]["auc"]),
        "error": 1 - np.max(trainer.evals_result["train"]["auc"])
    }   
$$);

CALL samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
    $cleanroom_name,
    'lookalike_score',
    ['pickle_jar variant', 'emails variant', 'features variant'],
    ['pandas', 'numpy', 'xgboost', 'scikit-learn'],
    'string',
    'score',
$$
import numpy as np
import pandas as pd
import xgboost as xgb
import pickle
import codecs
import json


def score(model, emails, features):
    # load model
    model = model[0] if not isinstance(model, str) else model
    model = pickle.loads(codecs.decode(model.encode(), "base64"))

    # retrieve the XGBoost trainer from the pickle jar
    bst = model[0]

    # retrieve the fitted one-hot-encoder from the pickle jar
    ohe2 = model[1]

    # create pandas dataframe from the inference features
    Y = pd.DataFrame(features)

    # select the categorical attributes and one-hot-encode them
    Y1 = Y.select_dtypes(include=[object])
    Y2 = ohe2.transform(Y1)

    # select the non-categorical attributes
    Y3 = Y.select_dtypes(exclude=[object])

    # join the results of the one-hot encoding to the rest of the attributes
    Y_pred = np.concatenate((Y2.toarray(), Y3.to_numpy()), axis=1)

    # inference
    dscore = xgb.DMatrix(Y_pred)
    pred = bst.predict(dscore)

    retval = list(zip(np.array(emails), list(map(str, pred))))
    retval = [{"email": r[0], "score": r[1]} for r in retval]
    return json.dumps(retval)  
$$);

-- See the versions available inside the cleanroom
SHOW VERSIONS IN APPLICATION PACKAGE samooha_cleanroom_UI_Registration_ML_clean_room;

-- Once the security scan is approved, update the release directive to the latest version
CALL samooha_by_snowflake_local_db.provider.set_default_release_directive($cleanroom_name, 'V1_0', '2');

CALL samooha_by_snowflake_local_db.provider.add_custom_sql_template($cleanroom_name, 'prod_custom_lookalike_template',
$$
WITH
features AS (
    SELECT
        identifier({{ provider_join_col | join_policy }}) AS joincol,
        array_construct({{ dimensions[0] | sqlsafe }} {% for feat in dimensions[1:] %} , {{ feat | sqlsafe }} {% endfor %}) AS features
    FROM
        identifier({{ source_table[0] }}) AS p
),
labels AS (
    SELECT
        c.{{ consumer_join_col | sqlsafe }} AS joincol,
        c.{{ filter_column | default('SALES_DLR') | sqlsafe }} {{ operator | default('>=') | sqlsafe }} {{ filter_value | default(2000) | sqlsafe }} AS label_value
    FROM
        identifier({{ my_table[0] }}) AS c
),
trained_model AS (
    SELECT
        train_out:model::varchar AS model,
        train_out:error::float AS error
    FROM (
      SELECT
        cleanroom.{{ lookalike_train_function | default('lookalike_train') | sqlsafe }}(array_agg(f.features), array_agg(l.label_value)) AS train_out
      FROM features f, labels l
      WHERE f.joincol = l.joincol
    )
),
inference_output AS (
    SELECT
        MOD(seq4(), 100) AS batch,
        cleanroom.{{ lookalike_score_function | default('lookalike_score') | sqlsafe }}(
            array_agg(distinct t.model), 
            array_agg(identifier({{ provider_join_col | join_policy }})), 
            array_agg(array_construct( identifier({{ dimensions[0] }}) {% for feat in dimensions[1:] %} , identifier({{ feat }}) {% endfor %}) )
        ) AS scores
    FROM trained_model t, identifier({{ source_table[0] }}) p
    WHERE identifier({{ provider_join_col | join_policy }}) NOT IN (SELECT c.{{ consumer_join_col | sqlsafe }} FROM identifier({{ my_table[0] }}) c)
    GROUP BY batch
),
processed_output AS (
    SELECT value:email::string as id, value:score::float AS score FROM (select scores from inference_output), lateral flatten(input => parse_json(scores))
), train_results AS (
    SELECT {{ num_boosting_rounds | sqlsafe }} AS num_boosting_rounds, {{ trim_extremes | sqlsafe }} AS trim_extremes, p.audience_size AS audience_size, t.error AS error FROM (SELECT count(distinct id) AS audience_size FROM processed_output WHERE score > 0.5) p, trained_model t
), seed_size AS (
    select count(*) AS seed_audience_size FROM features f, labels l WHERE f.joincol = l.joincol
)
SELECT s.seed_audience_size, t.audience_size AS num_lookalikes_found, t.error FROM train_results t, seed_size s
$$);

-- Last parameter (Differential Privacy) is optional and omitted here. Default is 1

CALL samooha_by_snowflake_local_db.provider.view_added_templates($cleanroom_name);

Définir les politiques de colonne sur chaque modèle¶

Une fois que vous avez ajouté votre modèle personnalisé, vous pouvez appliquer des politiques de colonne à toutes les colonnes de table définies par ce modèle.

Pour voir les 10 premières lignes de la table mises à la disposition de vos consommateurs, exécutez la requête suivante :

SELECT * FROM <PROVIDER_TABLE> LIMIT 10;

Définissez les colonnes sur lesquelles vous souhaitez effectuer des regroupements, des agrégations (par exemple SUM/AVG) et, d’une manière générale, utiliser une analyse pour chaque combinaison de table et de modèle. Cela offre une certaine souplesse, de sorte qu’une même table peut permettre différentes sélections de colonnes en fonction du modèle sous-jacent. Cette fonction ne doit être appelée qu’après l’ajout du modèle.

Notez que set_column_policy n’est pas additif ; si la fonction est appelée à nouveau, la politique de colonne précédente est entièrement remplacée par la nouvelle.

La politique de colonnes ne doit pas être utilisée pour les colonnes d’identité telles que l’adresse e-mail, HEM, RampID, car vous ne souhaitez pas que le consommateur puisse effectuer des groupes en fonction de ces colonnes. Dans l’environnement de production, le système déduit intelligemment les colonnes PII et bloque cette opération, mais cette fonction n’est pas disponible dans l’environnement sandbox. Elle ne doit être utilisée que pour les colonnes par lesquelles vous souhaitez que le consommateur puisse faire des agrégations et des groupes, comme le statut, la tranche d’âge, le code de région, le nombre de jours d’activité, etc.

CALL samooha_by_snowflake_local_db.provider.set_column_policy($cleanroom_name, [
    'prod_custom_lookalike_template:samooha_provider_sample_database.lookalike_modeling.customers:status', 
    'prod_custom_lookalike_template:samooha_provider_sample_database.lookalike_modeling.customers:age', 
    'prod_custom_lookalike_template:samooha_provider_sample_database.lookalike_modeling.customers:region_code', 
    'prod_custom_lookalike_template:samooha_provider_sample_database.lookalike_modeling.customers:days_active', 
    'prod_custom_lookalike_template:samooha_provider_sample_database.lookalike_modeling.customers:income_bracket'
]);

Si vous souhaitez voir la politique de colonnes qui a été ajoutée à la salle blanche, appelez la procédure suivante.

CALL samooha_by_snowflake_local_db.provider.view_column_policy($cleanroom_name);

Créer et appliquer votre UI modèle¶

Ensuite, vous définirez l’UI pour votre modèle afin que les consommateurs puissent l’utiliser dans le navigateur :

1. Appelez la commande provider.add_ui_form_customizations pour définir la manière dont le modèle apparaît dans l’application Web.

2. Connectez-vous sur le Web en tant que fournisseur.

CALL samooha_by_snowflake_local_db.provider.add_ui_form_customizations(
    $cleanroom_name,
    'prod_custom_lookalike_template',
    {
        'display_name': 'Custom Lookalike Template',
        'description': 'Use our customized ML techniques to find lookalike audiences.',
        'methodology': 'Specify your own seed audience, while matching against our users. Then customize the lookalike model across number of boosting rounds and removing outliers.',
        'warehouse_hints': {
            'warehouse_size': 'medium',
            'snowpark_optimized': TRUE
        }
    },
    {
    'num_boosting_rounds': {
        'display_name': 'Number of Boosting Rounds',
        'type': 'integer',
        'default': 10,
        'order': 7,
        'description': 'How many rounds of boosting should the model do?',
        'size': 'M',
        'group': 'Training & Inference Configuration'
    },
    'trim_extremes': {
        'display_name': 'Trim Extremes',
        'type': 'boolean',
        'default': False,
        'order': 8,
        'description': 'Remove outliers by default?',
        'size': 'M',
        'group': 'Training & Inference Configuration'
    },
    'lookalike_train_function': {
        'display_name': 'Training Function',
        'choices': ['lookalike_train'],
        'type': 'dropdown',
        'order': 9,
        'description': 'Which function do you want to use for training?',
        'size': 'M',
        'group': 'Training & Inference Configuration'
    },
    'lookalike_score_function': {
        'display_name': 'Scoring Function',
        'choices': ['lookalike_score'],
        'type': 'dropdown',
        'order': 10,
        'description': 'Which function do you want to use for scoring?',
        'size': 'M',
        'group': 'Training & Inference Configuration'
    },    
    'provider_join_col': {
        'display_name': 'Provider Join Column',
        'choices': ['p.HASHED_EMAIL'],
        'type': 'dropdown',
        'order': 4,
        'description': 'Select the provider column to join users on.',
        'infoMessage': 'We recommend using HASHED_EMAIL.',
        'size': 'M',
        'group': 'Enable Provider Features'
    },
    'consumer_join_col': {
        'display_name': 'Consumer Join Column',
        'description': 'Specify column in your table that matches the providers (i.e. HASHED_EMAIL).',
        'size': 'M',
        'default': 'HASHED_EMAIL',
        'infoMessage': 'We recommend using HASHED_EMAIL.',
        'order': 5,
        'group': 'Enable Provider Features'
    },
    'dimensions': {
        'display_name': 'Feature Selection',
        'choices': ['p.STATUS', 'p.AGE', 'p.REGION_CODE', 'p.DAYS_ACTIVE'],
        'type': 'multiselect',
        'order': 6,
        'description': 'What features do you want to train on?',
        'infoMessage': 'We recommend selecting all features for maximum signal.',
        'size': 'M',
        'group': 'Enable Provider Features'
    },
    'filter_column': {
        'display_name': 'Filter Column',
        'type': 'any',
        'order': 1,
        'description': 'Specify column in your table to filter for high value users (i.e. SALES_DLR)',
        'size': 'S',
        'default': 'SALES_DLR',
        'infoMessage': 'We recommend you input SALES_DLR over here.',
        'group': 'Seed Audience Selection'
    },
    'operator': {
        'display_name': 'Operator',
        'choices': ['>=', '=', '<='],
        'type': 'dropdown',
        'order': 2,
        'description': 'What is the operator your want to use for the filter?',
        'size': 'S',
        'group': 'Seed Audience Selection'
    },
    'filter_value': {
        'display_name': 'Filter Value',
        'order': 3,
        'description': 'What value do you want to filter to?',
        'default': 2000,        
        'size': 'S',
        'group': 'Seed Audience Selection'
    }
}, {
    'measure_columns': ['seed_audience_size', 'audience_size', 'num_lookalikes_found', 'error'],
    'default_output_type': 'BAR'
});

Partager avec un consommateur¶

Enfin, ajoutez un consommateur de données à la salle blanche en ajoutant son localisateur de compte Snowflake et ses noms de compte, comme indiqué ci-dessous. Le nom du compte Snowflake doit être de la forme suivante : <ORGANIZATION>.<ACCOUNT_NAME>.

SHOW VERSIONS IN APPLICATION PACKAGE samooha_cleanroom_UI_Registration_ML_clean_room;

CALL samooha_by_snowflake_local_db.provider.add_consumers($cleanroom_name, '<CONSUMER_ACCOUNT_LOCATOR>', '<CONSUMER_ACCOUNT_NAME>');
CALL samooha_by_snowflake_local_db.provider.create_or_update_cleanroom_listing($cleanroom_name);

Si vous souhaitez activer l’analyse gérée par le fournisseur, appelez enable_provider_run_analysis après avoir appelé add_consumers et avant d’appeler create_or_update_cleanroom_listing.

Méthodes d’aide¶

Voici quelques fonctions d’aide utiles pour créer une salle blanche.

Plusieurs localisateurs de comptes de consommateurs peuvent être transmis à la fonction provider.add_consumers sous la forme d’une chaîne séparée par des virgules ou sous la forme d’appels distincts à provider.add_consumers.

Si vous souhaitez voir les consommateurs qui ont été ajoutés à cette salle blanche, appelez la procédure suivante.

CALL samooha_by_snowflake_local_db.provider.view_consumers($cleanroom_name);

Si vous souhaitez voir les salles blanches qui ont été créées récemment, utilisez la procédure suivante.

CALL samooha_by_snowflake_local_db.provider.view_cleanrooms();

Si vous souhaitez obtenir plus d’informations sur la salle blanche que vous avez créée, suivez la procédure suivante.

CALL samooha_by_snowflake_local_db.provider.describe_cleanroom($cleanroom_name);

Toute salle blanche créée peut également être supprimée. La commande suivante supprime entièrement la salle blanche, de sorte que les consommateurs qui avaient auparavant accès à la salle blanche ne pourront plus l’utiliser. Si une salle blanche portant le même nom est souhaitée à l’avenir, elle doit être réinitialisée à l’aide du flux ci-dessus.

CALL samooha_by_snowflake_local_db.provider.drop_cleanroom($cleanroom_name);

Accéder au compte du consommateur sur l’application Web¶

Pour se connecter à la salle blanche en tant que consommateur :

1. Connectez-vous à l’application Web de la Snowflake Data Clean Room. Pour plus de détails, voir Snowflake Data Clean Room : application Web.

2. Saisissez votre adresse e-mail et sélectionnez Continuer.

3. Entrez votre mot de passe.

4. Sélectionnez le compte Snowflake associé au compte du consommateur.

Installer la salle blanche¶

Sur la page Salles blanches, recherchez la vignette correspondant à la salle blanche que vous venez de créer et sélectionnez Installer.

Effectuer une analyse¶

Effectuer une analyse dans la salle blanche :

1. Sur la page Salles blanches, trouvez la vignette de la nouvelle salle blanche et sélectionnez Exécuter.

2. Sélectionnez l’analyse ou la requête à exécuter, puis sélectionnez Continuer.

3. Configurez les champs requis pour l’analyse choisie, choisissez éventuellement une taille d’entrepôt, puis sélectionnez Exécuter.

4. Vous pouvez également donner un nom à l’analyse. Si vous souhaitez que l’analyse soit exécutée périodiquement, choisissez un intervalle de temps, sinon choisissez Off pour n’exécuter votre analyse qu’une seule fois.

5. Sélectionnez Enregistrer pour lancer votre analyse.

6. Sélectionnez Voir toutes les analyses pour afficher la liste des analyses planifiées, en cours et terminées, y compris celle que vous venez de créer.

7. Lorsque l’analyse est terminée, sélectionnez-la pour voir les résultats.