#创建 Workbench

#前提条件

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

#通过 Web 控制台创建 Workbench

#操作步骤

#连接到 Workbench

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

#在 JupyterLab 中上传文件

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

#离线安装 Python Wheel 文件

1. 连接到 workbench 并打开 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

#可用的 Workbench 镜像

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

以下表格采用与 Red Hat OpenShift AI 文档相同的整体风格：每个镜像都描述其预期用途，并列出关键的预装包以供快速参考。包列表为代表性示例，而非完整清单。版本信息取自构建仓库中对应的镜像目录及其相关锁定文件。

#内置镜像

以下镜像开箱即用：

#多架构镜像（x86_64 和 arm64）

#其他镜像

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

#x86_64 镜像

这些镜像面向支持 NVIDIA GPU 的 x86_64 节点。

#arm64 镜像

这些镜像面向支持 Ascend NPU 的 arm64 节点。

要使用其他镜像，首先需要将其同步到你自己的镜像仓库。你可以使用 skopeo 等工具，或者使用下一节中描述的脚本。

#使用 Qwen3.5 notebook 验证 ModelSlim 镜像

如果你使用 docker.io/alaudadockerhub/alauda-workbench-jupyter-modelslim-cann-py311-ubi9:v0.1.7，可以通过 Download qwen35_modelslim_quant_verify.ipynb 验证环境。

该 notebook 遵循官方 Ascend msmodelslim Qwen3.5 示例，旨在作为预检验证 notebook，而不是完整的量化运行。默认情况下，它会：

• 检查验证过的技术栈所需的运行时导入以及锁定的包版本，包括 msmodelslim 26.0.0a2 和 transformers 5.2.0
• 验证 msmodelslim CLI 以及模型目录和输出目录的权限要求
• 准备官方 msmodelslim quant --device npu ... 命令，并且仅在 RUN_QUANT = True 时执行量化

在运行 notebook 之前，请将基础模型上传到 workbench，并查看第一个参数单元中的 MODEL_PATH、SAVE_PATH、MODEL_TYPE 和 QUANT_TYPE。此镜像使用 Python 3.11，因为构建所使用、已验证的公开 msmodelslim wheel 版本面向 CPython 3.11。上游 Qwen3.5 指南当前将 Atlas A2 和 Atlas A3 训练与推理产品列为该量化流程支持的设备系列。

#Docker Hub 镜像同步脚本指南

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

#脚本前提条件

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

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

#环境变量配置

脚本通过读取环境变量来执行同步，提供了灵活的使用方式，而无需修改代码。

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

#可选参数（源 DockerHub 配置）

为防止在拉取大量镜像时触发 DockerHub 的 Rate Limit，你可以提供 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 中筛选掉 minimal 镜像的方式）。

当镜像可在你的仓库中使用后，你还需要将相应配置添加到计划使用的 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，使新的 workbench 镜像可在 workbench 创建 UI 中使用。

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

#为 Ascend vNPU workbench 配置 supplemental groups

如果你使用 huawei.com/Ascend910B4 等 Ascend vNPU 资源选项，请确认目标 WorkspaceKind pod 模板在 supplementalGroups 中包含 Ascend 设备组。某些 vNPU 环境会将 /dev/davinci* 设备文件挂载为组拥有的字符设备，例如 1000:1000，权限模式为 crw-rw----。在这种情况下，仅设置 fsGroup 不足以授予对设备文件的访问权限，npu-smi info 等命令可能会失败，并报错 dcmi module initialize failed. ret is -8005。

请对提供 vNPU workbench 选项的 WorkspaceKind 执行 patch：

kubectl patch workspacekind jupyterlab-internal-3-4-ea1-v1-41 \
  --type=merge \
  -p '{"spec":{"podTemplate":{"securityContext":{"fsGroup":0,"supplementalGroups":[1000]}}}}'

请使用你集群中拥有 Ascend 设备文件的组 ID。基于此 WorkspaceKind 创建的新 workbench pod 将继承更新后的安全上下文。现有的 workbench pod 必须重启后才能生效。