Snowflake Cortex AISQL (incluindo as funções LLM)¶

Funções disponíveis¶

Os recursos do Snowflake Cortex são fornecidos como funções SQL e também estão disponíveis em Python. As funções do Cortex AISQL podem ser agrupadas nas seguintes categorias:

• Funções AISQL

• Funções auxiliares

Considerações de desempenho¶

As funções do Cortex AISQL são otimizadas para rendimento. Recomendamos o uso dessas funções para processar várias entradas, como texto de grandes tabelas SQL. O processamento em lote é normalmente mais adequado para funções AISQL. Para casos de uso mais interativos em que a latência é importante, use REST API. Eles estão disponíveis para inferência simples (Complete API), incorporação (Embed API) e aplicativos agênticos (Agents API).

Privilégios obrigatórios¶

A função de banco de dados CORTEX_USER no banco de dados SNOWFLAKE inclui os privilégios que permitem aos usuários chamar funções de AI do Snowflake Cortex. Por padrão, a função CORTEX_USER é concedida à função PUBLIC. A função PUBLIC é concedida automaticamente a todos os usuários e funções, portanto, isto permite que todos os usuários em sua conta usem as funções de AI do Snowflake Cortex.

Se não quiser que todos os usuários tenham esse privilégio, você pode revogar o acesso à função PUBLIC e conceder acesso a funções específicas.

Para revogar a função de banco de dados CORTEX_USER da função PUBLIC, execute os seguintes comandos usando a função ACCOUNTADMIN:

REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER
  FROM ROLE PUBLIC;

REVOKE IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE
  FROM ROLE PUBLIC;

Você poderá então fornecer acesso seletivamente a funções específicas. A função de banco de dados SNOWFLAKE.CORTEX_USER não pode ser concedida diretamente a um usuário. Para obter mais informações, consulte Como usar as funções de banco de dados SNOWFLAKE. Um usuário com a função ACCOUNTADMIN pode conceder esta função a uma função personalizada para permitir que os usuários acessem as funções do Cortex AI. No exemplo a seguir, use a função ACCOUNTADMIN e conceda ao usuário some_user a função de banco de dados CORTEX_USER por meio da função de conta cortex_user_role, que você cria para essa finalidade.

USE ROLE ACCOUNTADMIN;

CREATE ROLE cortex_user_role;
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE cortex_user_role;

GRANT ROLE cortex_user_role TO USER some_user;

Você também pode conceder acesso às funções de AI do Snowflake Cortex por meio de funções existentes comumente usadas por grupos específicos de usuários. (Consulte Funções do usuário.) Por exemplo, se você criou uma função analyst usada como função padrão pelos analistas da sua organização, poderá conceder facilmente a esses usuários acesso às funções de AISQL do Snowflake Cortex com uma única instrução GRANT.

GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE analyst;

Controle o acesso ao modelo¶

Há dois métodos para controlar o acesso aos modelos no Snowflake Cortex. Você pode usar um ou ambos os métodos juntos para obter uma combinação de controle de acesso amplo e refinado:

• Lista de permissão de modelos

• controle de acesso baseado em função

A lista de permissão de modelos fornece um nível padrão de acesso aos modelos para todos os usuários da conta, que pode ser personalizado usando o parâmetro CORTEX_MODELS_ALLOWLIST. O controle de acesso baseado em função permite o gerenciamento de acesso refinado, concedendo ou revogando privilégios a objetos de modelo específicos por meio de funções de aplicativo.

O controle de acesso ao modelo está disponível para os seguintes serviços:

• Funções AISQL

• Cortex REST API

• TRY_COMPLETE (SNOWFLAKE.CORTEX)

• Playground do Cortex

Os métodos de controle de acesso com granularidade fina não estão disponíveis para os seguintes serviços:

• Cortex Search

• Cortex Analyst

• Cortex Copilot

• Cortex Agents

• AI do documento

CALL SNOWFLAKE.MODELS.CORTEX_BASE_MODELS_REFRESH();

SHOW MODELS IN SNOWFLAKE.MODELS;

SHOW APPLICATION ROLES IN APPLICATION SNOWFLAKE;

GRANT APPLICATION ROLE SNOWFLAKE."CORTEX-MODEL-ROLE-LLAMA3.1-70B" TO ROLE MY_ROLE;

SELECT AI_COMPLETE('SNOWFLAKE.MODELS."LLAMA3.1-70B"', 'Hello');

Disponibilidade¶

