tf.image.augment_image 根本不是 tensorflow 的公开 api，它既不在官方文档里，也不在 tf.image 模块的导出列表中。
tf.image.augment_image 不存在？别调用这个函数
直接说结论：tf.image.augment_image 根本不是 TensorFlow 的公开 API，它既不在官方文档里，也不在 tf.image 模块的导出列表中。你搜到的示例大概率是旧版 TF 0.x 的遗留写法，或是把 Keras 预处理层（如 tf.keras.layers.RandomFlip）和 tf.image 函数混用了。
真正可用的是一个个独立的、确定行为的图像变换函数，比如 tf.image.random_flip_left_right、tf.image.rot90、tf.image.adjust_brightness 等。它们不自动组合，也不带“增强流水线”概念——那得你自己串起来。
- 所有
tf.image函数都只接受uint8或float32张量，输入 shape 必须是[height, width, channels]（不能带 batch 维度） - 函数返回值类型与输入一致，但部分操作（如归一化后缩放）可能隐式改变数值范围，需留意后续模型输入要求
- 没有内置“随机概率开关”，
random_*系列函数每次调用都强制随机，如需条件控制（比如 50% 概率翻转），得自己套tf.cond或用tf.random.uniform判定
构建可复用的增强流水线：用 tf.function + tf.data.Dataset.map
生产环境的数据增强必须和 tf.data.Dataset 流水线绑定，否则无法并行、无法缓存、无法在 GPU/TPU 上高效调度。核心是把多个 tf.image 操作封装进一个 @tf.function 函数，再传给 dataset.map()。
例如实现「随机水平翻转 + 随机亮度扰动 + 归一化」：
@tf.function
def augment_fn(image, label):
image = tf.cast(image, tf.float32) # 确保 float32，避免 uint8 下 adjust_brightness 溢出
image = tf.image.random_flip_left_right(image)
image = tf.image.adjust_brightness(image, tf.random.uniform([], -0.2, 0.2))
image = image / 255.0 # 归一化到 [0,1]
return image, label
- 必须用
@tf.function包裹，否则map会退化为 Python 调用，失去图优化和加速能力 -
tf.image.adjust_brightness对uint8输入有未定义行为，务必先转float32 - 不要在
map外预计算随机数（如tf.random.uniform放在函数外），否则所有样本得到相同增强结果
batch 前还是 batch 后做增强？顺序影响显存和效果
增强必须在 dataset.batch() 之前做。因为 tf.image 函数不支持 batch 维度（即 shape 不能是 [B, H, W, C]），强行传入会报错：ValueError: Image must be 3D。
典型正确顺序是：from_tensor_slices → map(augment_fn) → cache() → shuffle() → batch() → prefetch()。
- 如果先
batch再想增强，只能改用tf.vectorized_map或拆成循环，性能暴跌且易出错 -
cache()放在map后、shuffle前能缓存已增强数据，适合小数据集；但若增强含随机性（如上面例子），缓存就失去意义，此时应把cache移到map前（缓存原始数据） - 增强强度过高（如大角度旋转+裁剪）可能导致部分样本内容丢失，建议在增强后加简单校验逻辑（如检查像素均值是否过低），但注意这会增加图复杂度
和 tf.keras.layers.Random* 的关键区别在哪
从 TF 2.3 开始，Keras 层（如 tf.keras.layers.RandomFlip）也能做在线增强，但它和 tf.image 是两套机制：
-
tf.keras.layers.Random*是模型层，必须嵌入tf.keras.Model中，运行在model.fit()期间；而tf.image函数可自由组合，适用于自定义训练循环或非 Keras 场景 - Keras 层默认作用于 batch 维度（
[B, H, W, C]），无需手动去 batch；tf.image必须单张处理，靠map隐式批量 - Keras 层的随机种子控制更直观（
seed=参数），tf.image需统一管理tf.random.set_seed()或用tf.random.Generator - 混合使用容易出问题：比如在
map里调用 Keras 层，会触发 eager 执行，破坏图模式，报错Cannot use 'X' as input to a function
增强逻辑越简单、越固定，越推荐用 Keras 层；需要精细控制每步数值范围、调试中间结果、或脱离 Keras 生态时，tf.image 是唯一选择。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
