按场景调度工作流程¶

场景 A：在专用工作区中进行开发¶

1. 在导航菜单中，选择 Projects » Workspaces。

2. 选择 + Add new » Notebook 以创建新笔记本或打开要计划的现有笔记本。

   备注

   确保已在计划的笔记本中指定执行上下文（数据库和架构）。有关更多信息，请参阅 设置执行上下文。

3. 在笔记本编辑器的顶部，选择 Scheduled runs 。

   • 如果这是笔记本的第一个任务， 图标是一个日历。

   • 如果计划已存在， 图标则变为带时钟的日历。

4. 选择 Create Schedule。

5. 在 Schedule a Notebook Task 对话框中，填写以下信息：

   基本设置

   • 任务名称： 计划任务的唯一名称。默认名称为 {notebook-name}_task_#，如有需要可进行修改。

   • 所有者角色： 执行任务所使用的 Snowflake 角色。请选择具有执行计划笔记本所有操作所需权限的角色。该角色必须具备以下权限：

     • 读取/写入笔记本使用的数据库对象。

     • 访问仓库、计算池和集成。

     • 创建/更新任务和项目对象。

   • 位置： 任务对象及其关联笔记本项目对象将创建所在的数据库和架构。请选择您的角色在其中具有 CREATE TASK 和 USAGE 权限的架构。如果您的角色只有架构的 USAGE 权限，确保它也具有 CREATE NOTEBOOK PROJECT 权限。

   • 频率： 笔记本的运行频率。可选择以下频率：每小时、每天、每周、每月或自定义（Cron 计划）。所有执行时间均以您的本地时区为准。

   高级设置（除非另有说明，否则所有字段均为必填）

   • 笔记本项目名称： Snowflake 为任务执行创建的笔记本项目容器的唯一名称。若未修改，Snowflake 会使用默认名称。

   • 参数（可选）： 在运行时传递给笔记本的键值参数，会以命令行实参形式（在 sys.argv 中）出现。参数可用于传递日期、环境标志、阈值或模型版本等信息。参数可以通过以下方式传入：在 Snowsight 中以空格分隔的值传递，或在 EXECUTE NOTEBOOK PROJECT 命令中以 ARGUMENTS = 'env prod' 形式传递。有关更多信息，请参阅 带参数运行笔记本。

   • 运行时变体： 用于笔记本执行的运行时环境。可选择以下频率：

     • CPU: 使用 CPU 容器运行时环境，并在 CPU 计算池（例如，自动配置的 SYSTEM_COMPUTE_POOL_CPU）上运行。

     • GPU 使用包含 GPU 加速库的 GPU 容器运行时环境，并在 GPU 计算池（例如 SYSTEM_COMPUTE_POOL_GPU）上运行。

     • Python 版本： 任务执行时使用的 Python 版本。

     • 运行时版本： 基础容器运行时镜像。选择正确的运行时版本，可确保您的笔记本在开发环境与计划执行任务之间保持运行一致性。

   • 计算池： 执行笔记本任务的计算池。确保计算池在计划执行时具有足够容量（空闲节点）。为避免计划运行失败，建议您使用专用计算池，确保没有其他 SPCS 服务占用全部容量。

   • 查询仓库： 用于处理笔记本中所有 SQL 查询的 Snowflake 仓库。

   • 外部访问集成（可选）： 定义笔记本可使用的外部访问集成 (EAIs)。如果您的笔记本需要访问外部 APIs、第三方服务或 Snowflake 内部暂存区之外的云存储，则必须配置 EAIs。如果列表中未显示 EAIs，说明您当前所选角色不拥有任何集成，或没有相关权限。

   • 要求文件（可选）： 使用以下命令预安装 Python 依赖项，以便可使用 REQUIREMENTS_FILE 参数重复运行。有关更多信息，请参阅 管理包和运行时。

6. 检查计划预览，然后选择 Create。

场景 B：生产 (CI/CD)¶

