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 文件中捕获，语义模型的整体结构和概念与数据库架构相似，但允许对数据相关的语义信息进行更丰富的描述。
安全与治理。 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 角色的角色。

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

权限	对象
USAGE	如果语义模型上传到暂存区，则为包含语义模型 YAML 文件的暂存区。
USAGE	语义模型中提到的 Cortex Search 服务。
SELECT	语义模型中提到的表。

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

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

限制访问特定角色¶

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

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

区域可用性¶

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

AWS ap-northeast-1（东京）
AWS ap-southeast-2（悉尼）
AWS us-east-1（弗吉尼亚）
AWS us-west-2（俄勒冈）
AWS eu-central-1（法兰克福）
AWS eu-west-1（爱尔兰）
Azure 东部 US 2（弗吉尼亚）
Azure 欧洲西部（荷兰）

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

已知问题和限制¶

如果您将语义模型 YAML 文件上传到暂存区，则对该语义模型的访问受其上传到的暂存区的访问权限控制。这意味着任何能够访问该暂存区的角色都可以访问该暂存区上的语义模型，即使该角色不能访问基础表。
默认情况下，Cortex Analyst 速率限制为每分钟 20 个请求，这个数量对于概念验证应该已经足够。请联系您的销售工程师，申请更高的限额。

启用 Azure OpenAI 模型¶

默认情况下，Cortex Analyst 由 Snowflake 托管的 Cortex LLMs 提供支持。但是，您可以显式选择允许 Cortex Analyst 使用 Microsoft Azure 托管的最新 OpenAI GPT 模型，以及 Snowflake 托管的模型。在运行时，Cortex Analyst 会选择最佳模型组合，以确保每个查询都具有最高准确性和性能。

备注

如果您选择使用 Azure OpenAI 模型，则 Cortex Analyst 可在所有 AWS、Azure 和 GCP 区域中使用，但政府和 VPS 部署除外。

您可以将账户配置为允许使用带有 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。

启用此参数后，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 托管的模型来处理请求。 TRUE：除了 Snowflake 托管的模型之外，Cortex Analyst 还可以使用 Azure OpenAI 模型来处理请求。
默认值	FALSE

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 版本可能会解决以下某些限制。

访问先前 SQL 查询的结果: Cortex Analyst 无法访问先前 SQL 查询的结果。例如，如果您先问“我的产品有哪些？”，然后问“第二个产品的收入是多少？”，那么，Cortex Analyst 无法参考第一个查询中的产品列表来获取第二个产品。
一般业务见解: Cortex Analyst 只能回答可以通过 SQL 解决的问题。它不会针对更广泛的业务相关查询生成见解，例如“您观察到什么趋势？”
长对话: 如果对话包含太多轮或用户频繁改变意图，则 Cortex Analyst 可能难以解读后续问题。在这种情况下，请重置对话并重新开始。

开始使用选项¶

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

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

如果您希望从基本的基础示例开始，能够轻松使用 Streamlit 并进行修改，请选择此选项。您可以在 Streamlit in Snowflake (SiS) 或本地运行此示例。
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 应用程序。

创建语义模型
将语义模型上传到暂存区
在 Snowflake 应用程序中创建并运行 Streamlit
在 Snowflake 应用程序中与 Streamlit 交互

创建语义模型¶

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

首先列出您希望 Cortex Analyst 回答的问题。在此基础上，决定语义模型的数据集。
根据规范创建语义模型 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。

按照使用 Snowsight 创建 Streamlit 应用程序中的说明在 Snowsight 中创建新的 Streamlit 应用程序。
从我们的 GitHub 存储库将 Streamlit 代码 (https://github.com/Snowflake-Labs/sfguide-getting-started-with-cortex-analyst/blob/main/cortex_analyst_sis_demo_app.py) 复制到代码编辑器中。
用您的账户详细信息替换占位符值。
要预览该应用程序，请选择 Run 以更新 Streamlit 预览窗格中的内容。

与 Streamlit 应用程序交互¶

在浏览器中导航到 Streamlit 应用程序或在 Snowflake 预览窗格中导航到 Streamlit。
开始用自然语言询问有关数据的问题（例如，“我可以问什么问题？”）。

创建独立的 Streamlit 应用程序¶

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

备注

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

安装 Streamlit (https://pypi.org/project/streamlit/)。
在本地创建一个名为 analyst_api.py 的 Python 文件。
从我们的 GitHub 存储库将 Streamlit 代码 (https://github.com/Snowflake-Labs/sfguide-getting-started-with-cortex-analyst/blob/main/cortex_analyst_streamlit.py) 复制到文件中。
用您的账户详细信息替换占位符值。
使用 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 的 credit 费率使用基于 Snowflake 服务使用表中列出的已处理消息数量。仅计算成功的响应 (HTTP 200)。每条消息中的词元数量不会影响成本。

备注

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

法律声明¶

Cortex Analyst 由机器学习技术（包括 Meta 的 Llama 3 和 Mistral Large 模型）提供支持。基础 Llama 3 模型根据 Llama 3 (https://llama.meta.com/llama3/license/) 社区许可获得许可，版权归 Meta Platforms, Inc. 所有。保留所有权利。您对此功能的使用受 Meta 的可接受使用政策 (https://ai.meta.com/llama/use-policy/) 约束。

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

输入 Data Classification	输出 Data Classification	名称
Usage Data	Usage Data	Preview AI Features [1]

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