Snowflake Cortex AI Functions (including LLM functions)¶

Cortex AI functions¶

Les fonctions spécifiques aux tâches sont spécialement conçues et gérées pour automatiser les tâches de routine, comme les résumés simples et les traductions rapides, qui ne nécessitent aucune exigence de personnalisation.

• AI_COMPLETE : Génère un achèvement pour une chaîne de texte ou une image donnée en utilisant un LLM sélectionné. Utilisez cette fonction pour la plupart des tâches de l’AI générative.

  • AI_COMPLETE est la version mise à jour de COMPLETE (SNOWFLAKE.CORTEX).

• AI_CLASSIFY : Classe le texte ou les images dans des catégories définies par l’utilisateur.

  • AI_CLASSIFY est la version mise à jour de CLASSIFY_TEXT (SNOWFLAKE.CORTEX) avec prise en charge de la classification multi-label et des images.

• AI_FILTER : Renvoie True ou False pour une entrée de texte ou d’image donnée, ce qui vous permet de filtrer les résultats dans les clauses SELECT, WHERE ou JOIN. .. ON.

• AI_AGG : Agrège une colonne de texte et renvoie des aperçus sur plusieurs lignes en fonction d’un prompt défini par l’utilisateur. Cette fonction n’est pas soumise aux limites des fenêtres contextuelles.

• AI_EMBED : Génère un vecteur d’intégration pour une entrée de texte ou d’image, qui peut être utilisé pour des tâches de recherche de similarité, de clustering et de classification.

  • AI_EMBED est la version mise à jour de EMBED_TEXT_1024 (SNOWFLAKE.CORTEX).

• AI_EXTRACT : Extrait des informations d’une chaîne ou d’un fichier d’entrée, par exemple du texte, des images et des documents. Prend en charge plusieurs langues.

  • AI_EXTRACT est la version mise à jour de EXTRACT_ANSWER (SNOWFLAKE.CORTEX).

• AI_REDACT: Redacts personally identifiable information (PII) from text.

• AI_SENTIMENT: Extracts sentiment from text.

  • AI_SENTIMENT est la version mise à jour de SENTIMENT (SNOWFLAKE.CORTEX).

• AI_SUMMARIZE_AGG : Agrège une colonne de texte et renvoie un résumé sur plusieurs lignes. Cette fonction n’est pas soumise aux limites des fenêtres contextuelles.

• AI_SIMILARITY : Calcule la similarité d’intégration entre deux entrées.

• AI_TRANSCRIBE: Transcribes audio and video files stored in a stage, extracting text, timestamps, and speaker information.

• AI_PARSE_DOCUMENT : extrait du texte (à l’aide du mode OCR) ou du texte avec des informations de mise en page (avec le mode LAYOUT) à partir de documents dans une zone de préparation interne ou externe.

  • AI_PARSE_DOCUMENT est la version mise à jour de PARSE_DOCUMENT (SNOWFLAKE.CORTEX).

• AI_TRANSLATE : Traduit le texte entre les langues prises en charge.

  • AI_TRANSLATE est la version mise à jour de TRANSLATE (SNOWFLAKE.CORTEX).

• SUMMARIZE (SNOWFLAKE.CORTEX) : Renvoie un résumé du texte que vous avez spécifié.

Fonctions d’assistance¶

Helper functions are purpose-built managed functions that reduce cases of failures when running other Cortex AI Functions, for example by getting the count of tokens in an input prompt to ensure the call doesn’t exceed a model limit.

• TO_FILE : crée une référence à un fichier dans une zone de préparation interne ou externe pour une utilisation avec AI_COMPLETE et d’autres fonctions qui acceptent des fichiers.

• AI_COUNT_TOKENS : Avec un texte d’entrée, renvoie le nombre de jetons en fonction du modèle ou de la fonction Cortex spécifié.

  • AI_COUNT_TOKENS est la version mise à jour de COUNT_TOKENS (SNOWFLAKE.CORTEX).

• PROMPT : vous aide à créer des objets d’invite à utiliser avec AI_COMPLETE et d’autres fonctions.

• TRY_COMPLETE (SNOWFLAKE.CORTEX) : Fonctionne comme la fonction COMPLETE, mais renvoie NULL lorsque la fonction n’a pas pu s’exécuter, au lieu d’un code d’erreur.

Cortex Guard¶

