#使用 Workbench 上传模型

Workbench 提供了一个便捷的环境，用于下载模型文件、从本地计算机复制文件，以及将文件上传到模型存储中。本页仅介绍工作流中的 Workbench 部分：在本地准备模型，然后将其复制到 S3、PVC 或 OCI registry。

Model Catalog 不需要此页面：catalog 模型已由配置的源提供。在 Model Registry 中注册已上传的 artifact 是一个独立的控制台操作。上传完成后，请按照注册模型和版本创建一个已注册的模型版本，并使用生成的 Model URI。

#选择上传路径

#前提条件

• 具有 Alauda AI 监控面板的访问权限以及目标命名空间。
• 一个正在运行的 Workbench，并具有足够的本地存储或已挂载的 PVC 存储来保存模型。
• S3 对象存储、PVC 或 OCI registry 中的目标位置。
• 目标存储的写入凭据。
• 对于 S3，需要已有的 bucket、endpoint、access key、secret key，以及可选的 region。上传脚本不会创建 bucket。
• 对于 PVC，需要一个可由 Workbench 和后续推理服务挂载的 claim。Workbench 和推理服务可以依次使用 PVC，因此在不需要并发挂载时不需要 ReadWriteMany。

有关存储后端要求，请参阅 Model Storage。

#创建并连接到 Workbench

1. 从左侧导航中的 Workbench 创建 Workbench。在较旧的安装中，对应入口可能位于 Advanced > Notebook 下。
2. 当模型过大，无法放入 Workbench 的本地工作区，或文件必须在 Workbench 重启后仍然可用时，挂载 PVC。
3. 等待 Workbench 状态变为 Running，然后选择 Connect。
4. 在 JupyterLab 或 code-server 中打开终端。

#将模型下载或复制到 Workbench

从获准的上游源下载模型，或将模型从本地计算机复制到 Workbench。例如，使用 Hugging Face mirror：

export HF_ENDPOINT=https://hf-mirror.com
pip install huggingface_hub
huggingface-cli download \
  deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B \
  --local-dir ./DeepSeek-R1-Distill-Qwen-1.5B

其他常见源包括：

• Hugging Face
• hf-mirror
• ModelScope

如果 Workbench 无法访问 Internet，请在能够连接上游源的计算机上下载模型，然后通过 Workbench 文件浏览器上传：

• 在 JupyterLab 中，打开 Files，选择 Upload Files，然后选择模型文件或 archive。
• 在 code-server 中，打开 Explorer，将文件拖到目标文件夹中。

必要时，在 Workbench 终端中解压 archive。上传前，请确认模型目录包含其 serving framework 所需的文件，例如 configuration、tokenizer 和 weight 文件。不要包含凭据或无关的训练数据。

#将模型从 Workbench 上传到 S3

以下操作步骤会将 Workbench 本地目录递归上传到兼容 S3 的 bucket。它适用于 AWS S3、Ceph、MinIO 以及其他提供兼容 S3 API 的服务。

#1. 在 Workbench 中准备 S3 访问

如果项目使用托管的 connection 设置，请在 User View > Connections 中创建或获取 S3 Connection。选择 S3-compatible object storage，并提供 access key、secret key、endpoint、region 和 bucket。S3 Connection 会记录诸如 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_S3_ENDPOINT、AWS_DEFAULT_REGION 和 AWS_S3_BUCKET 等值。

为推理服务选择的 Connection 不会自动将其值注入已在运行的 Workbench。Workbench 需要拥有自己的 S3 访问权限。请使用管理员批准的方法配置相同的值，例如 PodDefault、已挂载的 Secret 或临时终端环境变量。以下上传命令使用环境变量方式。

对于临时终端会话，请导出这些值，不要将它们放入 notebook 或提交到文件中。对于可重复的工作负载，优先使用 Secret 或 PodDefault，并在上传完成后清除变量：

export AWS_ACCESS_KEY_ID='<access-key>'
export AWS_SECRET_ACCESS_KEY='<secret-key>'
export AWS_S3_ENDPOINT='https://s3.example.com'
export AWS_DEFAULT_REGION='us-east-1'
export AWS_S3_BUCKET='models'

对于 AWS S3，使用默认 AWS endpoint 时可以省略 AWS_S3_ENDPOINT。对于兼容 S3 的服务，请将其设置为服务 endpoint。如果 endpoint 使用自签名证书，请使用组织批准的证书配置；不要在生产环境中禁用 TLS 验证。

#2. 安装或验证 AWS CLI

AWS CLI 是 Amazon S3 的标准命令行客户端。当传入存储 endpoint 时，它还支持 Ceph、MinIO 和 SeaweedFS 等兼容 S3 的对象存储。在 Workbench 终端中验证它是否可用：

aws --version

