Stabile Endpunkte und API-Referenz¶

Wichtige Funktionen¶

Stabile URL: Behalten Sie eine permanente URL bei, während Sie das Gateway auf verschiedene zugrunde liegende Dienste verweisen, wenn sich Ihre Modelle weiterentwickeln. Änderungen werden normalerweise innerhalb einer Minute umgesetzt.

Datenverkehr aufteilen: Leiten Sie Anforderungen an mehrere Endpunkte auf der Grundlage von zugewiesenen Prozentsätzen weiter, was die Blue/Green-Bereitstellung oder Canary-Bereitstellung einfacher macht.

Automatisches Failover: Leitet den Datenverkehr von einem nicht verfügbaren oder nicht funktionsfähigen Endpunkt automatisch zu anderen funktionsfähigen Zielen um.

Verhalten von Gateway-Failovers¶

Das Gateway respektiert den relativen Prozentsatz der angegebenen funktionsfähigen Endpunkte und löst automatisch ein Failover aus, wenn:

• Ein Dienst angehalten wird (und „auto_resume“ „false“ ist) oder sein Computepool angehalten wird (bis dieser wieder verfügbar ist).

• Ein Dienst besteht den zugehörigen Bereitschaftstest nicht oder wird ganz gelöscht.

• Der Besitzende des Gateway verliert die Berechtigung USAGE oder die Berechtigung OWNERSHIP für einen Zieldienstendpunkt.

1. Erstellen und Ändern eines Gateway¶

Sie können festlegen, wie der Datenverkehr zwischen Modellversionen mithilfe einer YAML-basierten Spezifikation innerhalb eines SQL-Befehls verteilt wird.

-- 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
$$;

Regeln für Spezifikationen: Der Typ muss „traffic_split“ sein, „split_type“ muss benutzerdefiniert sein, und alle Zielgewichtungen müssen in der Summe genau 100 ergeben. Standardmäßig kann ein Gateway zu maximal 5 Endpunkten weiterleiten.

2. Behandlung der Schemaentwicklung¶

Wenn eine neue Version des Modells (V2) andere Eingabe-Features erfordert als V1, folgen Sie dieser Strategie, um Unterbrechungen durch Anfragen zu vermeiden:

1. Update der Obermenge: Aktualisieren Sie Ihre Clientanwendung, um alle Features zu senden, die sowohl von V1 als auch V2 benötigt werden. Das Snowflake-Modell, das implizit bereitgestellt wird, ignoriert unnötige Features.

2. Schrittweise Aufteilung: Stellen Sie V2 bereit und verwenden Sie ALTER GATEWAY, um den Prozentsatz des Datenverkehrs langsam von V1 auf V2 zu verschieben.

3. Clientbereinigung: Sobald 100 % des Datenverkehrs an V2 weitergeleitet wurden, aktualisieren Sie den Client, um die jetzt veralteten V1-Features zu entfernen.

3. HTTP-Endpunkt¶

Jedes Gateway-Objekt enthält den Namen seines Endpunkts, den Sie mit der folgenden Abfrage ermitteln können:

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

Der Endpunkt des Gateways ist https://.<endpoint>/. Um bestimmte Methoden des Modells über das Gateway aufzurufen, verwenden Sie den Namen der Methode als Pfad zur URL (z. B. https://<endpoint>/<method-name> ). In einer URL werden Unterstriche (_) im Methodennamen durch Bindestriche (-) in der URL ersetzt. So wird beispielsweise der Name des Dienstes „predict_prob“ in „prediction-proba“ in der URL geändert.

Für Benutzende von Private Link verwenden Sie „privatelink_ingress_url“ anstelle von „ingress_url“.

Zugriff auf den Endpunkt¶

Authentifizierung: Das Verwenden von programmgesteuerten Zugriffstoken (PAT) im Header ist das einfachste: Authorization: Snowflake Token="your_pat_token". Das Gateway unterstützt alle Protokolle, die der Dienstendpunkt unterstützt.

Die 404-Verhaltensweise: Aus Sicherheitsgründen gibt Snowflake bei allen Autorisierungsfehlern (z. B. falsches Token oder fehlender Netzwerkpfad) die Meldung „404 Nicht gefunden“ zurück. Es gibt derzeit keine Möglichkeit, Authentifizierungsfehler von ungültigen URLs zu unterscheiden.

Erforderliche Berechtigungen¶

Um ein Gateway zu verwalten oder zu verwenden, benötigt die Eigentümerrolle Folgendes:

• Gateway-Verwaltung: CREATE GATEWAY im Schema und USAGE, MODIFY oder OWNERSHIP für das Gateway-Objekt.

• Endpunktnutzung: USAGE für die Endpunkte von Datenbank, Schema und Zieldienst (insbesondere die ALL_ENDPOINTS_USAGE-Dienstrolle für den bereitgestellten Dienst).

• Öffentlicher Zugriff: BIND SERVICE ENDPOINT für das Konto, um das Gateway für das öffentliche Internet zugänglich zu machen.

Übergabe zusätzlicher Metadaten¶

In einigen Szenarien müssen Sie möglicherweise zusätzliche Daten übergeben (z. B. Datensatz-IDs oder Primärschlüssel), die nicht Teil der Eingabesignatur des Modells sind, aber für die die nachgelagerte Protokollierung oder die Verknüpfung mit Ground-Truth-Labels benötigt werden. Um dies zu verarbeiten, unterstützt Snowflake ein optionales Feld auf oberster Ebene mit der Bezeichnung „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"]
}