#创建工作台

#前提条件

• 确保已配置 kubectl 并连接到集群。
• 确保已创建 PVC。

#使用 Web 控制台创建工作台

#操作步骤

#连接到工作台

创建工作台实例后，点击左侧导航栏中的 Workbench；你的工作台实例应会显示在列表中。当状态变为 Running 时，点击 Connect 按钮进入工作台。

#在 JupyterLab 中上传文件

如果你使用基于 JupyterLab 的工作台，可以通过文件浏览器中的 Upload Files 按钮从本地机器上传文件。当工作台无法访问公共互联网或 PyPI 镜像，且需要从本地 wheel 文件安装 Python 包时，此功能非常有用。

#离线安装 Python Wheel 文件

1. 连接到工作台并打开 JupyterLab。

2. 在左侧文件浏览器中，点击 Upload Files 按钮，并从本地机器选择一个或多个 .whl 文件。

3. 在 JupyterLab 中打开终端，并进入包含已上传文件的目录。

4. 安装该包：

   pip install ./your_package-1.0.0-py3-none-any.whl

如果该包依赖其他 wheel 文件，请将所有必需的 .whl 文件上传到同一目录，并在不访问外部包索引的情况下安装它们：

pip install --no-index --find-links . your-package

#可用的工作台镜像

该平台提供了一组可直接用于的 WorkspaceKind 镜像，这些镜像会直接出现在工作台创建表单中。其他镜像也会发布到 Docker Hub，但默认不会同步到平台中。

下表采用与 Red Hat OpenShift AI 文档相同的通用风格：每个镜像都说明了其适用场景，并列出关键的预装包，便于快速参考。包列表仅代表常见项，不是完整清单。版本信息来自构建仓库中对应的镜像目录及其相关 lock 文件。

#内置镜像

以下镜像开箱即用：

#多架构镜像（x86_64 和 arm64）

#额外镜像

以下镜像可在 Docker Hub 上获取，但默认不内置到平台中：

#x86_64 镜像

这些镜像适用于支持 NVIDIA GPU 的 x86_64 节点。

#arm64 镜像

这些镜像适用于支持 Ascend NPU 的 arm64 节点。

要使用额外镜像，首先需要将其同步到你自己的镜像仓库。你可以使用 skopeo 等工具，或者使用下一节所述的脚本来完成。

#Docker Hub 镜像同步脚本指南

sync-from-dockerhub.sh 是一个自动化工具，用于将选定的 Docker Hub 镜像，尤其是超大镜像，同步到私有镜像仓库（例如 Harbor）。 由于网络波动，大镜像在直接传输时更容易出现内存不足（OOM）或超时失败。为了提高可靠性，该脚本采用中继流程：先拉取到本地 → 导出为 tar 归档 → 再将 tar 归档推送到目标仓库。此外，它会在任务完成或意外退出时自动清理临时文件。

#脚本前提条件

在运行此脚本之前，请确保执行机器上已安装并可访问以下工具：

• bash（执行环境）
• nerdctl（用于拉取镜像并将镜像层导出为 tar 归档）
• skopeo（用于将 tar 镜像归档推送到目标私有仓库）

#环境变量配置

脚本通过读取环境变量执行同步，因此无需修改代码即可灵活使用。

#必需参数（目标私有仓库配置）

#可选参数（源 DockerHub 配置）

为避免在拉取大量镜像时触发 DockerHub 的速率限制，你可以提供 DockerHub 凭据，以便在拉取前先登录。如果不需要，可将其留空。

#示例 1：基本用法（最常见）

如果你只需要将脚本中定义的镜像同步到你的私有 Harbor：

# 1. 为目标仓库导出环境变量
export TARGET_REGISTRY="build-harbor.alauda.cn"
export TARGET_PROJECT="mlops/workbench-images"
export TARGET_USER="admin"
export TARGET_PASSWORD="YourHarborPassword"

