常见报错如OutOfRangeError或InvalidArgumentError，大概率因解析逻辑与写入feature描述不一致：需严格匹配bytes_list/float_list/int64_list类型、FixedLenFeature/VarLenFeature形状，且parse_sequence_example仅适用于SequenceExample文件。
tf.data.TFRecordDataset 读取失败的常见报错怎么快速定位
直接报 OutOfRangeError: End of sequence 或 InvalidArgumentError: Could not parse example？大概率不是数据损坏，而是解析逻辑和写入时的 feature 描述不一致。TFRecord 本身不存 schema，全靠你写的 parse_fn 去“猜”字段类型和形状。
- 先确认写入时用的
tf.train.Example中每个feature的类型（bytes_list/float_list/int64_list），读取时必须严格对应 —— 比如写的是int64_list，却用tf.io.FixedLenFeature([], tf.int32)就会崩 - 检查 shape：标量字段写成
tf.io.FixedLenFeature([], ...)，变长列表得用tf.io.VarLenFeature(...)，否则parse_single_example会直接抛异常 - 如果用了
tf.io.parse_sequence_example却传了非 SequenceExample 文件，也会报类似InvalidArgumentError
怎么写一个健壮的 parse_fn 避免反复改代码
别把所有字段硬编码进 tf.io.FixedLenFeature 字典里。用字典生成 + 类型校验更省事，尤其当你有几十个字段时。
- 字段名和类型存在一个配置字典里，比如
features_dict = {"image": tf.io.FixedLenFeature([], tf.string), "label": tf.io.FixedLenFeature([], tf.int64)}，然后直接传给tf.io.parse_single_example - 对 bytes 类型的 image，务必在
parse_fn里紧接着调用tf.io.decode_jpeg或tf.io.decode_png，否则后续模型层会报 tensor dtype 不匹配 - 如果 label 是 one-hot 形式存的，写入时是
float_list，读取后要tf.reshape成正确维度，否则 batch 维度可能错乱
tf.data.TFRecordDataset 的 num_parallel_reads 和 prefetch 怎么设才不拖慢训练
默认 num_parallel_reads=1 是瓶颈。多文件场景下不并行读，IO 就卡死；但设太大又抢 CPU，尤其配合 map 解析时容易挤占模型计算资源。
- 单机多文件：设为 CPU 核数的 1.5–2 倍（比如 8 核就用
num_parallel_reads=12），比盲目设tf.data.AUTOTUNE更稳 -
prefetch放在 pipeline 最末尾（即 map、batch 之后），值设为tf.data.AUTOTUNE即可；放早了反而导致内存暴涨，特别是 decode 图片后 tensor 变大 - 如果用了
cache()，确保它在map之后、batch之前 —— 否则缓存的是原始 bytes，每次 batch 还得重复 decode
为什么 shuffle(buffer_size) 放在 repeat() 前后结果差很多
顺序错了会导致 epoch 内样本分布失真，甚至某些样本连续出现多次，另一些压根没被采到。
- 正确顺序是：
dataset = dataset.shuffle(10000).repeat().batch(32)—— 先打乱整个数据集，再循环，最后分批 - 如果写成
repeat().shuffle(...)，相当于每个 epoch 都从头 shuffle，但 buffer 初始为空，前几轮实际没打乱；更糟的是，如果 buffer_size 小于总样本数，shuffle 效果极弱 - buffer_size 不必等于总数，一般设为 10–100 倍 batch size 即可（如 batch=32，buffer_size=2048），太大会吃内存，太小打乱不充分
真正麻烦的是跨文件 shuffle：TFRecord 天然按文件切分，如果你有 100 个文件但只 shuffle 其中 10 个的路径，那剩下 90 个永远在后面 —— 所以 shuffle 必须作用在最终的 TFRecordDataset 实例上，而不是文件路径列表。
