企业官网建设流程全解析

• 人工智能
• 大模型
• 分布式训练
• 预训练
• 微调
• 模型推理服务
• 强化学习
• Ascend

本文围绕 examples/mcore/qwen3 目录下 Qwen3 8B 的 Mcore（Megatron-Core）示例脚本链路展开，覆盖预训练数据处理、指令数据处理、HF/mcore 双向权重转换、预训练、全参微调、LoRA 微调、推理与评估八个阶段。读完本文，你将掌握每类脚本的定位、核心参数含义、脚本命名规律，以及从昇腾 NPU 环境准备到跑通完整 Qwen3 训练链路的实操方法，并能据此快速改造出适配其他模型规模或集群拓扑的脚本。

一、示例脚本任务链路总览

Qwen3 Mcore 示例链路按任务阶段组织脚本，用户可按阶段直接查找对应脚本。完整链路如下表所示：

脚本入口与仓库源码的对应关系：预训练、微调、推理、评估分别由仓库根目录的 pretrain_gpt.py、posttrain_gpt.py、inference.py、evaluation.py 承接，权重转换统一走 convert_ckpt_v2.py，数据处理走 preprocess_data.py。

二、相关文档与前置环境

运行任何脚本前，建议先按以下文档完成环境准备与概念铺垫：

• MindSpeed-LLM 软件安装：安装 MindSpeed-LLM、MindSpeed、Megatron-LM 及其依赖，并配置昇腾 CANN 环境。
• mcore 预训练：预训练任务的整体流程与参数说明。
• mcore 指令微调：指令微调任务的流程、数据组织与训练入口说明。
• 模型推理：推理入口 inference.py 的使用方式。
• 模型评估：评估入口 evaluation.py 与各 benchmark 数据集的用法。
• 预训练数据处理：preprocess_data.py的通用用法。
• 权重转换说明可参考文档导航中的工具链部分，如 checkpoint_convert_hf_mcore_large_params.md。

需要特别说明的是，训练与微调脚本本身支持--enable-hf2mg-convert --model-type-hf qwen3参数，可直接加载 Hugging Face 格式权重并在启动时自动完成 HF → mcore 转换；独立的权重转换脚本则用于需要显式预转换（例如按目标 TP/PP 切分保存）或需要转回 HF 格式发布/部署的场景。两套路径可互为替代与补充。

三、脚本命名规范速查

Qwen3 示例脚本通常按任务类型、模型规模和上下文长度命名，理解命名规律后可快速定位所需脚本：

• pretrain_qwen3_*：预训练或续训脚本。
• tune_qwen3_*_full_*：全参微调脚本。
• tune_qwen3_*_lora_*：LoRA 微调脚本。
• generate_qwen3_*：推理脚本。
• evaluate_qwen3_*：评估脚本。
• ckpt_convert_qwen3_*：权重转换脚本。
• data_convert_qwen3_*：数据处理脚本。

文件名中的0point6b、1point7b、4b、8b、14b、32b表示模型规模，4K、32K、256K表示常见序列长度配置，A3表示面向特定硬件或集群配置场景的示例脚本。以当前 8B 目录为例：pretrain_qwen3_8b_4K_ptd.sh表示 Qwen3 8B、4K 序列长度的预训练脚本，ptd指采用 PyTorch 分布式（torchrun）启动方式；带A3后缀的变体从脚本内容看使用 16 卡、TP=2、PP=1 的配置，而标准版使用 8 卡、TP=1、PP=2。具体含义以脚本内容和相关文档为准。

四、阶段一：数据准备

4.1 预训练数据处理

data_convert_qwen3_pretrain.sh 将原始预训练语料（示例输入为 parquet 格式）切词并落盘为训练入口可读取的索引化数据：

# 修改 ascend-toolkit 路径 source /usr/local/Ascend/ascend-toolkit/set_env.sh mkdir ./dataset python ./preprocess_data.py \ --input ./dataset/train-00000-of-00042-d964455e17e96d5a.parquet \ --tokenizer-name-or-path ./model_from_hf/qwen3_hf/ \ --tokenizer-type PretrainedFromHF \ --handler-name GeneralPretrainHandler \ --output-prefix ./dataset/enwiki \ --json-keys text \ --workers 4 \ --log-interval 1000

关键参数说明：

