Snowflake Cortex AISQL（包括 LLM 功能）¶

可用函数¶

Snowflake Cortex 功能以 SQL 函数的形式提供，而且也可用于 Python 中。Cortex AISQL 函数可以分为以下几类：

• AISQL 函数

• 辅助函数

性能注意事项¶

Cortex AISQL 函数针对吞吐量进行了优化。我们建议使用这些函数来处理大量输入，例如大型 SQL 表的文本。批处理通常更适用于 AISQL 函数。对于延迟很重要的更多交互式使用案例，请使用 REST API。这些可用于简单推理 (Complete API)、嵌入 (Embed API) 和代理应用程序 (Agents API)。

所需权限¶

SNOWFLAKE 数据库中的 CORTEX_USER 数据库角色包含了允许用户调用 Snowflake Cortex AI 函数的权限。默认情况下，CORTEX_USER 角色被授予给 PUBLIC 角色。PUBLIC 角色会自动授予给所有用户和角色，从而允许您账户中的所有用户使用 Snowflake Cortex AI 函数。

如果您不希望所有用户都拥有此权限，则可以撤销对 PUBLIC 角色的访问权限，并授予对特定角色的访问权限。

要从 PUBLIC 角色中撤销 CORTEX_USER 数据库角色，请使用 ACCOUNTADMIN 角色运行以下命令：

REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER
  FROM ROLE PUBLIC;

REVOKE IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE
  FROM ROLE PUBLIC;

然后，您可以有选择地提供对特定角色的访问权限。不能直接向用户授予 SNOWFLAKE.CORTEX_USER 数据库角色。有关更多信息，请参阅 使用 SNOWFLAKE 数据库角色。具有 ACCOUNTADMIN 角色的用户可以将此角色授予自定义角色，以允许用户访问 Cortex AI 函数。在以下示例中，使用 ACCOUNTADMIN 角色，并通过您为此目的创建的账户角色 cortex_user_role 向用户 some_user 授予 CORTEX_USER 数据库角色。

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;

您还可以通过特定用户组通常使用的现有角色，授予对 Snowflake Cortex AI 函数的访问权限。（请参阅 用户角色。）例如，如果您创建了一个 analyst 角色（它被组织中的分析师用作默认角色），则可以使用一条 GRANT 语句，轻松地向这些用户授予对 Snowflake Cortex AISQL 函数的访问权限。

GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE analyst;

控制模型访问¶

有两种方法可以控制 Snowflake Cortex 中模型的访问权限。您可以使用其中一种方法或同时使用两种方法，来结合使用广泛和细粒度的访问控制：

• 模型允许列表

• 基于角色的访问控制

模型允许列表为账户中的所有用户提供对模型的默认访问级别，可以使用 CORTEX_MODELS_ALLOWLIST 参数进行自定义。基于角色的访问控制允许通过应用程序角色授予或撤销特定模型对象的权限，从而实现细粒度的访问管理。

模型访问控制适用于以下服务：

• AISQL 函数

• Cortex REST API

• TRY_COMPLETE (SNOWFLAKE.CORTEX)

• Cortex Playground

精细的访问控制方法不适用于以下服务：

• Cortex Search

• Cortex Analyst

• Cortex Copilot

• Cortex Agents

• 文档 AI

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

可用性¶

Snowflake Cortex AI 函数目前在以下区域可用。要从未列出的区域访问 LLMs，请使用 跨区域推理参数。

以下 Snowflake Cortex AI 函数目前在以下扩展区域可用。

下表列出了旧版模型。如果您刚刚开始使用，请先从前述表中的模型开始：

成本注意事项¶

Snowflake Cortex AI 函数根据处理的词元数产生计算成本。请参阅 Snowflake 服务使用表，以了解每个函数的每百万个词元消耗的 credit 成本。

词元是 Snowflake Cortex AI 函数处理的最小文本单位，大约等于四个字符。原始输入或输出文本与词元的等价性可能因模型而异。

• 对于在响应中生成新文本的函数（AI_COMPLETE、AI_CLASSIFY、AI_FILTER、AI_AGG、AI_SUMMARIZE 和 TRANSLATE），输入和输出词元都会统计在内。

• 对于 CORTEX GUARD，仅统计输入词元。输入词元的数量基于 COMPLETE 函数中使用的每个 LLM 模型的输出词元的数量。

• 对于 AI_SIMILARITY EMBED_* 函数，仅统计输入词元。

• 对于 EXTRACT_ANSWER，可计费词元的数量是 from_text 和 question 字段中的词元数量之和。

• AI_CLASSIFY、AI_FILTER、AI_AGG、AI_SUMMARIZE_AGG、SUMMARIZE、TRANSLATE、EXTRACT_ANSWER、ENTITY_SENTIMENT 和 SENTIMENT 会向输入文本添加提示，以生成响应。因此，输入词元计数高于您提供的文本中的词元数。

• AI_CLASSIFY 标签、描述和示例会作为每条已处理记录的输入词元进行计算，而不仅针对每次 AI_CLASSIFY 调用计算一次。

• 对于 PARSE_DOCUMENT (SNOWFLAKE.CORTEX)，按处理的文档页数计费。

• TRY_COMPLETE(SNOWFLAKE.CORTEX) 不会产生错误处理成本。这意味着如果 TRY_COMPLETE(SNOWFLAKE.CORTEX) 函数返回 NULL，则不会产生任何成本。

