> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siflow.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 JupyterLab 开发环境

> 在人工智能平台中创建、打开和管理 JupyterLab 开发环境，用于 Notebook 交互式开发、数据探索和调试验证。

JupyterLab 开发环境用于在浏览器中进行 Notebook 交互式开发。您可以按需选择算力、镜像、Volume、数据集和模型，创建独立的云端开发环境，用于数据探索、Notebook 实验、代码调试和小规模验证。

JupyterLab 仅提供浏览器访问方式，不提供 SSH 登录。如需通过本地 VS Code、Cursor 或 SSH 连接云端环境，请使用 VSCS 开发环境。

## 创建 JupyterLab 开发环境

### 1. 进入创建页

1. 进入 **开发环境 > JupyterLab**。
2. 单击 **新建**。

### 2. 填写配置信息

#### 基本信息

| 配置项     | 说明                                                                                  |
| ------- | ----------------------------------------------------------------------------------- |
| 区域和集群   | 决定开发环境运行位置。选定后，资源规格、镜像、Volume、数据集和模型等可选项会随之变化。建议选择与数据、模型和算力资源相同或相近的集群，减少跨区域读取带来的延迟。 |
| 名称      | 用于在列表和详情中识别开发环境。名称需符合平台校验规则；如果提交时提示名称冲突，请更换名称后重试。                                   |
| 项目组     | 指定开发环境所属项目组。                                                                        |
| 在项目组内公开 | 控制项目组内其他用户是否可以在列表中查看该开发环境。公开后，管理操作仍由创建者执行。                                          |

#### 资源信息

| 配置项   | 说明                                                                        |
| ----- | ------------------------------------------------------------------------- |
| 资源类型  | 选择 **预留实例**、**按量实例** 或 **Spot**。不同资源类型会影响资源来源和计费方式。                       |
| 实例    | 如果使用 **预留实例**，选择 **共享资源池** 或 **专属资源池**。                                   |
| 实例类型  | 选择 **GPU** 或 **CPU**。数据探索、轻量脚本调试通常可选择 CPU；需要运行模型训练、推理验证或 GPU 加速任务时选择 GPU。 |
| 资源规格  | 在实例列表中选择规格，并配置单节点实例规格数。提交时平台会校验资源配额；如果提示配额不足，可减少规格数、更换规格或联系管理员扩容。         |
| 资源优先级 | 选择多个实例规格时，按优先级从高到低排序。调度时优先使用排在前面的实例规格。                                    |

#### 环境信息

| 配置项 | 说明                                                                                                                                                                                                                                                                                                            |
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 镜像  | 选择 **内置**、**自定义** 或 **镜像地址**，决定开发环境内的系统环境、依赖库和工具链。使用自定义镜像或镜像地址时，请确认镜像内包含 `bash` 和 JupyterLab 相关组件。                                                                                                                                                                                                            |
| 存储  | 选择需要挂载的 Volume，并填写 Pod 中挂载路径。Volume 和挂载路径需成对配置，可添加多条存储挂载。挂载时关注：<ul><li>挂载路径建议使用 `/volume`、`/mnt` 等开头的目录。</li><li>避免覆盖根目录、`/opt`、`/workspace`、`/usr` 等镜像默认目录。</li><li>需要保留代码、Notebook、输出结果、模型文件或安装后的依赖时，请挂载 Volume，并将重要文件写入 Volume 路径。</li><li>容器本地盘容量有限，写入大量数据可能导致负载被系统驱逐；开发环境重启或迁移后，写入本地盘的数据可能被清空。</li></ul> |
| 数据集 | 选择需要挂载的数据集，可按需挂载子目录。数据集通常作为只读输入使用。                                                                                                                                                                                                                                                                            |
| 模型  | 选择需要挂载的模型，可按需挂载子目录。模型通常作为只读输入使用。                                                                                                                                                                                                                                                                              |
| 命令  | 输入 shell 命令，在 JupyterLab 启动前执行，适合设置环境变量、准备目录或启动轻量后台服务。如果命令无效或执行失败，可能导致 JupyterLab 无法启动。                                                                                                                                                                                                                       |

