cortex-classify-notebook

用途

该技能用于把 Cortex CLASSIFY_TEXT 教程笔记本部署到用户的 Snowflake 账户，并提供一个在 Snowsight 中打开该笔记本的直接链接。当用户想学习文本分类（CLASSIFY_TEXT）时使用。

主要能力

获取最新官方文档，确保语法与说明为当前版本。
检测或设置目标环境，优先使用 SNOWFLAKE_LEARNING 环境。
创建以当前用户命名的 schema。
创建内部 stage 用于存放笔记本文件。
上传教程笔记本到 Snowflake stage。
在用户账户中创建笔记本。
生成在 Snowsight 中打开笔记本的直接链接。

使用方式（部署流程）

技能会先简短欢迎用户，然后高效推进各步骤并保持用户知情，不在每一步请求确认。

步骤 0：获取最新文档（始终先执行） 使用 web_fetch 获取当前官方文档：

https://docs.snowflake.com/en/sql-reference/functions/classify_text-snowflake-cortex
https://docs.snowflake.com/en/user-guide/ui-snowsight/notebooks

步骤 1：环境检测与设置 并行运行两个查询：

SHOW ROLES LIKE 'SNOWFLAKE_LEARNING_ROLE';

并读取 assets/classify_unstructured_customer_reviews.ipynb。

若 SNOWFLAKE_LEARNING_ROLE 存在（首选）：

USE ROLE SNOWFLAKE_LEARNING_ROLE;
USE DATABASE SNOWFLAKE_LEARNING_DB;
USE WAREHOUSE SNOWFLAKE_LEARNING_WH;

若不可用（回退）：

USE ROLE ACCOUNTADMIN;
CREATE DATABASE IF NOT EXISTS CORTEX_TUTORIALS_DB;
USE DATABASE CORTEX_TUTORIALS_DB;
CREATE WAREHOUSE IF NOT EXISTS CORTEX_TUTORIALS_WH WITH WAREHOUSE_SIZE = 'XSMALL';
USE WAREHOUSE CORTEX_TUTORIALS_WH;

步骤 2：创建用户 schema 与 stage

SET schema_name = CONCAT(CURRENT_USER(), '_CORTEX_TUTORIALS');
CREATE SCHEMA IF NOT EXISTS IDENTIFIER($schema_name);
USE SCHEMA IDENTIFIER($schema_name);
CREATE STAGE IF NOT EXISTS notebook_stage
    DIRECTORY = (ENABLE = TRUE)
    ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE');

步骤 3：捕获环境信息（关键） 设置环境后必须查询实际值，不要根据本地用户名猜测 schema 名：

SELECT 
    CURRENT_USER() as current_user,
    CURRENT_SCHEMA() as current_schema, 
    CURRENT_DATABASE() as current_database,
    CURRENT_ROLE() as current_role

步骤 4：上传笔记本文件到 stage

snow stage copy <local_notebook_path> @<DATABASE>.<SCHEMA>.notebook_stage --overwrite --connection <connection_name>

本地路径为相对技能基础目录的 assets/classify_unstructured_customer_reviews.ipynb，始终使用 --overwrite 以支持重复部署。

步骤 5：创建笔记本

CREATE OR REPLACE NOTEBOOK <DATABASE>.<SCHEMA>.CLASSIFY_CUSTOMER_REVIEWS
    FROM '@<DATABASE>.<SCHEMA>.notebook_stage'
    MAIN_FILE = 'classify_unstructured_customer_reviews.ipynb'
    COMMENT = 'Tutorial: Classify customer reviews with Cortex AI';

步骤 6：生成 Snowsight URL

SELECT CURRENT_ORGANIZATION_NAME() || '-' || CURRENT_ACCOUNT_NAME() as account_identifier

URL 格式：

https://app.snowflake.com/{ORG}/{ACCOUNT}/#/notebooks/{DATABASE}.{SCHEMA}.CLASSIFY_CUSTOMER_REVIEWS

笔记本内容

加载示例数据：来自 Tasty Bytes 餐车的客户评论。
用 Python 分类文本：对单个字符串和 DataFrame 使用 cortex.classify_text()。
用 SQL 分类文本：在查询中直接使用 SNOWFLAKE.CORTEX.CLASSIFY_TEXT()。
分析结果：根据评论判断客户是否愿意推荐餐车。

运行教程：打开 Snowsight 链接，点击 Run All 执行所有单元格，查看分类结果（Likely、Unlikely 或 Unsure）。

适用场景

用户希望学习 Snowflake Cortex 的文本分类功能。
用户需要将官方教程笔记本部署到自己的 Snowflake 账户并直接打开。

限制与问题处理

Schema 名不匹配：始终在设置后查询 CURRENT_SCHEMA() 获取实际 schema 名，不要假设与本地 OS 用户名一致。
Stage 复制失败：确认 stage 路径使用全限定名 @DATABASE.SCHEMA.stage_name，连接参数与用户活动连接一致，角色对 stage 有 WRITE 权限。
笔记本已存在：默认使用 CREATE OR REPLACE NOTEBOOK，可自动处理。
权限不足：检查是否有 schema 上的 CREATE NOTEBOOK 权限，建议使用 SNOWFLAKE_LEARNING_ROLE，必要时回退到 ACCOUNTADMIN。
Cortex 不可用：检查 Cortex 区域可用性，确认账户已启用 Cortex。

参考材料

assets/classify_unstructured_customer_reviews.ipynb：要部署的笔记本文件。
笔记本教授将客户评论分类为 Likely、Unlikely、Unsure 三类。