cortex guard est une option de la fonction AI_COMPLETE (ou SNOWFLAKE.CORTEX.COMPLETE) conçue pour filtrer les éventuelles réponses dangereuses et nuisibles d’un modèle de langue. Cortex Guard est actuellement construit avec Llama Guard 3 de Meta. Cortex Guard fonctionne en évaluant les réponses d’un modèle de langage avant que cette sortie ne soit renvoyée à l’application. Une fois que vous avez activé Cortex Guard, les réponses du modèle linguistique qui peuvent être associées à des crimes violents, à la haine, au contenu sexuel, à l’automutilation, etc. sont automatiquement filtrées. Voir arguments COMPLETE pour la syntaxe et les exemples.

Rôle de la base de données CORTEX_USER¶

The CORTEX_USER database role in the SNOWFLAKE database includes the privileges that allow users to call Snowflake Cortex AI Functions. By default, the CORTEX_USER role is granted to the PUBLIC role. The PUBLIC role is automatically granted to all users and roles, so this allows all users in your account to use the Snowflake Cortex AI functions.

si vous ne souhaitez pas que tous les utilisateurs disposent de ce privilège, vous pouvez révoquer l’accès au rôle PUBLIC et accorder l’accès à d’autres rôles. le rôle de base de donnéesSNOWFLAKE.CORTEX_USER ne peut pas être accordé directement à un utilisateur. pour plus d’informations, consultez À l’aide des rôles de base de données SNOWFLAKE.

Pour révoquer le rôle de base de données CORTEX_USER à partir du rôle PUBLIC, exécutez les commandes suivantes à l’aide du rôle ACCOUNTADMIN :

REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER
  FROM ROLE PUBLIC;

REVOKE IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE
  FROM ROLE PUBLIC;

Vous pouvez ensuite accorder un accès sélectif à des rôles spécifiques. un utilisateur ayant le rôle ACCOUNTADMIN peut attribuer ce rôle à un rôle personnalisé afin de permettre aux utilisateurs d’accéder aux fonctions AI de cortex. Dans l’exemple suivant, vous avez le rôle ACCOUNTADMIN et accordez à l’utilisateur some_user le rôle de base de données CORTEX_USER via le rôle de compte cortex_user_role, que vous créez à cet effet.

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;

You can also grant access to Snowflake Cortex AI functions through existing roles commonly used by specific groups of users. (See Rôles utilisateur.) For example, if you have created an analyst role that is used as a default role by analysts in your organization, you can easily grant these users access to Snowflake Cortex AI Functions with a single GRANT statement.

GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE analyst;

Rôle de la base de données CORTEX_EMBED_USER¶

The CORTEX_EMBED_USER database role in the SNOWFLAKE database includes the privileges that allow users to call the text embedding functions AI_EMBED, EMBED_TEXT_768, and EMBED_TEXT_1024 and to create Cortex Search Services with managed vector embeddings. CORTEX_EMBED_USER allows you to grant embedding privileges separately from other Cortex AI capabilities.

Contrairement au rôle CORTEX_USER, le rôle CORTEX_EMBED_USER n’est pas accordé au rôle par défaut PUBLIC. Vous devez explicitement accorder ce rôle aux rôles qui nécessitent des capacités d’intégration si vous avez révoqué le rôle CORTEx_USER. Le rôle de base de données CORTEX_EMBED_USER ne peut pas être accordé directement aux utilisateurs, mais doit être accordé aux rôles que les utilisateurs peuvent assumer. L’exemple suivant illustre ce processus.

USE ROLE ACCOUNTADMIN;

CREATE ROLE cortex_embed_user_role;
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_EMBED_USER TO ROLE cortex_embed_user_role;

GRANT ROLE cortex_embed_user_role TO USER some_user;

Sinon, pour donner à tous les utilisateurs l’accès aux capacités d’intégration, accordez le rôle CORTEX_EMBED_USER au rôle PUBLIC comme suit.

USE ROLE ACCOUNTADMIN;

GRANT DATABASE ROLE SNOWFLAKE.CORTEX_EMBED_USER TO ROLE PUBLIC;

Using AI Functions in stored procedures with EXECUTE AS RESTRICTED CALLER¶

To use AI Functions inside stored procedures with EXECUTE AS RESTRICTED CALLER, grant the following privileges to the role that created the stored procedure:

GRANT INHERITED CALLER USAGE ON ALL SCHEMAS IN DATABASE snowflake TO ROLE <role_that_created_the_stored_procedure>;
GRANT INHERITED CALLER USAGE ON ALL FUNCTIONS IN DATABASE snowflake TO ROLE <role_that_created_the_stored_procedure>;
GRANT CALLER USAGE ON DATABASE snowflake TO ROLE <role_that_created_the_stored_procedure>;

