企业官网建设流程全解析

训练日志里突然出现Not using XLA:CPU for cluster，先别急着以为模型要崩。我自己在跑 TF2.x 的模型训练时第一次见到这一行，第一反应是 XLA 加速没生效，CPU 部分全都白等了。实际排查下来发现：这一行只是图优化阶段的一个提示，它说明 TensorFlow 确实尝试过把某些计算聚成 cluster，也尝试过扔给 XLA 编译，但最终因为某些原因放弃了这个 cluster。这篇文章会从这一行日志的来源讲起，把它触发的原因、开启 XLA CPU 自动聚类的配置方法、以及我踩过的一些坑都整理出来，给同样正在折腾训练性能的人一个可复现的排查路径。

1. 先准确理解这行提示：XLA 聚类被跳过了

1.1 从算子到聚类：XLA 为什么以 cluster 为编译单位

TensorFlow 的计算图由很多 op（算子）组成，比如 matmul、add、relu、bias_add。XLA 并不是一个算子一个算子去优化的，它会把计算图中相邻、且符合编译条件的多个算子打包成一个 cluster，再对整个 cluster 做整体编译。这种打包行为在官方文档里叫 auto-clustering，也就是自动聚类。

打个比方：你从网上下单了十件小商品，快递公司不会每件单独派一辆车送，而会把同一片区的小包裹塞进同一个袋子，再统一运输。XLA 集群优化就是这个“统一运输”的过程。算子之间的中间结果不用落回内存，被融合到一张大的加速计算核心里，内存访问次数和调度开销都会降下来。

所以日志里的cluster，指的就是某一组被 TensorFlow 尝试打包的算子，不是分布式集群，也不是多机多卡集群。XLA:CPU则表示这次编译目标是 CPU 平台。整句话连起来的意思就是：TensorFlow 尝试把一个 CPU 上的算子聚类交给 XLA 编译，但没有成功，于是把这个聚类退回给默认的 TensorFlow 执行器执行。

1.2 日志级别的真相：不是 error 也不是 warning

我第一次看到这个提示时，一度以为训练出 BUG 了，拼命去翻异常栈。后来才发现，它大概率只是 info 级别的日志，不是 error，甚至很多情况下连 warning 都算不上。

判断标准很简单：如果训练还在正常跑，loss 还在正常下降，模型的权重还在更新，那这行日志就只是“可选优化”相关的提示。XLA 编译失败不会破坏原有计算逻辑，TensorFlow 的执行器会按照普通的图执行方式把这个聚类里的算子逐个跑完，结果的数值精度基本一致，最多因为融合失败损失一部分性能。

不过要注意，它有时会出现在比较靠前的位置，看起来很像报错。比如网络结构里有tf.data管道、字符串处理、动态 shape 的操作，XLA 处理不了，日志就会打出这个提示。这时候不用紧张，重点看有没有真正的Traceback或Error关键字。

1.3 出现这一行不等于 XLA 整体失效

很多人有一个误区：只要日志里出现一句Not using XLA:CPU for cluster，就认为 XLA 完全没生效。我实测下来的情况是，一个训练图里可能同时存在几十个 cluster，其中一部分能编译成功，一部分会被放弃。

我经常在日志里看到的组合模式是：

• 局部出现Not using XLA:CPU for cluster ...
• 其他 cluster 继续被 XLA 编译
• 也有XLA service ... compiled and linked to executable之类的成功日志

这就好比十个快递包裹里，八个成功装车运走，两个因为尺寸太大被留在仓库改走别的通道。你只能说这单没有完全走 XLA，但不能说 XLA 一点都没用上。

2. 为什么会被跳过：从触发场景反推原因

2.1 自动聚类开启后才容易出现这个提示

如果完全没有开启 XLA，TensorFlow 根本不会尝试把算子聚合成 cluster，正常训练时也就不会出现这行日志。最常见的出现场景，是你做了下面某个操作：

