LLaMA-Factory微调Hy4 preview：hy_v4模板注册与FSDP加速实战

LLaMA-Factory微调Hy4 preview：hy_v4模板注册与FSDP加速实战

【免费下载链接】Hy4-previewHy4 preview 是由腾讯混元团队研发的新一代混合专家（MoE）旗舰模型。模型总参数量 770B，每个 token 激活 49B，主干共包含78层，第一层采用标准 FFN，其余 77 层均为 MoE 结构，每层包含 256 个路由专家与 1 个共享专家，每个 token 激活 top-8 路由专家及共享专家。主干之外原生内置 1 层 MTP（总参数量 10B，激活 0.7B）以支持投机解码。项目地址: https://ai.gitcode.com/tencent_hunyuan/Hy4-preview

腾讯混元旗舰 MoE 模型Hy4 preview（总参数 770B、每 token 激活 49B）现已开源完整微调方案。本文以LLaMA-Factory 微调为主线，手把手带你完成hy_v4 对话模板注册与FSDP 加速，覆盖 LoRA 微调、全量微调与慢思考（CoT）训练，帮助你在多机多卡上跑通 770B 级模型训练。

一、为什么用 LLaMA-Factory 微调 Hy4 preview

Hy4 preview 是腾讯混元团队研发的混合专家（MoE）旗舰模型，核心规格如下：

官方在 finetune/ 目录下提供三套微调方案，其中 llama_factory_support/ 面向熟悉 LLaMA-Factory 的用户，脚本、补丁与配置文件开箱即用。

二、快速上手：一键启动微调

1. 克隆仓库并安装依赖

git clone https://gitcode.com/tencent_hunyuan/Hy4-preview cd Hy4-preview/finetune pip install -r requirements.txt

依赖清单见 requirements.txt：transformers>=5.16.2、torch>=2.10.0、accelerate>=1.11.0、peft>=0.18.1、deepspeed>=0.18.7、flash-attn等；同时需按 LLaMA-Factory 官方指引完成其自身安装。

2. 修改启动脚本

编辑 train_lf.sh，设置显卡数与节点 IP：

export HOST_GPU_NUM=8 # 单机保持默认；多机填 IP 列表，如 "192.168.1.1,192.168.1.2" export IP_LIST=${IP_LIST:-"127.0.0.1"}

如需切换 LoRA 配置，通过环境变量指定 YAML：

export YAML_FILE=hy_v4_lora_sft.yaml

3. 启动训练

在每一台机器的 llama_factory_support/ 目录下执行：

bash train_lf.sh

脚本通过torchrun拉起分布式进程，每个进程运行 train_hy_v4.py 并自动注入全部 HYV4 补丁。

💡 硬件参考（最小配置）：LoRA 微调约8 机 64 卡、全量微调约16 机 128 卡，每卡显存 ≥96GB，每机 CPU 内存 ≥2TB。详见 README_CN.md。

三、hy_v4 对话模板注册详解

模板注册是微调正确性的关键。hy_v4_template.py 用register_template向 LLaMA-Factory 注册名为hy_v4的模板。

1. Token 格式

对话每一轮遵循如下结构（对应 chat_template.jinja）：

Loss 掩码：仅对 assistant 内容（含 EOS）计算损失，system / user 部分不参与。

2. 快思考与慢思考

模板采用ReasoningTemplate并配置thought_words=("<think:opensource>", "</think:opensource>")，从而正确屏蔽思考标签 token。

• 快思考：数据中不含<think:opensource>标签 → 模型学习直接作答。
• 慢思考（CoT）：assistant 内容中必须写入<think:opensource>...</think:opensource>标签，否则只能学到快思考。

⚠️ 是否有慢/快思考，完全由数据中是否存在 think 标签决定，请在训练慢思考能力时务必加入 think 标签。

3. 注册源码

核心注册代码见 hy_v4_template.py#L40-L50：

register_template( name="hy_v4", template_class=ReasoningTemplate, format_user=StringFormatter(slots=["<｜hy_start:opensource｜>user<｜hy_middle:opensource｜>{{content}}<｜hy_end:opensource｜>"]), format_assistant=StringFormatter(slots=["<｜hy_start:opensource｜>assistant<｜hy_middle:opensource｜>{{content}}<｜hy_end:opensource｜>"]), format_system=StringFormatter(slots=["<｜hy_start:opensource｜>system<｜hy_middle:opensource｜>{{content}}<｜hy_end:opensource｜>"]), thought_words=("<think:opensource>", "</think:opensource>"), stop_words=["<｜hy_end:opensource｜>"], efficient_eos=False, )

四、FSDP 加速实战

对LoRA 微调，官方推荐FSDP（Full Shard Data Parallel）：兼容性好、配置简单，全部配置内置于 hy_v4_lora_sft.yaml。

1. FSDP 配置