Paramètre de la liste d’autorisation au niveau du compte¶

vous pouvez contrôler l’accès aux modèles pour l’ensemble de votre compte à l’aide du paramètreCORTEX_MODELS_ALLOWLIST. les fonctionnalités prises en charge respecteront la valeur de ce paramètre et empêcheront l’utilisation de modèles qui ne figurent pas dans la liste d’autorisation.

Le paramètre CORTEX_MODELS_ALLOWLIST peut être réglé sur 'All', 'None', ou sur une liste de noms de modèles séparés par des virgules. Ce paramètre ne peut être défini qu’au niveau du compte, pas aux niveaux de l’utilisateur ou de la session. seul le rôle ACCOUNTADMIN peut définir le paramètre à l’aide de la commande ALTER ACCOUNT:

Exemples :

• Pour autoriser l’accès à tous les modèles :

  ALTER ACCOUNT SET CORTEX_MODELS_ALLOWLIST = 'All';
  

  Copy

• pour permettre l’accès aux modèles mistral-large2 et llama3.1-70b :

  ALTER ACCOUNT SET CORTEX_MODELS_ALLOWLIST = 'mistral-large2,llama3.1-70b';
  

  Copy

• Pour empêcher l’accès à tout modèle :

  ALTER ACCOUNT SET CORTEX_MODELS_ALLOWLIST = 'None';
  

  Copy

utiliser le RBAC, comme décrit dans la section suivante, pour fournir des rôles spécifiques avec un accès supérieur à celui que vous avez spécifié dans la liste d’autorisation.

contrôle d’accès basé sur les rôles (RBAC)¶

Bien que les modèles Cortex ne soient pas eux-mêmes des objets Snowflake, Snowflake vous permet de créer des objets de modèle dans le schéma SNOWFLAKE.MODELS qui représentent les modèles Cortex. en appliquant le RBAC à ces objets, vous pouvez contrôler l’accès aux modèles de la même manière que vous le feriez pour tout autre objet snowflake. Les fonctionnalités prises en charge acceptent les identificateurs des objets dans SNOWFLAKE.MODELS partout où un modèle peut être spécifié.

CALL SNOWFLAKE.MODELS.CORTEX_BASE_MODELS_REFRESH();

SHOW MODELS IN SNOWFLAKE.MODELS;

SHOW APPLICATION ROLES IN APPLICATION SNOWFLAKE;

-- set up access
USE SECONDARY ROLES NONE;
USE ROLE ACCOUNTADMIN;
ALTER ACCOUNT SET CORTEX_MODELS_ALLOWLIST = 'MISTRAL-LARGE2';
CALL SNOWFLAKE.MODELS.CORTEX_BASE_MODELS_REFRESH();
GRANT APPLICATION ROLE SNOWFLAKE."CORTEX-MODEL-ROLE-LLAMA3.1-70B" TO ROLE PUBLIC;

-- test access
USE ROLE PUBLIC;

-- this succeeds because mistral-large2 is in the allowlist
SELECT AI_COMPLETE('MISTRAL-LARGE2', 'Hello');

-- this succeeds because the role has access to the model object
SELECT AI_COMPLETE('SNOWFLAKE.MODELS."LLAMA3.1-70B"', 'Hello');

-- this fails because the first argument is
-- neither an identifier for an accessible model object
-- nor is it a model name in the allowlist
SELECT AI_COMPLETE('SNOWFLAKE-ARCTIC', 'Hello');

Problèmes courants¶

• l’accès à un modèle (soit par liste d’autorisation, soit via le RBAC) ne signifie pas toujours qu’il peut être utilisé. Il peut encore être soumis à des contraintes de région, d’obsolescence ou à d’autres contraintes de disponibilité. Ces restrictions peuvent entraîner des messages d’erreur qui semblent similaires à des erreurs d’accès au modèle.

• Les contrôles d’accès aux modèles régissent uniquement l’utilisation d’un modèle, et non l’utilisation d’une fonctionnalité elle-même, qui peut avoir ses propres contrôles d’accès. par exemple, l’accès à AI_COMPLETE est régi par le rôle de base de données CORTEX_USER. Pour plus d’informations, voir Privilèges LLM Cortex.

• Toutes les fonctions ne prennent pas en charge les contrôles d’accès aux modèles. consultez le tableau des fonctionnalités prises en charge pour voir les méthodes de contrôle d’accès prises en charge par une fonctionnalité donnée.

