使用 Workbench 微调 LLM

本指南介绍如何使用从 Alauda AI Workbench 启动的 LLaMA-Factory 微调 LLM(示例:Qwen3-0.6B)。Notebook 会向集群提交一个 VolcanoJob,因此 GPU 工作负载会在集群节点上运行,同时你可以继续在 JupyterLab 中进行迭代。

如果你需要交互式控制、自定义训练脚本以及针对每次实验调整 YAML,请使用此方法。对于可复用的模板和配额,建议改用 Kubeflow Trainer v2。

范围

  • Alauda AI 1.3 及更高版本。
  • 在 x86_64 + NVIDIA GPU 上微调 LLM。其他模型系列(例如 YOLOv5)需要使用其专用镜像、脚本和数据集格式。
  • NPU 集群需要使用与厂商软件栈兼容的运行时镜像 — 请参阅下方的在非 NVIDIA GPU 上运行或Ascend NPU 配方。

前提条件

  • 已安装 Alauda AI Workbench 插件(或 Kubeflow Base + Notebook)。
  • 已安装 MLflow 插件以进行实验跟踪。

1. 创建 Notebook / VSCode 实例

在 Alauda AI Platform → Workbench(或 Advanced → Kubeflow → Notebook)中创建 Workbench。Workbench 自身只应请求 CPU — GPU 由它提交的 VolcanoJob 请求。请参阅创建 Workbench。

2. 准备基础模型

将 Qwen/Qwen3-0.6B(或任意 Hugging Face 模型)下载到共享 PVC 或 训练作业可以访问的 S3 兼容对象存储中。如果希望通过控制台部署或重复使用基础模型,请在 Model Registry 中注册生成的 Model URI。请参阅使用 Workbench 上传模型 和 Model Registry。

3. 准备输出模型位置

使用共享 PVC 目录存储微调输出,或为作业配置用于写入的 S3 位置。作业完成后,使用其 Model URI 将输出构件注册为新的 Model Registry 版本。无需创建占位模型记录。

4. 准备数据集

使用示例身份数据集,该数据集用于教模型回答“你是谁?”。将解压后的文件上传到训练作业可访问的 PVC 或 S3 位置,并将 DATASET_URI 设置为该位置。数据集布局必须与微调框架匹配。

数据集格式必须与微调框架所要求的格式匹配。

要从 PDF 或 Office 文件构建该 JSONL,请使用 Docling 进行转换,并在同一 Workbench 中使用 SDG Hub 生成合成问答——请参阅使用 Docling 和 SDG Hub 准备微调数据。

HuggingFace datasets 格式

import datasets
print(datasets.get_dataset_infos("<dataset directory>"))
print(datasets.load_dataset("<dataset directory>"))

LLaMA-Factory 格式

如果使用 LLaMA-Factory,请使用其所需的布局——请参阅data_preparation。

5. 运行时镜像

使用预构建的 alaudadockerhub/fine_tune_with_llamafactory:v0.1.1,或自行构建镜像。镜像必须包含读取所选模型和数据集存储所需的工具。不需要大型文件模型仓库客户端。

Containerfile
ARG LLAMA_FACTORY_VERSION="v0.9.4"
FROM <registry-address>/mlops/nvidia/pytorch:24.12-py3

