MirroredStrategy的梯度同步并非真正“自动完成”，因其依赖严格的作用域约束：模型构建、编译、数据集分发（需experimental_distribute_dataset）、训练执行（fit或自定义循环）均须在strategy.scope()内，否则梯度无法被策略接管而致同步失效。

为什么 MirroredStrategy 的梯度同步不是“自动完成”的？

TensorFlow 的 MirroredStrategy 确实会在每个 GPU 上复制模型，并在反向传播后自动调用 all-reduce 同步梯度——但前提是：你得让整个训练逻辑真正运行在策略作用域内。常见错误是只把模型构建放进 strategy.scope()，而把 model.compile() 或 model.fit() 放在外面，结果梯度压根没被策略接管，各卡各自为政。

• 必须把模型创建、编译、数据集封装全部放在 strategy.scope() 内
• tf.data.Dataset 需调用 strategy.experimental_distribute_dataset() 才能触发分片分发（否则每张卡拿到全量数据）
• 自定义训练循环中，strategy.run() 包裹的函数内部不能直接访问单个 GPU 的梯度；所有聚合操作（如 loss 求均值）需用 strategy.reduce()

model.fit() 下 MirroredStrategy 的最小可靠写法

很多人抄示例时漏掉 experimental_distribute_dataset 或误用 batch_size，导致 OOM 或实际单卡训练。关键点在于：全局 batch size 是各卡 batch size 之和，且 dataset 必须显式分发。

import tensorflow as tf
strategy = tf.distribute.MirroredStrategy()
print('Number of devices: {}'.format(strategy.num_replicas_in_sync))
全局 batch size = per_replica_batch_size × GPU 数
per_replica_batch_size = 32
global_batch_size = per_replica_batch_size * strategy.num_replicas_in_sync
with strategy.scope():
model = tf.keras.Sequential([tf.keras.layers.Dense(10)])
model.compile(optimizer='sgd', loss='mse')
注意：dataset 必须先 batch，再 distribute
dataset = tf.data.Dataset.from_tensor_slices((x_train, y_train)).batch(global_batch_size)
dist_dataset = strategy.experimental_distribute_dataset(dataset)
fit 时传入 dist_dataset，而非原始 dataset
model.fit(dist_dataset, epochs=10, steps_per_epoch=len(x_train)//global_batch_size)

自定义训练循环里梯度同步容易错在哪？

用 @tf.function + strategy.run() 时，最常踩的坑是误以为 strategy.run(train_step) 返回的是标量 loss，其实它返回的是 PerReplica 对象；还有人直接对 gradients 做 np.mean()，这会破坏图执行并报 Cannot convert a symbolic Tensor 错误。

Python 3.14.3

微软官方的 Python 扩展，是 VS Code 安装量最高的扩展（209M+）。集成 IntelliSense（通过 Pylance）、调试（通过 Python Debugger）、代码检查、格式化、重构和单元测试等功能。支持 Jupyter Notebook、虚拟环境管理和多 Python 版本切换。

• loss 和 metrics 需用 strategy.reduce(tf.distribute.ReduceOp.SUM, per_replica_loss, axis=None) 聚合（注意 SUM 而非 MEAN，因为各卡算的是局部 batch loss）
• optimizer.apply_gradients() 必须在 strategy.run() 外部调用，且传入 strategy.reduce() 后的梯度（或使用 strategy.run() 返回的 PerReplica gradients 直接传给 optimizer.apply_gradients()）
• 不要在 @tf.function 内部 print 或调试 tensor 值——那是图模式，得用 tf.print

同步失败时典型报错和定位方法

如果看到 InvalidArgumentError: All tensors in a batch must have the same shape 或训练 loss 不下降甚至发散，大概率是数据没对齐或梯度没同步。优先检查三件事：

• 输入数据是否在分发前已确保各卡 batch size 一致？用 dataset.cardinality().numpy() 看是否为有限值，避免最后一轮 batch 尺寸不匹配
• 是否在 strategy.scope() 外修改了模型权重？比如手动调 model.set_weights()，会导致副本间权重不同步
• 混合使用 tf.Variable 和 Keras 层？自定义变量必须也创建在 strategy.scope() 内，否则不会被镜像

多卡训练真正的复杂点不在 API 调用，而在数据流和变量生命周期的隐式耦合——一旦某处跳出策略作用域，同步就断了，而且往往不报错，只静默失效。