#### 高级配置

| 配置项  | 说明                                                               |
| ---- | ---------------------------------------------------------------- |
| 环境变量 | 以键值对形式添加环境变量，供启动命令、Notebook 或开发环境内程序读取，常用于配置项、路径或凭据。敏感信息需谨慎使用。   |
| 时区   | 配置开发环境时区，默认 `Asia/Shanghai`，会影响日志时间戳、定时启停时间和程序本地时间。              |
| 默认目录 | 配置打开 JupyterLab 后默认进入的目录。建议设置为常用工作目录或 Volume 挂载路径，避免每次打开后逐级切换目录。 |

### 3. 提交创建

单击 **新建** 提交。开发环境会异步创建，您可以在列表中查看状态变化。

## 打开和保存工作内容

### 打开 JupyterLab

1. 进入 **开发环境 > JupyterLab**。
2. 在列表中找到目标开发环境。
3. 确认开发环境处于运行中状态。
4. 单击 **打开**。
5. 进入 JupyterLab 后，确认默认目录、Volume、数据集或模型挂载路径符合预期。

进入 JupyterLab 后，可以新建 Notebook、脚本、终端或控制台。打开后的默认位置由创建时配置的默认目录决定。

<img src="https://mintcdn.com/siflow/avekptrv6O-LsLPz/ai-platform/development/media/open-jupyterlab-development-environment.png?fit=max&auto=format&n=avekptrv6O-LsLPz&q=85&s=306713cc5f2155bf78ef082c95e2fca1" alt="在浏览器中打开 JupyterLab 开发环境" width="1440" height="900" data-path="ai-platform/development/media/open-jupyterlab-development-environment.png" />

### 保存工作内容

需要长期保留的 Notebook、代码、输出结果和中间文件，应保存到已挂载的 Volume 路径下。数据集和模型建议作为输入读取，训练产物和分析结果写入 Volume，避免输入和输出混在同一路径中。

建议为团队或项目约定稳定的挂载路径。例如将项目代码和输出结果放在 Volume 路径下，将数据集和模型作为只读输入路径使用。这样 Notebook、脚本和训练命令可以复用固定路径，减少因路径变化导致的调试成本。

挂载目录不要相互重叠，也不要覆盖镜像中的系统关键目录。如果需要使用同一个 Volume 支撑多个开发环境，可按项目、实验或成员划分子目录，避免相互覆盖。

## 查看和管理开发环境

### 查看配置、事件和监控

详情页用于确认开发环境配置、生命周期事件和资源用量。开发环境创建、启动、停止、重启或访问异常时，建议先进入详情页查看状态、事件和停止原因。

* **基本配置**：查看资源规格、区域、集群、所有者、创建时间、更新时间、项目组和可见性等信息。
* **资源信息**：查看资源池、用户选择的实例规格、实际使用规格和所在节点。
* **环境信息**：查看时区、镜像、镜像地址、挂载的存储、数据集、模型、环境变量、启动命令和默认目录。
* **事件**：查看开发环境调度、启动、异常和生命周期变化，适合排查创建失败、启动失败、卷挂载失败等问题。
* **监控**：查看开发环境的 CPU、内存、GPU 等资源用量曲线，用于判断资源是否够用或是否长期闲置。

如果开发环境未进入运行中状态，先查看事件和停止原因，再根据提示检查资源配额、镜像组件、卷挂载路径、启动命令或环境变量。

### 管理生命周期

创建后，您可以在列表或详情页对 JupyterLab 开发环境执行生命周期管理操作。

