企业官网建设流程全解析

ValueError: sampler option is mutually exclusive with shuffle，这个报错我在 PyTorch 的 DataLoader 上至少见过几十次了，而且很有意思的是，它经常不是新手专属——很多写了好几年模型的老手，在从单机改成自定义采样器，或者接入分布式训练的时候，也会被这一行英文卡住。今天我就把这个问题彻底讲透，从报错原理到正确的代码写法，再到排查思路和同类报错，一次性说清楚。

这个错误本质上是 DataLoader 对参数组合的一道“硬性红线”：你在初始化 DataLoader 的时候，既传了 sampler，又把 shuffle 参数设成了 True，PyTorch 干脆直接抛异常拒绝运行。它这么做不是故意给你添堵，而是为了避免更隐蔽的错误。这篇文章适合正在被这个报错搞崩溃的 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, dtype=torch.float32) dataset = MyDataset() # 给每个样本一个采样权重，比如正负样本不均衡时 weights = torch.ones(1000) weights[:100] = 10.0 sampler = WeightedRandomSampler(weights, num_samples=500, replacement=True) dataloader = DataLoader( dataset, batch_size=32, sampler=sampler, shuffle=True, # 这里和 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")

也就是说，只要shuffle=True，你再显式传sampler（或者batch_sampler），它就会报错。为什么要这么设计？因为 DataLoader 在内部对“如何从数据集中取样本”这件事是有一套默认规则的：

• 当shuffle=False的时候，DataLoader 内部会用一个SequentialSampler，按顺序从头到尾取样本。
• 当shuffle=True的时候，DataLoader 内部会创建一个RandomSampler，把索引顺序打乱后再取样本。
• 如果你显式传入了sampler，DataLoader 就会完全无视shuffle，直接用你传进来的 sampler 去取样本。

想一想，如果你既告诉 DataLoader“你给我用随机采样器洗牌”，又告诉它“用我自定义的这个 sampler 来决定采样顺序”，那到底听谁的？听你的 sampler，那shuffle=True就没有意义；听shuffle，那你辛辛苦苦写的采样器就白费了。这种二选一的矛盾，与其悄悄忽略一个参数，让你在训练结果里看到诡异的行为，不如直接抛异常逼你明确自己的意图。

从工程设计的角度来看，PyTorch 这种做法其实非常明智。它把“采样顺序”这个关键职责统一交给 sampler 体系来管，shuffle只是一个方便开关：shuffle=True就等价于内部帮你创建一个RandomSampler，shuffle=False就等价于创建SequentialSampler。所以当你自定义了 sampler，实际上已经接管了“顺序怎么来”这件事，shuffle参数自然就应该保持默认的False。

2. 理解 DataLoader 的采样机制，才能彻底搞懂

2.1 shuffle 和 sampler 到底在干什么

很多同学在写训练代码时，对shuffle的理解停留在“打乱数据顺序，避免模型学到顺序偏差”。这个理解没错，但不够底层。在 DataLoader 的机制里，采样过程真正发生的事情是：先通过 sampler 获得一个“索引列表”，然后 DataLoader 按这个索引列表去数据集里把对应样本取出来，再按batch_size拼成 batch。

举个例子，一个数据集有 5 个样本，索引分别是 0、1、2、3、4。shuffle=False时，SequentialSampler返回的索引序列是：

[0, 1, 2, 3, 4]

shuffle=True时，RandomSampler返回的可能是：

[3, 0, 4, 1, 2]

然后 DataLoader 按 batch_size=2 切分，第一批就是样本 3 和样本 0。

当你自定义 sampler 时，你就是自己实现那个“索引序列”的生成逻辑。WeightedRandomSampler按权重有放回地抽索引，DistributedSampler在多卡环境下把数据切分给不同进程，BatchSampler则是一次性生成一整批的索引列表。它们的本质都一样：决定 DataLoader 以什么样的顺序去访问数据。

所以，shuffle=True本质上只是“使用随机采样器”的语法糖，而不是独立于 sampler 之外的另一个机制。理解了这一点，你就明白为什么它俩不能共存——因为一旦显式指定 sampler，shuffle 这个语法糖就没法再套用一个隐式的 RandomSampler 了。

2.2 自定义 sampler 的常见理由

既然系统已经自带了SequentialSampler和RandomSampler，为什么还要自定义 sampler？我总结下来，最常见的有三种场景：

第一种，样本类别不均衡，需要控制每个样本被抽中的概率。这是WeightedRandomSampler的典型用法。比如分类任务中正样本有 1000 条、负样本有 10000 条，你不想简单粗暴地过采样，可以用权重让正样本以更高的概率被抽中，让模型每个 batch 里都看到足够的正样本。这类问题在文本分类、图像分类、点击率预估里非常常见。

