关键在于用 tf.data.dataset 分别构建标记与未标记数据集，再通过 zip 同步配对，确保每步训练同时获取一个标记 batch 和一个未标记 batch，避免拼接、错误填充标签或 repeat 不匹配等问题。
用 tf.data 构建带标记/未标记混合数据流
半监督学习的关键不是改模型结构，而是让训练时能同时喂入标记样本（有 y）和未标记样本（只有 x）。TensorFlow 里最稳妥的方式是用 tf.data.Dataset 分别构造两个数据集，再用 tf.data.Dataset.zip() 配对合并——注意不是拼接（concatenate），因为每步训练需要同步取一个标记 batch 和一个未标记 batch。
常见错误是把未标记数据强行塞进同一张 label tensor，填 -1 或 0 导致 loss 计算异常；也有人误用 repeat() 不匹配导致 zip 报 OutOfRangeError。
- 标记数据集输出 shape：(
x_batch,y_batch)，dtype 通常为float32/int32 - 未标记数据集只输出
x_unlabeled_batch，但必须和标记 batch 的 batch size 一致（如都设为 32） - zip 前分别调用
.repeat()和.shuffle(buffer_size)，确保两者 epoch 步数对齐 - 最终 dataset 输出结构建议为：
(x_l, y_l), x_ul，便于 model call 和 loss 分离计算
在自定义训练循环中分离监督 loss 和一致性正则项
TensorFlow 原生不提供现成的半监督 loss（比如 Mean Teacher、UDA、FixMatch），得手动组合。核心逻辑是：对标记样本算交叉熵，对未标记样本加一致性约束（如弱增强 vs 强增强预测一致、或对同一输入多次 dropout 输出一致）。
容易被忽略的是梯度更新范围——未标记部分的 loss 不能反传到 embedding 层之前（除非你真想做表征学习），否则会污染特征空间；更常见的做法是只让一致性 loss 影响最后几层或分类头。
- 用
tf.GradientTape(persistent=True)可分别记录两部分 loss 的梯度 - 监督 loss（
tf.keras.losses.sparse_categorical_crossentropy）只基于x_l和y_l - 一致性 loss（如 MSE 或 KL 散度）需对
x_ul做两次前向：一次标准推断，一次加扰动（tf.image.random_flip_left_right+tf.image.random_saturation） - 建议用
tf.stop_gradient()固定弱增强分支输出，只优化强增强分支——这是 FixMatch 的关键
用 tf.keras.Model.train_step 封装逻辑更可控
相比写完整训练循环，重载 train_step 更简洁且兼容 model.fit()。但它默认只接收一个 data 参数，所以得提前把混合数据打包成元组传入，例如：dataset = tf.data.Dataset.zip((labeled_ds, unlabeled_ds))，然后在 train_step(self, data) 中解包为 (x_l, y_l), x_ul = data。
这里有个隐藏坑：如果未标记数据量远大于标记数据，fit() 的 steps_per_epoch 应按标记数据量算（否则多跑的 step 全是无效未标记 batch），而不能依赖 dataset 自动推断。
- 重载时别忘调用
super().train_step()仅用于标记部分？不行——得完全自己写 forward + loss + grad + apply -
self.compiled_loss只适用于监督 loss；一致性 loss 得手写并加权（如 λ=1.0） - 记得在
@tf.function装饰下运行整个train_step，否则图模式下tf.random行为可能异常
验证时只用标记数据，但监控未标记预测置信度分布
评估指标（accuracy、F1）永远只在验证集（全标记）上算，这点不能妥协。但半监督训练是否健康，要看未标记数据的预测输出是否逐渐“尖锐化”——即 softmax 最大值的均值是否随 epoch 上升。这比看 train loss 下降更可靠。
另一个易错点：在 @tf.function 内直接 print 置信度会失效，得用 tf.print，且最好限制频率（如每 100 step 一次），否则 I/O 拖慢训练。
- 加一段验证钩子：每个 epoch 结束后，抽 1000 个未标记样本过模型，统计
tf.reduce_max(tf.nn.softmax(logits), axis=-1)的均值和 std - 如果均值长期卡在 0.4~0.5，说明模型没学会区分，可能是强增强太猛、λ 设太大、或标注数据太少
- 不要用未标记数据做 early stopping——它没真实标签，loss 值无意义
半监督真正难的不是代码实现，而是未标记数据质量不可控、增强策略与任务耦合深、以及监督信号稀疏时梯度方向容易漂移。动手前先可视化几组强/弱增强结果，比调十次 learning rate 更有效。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