• COUNT_TOKENS(SNOWFLAKE.CORTEX) 只会产生运行函数的计算成本。不会产生额外的词元成本。

Snowflake 建议在使用较小仓库（不大于 MEDIUM）的情况下执行调用 Snowflake Cortex AISQL 函数或 Cortex PARSE_DOCUMENT 函数的查询，因为较大的仓库不会提高性能。在执行调用 Snowflake Cortex LLM 函数的查询时，与保持仓库活动相关的成本将继续适用。有关计算成本的一般信息，请参阅 了解计算成本。

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

使用量配额¶

为确保所有 Snowflake 客户都可以访问 LLM 功能，Snowflake Cortex AI 函数在高使用率期间可能会受到限流。使用量配额不会在账户级别应用。

受到限流的请求将收到一个 错误响应，并应稍后重试。

管理成本和限流¶

在调用 Snowflake Cortex AISQL 函数时，Snowflake 建议使用不大于 MEDIUM 的仓库。使用不必要的较大仓库不会提高性能，但可能会导致不必要的成本和更高的限流风险。由于产品更新在即，此建议将来可能不适用。

模型限制¶

Snowflake Cortex 使用的模型具有大小限制，如下表所述。大小以词元数指定。词元通常表示大约四个字符的文本，因此限制对应的单词数小于词元数。超过限制的输入将导致错误。

模型可以生成的输出的最大大小受以下限制：

• 模型的输出词元限制。

• 模型使用输入词元后上下文窗口中的可用空间。

例如，claude-3-5-sonnet 具有 200,000 个词元的上下文窗口。如果使用 100,000 个词元进行输入，则模型最多可以生成 8,192 个词元。但是，如果使用 195,000 个词元作为输入，则模型最多只能生成 5,000 个词元，总共 200,000 个词元。

选择模型¶

Snowflake Cortex COMPLETE 函数支持多种不同功能、延迟和成本的模型。 这些模型经过精心挑选，符合常见的客户用例。要实现最佳的 每 credit 性能，请选择与任务的内容大小和复杂性正确匹配的模型。以下是可用模型的简要概述。

以前的模型版本¶

Snowflake Cortex COMPLETE 函数还支持以下较旧的模型版本。我们建议使用最新的模型版本，而不是此表中列出的版本。

错误条件¶

Snowflake Cortex AI 函数可能会生成以下错误消息。

将 Snowflake Cortex AISQL 与 Python 一起使用¶

您可以在 Snowpark Python API 中使用 Snowflake Cortex AISQL 函数。在 API 中，您可以使用函数对文本和图像数据进行分类、汇总和筛选。

包括以下函数：

• ai_agg() – 使用自然语言指令汇总一列文本。有关更多信息，请参阅 AI_AGG。

• ai_classify() – 将文本或图像分类为自定义类别。有关更多信息，请参阅 AI_CLASSIFY。

• ai_filter() – 使用自然语言筛选数据。有关更多信息，请参阅 AI_FILTER。

ai_agg() 函数使用自然语言指令汇总一列文本，其方式与您要求分析师从分组或未分组的数据中汇总或提取结果的方式类似。

以下示例使用 ai_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()

ai_classify() 函数获取文本或图像并将其分类到您定义的类别中。

以下示例将旅行评论分为“travel”和“cooking”等类别。该函数采用一列文本和一个类别列表来对文本进行分类。

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

ai_filter() 函数评估自然语言条件并返回 TRUE 或 FALSE。可以使用它来筛选或标记行。

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

在 Snowpark ML 版本 1.1.2 及更高版本中，仍然支持现有的 Snowpark ML 函数。请参阅 在本地使用 Snowflake ML，以了解有关设置 Snowpark ML 的说明。

如果在 Snowflake 之外运行 Python 脚本，则必须创建 Snowpark 会话才能使用这些函数。有关说明，请参阅 连接到 Snowflake。

以下 Python 示例演示了如何对单个值调用 Snowflake Cortex AI 函数：

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

在使用 COMPLETE 函数时，可以传递影响模型超参数的选项。以下 Python 示例说明调用 COMPLETE 函数的情况，调用时修改了模型可以生成的最大输出词元数：

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

您也可以对表列调用 AI 函数，如下所示。此示例需要一个会话对象（存储在 session 中）和一个包含文本列 abstract_text 的表 articles，并会创建一个新列 ``abstract_summary``（包含摘要的汇总）。

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

将 Snowflake Cortex AI 函数与 Snowflake CLI 一起使用¶

Snowflake Cortex AISQL 可在 Snowflake CLI 版本 2.4.0 及更高版本中使用。有关使用 Snowflake CLI 的更多信息，请参阅 隆重推出 Snowflake CLI。

以下示例说明了如何在单个值上使用 snow cortex 命令。-c 参数指定要使用的连接。

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

也可以使用包含要用于命令的文本的文件。对于此示例，假设文件 about_cortex.txt 包含以下内容：

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.

然后，您可以通过使用 --file 参数传入文件名来执行 snow cortex summarize 命令，如下所示：

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

有关这些命令的更多信息，请参阅 snow cortex commands。

法律声明¶

输入和输出的 Data Classification 如下表所示。

有关更多信息，请参阅 Snowflake AI 和 ML。