#创建工作台

#前提条件

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

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

#操作步骤

#连接到工作台

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

#在 JupyterLab 中上传文件

如果你使用的是基于 JupyterLab 的工作台，可以通过文件浏览器中的 Upload Files 按钮从本地机器上传文件。当工作台无法访问公网或 PyPI mirror，而你需要从本地 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 等工具完成此操作，或者使用下一节中描述的脚本。

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

如果你使用 docker.io/alaudadockerhub/alauda-workbench-jupyter-modelslim-cann-py311-ubi9:v0.1.7，可以通过 下载 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 之前，请将基础模型上传到工作台，并在第一个参数单元中检查 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。
由于网络波动，超大镜像在直接传输时更容易出现 OOM 或超时失败。为提高可靠性，该脚本使用中转工作流：本地拉取 → 导出为 tar 归档 → 将 tar 归档推送到目标仓库。它还会在任务完成或异常退出时自动清理临时文件。

#脚本前提条件

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

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

#环境变量配置

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

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

#可选参数（源 DockerHub 配置）

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

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

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

# 1. Export environment variables for the target registry
export TARGET_REGISTRY="build-harbor.alauda.cn"
export TARGET_PROJECT="mlops/workbench-images"
export TARGET_USER="admin"
export TARGET_PASSWORD="YourHarborPassword"

# 2. Grant execution permissions to the script (if not already done)
chmod +x ./sync-from-dockerhub.sh

# 3. Execute the synchronization
./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，从而使新的工作台镜像可以在工作台创建 UI 中使用。

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

#为 Ascend vNPU 工作台配置补充组

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

请为提供 vNPU 工作台选项的 WorkspaceKind 打补丁：

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

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