ValueError: sampler option is mutually exclusive with shuffle这个报错我在 PyTorch 的 DataLoader 上至少见过几十次了而且很有意思的是它经常不是新手专属——很多写了好几年模型的老手在从单机改成自定义采样器或者接入分布式训练的时候也会被这一行英文卡住。今天我就把这个问题彻底讲透从报错原理到正确的代码写法再到排查思路和同类报错一次性说清楚。这个错误本质上是 DataLoader 对参数组合的一道“硬性红线”你在初始化 DataLoader 的时候既传了 sampler又把 shuffle 参数设成了 TruePyTorch 干脆直接抛异常拒绝运行。它这么做不是故意给你添堵而是为了避免更隐蔽的错误。这篇文章适合正在被这个报错搞崩溃的 PyTorch 开发者看也适合想彻底理解 DataLoader 采样机制的读者——看完你不仅能修掉这个报错还能搞明白 shuffle、sampler、batch_sampler 这三者之间的关系以后再遇到类似参数冲突都能一眼看穿。1. 先复现这个报错搞明白它在说什么1.1 最典型的触发场景先看一段能稳定触发这个报错的代码。假设你有一个自定义数据集因为样本类别不均衡你打算用WeightedRandomSampler来采样于是写出了这样的初始化和 DataLoader 构造逻辑import torch from torch.utils.data import DataLoader, Dataset, WeightedRandomSampler class MyDataset(Dataset): def __len__(self): return 1000 def __getitem__(self, idx): return torch.tensor(idx, dtypetorch.float32) dataset MyDataset() # 给每个样本一个采样权重比如正负样本不均衡时 weights torch.ones(1000) weights[:100] 10.0 sampler WeightedRandomSampler(weights, num_samples500, replacementTrue) dataloader DataLoader( dataset, batch_size32, samplersampler, shuffleTrue, # 这里和 sampler 同时出现了 )一旦你运行到这一行PyTorch 就会直接给你甩出题目里那个报错ValueError: sampler option is mutually exclusive with shuffle这行报错的字面意思是sampler参数和shuffle参数是互斥的你不能同时指定。但很多人第一次看到mutually exclusive这个短语时第一反应是“哦我把两个参数都删掉一个就行”删完之后结果莫名其妙变好了但并不知道为什么下次遇到同类问题又开始懵。1.2 报错的完整信息和内部机制先看看 PyTorch 源码里到底在哪个环节做了拦截。DataLoader 的__init__里面有一段很直接的状态检查逻辑简化一下大概是这样的if shuffle: if sampler is not None or batch_sampler is not None: raise ValueError(sampler option is mutually exclusive with shuffle)也就是说只要shuffleTrue你再显式传sampler或者batch_sampler它就会报错。为什么要这么设计因为 DataLoader 在内部对“如何从数据集中取样本”这件事是有一套默认规则的当shuffleFalse的时候DataLoader 内部会用一个SequentialSampler按顺序从头到尾取样本。当shuffleTrue的时候DataLoader 内部会创建一个RandomSampler把索引顺序打乱后再取样本。如果你显式传入了samplerDataLoader 就会完全无视shuffle直接用你传进来的 sampler 去取样本。想一想如果你既告诉 DataLoader“你给我用随机采样器洗牌”又告诉它“用我自定义的这个 sampler 来决定采样顺序”那到底听谁的听你的 sampler那shuffleTrue就没有意义听shuffle那你辛辛苦苦写的采样器就白费了。这种二选一的矛盾与其悄悄忽略一个参数让你在训练结果里看到诡异的行为不如直接抛异常逼你明确自己的意图。从工程设计的角度来看PyTorch 这种做法其实非常明智。它把“采样顺序”这个关键职责统一交给 sampler 体系来管shuffle只是一个方便开关shuffleTrue就等价于内部帮你创建一个RandomSamplershuffleFalse就等价于创建SequentialSampler。所以当你自定义了 sampler实际上已经接管了“顺序怎么来”这件事shuffle参数自然就应该保持默认的False。2. 理解 DataLoader 的采样机制才能彻底搞懂2.1 shuffle 和 sampler 到底在干什么很多同学在写训练代码时对shuffle的理解停留在“打乱数据顺序避免模型学到顺序偏差”。这个理解没错但不够底层。在 DataLoader 的机制里采样过程真正发生的事情是先通过 sampler 获得一个“索引列表”然后 DataLoader 按这个索引列表去数据集里把对应样本取出来再按batch_size拼成 batch。举个例子一个数据集有 5 个样本索引分别是 0、1、2、3、4。shuffleFalse时SequentialSampler返回的索引序列是[0, 1, 2, 3, 4]shuffleTrue时RandomSampler返回的可能是[3, 0, 4, 1, 2]然后 DataLoader 按 batch_size2 切分第一批就是样本 3 和样本 0。当你自定义 sampler 时你就是自己实现那个“索引序列”的生成逻辑。WeightedRandomSampler按权重有放回地抽索引DistributedSampler在多卡环境下把数据切分给不同进程BatchSampler则是一次性生成一整批的索引列表。它们的本质都一样决定 DataLoader 以什么样的顺序去访问数据。所以shuffleTrue本质上只是“使用随机采样器”的语法糖而不是独立于 sampler 之外的另一个机制。理解了这一点你就明白为什么它俩不能共存——因为一旦显式指定 samplershuffle 这个语法糖就没法再套用一个隐式的 RandomSampler 了。2.2 自定义 sampler 的常见理由既然系统已经自带了SequentialSampler和RandomSampler为什么还要自定义 sampler我总结下来最常见的有三种场景第一种样本类别不均衡需要控制每个样本被抽中的概率。这是WeightedRandomSampler的典型用法。比如分类任务中正样本有 1000 条、负样本有 10000 条你不想简单粗暴地过采样可以用权重让正样本以更高的概率被抽中让模型每个 batch 里都看到足够的正样本。这类问题在文本分类、图像分类、点击率预估里非常常见。第二种多卡分布式训练时每张卡只需要处理数据集的一个分片。这种情况下要保证数据互不重复同时还要让不同进程之间的 shuffle 是协调一致的不能用普通的RandomSampler各洗各的否则不同卡上会出现重复或者漏掉的样本。DistributedSampler就是干这个的。第三种需要对数据顺序做特殊控制。比如训练序列模型时你可能希望同一 batch 内的样本长度尽量接近所以需要先按照序列长度排序或者分桶bucket再在每个桶内部做随机。这时候就要自定义一个按长度分组的 sampler。NLP 里的很多预处理任务就是这么干的。明白这些场景之后你就知道很多自定义 sampler 的场景里你根本不需要再额外打开shuffleTrue因为你的 sampler 自己已经带着随机逻辑了比如WeightedRandomSampler本身就是带放回的随机抽取。2.3 参数之间的“排他协议”shuffle、sampler 和 batch_sampler比shuffle和sampler的互斥关系更完整的是 DataLoader 里四个参数之间的“排他协议”参数作用冲突规则shuffle是否打乱样本顺序与sampler、batch_sampler互斥sampler决定每个样本的采样顺序与shuffle、batch_sampler互斥batch_sampler一次性生成 batch 级别的索引列表与batch_size、shuffle、sampler、drop_last互斥batch_size每个 batch 的样本数指定batch_sampler时不能传翻译成人话就是你在用sampler控制采样顺序就别再让shuffle插手。你在用batch_sampler直接指定“每个 batch 由哪些样本组成”那么batch_size、shuffle、sampler、drop_last这四个参数统统不能再传。如果你什么都不传DataLoader 默认使用SequentialSamplershuffle默认为Falsebatch_size1。这个协议非常像日常生活中“你选了套餐就不能再单点米饭”这种硬规则。它保证了采样职责的唯一性避免出现两个互相矛盾的指令同时生效。你理解了这套协议之后再看到 DataLoader 的初始化代码一眼就能判断它有没有踩红线。3. 实操几种正确的组合写法3.1 方案一保留 sampler关闭 shuffle最直接的修复方式就是把原来那段报错代码里的shuffleTrue改成shuffleFalse或者干脆删掉不写shuffle默认就是False。dataloader DataLoader( dataset, batch_size32, samplersampler, shuffleFalse, # 关键显式传 sampler 时这里必须为 False )这样改完之后你的WeightedRandomSampler会正常工作因为权重采样本身已经带了随机性——replacementTrue表示有放回抽样每次从全部样本里按权重随机抽一个索引出来。也就是说你的数据顺序已经是随机的了不需要 DataLoader 再做一层 shuffle。我见过不少同学在这里很担心“那我是不是失去了随机性”完全不是。WeightedRandomSampler的随机性体现在“每次按权重抽哪个样本”这件事本身它的__iter__方法每次都会重新随机抽取索引序列和RandomSampler的效果是一样的。你失去的只是一个多余的开关而不是随机性本身。3.2 方案二只用 shuffle不传 sampler如果你的需求只是“把数据顺序打乱”不需要任何自定义采样逻辑那最简单的写法就是dataloader DataLoader( dataset, batch_size32, shuffleTrue, )这种写法等价于内部创建了一个RandomSampler。它的随机性来自 DataLoader 遍历完一个 epoch 之后下一次iter(dataloader)时重新生成一个新的随机索引序列。所以当你不需要做特殊采样时不要画蛇添足地去显式传入RandomSampler再去设shuffleTrue。直接用shuffleTrue就是最干净的写法。如果你确实需要显式传入RandomSampler比如你想自定义num_samples或者设置replacement参数那就按方案一把shuffle关掉。3.3 方案三自定义 sampler 自带随机打乱有时候你的采样逻辑是自定义的但又想让它内部支持随机打乱。这时候正确的做法不是去设置 DataLoader 的shuffleTrue而是把这个随机逻辑写进 sampler 自己的__iter__方法里。举一个简单的自定义 sampler 例子import random from torch.utils.data import Sampler class MyCustomSampler(Sampler): def __init__(self, data_source, shuffleTrue): self.data_source data_source self.indices list(range(len(data_source))) self.shuffle shuffle def __iter__(self): if self.shuffle: random.shuffle(self.indices) return iter(self.indices) def __len__(self): return len(self.indices) sampler MyCustomSampler(dataset, shuffleTrue) dataloader DataLoader( dataset, batch_size32, samplersampler, # 这里不再需要也不会使用 shuffleTrue )这种模式在很多开源项目里很常见sampler 自己管理随机性DataLoader 只负责按索引取数。这样做的好处是采样逻辑完全内聚在一个类里面职责清晰也避免了外面再加shuffleTrue导致报错。3.4 方案四分布式训练里的 DistributedSampler再说一个非常高频的坑就是分布式训练。很多人会写出这样的代码from torch.utils.data.distributed import DistributedSampler import torch.distributed as dist sampler DistributedSampler(dataset, shuffleTrue) dataloader DataLoader( dataset, batch_size32, samplersampler, shuffleTrue, # 错误 )这个写法报的错和我们主题完全是同一个。正确的写法是 DataLoader 里不设shuffle让DistributedSampler自己去管sampler DistributedSampler(dataset, shuffleTrue) dataloader DataLoader( dataset, batch_size32, samplersampler, shuffleFalse, ) for epoch in range(num_epochs): sampler.set_epoch(epoch) # 关键每个 epoch 都要设置保证不同 epoch 的 shuffle 不同 for batch in dataloader: train(batch)这里有个额外的细节DistributedSampler内部有set_epoch方法你必须每个 epoch 都调用它否则每个 epoch 拿到的是完全一样的索引序列shuffle 就形同虚设了。从 PyTorch 1.x 开始DistributedSampler支持在初始化时传shuffleTrue然后在set_epoch(epoch)时根据 epoch 种子重新洗牌。DataLoader 层级的shuffle参数和它无关保持默认就好。3.5 进阶场景batch_sampler 的正确用法有些时候你的采样粒度不是“单个样本”而是“整个 batch”。比如训练推荐模型时你想一次性构造出“同一个 session 的用户行为序列”这样的 batch就需要自定义BatchSampler。from torch.utils.data import BatchSampler, SequentialSampler class MyBatchSampler(BatchSampler): def __init__(self, sampler, batch_size, drop_last): super().__init__(sampler, batch_size, drop_last) def __iter__(self): # 这里可以自定义如何合并样本索引 for batch_indices in super().__iter__(): yield batch_indices sampler SequentialSampler(dataset) batch_sampler MyBatchSampler(sampler, batch_size32, drop_lastFalse) dataloader DataLoader( dataset, batch_samplerbatch_sampler, # 此时不能再传 batch_size / shuffle / sampler / drop_last )注意这段代码注释里的关键点一旦你传了batch_sampler就不允许再传batch_size和shuffle否则 PyTorch 会抛出另一个类似的ValueError。这条规则是sampler option is mutually exclusive with shuffle的“姊妹规则”很多人修好了sampler和shuffle的冲突转头又在batch_sampler上踩了同样的坑。4. 同类 ValueError 实战排查与避坑建议4.1 相关的高频 ValueError 速查表在搜这个报错的时候很多人还会同时搜到其他一些长得差不多的ValueError它们不一定和 PyTorch 的 DataLoader 有关但字面都叫ValueError容易让人混淆。我整理了一个速查表你可以当作排查手册用报错信息可能原因解决思路ValueError: sampler option is mutually exclusive with shuffleDataLoader 同时指定了 sampler 和 shuffle二选一保留 sampler 就设 shuffleFalseValueError: batch_sampler option is mutually exclusive with batch_size, shuffle, sampler, and drop_last同时指定了 batch_sampler 与其他采样参数去掉 batch_size/shuffle/sampler/drop_lastValueError: Couldnt instantiate the backend tokenizer from one of: [网络模型地址]transformers 加载 tokenizer 时无法识别模型路径检查模型路径、是否下载完整、是否使用正确的 AutoTokenizerValueError: unsupported pickle protocol: 5pickle 数据由更高版本的 Python 生成升级 Python或者用原环境重新生成数据ValueError: unrecognized model in wangzejun/simbert-base-chinese. Should have...模型名不符合 transformers 命名规范或本地路径缺失确认模型名完整改用官方发布的模型标识符ValueError: unable to find resource t32.exe in package pip._vendored...pip 内部资源文件损坏或下载不完整重新安装 pip或升级到最新版本这里要特别说明一下后面几个和本文主题关系不大但它们出现频率很高很多时候是在搜索同一个关键词时被一起带出来的。如果你正好遇到这几个问题可以按表里的思路去查。4.2 标准的排查步骤遇到sampler option is mutually exclusive with shuffle这类报错我建议你按以下顺序排查不要一上来就盲目删参数第一步看完整的 traceback。注意报错信息会有两行实际含义是“DataLoader 构造时发现shuffleTrue而这个值应该只有在sampler is None时才允许生效”。所以先把报错定位到你正在构造 DataLoader 的那一行。第二步检查传入 DataLoader 的所有参数。很多人用dataclass或者配置字典来管理超参像这样dataloader DataLoader(dataset, **data_loader_params)如果data_loader_params里既包含sampler又包含shuffleTrue你直接在构造处检查是看不出来的得把字典打印出来看。我建议你用print(data_loader_params)先看一眼确认键值内容。这一步在调试时特别重要因为问题可能出在上游某个配置模块。第三步确认你对采样逻辑的需求。问自己一个问题我需要随机打乱数据吗如果需要是那种随机是全量随机还是按权重随机还是按分组随机对应需求选择合适的参数组合全量随机shuffleTrue即可。按权重随机WeightedRandomSamplershuffleFalse。分组随机自定义 sampler 内部做随机DataLoader 不设 shuffle。多卡随机DistributedSamplershuffleFalse 每个 epoch 调用set_epoch。第四步修改之后重新跑一个小规模的空训练循环不要直接跑全量数据。用一个少量样本的数据集验证 DataLoader 能正常迭代再投入正式训练避免浪费算力和时间。4.3 那些年我在 DataLoader 上踩过的别的坑除了sampler和shuffle的互斥问题DataLoader 还有几个坑跟它高度相关第一个是我上次自己掉进去的在编写自定义 Dataset 时内部如果维护了可变状态比如做数据增强时的随机状态、缓存等而你又用了多进程num_workers0数据会被多个 worker 复制多份它们的状态是各自独立的很容易出现“同一个 epoch 里某些样本被重复处理、某些样本没被处理”的诡异现象。这个坑排查起来比参数互斥更隐蔽。第二个坑是num_workers在 Windows 上如果不放在if __name__ __main__:块里会反复递归加载数据脚本报错起来很吓人。但根因往往和采样器无关而是多进程启动方式的问题。所以当你在 Windows 上看到奇奇怪怪的 DataLoader 报错时先检查你的入口函数写法。第三个坑是drop_last和自定义 sampler 的__len__不一致。如果你的 sampler 返回的索引数量不能被batch_size整除又没设置drop_lastTrue最后一个 batch 会比其他 batch 小。很多新手在这个地方会困惑“为什么我的 batch 大小忽大忽小”实际上这就是采样数量分布的问题不是采样器坏了。第四个坑是在做验证集评估时有人习惯性地也给验证集 DataLoader 传入shuffleTrue导致每个 epoch 验证集顺序都不一样进而导致某些依赖“固定顺序”的指标计算比如排序类指标出现偏差结果波动很大。验证集和测试集通常应该保持固定的顺序shuffleFalse就好。4.4 一个彻底避免这类报错的习惯我现在写训练代码对 DataLoader 参数的写法有一套固定习惯基本不会再踩到sampler option is mutually exclusive with shuffle这类的坑如果只写普通训练脚本不是分布式不是自定义采样那就只用shuffle参数不碰sampler。如果需要处理不平衡数据那就显式创建WeightedRandomSampler并强制把 DataLoader 的shuffle写成显式的shuffleFalse不依赖默认值。这个“显式”很重要因为将来别人接手代码时一眼就能看出你是故意关掉 shuffle 的而不是忘写了。如果代码里出现了sampler和shuffle同时为真的情况我会把它当成一个“不合法状态”来处理而不是单纯依赖 PyTorch 的报错。所以在自己封装的数据加载模块里我还会加一层断言assert not (sampler is not None and shuffle), sampler and shuffle cannot be both set这层断言在 PyTorch 报错之前就能帮你拦住有问题的配置而且在你的自定义组件之间传递参数时特别有用能让你第一时间定位到是哪个模块把参数配错了。写在后面修复这个报错只是第一步说实话sampler option is mutually exclusive with shuffle这个报错本身并不是什么大难题把它修掉可能只需要改一个单词。但它背后的采样机制和 DataLoader 参数之间的排他协议才是真正值得理解的东西。我见过很多人在这个报错上消化的时间很短修完就忘了结果过两周在别的项目里又踩一次——因为这种“参数互相排斥”的设计在 PyTorch 里并不少见理解了这套思路你以后看batch_sampler、collate_fn、pin_memory这些参数的组合方式都会快很多。我个人在实际操作中最深的体会是不要急着把报错改掉先花几分钟搞清楚 PyTorch 为什么不允许这种组合。每一个看似多余的异常都在告诉你一个设计约束。当你真正理解了 DataLoader 是先通过 sampler 生成索引、再按索引取样本、最后拼成 batch 这个完整流程之后这一类参数冲突问题就再也不会迷惑你了。最后再分享一个小技巧如果你的代码里用了很多配置项来动态组装 DataLoader建议在配置结构体里单独开一个sampler字段和shuffle字段并且在构造 DataLoader 之前打印一遍完整参数确保没有同时出现。实测下来这个习惯能帮你在调试这种报错时省下不少时间。
PyTorch DataLoader参数冲突：sampler与shuffle互斥的根源与正确写法
ValueError: sampler option is mutually exclusive with shuffle这个报错我在 PyTorch 的 DataLoader 上至少见过几十次了而且很有意思的是它经常不是新手专属——很多写了好几年模型的老手在从单机改成自定义采样器或者接入分布式训练的时候也会被这一行英文卡住。今天我就把这个问题彻底讲透从报错原理到正确的代码写法再到排查思路和同类报错一次性说清楚。这个错误本质上是 DataLoader 对参数组合的一道“硬性红线”你在初始化 DataLoader 的时候既传了 sampler又把 shuffle 参数设成了 TruePyTorch 干脆直接抛异常拒绝运行。它这么做不是故意给你添堵而是为了避免更隐蔽的错误。这篇文章适合正在被这个报错搞崩溃的 PyTorch 开发者看也适合想彻底理解 DataLoader 采样机制的读者——看完你不仅能修掉这个报错还能搞明白 shuffle、sampler、batch_sampler 这三者之间的关系以后再遇到类似参数冲突都能一眼看穿。1. 先复现这个报错搞明白它在说什么1.1 最典型的触发场景先看一段能稳定触发这个报错的代码。假设你有一个自定义数据集因为样本类别不均衡你打算用WeightedRandomSampler来采样于是写出了这样的初始化和 DataLoader 构造逻辑import torch from torch.utils.data import DataLoader, Dataset, WeightedRandomSampler class MyDataset(Dataset): def __len__(self): return 1000 def __getitem__(self, idx): return torch.tensor(idx, dtypetorch.float32) dataset MyDataset() # 给每个样本一个采样权重比如正负样本不均衡时 weights torch.ones(1000) weights[:100] 10.0 sampler WeightedRandomSampler(weights, num_samples500, replacementTrue) dataloader DataLoader( dataset, batch_size32, samplersampler, shuffleTrue, # 这里和 sampler 同时出现了 )一旦你运行到这一行PyTorch 就会直接给你甩出题目里那个报错ValueError: sampler option is mutually exclusive with shuffle这行报错的字面意思是sampler参数和shuffle参数是互斥的你不能同时指定。但很多人第一次看到mutually exclusive这个短语时第一反应是“哦我把两个参数都删掉一个就行”删完之后结果莫名其妙变好了但并不知道为什么下次遇到同类问题又开始懵。1.2 报错的完整信息和内部机制先看看 PyTorch 源码里到底在哪个环节做了拦截。DataLoader 的__init__里面有一段很直接的状态检查逻辑简化一下大概是这样的if shuffle: if sampler is not None or batch_sampler is not None: raise ValueError(sampler option is mutually exclusive with shuffle)也就是说只要shuffleTrue你再显式传sampler或者batch_sampler它就会报错。为什么要这么设计因为 DataLoader 在内部对“如何从数据集中取样本”这件事是有一套默认规则的当shuffleFalse的时候DataLoader 内部会用一个SequentialSampler按顺序从头到尾取样本。当shuffleTrue的时候DataLoader 内部会创建一个RandomSampler把索引顺序打乱后再取样本。如果你显式传入了samplerDataLoader 就会完全无视shuffle直接用你传进来的 sampler 去取样本。想一想如果你既告诉 DataLoader“你给我用随机采样器洗牌”又告诉它“用我自定义的这个 sampler 来决定采样顺序”那到底听谁的听你的 sampler那shuffleTrue就没有意义听shuffle那你辛辛苦苦写的采样器就白费了。这种二选一的矛盾与其悄悄忽略一个参数让你在训练结果里看到诡异的行为不如直接抛异常逼你明确自己的意图。从工程设计的角度来看PyTorch 这种做法其实非常明智。它把“采样顺序”这个关键职责统一交给 sampler 体系来管shuffle只是一个方便开关shuffleTrue就等价于内部帮你创建一个RandomSamplershuffleFalse就等价于创建SequentialSampler。所以当你自定义了 sampler实际上已经接管了“顺序怎么来”这件事shuffle参数自然就应该保持默认的False。2. 理解 DataLoader 的采样机制才能彻底搞懂2.1 shuffle 和 sampler 到底在干什么很多同学在写训练代码时对shuffle的理解停留在“打乱数据顺序避免模型学到顺序偏差”。这个理解没错但不够底层。在 DataLoader 的机制里采样过程真正发生的事情是先通过 sampler 获得一个“索引列表”然后 DataLoader 按这个索引列表去数据集里把对应样本取出来再按batch_size拼成 batch。举个例子一个数据集有 5 个样本索引分别是 0、1、2、3、4。shuffleFalse时SequentialSampler返回的索引序列是[0, 1, 2, 3, 4]shuffleTrue时RandomSampler返回的可能是[3, 0, 4, 1, 2]然后 DataLoader 按 batch_size2 切分第一批就是样本 3 和样本 0。当你自定义 sampler 时你就是自己实现那个“索引序列”的生成逻辑。WeightedRandomSampler按权重有放回地抽索引DistributedSampler在多卡环境下把数据切分给不同进程BatchSampler则是一次性生成一整批的索引列表。它们的本质都一样决定 DataLoader 以什么样的顺序去访问数据。所以shuffleTrue本质上只是“使用随机采样器”的语法糖而不是独立于 sampler 之外的另一个机制。理解了这一点你就明白为什么它俩不能共存——因为一旦显式指定 samplershuffle 这个语法糖就没法再套用一个隐式的 RandomSampler 了。2.2 自定义 sampler 的常见理由既然系统已经自带了SequentialSampler和RandomSampler为什么还要自定义 sampler我总结下来最常见的有三种场景第一种样本类别不均衡需要控制每个样本被抽中的概率。这是WeightedRandomSampler的典型用法。比如分类任务中正样本有 1000 条、负样本有 10000 条你不想简单粗暴地过采样可以用权重让正样本以更高的概率被抽中让模型每个 batch 里都看到足够的正样本。这类问题在文本分类、图像分类、点击率预估里非常常见。第二种多卡分布式训练时每张卡只需要处理数据集的一个分片。这种情况下要保证数据互不重复同时还要让不同进程之间的 shuffle 是协调一致的不能用普通的RandomSampler各洗各的否则不同卡上会出现重复或者漏掉的样本。DistributedSampler就是干这个的。第三种需要对数据顺序做特殊控制。比如训练序列模型时你可能希望同一 batch 内的样本长度尽量接近所以需要先按照序列长度排序或者分桶bucket再在每个桶内部做随机。这时候就要自定义一个按长度分组的 sampler。NLP 里的很多预处理任务就是这么干的。明白这些场景之后你就知道很多自定义 sampler 的场景里你根本不需要再额外打开shuffleTrue因为你的 sampler 自己已经带着随机逻辑了比如WeightedRandomSampler本身就是带放回的随机抽取。2.3 参数之间的“排他协议”shuffle、sampler 和 batch_sampler比shuffle和sampler的互斥关系更完整的是 DataLoader 里四个参数之间的“排他协议”参数作用冲突规则shuffle是否打乱样本顺序与sampler、batch_sampler互斥sampler决定每个样本的采样顺序与shuffle、batch_sampler互斥batch_sampler一次性生成 batch 级别的索引列表与batch_size、shuffle、sampler、drop_last互斥batch_size每个 batch 的样本数指定batch_sampler时不能传翻译成人话就是你在用sampler控制采样顺序就别再让shuffle插手。你在用batch_sampler直接指定“每个 batch 由哪些样本组成”那么batch_size、shuffle、sampler、drop_last这四个参数统统不能再传。如果你什么都不传DataLoader 默认使用SequentialSamplershuffle默认为Falsebatch_size1。这个协议非常像日常生活中“你选了套餐就不能再单点米饭”这种硬规则。它保证了采样职责的唯一性避免出现两个互相矛盾的指令同时生效。你理解了这套协议之后再看到 DataLoader 的初始化代码一眼就能判断它有没有踩红线。3. 实操几种正确的组合写法3.1 方案一保留 sampler关闭 shuffle最直接的修复方式就是把原来那段报错代码里的shuffleTrue改成shuffleFalse或者干脆删掉不写shuffle默认就是False。dataloader DataLoader( dataset, batch_size32, samplersampler, shuffleFalse, # 关键显式传 sampler 时这里必须为 False )这样改完之后你的WeightedRandomSampler会正常工作因为权重采样本身已经带了随机性——replacementTrue表示有放回抽样每次从全部样本里按权重随机抽一个索引出来。也就是说你的数据顺序已经是随机的了不需要 DataLoader 再做一层 shuffle。我见过不少同学在这里很担心“那我是不是失去了随机性”完全不是。WeightedRandomSampler的随机性体现在“每次按权重抽哪个样本”这件事本身它的__iter__方法每次都会重新随机抽取索引序列和RandomSampler的效果是一样的。你失去的只是一个多余的开关而不是随机性本身。3.2 方案二只用 shuffle不传 sampler如果你的需求只是“把数据顺序打乱”不需要任何自定义采样逻辑那最简单的写法就是dataloader DataLoader( dataset, batch_size32, shuffleTrue, )这种写法等价于内部创建了一个RandomSampler。它的随机性来自 DataLoader 遍历完一个 epoch 之后下一次iter(dataloader)时重新生成一个新的随机索引序列。所以当你不需要做特殊采样时不要画蛇添足地去显式传入RandomSampler再去设shuffleTrue。直接用shuffleTrue就是最干净的写法。如果你确实需要显式传入RandomSampler比如你想自定义num_samples或者设置replacement参数那就按方案一把shuffle关掉。3.3 方案三自定义 sampler 自带随机打乱有时候你的采样逻辑是自定义的但又想让它内部支持随机打乱。这时候正确的做法不是去设置 DataLoader 的shuffleTrue而是把这个随机逻辑写进 sampler 自己的__iter__方法里。举一个简单的自定义 sampler 例子import random from torch.utils.data import Sampler class MyCustomSampler(Sampler): def __init__(self, data_source, shuffleTrue): self.data_source data_source self.indices list(range(len(data_source))) self.shuffle shuffle def __iter__(self): if self.shuffle: random.shuffle(self.indices) return iter(self.indices) def __len__(self): return len(self.indices) sampler MyCustomSampler(dataset, shuffleTrue) dataloader DataLoader( dataset, batch_size32, samplersampler, # 这里不再需要也不会使用 shuffleTrue )这种模式在很多开源项目里很常见sampler 自己管理随机性DataLoader 只负责按索引取数。这样做的好处是采样逻辑完全内聚在一个类里面职责清晰也避免了外面再加shuffleTrue导致报错。3.4 方案四分布式训练里的 DistributedSampler再说一个非常高频的坑就是分布式训练。很多人会写出这样的代码from torch.utils.data.distributed import DistributedSampler import torch.distributed as dist sampler DistributedSampler(dataset, shuffleTrue) dataloader DataLoader( dataset, batch_size32, samplersampler, shuffleTrue, # 错误 )这个写法报的错和我们主题完全是同一个。正确的写法是 DataLoader 里不设shuffle让DistributedSampler自己去管sampler DistributedSampler(dataset, shuffleTrue) dataloader DataLoader( dataset, batch_size32, samplersampler, shuffleFalse, ) for epoch in range(num_epochs): sampler.set_epoch(epoch) # 关键每个 epoch 都要设置保证不同 epoch 的 shuffle 不同 for batch in dataloader: train(batch)这里有个额外的细节DistributedSampler内部有set_epoch方法你必须每个 epoch 都调用它否则每个 epoch 拿到的是完全一样的索引序列shuffle 就形同虚设了。从 PyTorch 1.x 开始DistributedSampler支持在初始化时传shuffleTrue然后在set_epoch(epoch)时根据 epoch 种子重新洗牌。DataLoader 层级的shuffle参数和它无关保持默认就好。3.5 进阶场景batch_sampler 的正确用法有些时候你的采样粒度不是“单个样本”而是“整个 batch”。比如训练推荐模型时你想一次性构造出“同一个 session 的用户行为序列”这样的 batch就需要自定义BatchSampler。from torch.utils.data import BatchSampler, SequentialSampler class MyBatchSampler(BatchSampler): def __init__(self, sampler, batch_size, drop_last): super().__init__(sampler, batch_size, drop_last) def __iter__(self): # 这里可以自定义如何合并样本索引 for batch_indices in super().__iter__(): yield batch_indices sampler SequentialSampler(dataset) batch_sampler MyBatchSampler(sampler, batch_size32, drop_lastFalse) dataloader DataLoader( dataset, batch_samplerbatch_sampler, # 此时不能再传 batch_size / shuffle / sampler / drop_last )注意这段代码注释里的关键点一旦你传了batch_sampler就不允许再传batch_size和shuffle否则 PyTorch 会抛出另一个类似的ValueError。这条规则是sampler option is mutually exclusive with shuffle的“姊妹规则”很多人修好了sampler和shuffle的冲突转头又在batch_sampler上踩了同样的坑。4. 同类 ValueError 实战排查与避坑建议4.1 相关的高频 ValueError 速查表在搜这个报错的时候很多人还会同时搜到其他一些长得差不多的ValueError它们不一定和 PyTorch 的 DataLoader 有关但字面都叫ValueError容易让人混淆。我整理了一个速查表你可以当作排查手册用报错信息可能原因解决思路ValueError: sampler option is mutually exclusive with shuffleDataLoader 同时指定了 sampler 和 shuffle二选一保留 sampler 就设 shuffleFalseValueError: batch_sampler option is mutually exclusive with batch_size, shuffle, sampler, and drop_last同时指定了 batch_sampler 与其他采样参数去掉 batch_size/shuffle/sampler/drop_lastValueError: Couldnt instantiate the backend tokenizer from one of: [网络模型地址]transformers 加载 tokenizer 时无法识别模型路径检查模型路径、是否下载完整、是否使用正确的 AutoTokenizerValueError: unsupported pickle protocol: 5pickle 数据由更高版本的 Python 生成升级 Python或者用原环境重新生成数据ValueError: unrecognized model in wangzejun/simbert-base-chinese. Should have...模型名不符合 transformers 命名规范或本地路径缺失确认模型名完整改用官方发布的模型标识符ValueError: unable to find resource t32.exe in package pip._vendored...pip 内部资源文件损坏或下载不完整重新安装 pip或升级到最新版本这里要特别说明一下后面几个和本文主题关系不大但它们出现频率很高很多时候是在搜索同一个关键词时被一起带出来的。如果你正好遇到这几个问题可以按表里的思路去查。4.2 标准的排查步骤遇到sampler option is mutually exclusive with shuffle这类报错我建议你按以下顺序排查不要一上来就盲目删参数第一步看完整的 traceback。注意报错信息会有两行实际含义是“DataLoader 构造时发现shuffleTrue而这个值应该只有在sampler is None时才允许生效”。所以先把报错定位到你正在构造 DataLoader 的那一行。第二步检查传入 DataLoader 的所有参数。很多人用dataclass或者配置字典来管理超参像这样dataloader DataLoader(dataset, **data_loader_params)如果data_loader_params里既包含sampler又包含shuffleTrue你直接在构造处检查是看不出来的得把字典打印出来看。我建议你用print(data_loader_params)先看一眼确认键值内容。这一步在调试时特别重要因为问题可能出在上游某个配置模块。第三步确认你对采样逻辑的需求。问自己一个问题我需要随机打乱数据吗如果需要是那种随机是全量随机还是按权重随机还是按分组随机对应需求选择合适的参数组合全量随机shuffleTrue即可。按权重随机WeightedRandomSamplershuffleFalse。分组随机自定义 sampler 内部做随机DataLoader 不设 shuffle。多卡随机DistributedSamplershuffleFalse 每个 epoch 调用set_epoch。第四步修改之后重新跑一个小规模的空训练循环不要直接跑全量数据。用一个少量样本的数据集验证 DataLoader 能正常迭代再投入正式训练避免浪费算力和时间。4.3 那些年我在 DataLoader 上踩过的别的坑除了sampler和shuffle的互斥问题DataLoader 还有几个坑跟它高度相关第一个是我上次自己掉进去的在编写自定义 Dataset 时内部如果维护了可变状态比如做数据增强时的随机状态、缓存等而你又用了多进程num_workers0数据会被多个 worker 复制多份它们的状态是各自独立的很容易出现“同一个 epoch 里某些样本被重复处理、某些样本没被处理”的诡异现象。这个坑排查起来比参数互斥更隐蔽。第二个坑是num_workers在 Windows 上如果不放在if __name__ __main__:块里会反复递归加载数据脚本报错起来很吓人。但根因往往和采样器无关而是多进程启动方式的问题。所以当你在 Windows 上看到奇奇怪怪的 DataLoader 报错时先检查你的入口函数写法。第三个坑是drop_last和自定义 sampler 的__len__不一致。如果你的 sampler 返回的索引数量不能被batch_size整除又没设置drop_lastTrue最后一个 batch 会比其他 batch 小。很多新手在这个地方会困惑“为什么我的 batch 大小忽大忽小”实际上这就是采样数量分布的问题不是采样器坏了。第四个坑是在做验证集评估时有人习惯性地也给验证集 DataLoader 传入shuffleTrue导致每个 epoch 验证集顺序都不一样进而导致某些依赖“固定顺序”的指标计算比如排序类指标出现偏差结果波动很大。验证集和测试集通常应该保持固定的顺序shuffleFalse就好。4.4 一个彻底避免这类报错的习惯我现在写训练代码对 DataLoader 参数的写法有一套固定习惯基本不会再踩到sampler option is mutually exclusive with shuffle这类的坑如果只写普通训练脚本不是分布式不是自定义采样那就只用shuffle参数不碰sampler。如果需要处理不平衡数据那就显式创建WeightedRandomSampler并强制把 DataLoader 的shuffle写成显式的shuffleFalse不依赖默认值。这个“显式”很重要因为将来别人接手代码时一眼就能看出你是故意关掉 shuffle 的而不是忘写了。如果代码里出现了sampler和shuffle同时为真的情况我会把它当成一个“不合法状态”来处理而不是单纯依赖 PyTorch 的报错。所以在自己封装的数据加载模块里我还会加一层断言assert not (sampler is not None and shuffle), sampler and shuffle cannot be both set这层断言在 PyTorch 报错之前就能帮你拦住有问题的配置而且在你的自定义组件之间传递参数时特别有用能让你第一时间定位到是哪个模块把参数配错了。写在后面修复这个报错只是第一步说实话sampler option is mutually exclusive with shuffle这个报错本身并不是什么大难题把它修掉可能只需要改一个单词。但它背后的采样机制和 DataLoader 参数之间的排他协议才是真正值得理解的东西。我见过很多人在这个报错上消化的时间很短修完就忘了结果过两周在别的项目里又踩一次——因为这种“参数互相排斥”的设计在 PyTorch 里并不少见理解了这套思路你以后看batch_sampler、collate_fn、pin_memory这些参数的组合方式都会快很多。我个人在实际操作中最深的体会是不要急着把报错改掉先花几分钟搞清楚 PyTorch 为什么不允许这种组合。每一个看似多余的异常都在告诉你一个设计约束。当你真正理解了 DataLoader 是先通过 sampler 生成索引、再按索引取样本、最后拼成 batch 这个完整流程之后这一类参数冲突问题就再也不会迷惑你了。最后再分享一个小技巧如果你的代码里用了很多配置项来动态组装 DataLoader建议在配置结构体里单独开一个sampler字段和shuffle字段并且在构造 DataLoader 之前打印一遍完整参数确保没有同时出现。实测下来这个习惯能帮你在调试这种报错时省下不少时间。