• --handler-name GeneralPretrainHandler：指定预训练数据处理逻辑，与训练脚本中的--handler-name GeneralPretrainHandler保持一致，保证数据格式可被训练入口直接读取。
• --tokenizer-type PretrainedFromHF与--tokenizer-name-or-path：从 Hugging Face 格式的 tokenizer 目录加载分词器。
• --json-keys text：抽取语料 JSON 中的文本字段。
• --output-prefix ./dataset/enwiki：输出文件前缀，训练时--data-path即指向此前缀。
• --workers 4：并行处理进程数；--log-interval 1000：每处理 1000 条样本打印一次进度。

4.2 指令微调数据处理

data_convert_qwen3_instruction.sh 处理指令微调数据，与全参/LoRA 微调脚本中的AlpacaStyleInstructionHandler一一对应：

# 请按照您的真实环境修改 set_env.sh 路径 source /usr/local/Ascend/ascend-toolkit/set_env.sh mkdir ./finetune_dataset python ./preprocess_data.py \ --input ./dataset/train-00000-of-00001-a09b74b3ef9c3b56.parquet \ --tokenizer-name-or-path ./model_from_hf/qwen3_hf/ \ --output-prefix ./finetune_dataset/alpaca \ --handler-name AlpacaStyleInstructionHandler \ --tokenizer-type PretrainedFromHF \ --workers 4 \ --log-interval 1000 \ --enable-thinking true \ --prompt-type qwen3

与预训练数据处理相比，指令数据链路额外引入了两个 Qwen3 专属参数：

• --enable-thinking true：保留并正确处理 Qwen3 的思考（thinking）过程字段，与微调脚本--enable-thinking true配套使用。
• --prompt-type qwen3：采用 Qwen3 的对话模板拼接 prompt 与 response，微调脚本中的--prompt-type qwen3与此保持一致。

更通用的数据格式（如 ShareGPT 风格）可参考 data_process_sft_sharegpt_style.md 与 data_process_sft_alpaca_style.md。

五、阶段二：权重格式转换

权重转换统一使用仓库根目录的 convert_ckpt_v2.py。从该入口源码（convert_ckpt_v2.py）可见，转换方向由--load-model-type/--save-model-type组合决定：hf→mg走Hf2MgConvert，mg→hf走Mg2HfConvert；--model-type-hf支持qwen3、qwen3-moe、deepseek3、llama2、glm5等十余种模型类型，默认即为qwen3。

5.1 HF 权重转 mcore

ckpt_convert_qwen3_hf2mcore.sh 将 Hugging Face 权重转换为 mcore 训练、推理或评估可用格式，并可指定目标并行切分：

# 修改 ascend-toolkit 路径 export CUDA_DEVICE_MAX_CONNECTIONS=1 source /usr/local/Ascend/ascend-toolkit/set_env.sh python convert_ckpt_v2.py \ --load-model-type hf \ --save-model-type mg \ --target-tensor-parallel-size 1 \ --target-pipeline-parallel-size 8 \ --load-dir ./model_from_hf/qwen3_hf/ \ --save-dir ./model_weights/qwen3_mcore/ \ --model-type-hf qwen3

• --target-tensor-parallel-size/--target-pipeline-parallel-size：指定转换后权重按多大的 TP、PP 切分保存（对应训练时的--tensor-model-parallel-size/--pipeline-model-parallel-size）。示例中 TP=1、PP=8 的切分需与后续训练脚本的并行配置严格一致。
• --model-type-hf qwen3：声明源模型为 Qwen3 结构，转换器据此完成层名与张量布局映射。

5.2 mcore 权重转 HF

ckpt_convert_qwen3_mcore2hf.sh 将训练得到的 mcore 权重转回 Hugging Face 格式，用于模型发布或接入 HF 生态工具：

# 修改 ascend-toolkit 路径 source /usr/local/Ascend/ascend-toolkit/set_env.sh export CUDA_DEVICE_MAX_CONNECTIONS=1 python convert_ckpt_v2.py \ --load-model-type mg \ --save-model-type hf \ --load-dir ./model_weights/qwen3_mcore/ \ --save-dir ./hf_weights/qwen3_hf/ \ --hf-cfg-dir ./origin_hf_cfg \ --model-type-hf qwen3

--hf-cfg-dir指向原始 Hugging Face 权重目录，用于读取config.json等元信息，保证转换出的 HF 模型结构与原模型一致。

5.3 LoRA 权重合并转 HF

ckpt_convert_qwen3_mcore2hf_lora.sh 将 mcore 基座权重与 LoRA 增量权重合并后输出 HF 格式：

