안정적인 엔드포인트 및 API 참조¶

주요 기능¶

안정적인 URL: 모델이 진화함에 따라 게이트웨이가 다양한 기본 서비스를 가리키면서 하나의 영구 URL을 유지합니다. 변경 사항은 일반적으로 1분 이내에 반영됩니다.

트래픽 분할: 할당된 비율에 따라 요청을 여러 엔드포인트로 라우팅하여 블루-그린 또는 카나리 배포를 촉진합니다.

자동 장애 조치: 사용할 수 없거나 작동하지 않는 엔드포인트에서 정상적인 다른 대상으로 트래픽을 자동으로 리디렉션합니다.

게이트웨이 장애 조치 동작¶

게이트웨이는 지정된 정상 엔드포인트의 상대적 비율을 따르며 다음과 같은 경우 장애 조치를 자동으로 트리거합니다.

• 서비스가 일시 중단되거나(auto_resume이 false임) 해당 컴퓨팅 풀이 일시 중단됩니다(다시 활성화될 때까지).

• 서비스가 준비 상태 프로브에 실패하거나 완전히 삭제됩니다.

• 게이트웨이 소유자가 대상 서비스 엔드포인트에 대한 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이어야 하고, traffic_split은 사용자 지정이어야 하며, 모든 대상 가중치의 합이 정확히 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 Not Found를 반환합니다. 현재는 인증 오류와 유효하지 않은 URLs를 구분할 방법이 없습니다.

필수 권한¶

게이트웨이를 관리하거나 사용하려면 소유자 역할에 다음이 필요합니다.

• 게이트웨이 관리: 스키마에 대한 CREATE GATEWAY 권한 및 게이트웨이 오브젝트에 대한 USAGE, MODIFY, OWNERSHIP 권한.

• 엔드포인트 사용법: 데이터베이스, 스키마 및 대상 서비스 엔드포인트(특히 배포된 서비스에 대한 ALL_ENDPOINTS_USAGE 서비스 역할)에 대한 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"]
}