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. 运行批处理任务前检查 token 成本 — 对样本运行 AI_COUNT_TOKENS(model, text)，然后再对大型表运行函数。
3. 在 SQL 中进行原型验证 — 在带有 LIMIT 的小样本上调用函数并检查结果，然后再对整张表运行。
4. 明确构造提示词 — 使用 PROMPT('template {0}', arg) 创建参数化提示词；需要结构化字段时，将 JSON 输出转换为 VARIANT。
5. 对于 RAG，搭建 Cortex Search — 在源表上创建 CORTEX SEARCH SERVICE，通过 Python 或 REST API 查询以检索上下文，然后将该上下文传入 AI_COMPLETE。
6. 使用专用计算资源 — 将 Cortex Search 的后备仓库规模控制在不超过 MEDIUM，并将其与其他管道仓库分开。
7. 防范失败 — 对于不应因单次失败而导致整个批次失败的批处理任务，使用 TRY_COMPLETE 替代 AI_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	计算两个输入之间的嵌入相似度
AI_TRANSCRIBE	转录暂存区中的音频/视频文件
AI_PARSE_DOCUMENT	对暂存区中的文档执行 OCR 或文本 + 布局提取
AI_REDACT	从文本中屏蔽 PII
AI_TRANSLATE	在支持的语言之间翻译文本

辅助函数：

• TO_FILE('@stage', 'filename') — 为文档/图像处理构建文件引用。
• AI_COUNT_TOKENS(model, text) — 调用模型前检查 token 数量，尤其是在运行大型批处理任务前。
• 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 函数需要 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_CLASSIFY 而非 AI_COMPLETE——它专为此用途设计，成本也更低。
• 在大型批处理任务前运行 AI_COUNT_TOKENS，以估算成本并避免意外截断。
• 为 Cortex Search 服务设置 PRIMARY KEY，这样刷新就是增量式的，而非完整重建。
• 对任何需要在查询时筛选的列使用 ATTRIBUTES。
• 在开发过程中使用 SEARCH_PREVIEW 进行交互式测试；在生产集成中使用 Python 或 REST API。
• 为搜索服务提供支持的仓库规格不要超过 MEDIUM，并将其专用于该服务。

反模式

• 不要使用已弃用的函数名称（COMPLETE、CLASSIFY_TEXT 等）——请使用当前的 AI_* 版本。
• 不要逐行将整个表传入 AI_COMPLETE，而不先使用 AI_COUNT_TOKENS 估算成本。
• 不要在未确认模型的区域可用性前硬编码模型名称。
• 对于 AI_CLASSIFY、AI_FILTER、AI_EXTRACT 等更专用的函数已能处理的任务，不要使用 AI_COMPLETE。