昇腾社区首页
中文
注册
开发者
下载
支持
积分兑换 NEW

适配示例

本章节将指导用户step by step地完成断点续训的适配步骤。

  • 为保证优雅容错与进程级在线恢复功能的正常使用，请将K8s集群master节点与worker节点的时钟保持一致。
  • 断点续训展示的组件代码为开源代码，其中涉及到相关安全说明请参见安全说明。
  • 下文中模型示例代码可能与实际版本存在差异，请以实际版本代码为准。
  • 模型的参数设置，根据模型仓的模型配置以实际情况来写。若修改不当，可能会引发不可预知的问题。
  • 若训练过程中出现“Failed to bind the IP port. Reason: The IP address and port have been bound already”报错，可以按照如下进行配置，详情请参见《CANN 环境变量参考》中的“HCCL_HOST_SOCKET_PORT_RANGE”章节。 
    export HCCL_HOST_SOCKET_PORT_RANGE="60000-60050"
export HCCL_NPU_SOCKET_PORT_RANGE="61000-61050"

PyTorch场景适配示例（基于MindSpeed-LLM）

训练代码与数据集准备，可以参考MindSpeed-LLM使用指南。下面以两台Atlas 800T A2 训练服务器为例，说明具体操作步骤。

  1. 拉取训练代码。
    mkdir -p /data/atlas_dls/public/code
cd /data/atlas_dls/public/code
git clone https://gitcode.com/Ascend/MindSpeed-LLM.git
git clone https://github.com/NVIDIA/Megatron-LM.git
cd MindSpeed-LLM
git checkout 2.3.0
cd ..
cd Megatron-LM 
git checkout core_v0.12.1
cp -r megatron ../MindSpeed-LLM #此处目的是将Megatron-LM项目下的Megatron目录复制到MindSpeed-LLM项目下
## 重命名MindSpeed-LLM为QWEN3_for_PyTorch_2.7_code
cd ..
mv MindSpeed-LLM QWEN3_for_PyTorch_2.7_code
  2. 获取模型权重。

    请用户自行从Qwen3下载模型权重放到服务器某目录下，如“/data/atlas_dls/public/dataset/qwen3-8b-hf”。

  3. 获取数据集。

    请用户自行从Alpaca下载数据集（以Alpaca数据集为例）放到服务器某目录下，如“/data/atlas_dls/public/dataset/qwen3-alpaca”。

  4. 处理数据集。
    1. 启动容器。 
      docker run -it -v /data/atlas_dls/public/:/data/atlas_dls/public/ -e ASCEND_VISIBLE_DEVICES=0-7 mindspeed-dl:v1 bash
    2. 在容器中执行如下操作。 
      export TORCH_DEVICE_BACKEND_AUTOLOAD=0
source /usr/local/Ascend/cann/set_env.sh
cd /data/atlas_dls/public/code/QWEN3_for_PyTorch_2.7_code
# 可选，如下为安装MindSpeed加速库操作，可在任意目录下执行。若制作镜像时已安装，则跳过该操作
git clone https://gitcode.com/ascend/MindSpeed.git 
cd MindSpeed 
git checkout 2.3.0_core_r0.12.1
pip install -r requirements.txt 
pip install -e . 
export PYTHONPATH=/data/atlas_dls/public/code/QWEN3_for_PyTorch_2.7_code/MindSpeed:$PYTHONPATH
cd ..
    3. 处理数据集。

      Qwen3要求使用Transformers>=4.51.0，因此Python需使用3.9及以上版本且需要安装4.51.0及以上的Transformers。

      python preprocess_data.py \
    --input /data/atlas_dls/public/dataset/qwen3-alpaca/train-00000-of-00001-a09b74b3ef9c3b56.parquet \ # 数据集文件路径
    --tokenizer-name-or-path /data/atlas_dls/public/dataset/qwen3-8b-hf \ # 开源模型权重文件目录
    --tokenizer-type PretrainedFromHF \
    --handler-name GeneralPretrainHandler \
    --output-prefix /data/atlas_dls/public/dataset/qwen3-alpaca/alpaca \ # 会生成alpaca_text_document.bin和.idx文件
    --json-keys text \
    --workers 4 \
    --log-interval 1000
      若出现报错：/usr/local/lib/python3.10/dist-packages/sklearn/utils/../../scikit_learn.libs/libgomp-947d5fa1.so.1.0.0: cannot allocate memory in static TLS block，可执行以下命令预加载libgomp库。 
      export LD_PRELOAD="/usr/local/lib/python3.10/dist-packages/scikit_learn.libs/libgomp-947d5fa1.so.1.0.0"
  5. 进入“mindcluster-deploy”仓库，根据mindcluster-deploy开源仓版本说明进入版本对应分支，获取“samples/train/resumable-training/fault-tolerance/without-ranktable/pytorch/Qwen3”目录下的train_start.sh文件，在管理节点构造成如下的目录结构。
    root@ubuntu:/data/atlas_dls/public/code/QWEN3_for_PyTorch_2.7_code/scripts#
