snowflake-cortex-ai

Snowflake Cortex AI

このスキルでは、Snowflake Cortex について説明します。Snowflake の SQL から呼び出せる AI レイヤーであり、LLM／ML タスク向けの Cortex AI Functions と、管理型のハイブリッド検索（ベクトル＋キーワード検索）を行う Cortex Search が含まれます。すべて Snowflake 内で実行され、データがプラットフォームの外に出ることはありません。

Cortex を活用した機能を構築するワークフロー

1. タスクに最適な、最も限定的な関数を選びます — 分類には AI_CLASSIFY、自然言語による行のフィルタリングには AI_FILTER、構造化フィールドの抽出には AI_EXTRACT を使い、自由形式の生成には AI_COMPLETE を使用します。限定的な関数のほうが、すべてを AI_COMPLETE に渡すよりも低コストで信頼性が高くなります。
2. バッチジョブの前にトークンコストを確認します — 大きなテーブルに対して関数を実行する前に、サンプルを使って AI_COUNT_TOKENS(model, text) を実行します。
3. SQL でプロトタイプを作成します — 少量の LIMIT 付きサンプルに対して関数を呼び出し、結果を確認してからテーブル全体に対して実行します。
4. プロンプトを明示的に構成します — パラメーター化されたプロンプトには PROMPT('template {0}', arg) を使い、構造化フィールドを取得する必要がある場合は JSON 出力を VARIANT にキャストします。
5. RAG には Cortex Search を構築します — ソーステーブルに対して CORTEX SEARCH SERVICE を作成し、Python API または REST API でクエリしてコンテキストを取得し、そのコンテキストを AI_COMPLETE に渡します。
6. 専用のコンピューティングリソースを使います — Cortex Search を支えるウェアハウスのサイズは MEDIUM 以下にし、他のパイプライン用ウェアハウスとは分離します。
7. 失敗に備えます — 1 件の失敗でジョブ全体が失敗してはならないバッチジョブでは、AI_COMPLETE の代わりに TRY_COMPLETE を使います。エラーを発生させずに NULL を返します。

Cortex AI Functions

使用可能な関数（現在の名前を使用してください。COMPLETE や CLASSIFY_TEXT などの非推奨の名前は使用しないでください）：

関数	用途
AI_COMPLETE	テキスト、画像、ドキュメントを対象とする汎用 LLM 補完
AI_CLASSIFY	テキスト／画像をユーザー定義のカテゴリに分類（複数ラベルに対応）
AI_FILTER	テキスト／画像入力に対して TRUE／FALSE を返す — WHERE で直接使用可能
AI_AGG	コンテキストウィンドウの制限なしに、複数のテキスト行からインサイトを集約
AI_EMBED	類似検索またはクラスタリング用の埋め込みベクトルを生成
AI_EXTRACT	テキスト、画像、ドキュメントから構造化フィールドを抽出
AI_SENTIMENT	テキストの感情スコアを -1 から 1 の範囲で返す
AI_SUMMARIZE_AGG	コンテキストウィンドウの制限なしに、複数の行を要約
AI_SIMILARITY	2 つの入力間の埋め込み類似度
AI_TRANSCRIBE	ステージ内の音声／動画ファイルを文字起こし
AI_PARSE_DOCUMENT	ステージ内のドキュメントから OCR またはテキスト＋レイアウトを抽出
AI_REDACT	テキストから PII をマスキング
AI_TRANSLATE	対応言語間でテキストを翻訳

ヘルパー関数：

• TO_FILE('@stage', 'filename') — ドキュメント／画像処理用のファイル参照を作成します。
• AI_COUNT_TOKENS(model, text) — モデルを呼び出す前にトークン数を確認します。特に、大規模なバッチジョブの前に使用します。
• PROMPT('template {0}', arg) — AI_COMPLETE 用のパラメーター化されたプロンプトオブジェクトを作成します。
• TRY_COMPLETE — AI_COMPLETE と同様ですが、エラーを発生させず、失敗時に NULL を返します。

AI_COMPLETE — 主な関数

対応モデルには、claude-4-opus、claude-4-sonnet、claude-sonnet-4-5、claude-opus-4-5、claude-haiku-4-5、gemini-3-pro、llama3.1-70b、llama3.1-8b、llama3.3-70b、mistral-large2、mistral-small2、deepseek-r1 などがあります。モデルの利用可否はリージョンによって異なります。リージョンで利用可能か確認せずに、モデル名をハードコードしないでください。

-- Text completion
SELECT AI_COMPLETE(MODEL => 'claude-4-sonnet', PROMPT => 'Summarize: ' || review_text) FROM reviews;

-- Document processing
SELECT AI_COMPLETE(
  MODEL => 'claude-4-sonnet',
  PROMPT => PROMPT('Extract the invoice total from {0}', TO_FILE('@docs', 'invoice.pdf'))
);

-- Structured JSON output
SELECT AI_COMPLETE(MODEL => 'claude-4-sonnet',
  PROMPT => 'Extract name, email, company as JSON: ' || raw_text)::VARIANT AS extracted
FROM contacts;

分類、フィルタリング、集約

-- AI_CLASSIFY: cheaper than AI_COMPLETE for categorization tasks
SELECT AI_CLASSIFY(ticket_text, ['billing', 'technical', 'account', 'other']) AS category FROM tickets;
-- Multi-label: AI_CLASSIFY(input, categories, {'output_mode': 'multi'})

-- AI_FILTER: natural-language predicate directly in WHERE
SELECT * FROM reviews WHERE AI_FILTER(review_text, 'mentions product quality issues');

