Snowflake Cortex AI Functions (including LLM functions)¶

Cortex AI functions¶

これらのタスク固有の関数は、カスタマイズを必要としない、簡単な要約やクィック翻訳などのルーチンタスクを自動化するために、目的に応じて構築され管理される関数です。

• AI_COMPLETE: 選択された LLM を使用して、指定された文字列または画像の補完を生成します。生成的な AI タスクのほとんどにこの関数を使用します。

  • AI_COMPLETE は COMPLETE （SNOWFLAKE.CORTEX） の更新されたバージョンです。

• AI_CLASSIFY: テキストや画像をユーザー定義のカテゴリに分類します。

  • AI_CLASSIFY はマルチラベルと画像分類をサポートする CLASSIFY_TEXT （SNOWFLAKE.CORTEX） の更新されたバージョンです。

• AI_FILTER: イメージやテキストの入力に対してTrueかFalseを返し、 SELECT, WHERE, JOIN ... ON 句で結果をフィルターできます。

• AI_AGG: テキスト列を集約し、ユーザー定義のプロンプトに基づいて複数の行にわたる洞察を返します。この関数はコンテキストウィンドウの制限を受けません。

• AI_EMBED:テキストまたは画像入力の埋め込みベクトルを生成します。これは、類似性検索、クラスタリング、分類タスクに使用できます。

  • AI_EMBED は EMBED_TEXT_1024 (SNOWFLAKE.CORTEX) の更新されたバージョンです。

• AI_EXTRACT:入力文字列やファイル（テキスト、画像、ドキュメントなど）から情報を抽出します。複数の言語をサポートしています。

  • AI_EXTRACT は EXTRACT_ANSWER (SNOWFLAKE.CORTEX) の更新されたバージョンです。

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

• AI_SENTIMENT: Extracts sentiment from text.

  • AI_SENTIMENT は SENTIMENT (SNOWFLAKE.CORTEX) の更新されたバージョンです。

• AI_SUMMARIZE_AGG: テキスト列を集約し、複数行にわたるサマリーを返します。この関数はコンテキストウィンドウの制限を受けません。

• AI_SIMILARITY:2つの入力間の埋め込み類似度を計算します。

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

• AI_PARSE_DOCUMENT:（OCR モードを使用して）テキストを抽出します。または、レイアウト情報を含むテキストを（LAYOUT モードを使用して）内部または外部ステージのドキュメントから抽出します。

  • AI_PARSE_DOCUMENT は PARSE_DOCUMENT （SNOWFLAKE.CORTEX） の更新されたバージョンです。

• AI_TRANSLATE: サポートされている言語間でテキストを翻訳します。

  • AI_TRANSLATE は TRANSLATE (SNOWFLAKE.CORTEX) の更新されたバージョンです。

• SUMMARIZE (SNOWFLAKE.CORTEX): 指定したテキストの要約を返します。

ヘルパー関数¶

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:AI_COMPLETE とファイルを受け付けるその他の関数で使用するために、内部ステージまたは外部ステージでファイルへの参照を作成します。

• AI_COUNT_TOKENS: 入力テキストが与えられると、指定されたモデルまたはCortex関数に基づいてトークン数を返します。

  • AI_COUNT_TOKENS は COUNT_TOKENS （SNOWFLAKE.CORTEX） の更新されたバージョンです。

• PROMPT:AI_COMPLETE およびその他の関数で使用するプロンプトオブジェクトの構築を支援します。

• TRY_COMPLETE （SNOWFLAKE.CORTEX）: COMPLETE 関数と同様に動作しますが、関数を実行できなかった場合、エラーコードの代わりに NULL を返します。

Cortex Guard¶

Cortex Guardは、AI_COMPLETE（または SNOWFLAKE.CORTEX.COMPLETE）関数のオプションであり、言語モデルからの安全でない可能性のある有害な応答をフィルタリングするように設計されています。Cortex Guardは現在、MetaのLlama Guard 3で構築されています。Cortex Guardは、出力がアプリケーションに返される前に言語モデルの応答を評価することで機能します。Cortex Guardを起動すると、暴力犯罪、憎悪、性的コンテンツ、自傷行為などに関連する可能性のある言語モデルの反応が自動的にフィルタリングされます。構文と例については、 COMPLETE 引数 をご参照ください。

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.

すべてのユーザーにこの権限を付与することを回避する場合は、PUBLIC ロールへのアクセス権を取り消して、他のロールへのアクセス権を付与することができます。SNOWFLAKE.CORTEX_USER データベースロールをユーザーに直接付与することはできません。詳細については、SNOWFLAKE データベースロールの使用 をご参照ください。

