Cortex Analyst

概述

Cortex Analyst 是一个完全托管的、LLM 支持的 Snowflake Cortex 功能,可帮助您创建能够基于 Snowflake 中的结构化数据可靠回答业务问题的应用程序。利用 Cortex Analyst,业务用户可以用自然语言提问,并直接获得答案,无需撰写 SQL 代码。Cortex Analyst 作为便捷的 REST API 提供,可以无缝集成到任何应用程序。

构建生产级对话式自助服务分析解决方案需要能够生成准确文本到 SQL 响应的服务。对于大多数团队来说,开发这样一个能够成功平衡准确性、延迟和成本的服务是一项艰巨的任务。Cortex Analyst 通过提供一个完全托管的复杂代理 AI 系统来简化这一过程,该系统可以处理所有这些复杂问题,生成高度准确的文本到 SQL 响应。它可帮助您加快向业务团队交付高精度自助式会话分析,同时避免复杂的 RAG 解决方案模式、模型实验和 GPU 容量规划等消耗时间。生成的 SQL 查询将针对可扩展的 Snowflake 引擎执行,确保行业领先的性价比和更低的总拥有成本 (TCO)。

小技巧

想要快速开始使用 Cortex Analyst?尝试 教程:使用 Cortex Analyst 回答有关时间序列收入数据的问题 教程。

主要功能

  • 通过自然语言查询进行自助分析。 通过 Snowflake 中的结构化数据提供即时答案和见解,让业务团队和非技术用户更加轻松。使用 Cortex Analyst,您可以构建下游聊天应用程序,让用户能够使用自然语言提问并即时获得准确的答案。

  • 用于集成到现有业务工作流程的便捷 REST API。 Cortex Analyst 采用 API 优先方法,让您可以完全掌控最终用户体验。轻松将 Cortex Analyst 集成到现有业务工具和平台中,为各种业务用户运营的位置增加数据洞察功能,例如 Streamlit 应用程序、Slack、Teams、自定义聊天界面等。

  • 由先进的大型语言模型提供支持: 默认情况下,最新的 Meta Llama 和 Mistral 模型为 Cortex Analyst 提供支持,这些模型在 Snowflake Cortex <label-cortex_llm_availability>`(Snowflake 的完全托管智能 AI 服务)中安全运行。此外,您还可以授予 |cortex-analyst| 访问最新的 Azure 托管 OpenAI GPT 模型的权限。在运行时,|cortex-analyst| 选择最佳模型组合,以确保每个查询的最高准确性和性能。有关详细信息,请参阅 :ref:`label-copilot_enable_azure_openai_models。随着 LLMs 的发展,Snowflake 将继续探索添加更多模型,以进一步提高性能和准确性。

  • 高精度和准确性的语义模型: 当仅给出数据库架构时,通用 AI 解决方案通常难以进行文本到 SQL 转换,因为架构缺乏业务流程定义和指标处理等关键知识。Cortex Analyst 通过使用 语义模型 来弥合业务用户和数据库之间的鸿沟,克服了这一限制。在轻量级 YAML 文件中捕获,语义模型的整体结构和概念与数据库架构相似,但允许对数据相关的语义信息进行更丰富的描述。

    如果您设置 Cortex Analyst 来回答来自大量数据源的问题,则 Cortex Analyst 可以自动找出要使用哪个数据源的问题。您不必担心为每个查询指定正确的查询。

  • 安全与治理。 Snowflake 的隐私优先基础和企业级安全性可确保您可以放心探索 AI 驱动型用例,因为您知道数据受到了最高隐私和治理标准的保护。

    • Cortex Analyst 不使用客户数据进行训练。我们不会使用客户数据来训练或微调任何模型以供我们的客户群使用。此外,对于推理,Cortex Analyst 仅会利用语义模型 YAML 文件中提供的元数据(例如,表名、列名、值类型、描述等)进行 SQL 查询生成。然后,在 Snowflake 虚拟仓库中执行此 SQL 查询以生成最终输出。

    • 数据在 Snowflake 治理范围内。默认情况下,Cortex Analyst 由来自 Mistral 和 Meta 的 Snowflake 托管 LLMs 提供支持,确保没有数据(包括元数据或提示)不在 Snowflake 的治理范围内。如果您选择使用 Azure OpenAI 模型,则只有元数据和提示会传输到 Snowflake 的治理范围之外。

    • 与 Snowflake 的隐私和治理功能无缝集成。Cortex Analyst 与 Snowflake 的基于角色的访问控制 (RBAC) 策略完全集成,确保生成和执行的 SQL 查询符合所有确立的访问控制。这保证了数据的强大安全性和治理能力。

