Points de terminaison stables et référence API¶

Capacités clés¶

URL stable : conserver une URL permanente tout en pointant la passerelle vers différents services sous-jacents à mesure que vos modèles évoluent. Les modifications sont généralement reflétées dans un délai d’une minute.

Répartition du trafic : acheminer les requêtes vers plusieurs points de terminaison en fonction des pourcentages attribués, ce qui facilite les déploiements bleu-vert ou canari.

Basculement automatique : rediriger automatiquement le trafic d’un point de terminaison indisponible ou non opérationnel vers d’autres cibles saines.

Comportement de basculement des passerelles¶

La passerelle respecte le pourcentage relatif de points de terminaison sains spécifiés et déclenchera automatiquement un basculement si :

• Un service est suspendu (et auto_resume est false) ou son pool de calcul est suspendu (jusqu’à ce qu’il soit rétabli).

• Un service échoue à son test de disponibilité ou est complètement abandonné.

• Le propriétaire de la passerelle perd les privilèges USAGE ou OWNERSHIP sur un point de terminaison de service cible.

1. Création et modification d’une passerelle¶

Vous pouvez définir la manière dont le trafic est réparti entre les versions de modèle à l’aide d’une spécification basée sur YAMLdans une commande SQL.

-- Create a gateway to split traffic between V1 (90%) and V2 (10%)
CREATE OR REPLACE GATEWAY my_model_gateway
  FROM SPECIFICATION $$
    spec:
      type: traffic_split
      split_type: custom
      targets:
        - type: endpoint
          value: my_db.my_schema.model_v1_service!inference
          weight: 90
        - type: endpoint
          value: my_db.my_schema.model_v2_service!inference
          weight: 10
  $$;

-- Change the gateway to split traffic differently V1 (60%) and V2 (40%)
ALTER GATEWAY split_gateway
FROM SPECIFICATION $$
spec:
type: traffic_split
split_type: custom
targets:
- type: endpoint
value: my_db.my_schema.model_v1_service!inference
weight: 60
- type: endpoint
value: my_db.my_schema.model_v2_service!inference
weight: 40
$$;

Règles relatives aux spécifications : le type doit être traffic_split, le split_type doit être personnalisé et tous les poids cibles doivent totaliser exactement 100. Par défaut, une passerelle peut acheminer vers un maximum de cinq points de terminaison.

2. Gestion de l’évolution des schémas¶

Lorsqu’une nouvelle version de modèle (V2) nécessite des fonctionnalités d’entrée différentes de V1, suivez cette stratégie pour éviter les interruptions de requête :

1. Mise à jour Superset : mettez à jour votre application cliente afin qu’elle envoie toutes les fonctionnalités requises par les versions V1 et V2. La version du modèle Snowflake ignore implicitement les fonctionnalités non nécessaires.

2. Séparation progressive : déployez la version V2 et utilisez ALTER GATEWAY pour transférer progressivement le trafic de la version V1 vers la version V2.

3. Nettoyage du client : une fois que 100 % du trafic est acheminé vers V2, mettez à jour le client afin de supprimer les fonctionnalités désormais obsolètes de V1.

3. Point de terminaison HTTP¶

Chaque objet de passerelle est fourni avec son nom de point de terminaison, qui peut être trouvé en utilisant la requête suivante :

DESC GATEWAY split_gateway ->> select "ingress_url" as endpoint from $1

Le point de terminaison de la passerelle sera https://<endpoint>/. Pour appeler des méthodes particulières du modèle via une passerelle, utilisez le nom de la méthode comme chemin vers l’URL (par ex. https://<endpoint>/<method-name> ). Dans une URL, les traits de soulignement (_) dans le nom de la méthode sont remplacés par des tirets (-) dans l’URL. Par exemple, le nom du service prediction_prob est changé en prediction-proba dans l’URL.

Pour les utilisateurs de lien privé, utilisez privatelink_ingress_url au lieu de ingress_url.

Accès au point de terminaison¶

Authentification : utiliser de jetons d’accès programmatiques (PAT) dans l’en-tête est la solution la plus simple : Authorization: Snowflake Token="your_pat_token". La passerelle prend en charge tous les protocoles pris en charge par le point de terminaison de service.

Comportement 404 : pour des raisons de sécurité, Snowflake renvoie une erreur 404 Not Found pour tous les échecs d’autorisation (par exemple, un jeton incorrect ou absence d’itinéraire réseau). Il n’existe actuellement aucun moyen de différencier les erreurs d’authentification des URLs non valides.

Privilèges requis¶

Pour gérer ou utiliser une passerelle, le rôle de propriétaire doit :

• Gestion de passerelle : CREATE GATEWAY dans le schéma et USAGE, MODIFY ou OWNERSHIP sur l’objet de passerelle.

• Utilisation du point de terminaison : USAGE sur la base de données, le schéma et les points de terminaison du service cible (en particulier le rôle de service ALL_ENDPOINTS_USAGE sur le service déployé).

• Accès public : BIND SERVICE ENDPOINT sur le compte pour exposer la passerelle vers l’Internet public.

Transmission de métadonnées supplémentaires¶

Dans certains scénarios, vous pouvez avoir besoin de transmettre des données supplémentaires (telles que des IDs d’enregistrement ou des clés primaires) qui ne font pas partie de la signature d’entrée du modèle, mais qui sont nécessaires pour la journalisation en aval ou la jointure avec des étiquettes véritables de terrain. Pour gérer cela, Snowflake prend en charge un champ de niveau supérieur facultatif, « extra_columns ».

payload = {
    "dataframe_split": {
        "index": [0, 1],
        "columns": [
            "customer_id",
            "age",
            "monthly_spend",
            "primary_key",
        ],
        "data": [
            [101, 32, 85.5, "001"],
            [102, 45, 120.0, "002"],
        ]
    },
    "extra_columns": ["primary_key"]
}

payload = {
    "dataframe_records": [
        {
            "customer_id": 101,
            "age": 32,
            "monthly_spend": 85.5,
            "primary_key": "001",
        },
        {
            "customer_id": 102,
            "age": 45,
            "monthly_spend": 120.0,
            "primary_key": "002",
        },
    ],
    "extra_columns": ["primary_key"]
}