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、自定义聊天界面等。
Powered by state-of-the-art large language models: By default, Cortex Analyst is powered by industry-leading models which run securely inside Snowflake Cortex, Snowflake's intelligent, fully managed AI service. At runtime, Cortex Analyst selects the best combination of models to ensure the highest accuracy and performance for each query. As LLMs evolve, Snowflake may add more models to the mix to further improve performance and accuracy.
高精度和准确性的语义模型： 当仅给出数据库架构时，通用 AI 解决方案通常难以进行文本到 SQL 转换，因为架构缺乏业务流程定义和指标处理等关键知识。Cortex Analyst 通过使用语义模型来弥合业务用户和数据库之间的鸿沟，克服了这一限制。在轻量级 YAML 文件中捕获，语义模型的整体结构和概念与数据库架构相似，但允许对数据相关的语义信息进行更丰富的描述。

如果您设置 Cortex Analyst 来回答来自大量数据源的问题，则 Cortex Analyst 可以自动找出要使用哪个数据源的问题。您不必担心为每个查询指定正确的查询。
安全与治理。 Snowflake 的隐私优先基础和企业级安全性可确保您可以放心探索 AI 驱动型用例，因为您知道数据受到了最高隐私和治理标准的保护。
- Cortex Analyst 不使用客户数据进行训练。我们不会使用客户数据来训练或微调任何模型以供我们的客户群使用。此外，对于推理，Cortex Analyst 仅会利用语义模型 YAML 文件中提供的元数据（例如，表名、列名、值类型、描述等）进行 SQL 查询生成。然后，在 Snowflake 虚拟仓库中执行此 SQL 查询以生成最终输出。
- Data stays within Snowflake's governance boundary. By default, Cortex Analyst is powered by Snowflake-hosted LLMs from Mistral and Meta, ensuring that no data, including metadata or prompts, leaves Snowflake's governance boundary.
- 与 Snowflake 的隐私和治理功能无缝集成。Cortex Analyst 与 Snowflake 的基于角色的访问控制 (RBAC) 策略完全集成，确保生成和执行的 SQL 查询符合所有确立的访问控制。这保证了数据的强大安全性和治理能力。

访问控制要求¶

To make requests to Cortex Analyst, use a role with either the SNOWFLAKE.CORTEX_USER or SNOWFLAKE.CORTEX_ANALYST_USER database role. CORTEX_USER provides access to all Covered AI features, while CORTEX_ANALYST_USER provides access only to Cortex Analyst. For information about Covered AI features, see 法律声明.

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

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

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

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

限制访问特定角色¶

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

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

Limiting access using the Cortex Analyst user role¶

To provide selective access to Cortex Analyst for specific users, use the SNOWFLAKE.CORTEX_ANALYST_USER database role. This role includes the privileges needed to call the Cortex Analyst API. For more information about Covered AI features, see 法律声明.

重要

If your user roles have the CORTEX_USER role, you must revoke access to the CORTEX_USER role. To revoke the CORTEX_USER database role from your user roles, run the following command using the ACCOUNTADMIN role:

REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER FROM ROLE analyst;

Copy

To provide access to Cortex Analyst, use the ACCOUNTADMIN role to do the following:

Grant the SNOWFLAKE.CORTEX_ANALYST_USER database role to a custom role.
Assign this custom role to users.

备注

You can't grant database roles directly to users. For more information, see GRANT DATABASE ROLE.

以下示例：

Creates the custom role, cortex_analyst_user_role.
Grants it the CORTEX_ANALYST_USER database role.
Assigns this role to 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

You can also grant access to Cortex Analyst through existing roles. For example, if you have an analyst role used by analysts in your organization, you can grant access with a single GRANT statement:

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：

基本代码示例：下一节中的 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_streaming_demo.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 functionality is available.
默认值	TRUE

Cortex Analyst 使用的控制模型¶

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

重要

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

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

您的 Snowflake 区域 <label-cortex_llm_availability> ` 中可用的模型 :ref:`。
账户的跨区域推理配置。
您建立的任何模型级 RBAC 限制。

小技巧

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

Cortex Analyst selects models in the following order of preference, using the highest-ranked model to which your role has access. If your role has access to none of these models, the request fails.

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 功能中的模型访问权限。

成本注意事项¶

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 的服务类型。

法律声明¶

如果 Cortex Analyst 配置使用模型和服务流程条款中提供的模型，则您对该模型的使用将进一步受该页面上该模型的条款的约束。

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

输入 Data Classification	输出 Data Classification	名称
Usage Data	输出（SQL 查询建议）：使用情况数据查询结果（使用 SQL 查询建议）：客户数据	Covered AI Features [1]

输入 Data Classification

输出 Data Classification

名称

Usage Data

输出（SQL 查询建议）：使用情况数据

查询结果（使用 SQL 查询建议）：客户数据

Covered AI Features [1]

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