访问控制要求

要向 Cortex Analyst 发起请求,请使用具有 SNOWFLAKE.CORTEX_USER 或 SNOWFLAKE.CORTEX_ANALYST_USER 数据库角色的角色。CORTEX_USER 可访问所有涵盖的 AI 功能,而 CORTEX_ANALYST_USER 仅限访问 Cortex Analyst。有关涵盖的 AI 功能的详细信息,请参阅 法律声明

要将 Cortex Analyst 和语义模型结合使用,您还需要以下权限:

权限

对象

READ 或 WRITE

如果语义模型上传到暂存区,则为包含语义模型 YAML 文件的暂存区。

USAGE

语义模型中提到的 Cortex Search 服务。

SELECT

语义模型中提到的表。

对 Cortex Analyst API 的请求必须包含授权令牌。有关如何对 API 进行身份验证的详细信息,请参阅 使用 Snowflake 对 Snowflake REST APIs 进行身份验证

请注意,本主题中的示例使用会话令牌对 Snowflake 账户进行身份验证。

限制访问特定角色

默认情况下,CORTEX_USER 角色被授予给 PUBLIC 角色。PUBLIC 角色会自动授予所有用户和角色。如果您不希望所有用户都拥有此权限,则可以撤销对 PUBLIC 角色的访问权限,并授予对特定角色的访问权限。有关更多信息,请参阅 所需权限

要控制对特定语义模型的访问,您可以将 YAML 文件存储在暂存区中并控制对该暂存区的访问。

Limiting access using the Cortex Analyst user role

要向特定用户提供对 Cortex Analyst 的选择性访问权限,请使用 SNOWFLAKE.CORTEX_ANALYST_USER 数据库角色。该角色包含调用 Cortex Analyst API 所需的权限。有关涵盖的 AI 功能的更多信息,请参阅 法律声明

重要

如果您的用户角色拥有 CORTEX_USER 角色,则必须撤销对 CORTEX_USER 角色的访问权限。要从用户角色中撤销 CORTEX_USER 数据库角色,请使用 ACCOUNTADMIN 角色运行以下命令:

REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER FROM ROLE analyst;
Copy

要为 Cortex Analyst 提供访问权限,请使用 ACCOUNTADMIN 角色执行以下操作:

  1. 向自定义角色授予 SNOWFLAKE.CORTEX_ANALYST_USER 数据库角色。

  2. 将此自定义角色分配给用户。

备注

您不能直接向用户授予数据库角色。有关更多信息,请参阅 GRANT DATABASE ROLE

以下示例:

  1. 创建自定义角色,cortex_analyst_user_role

  2. 向它授予 CORTEX_ANALYST_USER 数据库角色。

  3. 将此角色分配给 example_user

USE ROLE ACCOUNTADMIN;
CREATE ROLE cortex_user_role;
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE cortex_analyst_user_role;

GRANT ROLE cortex_analyst_user_role TO USER example_user;
Copy

您还可以通过现有角色授予对 Cortex Analyst 的访问权限。例如,如果您组织中有分析师使用的 analyst 角色,则可通过单条 GRANT 语句授予访问权限:

GRANT DATABASE ROLE SNOWFLAKE.CORTEX_ANALYST_USER TO ROLE analyst;
Copy

区域可用性

Cortex Analyst 在以下区域原生可用。

  • AWS ap-northeast-1(东京)

  • AWS ap-southeast-2(悉尼)

  • AWS us-east-1(弗吉尼亚)

  • AWS US 东部(商业政府 – 弗吉尼亚北部)

  • AWS us-west-2(俄勒冈)

  • AWS eu-central-1(法兰克福)

  • AWS eu-west-1(爱尔兰)

  • Azure 东部 US 2(弗吉尼亚)

  • Azure 欧洲西部(荷兰)