如果 AWS CLI 不可用，请在 home 目录中安装官方 AWS CLI v2 package。以下命令会根据 Workbench 的 CPU 架构选择 package：

mkdir -p "$HOME/bin" "$HOME/.local/aws-cli"
case "$(uname -m)" in
  x86_64) AWSCLI_ARCH=x86_64 ;;
  aarch64|arm64) AWSCLI_ARCH=aarch64 ;;
  *) echo "Unsupported architecture: $(uname -m)"; exit 1 ;;
esac
curl -fL "https://awscli.amazonaws.com/awscli-exe-linux-${AWSCLI_ARCH}.zip" \
  -o /tmp/awscliv2.zip
unzip -q /tmp/awscliv2.zip -d /tmp
/tmp/aws/install -i "$HOME/.local/aws-cli" -b "$HOME/bin"
export PATH="$HOME/bin:$PATH"
aws --version

#3. 上传并验证模型目录

Bucket 必须已存在。AWS CLI 使用环境中的 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY 和 AWS_DEFAULT_REGION。对于 Amazon S3，请将 AWS_S3_ENDPOINT 留空。对于兼容 S3 的服务，以下命令将 AWS_S3_ENDPOINT 作为 endpoint URL 传入：

AWS_ARGS=()
if [ -n "${AWS_S3_ENDPOINT:-}" ]; then
  AWS_ARGS+=(--endpoint-url "$AWS_S3_ENDPOINT")
fi

aws "${AWS_ARGS[@]}" s3 cp \
  "${LOCAL_MODEL_DIR:-./DeepSeek-R1-Distill-Qwen-1.5B}/" \
  "s3://${AWS_S3_BUCKET}/${S3_PREFIX:-DeepSeek-R1-Distill-Qwen-1.5B}/" \
  --recursive

aws "${AWS_ARGS[@]}" s3 ls \
  "s3://${AWS_S3_BUCKET}/${S3_PREFIX:-DeepSeek-R1-Distill-Qwen-1.5B}/" \
  --recursive

该命令会保留 S3 prefix 下的模型目录布局。例如，当 S3_PREFIX=qwen 时，./model/config.json 会上传为 s3://models/qwen/config.json。

生成的 Model URI 为：

s3://<bucket>/<prefix>

例如，使用 AWS_S3_BUCKET=models 和 S3_PREFIX=DeepSeek-R1-Distill-Qwen-1.5B 时，请使用：

s3://models/DeepSeek-R1-Distill-Qwen-1.5B

s3:// URI 不包含 endpoint。endpoint 和凭据会通过 S3 Connection，或通过 ServiceAccount 和 Secret 单独为推理服务配置。请参阅使用 S3 对象存储进行模型存储。

上传后，尽可能从终端会话中删除临时凭据：

unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_S3_ENDPOINT
unset AWS_DEFAULT_REGION AWS_S3_BUCKET

#从 Workbench 将模型上传到 PVC

1. 在目标命名空间中创建或确定一个 PVC。如果 Workbench 和推理服务在不同时间使用 PVC，则 PVC 不需要 ReadWriteMany。
2. 将 PVC 挂载到 Workbench。
3. 在 Workbench 文件浏览器中打开已挂载的 PVC 目录。
4. 创建一个稳定的模型目录，例如 models/DeepSeek-R1-Distill-Qwen-1.5B。
5. 从本地计算机上传模型文件，或将文件从 Workbench 工作区复制到该目录。
6. 确认 configuration、tokenizer 和 weight 文件出现在该目录中。
7. 在启动需要独占 claim 访问权限的推理服务之前，停止 Workbench，或以其他方式从 Workbench 卸载 PVC。这适用于 ReadWriteOnce PVC。如果 Workbench 必须在推理服务运行期间保持挂载，请使用支持并发挂载的 storage class 和 access mode，例如 ReadWriteMany。

生成的 Model URI 为：

pvc://<pvc-name>/models/DeepSeek-R1-Distill-Qwen-1.5B

请参阅将模型文件上传到 PVC。

#将模型作为 OCI artifact 上传

要使用 OCI 模型存储，请将模型打包为 OCI image，并将其推送到 Harbor 等兼容 OCI 的 registry。Workbench 必须具有获准的 OCI client 和 registry 凭据。推送后记录 image reference，例如：

oci://registry.example.com/models/deepseek-r1:1.0

推理集群必须能够拉取该 image。有关打包说明，请参阅使用 KServe Modelcar 进行模型存储。

#下一步：注册已上传的 artifact

上传到 S3、PVC 或 OCI registry 后，记录 Model URI 并打开 User View > AI Hub > Model Registry。选择 Register Model，选择一个 Model Registry，输入模型名称和版本，并提供 Model URI。此注册步骤会存储模型元数据和 artifact 引用；它不会移动或复制模型文件。在已注册版本处于使用状态期间，请保持 S3 bucket、prefix 和访问配置不变。