scripts/
└── train_start.sh
  6. 获取训练任务YAML。该YAML中已经配置了Pod级别重调度、进程级别重调度、进程级在线恢复、弹性训练等。根据实际情况配置挂载卷的服务器IP地址、各种重调度级别等。

    进程级别重调度、进程级在线恢复、弹性训练等训练进程级别的恢复与优雅容错不可同时存在。优雅容错的配置步骤请参见优雅容错模式。

  7. 配置训练启动脚本train_start.sh和训练任务YAML，请根据实际情况进行修改。
    1. 修改启动脚本基础参数。 
      mkdir -p /job/code/alllogs/$MINDX_TASK_ID/ttplogs
mkdir -p /job/code/alllogs/$MINDX_TASK_ID/trainlogs
mkdir -p /job/code/alllogs/$MINDX_TASK_ID/demo/
# 日志保存路径，可根据实际情况修改
export ASCEND_PROCESS_LOG_PATH=/job/code/alllogs/$MINDX_TASK_ID/plogs/$XDL_IP       # 设置plog保存路径，其中$MINDX_TASK_ID为Ascend Operator注入的任务UID环境变量，$XDL_IP为任务YAML中写入的环境变量status.hostIP
export TTP_LOG_PATH=/job/code/alllogs/$MINDX_TASK_ID/ttplogs/ttplog$XDL_IP-$RANK    # 设置TTP日志保存路径，其中$RANK为Ascend Operator为PyTorch框架注入的环境变量
export TRAIN_LOG_PATH=/job/code/alllogs/$MINDX_TASK_ID/trainlogs/$XDL_IP-$RANK      # 设置训练日志保存路径
export GLOO_SOCKET_IFNAME=enp189s0f0               # 物理机上可以通信的网口，根据主节点高速网卡实际情况进行配置，如任务YAML中配置hostNetwork为false，则设置为eth0
export HCCL_SOCKET_IFNAME=enp189s0f0               # 如任务YAML中配置hostNetwork为false，则设置为eth0
 
CKPT_SAVE_DIR="/job/code/output/ckpt" # 训练完成后的权重保存路径
DATA_PATH="/job/data/alpaca_text_document" # 数据集路径，填入数据预处理时保存的数据路径
TOKENIZER_PATH="/job/data/qwen3-8b-hf" # 词表路径，填入下载的开源权重词表路径
CKPT_LOAD_DIR="/job/code/output/ckpt" # 权重加载路径
    2. 使用TaskD完成进程级别重调度、进程级在线恢复、进程级别原地恢复或弹性训练，还需拉起TaskD Manager。
      1. 创建manager.py文件，放在调用训练脚本时的当前目录下。manager.py文件内容如下所示。 
        from taskd.api import init_taskd_manager, start_taskd_manager
import os
 
job_id=os.getenv("MINDX_TASK_ID")
node_nums=XX         # 用户填入任务节点总数
proc_per_node=XX     # 用户填入任务每个节点的训练进程数量
 
