API REST de incorporação de vetores¶

A API REST do Cortex fornece acesso a um ponto de extremidade para executar incorporações de vetores, usando a função AI_EMBED.

Configuração da autenticação¶

Para se autenticar na Cortex REST API, você pode usar os métodos descritos em Autenticando o Snowflake REST APIs com Snowflake.

Defina o cabeçalho Authorization para incluir seu token (por exemplo, um token da web JSON [JWT], um token OAuth ou um token de acesso programático).

Dica

Considere criar um usuário dedicado para solicitações da Cortex REST API.

Configuração da autorização¶

Para enviar uma solicitação API REST, sua função padrão deve ter recebido a função de banco de dados SNOWFLAKE.CORTEX_USER. Na maioria dos casos, os usuários já têm esse privilégio porque SNOWFLAKE.CORTEX_USER é concedido automaticamente à função PUBLIC, e todas as funções herdam PUBLIC.

Se o administrador do Snowflake revogou essa concessão, ele deve concedê-la novamente:

GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE my_role;
GRANT ROLE my_role TO USER my_user;

Importante

As solicitações REST API usam a função padrão do usuário, portanto, essa função deve ter os privilégios necessários. Você pode alterar a função padrão de um usuário com :doc:`ALTER … USER SETDEFAULT_ROLE.

ALTER USER my_user SET DEFAULT_ROLE=my_role

Formato do ponto de extremidade¶

Você pode fazer solicitações ao ponto de extremidade /api/v2/cortex/inference:embed para criar incorporações ao seu texto. A solicitação tem o seguinte formato:

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

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

Disponibilidade do modelo¶

A tabela a seguir exibe os modelos da função EMBED que você pode solicitar usando a REST API.

Modelos da função EMBED¶
Modelo	AWS US West 2 (Oregon)	AWS US East 1 (N. Virginia)	AWS Europe Central 1 (Frankfurt)	AWS Europe West 1 (Ireland)	AWS AP Southeast 2 (Sidney)	AWS AP Northeast 1 (Tokyo)	Azure East US 2 (Virginia)	Azure West Europe (Países Baixos)
`snowflake-arctic-embed-m-v1.5`	✔	✔	✔	✔	✔	✔	✔	✔
`snowflake-arctic-embed-m`	✔	✔	✔	✔	✔	✔	✔	✔
`e5-base-v2`	✔	✔	✔			✔	✔	✔
`snowflake-arctic-embed-l-v2.0`	✔	✔	✔	✔	✔	✔	✔	✔

A tabela a seguir mostra o número de dimensões que cada modelo pode retornar.

Modelos da função EMBED¶
Modelo	Número de dimensões
`snowflake-arctic-embed-m-v1.5`	768
`snowflake-arctic-embed-m`	768
`e5-base-v2`	768
`snowflake-arctic-embed-l-v2.0`	1024

Referência de API¶

POST /api/v2/cortex/inference:embed¶

Cria uma incorporação para o texto que você especificar.

Cabeçalhos obrigatórios

Authorization: Bearer token.: Autorização para a solicitação. token é um token da Web JSON (JWT), token OAuth ou token de acesso programático). Para obter mais detalhes, consulte Autenticando o Snowflake REST APIs com Snowflake.
Content-Type: application/json: Especifica que o corpo da solicitação está no formato JSON.
Accept: application/json: Especifica que a resposta contém JSON.

Cabeçalhos opcionais¶

X-Snowflake-Authorization-Token-Type: type

Define o tipo de token de autorização.

Se você omitir o cabeçalho X-Snowflake-Authorization-Token-Type, o Snowflake determinará o tipo de token examinando o token.

Embora esse cabeçalho seja opcional, você pode optar por especificá-lo. Você pode definir o cabeçalho com um dos seguintes valores:

KEYPAIR_JWT (para autenticação de pares de chaves)
OAUTH (para OAuth)
PROGRAMMATIC_ACCESS_TOKEN (para tokens de acesso programático)

Argumentos JSON exigidos¶


Argumento	Tipo	Descrição
`text`	matriz	Uma lista de cadeias de texto para as quais você está gerando incorporações. A lista pode conter até 1.280 cadeias de caracteres, sendo que cada uma delas pode ter até 4.096 caracteres.
`model`	string	O modelo que você está usando para criar as incorporações.

Códigos de status¶

O Snowflake Cortex LLM REST API usa os seguintes códigos de status HTTP para indicar conclusão bem-sucedida ou várias condições de erro.

200 OK: Solicitação concluída com sucesso. O corpo da resposta contém a saída do modelo.
400 invalid options object: Os argumentos opcionais têm valores inválidos.
400 unknown model model_name: O modelo especificado não existe.
400 schema validation failed: Erros relacionados à estrutura incorreta do esquema de resposta. Corrija o esquema e tente novamente.
400 max tokens of count exceeded: A solicitação excedeu o número máximo de tokens suportados pelo modelo (consulte Restrições de modelo).
400 all requests were throttled by remote service: A solicitação foi limitada devido ao alto nível de utilização. Tente novamente mais tarde.
402 budget exceeded: O orçamento de consumo do modelo foi excedido.
403 Not Authorized: Conta não habilitada para REST API, ou a função padrão para o usuário que efetuou a chamada não tem a função de banco de dados snowflake.cortex_user.
429 too many requests: A solicitação foi rejeitada porque a cota de uso foi excedida. Tente fazer sua solicitação mais tarde.
503 embed timed out: A solicitação demorou muito.

Exemplo de solicitação da CURL¶

O exemplo a seguir usa curl para fazer uma solicitação EMBED ao modelo e5-base-v2. Substitua token e account_identifier pelos valores apropriados nesse comando.

curl --location "<account_url>/api/v2/cortex/inference:embed" \
--header 'X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer <token>" \
--data '{
"text": ["foo", "bar"],
"model": "e5-base-v2"
}'

Saída¶

Veja a seguir a saída da solicitação, com o conteúdo da matriz de incorporação truncado:

{
  "object" : "list",
  "data" : [ {
    "object" : "embedding",
    "embedding" : [ [ -0.02102863, 0.0051381723, -0.0071509206, -0.032512695, 0.056507032, ... ] ],
    "index" : 0
  }, {
    "object" : "embedding",
    "embedding" : [ [ -0.03859099, -0.0025452692, 0.002827513, -0.023107057, 0.039019972, ... ] ],
    "index" : 1
  } ],
  "model" : "e5-base-v2",
  "usage" : {
    "total_tokens" : 6
  }
}

Cada incorporação tem um índice que corresponde à cadeia de caracteres de texto em uma lista na solicitação. O índice é baseado em 0, portanto, a primeira cadeia de caracteres de texto da lista tem um índice 0, a segunda cadeia de caracteres de texto tem um índice 1 e assim por diante.

No exemplo anterior, “foo” corresponde ao índice 0 e “bar” corresponde ao índice 1. A incorporação para “foo” é o primeiro elemento na lista de incorporações, e a incorporação para “bar” é o segundo elemento na lista de incorporações.

Exemplo de solicitação Python¶

O exemplo a seguir usa a Python API para fazer uma solicitação EMBED ao modelo e5-base-v2. Substitua token e account_identifier pelos valores apropriados nesse comando.

from snowflake.core import Root
from snowflake.snowpark.context import get_active_session

def embed_service():
    # Initialize Snowflake session and root
    session = get_active_session()
    root = Root(session)

    # Send embed_request request and process response
    response = root.cortex_embed_service.embed("e5-base-v2", ['foo', 'bar'])
    print(response)

if __name__ == "__main__":
    embed_service()

Saída¶

Veja a seguir a saída da solicitação, com o conteúdo da matriz de incorporação truncado:

{
  "object" : "list",
  "data" : [ {
    "object" : "embedding",
    "embedding" : [ [ -0.02102863, 0.0051381723, -0.0071509206, -0.032512695, 0.056507032, ... ] ],
    "index" : 0
  }, {
    "object" : "embedding",
    "embedding" : [ [ -0.03859099, -0.0025452692, 0.002827513, -0.023107057, 0.039019972, ... ] ],
    "index" : 1
  } ],
  "model" : "e5-base-v2",
  "usage" : {
    "total_tokens" : 6
  }
}

Cotas de uso¶

A tabela a seguir mostra as cotas de uso da função EMBED.

Cotas da função EMBED¶
Modelo	Tokens processados por minuto (TPM)	Solicitações por Minuto (RPM)	Saída máxima (tokens)
`snowflake-arctic-embed-m-v1.5`	400,000	200	4,096
`snowflake-arctic-embed-m`	400,000	200	4,096
`e5-base-v2`	400,000	200	4,096
`nv-embed-qa-4`	400,000	200	4,096
`multilingual-e5-large`	400,000	200	4,096
`voyage-multilingual-2`	400,000	200	4,096