对于生产环境，我们建议在基于 Git 的工作区中管理笔记本代码（有关详细信息，请参阅 将工作区与 Git 存储库集成），或在您首选的 IDE 中进行本地开发。您可以使用 CI/CD 管道（例如 GitHub 操作），将文件部署到 Snowflake 内部或临时暂存区。

文件进入暂存区后，您可以执行以下操作：

• 创建一个源自该存储位置路径的笔记本项目对象 (NPO)。

• 使用 Snowflake 任务计划 NPO 以实现自动化执行。

1. 创建暂存区

   使用 CREATE STAGE 创建内部或临时暂存区：

   -- Ensure the landing zone exists
   CREATE STAGE IF NOT EXISTS <database_name>.<schema_name>.<stage_name>;
   

   Copy

2. 将笔记本文件加载/部署到内部或临时暂存区

   您的 CI/CD 管道应将 .ipynb 文件上传到 Snowflake 暂存区。使用 PUT 命令，以确保笔记本文件加载到笔记本项目可读的暂存区中。

   PUT file://<absolute_path_to_file>/ @<database_name>.<schema_name>.<stage_name> AUTO_COMPRESS=FALSE OVERWRITE=TRUE;
   

   Copy

   示例：

   PUT file://notebooks/ml_model/train.ipynb @<database_name>.<schema_name>.<stage_name> AUTO_COMPRESS=FALSE OVERWRITE=TRUE;
   

   Copy

3. 创建或更新笔记本项目对象 (NPO)

   创建（或更新）NPO 以引用包含已部署的笔记本文件的内部或临时暂存区：

   CREATE NOTEBOOK PROJECT IF NOT EXISTS <database_name>.<schema_name>.<project_name>
     FROM '@<database_name>.<schema_name>.<stage_name>';
   

   Copy

4. 更改笔记本项目详细信息

   对于后续代码更改，管道会执行 ALTER 命令。这会将项目更新到最新版本的代码，而无需删除并重新创建对象：

   -- Update the project with the latest code from the stage
   ALTER NOTEBOOK PROJECT <database_name>.<schema_name>.<project_name>
     ADD VERSION FROM '@<database_name>.<schema_name>.<stage_name>';
   

   Copy

5. 执行笔记本项目（通过任务编排）

   创建任务以计划和执行 NPO。使用 Snowflake 任务定义 NPO 的计划和执行参数。

   备注

   确保指定笔记本执行上下文（使用要计划的笔记本的数据库和架构）。有关更多信息，请参阅 设置执行上下文。

   -- Create or replace the task to orchestrate the notebook
   CREATE OR REPLACE TASK <database_name>.<schema_name>.<task_name>
     WAREHOUSE = '<warehouse_name>'
     SCHEDULE = 'USING CRON 0 9 * * * America/Los_Angeles'
   AS
     EXECUTE NOTEBOOK PROJECT <database_name>.<schema_name>.<project_name>
       MAIN_FILE = 'snow://workspace/<workspace_hash>/path/to/notebook.ipynb'
       COMPUTE_POOL = 'SYSTEM_COMPUTE_POOL_CPU'
       RUNTIME = 'V2.2-CPU-PY3.12'
       QUERY_WAREHOUSE = '<warehouse_name>'
       ARGUMENTS = '<db_name> <schema_name> <warehouse_name>';
   

   Copy

   有关将参数传递给计划笔记本的信息，请参阅 带参数运行笔记本。

6. 查看笔记本运行或执行历史记录

   任务运行后，您可以在 Snowsight 中监控其成功或失败状态，以确保 CI/CD 部署按预期运行。有关查看运行历史记录的详细说明，请参阅 查看计划的笔记本运行。

Snowsight 支持笔记本的非交互式（无头）执行。这允许您触发笔记本的程序化运行，而无需打开 Snowsight，也不需要定期计划。

无头执行适用于任务、计划任务或由 Airflow、Prefect、Dagster、CI/CD 管道等工具或需要以编程方式执行笔记本的外部系统编排的工作流。有关更多信息，请参阅 CREATE NOTEBOOK PROJECT。