As funções de AI do Snowflake Cortex estão atualmente disponíveis nas seguintes regiões. Para acessar os LLMs a partir de regiões que não estão listadas, use o parâmetro de inferência entre regiões.

As seguintes funções de AI do Snowflake Cortex estão atualmente disponíveis nas seguintes regiões estendidas.

A tabela a seguir lista modelos de legado. Se você estiver apenas começando, comece com os modelos das tabelas anteriores:

Considerações sobre custo¶

As funções de AI do Snowflake Cortex 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 AI do Snowflake Cortex, aproximadamente igual a quatro caracteres. A equivalência do texto bruto de entrada ou saída com tokens pode variar de acordo com o modelo.

• Para funções que geram novo texto na resposta (AI_COMPLETE, AI_CLASSIFY, AI_FILTER, AI_AGG, AI_SUMMARIZE e TRANSLATE), os tokens de entrada e de saída são contados.

• Para CORTEX GUARD, somente os tokens de entrada são contados. O número de tokens de entrada é baseado no número de tokens de saída por modelo de LLM usado na função COMPLETE.

• Para as funções AI_SIMILARITY, EMBED_*, somente os tokens de entrada são contados.

• Para EXTRACT_ANSWER, o número de tokens faturáveis é a soma do número de tokens nos campos from_text e question.

• AI_CLASSIFY, AI_FILTER, AI_AGG, AI_SUMMARIZE_AGG, SUMMARIZE, TRANSLATE, EXTRACT_ANSWER, ENTITY_SENTIMENT e SENTIMENT adicionam um prompt ao texto de entrada para gerar a resposta. Como resultado, a contagem de tokens de entrada é maior do que o número de tokens no texto fornecido por você.

• Rótulos, descrições e exemplos de AI_CLASSIFY são contados como tokens de entrada para cada registro processado, e não apenas uma vez para cada chamada de AI_CLASSIFY.

• Para PARSE_DOCUMENT (SNOWFLAKE.CORTEX), o faturamento é baseado no número de páginas de documentos processadas.

• TRY_COMPLETE(SNOWFLAKE.CORTEX) não incorre em custos para tratamento de erro. Isso significa que se a função TRY_COMPLETE(SNOWFLAKE.CORTEX) retornar NULL, nenhum custo será gerado.

• COUNT_TOKENS(SNOWFLAKE.CORTEX) incorre em custo de computação apenas para executar a função. Não há custos adicionais baseados em token.

A Snowflake recomenda a execução de consultas que chamem uma função do Snowflake Cortex AISQL ou uma função do Cortex PARSE_DOCUMENT com um warehouse menor (não maior que MEDIUM) porque warehouses maiores não aumentam o desempenho. O custo associado à manutenção de um warehouse ativo continuará a ser aplicado ao executar uma consulta que chama uma função de LLM do Snowflake Cortex. Para obter informações gerais sobre custos de computação, consulte Compreensão do custo de computação.

SELECT *
  FROM SNOWFLAKE.ACCOUNT_USAGE.METERING_DAILY_HISTORY
  WHERE SERVICE_TYPE='AI_SERVICES';

SELECT *
  FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_FUNCTIONS_USAGE_HISTORY;

SELECT * FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_FUNCTIONS_QUERY_USAGE_HISTORY;

SELECT * FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_FUNCTIONS_QUERY_USAGE_HISTORY
WHERE query_id='<query-id>';

SELECT AI_COMPLETE('mistral-7b', 'Is a hot dog a sandwich'), AI_COMPLETE('mistral-large', 'Is a hot dog a sandwich');

Cotas de uso¶

Para garantir que todos os clientes Snowflake possam acessar as funcionalidades de LLM, as funções de AI do Snowflake Cortex podem estar sujeitas a limitações durante períodos de alta utilização. As cotas de uso não são aplicadas ao nível da conta.

As solicitações limitadas receberão uma resposta de erro e devem ser tentadas novamente mais tarde.

Gerenciamento de custos e limitação¶

Snowflake recomenda usar um tamanho de warehouse não maior que MEDIUM ao chamar funções de AISQL do Snowflake Cortex. Utilizar um warehouse maior do que o necessário não aumenta o desempenho, mas pode resultar em custos desnecessários e num maior risco de limitação. Esta recomendação pode não se aplicar no futuro devido a atualizações futuras do produto.

Restrições de modelo¶

Os modelos usados pelo Snowflake Cortex têm limitações de tamanho conforme descrito na tabela abaixo. Os tamanhos são fornecidos em tokens. Os tokens geralmente representam cerca de quatro caracteres de texto, portanto, o número de palavras correspondentes a um limite é menor que o número de tokens. As entradas que excedem o limite resultam em erro.