RUN sed -i 's@//.*archive.ubuntu.com@//mirrors.ustc.edu.cn@g' /etc/apt/sources.list.d/ubuntu.sources && \
    sed -i 's/security.ubuntu.com/mirrors.ustc.edu.cn/g' /etc/apt/sources.list.d/ubuntu.sources && \
    apt-get update && \
    DEBIAN_FRONTEND=noninteractive apt-get install -yq --no-install-recommends \
      unzip curl ffmpeg default-libmysqlclient-dev build-essential pkg-config && \
    apt clean && rm -rf /var/lib/apt/lists/*

RUN pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple -U pip setuptools && \
    cd /opt && \
    git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git && \
    cd LLaMA-Factory && git checkout ${LLAMA_FACTORY_VERSION} && \
    sed -i '/torch>=2.4.0/d;/torchvision>=0.19.0/d;/torchaudio>=2.4.0/d' pyproject.toml && \
    pip install --no-cache-dir -e ".[metrics,awq,modelscope]" -i https://pypi.tuna.tsinghua.edu.cn/simple

RUN pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple \
      "transformers>=4.51.1,<=4.53.3" "tokenizers>=0.21.1" \
      "sqlalchemy~=2.0.30" "pymysql~=1.1.1" "loguru~=0.7.2" "mysqlclient~=2.2.7" \
      "deepspeed~=0.18.8" "mlflow>=3.1"

WORKDIR /opt

6. 提交微调 VolcanoJob

创建 YAML,并在 Notebook 终端中使用 kubectl create -f vcjob_sft.yaml 提交。(使用 JupyterLab 上传器将 kubectl 二进制文件放入 Workbench——镜像中不包含该文件。)

VolcanoJob YAML
apiVersion: batch.volcano.sh/v1alpha1
kind: Job
metadata:
  generateName: vcjob-sft-qwen3-
spec:
  minAvailable: 1
  schedulerName: volcano
  maxRetry: 1
  queue: default
  volumes:
    # Workspace PVC (temporary; deleted after the job)
    - mountPath: '/mnt/workspace'
      volumeClaim:
        accessModes: ['ReadWriteOnce']
        storageClassName: 'sc-topolvm'
        resources:
          requests:
            storage: 5Gi
  tasks:
    - name: 'train'
      replicas: 1 # >= 2 for distributed training
      template:
        metadata:
          name: train
        spec:
          restartPolicy: Never
          securityContext:
            runAsNonRoot: true
            runAsUser: 65534
            runAsGroup: 65534
            fsGroup: 65534
          volumes:
            - name: dshm
              emptyDir: { medium: Memory, sizeLimit: 2Gi }
            # PVC for models and datasets. For distributed jobs, prefer NFS / Ceph
            # for simplicity, or local storage pre-cached via kserve local model cache.
            - name: models-cache
              persistentVolumeClaim:
                claimName: wy-model-cache
          initContainers:
            - name: prepare
              image: alaudadockerhub/fine_tune_with_llamafactory:v0.1.1
              imagePullPolicy: IfNotPresent
              env:
                - { name: BASE_MODEL_URI, value: 's3://models/qwen3-0.6b' }
                - {
                    name: DATASET_URI,
                    value: 'pvc://dataset-pvc/identity-alauda',
                  }
              resources:
                requests: { cpu: 100m, memory: 128Mi }
                limits: { cpu: 2, memory: 4Gi }
              securityContext:
                allowPrivilegeEscalation: false
                capabilities: { drop: [ALL] }
                runAsNonRoot: true
                seccompProfile: { type: RuntimeDefault }
              volumeMounts:
                - { name: models-cache, mountPath: /mnt/models }
              command: [/bin/bash, -c]
              args:
                - |
                  set -ex
                  # Mount or download the base model and dataset using the
                  # storage mechanism configured for the job. The example
                  # assumes the PVC mount already contains these directories.
                  cd /mnt/models
                  BASE_MODEL_NAME=qwen3-0.6b
                  DATASET_NAME=identity-alauda
                  test -d "${BASE_MODEL_NAME}" || { echo "Mount or stage ${BASE_MODEL_URI} at /mnt/models/${BASE_MODEL_NAME}"; exit 1; }
                  test -d "${DATASET_NAME}" || { echo "Mount or stage ${DATASET_URI} at /mnt/models/${DATASET_NAME}"; exit 1; }
          containers:
            - name: train
              image: alaudadockerhub/fine_tune_with_llamafactory:v0.1.1
              imagePullPolicy: IfNotPresent
              volumeMounts:
                - { mountPath: /dev/shm, name: dshm }
                - { name: models-cache, mountPath: /mnt/models }
              env:
                - { name: BASE_MODEL_URI, value: 's3://models/qwen3-0.6b' }
                - {
                    name: DATASET_URI,
                    value: 'pvc://dataset-pvc/identity-alauda',
                  }
                - { name: OUTPUT_MODEL_URI, value: 's3://models/wy-sft-output' }
                - { name: HF_HOME, value: /mnt/workspace/hf_cache }
                - { name: DO_MERGE, value: 'true' }
                - {
                    name: MLFLOW_TRACKING_URI,
                    value: 'http://mlflow-tracking-server.kubeflow:5000',
                  }
                - { name: MLFLOW_EXPERIMENT_NAME, value: '<your-namespace>' }
              command: [bash, -c]
              args:
                - |
                  set -ex
                  if [ "${VC_WORKER_HOSTS}" != "" ]; then
                      export N_RANKS=$(echo "${VC_WORKER_HOSTS}" | awk -F',' '{print NF}')
                      export RANK=$VC_TASK_INDEX
                      export MASTER_HOST=$(echo "${VC_WORKER_HOSTS}" | awk -F',' '{print $1}')
                      export WORLD_SIZE=$N_RANKS NNODES=$N_RANKS NODE_RANK=$RANK
                      export MASTER_ADDR=${MASTER_HOST} MASTER_PORT="8888"
                  else
                      export N_RANKS=1 RANK=0 NNODES=1 MASTER_HOST=""
                  fi
                  cd /mnt/workspace
                  BASE_MODEL_NAME=qwen3-0.6b
                  DATASET_NAME=identity-alauda
                  cat >lf-sft.yaml <<EOL
                  model_name_or_path: /mnt/models/${BASE_MODEL_NAME}
                  stage: sft
                  do_train: true
                  finetuning_type: lora
                  lora_target: all
                  lora_rank: 8
                  lora_alpha: 16
                  lora_dropout: 0.1
                  dataset: identity_alauda
                  dataset_dir: /mnt/models/${DATASET_NAME}
                  template: qwen
                  cutoff_len: 1024
                  max_samples: 1000
                  overwrite_cache: true
                  preprocessing_num_workers: 8
                  output_dir: output_models
                  logging_steps: 10
                  save_steps: 500
                  plot_loss: true
                  overwrite_output_dir: true
                  per_device_train_batch_size: 2
                  gradient_accumulation_steps: 2
                  learning_rate: 2.0e-4
                  num_train_epochs: 4.0
                  bf16: false
                  fp16: true
                  ddp_timeout: 180000000
                  val_size: 0.1
                  per_device_eval_batch_size: 1
                  eval_strategy: steps
                  eval_steps: 500
                  report_to: mlflow
                  EOL
                  if [ ${NNODES} -gt 1 ]; then
                      echo "deepspeed: ds-z3-config.json" >> lf-sft.yaml
                      FORCE_TORCHRUN=1 llamafactory-cli train lf-sft.yaml
                  else
                      unset NNODES NODE_RANK MASTER_ADDR MASTER_PORT
                      llamafactory-cli train lf-sft.yaml
                  fi
                  if [ "${DO_MERGE}" = "true" ]; then
                    cat >lf-merge-config.yaml <<EOL
                  model_name_or_path: /mnt/models/${BASE_MODEL_NAME}
                  adapter_name_or_path: output_models
                  template: qwen
                  finetuning_type: lora
                  export_dir: output_models_merged
                  export_size: 4
                  export_device: cpu
                  export_legacy_format: false
                  EOL
                    llamafactory-cli export lf-merge-config.yaml
                  else
                    mv output_models output_models_merged
                  fi
                  # The merged artifact is now available at
                  # /mnt/workspace/output_models_merged. Upload it to the
                  # configured S3/PVC location with the organization's storage
                  # tooling, then register OUTPUT_MODEL_URI as a new Model
                  # Registry version. The training job does not use a
                  # source-code repository for model storage.
              resources:
                requests: { cpu: '1', memory: '2Gi' }
                limits: { cpu: '8', memory: '16Gi', nvidia.com/gpu: 1 }
              securityContext:
                allowPrivilegeEscalation: false
                capabilities: { drop: [ALL] }
                runAsNonRoot: true
                seccompProfile: { type: RuntimeDefault }

提交前需要修改以下内容:

  • 将 BASE_MODEL_URI、DATASET_URI 和 OUTPUT_MODEL_URI 修改为环境所使用的受支持存储 URI。在示例所使用的路径挂载或暂存基础模型和数据集,并在作业完成后将输出目录上传到 OUTPUT_MODEL_URI。
  • models-cache PVC — 提前创建。跨实验重复使用它,以避免重复下载基础模型。
  • 共享内存 dshm — 多 GPU 至少需要 4 GiB。
  • CPU / 内存 / GPU requests 和 limits — 与集群的 device-plugin 匹配(例如 nvidia.com/gpu、nvidia.com/gpualloc)。
  • 超参数 — LLaMA-Factory YAML 已内联在脚本中。将经常调优的参数提取到环境变量中。

NFS 工作区 PVC 注意事项

如果 PVC 后端是 NFS:

  • 任何可能挂载 PVC 的节点都需要 nfs-utils(yum install -y nfs-utils)。

  • 在 StorageClass 上设置 mountPermissions: "0757":

    apiVersion: storage.k8s.io/v1
    kind: StorageClass
    metadata:
      name: ai-nfs
    provisioner: nfs.csi.k8s.io
    parameters:
      mountPermissions: '0757'
      server: <nfs-server-address>
      share: <nfs-export-path>
    reclaimPolicy: Delete
    volumeBindingMode: Immediate
    mountOptions: [hard, nfsvers=4.1]

7. 管理作业

kubectl get vcjob
kubectl get vcjob <name> -o yaml
kubectl get pod && kubectl logs <pod>
kubectl describe vcjob <name>      # if pods aren't scheduling
kubectl get podgroups              # Volcano scheduling view
kubectl delete vcjob <name>

作业成功后,将合并后的目录上传到 OUTPUT_MODEL_URI,并将其注册为 Model Registry 的新版本。发布时选择该活动版本。

8. 实验跟踪

在 LLaMA-Factory 配置中设置 report_to: mlflow,并设置 MLFLOW_TRACKING_URI / MLFLOW_EXPERIMENT_NAME 环境变量,即可将指标发送到 MLflow。在 Alauda AI Platform → Tools → MLFlow 中查找运行记录、比较损失曲线,并固定最佳运行记录。

在启用了安全功能(SSO + 多租户)的 MLflow 安装中,作业还必须进行身份验证——提供一个 MLFLOW_TRACKING_TOKEN 并选择一个工作区。有关如何获取令牌和配置客户端,请参阅使用带有身份验证和 RBAC 的 MLflow Python SDK。

9. 发布微调后的模型

本示例使用 LoRA,并在上传输出制品前将适配器合并到基础模型中。目前尚不支持由基础模型和适配器组成的推理服务。

  1. 打开 AI Hub > Model Registry,将微调后的输出 URI 注册为新模型版本,并在其元数据中设置 Task Type 和 Framework(例如 text-generation 和 transformers)。
  2. 打开活动版本,然后选择 Create Inference API。
  3. 选择与集群 CUDA 版本匹配的 vLLM 运行时,填写存储和资源设置以及 GPU 设置,然后单击 Publish。
  4. 服务运行后,单击 Experience 与模型聊天(仅当模型包含 chat_template 时)。

在非 NVIDIA GPU 上运行

适用于 Huawei Ascend NPU、Intel Gaudi、AMD 等。使用 PyTorch CANN + MindSpeed-LLM 的 Ascend NPU 方案详见在 Ascend NPU 上微调和预训练 LLM。

一般步骤:

  1. 前提条件:已部署供应商驱动程序和 Kubernetes device plugin,且设备对 Pod 可见。记下资源名称(例如 huawei.com/Ascend910: "1")。
  2. 收集供应商的解决方案——包括文档、微调镜像、支持的模型、示例数据和启动命令/参数。
  3. (可选)先端到端验证供应商解决方案,以排除解决方案本身的问题。
  4. (可选)将其封装为基本 Kubernetes Job,在添加 Volcano 之前确认 device plugin 在 K8s 下正常工作。
  5. 作为 VolcanoJob 运行,并以如下 YAML 为起点。
VolcanoJob YAML(供应商模板)
apiVersion: batch.volcano.sh/v1alpha1
kind: Job
metadata:
  generateName: vcjob-sft-
spec:
  minAvailable: 1
  schedulerName: volcano
  maxRetry: 1
  queue: default
  volumes:
    - mountPath: '/mnt/workspace'
      volumeClaim:
        accessModes: ['ReadWriteOnce']
        storageClassName: 'sc-topolvm'
        resources:
          requests:
            storage: 5Gi
  tasks:
    - name: 'train'
      replicas: 1
      template:
        metadata: { name: train }
        spec:
          restartPolicy: Never
          volumes:
            - name: dshm
              emptyDir: { medium: Memory, sizeLimit: 2Gi }
            - name: models-cache
              persistentVolumeClaim:
                claimName: sft-qwen3-volume
          containers:
            - name: train
              image: '<vendor-fine-tuning-image>'
              imagePullPolicy: IfNotPresent
              volumeMounts:
                - { mountPath: /dev/shm, name: dshm }
                - { name: models-cache, mountPath: /mnt/models }
              env:
                - {
                    name: MLFLOW_TRACKING_URI,
                    value: 'http://mlflow-tracking-server.aml-system.svc.cluster.local:5000',
                  }
                - {
                    name: MLFLOW_EXPERIMENT_NAME,
                    value: kubeflow-admin-cpaas-io,
                  }
              command: [bash, -c]
              args:
                - |
                  set -ex
                  echo "job workers list: ${VC_WORKER_HOSTS}"
                  # vendor-specific launch command goes here
              resources:
                requests: { cpu: '1', memory: '8Gi' }
                limits:
                  cpu: '8'
                  memory: '16Gi'
                  nvidia.com/gpualloc: '1'
                  nvidia.com/gpucores: '50'
                  nvidia.com/gpumem: '8192'

在其他设备上进行实验跟踪

LLaMA-Factory 和 Transformers 可直接与 MLflow / wandb 集成。在框架配置中设置目标位置(例如,LLaMA-Factory 使用 report_to: mlflow),并提供 MLFLOW_TRACKING_URI 和 MLFLOW_EXPERIMENT_NAME 环境变量(在启用了安全功能的安装中还需设置 MLFLOW_TRACKING_TOKEN——请参阅使用带有身份验证和 RBAC 的 MLflow Python SDK)。在 Alauda AI Platform → Tools → MLFlow 下查看结果。