• 在代码里调用了tf.config.optimizer.set_jit("autoclustering")
• 设置了环境变量TF_XLA_FLAGS=--tf_xla_auto_jit=2
• 使用了类似experimental_compile=True强制某些函数走 XLA 编译

也就是说，这个日志是“尝试过的证据”。它出现的前提是你主动开了自动聚类。如果没开就出现，那大概率是你依赖的某个高级库，或某个模型封装层在背后帮你开了。

2.2 动态 shape 与控制流是最常见的拦路虎

XLA 编译要求大部分 tensor 的 shape 在编译时是稳定、可推断的，因为它要做指令融合和内存布局分配。如果 shape 是运行时才能确定的，比如数据集的批次大小会变化、某个tf.while_loop的循环次数在运行时才决定、或者输入里有shape=(None, None, 3)这种带不确定维度的占位符，XLA 就可能无法对包含这些操作的 cluster 进行编译。

我遇到过最典型的一个案例：模型本身是卷积网络，主干很干净，输入 shape 也是固定的。但我在前处理里加了一个tf.gather，索引张量是通过动态计算得到的。启用自动聚类后，日志里就开始频繁出现Not using XLA:CPU for cluster。后来把tf.gather移动到了模型外部的数据预处理管道里，提示立刻减少，训练耗时也降了一些。

所以当你看到这个提示时，第一反应不是去查 XLA 配置，而是去查计算图里有没有下面这些东西：

• 带None维度的输入
• 动态tf.TensorArray
• 复杂的tf.while_loop或tf.cond
• 循环次数依赖 tensor 数值
• 运算结果被 shape 函数消费的情况

2.3 不支持的算子和自定义算子也会被跳过

TensorFlow 的算子数量很庞大，XLA 虽然支持很多，但并没有覆盖所有算子。尤其是一些新增算子、第三方自定义算子、或者算子梯度里调用了某些底层库函数时，XLA 的 HLO 构建器不认识它们，就会放弃整个 cluster。

这种情况在推荐系统和 NLP 模型里比较常见，因为这两类模型经常会用到 embedding 聚合、字符串哈希、稀疏特征处理等特殊算子。tf.string系列、tf.sparse系列的部分操作，我就遇到过 XLA 编译不了的情况。并不是说这些操作有多复杂，而是 XLA 更擅长数值密集计算，对 I/O 密集、字符串密集的逻辑覆盖没那么全。

如果你的模型里有自定义 op，例如通过tf.load_op_library加载的 C++ 算子，也需要额外注册 XLA 支持接口。否则 XLA 不知道这个 op 的语义，自然无法编译包含它的 cluster。这属于比较进阶的问题，但排查思路很直接：把自定义 op 排除在 XLA 编译区域外，或者提供对应的 XLA lowering 实现。

2.4 CPU cluster 的跳过和设备放置也有关

名字里的XLA:CPU不代表只有 CPU 训练才会出现。在 GPU 训练时，因为图里有些算子被放置在 CPU 上，比如数据预处理、host memory 上的张量操作，就会生成 CPU 聚类。这些 cluster 如果编译失败，同样会打出这个提示。

多设备场景里还有一类容易被忽略的问题：设备放置不稳定。同一个计算图，如果某些 op 因为显存不足、运行时动态 placement、或嵌套tf.device被安放到了不同设备，聚类边界会变化。上次能编译成功的 cluster，这次可能被打散。比如tf.distribute.MirroredStrategy下，CPU 端的一些同步逻辑就可能因为跨设备数据依赖而无法聚类成功。

这不算配置错误，但会影响优化的一致性。如果你的目标是想让 CPU 聚类也尽量编译成功，可以先手动把不需要参与分布式同步的数据预处理放在明确的tf.device("/CPU:0")块里，减少设备放置抖动。

3. 实操配置：让 CPU 聚类真正跑起来

3.1 开启前先确认 TensorFlow 版本和当前状态

不同 TensorFlow 版本对 XLA 自动聚类的实现细节有差别，但整体接口是稳定的。我习惯先确认版本和当前优化选项，再决定要不要开：