如果您的 Snowflake 账户位于不同的云区域,您仍然可以通过 跨区域推理 使用 Cortex Analyst。启用跨区域推理后,Cortex Analyst 将处理其他区域中对默认区域中不可用的模型的请求。为获得最佳性能,请使用 AWS US 区域配置跨区域。

Cortex Analyst 中的多轮对话

Cortex Analyst 支持针对数据相关问题的多轮对话。此功能允许提出基于先前查询的后续问题,打造更具动态和交互性的数据探索体验。例如,用户问,“2021 年亚洲的收入环比增长是多少?”,然后接着问,“北美呢?”

Cortex Analyst 识别后续问题,从初始查询中检索上下文,并将第二个问题重新措辞为:“2021 年北美的收入环比增长是多少?”然后,Cortex Analyst 生成一个 SQL 查询来回答这个问题。

要使用此功能,请在 messages 字段中传输会话历史记录:

{
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What is the month over month revenue growth for 2021 in Asia?"
                }
            ]
        },
        {
            "role": "analyst",
            "content": [
                {
                    "type": "text",
                    "text": "We interpreted your question as ..."
                },
                {
                    "type": "sql",
                    "statement": "SELECT * FROM table"
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What about North America?"
                }
            ]
        },
    ],
    "semantic_model_file": "@my_stage/my_semantic_model.yaml"
}
Copy

会话历史记录是按时间顺序排列的消息数组,其中每条消息都有一个角色和内容。角色可以是 ``"user"``(对于以前的问题)或 ``"analyst"``(对于以前的回答)。分析师响应有文本响应和 SQL 响应,如上述示例所示,而用户消息只有文本。

重要

Cortex Analyst 所使用的大型语言模型不会在请求之间保留状态。每次会话中的新查询都会处理完整历史记录,且相应计算成本会随轮次增加。

多轮对话中的已知限制

未来的 Cortex Analyst 版本可能会解决以下某些限制。

访问先前 SQL 查询的结果

Cortex Analyst 无法访问先前 SQL 查询的结果。例如,如果您先问“我的产品有哪些?”,然后问“第二个产品的收入是多少?”,那么,Cortex Analyst 无法参考第一个查询中的产品列表来获取第二个产品。

一般业务见解

Cortex Analyst 只能回答可以通过 SQL 解决的问题。它不会针对更广泛的业务相关查询生成见解,例如“您观察到什么趋势?”

长对话

如果对话包含太多轮或用户频繁改变意图,则 Cortex Analyst 可能难以解读后续问题。在这种情况下,请重置对话并重新开始。

开始使用