init_taskd_manager({"job_id":job_id, "node_nums": node_nums, "proc_per_node": proc_per_node})
start_taskd_manager()

        manager.py文件中的参数详细说明请参见def init_taskd_manager(config:dict) -> bool:。

      2. 在训练脚本中增加以下代码，拉起TaskD Manager，推荐将torchrun分布式参数--monitor_interval设置为1。

        在以下代码中，TASKD_SO_PATH和export LD_PRELOAD两条语句的作用是将安装TaskD后libtaskd.so的路径配置到环境变量LD_PRELOAD中。如果这两条语句配置不成功，可通过手动执行pip show taskd命令获取Location的值拼接上/taskd/python/cython_api/libs/libtaskd.so，然后通过export设置。

        sed -i '/import os/i import taskd.python.adaptor.patch' $(pip3 show torch | grep Location | awk -F ' ' '{print $2}')/torch/distributed/run.py
TASKD_SO_PATH="$(pip show taskd | awk '/^Location: / {print $2"/taskd/python/cython_api/libs/libtaskd.so"}')"
export LD_PRELOAD=$TASKD_SO_PATH:$LD_PRELOAD
export TASKD_PROCESS_ENABLE="on"
if [[ "${RANK}" == 0 ]]; then
    export MASTER_ADDR=${POD_IP}
    python manager.py &           # 具体执行路径由当前路径决定
fi
    
DISTRIBUTED_ARGS="...\
                  --monitor_interval 1 \
                  ..."
torchrun $DISTRIBUTED_ARGS ...
      3. 修改训练任务YAML，新增容器端口，在所有的Pod下增加TaskD通信使用的端口9601（如已有则跳过）。 
        ...
ports:                         
   - containerPort: 9601             
     name: taskd-port 
...

MindSpore场景适配示例（基于MindFormers）

训练代码与数据集准备，可以参考MindFormers文档。下面以两台Atlas 900 A3 SuperPoD 超节点为例，说明具体操作步骤。

  1. 准备代码。
    mkdir -p /data/atlas_dls/public/code
cd /data/atlas_dls/public/code
git clone https://gitee.com/mindspore/mindformers.git
cd mindformers
git checkout f06a946af29c8c7e002a6c49458f513d47b642e5
# 将mindformers重命名为QWEN3_for_MS_code
cd ..
mv mindformers QWEN3_for_MS_code
  2. 准备数据集。

    请用户自行从DagsHub下载数据集并放到服务器某目录下，如“/data/atlas_dls/public/code/QWEN3_for_MS_code/dataset”。

  3. 转换数据集。
    1. 下载数据集转换脚本。

      从数据集转换下载数据集转换脚本并放到服务器某目录下，如“/data/atlas_dls/public/code/QWEN3_for_MS_code/dataset/gen_wiki_json.py”。

    2. 下载tokenizer文件。

      从Qwen3-32B下载tokenizer文件并放到服务器某目录下，如“/data/atlas_dls/public/code/QWEN3_for_MS_code/dataset/Qwen3-32B-tokenizer”。

    3. 转换数据集。
      1. 启动容器并挂载所需文件。 
        docker run -it -v /data/atlas_dls/public/code/:/data/atlas_dls/public/code/ mindformers-dl:v1 bash
      2. 执行转换脚本，将wiki.train.tokens转换为jsonl格式。 
        # 执行该脚本需要的Python环境，请提前准备Python环境
cd /data/atlas_dls/public/code/QWEN3_for_MS_code/dataset
python gen_wiki_json.py --input wiki.train.tokens  --output wiki.jsonl
      3. 将jsonl格式数据转为bin格式数据。 
        # 执行时若报错ModuleNotFoundError: No module named 'xxx'，请自行安装依赖