# 修改 ascend-toolkit 路径 source /usr/local/Ascend/ascend-toolkit/set_env.sh export CUDA_DEVICE_MAX_CONNECTIONS=1 python convert_ckpt_v2.py \ --load-model-type mg \ --save-model-type hf \ --lora-r 8 \ --lora-alpha 16 \ --lora-target-modules linear_qkv linear_proj linear_fc1 linear_fc2 \ --load-dir ./model_weights/qwen3_mcore/ \ --lora-load ./ckpt/qwen3_lora \ --save-dir ./model_from_hf/qwen3_hf/ \ --hf-cfg-dir ./model_from_hf/qwen3_hf/ \ --model-type-hf qwen3

LoRA 参数（--lora-r、--lora-alpha、--lora-target-modules）须与 LoRA 微调时的配置一致，其中--lora-target-modules覆盖linear_qkv、linear_proj、linear_fc1、linear_fc2四个线性层，与微调脚本中的目标模块完全对应。

六、阶段三：预训练

6.1 标准 8 卡示例（TP=1, PP=2）

pretrain_qwen3_8b_4K_ptd.sh 是 Qwen3 8B 在 4K 序列长度下的 mcore 预训练主示例，先设定昇腾环境变量与分布式参数：

export HCCL_CONNECT_TIMEOUT=3600 export HCCL_EXEC_TIMEOUT=3600 export CUDA_DEVICE_MAX_CONNECTIONS=1 export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True export NPU_ASD_ENABLE=0 export TASK_QUEUE_ENABLE=2 NPUS_PER_NODE=8 MASTER_ADDR=localhost MASTER_PORT=6000 NNODES=1 NODE_RANK=0 WORLD_SIZE=$(($NPUS_PER_NODE*$NNODES))

其中HCCL_CONNECT_TIMEOUT/HCCL_EXEC_TIMEOUT放宽了 HCCL 建连与执行超时（3600 秒），PYTORCH_NPU_ALLOC_CONF=expandable_segments:True开启可扩展内存段以降低显存碎片。核心训练规模变量为TP=1、PP=2、CP=1、MBS=1、GBS=64、SEQ_LENGTH=4096、TRAIN_ITERS=2000。

模型结构参数（GPT_ARGS 块）完整定义了 Qwen3 8B 规格，是理解整条链路的关键：

优化与性能参数（OPTIMIZE_ARGS / TRAIN_ARGS）方面：--use-flash-attn、--use-fused-rotary-pos-emb、--use-fused-swiglu、--use-fused-rmsnorm启用融合算子；--use-distributed-optimizer --reuse-fp32-param --overlap-grad-reduce --overlap-param-gather --use-ascend-coc组合了分布式优化器、FP32 参数复用、梯度归约/参数聚合通信重叠与昇腾 COC（计算通信并发）优化；训练超参为lr 1.25e-6、min-lr 1.25e-7、cosine 衰减、lr-warmup-fraction 0.01、weight-decay 1e-1、clip-grad 1.0、adam-beta1 0.9、beta2 0.95、initial-loss-scale 4096、seed 42、--bf16。

数据与输出参数：--handler-name GeneralPretrainHandler、--data-path $DATA_PATH、--split 100,0,0（全部用于训练）；--log-interval 1、--save-interval 2000、--eval-interval 2000、--eval-iters 0、--no-load-optim --no-load-rng（断点续训时不加载优化器与随机数状态，从零初始化训练时使用）。

启动命令以torchrun拉起 8 进程执行仓库根目录的 pretrain_gpt.py，并通过--load ${CKPT_LOAD_DIR}、--save ${CKPT_SAVE_DIR}、--distributed-backend nccl、--transformer-impl local、--enable-hf2mg-convert、--model-type-hf qwen3完成加载与自动权重转换，日志通过tee落盘至logs/train_mcore_qwen3_8b.log。

6.2 A3 变体（TP=2, PP=1）

pretrain_qwen3_8b_4K_ptd_A3.sh 面向特定硬件或集群配置场景，与标准版的关键差异如下：

• 单节点 16 卡（NPUS_PER_NODE=16），TP=2、PP=1、GBS=128，即更侧重张量并行而非流水线并行。
• 将--enable-hf2mg-convert --model-type-hf qwen3抽离为独立的CKPT_ARGS变量组，数据参数中不再单独出现--workers，整体结构与标准版略有差异，但模型结构参数（36 层 / 4096 隐藏 / GQA-8 / padded-vocab 151936 等）保持一致。