import tensorflow as tf print("TensorFlow version:", tf.__version__) # 部分版本的 tf.config.optimizer 支持查询当前 jit 配置 try: print("Current JIT setting:", tf.config.optimizer.get_jit()) except AttributeError: print("当前版本不支持直接查询 jit 配置，跳过。")

如果你用的版本比较新，tf.config.optimizer.get_jit()可能会返回None、False或字符串，通常表示当前是否启用了 JIT。这一步的意义是避免重复配置，也方便确定日志是不是真的由自动聚类触发的。

3.2 使用 Python API 开启自动聚类

TensorFlow 2.x 里最简单的方式是在程序入口处设置：

import tensorflow as tf tf.config.optimizer.set_jit("autoclustering")

这个调用要放在模型构建和model.fit之前。自动聚类会在图优化阶段介入，把兼容的算子聚类送去 XLA 编译。设置完成之后，模型定义和训练流程都不用改：

model = build_model() model.compile(optimizer="adam", loss="sparse_categorical_crossentropy") model.fit(train_ds, epochs=5)

set_jit(True)也可以开启 XLA，但它和"autoclustering"不完全一样。True更倾向于对单个算子做 JIT 编译，"autoclustering"则会尝试把多个相邻算子打包成 cluster，然后再统一编译。如果你看到的是cluster相关日志，那自然要用"autoclustering"模式效果更匹配。

3.3 使用环境变量开启并追踪日志

有些场景不方便改代码，比如用别人的训练脚本快速跑实验，或者要对比多组配置。这时候可以在 shell 里设置环境变量：

TF_XLA_FLAGS="--tf_xla_auto_jit=2" TF_CPP_MIN_LOG_LEVEL=0 python train.py

--tf_xla_auto_jit=2对应自动聚类，=1对应更基础的 JIT 模式。设置TF_CPP_MIN_LOG_LEVEL=0是让底层 C++ 日志不要被过滤掉，否则你经常只会看到外层 Python 日志，看不到 XLA 编译相关的详情。

注意：环境变量对进程内全部 TensorFlow 计算生效。如果你只想让模型主干走 XLA，不想让数据预处理也参与聚类，还是用 Python API 精细控制在构建图之前更稳妥。

3.4 验证是否真正进入 XLA 编译路径

开了自动聚类后，怎么确认它真的生效？最简单的方法是用一个很小的矩阵运算模型做冒烟测试：

import tensorflow as tf import time tf.config.optimizer.set_jit("autoclustering") @tf.function def tiny_model(x, w, b): return tf.nn.relu(tf.matmul(x, w) + b) x = tf.random.normal([128, 64]) w = tf.random.normal([64, 64]) b = tf.random.normal([64]) # 先跑一次触发编译 print(tiny_model(x, w, b)) # 再跑一次计时，第二次通常会包含 XLA 编译后的执行 start = time.time() for _ in range(100): tiny_model(x, w, b) print("elapsed:", time.time() - start)

跑的时候把日志级别调高一点：

TF_CPP_MIN_VLOG_LEVEL=2 python smoke_test.py

日志量会明显变大。如果你能看到类似Compiling cluster、XLA service的字样，说明自动聚类已经介入。如果只有Not using XLA:CPU for cluster，而没有任何成功编译记录，那就需要按下一节的方式继续排查。

4. 常见问题与排查技巧实录

4.1 常见问题排查表

我把实际遇到的情况整理成一个表格，方便你对着自己的日志排查：

4.2 定位到底是哪一段 cluster 被跳过

想要定位具体是哪一组算子被跳过，最直接的办法是让日志更啰嗦。除了TF_CPP_MIN_VLOG_LEVEL=2，还可以适当关注日志里的 cluster 编号和上下文。如果日志里频繁提到某个 tensor 的 shape 信息，通常就是 shape 推断失败导致的问题。

