TensorFlow原生不支持半监督对比学习端到端封装，需手动构建混合数据流、自定义InfoNCE损失、分离监督/对比分支梯度更新，并注意tf.function重追踪、多卡all-gather及温度参数可训练等关键细节。
TensorFlow 原生不提供半监督对比学习（semi-supervised contrastive learning）的端到端封装接口，必须手动组合数据流、损失计算与训练逻辑；直接调用 tf.keras.losses.SparseCategoricalCrossentropy 或 tf.keras.losses.ContrastiveLoss 都无法满足需求——后者是为 Siamese 网络设计的二元对损失，不适用于多正例/多负例的 InfoNCE 变体。
构建带标签/无标签混合数据管道
半监督对比学习依赖两类样本：少量带标签样本（用于监督分支）和大量无标签样本（用于对比分支），二者需在 batch 内协同采样，不能简单拼接或交替喂入。
- 用
tf.data.Dataset.from_tensor_slices分别加载 labeled 和 unlabeled 数据，对 labeled 数据额外附加label字段，unlabeled 数据仅保留image - 对 unlabeled 数据应用两次不同强度的增强（如 RandAugment + GaussianBlur），生成
view1和view2，构成对比对；labeled 数据只需一次增强（用于监督分类） - 使用
tf.data.Dataset.zip将 labeled batch 与 unlabeled batch 对齐，并通过batch(32)统一尺寸（例如 16 labeled + 16 unlabeled → 总 batch_size=32） - 避免用
repeat()过早打乱节奏——应在每个 epoch 内重置 unlabeled 数据的 shuffle 状态，否则负样本分布会漂移
实现 InfoNCE 损失的自定义训练步骤
核心是复现 SimCLR / MoCo 中的归一化温度缩放点积损失，TensorFlow 没有现成的 tf.keras.losses.NTXentLoss，必须手写，且要注意梯度截断与数值稳定性。
- 编码器输出先经
tf.linalg.l2_normalize归一化，再用tf.matmul计算相似度矩阵 - 温度参数
temperature必须作为可训练变量（如self.temperature = tf.Variable(0.1, trainable=True)），而非固定常量，否则收敛困难 - 构造正例掩码时，对 unlabeled batch 中的每对
(view1[i], view2[i])设为正例，其余均为负例；注意排除自对比（i.e.,view1[i]与view1[j]不构成正例） - 用
tf.math.logsumexp替代tf.reduce_logsumexp（后者已弃用），并减去对角线上的正例 logit 避免 NaN
def compute_infonce_loss(self, z1, z2, temperature=0.1):
z = tf.concat([z1, z2], axis=0) # [2N, D]
sim = tf.matmul(z, z, transpose_b=True) / temperature # [2N, 2N]
sim = sim - tf.eye(tf.shape(sim)[0]) * 1e9 # mask self-sim
logits = sim
labels = tf.concat([tf.range(tf.shape(z1)[0]),
tf.range(tf.shape(z1)[0])], axis=0)
return tf.keras.losses.sparse_categorical_crossentropy(
labels, logits, from_logits=True)
联合优化监督损失与对比损失
不能把两个 loss 简单相加后反向传播——监督分支（分类头）和对比分支（投影头）共享主干网络，但梯度更新节奏不同：分类 loss 对 labeled 样本敏感，而对比 loss 在 unlabeled 样本上更平滑。直接加权平均（如 0.5 * sup_loss + 0.5 * cont_loss）会导致 early stopping 或 label leakage。
立即学习“Python免费学习笔记（深入）”；
- 对 labeled batch 单独计算
tf.keras.losses.SparseCategoricalCrossentropy(from_logits=True)，只更新分类头 + 主干 - 对 unlabeled batch 单独计算 InfoNCE loss，只更新投影头（
projection_head）+ 主干，**禁用分类头梯度**（可用with tf.GradientTape(persistent=True)分离 tape） - 用
tf.keras.optimizers.Adam时，建议为投影头设置略高的学习率（如 1e-4），主干用 1e-5，分类头用 1e-3——不对称 lr 是稳定训练的关键信号 - 验证阶段只启用监督分支，关闭所有对比增强与投影头，否则评估指标不可比
容易被忽略的兼容性陷阱
TensorFlow 2.12+ 默认启用 tf.function 图模式，但自定义 InfoNCE 中的动态 shape（如 batch 内正例索引生成）极易触发 retracing，导致显存暴涨或训练卡死。
- 所有 mask 构造必须用
tf.one_hot+tf.cast，避免np.where或 Python list comprehension - 不要在
@tf.function内调用len(dataset)或dataset.cardinality()，改用tf.data.experimental.cardinality并预存为常量 - 当使用
tf.distribute.MirroredStrategy多卡训练时，InfoNCE 的负样本需跨设备收集（即 all-gather），TensorFlow 原生不支持，必须手动集成tf.distribute.get_replica_context().all_gather，否则等效 batch size 不变 - 保存模型时，只保存主干 + 分类头（
model.encoder和model.classifier），投影头（model.projection_head）属于训练专用组件，不应进入推理 pipeline
半监督对比学习真正难的不是公式推导，而是让 labeled/unlabeled 数据流在 tf.data 图中不脱节、让 InfoNCE 的梯度在多设备间不发散、让温度参数和学习率组合不互相干扰——这些细节没有报错提示，但会让 loss 曲线看起来“一切正常”，实则学不到可迁移特征。
