根本原因是num_parallel_calls默认为none导致map()串行阻塞，应设为tf.data.autotune，并严格按map()→cache()→shuffle()→batch()→prefetch()顺序配置流水线。
训练卡在第一个 batch 或反复停顿，大概率不是模型或数据出问题，而是 tf.data 流水线没跑起来——GPU 在等 CPU 喂数据，CPU 却卡在串行读取、单线程解码或 shuffle 重置上。
tf.data.map() 为什么总在第一步卡住
默认 num_parallel_calls=None，map() 退化为单线程执行，尤其遇到 tf.io.read_file、tf.image.decode_jpeg 或 tf.py_function 时，整个流水线就堵死。
- 必须显式设
num_parallel_calls=tf.data.AUTOTUNE，别用固定数字（不同机器核数不同） - 如果用了
tf.py_function，不加num_parallel_calls就一定单线程，哪怕你开了 32 个 worker -
map()里别做同步 IO：比如每次调用都打开 config.json、查数据库、发 HTTP 请求——这些全得提前加载到内存或用tf.lookup.StaticHashTable
prefetch() 放错位置反而拖慢训练
写成 dataset.prefetch().batch() 是常见错误：prefetch 提前拉的是未 batch 的原始样本，GPU 等着拼 batch，CPU 却在拼命 yield 单条记录。
- 正确顺序只能是：
map()→cache()→shuffle()→batch()→prefetch() -
prefetch(1)够用；设成tf.data.AUTOTUNE可能吃光内存，尤其 batch size 大或样本本身大（如高分辨率图像） - 无限数据集（如流式生成器）上用
prefetch()没意义，它会无限制堆积，最终 OOM
shuffle() 和 cache() 组合不当引发 epoch 间卡顿
实测发现：shuffle(buffer_size=10000) 单独用，每个 epoch 开始前都要重建 buffer，导致“训练很快，但等下一 epoch 开始要卡十几秒”；cache() 单独用，若数据集太大，首次加载就内存爆炸。
- 小/中等静态数据集（map()，再
cache()，然后shuffle()—— 避免重复解码 - 大静态数据集：改用
cache('/path/to/disk/cache')写磁盘，别硬扛内存 - 千万别把
shuffle()放在prefetch()后面——它会强制重置迭代器，prefetch 缓存全失效
from_generator() 不是万能解药，极易隐式串行
tf.data.Dataset.from_generator() 看似灵活，但 generator yield 过程本身不支持并行；TF 只能在 yield 出来之后才对单条样本做 map() 并行，yield 这一步仍是单线程阻塞。
- generator 函数体内禁止
time.sleep()、requests.get()等同步阻塞操作 - 返回 numpy 数组时，务必在
map()中显式转tf.convert_to_tensor()，别依赖自动转换（可能触发隐式 copy） - 能用
tf.data.TFRecordDataset或from_tensor_slices().interleave()就别用 generator——后者性能通常低 2–3 倍
真正卡顿的根源，往往藏在「CPU 利用率 100% 但 GPU-util 为 0」这个现象背后：不是代码逻辑错，而是数据供给节奏没对齐 GPU 计算节奏。调优不是堆参数，而是让每一步操作都明确知道它该在哪个阶段并行、缓存、预取——少一个环节，整条流水线就断在那个点上。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