在多机场景下，将MASTER_ADDR改为实际主节点 IP，NNODES改为节点数，并按 rank 设置NODE_RANK即可扩展。

七、阶段四：指令微调

7.1 全参微调

tune_qwen3_8b_4K_full_ptd.sh 使用 posttrain_gpt.py 作为入口，以--finetune --stage sft --is-instruction-dataset --prompt-type qwen3 --no-pad-to-seq-lengths声明 SFT 阶段：

• 数据侧：--handler-name AlpacaStyleInstructionHandler、--enable-thinking true、--prompt-type qwen3，与指令数据处理脚本的参数一一对应；--no-pad-to-seq-lengths允许样本不强制 padding 到固定长度。
• 模型侧：除与预训练相同的结构参数外，额外出现--kv-channels 128（GQA 场景下显式指定 KV 通道数）与--sequence-parallel（序列并行）。
• 训练配置：MBS=1、GBS=16，--max-position-embeddings 32768（在 4K 训练序列长度之上预留更长位置编码空间），--exit-on-missing-checkpoint在检查点缺失时直接退出以避免无效训练，保存间隔--save-interval 1000。
• 检查点加载同样支持--enable-hf2mg-convert --model-type-hf qwen3，可直接从 HF 基座权重开始微调。

7.2 LoRA 微调

tune_qwen3_8b_4K_lora_ptd.sh 在 SFT 参数基础上叠加 LoRA 配置：

TUNE_ARGS=" --finetune \ --stage sft \ --is-instruction-dataset \ --tokenizer-not-use-fast \ --prompt-type qwen3 \ --no-pad-to-seq-lengths \ --lora-r 16 \ --lora-alpha 32 \ --lora-fusion \ --lora-target-modules linear_qkv linear_proj linear_fc1 linear_fc2 "

• --lora-r 16/--lora-alpha 32：LoRA 秩与缩放系数（实际秩 =lora-alpha / lora-r = 2），这两个值必须与后续 ckpt_convert_qwen3_mcore2hf_lora.sh 中的--lora-r 8 --lora-alpha 16对应配置保持自洽（注意示例中转换脚本的秩不同，合并前需按实际训练值修改）。
• --lora-fusion：将 LoRA 增量融合进基座权重，便于推理或后续转换。
• --lora-target-modules：指定注入 LoRA 的线性层，覆盖linear_qkv、linear_proj、linear_fc1、linear_fc2。
• 与全参微调的差异还包括：MBS=4、GBS=16、lr 1.25e-5（LoRA 场景通常采用更高学习率），并出现--no-shared-storage（非共享存储场景下的保存语义）。

LoRA 微调的完整流程（含多轮对话、数据组织）可进一步参考 lora_finetune.md 与 instruction_finetune.md。

八、阶段五：推理生成

generate_qwen3_8b_ptd.sh 使用 inference.py 加载训练或转换后的权重进行文本生成：

• 运行配置：TP=1、PP=2、SEQ_LENGTH=4096、--micro-batch-size 1、--max-new-tokens 256（单次生成的最大新 token 数）。
• 模型参数与训练脚本保持一致（36 层 / 4096 隐藏 / GQA-8 /--qk-layernorm/--rotary-base 1000000/ padded-vocab 151936 等），并额外开启--use-fused-swiglu --use-fused-rmsnorm --use-fused-rotary-pos-emb融合算子以提升解码性能。
• --tokenizer-not-use-fast：关闭 HF 快速 tokenizer（与部分昇腾分词器实现兼容）。
• --load ${CHECKPOINT}指定模型权重目录，--exit-on-missing-checkpoint保证权重缺失时快速失败；--transformer-impl local与--ckpt-format torch与训练阶段保持一致，保证检查点可直接复用。

推理入口的通用能力（chat 模板、多轮对话等）可参考 inference.md 与 chat.md。

九、阶段六：模型评估

evaluate_qwen3_8b_ptd.sh 使用 evaluation.py 运行 benchmark 任务，默认任务为 MMLU（TASK="mmlu"）：

• 通过--task-data-path ${DATA_PATH}指定评估数据集路径，--task ${TASK}指定任务名，支持替换为其他任务（如 CEval、CMMLU、GSM8K 等，参见 evaluation_guide.md）。
• 运行配置为TP=1、PP=1、--micro-batch-size 1、--max-new-tokens 2（选择题类 benchmark 只需少量生成 token）、--no-chat-template（评测时不套 chat 模板）。
• 模型结构参数与训练/推理脚本保持一致；--no-load-rng --no-load-optim --bf16保证评估过程不依赖训练状态。