cd /data/atlas_dls/public/code/QWEN3_for_MS_code
python toolkit/data_preprocess/megatron/preprocess_indexed_dataset.py \
  --input /data/atlas_dls/public/code/QWEN3_for_MS_code/dataset /wiki.jsonl \
  --output-prefix /data/atlas_dls/public/code/QWEN3_for_MS_code/dataset /wiki103-megatron \
  --tokenizer-type HuggingFaceTokenizer \
  --tokenizer-dir /data/atlas_dls/public/code/QWEN3_for_MS_code/dataset/Qwen3-32B-tokenizer # 其他规格的模型可以调整为对应的tokenizer路径

        运行完成后，“/data/atlas_dls/public/code/QWEN3_for_MS_code/dataset”目录下会生成“wiki103-megatron_text_document.bin”和“wiki103-megatron_text_document.idx”文件。 填写数据集路径时，需要使用“/data/atlas_dls/public/code/QWEN3_for_MS_code/dataset/wiki103-megatron_text_document”，不需要带后缀名。

  4. 获取训练任务YAML和训练启动脚本，并进行修改。
    1. 若训练任务YAML中“hostNetwork”参数值为“false”，则需要将启动脚本中“GLOO_SOCKET_IFNAME”的值设置为“eth0”。示例如下： 
      export GLOO_SOCKET_IFNAME=eth0  #eth0是容器内可以通信的网口
export HCCL_SOCKET_IFNAME=eth0

      然后根据实际情况修改启动脚本中的其他参数。

    2. 根据实际情况修改任务YAML中挂载卷的服务器IP地址等配置。
    3. 使用TaskD完成进程级别重调度、进程级在线恢复、进程级别原地恢复、借轨通信任务暂停与回切或在线压测，还需拉起TaskD Manager。
      1. 创建manager.py文件，放在调用训练脚本时的当前目录下，manager.py文件内容如下所示。 
        from taskd.api import init_taskd_manager, start_taskd_manager
import os

job_id=os.getenv("MINDX_TASK_ID")
node_nums=XX         # 用户填入任务节点总数
proc_per_node=XX     # 用户填入任务每个节点的训练进程数量

init_taskd_manager({"job_id":job_id, "node_nums": node_nums, "proc_per_node": proc_per_node})
start_taskd_manager()

        manager.py文件中的参数详细说明请参见def init_taskd_manager(config:dict) -> bool:。

      2. 在训练脚本中增加以下代码拉起TaskD Manager。在以下代码中，前两条语句的作用是将安装TaskD后libtaskd.so的路径配置到环境变量LD_PRELOAD中。如果这两条语句配置不成功，可通过手动执行pip show taskd命令获取Location的值拼接上/taskd/python/cython_api/libs/libtaskd.so，然后通过export设置。 
        TASKD_SO_PATH="$(pip show taskd | awk '/^Location: / {print $2"/taskd/python/cython_api/libs/libtaskd.so"}')"
export LD_PRELOAD=$TASKD_SO_PATH:$LD_PRELOAD
export TASKD_PROCESS_ENABLE="on"
if [[ "${MS_SCHED_HOST}" == "${POD_IP}" ]]; then
    python manager.py &   # 具体执行路径由当前路径决定
fi
msrun ...
      3. 修改训练任务YAML，新增容器端口，在所有的Pod下增加TaskD通信使用的端口9601（如已有则跳过）。 
        ...
ports:                         
   - containerPort: 9601             
     name: taskd-port 
