API REST de LLM Cortex¶

Considerações sobre custo¶

As solicitações do Snowflake Cortex LLM REST API incorrem em custos de computação com base no número de tokens processados. Consulte a Tabela de consumo do serviço Snowflake para o custo de cada função em créditos por milhão de tokens. Um token é a menor unidade de texto processada pelas funções de LLM do Snowflake Cortex, aproximadamente igual a quatro caracteres de texto. A equivalência do texto bruto de entrada ou saída com tokens pode variar de acordo com o modelo.

A função COMPLETE gera um novo texto a partir de um prompt de entrada. Tanto os tokens de entrada quanto os de saída incorrem em custo de computação. Se você usa COMPLETE para fornecer uma experiência de usuário de conversação ou bate-papo, todos os prompts e respostas anteriores são processados para gerar cada nova resposta, com custos correspondentes.

Cotas de uso¶

Para garantir um alto padrão de desempenho para todos os clientes do Snowflake, as solicitações do Snowflake Cortex LLM REST API estão sujeitas a cotas de uso, além das quais as solicitações podem ser limitadas. A Snowflake pode ajustar essas cotas de tempos em tempos. As cotas na tabela abaixo são aplicadas por conta e são aplicadas independentemente para cada modelo.

Ponto de extremidade COMPLETE¶

O ponto de extremidade /api/v2/cortex/inference:complete executa a função SQL COMPLETE. Ele assume a forma:

POST https://<account_identifier>.snowflakecomputing.com/api/v2/cortex/inference:complete

em que account_identifier é o identificador de conta que você usa para acessar o Snowsight.

Configuração da autenticação¶

A autenticação no Cortex LLM REST API usa autenticação de par de chaves.. Isso requer a criação de um par de chaves RSA e a atribuição de sua chave pública a um usuário, o que deve ser feito usando a função SECURITYADMIN (ou outra função que tenha recebido SECURITYADMIN, como ACCOUNTADMIN). Para obter instruções passo a passo, consulte Configuração da autenticação do par de chaves.

Para fazer solicitações de API, use a chave pública para criar um token JSON Web (JWT) e passá-lo em seus cabeçalhos da solicitação.

Configuração da autorização¶

Depois de criar um par de chaves e atribuir sua chave pública a um usuário, a função padrão desse usuário precisa ter a função de banco de dados snowflake.cortex_user, que contém os privilégios para usar as funções de LLM. Na maioria dos casos, os usuários já têm esse privilégio, porque ele é concedido à função PUBLIC automaticamente, e todas as funções herdam PUBLIC.

Se o administrador do Snowflake preferir aceitar usuários individuais, ele poderá ter revogado snowflake.cortex_user de PUBLIC e deverá conceder essa função aos usuários que devem poder usar o Cortex LLM REST API da seguinte maneira.

GRANT DATABASE ROLE snowflake.cortex_user TO ROLE MY_ROLE;
GRANT ROLE MY_ROLE TO USER MY_USER;

ALTER USER MY_USER SET DEFAULT_ROLE=MY_ROLE

Envio de solicitações¶

Você faz uma solicitação ao Cortex LLM REST API pelo POSTing para o ponto de extremidade REST da API. O cabeçalho Authorization deve conter um token JSON Web gerado a partir da sua chave pública, o que você pode fazer usando snowsql pelo seguinte comando. O JWT gerado expira após uma hora.

snowsql -a <account_identifier> -u <user> --private-key-path <path>/rsa_key.p8 --generate-jwt

O corpo da solicitação é um objeto JSON que especifica o modelo, o prompt ou histórico de conversas e as opções. Veja a seguinte referência de API para mais detalhes.

Referência de API¶

Exemplo¶

O exemplo a seguir usa curl para fazer uma solicitação COMPLETE. Substitua jwt, prompt e account_identifier pelos valores apropriados nesse comando.

curl -X POST \
    -H 'X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT' \
    -H "Authorization: Bearer <jwt>" \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/event-stream' \
    -d '{
    "model": "mistral-large",
    "messages": [
        {
            "content": "<prompt>"
        }
    ],
    "top_p": 0,
    "temperature": 0
    }' \
https://<account_identifier>.snowflakecomputing.com/api/v2/cortex/inference:complete

data: {
data:  "id": "65c5e2ac-529b-461e-8a8c-f80655e6bd3f",
data:  "created": 1723493954,
data:  "model": "mistral-7b",
data:  "choices": [
data:    {
data:      "delta": {
data:        "content": "Cor"
data:        }
data:      }
data:     ],
data:  "usage": {
data:    "prompt_tokens": 57,
data:    "completion_tokens": 1,
data:    "total_tokens": 58
data:  }
data: }

data: {
data:  "id": "65c5e2ac-529b-461e-8a8c-f80655e6bd3f",
data:  "created": 1723493954,
data:  "model": "mistral-7b",
data:  "choices": [
data:    {
data:      "delta": {
data:        "content": "tex"
data:        }
data:      }
data:     ],
data:  "usage": {
data:    "prompt_tokens": 57,
data:    "completion_tokens": 2,
data:    "total_tokens": 59
data:  }
data: }

API de Python¶

Para instalar a API de Python, use:

pip install snowflake-ml-python

A API Python está incluído no pacote snowflake-ml-python a partir da versão 1.6.1.

from snowflake.snowpark import Session
from snowflake.cortex import Complete

session = Session.builder.configs(...).create()

stream = Complete(
  "mistral-7b",
  "What are unique features of the Snowflake SQL dialect?",
  session=session,
  stream=True)

for update in stream:
  print(update)