第二种，多卡分布式训练时，每张卡只需要处理数据集的一个分片。这种情况下要保证数据互不重复，同时还要让不同进程之间的 shuffle 是协调一致的，不能用普通的RandomSampler各洗各的，否则不同卡上会出现重复或者漏掉的样本。DistributedSampler就是干这个的。

第三种，需要对数据顺序做特殊控制。比如训练序列模型时，你可能希望同一 batch 内的样本长度尽量接近，所以需要先按照序列长度排序或者分桶（bucket），再在每个桶内部做随机。这时候就要自定义一个按长度分组的 sampler。NLP 里的很多预处理任务就是这么干的。

明白这些场景之后，你就知道，很多自定义 sampler 的场景里你根本不需要再额外打开shuffle=True，因为你的 sampler 自己已经带着随机逻辑了，比如WeightedRandomSampler本身就是带放回的随机抽取。

2.3 参数之间的“排他协议”：shuffle、sampler 和 batch_sampler

比shuffle和sampler的互斥关系更完整的，是 DataLoader 里四个参数之间的“排他协议”：

翻译成人话就是：

• 你在用sampler控制采样顺序，就别再让shuffle插手。
• 你在用batch_sampler直接指定“每个 batch 由哪些样本组成”，那么batch_size、shuffle、sampler、drop_last这四个参数统统不能再传。
• 如果你什么都不传，DataLoader 默认使用SequentialSampler，shuffle默认为False，batch_size=1。

这个协议非常像日常生活中“你选了套餐就不能再单点米饭”这种硬规则。它保证了采样职责的唯一性，避免出现两个互相矛盾的指令同时生效。你理解了这套协议之后，再看到 DataLoader 的初始化代码，一眼就能判断它有没有踩红线。

3. 实操：几种正确的组合写法

3.1 方案一：保留 sampler，关闭 shuffle

最直接的修复方式，就是把原来那段报错代码里的shuffle=True改成shuffle=False，或者干脆删掉不写（shuffle默认就是False）。