...
  5. 修改参数模型配置文件。
    1. 打开代码目录下“configs/qwen3/pretrain_qwen3_32b_4k.yaml”文件。 
      vi configs/qwen3/pretrain_qwen3_32b_4k.yaml
    2. 按“i”进入编辑模式，修改参数模型配置文件。
      1. 修改如下加粗配置，包括数据集路径、分布式并行参数、模型参数等。以下模型参数仅供参考，如有需要请自行修改。 
        train_dataset: &train_dataset
  data_loader:
    type: BlendedMegatronDatasetDataLoader
    datasets_type: "GPTDataset"
    sizes:
      - 8000  # Number of samples in the training set
      - 0     # Number of samples in the test set (currently unsupported)
      - 0     # Number of samples in the evaluation set (currently unsupported)
    config:
      seed: 1234  # Random seed for data sampling
      split: "1, 0, 0"  # Proportions for training, test, and evaluation sets (test/eval currently unsupported)
      seq_length: 4096  # Sequence length of the dataset
      eod_mask_loss: False  # Whether to calculate loss at the end-of-document (EOD)
      reset_position_ids: False  # Whether to reset position_ids at EOD
      create_attention_mask: True  # Whether to include attention_mask in the dataset
      reset_attention_mask: False  # Whether to reset attention_mask at EOD, creating a stepped attention_mask
      create_compressed_eod_mask: False  # Whether to include a compressed attention_mask
      eod_pad_length: 128  # Length of the compressed attention_mask
      eod: 1  # Token ID for EOD in the dataset
      pad: -1  # Token ID for padding in the dataset
      data_path:  # Sampling proportion and path for the Megatron dataset
        - '1'
        - "/job/data/wiki103-megatron_text_document" # 数据集路径
……
# Parallel configuration
parallel_config:
  data_parallel: &dp 4  # Number of data parallel. If using the high availability feature, it must be an even number.
  model_parallel: 8  # Number of model parallel
  pipeline_stage: 1  # Number of pipeline parallel
  micro_batch_num: 1  # Pipeline parallel microbatch size
  use_seq_parallel: False  # Whether to enable sequence parallelism
  gradient_aggregation_group: 1  # Size of the gradient communication operator fusion group
# When model_parallel > 1, setting micro_batch_interleave_num to 2 may accelerate the training process.
micro_batch_interleave_num: 1
……
model:
  model_config:
    # Configurations from Hugging Face
    vocab_size: 75968            # 此处改小了模型参数仅供测试，如有需要请自行调整
    hidden_size: 2560           # 此处改小了模型参数仅供测试，如有需要请自行调整
    intermediate_size: 12800   # 此处改小了模型参数仅供测试，如有需要请自行调整
    num_hidden_layers: 32      # 此处改小了模型参数仅供测试，如有需要请自行调整
    num_attention_heads: 32    # 此处改小了模型参数仅供测试，如有需要请自行调整
    num_key_value_heads: 8
    head_dim: 128
    hidden_act: 'swiglu'
    max_position_embeddings: 4096
    seq_length: 4096
    initializer_range: 0.02
    rms_norm_eps: 1.e-6
    use_cache: True
    tie_word_embeddings: False
    rope_theta: 1000000.
    attention_bias: False
    use_flash_attention: True
    add_bias_linear: False
    eos_token_id: 151645
    pad_token_id: 151643
    bos_token_id: 151643
    attention_dropout: 0.0
    # Configurations from MindFormers
    hidden_dropout: 0.0
    input_sliced_sig: True
    untie_embeddings_and_output_weights: True
    position_embedding_type: "rope"
    qk_layernorm: True
    use_contiguous_weight_layout_attention: False
    qkv_concat: True
    offset: [0]
    params_dtype: "float32"
    compute_dtype: "bfloat16"
    layernorm_compute_dtype: "float32"
    softmax_compute_dtype: "float32"
    rotary_dtype: "float32"
    residual_dtype: "float32"
    model_type: "qwen3"
    architectures: ["Qwen3ForCausalLM"]
      2. （可选）使用临终CKPT的场景，在保存CKPT后通过Pod级别重调度加载CKPT，需修改如下配置字段。

        首次拉起必须保证“load_checkpoint”参数值的目录下存在正常可用的CKPT或该目录为空，否则可能导致训练无法正常拉起。

        resume_training: True 
src_strategy_path_or_dir: './output/strategy'
load_checkpoint: './output/checkpoint'
    3. 按“Esc”键，输入:wq!，按“Enter”保存并退出编辑。

强化学习后训练场景适配示例（基于Verl）