• Les rôles secondaires peuvent masquer les autorisations. Par exemple, si un utilisateur a ACCOUNTADMIN en tant que rôle secondaire, tous les objets du modèle peuvent être accessibles. Désactivez temporairement les rôles secondaires lors de la vérification des autorisations.

• Qualified model object identifiers are quoted and therefore case-sensitive. See QUOTED_IDENTIFIERS_IGNORE_CASE for more information.

Fonctionnalités prises en charge¶

Les contrôles d’accès aux modèles sont pris en charge par les fonctionnalités suivantes :

Cortex AI Functions storage best practices¶

You may find the following best practices helpful when working with media files in stages with Cortex AI Functions:

• Establish a scheme for organizing media files in stages. For example, create a separate stage for each team or project, and store the different types of media files in subdirectories.

• Enable directory listings on stages to allow querying and programmatic access to its files.

  Astuce

  To automatically refresh the directory table for the external stage when new or updated files are available, set AUTO_REFRESH = TRUE when creating the stage.

• For external stages, use fine-grained policies on the cloud provider side (for example, AWS IAM policies) to restrict the storage integration’s access to only what is necessary.

• Always use encryption, such as AWS_SSE or SNOWFLAKE_SSE, to protect your data at rest.

Warehouse sizing¶

Snowflake recommends using a warehouse size no larger than MEDIUM when calling Snowflake Cortex AI Functions. Using a larger warehouse than necessary does not increase performance, but can result in unnecessary costs. This recommendation may change in the future as we continue to evolve Cortex AI Functions.

Suivi des coûts des services AI¶

Pour suivre les crédits utilisés pour les services d’AI, y compris les fonctions LLM de votre compte, utilisez l” Vue METERING_HISTORY :

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

Track credit consumption for Cortex AI Functions¶

To view the credit and token consumption for each AI Function call, use the Vue CORTEX_FUNCTIONS_USAGE_HISTORY:

SELECT *
  FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_FUNCTIONS_USAGE_HISTORY;

Vous pouvez également voir la consommation de crédits et de jetons pour chaque requête dans votre compte Snowflake. La vue de la consommation de crédits et de jetons pour chaque requête vous aide à identifier les requêtes qui consomment le plus de crédits et de jetons.

L’exemple de requête suivant utilise l”Vue CORTEX_FUNCTIONS_QUERY_USAGE_HISTORY pour afficher la consommation de crédits et de jetons pour toutes vos requêtes au sein de votre compte.

SELECT * FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_FUNCTIONS_QUERY_USAGE_HISTORY;

Vous pouvez également utiliser la même vue pour voir la consommation de crédits et de jetons pour une requête spécifique.

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

L’historique de l’utilisation des requêtes est groupé en fonction des modèles utilisés dans la requête. Par exemple, si vous avez exécuté :

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

L’historique de l’utilisation de la requête fait apparaître deux lignes, l’une pour mistral-7b et l’autre pour mistral-large.

Grands modèles¶

Si vous ne savez pas par où commencer, essayez d’abord les modèles les plus performants afin d’établir une base de référence pour évaluer les autres modèles. claude-3-7-sonnet et mistral-large2 sont les modèles les plus performants proposés par Snowflake Cortex. Ils vous donneront une bonne idée de ce que peut faire un modèle à la pointe de la technologie.

• Claude 3-7 Sonnet est un leader dans le domaine du raisonnement général et des capacités multimodales. Il surpasse ses prédécesseurs dans les tâches qui requièrent un raisonnement à travers différents domaines et modalités. Vous pouvez utiliser sa large capacité de sortie pour obtenir davantage d’informations à partir de requêtes structurées ou non structurées. Ses capacités de raisonnement et ses grandes fenêtres contextuelles le rendent bien adapté aux flux de travail agentiques.

• deepseek-r1 est un modèle de base formé à l’aide de l’apprentissage par renforcement à grande échelle (RL) sans affinage supervisé (SFT). Il peut offrir des performances élevées dans les tâches de mathématiques, de codage et de raisonnement. Pour accéder au modèle, définissez le paramètre d’inférence inter-régionale sur AWS_US.

• mistral-large2 est le grand modèle de langage le plus avancé de l’AI Mistral avec des capacités de raisonnement de premier plan. Par rapport à mistral-large, il est nettement plus performant en matière de génération de code, de mathématiques, de raisonnement et offre un support multilingue beaucoup plus puissant. C’est idéal pour les tâches complexes qui requièrent de grandes capacités de raisonnement ou qui sont hautement spécialisées, telles que la génération de textes synthétiques, la génération de codes et l’analyse de texte multilingue.

