Referência de pontos de extremidade estáveis e API¶

Principais recursos¶

URL estável: mantenha um URL permanente enquanto aponta o gateway para diferentes serviços subjacentes à medida que seus modelos evoluem. Normalmente, as alterações são refletidas em um minuto.

Divisão de tráfego: roteie solicitações para vários pontos de extremidade com base em porcentagens atribuídas, facilitando implantações azul-verde ou canário.

Failover automático: redirecione automaticamente o tráfego de um ponto de extremidade indisponível ou inoperante para outros destinos íntegros.

Comportamento de failover do gateway¶

O gateway respeita a porcentagem relativa dos pontos de extremidade íntegros especificados e acionará automaticamente um failover se:

• um serviço for suspenso (e auto_resume for false) ou o pool de computação for suspenso (até ele voltar a ficar ativo);

• houver falha na análise de prontidão de um serviço ou ele for descartado completamente;

• o proprietário do gateway perder os privilégios USAGE ou OWNERSHIP em um ponto de extremidade do servidor de destino.

1. Criando e alterando um gateway¶

Você pode definir como o tráfego é distribuído entre versões do modelo usando uma especificação baseada em YAML em um comando 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
$$;

Regras para especificações: o tipo deve ser traffic_split, split_type deve ser personalizado e todos os pesos de destino devem somar exatamente 100. Por padrão, um gateway pode rotear para um máximo de 5 pontos de extremidade.

2. Tratando a evolução de esquema¶

Quando uma nova versão do modelo (V2) requer recursos de entrada diferentes daqueles da V1, siga esta estratégia para evitar interrupções de solicitação:

1. Atualização de superconjunto: atualize seu aplicativo cliente para enviar todos os recursos exigidos por ambas as versões V1 e V2. O serviço de modelo do Snowflake ignora implicitamente recursos desnecessários.

2. Divisão gradual: implante a V2 e use ALTER GATEWAY para mudar lentamente as porcentagens de tráfego da V1 para a V2.

3. Limpeza do cliente: quando 100% do tráfego for roteado para a V2, atualize o cliente para remover os recursos da V1 que agora ficam obsoletos.

3. Ponto de extremidade HTTP¶

Cada objeto de gateway vem com o próprio nome de ponto de extremidade, que pode ser encontrado usando a seguinte consulta:

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

O ponto de extremidade do gateway será https://<endpoint>/. Para chamar métodos específicos do modelo via gateway, use o nome do método como caminho para o URL (por exemplo, https://<endpoint>/<method-name>). Em um URL, os sublinhados (_) no nome do método são substituídos por hifens (-) no URL. Por exemplo, o nome do serviço predict_prob é alterado para predict-proba no URL.

Para usuários de links privados, use privatelink_ingress_url em vez de ingress_url.

Acessando o ponto de extremidade¶

Autenticação: o uso de tokens de acesso programático (Programmatic Access Tokens, PAT) no cabeçalho é a maneira mais simples: Authorization: Snowflake Token="your_pat_token". O Gateway oferece suporte a todos os protocolos compatíveis com o ponto de extremidade de serviço.

O comportamento 404: por segurança, o Snowflake retorna 404 Não encontrado para todas as falhas de autorização (por exemplo, token incorreto ou falta de rota de rede). Atualmente, não há como distinguir erros de autenticação de URLs inválidos.

Privilégios obrigatórios¶

Para gerenciar ou usar um gateway, a função de proprietário requer:

• Gerenciamento de gateway: CREATE GATEWAY no esquema e USAGE, MODIFY ou OWNERSHIP no objeto de gateway.

• Uso do ponto de extremidade: USAGE nos pontos de extremidade de banco de dados, esquema e serviço de destino (especificamente a função de serviço ALL_ENDPOINTS_USAGE no serviço implementado).

• Acesso público: BIND SERVICE ENDPOINT na conta para expor o gateway à internet pública.

Passando metadados complementares¶

Em alguns cenários, talvez seja necessário passar dados complementares (como IDs de registro ou chaves primárias) que não fazem parte da assinatura de entrada do modelo, mas são necessários para o registro downstream ou a junção com rótulos de ground truth (verdade fundamental). Para resolver isso, o Snowflake oferece suporte a um campo opcional de nível superior 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"]
}