MindCluster仅支持Job级别重调度。Verl的训练任务被Ray集群所管理，为适配MindCluster的Ascend Job任务部署，每个Worker节点上部署一个Pod，Pod内承载该Ray集群上的所有进程。Ray集群的head节点根据Ascend Operator注入的环境变量RANK=0所在的节点决定。RANK=0节点的Pod启动Ray集群，提交Verl后训练任务，其他Worker节点的Pod加入Ray集群。最后所有节点都检测提交的训练任务是否存在异常。

  • 若存在异常，则以非0退出，Volcano感知到业务异常触发Job级别重调度。
  • 若没有异常且任务已结束，则以0退出。

下面以两台Atlas 900 A3 SuperPoD 超节点为例，说明具体操作步骤。

  1. 模型权重转换，将HuggingFace模型转换为Megatron模型，可参考Verl模型转化脚本。
    # 启动容器，具体模型路径根据实际情况修改
docker run -it \
-v /qwen30b/Qwen3-30B-A3B-Instruct-2507:/qwen30b/Qwen3-30B-A3B-Instruct-2507 \
-v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
-e ASCEND_VISIBLE_DEVICES=0-15 \
verl:v1 /bin/bash
 
# 执行权重转化
cd ~/verl
python scripts/converter_hf_to_mcore.py \
--hf_model_path /qwen30b/Qwen3-30B-A3B-Instruct-2507 \
--output_path /qwen30b/Qwen3-30B-A3B-Instruct-Mcore \

    若出现如下错误，则先执行如下命令：

    export LD_PRELOAD="/usr/local/lib/python3.10/dist-packages/sklearn/utils/../../scikit_learn.libs/libgomp-947d5fa1.so.1.0.0"

  2. 构建Verl的Qwen3 30B MoE的训练脚本。其中推理后端为vLLM，训练后端为Megatron。

    获取脚本示例run_dapo_qwen3_30b_a3b_megatron.sh，并将其放置到verl路径中examples_npu下。同时在“examples_npu/config”路径下创建两个文件dapo_trainer-megatron.yaml和runtime_env.yaml，其内容如下：

    • dapo_trainer-megatron.yaml 
      # examples_npu/config/dapo_trainer-megatron.yaml
hydra:
  searchpath:
    - file://verl/trainer/config
defaults:
  - ppo_megatron_trainer
  - _self_
data:
  gen_batch_size: ${data.train_batch_size}
reward_model:
  reward_manager: dapo
  overlong_buffer: 
    enable: False # We try to avoid forgetting to set enable
    len: 0
    penalty_factor: 0.0
    log: False
algorithm:
  filter_groups:
    _target_: verl.trainer.config.FilterGroupsConfig
    enable: False # We try to avoid forgetting to set enable
    metric: null # acc / score / seq_reward / seq_final_reward / ...
    max_num_gen_batches: 0 # Non-positive values mean no upper limit
trainer:
  project_name: verl-dapo
    • runtime_env.yaml 
      # examples_npu/config/runtime_env.yaml
working_dir: ./
excludes: ["/.git/"]
env_vars:
  HCCL_EXEC_TIMEOUT: "7200"
  HCCL_CONNECT_TIMEOUT: "7200"
  VLLM_USE_V1: "1"
  VLLM_VERSION: "0.9.1"
  HCCL_IF_BASE_PORT: "23999"
  HCCL_ASYNC_ERROR_HANDLING: "0"
  P2P_HCCL_BUFFSIZE: "20"
  3. 构建适配MindCluster的Ray启动脚本。在每台Worker节点上准备好Ray启动脚本，放到两台Atlas 900 A3 SuperPoD 超节点上。其中的网卡信息需根据实际情况配置，其余脚本可以保持不变。

    获取脚本示例start.sh，并将脚本放置到verl目录下。

  4. 获取准备任务YAML中的verl-resche.yaml，根据实际情况修改其中的参数，然后执行如下命令启动任务。
    kubectl apply -f verl-resche.yaml

    启动任务后，会显示如下迭代信息：

父主题： 脚本适配