PUBLIC ロールから CORTEX_USER データベースロールを取り消すには、 ACCOUNTADMIN ロールを使用して以下のコマンドを実行します。

REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER
  FROM ROLE PUBLIC;

REVOKE IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE
  FROM ROLE PUBLIC;

そして、特定のロールに選択的にアクセスを提供することができます。ACCOUNTADMIN ロールを持つユーザーは、ユーザーがCortex AI 関数にアクセスできるように、このロールをカスタムロールに付与できます。以下の例では、 ACCOUNTADMIN ロールを引き受けて、この目的のために作成したアカウントロール some_user を介して、ユーザー CORTEX_USER に cortex_user_role データベースロールを付与します。

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 ユーザーのロール.) 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;

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.

CORTEX_USER ロールと異なり、 CORTEX_EMBED_USER ロールはデフォルトでは PUBLIC ロールに付与されません。CORTEx_USER ロールを取り消している場合は、埋め込み機能を必要とするロールにこのロールを明示的に付与する必要があります。CORTEX_EMBED_USER データベースロールは、ユーザーに直接付与することはできませんが、ユーザーが引き受けることができるロールに付与する必要があります。次の例は、このプロセスを示しています。

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;

あるいは、すべてのユーザーに埋め込み機能へのアクセス権を許可するには、　PUBLIC ロールに次のようにCORTEX_EMBED_USER ロールを付与します。

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

アカウントレベルの許可リストパラメーター¶

CORTEX_MODELS_ALLOWLIST パラメーターを使用して、アカウント全体でモデルアクセスを制御できます。サポートされている機能 はこのパラメーターの値を尊重し、許可リストにないモデルの使用を阻止します。

CORTEX_MODELS_ALLOWLIST パラメーターは 'All'、'None' またはモデル名のコンマ区切りリストに設定できます。このパラメーターはアカウントレベルでのみ設定可能で、ユーザーレベルやセッションレベルでは設定できません。ALTER ACCOUNT コマンドを使用してパラメーターを設定できるのは、ACCOUNTADMIN ロールのみです。

例：

• すべてのモデルへのアクセスを許可するには:

  ALTER ACCOUNT SET CORTEX_MODELS_ALLOWLIST = 'All';
  

  Copy

• mistral-large2 モデルおよび :code:`llama3.1-70b`モデルへのアクセスを許可するには:

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

  Copy

• あらゆるモデルへのアクセスを阻止するには:

  ALTER ACCOUNT SET CORTEX_MODELS_ALLOWLIST = 'None';
  

  Copy

次のセクションで説明するように、RBAC を使用して許可リストで指定したもの以外のアクセス権を持つ特定のロールを付与します。

ロールベースのアクセス制御（RBAC）¶

Cortexのモデルはそれら自体がSnowflakeオブジェクトではありませんが、Snowflakeを使用するとCortexモデルを*表す* SNOWFLAKE.MODELS スキーマでモデルオブジェクトを作成できます。RBAC をこれらのオブジェクトに適用することによって、他のSnowflakeオブジェクトと同じ方法でモデルへのアクセスを制御できます。サポートされている機能 は、モデルを指定できるあらゆる SNOWFLAKE.MODELS のオブジェクトの識別子を受け入れます。

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

一般的な落とし穴¶

• モデルへのアクセス（許可リストまたは RBAC による）は、常に使用できるものではありません。クロスリージョン、廃止、またはその他の可用性の制約が引き続き適用される可能性があります。これらの制限により、モデルアクセスエラーに類似したエラーメッセージが表示される可能性があります。

• モデルのアクセス制御は、モデルの使用のみを管理し、独自にアクセスが制御されている可能性がある機能自体の使用は管理対象外です。たとえば、AI_COMPLETE へのアクセスは CORTEX_USER データベースロールによって管理されます。詳細については、 Cortex LLM 権限 をご参照ください。

• すべての機能がモデルアクセス制御をサポートしているわけではありません。サポートされている機能 テーブルを参照して、特定の機能がどのアクセス制御メソッドをサポートするかを確認してください。

• セカンダリロールによって、権限が不明瞭になる可能性があります。たとえば、ユーザーがセカンダリロールとして ACCOUNTADMIN を保有している場合は、すべてのモデルオブジェクトにアクセスできるように見えます。権限を確認するときに、セカンダリロールを一時的に無効にします。

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

サポートされている機能¶

モデルのアクセス制御は、以下の機能でサポートされています。

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.

  Tip

  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.

AIサービスのコストを追跡する¶

