安定したエンドポイントおよび API 参照情報¶

主な機能¶

安定した URL: モデルが進化するにつれて、さまざまな基盤となるサービスにゲートウェイをポイントしながら、1つの永続的な URL を維持します。変更は通常、1分以内に反映されます。

トラフィック分割: 割り当てられたパーセンテージに基づいて、リクエストを複数のエンドポイントにルーティングし、ブルーグリーンデプロイまたはカナリアデプロイを容易にします。

自動フェイルオーバー: 利用不可または動作しない状態のエンドポイントから他の正常なターゲットにトラフィックを自動的にリダイレクトします。

ゲートウェイのフェイルオーバー動作¶

ゲートウェイは、指定された健全なエンドポイントの相対的な割合を尊重し、次の場合にフェイルオーバーを自動的にトリガーします。

• サービスが一時停止される（auto_resumeがfalse）か、そのコンピューティングプールが一時停止された（再起動するまで）。

• サービスのreadinessプローブが失敗するか、完全にドロップされた。

• ゲートウェイの所有者が、ターゲットサービスエンドポイントに対する USAGE 権限または OWNERSHIP 権限を失った。

1.ゲートウェイの作成と変更¶

SQL コマンド内で YAML ベースの仕様を使用して、モデルのバージョン間でトラフィックをどのように分散するかを定義できます。

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

仕様のルール: 型はtraffic_splitである必要があり、split_typeはカスタムである必要があります。さらに、すべてのターゲットの重みは正確に合計100にする必要があります。デフォルトでは、ゲートウェイは最大5つのエンドポイントにルーティングできます。

2.スキーマの進化の処理¶

新しいモデルのバージョン（V2）でV1とは異なる入力機能が必要な場合は、この戦略に従ってリクエストの中断を防ぎます。

1. スーパーセットの更新: V1とV2の両方に必要なすべての機能を送信するように、クライアントアプリケーションを更新します。Snowflakeモデルサービングは、不要な機能を暗黙的に無視します。

2. 段階的分割: V2をデプロイし、ALTER GATEWAY を使用して、トラフィックのパーセンテージをV1からV2に徐々にシフトします。

3. クライアントのクリーンアップ: トラフィックの100%がV2にルーティングされたら、クライアントを更新して、現在は廃止されているV1の機能を削除します。

3. HTTP エンドポイント¶

すべてのゲートウェイオブジェクトには、次のクエリを使用して見つけることができるエンドポイント名が付いています。

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

ゲートウェイのエンドポイントは https://<endpoint>/ になります。ゲートウェイ経由でモデルに対して特定のメソッドを呼び出すには、メソッド名を URL（例: https://<endpoint>/<method-name>）へのパスとして使用します。URL で、メソッド名のアンダースコア（_）は URL 内でダッシュ（-）に置き換えられます。たとえば、predict_probのサービス名は、URL でpredict-probaに変更されます。

プライベートリンクユーザーの場合は、ingress_urlではなくprivatelink_ingress_urlを使用してください。

エンドポイントへのアクセス¶

認証: ヘッダーでプログラムのアクセストークン（PAT）を使用する（Authorization: Snowflake Token="your_pat_token"）のが最も簡略な方法です。ゲートウェイは、サービスエンドポイントがサポートするすべてのプロトコルをサポートします。

404動作: セキュリティのため、Snowflakeはすべての認証失敗（例: 不正なトークンまたはネットワークルートの欠落）に対して404エラーを返します。現在、認証エラーと無効な URLs を区別するための方法はありません。

必要な権限¶

ゲートウェイを管理または使用する際の所有者ロールの要件は次のとおりです。

• ゲートウェイ管理: スキーマの CREATE GATEWAY、およびGatewayオブジェクトの USAGE、MODIFY または OWNERSHIP。

• エンドポイントの使用状況: データベース、スキーマ、およびターゲットサービスエンドポイントの USAGE（具体的には、デプロイされたサービスの ALL_ENDPOINTS_USAGE サービスロール）。

• パブリックアクセス: ゲートウェイをパブリックインターネットに公開するためのアカウントに対する BIND SERVICE ENDPOINT。

補足メタデータの引き渡し¶

シナリオによっては、モデルの入力署名の一部ではないものの、グランドトゥルースラベルを使用した下流でのロギングまたは結合に必要な補足データ（記録の IDs や主キーなど）を渡すことが必要な場合があります。これを処理するために、Snowflakeはオプションの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"]
}