dataloader = DataLoader( dataset, batch_size=32, sampler=sampler, shuffle=False, # 关键：显式传 sampler 时这里必须为 False )

这样改完之后，你的WeightedRandomSampler会正常工作，因为权重采样本身已经带了随机性——replacement=True表示有放回抽样，每次从全部样本里按权重随机抽一个索引出来。也就是说你的数据顺序已经是随机的了，不需要 DataLoader 再做一层 shuffle。

我见过不少同学在这里很担心：“那我是不是失去了随机性？”完全不是。WeightedRandomSampler的随机性体现在“每次按权重抽哪个样本”这件事本身，它的__iter__方法每次都会重新随机抽取索引序列，和RandomSampler的效果是一样的。你失去的只是一个多余的开关，而不是随机性本身。

3.2 方案二：只用 shuffle，不传 sampler

如果你的需求只是“把数据顺序打乱”，不需要任何自定义采样逻辑，那最简单的写法就是：

dataloader = DataLoader( dataset, batch_size=32, shuffle=True, )

这种写法等价于内部创建了一个RandomSampler。它的随机性来自 DataLoader 遍历完一个 epoch 之后，下一次iter(dataloader)时重新生成一个新的随机索引序列。

所以当你不需要做特殊采样时，不要画蛇添足地去显式传入RandomSampler，再去设shuffle=True。直接用shuffle=True就是最干净的写法。如果你确实需要显式传入RandomSampler（比如你想自定义num_samples或者设置replacement参数），那就按方案一，把shuffle关掉。

3.3 方案三：自定义 sampler 自带随机打乱

有时候你的采样逻辑是自定义的，但又想让它内部支持随机打乱。这时候正确的做法不是去设置 DataLoader 的shuffle=True，而是把这个随机逻辑写进 sampler 自己的__iter__方法里。

举一个简单的自定义 sampler 例子：

import random from torch.utils.data import Sampler class MyCustomSampler(Sampler): def __init__(self, data_source, shuffle=True): 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, shuffle=True) dataloader = DataLoader( dataset, batch_size=32, sampler=sampler, # 这里不再需要也不会使用 shuffle=True )

这种模式在很多开源项目里很常见：sampler 自己管理随机性，DataLoader 只负责按索引取数。这样做的好处是采样逻辑完全内聚在一个类里面，职责清晰，也避免了外面再加shuffle=True导致报错。

3.4 方案四：分布式训练里的 DistributedSampler

再说一个非常高频的坑，就是分布式训练。很多人会写出这样的代码：

from torch.utils.data.distributed import DistributedSampler import torch.distributed as dist sampler = DistributedSampler(dataset, shuffle=True) dataloader = DataLoader( dataset, batch_size=32, sampler=sampler, shuffle=True, # 错误！ )

这个写法报的错和我们主题完全是同一个。正确的写法是 DataLoader 里不设shuffle，让DistributedSampler自己去管：

sampler = DistributedSampler(dataset, shuffle=True) dataloader = DataLoader( dataset, batch_size=32, sampler=sampler, shuffle=False, ) 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支持在初始化时传shuffle=True，然后在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_size=32, drop_last=False) dataloader = DataLoader( dataset, batch_sampler=batch_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，容易让人混淆。我整理了一个速查表，你可以当作排查手册用：

这里要特别说明一下，后面几个和本文主题关系不大，但它们出现频率很高，很多时候是在搜索同一个关键词时被一起带出来的。如果你正好遇到这几个问题，可以按表里的思路去查。

4.2 标准的排查步骤

遇到sampler option is mutually exclusive with shuffle这类报错，我建议你按以下顺序排查，不要一上来就盲目删参数：

第一步，看完整的 traceback。注意报错信息会有两行，实际含义是“DataLoader 构造时发现shuffle=True，而这个值应该只有在sampler is None时才允许生效”。所以先把报错定位到你正在构造 DataLoader 的那一行。

第二步，检查传入 DataLoader 的所有参数。很多人用dataclass或者配置字典来管理超参，像这样：

dataloader = DataLoader(dataset, **data_loader_params)

如果data_loader_params里既包含sampler又包含shuffle=True，你直接在构造处检查是看不出来的，得把字典打印出来看。我建议你用print(data_loader_params)先看一眼，确认键值内容。这一步在调试时特别重要，因为问题可能出在上游某个配置模块。

第三步，确认你对采样逻辑的需求。问自己一个问题：我需要随机打乱数据吗？如果需要，是那种随机？是全量随机，还是按权重随机，还是按分组随机？对应需求选择合适的参数组合：

• 全量随机：shuffle=True即可。
• 按权重随机：WeightedRandomSampler+shuffle=False。
• 分组随机：自定义 sampler 内部做随机，DataLoader 不设 shuffle。
• 多卡随机：DistributedSampler+shuffle=False+ 每个 epoch 调用set_epoch。

第四步，修改之后重新跑一个小规模的空训练循环，不要直接跑全量数据。用一个少量样本的数据集验证 DataLoader 能正常迭代，再投入正式训练，避免浪费算力和时间。

4.3 那些年我在 DataLoader 上踩过的别的坑

除了sampler和shuffle的互斥问题，DataLoader 还有几个坑跟它高度相关，第一个是我上次自己掉进去的：在编写自定义 Dataset 时，内部如果维护了可变状态（比如做数据增强时的随机状态、缓存等），而你又用了多进程num_workers>0，数据会被多个 worker 复制多份，它们的状态是各自独立的，很容易出现“同一个 epoch 里某些样本被重复处理、某些样本没被处理”的诡异现象。这个坑排查起来比参数互斥更隐蔽。

第二个坑是num_workers在 Windows 上如果不放在if __name__ == '__main__':块里，会反复递归加载数据脚本，报错起来很吓人。但根因往往和采样器无关，而是多进程启动方式的问题。所以当你在 Windows 上看到奇奇怪怪的 DataLoader 报错时，先检查你的入口函数写法。

第三个坑是drop_last和自定义 sampler 的__len__不一致。如果你的 sampler 返回的索引数量不能被batch_size整除，又没设置drop_last=True，最后一个 batch 会比其他 batch 小。很多新手在这个地方会困惑“为什么我的 batch 大小忽大忽小”，实际上这就是采样数量分布的问题，不是采样器坏了。

第四个坑是在做验证集评估时，有人习惯性地也给验证集 DataLoader 传入shuffle=True，导致每个 epoch 验证集顺序都不一样，进而导致某些依赖“固定顺序”的指标计算（比如排序类指标）出现偏差，结果波动很大。验证集和测试集通常应该保持固定的顺序，shuffle=False就好。

4.4 一个彻底避免这类报错的习惯

我现在写训练代码，对 DataLoader 参数的写法有一套固定习惯，基本不会再踩到sampler option is mutually exclusive with shuffle这类的坑：

• 如果只写普通训练脚本，不是分布式，不是自定义采样，那就只用shuffle参数，不碰sampler。
• 如果需要处理不平衡数据，那就显式创建WeightedRandomSampler，并强制把 DataLoader 的shuffle写成显式的shuffle=False，不依赖默认值。这个“显式”很重要，因为将来别人接手代码时，一眼就能看出你是故意关掉 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 之前打印一遍完整参数，确保没有同时出现。实测下来，这个习惯能帮你在调试这种报错时省下不少时间。