我自己的习惯是给模型写一个单独的“最小复现训练脚本”，只保留最核心的几层网络和一批固定 shape 的假数据。然后逐步把数据预处理、数据增强、自定义损失函数加回去，每次加一部分就运行一次，观察Not using XLA:CPU for cluster出现的频率变化。这样能很快圈出问题很可能出在哪个模块。

如果问题集中在自定义损失或自定义层，可以试试在这些函数的输入都加上shape=[固定维度]的tf.reshape或限制，帮助 shape 推断收敛。有时候只是某一个维度为None，XLA 就宁可放弃整个 cluster。

4.3 开启后训练变慢的排查套路

XLA 不是无脑加速器。对小模型、少算子、单次训练步很快的场景，自动聚类的编译开销可能会远超融合收益。第一次调用时会触发编译，可能出现明显卡顿，那是正常的。如果后面依然慢，就需要怀疑是不是有动态 shape 导致反复重新编译。

动态 shape 最影响性能的地方在于：每次新的 shape 进来，XLA 都可能要重新编译一份专用二进制。比如模型输入明明是[None, 224, 224, 3]，如果数据管道里偶尔出现一批[223, 224, 3]，xla 编译缓存就会不断失效。所以训练时输入 shape 变化越小越好。

排查方式分两步：

1. 先关掉自动聚类跑一遍，记录 baseline 耗时。
2. 再开启自动聚类跑一遍，对比相同 epoch 数的时间。

如果开启后前几步变慢明显，但整体步耗时下降，说明值得用。如果整体更慢，就把自动聚类关闭，改成手动对核心算子使用tf.function配合 XLA 局部编译。

4.4 什么时候可以直接忽略这个提示

有一种情况是可以直接忽略的：训练能稳定跑完，性能也没有异常波动，同时这个提示只出现几条，不影响整个过程。XLA 本来就不是十全十美，有些 cluster 不合适被编译，不代表整个训练链路出问题了。

但如果你是那种对日志有洁癖的人，不看到这个提示就不舒服，可以适当调高日志过滤级别。这个操作纯粹是眼不见心不烦，不会改变功能。真正的优化方向还是要回到算子兼容性和 shape 稳定性上去。

5. 我的实测体验与后续建议

5.1 我的个人实测结论

就我跑过的模型来说，XLA CPU 自动聚类并不是越开越好的。它在卷积网络、全连接网络、Transformer 类模型这种以密集矩阵运算为主的场景里收益最明显，融合后训练步耗时大概能下降 20% 到 30%。但如果是推荐系统里的大规模 embedding 查找，或带大量字符串预处理、稀疏操作的模型，提示会非常频繁，而且整体提升往往很有限。

我自己后来定下来的策略是：每一个新模型都用三组配置对比同一段训练时间。

第一组是纯默认设置，一组是set_jit("autoclustering")，还有一组是手动在关键计算块上包tf.function(experimental_compile=True)。三组各跑几十步，看步耗时和收敛曲线。只有第二组和第三组明显更短时，才在生产脚本里保留 XLA。否则宁可放弃自动聚类，换更稳定的普通执行路径。

5.2 后续可以怎么继续优化

如果你确认需要深度调优 XLA，下一步不要继续盯着日志了，直接用 profiling 工具看算子热点。开启自动聚类后，如果你的算子名称从MatMul、Add变成了XlaLaunch、FusedConv2D之类的聚合算子，说明聚类已经生效。这时再配合 TensorBoard 里的 trace viewer，能清楚看到哪一段计算被融合了，哪一段还留在原始算子执行。

再往后，还可以研究编译缓存和 AOT 编译，把常用函数的 XLA 编译结果提前固化，减少训练过程中的重复编译。不过那是另一个话题了。

回到最初那个提示：它不是炸弹，也不是 bug。它只是 TensorFlow 在优化计算图时，对一个不合适编译的 cluster 说的那句“这次不带你玩了”。搞清楚它为什么出现，你就已经比绝大多数只会搜索报错的人更懂 XLA 了。