稳定端点和 API 参考¶

主要功能¶

稳定 URL： 随着模型的发展，维护一个永久 URL，同时将网关指向不同的底层服务。更改通常会在一分钟内显示。

流量拆分： 根据分配的百分比将请求路由到多个端点，从而促进蓝绿或金丝雀部署。

自动故障转移： 自动将流量从不可用或无法运行的端点重定向到其他健康目标。

网关故障转移行为¶

网关会考虑指定健康端点的相对百分比，并将在以下情况下自动触发故障转移：

• 服务已暂停（且 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，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:/ (https:/)/<endpoint>/。要通过网关调用模型的任何特定方法，请使用方法名称作为 URL 的路径（例如 https:/ (https:/)/<endpoint>/<method-name>）。在 URL 中，方法名称中的下划线 (_) 会在 URL 中被替换为短划线 (-)。例如，在 URL 中，服务名称 predict_prob 会变为 predict-proba。

对于专用链接用户，请使用 privatelink_ingress_url 而非 ingress_url。

访问端点¶

身份验证： 在标头中使用编程访问令牌 (PAT) 是最简单的：Authorization: Snowflake Token="your_pat_token"。网关支持服务端点支持的所有协议。

404 行为： 为了安全起见，Snowflake 会对所有授权失败（例如，令牌不正确或缺少网络路由）返回 404 Not Found。目前，还无法区分身份验证错误和无效的 URLs。

所需权限¶

要管理或使用网关，所有者角色需要：

• 网关管理： 在架构中 CREATE 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"]
}