torchtune 数据集与微调实战：一条样本的四段旅程和六类任务接入详解-北京尧图网络

torchtune 数据集与微调实战一条样本的四段旅程和六类任务接入详解【免费下载链接】torchtunePyTorch native post-training library项目地址: https://gitcode.com/GitHub_Trending/to/torchtune手里有一批自己整理的指令数据想接进 torchtune 做 LoRA 微调第一步就容易卡住dataset段到底指向哪个 builder列名对不上怎么办哪些 token 真正参与 losstorchtune 数据集体系的核心是一条所有任务共用的数据流水线——把任意来源的样本标准化成统一的 Message 结构再交给模型专属转换和 batch 打包。这篇文章不逐页念文档而是跟着一条真实样本走完全程再给你六类任务的数据模板、一份可以直接改的 recipe 配置写法以及高频坑的现象→解法对照。一条样本的旅程从原始行到训练 batchtorchtune 里所有数据集实现无论内置还是自定义最终都落在同一组插槽上最具代表性的就是 SFTDataset按source加载数据逐样本做message 转换 → 模型转换最后由 collater 打包。下面按一条数据的流转顺序走四站。第 1 站原始样本怎么进来SFTDataset.__init__把数据加载完全委托给 Hugging Face 的load_datasetsource的三种传法对应三种来源传 HF Hub 仓库名直接从 Hub 拉取传文件类型字符串json、csv、text并配合data_files读本地文件data_files给远程 URL 时直接在线读取。其余参数如split、name原样透传所以 HF 支持的加载语义都能拿到包括splittrain[:10%]这种子集切分。另外filter_fn可带filter_kwargs会在任何预处理之前先跑一遍适合在这里把低质量样本提前剔掉不浪费后面的分词开销。第 2 站Message 标准化给样本贴上四种角色Message 是 torchtune 的统一中间格式大白话理解就是带元信息的消息气泡role是谁说的、content说了什么也可以交错放图像、masked是否计入 loss、eot是否追加句尾符。角色只有四种取值角色含义system系统提示user输入给模型的 promptassistant模型响应真正要训练、要算 loss 的部分ipython工具调用返回agent/工具类数据常见message_transform 的职责就是不管原始 schema 长什么样都转成 Message 列表图片等媒体内容存放在与其关联的Message对象内部。masked默认False而 recipe 里的train_on_input、new_system_prompt这类参数底层就是在给对应消息设置这个标记。第 3 站模型转换分词、模板与图像model_transform 负责这个模型需要的一切处理分词、套用 prompt 模板、VLM 的图像预处理等。这一站的契约非常硬返回值必须至少包含tokens和mask两个键否则SFTTransform直接抛ValueError见 torchtune/datasets/_sft.py。因此纯文本任务可以把任何ModelTokenizer子类直接当 model_transform 用VLM 任务则换成对应模型的 transform例如llama3_2_vision_transform。第 4 站collate 打包成 batch一个 batch 里的样本长短不一模型只吃规整张量。collate打包就是把一批处理好的样本 padding 成 batch 的工序torchtune 的实现集中在 torchtune/data/_collate.py按任务类型各有专款通用padded_collate、SFT 的padded_collate_sft、多模态 tile 图像的padded_collate_tiled_images_and_mask、打包样本的padded_collate_packed、偏好对的padded_collate_dpo选哪个放到高频坑里再讲。谁计入 loss-100CROSS_ENTROPY_IGNORE_IDX从哪来这是新手最常卡住的一站。SFTTransform.__call__拿到 tokens 和 mask 之后构建 labels 的规则是mask 为True的位置替换成CROSS_ENTROPY_IGNORE_IDX即-100其余位置保留原 token再把 labels 整体相对 logits 右移一位末尾补一个-100。右移是因为自回归模型用第 t 个 token 预测第 t1 个。所以默认行为是系统消息和用户 prompt 在 labels 里全是-100不参与 loss只有 assistant 响应在被学习。数据接通后训练 loss 应该收敛得比较干净下面这条来自官方 LoRA 微调实验的对比曲线可以参考数据接入正确时的量级torchtune 数据集六类微调任务的数据长相该准备哪些列、用哪个 builder任务列结构默认入口 builder典型场景单轮 instructinput/output两列instruct_dataset指令跟随、语法纠错多轮 chat一个对话列role/value 消息对chat_dataset多轮对话偏好 DPOchosen/rejected两列preference_datasetDPO 对齐继续预训练单一文本列默认texttext_completion_dataset无标注语料图文多模态对话列图像列占位符multimodal_chat_datasetVLM 微调任意格式任意 schema → MessageSFTDataset 自定义 transform私有数据单轮 instruct两列文本列名可换必填列prompt 一列、响应一列默认叫input/output。关键参数两个column_map换列名写成{input: question, output: answer}这种默认列名 → 实际列名的映射train_on_input决定用户 prompt 是否计入 loss默认False即只学响应。另外new_system_prompt会给每条样本前置一条系统消息覆盖数据里已有的 system 消息。从 HF 加载时只需把source换成仓库名即可。多轮 chat对话列两种标准 style必填一个存放消息列表的对话列。conversation_column指定列名conversation_style指定消息结构只有两个取值分别对应 torchtune/data/_messages.py 里的两个内置转换器style转换器期望结构sharegptShareGPTToMessages{from: human/gpt, value: ...}openaiOpenAIToMessages{role: user/assistant, content: ...}典型的 sharegpt 结构长这样{conversations: [ {from: human, value: What is the answer to life?}, {from: gpt, value: The answer is 42.} ]}如果两种内置风格都匹配不了你的数据就降级到下一节的自定义 transform 处理不要硬凑。偏好 DPOchosen / rejected 双列prompt 必须一致每行给同一 prompt 下的偏好与非偏好响应两条的 prompt 部分必须完全一致单轮、多轮风格都支持。column_map映射到{chosen: ..., rejected: ...}。处理完一条样本会输出四组键chosen_input_ids/chosen_labels和rejected_input_ids/rejected_labelsprompt 部分全部是-100只有两条响应参与——这正是 DPO 对比学习的输入形态batch 层由padded_collate_dpo组装配合 lora_dpo_single_device.py 使用。公开数据有内置的hh_rlhf_helpful_dataset与stack_exchange_paired_dataset。继续预训练只有一个文本列要求最简column指定文本在哪一列默认textsource写text时按行读纯文本.txtadd_eos默认True每段末尾追加句尾符。适合 wikipedia 这类大体量语料内置有cnn_dailymail_articles_dataset和wikitext_dataset可直接套用。图文多模态对话列图像列占位符对话列是 sharegpt 风格文本里带图像占位符如image另加一列图像路径。关键参数image_dir把前缀拼到相对路径前面image_tag声明占位符builder 自动把图像插到占位位置。注意两点每个样本目前只支持单张图像且固定挂在第一条 user 消息上入口参数要传 VLM 的model_transform而不是普通 tokenizer。内置的有multimodal.the_cauldron_dataset与multimodal.llava_instruct_dataset。任意格式自定义Transform SFTDatasetschema 套不进任何 builder 时自己写一个message_transform把一行数据转成 Messages剩下交给SFTDataset。最小写法class MyMessageTransform(Transform): def __call__(self, sample): return {messages: [ Message(roleuser, contentsample[q], maskedTrue), Message(roleassistant, contentsample[a], maskedFalse), ]}maskedTrue/False直接决定哪些 token 变-100多模态场景把 PIL 图像直接放进消息 content再让model_transform换成 VLM 的 transform 即可详见 custom_datasets.rst。三步跑通自己的数据recipe 配置写法第 1 步在 recipe 里配 tokenizertokenizer 配在 recipe 层由 recipe 传进 dataset builderdataset 段里不用重复声明。VLM 任务在这个位置配对应模型 transform如llama3_2_vision_transform记得给image_size并与模型侧保持一致。第 2 步写 dataset 段_component_指向入口 builder再按任务列要求填source、data_files、split、column_map等。用公开数据时可以直接指到内置 builder例如 0.6B_lora_single_device.yaml 里的torchtune.datasets.alpaca_cleaned_dataset。第 3 步指向 builder 并跑起来完整最小配置单卡 LoRA instruct 数据tokenizer: _component_: torchtune.models.llama3.llama3_tokenizer path: /tmp/tokenizer.model dataset: _component_: torchtune.datasets.instruct_dataset source: json data_files: data/my_data.json column_map: {input: question, output: answer}存成配置后用tune run lora_finetune_single_device --config 你的配置就能开跑命令行还支持逐参数覆盖。到这里数据流水线已经和训练超参解耦换数据只换 dataset 段LoRA 微调本身的权重更新方式可看官方示意图进阶参数与高频坑列名不一致、loss 范围、打包提速怎么解现象解法关键参数列名与 builder 默认不符加载即 KeyErrorcolumn_map做默认列名 → 实际列名映射chat 场景用conversation_column指明对话列column_map/conversation_column想让 prompt 进 loss或反向排除train_on_inputTrue把用户 prompt 计入 loss需要逐样本控制就在 Message 上写maskedtrain_on_input/masked数据集里有脏样本污染训练filter_fn可调用对象在任何预处理之前执行一次filter_fn/filter_kwargs图像相对路径找不到image_dir拼路径前缀文本里的占位符用image_tag声明默认imageimage_dir/image_tag首条样本就报model_transform ... Must return tokens and mask自定义 transform 至少返回tokens与mask两键model_transform短样本多、padding 浪费显存PackedDataset把样本打包到max_seq_len多数 builder 支持packed: TrueConcatDataset可先拼接多数据集packed多模态训练 batch 形状报错collate_fn: torchtune.data.padded_collate_tiled_images_and_mask官方 VLM 配置已写好可直接抄11B_lora_single_device.yamlcollate_fncollater 的选择原则就一句话普通 SFT 用padded_collate_sft打包样本用padded_collate_packed偏好对用padded_collate_dpo带 tile 图像的 VLM 用padded_collate_tiled_images_and_mask拿不准就用通用的padded_collate。参考路径速查内容相对路径数据流水线总览文档docs/source/basics/datasets_overview.rstSFTDataset / SFTTransform 实现torchtune/datasets/_sft.py六类任务 builder_instruct.py、_chat.py、_preference.py、_text_completion.py、multimodal/_multimodal.pyMessage、角色校验与 mask 工具torchtune/data/_messages.py各任务 collaterbatch 打包torchtune/data/_collate.py内置 builder 导出清单torchtune/datasets/init.py各任务格式文档instruct、chat、preference、multimodal、text completion、custom、message transform示例 recipe 配置recipes/configs/qwen3/0.6B_lora_single_device.yaml、recipes/configs/llama3_2_vision/11B_lora_single_device.yaml一句话收束torchtune 数据集体系把备数据变成了拼装问题——source、Message、模型专属转换、collater 四个插槽都有标准接口你挑哪个 builder 只是挑一套预填组合。建议的下一步动作先打印ds[0]对着tokens、labels找出-100的分布再用 tokenizer 把 tokens 解码一遍确认模板和角色都符合预期——数据层验证通过再谈训练超参。【免费下载链接】torchtunePyTorch native post-training library项目地址: https://gitcode.com/GitHub_Trending/to/torchtune创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

torchtune 数据集与微调实战：一条样本的四段旅程和六类任务接入详解

相关推荐

MCreator 生物群系水雾颜色（Water Fog Color）参数详解：从界面配置到数据包 JSON 生成原理

Argos Translate离线翻译排错全手册

基于ODConv动态卷积的YOLO26小目标检测与多尺度感知改进

更多资讯

AI影片制作全流程拆解：从分镜脚本到批量渲染的完整工作流

WebSocket抓包分析实战：从协议帧到真实问题排查

C++节点编辑器实战：命令模式、编组与命中检测优化

AI多模态创作：把ADHD抽象感受拆解成可视化视频

基于窗函数反求法的NLFM信号设计与脉压验证

Microsoft Remote Desktop for macOS 深度指南：RDP 协议、ARM64 原生与 macOS 系统集成

今日更新

Cephadm实战指南：Linux系统工程师的生产级Ceph集群部署与排障

不想再被 Token 额度卡脖子？把免费 API 接入 WorkBuddy 的完整教程

ITK中SpatialObject几何体系解析：坐标系、变换与管道集成

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？