O tamanho máximo da saída que um modelo pode produzir é limitado pelo seguinte:

• O limite do token de saída do modelo.

• O espaço disponível na janela de contexto após o modelo consumir os tokens de entrada.

Por exemplo, claude-3-5-sonnet tem uma janela de contexto de 200 mil tokens. Se 100 mil tokens forem usados para a entrada, o modelo poderá gerar até 8.192 tokens. No entanto, se 195 mil tokens forem usados como entrada, o modelo só poderá gerar até 5 mil tokens para um total de 200 mil tokens.

Escolha de um modelo¶

A função COMPLETE do Snowflake Cortex oferece suporte a vários modelos de capacidade, latência e custo variados. Esses modelos foram cuidadosamente escolhidos para se alinharem aos casos de uso comuns dos clientes. Para obter o melhor desempenho por crédito, escolha um modelo que corresponda bem ao tamanho do conteúdo e à complexidade da sua tarefa. Aqui estão breves visões gerais dos modelos disponíveis.

Versões anteriores do modelo¶

A função COMPLETE do Snowflake Cortex também é compatível com as seguintes versões de modelos mais antigos. Recomendamos que você use as versões mais recentes do modelo em vez das versões listadas nesta tabela.

Condições de erro¶

As funções de AI do Snowflake Cortex podem produzir as seguintes mensagens de erro.

Usando o Snowflake Cortex AISQL com Python¶

Você pode usar as funções do Snowflake Cortex AISQL na Snowpark Python API. Na API, você pode usar as funções para classificar, resumir e filtrar dados de texto e imagem.

Essas funções incluem o seguinte:

• ai_agg() – Agrega uma coluna de texto usando instruções de linguagem natural. Para obter mais informações, consulte AI_AGG.

• ai_classify() – Classifica texto ou imagens em categorias personalizadas. Para obter mais informações, consulte AI_CLASSIFY.

• ai_filter() – Filtra dados usando linguagem natural. Para obter mais informações, consulte AI_FILTER.

A função ai_agg() agrega uma coluna de texto usando instruções de linguagem natural de forma semelhante a como você pediria a um analista para resumir ou extrair conclusões de dados agrupados ou não agrupados.

O exemplo a seguir resume as avaliações dos clientes para cada produto usando a função ai_agg(). A função usa uma coluna de texto e uma instrução de linguagem natural para resumir as avaliações.

from snowflake.snowpark.functions import ai_agg, col

df = session.create_dataframe([
    [1, "Excellent product!"],
    [1, "Great battery life."],
    [1, "A bit expensive but worth it."],
    [2, "Terrible customer service."],
    [2, "Won’t buy again."],
], schema=["product_id", "review"])

# Summarize reviews per product
summary_df = df.group_by("product_id").agg(
    ai_agg(col("review"), "Summarize the customer reviews in one sentence.")
)
summary_df.show()

A função ai_classify() pega um texto ou imagem e o classifica nas categorias que você definir.

O exemplo a seguir classifica as avaliações de viagens em categorias como “viagens” e “culinária”. A função recebe uma coluna de texto e uma lista de categorias para classificar o texto.

from snowflake.snowpark.functions import ai_classify

df = session.create_dataframe([
    ["I dream of backpacking across South America."],
    ["I made the best pasta yesterday."],
], schema=["sentence"])

df = df.select(
    "sentence",
    ai_classify("sentence", ["travel", "cooking"]).alias("classification")
)
df.show()

A função ai_filter() avalia uma condição de linguagem natural e retorna TRUE ou FALSE. Você pode usá-lo para filtrar ou marcar linhas.

from snowflake.snowpark.functions import ai_filter, prompt, col

df = session.create_dataframe(["Canada", "Germany", "Japan"], schema=["country"])

filtered_df = df.select(
    "country",
    ai_filter(prompt("Is {0} in Asia?", col("country"))).alias("is_in_asia")
)
filtered_df.show()

As funções existentes do Snowpark ML ainda são compatíveis com o Snowpark ML versão 1.1.2 e posteriores. Consulte Como usar o Snowflake ML localmente para obter instruções sobre como configurar o Snowpark ML.

Se você executar seu script Python fora do Snowflake, deverá criar uma sessão do Snowpark para usar essas funções. Consulte Conexão ao Snowflake para obter instruções.

O exemplo Python a seguir ilustra a chamada de funções de AI do Snowflake Cortex em valores únicos:

from snowflake.cortex import Complete, ExtractAnswer, Sentiment, Summarize, Translate

text = """
    The Snowflake company was co-founded by Thierry Cruanes, Marcin Zukowski,
    and Benoit Dageville in 2012 and is headquartered in Bozeman, Montana.
"""

print(Complete("llama2-70b-chat", "how do snowflakes get their unique patterns?"))
print(ExtractAnswer(text, "When was snowflake founded?"))
print(Sentiment("I really enjoyed this restaurant. Fantastic service!"))
print(Summarize(text))
print(Translate(text, "en", "fr"))

Você pode passar opções que afetam os hiperparâmetros do modelo ao usar a função COMPLETE. O exemplo em Python a seguir ilustra a chamada da função COMPLETE com uma modificação do número máximo de tokens de saída que o modelo pode gerar:

from snowflake.cortex import Complete,CompleteOptions

model_options1 = CompleteOptions(
    {'max_tokens':30}
)

print(Complete("llama3.1-8b", "how do snowflakes get their unique patterns?", options=model_options1))

Você também pode chamar uma função de AI em uma coluna da tabela, conforme mostrado abaixo. Este exemplo requer um objeto de sessão (armazenado em session) e uma tabela articles contendo uma coluna de texto abstract_text e cria uma nova coluna abstract_summary contendo um resumo do abstract.

from snowflake.cortex import Summarize
from snowflake.snowpark.functions import col

article_df = session.table("articles")
article_df = article_df.withColumn(
    "abstract_summary",
    Summarize(col("abstract_text"))
)
article_df.collect()

Uso das funções de AI do Snowflake Cortex com Snowflake CLI¶

O Snowflake Cortex AISQL está disponível na Snowflake CLI versão 2.4.0 e posteriores. Consulte Apresentação do Snowflake CLI para obter mais informações sobre o uso de Snowflake CLI.

Os exemplos a seguir ilustram o uso dos comandos snow cortex em valores únicos. O parâmetro -c especifica qual conexão usar.

snow cortex complete "Is 5 more than 4? Please answer using one word without a period." -c "snowhouse"

snow cortex extract-answer "what is snowflake?" "snowflake is a company" -c "snowhouse"

snow cortex sentiment "Mary had a little Lamb" -c "snowhouse"

snow cortex summarize "John has a car. John's car is blue. John's car is old and John is thinking about buying a new car. There are a lot of cars to choose from and John cannot sleep because it's an important decision for John."

snow cortex translate herb --to pl

Você também pode usar arquivos que contenham o texto que deseja usar para os comandos. Para este exemplo, suponha que o arquivo about_cortex.txt tenha o seguinte conteúdo:

Snowflake Cortex gives you instant access to industry-leading large language models (LLMs) trained by researchers at companies like Anthropic, Mistral, Reka, Meta, and Google, including Snowflake Arctic, an open enterprise-grade model developed by Snowflake.

Since these LLMs are fully hosted and managed by Snowflake, using them requires no setup. Your data stays within Snowflake, giving you the performance, scalability, and governance you expect.

Snowflake Cortex features are provided as SQL functions and are also available in Python. The available functions are summarized below.

COMPLETE: Given a prompt, returns a response that completes the prompt. This function accepts either a single prompt or a conversation with multiple prompts and responses.
EMBED_TEXT_768: Given a piece of text, returns a vector embedding that represents that text.
EXTRACT_ANSWER: Given a question and unstructured data, returns the answer to the question if it can be found in the data.
SENTIMENT: Returns a sentiment score, from -1 to 1, representing the detected positive or negative sentiment of the given text.
SUMMARIZE: Returns a summary of the given text.
TRANSLATE: Translates given text from any supported language to any other.

Você pode então executar o comando snow cortex summarize passando o nome do arquivo usando o parâmetro --file, conforme mostrado:

snow cortex summarize --file about_cortex.txt

Snowflake Cortex offers instant access to industry-leading language models, including Snowflake Arctic, with SQL functions for completing prompts (COMPLETE), text embedding (EMBED\_TEXT\_768), extracting answers (EXTRACT\_ANSWER), sentiment analysis (SENTIMENT), summarizing text (SUMMARIZE), and translating text (TRANSLATE).

Para obter mais informações sobre esses comandos, consulte snow cortex commands.

Avisos legais¶

A classificação dos dados de entradas e saídas é definido na tabela a seguir.

Para obter informações adicionais, consulte AI e ML Snowflake.