* **更新**：修改镜像、资源规格、Volume 挂载、数据集或模型挂载、启动命令、环境变量等配置。部分变更需要重启后才能生效。
* **启动**：将已停止的开发环境重新拉起。启动时会重新申请算力并进行调度。
* **停止**：关闭运行中的开发环境并释放算力。开发环境配置和已写入 Volume 的数据会保留。
* **重启**：重启会中断开发环境内正在运行的 Notebook、脚本或终端进程。原地重启通常用于重置运行进程；重调度重启会重新校验资源并重新调度，可能被分配到其他节点。
* **保存镜像**：将运行中的开发环境保存为自定义镜像，便于后续复用已安装的依赖和工具。保存期间开发环境会暂时不可用，建议在无交互操作时执行。
* **调整可见性**：将开发环境设置为私有或项目组内公开。调整可见性不影响运行状态。
* **删除**：移除开发环境记录并释放占用资源。删除为不可逆操作，删除前请确认需要保留的数据已保存到 Volume。

重启前请保存 Notebook 和终端中的未提交内容。删除或重建开发环境前，请确认重要文件已写入 Volume；仅保存在容器本地盘中的文件可能无法恢复。

## 配置闲置回收

JupyterLab 开发环境长时间运行会持续占用算力。您可以按使用习惯配置定时启停或自动缩容，减少闲置资源占用。

### 定时启停

定时启停用于按周期性时间规则自动启动或停止开发环境，适合固定工作时间的开发场景。例如工作日前自动启动、夜间自动停止，让算力集中在实际使用时段。

配置定时启停时，请关注开发环境时区，避免计划触发时间与预期不一致。定时计划可以与手动启停并用；计划外需要使用时仍可手动启动，后续计划会在下一个触发点继续生效。

### 按 GPU 利用率自动缩容

按 GPU 利用率自动缩容用于回收长时间闲置的 GPU 算力。当 GPU 利用率在设定观测时长内持续低于阈值时，平台会自动停止开发环境并释放 GPU。

配置自动缩容时，需要关注观测时长、GPU 利用率阈值和策略类型。策略类型用于决定按观测期内的最大值或平均值判断是否闲置。自动缩容触发后不会自动重新启动开发环境；需要继续使用时，请手动启动，或配合定时启停计划启动。对需要长时间保留 GPU 会话的开发环境，请调高阈值或关闭自动缩容，避免误停正在进行的工作。

## 使用 JupyterLab 调试分布式任务

如果需要在 Notebook 环境中临时验证分布式训练脚本，可以创建多个 JupyterLab 开发环境，并在各环境终端中使用同一主节点地址和端口运行 `torchrun`。主节点地址可在主节点环境中通过 `echo $POD_IP` 获取。

```bash theme={null}
# 主节点
torchrun --master_addr <主节点 POD_IP> --master_port 23457 \
  --nnodes 2 --nproc_per_node 1 --node_rank 0 trainer.py

# 其他节点
torchrun --master_addr <主节点 POD_IP> --master_port 23457 \
  --nnodes 2 --nproc_per_node 1 --node_rank 1 trainer.py
```

各节点的 `--master_addr`、`--master_port`、`--nnodes` 和 `--nproc_per_node` 需要保持一致，`--node_rank` 按节点顺序分别设置。正式的大规模训练、需要队列调度或需要更稳定容错能力时，建议使用训练任务。

## 排查常见问题

<AccordionGroup>
  <Accordion title="开发环境长时间排队或创建失败怎么办？">
    查看事件和状态详情，确认所选资源规格、用户剩余配额和资源池可用量是否满足要求。配额不足时，可减少规格数、更换规格或联系管理员扩容。
  </Accordion>

  <Accordion title="JupyterLab 打不开或反复重启怎么办？">
    检查镜像是否包含 `bash` 和 JupyterLab 相关组件，并查看启动命令和环境变量是否会导致进程退出。
  </Accordion>

  <Accordion title="Volume、数据集或模型路径不可用怎么办？">
    确认挂载对象与 Pod 中挂载路径已成对配置，挂载路径没有覆盖系统目录，也没有与其他挂载路径冲突。
  </Accordion>

  <Accordion title="重启或迁移后文件丢失怎么办？">
    确认文件是否写入 Volume。容器本地盘不适合保存重要代码、数据和输出结果。
  </Accordion>
</AccordionGroup>

## 相关文档

* [创建和使用存储卷](../resources/create-and-use-storage-volumes)
* [在开发环境和训练任务中挂载数据集](../datasets/mount-datasets-in-workloads)