お客様のアカウントで LLM 関数を含む AI サービスに使用されたクレジットを追跡するには、 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 CORTEX_FUNCTIONS_USAGE_HISTORY ビュー:

SELECT *
  FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_FUNCTIONS_USAGE_HISTORY;

Snowflakeアカウント内で各クエリのクレジットとトークンの消費量を表示することもできます。各クエリのクレジットとトークンの消費量を表示することで、最もクレジットとトークンを消費しているクエリを特定することができます。

以下のクエリ例では、 CORTEX_FUNCTIONS_QUERY_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');

クエリの使用履歴には、 mistral-7b と mistral-large の2行が表示されます。

大規模モデル¶

どこから始めたらよいかわからない場合は、まず最も高性能なモデルを試して、他のモデルを評価するためのベースラインを確立してください。 claude-3-7-sonnet と mistral-large2 は、Snowflake Cortexが提供する最も高性能なモデルで、最先端のモデルで何ができるかを知ることができます。

• Claude 3-7 Sonnet は、一般的な推論とマルチモーダル機能のリーダーです。異なるドメインやモダリティにまたがる推論を必要とするタスクにおいて、先行製品を凌駕します。構造化クエリでも非構造化クエリでも、その大容量出力を使ってより多くの情報を得ることができます。推論機能と大容量ウィンドウにより、Agenticなワークフローに適しています。

• deepseek-r1 は、教師あり微調整 (SFT) を行わず、大規模強化学習 (RL) を用いて学習された基礎モデルです。数学、コード、推論の各タスクで高いパフォーマンスを発揮します。モデルにアクセスするには、 クロスリージョン推論パラメーター を AWS_US にセットします。

• mistral-large2 は、Mistral AIの最も高度な大規模言語モデルで、トップクラスの推論機能を備えています。mistral-large と比較すると、コード生成、数学、推論において格段に能力が高く、多言語サポートもはるかに強力です。合成テキスト生成、コード生成、多言語テキスト分析など、大規模な推論能力を必要とする複雑なタスクや、高度に専門化されたタスクに最適です。

• llama3.1-405b はMeta社の llama3.1 モデルファミリーのオープンソースモデルで、128Kの大きなコンテキストウィンドウを持ちます。長文の文書処理、多言語サポート、合成データ生成、モデルの蒸留に優れています。

• snowflake-llama3.1-405b は、オープンソースllama3.1モデルから派生したモデルです。Snowflakeの AI 研究チームによって開発された SwiftKV 最適化 を使用して、最大75%の推論コスト削減を実現します。SwiftKV は、最小限の精度損失でより高いスループットパフォーマンスを実現します。

中規模モデル¶

• llama3.1-70b は、チャットアプリケーション、コンテンツ作成、およびエンタープライズアプリケーションに理想的な最先端のパフォーマンスを提供するオープンソースモデルです。128Kのコンテキストウィンドウで多様なユースケースを可能にする、高いパフォーマンスとコスト効率を備えたモデルです。llama3-70b は現在もサポートされており、コンテキストウィンドウは8Kです。

• snowflake-llama3.3-70b は、オープンソースllama3.3モデルから派生したモデルです。Snowflakeの AI 研究チームによって開発された SwiftKV 最適化 を使用して、最大75%の推論コスト削減を実現します。SwiftKV は、最小限の精度損失でより高いスループットパフォーマンスを実現します。

• snowflake-arctic は、Snowflakeのエンタープライズ向けトップクラスの LLM です。Arcticは、SQLの生成、コーディング、ベンチマークに従った命令などのエンタープライズタスクを得意としています。

• mixtral-8x7b は、テキスト生成、分類、質問回答などに最適です。Mistralのモデルは、低レイテンシ、低メモリ要件に最適化されており、企業のユースケースにおいて高いスループットを実現します。

小規模モデル¶

• llama3.1-8b は、低～中程度の推論を必要とするタスクに最適です。軽量で超高速のモデルで、コンテキストウィンドウは128Kです。llama3-8b では、コンテキストウィンドウが小さくなり、精度が比較的低くなります。

• mistral-7b は、最も単純な要約、構造化、質問に対する回答など、素早く行う必要のあるタスクに最適です。32Kのコンテキストウィンドウにより、複数ページのテキストを低レイテンシで高スループットに処理します。

以下のテーブルは、人気モデルが各種ベンチマークでどのようなパフォーマンスを発揮するかについての情報を示しており、Snowflake Cortex AI_COMPLETEが提供するモデルや他のいくつかの人気モデルが含まれています。

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.

PythonスクリプトをSnowflakeの外で実行する場合、これらの関数を使用するにはSnowparkセッションを作成する必要があります。手順については、 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()