fsdp: true fsdp_config: version: 1 fsdp_sharding_strategy: FULL_SHARD fsdp_backward_prefetch: BACKWARD_PRE fsdp_state_dict_type: FULL_STATE_DICT fsdp_use_orig_params: true fsdp_cpu_ram_efficient_loading: true fsdp_offload_params: false fsdp_auto_wrap_policy: TRANSFORMER_BASED_WRAP fsdp_transformer_layer_cls_to_wrap: HYV4DecoderLayer

关键点：

• FULL_SHARD全切分参数 / 梯度 / 优化器状态，最大化显存节省。
• TRANSFORMER_BASED_WRAP+HYV4DecoderLayer：按解码器层切分，粒度合理、通信高效。
• fsdp_cpu_ram_efficient_loading: true：仅 local_rank 0 加载真实权重到 CPU，其余 rank 建 meta 模型，由 FSDP 广播，把单节点峰值 CPU 内存从N_ranks × 模型降到1 × 模型。

2. LoRA 目标模块

Hy4 preview 使用 MLA，LoRA 默认挂载在注意力投影层（见 hy_v4_lora_sft.yaml#L26-L30）：

lora_rank: 64 lora_alpha: 128 lora_dropout: 0.05 lora_target: q_a_proj,q_b_proj,kv_a_proj_with_mqa,kv_b_proj,o_proj

3. FSDP vs DeepSpeed 怎么选

全量微调的 DeepSpeed 配置见 hy_v4_full_sft.yaml 的deepspeed字段。

五、运行时补丁：让 770B 模型跑得动

train_hy_v4.py 启动时依次完成四件事：注册模板、应用补丁、注入回调、调用run_exp()。真正的"重活"在 hy_v4_patches.py，它通过 monkey-patch 解决了多个 770B 级工程难题：

此外，train_hy_v4.py#L54-L77 还针对ZeRO-3 + CPU offload场景跳过全局梯度范数计算（max_grad_norm=0时），避免 770B 模型在 optimizer step 处 NCCL 超时 / 死锁。

补丁在import hy_v4_patches时即自动生效（见 hy_v4_patches.py#L650-L654），无需手动调用。

六、训练数据与关键超参数

1. 数据格式

训练数据为 messages 结构（sharegpt 格式），示例见 example_data.jsonl：

{"messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "1+1=?"}, {"role": "assistant", "content": "1+1=2"}]}

在 dataset_info.json 中注册数据集（hy_v4_demo指向../data/example_data.jsonl）。

2. 学习率建议

两者均使用cosine_with_min_lr调度、bf16: true、gradient_checkpointing: true，并建议flash_attn: auto。

3. 其他常用参数

• cutoff_len：最大序列长度，LoRA 可适当调小省显存。
• max_samples：限制使用的样本数（示例默认 1000）。
• save_steps/logging_steps：存盘与日志间隔。
• report_to：可选none / wandb / tensorboard / swanlab / mlflow。

七、常见问题 FAQ

Q1：启动时提示线性层 bias 未加载？Hy4 preview 的线性层（q_a_proj 等）不使用 bias，可忽略；但 MoE 路由的e_score_correction_bias属于 buffer，由补丁自动加载，若加载失败请勿忽略。

Q2：LoRA 训练只保存 LoRA 权重？是的。LoRA 微调只保存适配器权重，不保存 base 模型权重，推理时需合并或加载对应 base。

Q3：想断点续训怎么做？将resume_from_checkpoint设为已有 checkpoint 路径，且不要同时指定model_name_or_path（后者只加载权重不加载训练状态）。续训 loss 可能有微小偏差，属正常现象。

Q4：全量微调 CPU OOM？Patch 3 的分片加载已把 CPU 内存降到约 7GB/rank；若仍不足，可尝试调小cutoff_len、降低per_device_train_batch_size或改用 offload 配置。

小结

• 模板注册：hy_v4模板 +ReasoningTemplate决定 token 切分与慢 / 快思考行为，是训练正确性的基石。
• FSDP 加速：LoRA 用 FSDP、全量用 ZeRO-3+Offload，二者按需二选一。
• 运行时补丁：自动解决 ZeRO-3 加载、分片加载、dtype 统一等 770B 工程难题。

掌握以上三步，你就能在 llama_factory_support/ 目录下快速跑通 Hy4 preview 的微调任务。

【免费下载链接】Hy4-previewHy4 preview 是由腾讯混元团队研发的新一代混合专家（MoE）旗舰模型。模型总参数量 770B，每个 token 激活 49B，主干共包含78层，第一层采用标准 FFN，其余 77 层均为 MoE 结构，每层包含 256 个路由专家与 1 个共享专家，每个 token 激活 top-8 路由专家及共享专家。主干之外原生内置 1 层 MTP（总参数量 10B，激活 0.7B）以支持投机解码。项目地址: https://ai.gitcode.com/tencent_hunyuan/Hy4-preview