十、模型规格底层解析：qwen3_spec

训练、微调、推理、评估脚本中统一出现的--spec mindspeed_llm.tasks.models.spec.qwen3_spec layer_spec指向仓库内的 qwen3_spec.py。该模块通过 Megatron-Core 的ModuleSpec机制声明 Qwen3 Transformer Layer 的完整子模块结构：

• 输入归一化input_layernorm使用PTNorm（昇腾适配的 LayerNorm），注意力self_attention采用因果掩码AttnMaskType.causal，linear_qkv用列并行线性层、linear_proj用行并行线性层。
• 当--qk-layernorm开启时，Q、K 上会附加q_layernorm/k_layernorm；同时通过sharded_state_dict_keys_map将input_layernorm、pre_mlp_layernorm映射到 QKV 与 FC1 内嵌的 LayerNorm 张量上，确保检查点状态字典的加载/保存与 Qwen3 原生权重布局对齐。
• 该文件同时根据--transformer-impl自动切换实现：local模式使用原生DotProductAttention，transformer_engine模式则切换到 TE 系列算子，与各脚本中的--transformer-impl local设定相印证。

可以推断：脚本中--qk-layernorm、--group-query-attention、--num-query-groups 8、--swiglu等参数正是为了让 mcore 通用 Transformer 框架还原出 Qwen3 的 GQA + QK-Norm + SwiGLU 结构，这也是 Qwen3 系列模型区别于传统 GPT 结构的关键所在。

十一、运行与调整前检查清单

README 明确要求：运行或调整脚本前，建议先确认以下内容：

1. 数据、权重、tokenizer、日志和输出目录已替换为实际路径（脚本中CKPT_SAVE_DIR、DATA_PATH、TOKENIZER_PATH、CKPT_LOAD_DIR等占位符必须全部替换）。
2. 模型规模相关参数与目标权重一致（如--num-layers 36、--hidden-size 4096、--padded-vocab-size 151936需与 Qwen3-8B 实际配置相符）。
3. TP、PP、CP 等并行参数与硬件数量和权重切分方式匹配（若权重已按 TP=1、PP=8 预转换，训练时并行配置必须一致；A3 脚本的 TP=2、PP=1 亦须与 16 卡拓扑对应）。
4. 数据处理、权重转换、训练、推理和评估阶段使用的路径前后一致（--output-prefix→--data-path、--save-dir→--load等链路不能断点）。
5. 多机训练时，主节点地址、端口、节点数和节点序号配置正确（MASTER_ADDR、MASTER_PORT、NNODES、NODE_RANK）。

十二、常见问题与排查建议

结合脚本内容与源码，以下排查点具有实操价值：

• 检查点缺失导致训练/推理中断：确认脚本中是否包含--exit-on-missing-checkpoint（微调、推理、评估脚本均有）；预训练脚本从零开始时使用--no-load-optim --no-load-rng避免加载不存在的优化器状态。
• 并行切分不一致：预转换权重（--target-tensor-parallel-size/--target-pipeline-parallel-size）与训练脚本的--tensor-model-parallel-size/--pipeline-model-parallel-size必须完全对齐，否则会因状态字典 shape 不匹配而加载失败。
• LoRA 参数不自洽：微调的--lora-r/--lora-alpha/--lora-target-modules与 mcore2hf_lora 转换脚本必须保持逻辑一致，否则合并出的 HF 权重结构与训练时不同。
• 数据与 handler 不匹配：预训练用GeneralPretrainHandler，指令微调用AlpacaStyleInstructionHandler，数据处理与训练两个阶段必须配对使用；Qwen3 场景还需同步开启--enable-thinking true与--prompt-type qwen3。
• 超时与资源类错误：可参照预训练脚本头部环境变量，适当调大HCCL_CONNECT_TIMEOUT/HCCL_EXEC_TIMEOUT，并开启PYTORCH_NPU_ALLOC_CONF=expandable_segments:True缓解显存碎片问题。

按"数据处理 → 权重转换 → 预训练/微调 → 推理 → 评估"的链路逐阶段打通，即可基于 MindSpeed-LLM 完成 Qwen3 8B 在昇腾 NPU 上的完整 mcore 训练闭环；在此基础上替换模型规格参数并同步调整并行配置，即可迁移到其他规模的 Qwen3 系列模型。

• 人工智能
• 大模型
• 分布式训练
• 预训练
• 微调
• 模型推理服务
• 强化学习
• Ascend