• llama3.1-405b est un modèle open source de la famille de modèles llama3.1 de Meta avec une grande fenêtre de contexte de 128K. Il excelle dans le traitement de documents longs, l’assistance multilingue, la génération de données synthétiques et la distillation de modèles.

• snowflake-llama3.1-405b est un modèle dérivé du modèle open source llama3.1. Il utilise les `optimisations SwiftKV<https://www.snowflake.com/en/blog/up-to-75-lower-inference-cost-llama-meta-llm/>`_ développées par l’équipe de recherche de l’AI de Snowflake pour fournir jusqu’à 75 % de réduction des coûts d’inférence. SwiftKV permet d’obtenir des performances de débit supérieures avec une perte de précision minimale.

Modèles moyens¶

• llama3.1-70b est un modèle open source qui offre des performances de pointe idéales pour les applications de chat, la création de contenu et les applications d’entreprise. Il s’agit d’un modèle hautement performant et rentable qui permet divers cas d’utilisation avec une fenêtre contextuelle de 128K. llama3-70b est toujours pris en charge et dispose d’une fenêtre contextuelle de 8K.

• snowflake-llama3.3-70b est un modèle dérivé du modèle open source llama3.3. Il utilise les `optimisations SwiftKV<https://www.snowflake.com/en/blog/up-to-75-lower-inference-cost-llama-meta-llm/>`_ développées par l’équipe de recherche de l’AI de Snowflake pour fournir jusqu’à 75 % de réduction des coûts d’inférence. SwiftKV permet d’obtenir des performances de débit supérieures avec une perte de précision minimale.

• snowflake-arctic est la solution de premier plan de Snowflake axée sur l’entreprise LLM. Arctic excelle dans les tâches d’entreprise telles que la génération de SQL, le codage et les benchmarks de suivi des instructions.

• mixtral-8x7b est idéal pour la génération de textes, la classification et la réponse aux questions. Les modèles Mistral sont optimisés pour une faible latence avec de faibles besoins en mémoire, ce qui se traduit par un débit plus élevé pour les cas d’utilisation en entreprise.

Petits modèles¶

• llama3.1-8b est idéal pour les tâches qui nécessitent un raisonnement faible à modéré. Il s’agit d’un modèle léger et ultra-rapide avec une fenêtre contextuelle de 128K. llama3-8b fournit une fenêtre contextuelle plus petite et une précision relativement faible.

• mistral-7b est idéal pour vos tâches les plus simples de résumé, de structuration et de réponse à des questions qui doivent être effectuées rapidement. Il offre une faible latence et un traitement à haut débit pour plusieurs pages de texte grâce à sa fenêtre contextuelle de 32 Ko.

Le tableau suivant fournit des informations sur les performances des modèles les plus courants sur différents benchmarks, y compris les modèles proposés par Snowflake Cortex AI_COMPLETE ainsi que quelques autres modèles courants.

Call Cortex AI Functions in Snowpark Python¶

You can use Snowflake Cortex AI Functions in the Snowpark Python API. These functions include the following. Note that the functions in Snowpark Python have names in Pythonic « snake_case » format, with words separated by underscores and all letters in lowercase.

• ai_agg

• ai_classify

• ai_complete

• ai_filter

• ai_similarity

• ai_summarize_agg

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()

from snowflake.snowpark.functions import ai_classify, col

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(col("sentence"), ["travel", "cooking"]).alias("classification")
)
df.show()

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()

Call Cortex AI Functions in Snowflake ML¶

Snowflake ML contains the older AI Functions, those with names that don’t begin with « AI ». These functions are supported in version 1.1.2 and later of Snowflake ML. The names are rendered in Pythonic « snake_case » format, with words separated by underscores and all letters in lowercase.

Si vous exécutez votre script Python en dehors de Snowflake, vous devez créer une session Snowpark pour utiliser ces fonctions. Pour obtenir des instructions, voir Connexion à Snowflake.

from snowflake.cortex import complete, extract_answer, 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("llama3.1-8b", "how do snowflakes get their unique patterns?"))
print(extract_answer(text, "When was snowflake founded?"))
print(sentiment("I really enjoyed this restaurant. Fantastic service!"))
print(summarize(text))
print(translate(text, "en", "fr"))

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))

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()