-- AI_AGG: cross-row aggregation with no context-window limit
SELECT AI_AGG(feedback_text, 'What are the top 3 themes?') FROM customer_feedback;

-- AI_EXTRACT: pull named fields out of free text
SELECT AI_EXTRACT(email_body, 'meeting date', 'attendees', 'action items') FROM emails;

その他の関数

SELECT review_text, AI_SENTIMENT(review_text) AS sentiment FROM product_reviews;
SELECT AI_EMBED(description) AS embedding FROM products;
SELECT AI_PARSE_DOCUMENT(TO_FILE('@docs', 'contract.pdf'), MODE => 'LAYOUT');
SELECT AI_TRANSCRIBE(TO_FILE('@media', 'recording.mp3')) AS transcript;
SELECT AI_REDACT(customer_notes) AS redacted FROM support_cases;

権限

Cortex AI Functions を使用するには、アカウント権限 USE AI FUNCTIONS とデータベースロール SNOWFLAKE.CORTEX_USER の両方が必要です。どちらもデフォルトで PUBLIC に付与されているため、ほとんどのワークロードでは追加の権限付与なしで動作します。

Cortex Search — ベクトル検索とキーワード検索のハイブリッド

Cortex Search は、ベクトル（意味）検索とキーワード（語彙）検索を組み合わせた、フルマネージド型の検索機能です。一般的な用途には、LLM チャットボット向けの RAG、エンタープライズ検索、AI を活用した質疑応答があります。

単一インデックスのサービス

CREATE OR REPLACE CORTEX SEARCH SERVICE my_search
  ON transcript_text
  ATTRIBUTES region, agent_id
  WAREHOUSE = my_wh
  TARGET_LAG = '1 day'
  EMBEDDING_MODEL = 'snowflake-arctic-embed-l-v2.0'
  AS (SELECT transcript_text, region, agent_id FROM support_transcripts);

マルチインデックスのサービス（列をまたいだテキストとベクトル）

CREATE OR REPLACE CORTEX SEARCH SERVICE my_multi_search
  TEXT INDEXES transcript_text, summary
  VECTOR INDEXES transcript_text (model='snowflake-arctic-embed-l-v2.0')
  ATTRIBUTES region
  WAREHOUSE = my_wh
  TARGET_LAG = '1 hour'
  AS (SELECT transcript_text, summary, region FROM support_transcripts);

主なパラメーター：ON（単一インデックスの列）、TEXT INDEXES、VECTOR INDEXES、ATTRIBUTES（フィルター可能な列）、TARGET_LAG（鮮度）、EMBEDDING_MODEL、PRIMARY KEY（最適化された増分更新を有効にします。ソーステーブルに安定したキーがある場合は必ず設定してください）。

クエリ — Python API（アプリケーションに推奨）

from snowflake.core import Root

root = Root(session)
service = root.databases["db"].schemas["schema"].cortex_search_services["my_search"]
resp = service.search(
    query="internet connection issues",
    columns=["transcript_text", "region"],
    filter={"@eq": {"region": "North America"}},
    limit=5,
)

クエリ — REST API

POST /api/v2/databases/<db>/schemas/<schema>/cortex-search-services/<service>:query
Body: {"query": "...", "columns": [...], "filter": {...}, "limit": N}

フィルター構文

{"@eq": {"region": "NA"}}
{"@contains": {"tags": "urgent"}}
{"@gte": {"score": 0.8}}
{"@and": [f1, f2]}
{"@or": [f1, f2]}
{"@not": f}

関連性の調整

テキストの一致度、ベクトルの類似度、再ランキングスコアの重み付けを調整します。

resp = service.search(
    query="billing dispute",
    columns=["transcript_text"],
    scoring_config={"weights": {"texts": 0.3, "vectors": 0.5, "reranker": 0.2}},
    limit=10,
)

RAG パターン

1. コンテキストを取得します：results = service.search(query=question, columns=["content"], limit=5)
2. 取得したコンテキストを AI_COMPLETE に渡します。

SELECT AI_COMPLETE(
  MODEL => 'claude-4-sonnet',
  PROMPT => 'Answer using only this context: ' || context || ' Question: ' || question
);

ベストプラクティス

• 分類には AI_COMPLETE ではなく AI_CLASSIFY を使用してください。分類専用に設計されており、コストも低くなります。
• 大規模なバッチジョブの前に AI_COUNT_TOKENS を実行してコストを見積もり、予期しない切り捨てを防いでください。
• Cortex Search サービスに PRIMARY KEY を設定して、全体を再構築するのではなく、増分更新を行うようにしてください。
• クエリ時にフィルターする必要がある列には、ATTRIBUTES を使用してください。
• 開発時の対話的なテストには SEARCH_PREVIEW を使用してください。本番環境との統合には Python API または REST API を使用してください。
• 検索サービスを支えるウェアハウスのサイズは MEDIUM 以下にし、そのサービス専用にしてください。

アンチパターン

• 非推奨の関数名（COMPLETE、CLASSIFY_TEXT など）は使用せず、現行の AI_* バージョンを使用してください。
• AI_COUNT_TOKENS で事前にコストを見積もらず、テーブル全体を行ごとに AI_COMPLETE に渡さないでください。
• リージョンで利用できるか確認せずに、モデル名をハードコードしないでください。
• より用途を限定した関数（AI_CLASSIFY、AI_FILTER、AI_EXTRACT）で対応できるタスクに AI_COMPLETE を使用しないでください。