# 2. 为脚本授予执行权限（如果尚未设置）
chmod +x ./sync-from-dockerhub.sh

# 3. 执行同步
./sync-from-dockerhub.sh

#示例 2：单行命令执行（适用于 CI 环境）

你可以在同一行中声明环境变量并运行脚本。这样可以避免污染当前 Shell 环境变量：

TARGET_REGISTRY="build-harbor.alauda.cn" \
TARGET_PROJECT="mlops/workbench-images" \
TARGET_USER="admin" \
TARGET_PASSWORD="YourHarborPassword" \
./sync-from-dockerhub.sh

#示例 3：启用 DockerHub 认证的完整执行（防止速率限制）

当你从同一台机器频繁拉取镜像时，DockerHub 可能会拒绝你的请求。此时，请加入 DockerHub 凭据：

export TARGET_REGISTRY="build-harbor.alauda.cn"
export TARGET_PROJECT="mlops/workbench-images"
export TARGET_USER="admin"
export TARGET_PASSWORD="YourHarborPassword"

export DOCKERHUB_USER="alaudadockerhub"
export DOCKERHUB_PASSWORD="dckr_pat_xxx_your_token_xxx"

./sync-from-dockerhub.sh

#故障排查与说明

1. 磁盘空间：由于脚本需要临时将超大镜像（例如 13GB）存储为 tar 归档，请确保系统的 /tmp 目录（或其所在的根分区）有充足的可用空间（建议至少 30GB）。脚本默认的暂存目录为 /tmp/workbench-images-export-from-hub。
2. 传输超时：当前脚本对推送大文件设置了 120 分钟超时（SKOPEO_TIMEOUT="120m"）。如果由于网络速度极慢而导致进程失败，你可以使用任意文本编辑器在脚本顶部调整该参数值。
3. 修改镜像列表：如果有不再希望同步的镜像，只需打开 sync-from-dockerhub.sh，并在 WORKBENCH_IMAGES 数组中使用 # 注释掉相应行即可（类似于在 sync.sh 中筛选掉最小镜像的方式）。

当镜像已在你的仓库中可用后，你还需要将相应配置添加到你计划使用的 WorkspaceKind 资源的 imageConfig 字段中。下面是一个示例 patch YAML，它会向现有的 WorkspaceKind 中添加一个新的镜像配置：

[
  {
    "op": "add",
    "path": "/spec/podTemplate/options/imageConfig/values/-",
    "value": {
      "id": "jupyter-pytorch-llmcompressor-cuda-py312",
      "spawner": {
        "displayName": "Jupyter | PyTorch LLM Compressor | CUDA | Python 3.12",
        "description": "JupyterLab with PyTorch and LLM Compressor for CUDA",
        "labels": [
          {
            "key": "python_version",
            "value": "3.12"
          },
          {
            "key": "framework",
            "value": "pytorch"
          },
          {
            "key": "accelerator",
            "value": "cuda"
          }
        ]
      },
      "spec": {
        "image": "build-harbor.alauda.cn/mlops/workbench-images/odh-workbench-jupyter-pytorch-llmcompressor-cuda-py312-ubi9:3.4_ea1-v1.41",
        "imagePullPolicy": "IfNotPresent",
        "ports": [
          {
            "id": "jupyterlab",
            "displayName": "JupyterLab",
            "port": 8888,
            "protocol": "HTTP"
          }
        ]
      }
    }
  }
]

你可以使用类似下面的命令，将该 patch 应用到你正在使用的 WorkspaceKind：

kubectl patch workspacekind jupyterlab-internal-3-4-ea1-v1-41 \
  --type=json \
  --patch-file add-llmcompressor-image-patch.json \
  -o yaml

此命令会将 JSON patch 文件应用到指定的 WorkspaceKind，并更新其 imageConfig，从而使新的工作台镜像可在工作台创建 UI 中使用。

在实际使用中，你可以根据已同步的镜像以及集群中采用的命名规范，调整 name、image 和 description 字段。