开发人员可以使用以下资源开始使用 Cortex Analyst:

  1. 基本代码示例:下一节中的 Cortex Analyst 示例 提供了一个简单易读的脚本,可帮助您使用 Cortex Analyst 创建交互式应用程序。

    如果您希望从基本的基础示例开始,能够轻松使用 Streamlit 并进行修改,请选择此选项。您可以在 Streamlit in Snowflake (SiS) 或本地运行此示例。

  2. Snowflake Samples 存储库:如果您需要更全面的实施,Snowflake Samples 存储库中的 Cortex Analyst 高级 SiS 演示已经设置了所有功能和选项。此存储库配置了各种预构建的功能,能够无缝且稳健地部署 Cortex Analyst。

    如果您是第一次尝试测试该功能,或者需要进行较少的自定义修改,请选择此选项。

    备注

    此处仅为示例。Snowflake 不对以下内容提供支持,也不保证以下内容的准确性。

    要了解更多信息,请参阅 Snowflake Samples GitHub 存储库中的 Cortex Analyst 高级 SiS 演示 (https://github.com/Snowflake-Labs/sf-samples/tree/main/samples/cortex-analyst/Advanced%20SiS%20Demo)。

Cortex Analyst 示例

按照以下步骤在 Snowflake (SiS) 中创建交互式 Streamlit 或使用 Cortex Analyst 的独立 Streamlit 应用程序。

  1. 创建语义模型

  2. 将语义模型上传到暂存区

  3. 在 Snowflake 应用程序中创建并运行 Streamlit

  4. 在 Snowflake 应用程序中与 Streamlit 交互

创建语义模型

语义模型 是一种轻量级机制,通过允许指定关于数据集的附加语义细节来解决与业务用户和数据库定义之间的语言差异相关的问题。这些额外的语义细节(比如更具描述性的名称或同义词),使得 Cortex Analyst 能够更可靠地回答数据问题。

  1. 首先列出您希望 Cortex Analyst 回答的问题。在此基础上,决定语义模型的数据集。

  2. 根据 规范 创建语义模型 YAML。为方便起见,请尝试 使用模型生成器创建语义模型

上传语义模型

您可以将语义模型 YAML 文件上传到 暂存区,或者将语义模型 YAML 作为字符串传递到请求主体中。如果您将语义模型 YAML 上传到暂存区,则对该语义模型的访问受其上传到的暂存区的访问权限控制。这意味着任何能够访问该暂存区的角色都可以访问该暂存区上的语义模型,即使该角色不能访问模型基于的表。确保获授暂存区访问权限的角色具有该暂存区上所有语义模型中引用的所有表的 SELECT 访问权限。

以下示例演示了如何设置包含语义模型的暂存区。组织中的所有成员都可以访问一个暂存区 (public),而另一个暂存区 (sales) 仅供 sales_analyst 角色访问。

为暂存区创建数据库和架构。以下示例创建了一个名为 semantic_model 的数据库,该数据库的架构名为 definition,但您可以对这些名称使用任何有效的标识符字符串。

CREATE DATABASE semantic_model;
CREATE SCHEMA semantic_model.definitions;
GRANT USAGE ON DATABASE semantic_model TO ROLE PUBLIC;
GRANT USAGE ON SCHEMA semantic_model.definitions TO ROLE PUBLIC;

USE SCHEMA semantic_model.definitions;
Copy

然后创建存储语义模型的暂存区:

CREATE STAGE public DIRECTORY = (ENABLE = TRUE);
GRANT READ ON STAGE public TO ROLE PUBLIC;

CREATE STAGE sales DIRECTORY = (ENABLE = TRUE);
GRANT READ ON STAGE sales TO ROLE sales_analyst;
Copy

在 Snowsight 中,您可以刷新页面并在 数据库对象资源管理器 中找到新创建的暂存区。您可以在新选项卡中打开暂存区页面并在 Snowsight 中上传 YAML 文件。

或者,您可以使用 Snowflake CLI 客户端 从本地文件系统上传。

snow stage copy file:///path/to/local/file.yaml @sales
Copy

在 Snowflake 应用程序中创建 Streamlit

此示例向您展示如何在 Snowflake 应用程序中创建 Streamlit,该应用程序以自然语言问题为输入,并根据您提供的语义模型调用 Cortex Analyst 生成答案。

备注

此处仅为示例。Snowflake 不对以下内容提供支持,也不保证以下内容的准确性。

有关在 Snowflake 中创建和运行 Streamlit 应用程序的更多信息,请参阅 关于 Streamlit in Snowflake

  1. 按照 使用 Snowsight 创建 Streamlit 应用程序 中的说明在 Snowsight 中创建新的 Streamlit 应用程序。

  2. 从我们的 GitHub 存储库将 Streamlit 代码 (https://github.com/Snowflake-Labs/sfguide-getting-started-with-cortex-analyst/blob/main/cortex_analyst_sis_demo_app.py) 复制到代码编辑器中。

  3. 用您的账户详细信息替换占位符值。

  4. 要预览该应用程序,请选择 Run 以更新 Streamlit 预览窗格中的内容。

与 Streamlit 应用程序交互

  1. 在浏览器中导航到 Streamlit 应用程序或在 Snowflake 预览窗格中导航到 Streamlit。

  2. 开始用自然语言询问有关数据的问题(例如,“我可以问什么问题?”)。

创建独立的 Streamlit 应用程序

您还可以使用示例代码来构建独立应用程序。

备注

此处仅为示例。Snowflake 不对以下内容提供支持,也不保证以下内容的准确性。

  1. 安装 Streamlit (https://pypi.org/project/streamlit/)。

  2. 在本地创建一个名为 analyst_api.py 的 Python 文件。

  3. 从我们的 GitHub 存储库将 Streamlit 代码 (https://github.com/Snowflake-Labs/sfguide-getting-started-with-cortex-analyst/blob/main/cortex_analyst_streaming_demo.py) 复制到文件中。

  4. 用您的账户详细信息替换占位符值。

  5. 使用 streamlit run analyst_api.py 运行 Streamlit 应用程序。

代码中指定的数据库和架构是语义模型 YAML 文件的暂存区位置。Snowflake 连接器中使用的角色应该能够访问语义模型中定义的基础数据。

有关更全面的实施,请参阅 Snowflake Samples GitHub 存储库中的 Cortex Analyst 高级 SiS 演示 (https://github.com/Snowflake-Labs/sf-samples/tree/main/samples/cortex-analyst/Advanced%20SiS%20Demo)。此存储库配置了各种预构建的功能,能够无缝且稳健地部署 Cortex Analyst。

禁用 Cortex Analyst 功能

如果您不希望 Cortex Analyst 在账户中可用,请通过使用 ACCOUNTADMIN 角色更改 ENABLE_CORTEX_ANALYST 参数来禁用该功能:

USE ROLE ACCOUNTADMIN;
ALTER ACCOUNT SET ENABLE_CORTEX_ANALYST = FALSE;
Copy

参数类型

会话

数据类型

BOOLEAN

描述

控制是否在您的账户中启用 Cortex Analyst 功能。

  • FALSE:Cortex Analyst 功能不可用。

  • TRUE:Cortex Analyst 功能可用。如果 ENABLE_CORTEX_ANALYST_MODEL_AZURE_OPENAI 设置为 TRUE,则 Cortex Analyst 可以使用 Azure OpenAI 模型以及 Snowflake 托管的模型。否则,只能使用 Snowflake 托管的模型。

默认值

TRUE

Cortex Analyst 使用的控制模型

您可以使用模型级 RBAC(基于角色的访问控制)来控制对 Cortex Analyst 所用模型的访问权限。每个模型都受指定的应用程序角色的保护,管理员可以通过这些模型特定角色授予或撤消对特定 LLMs 的访问权限。有关更多信息,请参阅 基于角色的访问控制 (RBAC)

重要

模型级 RBAC 是一项高级功能,适用于那些因特定监管或合规要求而需要明确规定可使用哪些模型以及这些模型托管位置的客户。如果您没有此类要求,Snowflake 建议您不要使用此功能。

您不能直接选择模型。相反,会根据以下因素,Cortex Analyst 将每个请求分配给某个模型或模型组合。

小技巧

不同的模型会产生不同的结果。为了获得一致的结果,请对所有请求使用相同的 Snowflake 区域、跨区域推理配置和模型级 RBAC 限制。

如果您的账户配置为使用现已过时的 Azure OpenAI 账户级别参数,则 Cortex Analyst 将遵循 启用使用 Azure OpenAI 模型(旧版路径) 中概述的逻辑。否则,Cortex Analyst 会使用您的角色可以访问的排名最高的模型,并按照以下优先顺序选择模型。如果您的角色无法访问这些模型,则请求会失败。

  • Anthropic Claude Sonnet 4

  • Anthropic Claude Sonnet 3.7

  • Anthropic Claude Sonnet 3.5

  • OpenAI GPT 4.1

  • Mistral Large 2 和 Llama 3.1 70b 的组合

Cortex Analyst 的模型选择行为可能会不时发生变化,以便利用模型功能的进步。

风险和局限性

Cortex Analyst 取决于至少有一种受支持的模型配置可用。禁用特定模型会减少回退的选项,并增加查询失败的风险。

模型级限制适用于所有可以使用该模型的 Cortex 功能;无法仅在 Cortex Analyst 中或任何其他单个 Cortex 功能中的模型访问权限。

启用使用 Azure OpenAI 模型(旧版路径)

在 Snowflake 托管的 LLMs 模型提供 OpenAI 模型之前,Cortex Analyst 提供了通过 Microsoft Azure 调用来使用 OpenAI 模型的选项。既然 OpenAI 模型已在 Snowflake 托管边界中可用,Snowflake 建议想要使用模型的客户使用 OpenAI 模型的 Snowflake 托管版本,必要时使用 跨区域推理

Snowflake 强烈不鼓励通过本节中描述的账户参数使用 Azure OpenAI 模型。Snowflake 预计将在未来的版本中会弃用对此路径的支持,并建议客户在可行的情况下尽快迁移到 Snowflake 托管的 OpenAI 模型。

您可以将 Snowflake 账户配置为允许使用带有 ENABLE_CORTEX_ANALYST_MODEL_AZURE_OPENAI 账户参数的 Azure OpenAI GPT 模型。默认情况下,该参数处于禁用状态,并且只能由 ACCOUNTADMIN 角色使用 ALTER ACCOUNT 命令设置:

USE ROLE ACCOUNTADMIN;

ALTER ACCOUNT SET ENABLE_CORTEX_ANALYST_MODEL_AZURE_OPENAI = TRUE;
Copy

小技巧

要查看此参数的当前值,请使用以下 SQL 语句。

SHOW PARAMETERS LIKE 'ENABLE_CORTEX_ANALYST_MODEL_AZURE_OPENAI' IN ACCOUNT
Copy

有关更多详细信息,请参阅 ENABLE_CORTEX_ANALYST_MODEL_AZURE_OPENAI 参数

备注

与 Snowflake 托管的模型不同,Azure OpenAI 模型不遵守 RBAC 限制。启用 ENABLE_CORTEX_ANALYST_MODEL_AZURE_OPENAI 账户参数后,Azure OpenAI 模型始终可供使用。如果您使用模型访问控制,请不要启用此参数,因为它与模型级 RBAC 不兼容。

启用此参数后,Cortex Analyst 可能由以下任意组合提供支持:

  • Snowflake 托管模型,目前为 Mistral Large 和 Llama3 模型

  • Azure OpenAI 模型,目前为 GPT-4o(需要显式选择加入)

备注

Cortex Analyst 未来可能会使用不同的模型,从而进一步提高性能和准确性。

注意事项

语义模型文件被分类为 元数据。如果您选择在 Cortex Analyst 中使用 Azure OpenAI 模型,则您的语义模型将由第三方 (Microsoft Azure) 处理。但是,客户数据不会与 Azure 共享,也不会由 Azure 处理。

ENABLE_CORTEX_ANALYST_MODEL_AZURE_OPENAI 参数

ENABLE_CORTEX_ANALYST_MODEL_AZURE_OPENAI 账户参数,如果为 TRUE,则允许 Cortex Analyst 使用 Azure OpenAI 模型。

参数类型

会话

数据类型

BOOLEAN

描述

控制 Cortex Analyst 是否可以使用 Azure OpenAI 模型来处理请求。

  • FALSE:Cortex Analyst 仅使用 Snowflake 托管的模型来处理请求并遵守模型级 RBAC。

  • TRUE:除了 Snowflake 托管的模型之外,Cortex Analyst 还可以使用 Azure OpenAI 模型来处理请求。模型级 RBAC 不可用。

默认值

FALSE

成本注意事项

Cortex Analyst 的 credit 费率使用基于 Snowflake 服务使用表 中列出的已处理消息数量。仅计算成功的响应 (HTTP 200)。每条消息中的词元数量不会影响成本。

备注

上述费用包括文本到 SQL 的 AI 成本。如果执行 Cortex Analyst 生成的 SQL,则会产生额外的仓库成本。

监控 Cortex Analyst 的成本

如需查看 Cortex Analyst 的 Credit 使用情况,请使用 CORTEX_ANALYST_USAGE_HISTORY 视图。例如:

SELECT * FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_ANALYST_USAGE_HISTORY;
Copy

Cortex Analyst 的使用情况也会显示在 ACCOUNT_USAGE 架构的 METERING_HISTORY 视图 中,其中包含 AI_SERVICES 的服务类型。

语言: 中文