大模型人工智能教程本地部署微调【免费下载链接】self-llm《开源大模型食用指南》针对中国宝宝量身打造的基于Linux环境快速微调全参数/Lora、部署国内外开源大模型LLM/多模态大模型MLLM教程项目地址https://gitcode.com/datawhalechina/self-llm点击查看免费下载本文以腾讯混元开源模型 Hunyuan-A13B-Instruct 为例完整讲解在 Linux 环境下从环境配置、模型下载、数据集构建到 LoRA 有监督微调SFT的端到端流程并集成 SwanLab 完成训练过程的实时记录与可视化分析。读完本文你将掌握混合推理大模型的 Chat Template 适配技巧、process_func数据预处理范式、LoraConfig/TrainingArguments的核心参数含义以及微调后使用PeftModel加载 LoRA 权重进行推理的完整方案可直接复用到其他同架构模型。本教程的配套代码以 Jupyter Notebook 形式保存在仓库的 05-Hunyuan-A13B-Instruct-LoRA.ipynb 中可对照本文逐步运行。Hunyuan-A13B-Instruct 与 LoRA 微调背景Hunyuan-A13B-Instruct 是腾讯混元大模型的开源指令微调版本采用大规模稀疏专家MoE架构包含 1 个共享专家与 64 个细粒度非共享专家训练阶段同时激活 8 个并引入 SwiGLU 激活函数、Grouped-Query AttentionGQA以及快思考 慢思考双模式推理链框架。关于架构的详细解析可参考仓库文档 01-Hunyuan-A13B-Instruct 模型架构解析 Blog.md。LoRALow-Rank Adaptation低秩适配的核心思想是冻结预训练模型的全部原始权重仅在大模型原有的线性层旁路插入低秩分解矩阵进行训练。其显著优势包括显存占用低只优化少量低秩参数对单卡资源有限的场景非常友好训练速度快反向传播仅更新可训练的旁路参数权重可插拔训练产物是体积很小的 adapter 权重推理时可随时合并或切换不影响原始模型训练记录可复现配合训练日志工具可完整留存每次实验的超参数与指标曲线。正是由于上述特性LoRA 成为在消费级/单卡环境下微调大模型的常用方案也是本教程采用的微调方式。环境配置微调环境建议基于 AutoDL 等提供 GPU 的 Linux 云平台搭建。本教程使用的关键依赖及版本如下# 换清华镜像源 !pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple !pip install modelscope1.25.0 !pip install transformers4.51.3 !pip install accelerate1.6.0 !pip install datasets3.5.1 !pip install peft0.15.2 !pip install swanlab0.5.7 !pip install tiktoken各依赖在流程中的角色依赖版本作用modelscope1.25.0从魔搭社区下载模型权重国内网络友好transformers4.51.3加载模型与 tokenizer、提供Trainer训练框架accelerate1.6.0分布式/多卡训练的底层支持device_mapauto依赖datasets3.5.1构建与处理训练数据集peft0.15.2提供LoraConfig、get_peft_model、PeftModel等 LoRA 能力swanlab0.5.7训练过程的可视化记录与实验对比tiktoken-混元分词器依赖的 BPE 编码实现考虑到部分同学配置环境可能会遇到一些问题本仓库在 AutoDL 平台准备了 Hunyuan-A13B-Instruct 的环境镜像可直接创建 AutoDL 示例快速复用。模型下载使用modelscope的snapshot_download接口下载模型首次运行会拉取全部权重文件包括模型的hunyuan.py等trust_remote_code依赖文件# model_download.py # 注意修改cache_dir为保存的路径 from modelscope import snapshot_download model_dir snapshot_download(Tencent-Hunyuan/Hunyuan-A13B-Instruct, cache_dir/root/autodl-tmp, revisionmaster) ###可以根据自己需要修改下载模型所在的存储路径:cache_dir print(f模型下载完成保存路径为{model_dir})参数说明Tencent-Hunyuan/Hunyuan-A13B-Instruct模型在 ModelScope 上的仓库 IDcache_dir模型保存路径示例中为/root/autodl-tmp可按需修改revision模型版本分支示例中为master。注意事项在模型下载完成后需要修改模型文件夹下的hunyuan.py文件在开头加入以下代码以解决该模型远程代码在部分环境下的日志初始化问题import logging logger logging.getLogger(__name__)该文件位于模型权重目录如/root/autodl-tmp/Tencent-Hunyuan/Hunyuan-A13B-Instruct/hunyuan.py加载模型时通过trust_remote_codeTrue执行。数据集构建对大语言模型进行有监督微调SFT的数据格式如下{ instruction: 回答以下用户问题仅输出答案。, input: 11等于几?, output: 2 }其中instruction是用户指令告知模型其需要完成的任务input是用户输入是完成用户指令所必须的输入内容output是模型应该给出的输出。有监督微调的目标是让模型具备理解并遵循用户指令的能力。因此在构建数据集时应针对目标任务针对性构建数据。本教程以角色扮演role-play场景为例目标是通过大量人物对话数据微调得到一个能够扮演甄嬛对话风格的模型该场景下的数据示例如下{ instruction: 你父亲是谁, input: , output: 家父是大理寺少卿甄远道。 }仓库中所有示例微调数据集位于 dataset/huanhuan.json该文件共包含数千条甄嬛体对话样本均为instruction/input/output三字段结构可直接用于本教程的微调流程例如{ instruction: 娘娘。, input: , output: 你放心本宫到任何时候都不会自轻自贱委屈了这孩子。 }如果你希望训练自定义任务只需按照相同的三字段结构构建自己的 JSON 数据即可无需改动后续代码。数据准备process_func 预处理LoRA 训练的数据需要经过格式化、编码之后再输入给模型。核心流程是将输入文本编码为input_ids将输出文本编码为labels编码之后的结果是向量。首先定义一个预处理函数对每一个样本同时编码其输入、输出文本并返回一个编码后的字典def process_func(example): MAX_LENGTH 1024 # 设置最大序列长度为1024个token input_ids, attention_mask, labels [], [], [] # 初始化返回值 # 适配chat_template instruction tokenizer( fs|im_start|system\n现在你要扮演皇帝身边的女人--甄嬛|im_end|\n f|im_start|user\n{example[instruction] example[input]}|im_end|\n f|im_start|assistant\nthink\n\n/think\n\n, add_special_tokensFalse ) response tokenizer(f{example[output]}, add_special_tokensFalse) # 将instruction部分和response部分的input_ids拼接并在末尾添加eos token作为标记结束的token input_ids instruction[input_ids] response[input_ids] [tokenizer.pad_token_id] # 注意力掩码表示模型需要关注的位置 attention_mask instruction[attention_mask] response[attention_mask] [1] # 对于instruction使用-100表示这些位置不计算loss即模型不需要预测这部分 labels [-100] * len(instruction[input_ids]) response[input_ids] [tokenizer.pad_token_id] if len(input_ids) MAX_LENGTH: # 超出最大序列长度截断 input_ids input_ids[:MAX_LENGTH] attention_mask attention_mask[:MAX_LENGTH] labels labels[:MAX_LENGTH] return { input_ids: input_ids, attention_mask: attention_mask, labels: labels }该函数的三个关键设计点labels中 instruction 部分用-100填充在训练时-100位置的 token 不参与损失计算即模型只学习预测输出而不学习预测输入这是 SFT 的标准做法末尾追加pad_token_id作为序列结束标记同时attention_mask对应位置补1保证结束符也参与注意力计算MAX_LENGTH 1024截断防止超长样本导致显存溢出超出部分直接切片丢弃。Chat Template 与混合推理模型的思考模式Hunyuan-A13B-Instruct 的 Chat Template 格式如下messages [ {role: system, content: system_message_test}, {role: user, content: user_message_test}, {role: assistant, content: assistant_message_test}, ]由于 Hunyuan-A13B-Instruct 是混合推理模型因此可以手动选择开启思考模式thinking mode。不开启 thinking mode时messages [ {role: system, content: system_message_test}, {role: user, content: user_message_test}, {role: assistant, content: assistant_message_test}, ] text tokenizer.apply_chat_template( messages, tokenizeFalse, add_generation_promptTrue, enable_thinkingFalse ) print(text)输出|im_start|system system_message_test|im_end| |im_start|user user_message_test|im_end| |im_start|assistant think /think assistant_message_test|im_end| |im_start|assistant think /think开启 thinking mode时messages [ {role: system, content: system_message_test}, {role: user, content: user_message_test}, {role: assistant, content: assistant_message_test}, ] text tokenizer.apply_chat_template( messages, tokenizeFalse, add_generation_promptTrue, enable_thinkingTrue ) print(text)输出|im_start|system system_message_test|im_end| |im_start|user user_message_test|im_end| |im_start|assistant think /think assistant_message_test|im_end| |im_start|assistant可以看到两种模式的模板结构都以|im_start|assistant\nthink\n\n/think\n\n开头。区别在于enable_thinkingFalse时在思考块之后仍会拼接assistant_message_test及第二个|im_start|assistant提示用于在训练时让模型同时学习输出内容而enable_thinkingTrue时则以一个空的思考块 assistant起始标记结尾推理时模型会先生成思考内容再生成answer答案。训练数据的格式化即process_func中的模板必须与模型实际的 Chat Template 保持一致否则会造成训练与推理分布不一致这正是本教程在预处理阶段手工拼写该模板的原因。加载模型和 tokenizer加载模型时统一使用trust_remote_codeTrue使 transformers 执行模型目录下的远程代码hunyuan.py并使用torch.bfloat16半精度以降低显存占用mode_path /root/autodl-tmp/Tencent-Hunyuan/Hunyuan-A13B-Instruct # 加载tokenizer tokenizer AutoTokenizer.from_pretrained(mode_path, trust_remote_codeTrue) # 加载模型 model AutoModelForCausalLM.from_pretrained(mode_path, device_mapauto,torch_dtypetorch.bfloat16, trust_remote_codeTrue)说明device_mapauto由 accelerate 自动分配模型层到可用 GPU/CPUtorch_dtypetorch.bfloat16使用 BF16 精度兼顾训练稳定性与显存开销与仓库中其他模型微调案例如 examples/Chat-嬛嬛/train.py一致加载后建议调用model.enable_input_require_grads()以配合梯度检查点gradient checkpointing使用。Lora Config 配置LoraConfig是 peft 库中配置 LoRA 训练的核心类其中比较重要的参数如下task_type模型类型现在绝大部分decoder_only的模型都是因果语言模型CAUSAL_LMtarget_modules需要训练的模型层名字主要就是attention部分的层不同模型对应的层名字不同rLoRA 的秩决定低秩矩阵的维度较小的r意味着更少的参数lora_alpha缩放参数与r一起决定 LoRA 更新的强度实际缩放比例为lora_alpha / r在当前示例中是32 / 8 4倍lora_dropout应用于 LoRA 层的 dropout rate用于防止过拟合。config LoraConfig( task_typeTaskType.CAUSAL_LM, target_modules[q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj], inference_modeFalse, # 训练模式 r8, # Lora 秩 lora_alpha32, # Lora alpha lora_dropout0.1 # Dropout 比例 )配置解读target_modules覆盖了注意力四件套q/k/v/o_proj与 MoE 前馈网络的三组线性层gate/up/down_proj这是混元 A13B 模型可插入 LoRA 的全部关键投影层。使用get_peft_model(model, config)包裹模型后可通过model.print_trainable_parameters()打印实际可训练参数量r8、lora_alpha32意味着旁路矩阵的实际更新强度为 4 倍缩放这是社区实践中常用的低秩 较大缩放组合若显存紧张可尝试降低r如 4或提高lora_dropout如 0.15以减小过拟合风险。Training Arguments 训练参数TrainingArguments用于配置训练器的运行参数本教程中最关键的几个如下output_dir模型的输出路径checkpoint 保存目录per_device_train_batch_size每张卡上的batch_sizegradient_accumulation_steps梯度累积步数等效 batch size per_device_train_batch_size × gradient_accumulation_stepsnum_train_epochs训练轮数epoch。args TrainingArguments( output_dir./output/Hunyuan-A13B-Instruct, # 注意修改 per_device_train_batch_size4, gradient_accumulation_steps4, logging_steps10, num_train_epochs1, save_steps100, learning_rate1e-4, save_on_each_nodeTrue, gradient_checkpointingTrue, report_tonone, )参数说明与调参建议参数本示例值作用与建议output_dir./output/Hunyuan-A13B-Instructcheckpoint 与日志输出目录需按实际路径修改per_device_train_batch_size4单卡 batch size显存不足时可降至 12gradient_accumulation_steps4梯度累积等效总 batch 4×416显存有限时优先调大此值logging_steps10每 10 步打印一次训练日志num_train_epochs1训练 1 个 epoch数据量大时可保持 13save_steps100每 100 步保存一次 checkpoint训练结束后按此频率产出checkpoint-XXX目录learning_rate1e-4LoRA 常用学习率一般落在 1e-42e-5 区间save_on_each_nodeTrue多节点训练时每个节点都保存gradient_checkpointingTrue梯度检查点用少量计算换显存开启后需配合enable_input_require_grads()report_tonone关闭 transformers 自带的外部实验平台上报改由 SwanLab 回调负责记录SwanLab训练可视化与实验记录SwanLab 简介SwanLab 是一个开源的 AI 模型训练记录工具面向 AI 研究者提供训练可视化、自动日志记录、超参数记录、实验对比、多人协同等功能。在 SwanLab 上研究者能基于直观的可视化图表发现训练问题对比多个实验找到研究灵感并通过在线链接的分享与基于组织的多人协同训练打破团队沟通的壁垒。为什么要记录训练相较于软件开发模型训练更像一个实验科学。一个品质优秀的模型背后往往是成千上万次实验。研究者需要不断尝试、记录、对比、积累经验才能找到最佳的模型结构、超参数与数据配比。在这之中如何高效进行记录与对比对于研究效率的提升至关重要。实例化 SwanLabCallback建议先在 SwanLab 官网注册账号然后在训练初始化阶段选择(2) Use an existing SwanLab account并使用 private API Key 登录。import swanlab from swanlab.integration.transformers import SwanLabCallback # 实例化SwanLabCallback swanlab_callback SwanLabCallback( projectHunyuan-A13B-Instruct-Lora, # 注意修改 experiment_nameHunyuan-A13B-Instruct-LoRA-experiment # 注意修改 )SwanLabCallback是 SwanLab 为 HuggingFaceTrainer提供的官方回调实现它会自动捕获训练过程中的 loss、学习率、梯度范数、每步耗时等指标并随Trainer的训练循环自动上报无需在训练代码中手动埋点。使用 Trainer 训练将模型、参数、数据集与回调注入Trainer后启动训练。DataCollatorForSeq2Seq负责将 batch 内不同长度的序列 padding 到统一长度trainer Trainer( modelmodel, argsargs, train_datasettokenized_id, data_collatorDataCollatorForSeq2Seq(tokenizertokenizer, paddingTrue), callbacks[swanlab_callback] # 传入之前的swanlab_callback ) trainer.train()训练完成后会输出类似如下的统计信息TrainOutput(global_step233, training_loss3.3132195984345136, metrics{train_runtime: 4321.001, train_samples_per_second: 0.863, train_steps_per_second: 0.054, total_flos: 2.225441122839429e17, train_loss: 3.3132195984345136, epoch: 0.9989281886387996})关键指标解读global_step233共训练 233 步对应约 1 个 epoch与save_steps100配合会产生checkpoint-100、checkpoint-200等检查点train_loss3.313最终平均训练损失train_runtime4321秒总训练时长train_samples_per_second/train_steps_per_second吞吐指标用于评估训练效率。训练完成后打开 SwanLab 即可查看训练过程中记录的参数和可视化的训练 loss 曲线如上图所示loss 曲线随训练步数增加整体呈下降趋势训练初期下降较快随后趋于平稳约在 3.3 附近波动表明模型在持续优化。SwanLab 会自动记录超参数project、experiment_name、batch size、learning rate 等以及每个 step 的指标便于多实验横向对比。加载 LoRA 权重推理训练得到任意checkpoints之后使用PeftModel.from_pretrained加载 LoRA 权重进行推理from transformers import AutoModelForCausalLM, AutoTokenizer import torch from peft import PeftModel mode_path /root/autodl-tmp/Tencent-Hunyuan/Hunyuan-A13B-Instruct #这里修改实际的模型路径 lora_path /root/output/Hunyuan-A13B-Instruct/checkpoint-233 # 这里改成你的 lora 输出对应 checkpoint 地址 # 加载tokenizer tokenizer AutoTokenizer.from_pretrained(mode_path, trust_remote_codeTrue) # 加载模型 model AutoModelForCausalLM.from_pretrained(mode_path, device_mapauto,torch_dtypetorch.bfloat16, trust_remote_codeTrue) # 加载lora权重 model PeftModel.from_pretrained(model, model_idlora_path) import re messages [ {role: user, content: who are you?}, ] tokenized_chat tokenizer.apply_chat_template(messages, tokenizeTrue, return_tensorspt, enable_thinkingFalse # Toggle thinking mode (default: True) ) outputs model.generate(tokenized_chat.to(model.device), max_new_tokens4096) output_text tokenizer.decode(outputs[0]) answer_pattern ranswer(.*?)/answer answer_matches re.findall(answer_pattern, output_text, re.DOTALL) answer_content [match.strip() for match in answer_matches][0] print(fanswer_content:{answer_content}\n\n)推理要点lora_path指向 checkpoint 目录例如checkpoint-233目录内保存了adapter_config.json与adapter_model.safetensors等 LoRA 权重文件enable_thinkingFalse推理时可切换思考模式默认开启关闭后模型直接给出答案响应更快answer标签解析混元混合推理模型最终答案包裹在answer与/answer标签内因此使用正则ranswer(.*?)/answer提取最终回答内容re.DOTALL用于匹配跨行内容。运行结果示例answer_content:Im HunYuan, Tencents AI assistant. Im here to help you with any questions or tasks you have. How can I assist you today?常见问题与调优建议模型加载报 logging 相关错误按前文要求在模型目录下的hunyuan.py开头添加import logging与logger logging.getLogger(__name__)显存不足OOM降低per_device_train_batch_size、增大gradient_accumulation_steps或降低MAX_LENGTH截断长度同时保持gradient_checkpointingTrue微调后模型仍不会角色扮演检查训练数据量与格式建议不少于数百条对话、确认process_func中模板与 Chat Template 一致、适当增加num_train_epochs推理时无输出或输出为空确认enable_thinking参数与训练时一致并正确使用answer标签正则提取必要时将max_new_tokens调大示例中为 4096想要对比不同超参数的效果为每次实验更换experiment_name并保持同一project即可在 SwanLab 中横向对比多组实验的 loss 曲线。小结本文以 Hunyuan-A13B-Instruct 为例完成了从环境搭建、模型下载、SFT 数据集构建与预处理、LoRA 配置、训练参数设计、SwanLab 可视化记录到 LoRA 权重推理的完整闭环。核心要点可归纳为LoRA 微调只需冻结原模型并训练少量低秩旁路参数适合单卡/低显存环境混合推理模型的 Chat Template 适配是训练成败的关键训练模板必须与推理模板保持一致数据预处理中labels的-100掩码设计决定了模型只学习输出部分接入 SwanLab 的SwanLabCallback即可零侵入地完成训练指标的可视化与实验对比。该流程同样适用于仓库中其他同架构 MoE 模型的微调感兴趣的读者可进一步阅读 01-Hunyuan-A13B-Instruct 模型架构解析 Blog.md 了解模型内部机制或参考 05-Hunyuan-A13B-Instruct-LoRA.ipynb 直接运行完整代码。赞分享大模型人工智能教程本地部署微调【免费下载链接】self-llm《开源大模型食用指南》针对中国宝宝量身打造的基于Linux环境快速微调全参数/Lora、部署国内外开源大模型LLM/多模态大模型MLLM教程项目地址https://gitcode.com/datawhalechina/self-llm点击查看免费下载相关推荐Qwen2.5-7B-Instruct 法律问答 LoRA 微调实战基于 SwanLab 的全流程训练可视化与实验对比Qwen2.5 7B Instruct 法律问答 LoRA 微调实战基于 SwanLab 的全流程训练可视化与实验对比 本文以 Datawhale《开源大模型大模型人工智能教程本地部署微调Qwen2-VL-2B-Instruct LoRA 微调实战基于 COCO2014 图像描述任务与 SwanLab 全流程可视化Qwen2 VL 2B Instruct LoRA 微调实战基于 COCO2014 图像描述任务与 SwanLab 全流程可视化 本文是《开源大模型食用指南》大模型人工智能教程本地部署微调Qwen2.5-7B-Instruct LoRA 微调实战DISC-Law 法律问答数据集与 SwanLab 训练可视化全流程指南Qwen2.5 7B Instruct LoRA 微调实战DISC Law 法律问答数据集与 SwanLab 训练可视化全流程指南 导读 本文以 models教程大模型本地部署微调创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 基于 Hunyuan-A13B-Instruct 的 LoRA 微调与 SwanLab 训练可视化全流程实战
大模型人工智能教程本地部署微调【免费下载链接】self-llm《开源大模型食用指南》针对中国宝宝量身打造的基于Linux环境快速微调全参数/Lora、部署国内外开源大模型LLM/多模态大模型MLLM教程项目地址https://gitcode.com/datawhalechina/self-llm点击查看免费下载本文以腾讯混元开源模型 Hunyuan-A13B-Instruct 为例完整讲解在 Linux 环境下从环境配置、模型下载、数据集构建到 LoRA 有监督微调SFT的端到端流程并集成 SwanLab 完成训练过程的实时记录与可视化分析。读完本文你将掌握混合推理大模型的 Chat Template 适配技巧、process_func数据预处理范式、LoraConfig/TrainingArguments的核心参数含义以及微调后使用PeftModel加载 LoRA 权重进行推理的完整方案可直接复用到其他同架构模型。本教程的配套代码以 Jupyter Notebook 形式保存在仓库的 05-Hunyuan-A13B-Instruct-LoRA.ipynb 中可对照本文逐步运行。Hunyuan-A13B-Instruct 与 LoRA 微调背景Hunyuan-A13B-Instruct 是腾讯混元大模型的开源指令微调版本采用大规模稀疏专家MoE架构包含 1 个共享专家与 64 个细粒度非共享专家训练阶段同时激活 8 个并引入 SwiGLU 激活函数、Grouped-Query AttentionGQA以及快思考 慢思考双模式推理链框架。关于架构的详细解析可参考仓库文档 01-Hunyuan-A13B-Instruct 模型架构解析 Blog.md。LoRALow-Rank Adaptation低秩适配的核心思想是冻结预训练模型的全部原始权重仅在大模型原有的线性层旁路插入低秩分解矩阵进行训练。其显著优势包括显存占用低只优化少量低秩参数对单卡资源有限的场景非常友好训练速度快反向传播仅更新可训练的旁路参数权重可插拔训练产物是体积很小的 adapter 权重推理时可随时合并或切换不影响原始模型训练记录可复现配合训练日志工具可完整留存每次实验的超参数与指标曲线。正是由于上述特性LoRA 成为在消费级/单卡环境下微调大模型的常用方案也是本教程采用的微调方式。环境配置微调环境建议基于 AutoDL 等提供 GPU 的 Linux 云平台搭建。本教程使用的关键依赖及版本如下# 换清华镜像源 !pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple !pip install modelscope1.25.0 !pip install transformers4.51.3 !pip install accelerate1.6.0 !pip install datasets3.5.1 !pip install peft0.15.2 !pip install swanlab0.5.7 !pip install tiktoken各依赖在流程中的角色依赖版本作用modelscope1.25.0从魔搭社区下载模型权重国内网络友好transformers4.51.3加载模型与 tokenizer、提供Trainer训练框架accelerate1.6.0分布式/多卡训练的底层支持device_mapauto依赖datasets3.5.1构建与处理训练数据集peft0.15.2提供LoraConfig、get_peft_model、PeftModel等 LoRA 能力swanlab0.5.7训练过程的可视化记录与实验对比tiktoken-混元分词器依赖的 BPE 编码实现考虑到部分同学配置环境可能会遇到一些问题本仓库在 AutoDL 平台准备了 Hunyuan-A13B-Instruct 的环境镜像可直接创建 AutoDL 示例快速复用。模型下载使用modelscope的snapshot_download接口下载模型首次运行会拉取全部权重文件包括模型的hunyuan.py等trust_remote_code依赖文件# model_download.py # 注意修改cache_dir为保存的路径 from modelscope import snapshot_download model_dir snapshot_download(Tencent-Hunyuan/Hunyuan-A13B-Instruct, cache_dir/root/autodl-tmp, revisionmaster) ###可以根据自己需要修改下载模型所在的存储路径:cache_dir print(f模型下载完成保存路径为{model_dir})参数说明Tencent-Hunyuan/Hunyuan-A13B-Instruct模型在 ModelScope 上的仓库 IDcache_dir模型保存路径示例中为/root/autodl-tmp可按需修改revision模型版本分支示例中为master。注意事项在模型下载完成后需要修改模型文件夹下的hunyuan.py文件在开头加入以下代码以解决该模型远程代码在部分环境下的日志初始化问题import logging logger logging.getLogger(__name__)该文件位于模型权重目录如/root/autodl-tmp/Tencent-Hunyuan/Hunyuan-A13B-Instruct/hunyuan.py加载模型时通过trust_remote_codeTrue执行。数据集构建对大语言模型进行有监督微调SFT的数据格式如下{ instruction: 回答以下用户问题仅输出答案。, input: 11等于几?, output: 2 }其中instruction是用户指令告知模型其需要完成的任务input是用户输入是完成用户指令所必须的输入内容output是模型应该给出的输出。有监督微调的目标是让模型具备理解并遵循用户指令的能力。因此在构建数据集时应针对目标任务针对性构建数据。本教程以角色扮演role-play场景为例目标是通过大量人物对话数据微调得到一个能够扮演甄嬛对话风格的模型该场景下的数据示例如下{ instruction: 你父亲是谁, input: , output: 家父是大理寺少卿甄远道。 }仓库中所有示例微调数据集位于 dataset/huanhuan.json该文件共包含数千条甄嬛体对话样本均为instruction/input/output三字段结构可直接用于本教程的微调流程例如{ instruction: 娘娘。, input: , output: 你放心本宫到任何时候都不会自轻自贱委屈了这孩子。 }如果你希望训练自定义任务只需按照相同的三字段结构构建自己的 JSON 数据即可无需改动后续代码。数据准备process_func 预处理LoRA 训练的数据需要经过格式化、编码之后再输入给模型。核心流程是将输入文本编码为input_ids将输出文本编码为labels编码之后的结果是向量。首先定义一个预处理函数对每一个样本同时编码其输入、输出文本并返回一个编码后的字典def process_func(example): MAX_LENGTH 1024 # 设置最大序列长度为1024个token input_ids, attention_mask, labels [], [], [] # 初始化返回值 # 适配chat_template instruction tokenizer( fs|im_start|system\n现在你要扮演皇帝身边的女人--甄嬛|im_end|\n f|im_start|user\n{example[instruction] example[input]}|im_end|\n f|im_start|assistant\nthink\n\n/think\n\n, add_special_tokensFalse ) response tokenizer(f{example[output]}, add_special_tokensFalse) # 将instruction部分和response部分的input_ids拼接并在末尾添加eos token作为标记结束的token input_ids instruction[input_ids] response[input_ids] [tokenizer.pad_token_id] # 注意力掩码表示模型需要关注的位置 attention_mask instruction[attention_mask] response[attention_mask] [1] # 对于instruction使用-100表示这些位置不计算loss即模型不需要预测这部分 labels [-100] * len(instruction[input_ids]) response[input_ids] [tokenizer.pad_token_id] if len(input_ids) MAX_LENGTH: # 超出最大序列长度截断 input_ids input_ids[:MAX_LENGTH] attention_mask attention_mask[:MAX_LENGTH] labels labels[:MAX_LENGTH] return { input_ids: input_ids, attention_mask: attention_mask, labels: labels }该函数的三个关键设计点labels中 instruction 部分用-100填充在训练时-100位置的 token 不参与损失计算即模型只学习预测输出而不学习预测输入这是 SFT 的标准做法末尾追加pad_token_id作为序列结束标记同时attention_mask对应位置补1保证结束符也参与注意力计算MAX_LENGTH 1024截断防止超长样本导致显存溢出超出部分直接切片丢弃。Chat Template 与混合推理模型的思考模式Hunyuan-A13B-Instruct 的 Chat Template 格式如下messages [ {role: system, content: system_message_test}, {role: user, content: user_message_test}, {role: assistant, content: assistant_message_test}, ]由于 Hunyuan-A13B-Instruct 是混合推理模型因此可以手动选择开启思考模式thinking mode。不开启 thinking mode时messages [ {role: system, content: system_message_test}, {role: user, content: user_message_test}, {role: assistant, content: assistant_message_test}, ] text tokenizer.apply_chat_template( messages, tokenizeFalse, add_generation_promptTrue, enable_thinkingFalse ) print(text)输出|im_start|system system_message_test|im_end| |im_start|user user_message_test|im_end| |im_start|assistant think /think assistant_message_test|im_end| |im_start|assistant think /think开启 thinking mode时messages [ {role: system, content: system_message_test}, {role: user, content: user_message_test}, {role: assistant, content: assistant_message_test}, ] text tokenizer.apply_chat_template( messages, tokenizeFalse, add_generation_promptTrue, enable_thinkingTrue ) print(text)输出|im_start|system system_message_test|im_end| |im_start|user user_message_test|im_end| |im_start|assistant think /think assistant_message_test|im_end| |im_start|assistant可以看到两种模式的模板结构都以|im_start|assistant\nthink\n\n/think\n\n开头。区别在于enable_thinkingFalse时在思考块之后仍会拼接assistant_message_test及第二个|im_start|assistant提示用于在训练时让模型同时学习输出内容而enable_thinkingTrue时则以一个空的思考块 assistant起始标记结尾推理时模型会先生成思考内容再生成answer答案。训练数据的格式化即process_func中的模板必须与模型实际的 Chat Template 保持一致否则会造成训练与推理分布不一致这正是本教程在预处理阶段手工拼写该模板的原因。加载模型和 tokenizer加载模型时统一使用trust_remote_codeTrue使 transformers 执行模型目录下的远程代码hunyuan.py并使用torch.bfloat16半精度以降低显存占用mode_path /root/autodl-tmp/Tencent-Hunyuan/Hunyuan-A13B-Instruct # 加载tokenizer tokenizer AutoTokenizer.from_pretrained(mode_path, trust_remote_codeTrue) # 加载模型 model AutoModelForCausalLM.from_pretrained(mode_path, device_mapauto,torch_dtypetorch.bfloat16, trust_remote_codeTrue)说明device_mapauto由 accelerate 自动分配模型层到可用 GPU/CPUtorch_dtypetorch.bfloat16使用 BF16 精度兼顾训练稳定性与显存开销与仓库中其他模型微调案例如 examples/Chat-嬛嬛/train.py一致加载后建议调用model.enable_input_require_grads()以配合梯度检查点gradient checkpointing使用。Lora Config 配置LoraConfig是 peft 库中配置 LoRA 训练的核心类其中比较重要的参数如下task_type模型类型现在绝大部分decoder_only的模型都是因果语言模型CAUSAL_LMtarget_modules需要训练的模型层名字主要就是attention部分的层不同模型对应的层名字不同rLoRA 的秩决定低秩矩阵的维度较小的r意味着更少的参数lora_alpha缩放参数与r一起决定 LoRA 更新的强度实际缩放比例为lora_alpha / r在当前示例中是32 / 8 4倍lora_dropout应用于 LoRA 层的 dropout rate用于防止过拟合。config LoraConfig( task_typeTaskType.CAUSAL_LM, target_modules[q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj], inference_modeFalse, # 训练模式 r8, # Lora 秩 lora_alpha32, # Lora alpha lora_dropout0.1 # Dropout 比例 )配置解读target_modules覆盖了注意力四件套q/k/v/o_proj与 MoE 前馈网络的三组线性层gate/up/down_proj这是混元 A13B 模型可插入 LoRA 的全部关键投影层。使用get_peft_model(model, config)包裹模型后可通过model.print_trainable_parameters()打印实际可训练参数量r8、lora_alpha32意味着旁路矩阵的实际更新强度为 4 倍缩放这是社区实践中常用的低秩 较大缩放组合若显存紧张可尝试降低r如 4或提高lora_dropout如 0.15以减小过拟合风险。Training Arguments 训练参数TrainingArguments用于配置训练器的运行参数本教程中最关键的几个如下output_dir模型的输出路径checkpoint 保存目录per_device_train_batch_size每张卡上的batch_sizegradient_accumulation_steps梯度累积步数等效 batch size per_device_train_batch_size × gradient_accumulation_stepsnum_train_epochs训练轮数epoch。args TrainingArguments( output_dir./output/Hunyuan-A13B-Instruct, # 注意修改 per_device_train_batch_size4, gradient_accumulation_steps4, logging_steps10, num_train_epochs1, save_steps100, learning_rate1e-4, save_on_each_nodeTrue, gradient_checkpointingTrue, report_tonone, )参数说明与调参建议参数本示例值作用与建议output_dir./output/Hunyuan-A13B-Instructcheckpoint 与日志输出目录需按实际路径修改per_device_train_batch_size4单卡 batch size显存不足时可降至 12gradient_accumulation_steps4梯度累积等效总 batch 4×416显存有限时优先调大此值logging_steps10每 10 步打印一次训练日志num_train_epochs1训练 1 个 epoch数据量大时可保持 13save_steps100每 100 步保存一次 checkpoint训练结束后按此频率产出checkpoint-XXX目录learning_rate1e-4LoRA 常用学习率一般落在 1e-42e-5 区间save_on_each_nodeTrue多节点训练时每个节点都保存gradient_checkpointingTrue梯度检查点用少量计算换显存开启后需配合enable_input_require_grads()report_tonone关闭 transformers 自带的外部实验平台上报改由 SwanLab 回调负责记录SwanLab训练可视化与实验记录SwanLab 简介SwanLab 是一个开源的 AI 模型训练记录工具面向 AI 研究者提供训练可视化、自动日志记录、超参数记录、实验对比、多人协同等功能。在 SwanLab 上研究者能基于直观的可视化图表发现训练问题对比多个实验找到研究灵感并通过在线链接的分享与基于组织的多人协同训练打破团队沟通的壁垒。为什么要记录训练相较于软件开发模型训练更像一个实验科学。一个品质优秀的模型背后往往是成千上万次实验。研究者需要不断尝试、记录、对比、积累经验才能找到最佳的模型结构、超参数与数据配比。在这之中如何高效进行记录与对比对于研究效率的提升至关重要。实例化 SwanLabCallback建议先在 SwanLab 官网注册账号然后在训练初始化阶段选择(2) Use an existing SwanLab account并使用 private API Key 登录。import swanlab from swanlab.integration.transformers import SwanLabCallback # 实例化SwanLabCallback swanlab_callback SwanLabCallback( projectHunyuan-A13B-Instruct-Lora, # 注意修改 experiment_nameHunyuan-A13B-Instruct-LoRA-experiment # 注意修改 )SwanLabCallback是 SwanLab 为 HuggingFaceTrainer提供的官方回调实现它会自动捕获训练过程中的 loss、学习率、梯度范数、每步耗时等指标并随Trainer的训练循环自动上报无需在训练代码中手动埋点。使用 Trainer 训练将模型、参数、数据集与回调注入Trainer后启动训练。DataCollatorForSeq2Seq负责将 batch 内不同长度的序列 padding 到统一长度trainer Trainer( modelmodel, argsargs, train_datasettokenized_id, data_collatorDataCollatorForSeq2Seq(tokenizertokenizer, paddingTrue), callbacks[swanlab_callback] # 传入之前的swanlab_callback ) trainer.train()训练完成后会输出类似如下的统计信息TrainOutput(global_step233, training_loss3.3132195984345136, metrics{train_runtime: 4321.001, train_samples_per_second: 0.863, train_steps_per_second: 0.054, total_flos: 2.225441122839429e17, train_loss: 3.3132195984345136, epoch: 0.9989281886387996})关键指标解读global_step233共训练 233 步对应约 1 个 epoch与save_steps100配合会产生checkpoint-100、checkpoint-200等检查点train_loss3.313最终平均训练损失train_runtime4321秒总训练时长train_samples_per_second/train_steps_per_second吞吐指标用于评估训练效率。训练完成后打开 SwanLab 即可查看训练过程中记录的参数和可视化的训练 loss 曲线如上图所示loss 曲线随训练步数增加整体呈下降趋势训练初期下降较快随后趋于平稳约在 3.3 附近波动表明模型在持续优化。SwanLab 会自动记录超参数project、experiment_name、batch size、learning rate 等以及每个 step 的指标便于多实验横向对比。加载 LoRA 权重推理训练得到任意checkpoints之后使用PeftModel.from_pretrained加载 LoRA 权重进行推理from transformers import AutoModelForCausalLM, AutoTokenizer import torch from peft import PeftModel mode_path /root/autodl-tmp/Tencent-Hunyuan/Hunyuan-A13B-Instruct #这里修改实际的模型路径 lora_path /root/output/Hunyuan-A13B-Instruct/checkpoint-233 # 这里改成你的 lora 输出对应 checkpoint 地址 # 加载tokenizer tokenizer AutoTokenizer.from_pretrained(mode_path, trust_remote_codeTrue) # 加载模型 model AutoModelForCausalLM.from_pretrained(mode_path, device_mapauto,torch_dtypetorch.bfloat16, trust_remote_codeTrue) # 加载lora权重 model PeftModel.from_pretrained(model, model_idlora_path) import re messages [ {role: user, content: who are you?}, ] tokenized_chat tokenizer.apply_chat_template(messages, tokenizeTrue, return_tensorspt, enable_thinkingFalse # Toggle thinking mode (default: True) ) outputs model.generate(tokenized_chat.to(model.device), max_new_tokens4096) output_text tokenizer.decode(outputs[0]) answer_pattern ranswer(.*?)/answer answer_matches re.findall(answer_pattern, output_text, re.DOTALL) answer_content [match.strip() for match in answer_matches][0] print(fanswer_content:{answer_content}\n\n)推理要点lora_path指向 checkpoint 目录例如checkpoint-233目录内保存了adapter_config.json与adapter_model.safetensors等 LoRA 权重文件enable_thinkingFalse推理时可切换思考模式默认开启关闭后模型直接给出答案响应更快answer标签解析混元混合推理模型最终答案包裹在answer与/answer标签内因此使用正则ranswer(.*?)/answer提取最终回答内容re.DOTALL用于匹配跨行内容。运行结果示例answer_content:Im HunYuan, Tencents AI assistant. Im here to help you with any questions or tasks you have. How can I assist you today?常见问题与调优建议模型加载报 logging 相关错误按前文要求在模型目录下的hunyuan.py开头添加import logging与logger logging.getLogger(__name__)显存不足OOM降低per_device_train_batch_size、增大gradient_accumulation_steps或降低MAX_LENGTH截断长度同时保持gradient_checkpointingTrue微调后模型仍不会角色扮演检查训练数据量与格式建议不少于数百条对话、确认process_func中模板与 Chat Template 一致、适当增加num_train_epochs推理时无输出或输出为空确认enable_thinking参数与训练时一致并正确使用answer标签正则提取必要时将max_new_tokens调大示例中为 4096想要对比不同超参数的效果为每次实验更换experiment_name并保持同一project即可在 SwanLab 中横向对比多组实验的 loss 曲线。小结本文以 Hunyuan-A13B-Instruct 为例完成了从环境搭建、模型下载、SFT 数据集构建与预处理、LoRA 配置、训练参数设计、SwanLab 可视化记录到 LoRA 权重推理的完整闭环。核心要点可归纳为LoRA 微调只需冻结原模型并训练少量低秩旁路参数适合单卡/低显存环境混合推理模型的 Chat Template 适配是训练成败的关键训练模板必须与推理模板保持一致数据预处理中labels的-100掩码设计决定了模型只学习输出部分接入 SwanLab 的SwanLabCallback即可零侵入地完成训练指标的可视化与实验对比。该流程同样适用于仓库中其他同架构 MoE 模型的微调感兴趣的读者可进一步阅读 01-Hunyuan-A13B-Instruct 模型架构解析 Blog.md 了解模型内部机制或参考 05-Hunyuan-A13B-Instruct-LoRA.ipynb 直接运行完整代码。赞分享大模型人工智能教程本地部署微调【免费下载链接】self-llm《开源大模型食用指南》针对中国宝宝量身打造的基于Linux环境快速微调全参数/Lora、部署国内外开源大模型LLM/多模态大模型MLLM教程项目地址https://gitcode.com/datawhalechina/self-llm点击查看免费下载相关推荐Qwen2.5-7B-Instruct 法律问答 LoRA 微调实战基于 SwanLab 的全流程训练可视化与实验对比Qwen2.5 7B Instruct 法律问答 LoRA 微调实战基于 SwanLab 的全流程训练可视化与实验对比 本文以 Datawhale《开源大模型大模型人工智能教程本地部署微调Qwen2-VL-2B-Instruct LoRA 微调实战基于 COCO2014 图像描述任务与 SwanLab 全流程可视化Qwen2 VL 2B Instruct LoRA 微调实战基于 COCO2014 图像描述任务与 SwanLab 全流程可视化 本文是《开源大模型食用指南》大模型人工智能教程本地部署微调Qwen2.5-7B-Instruct LoRA 微调实战DISC-Law 法律问答数据集与 SwanLab 训练可视化全流程指南Qwen2.5 7B Instruct LoRA 微调实战DISC Law 法律问答数据集与 SwanLab 训练可视化全流程指南 导读 本文以 models教程大模型本地部署微调创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考