TPU v7x on GKE 运维方案交付验收 · 监控告警 · 故障处置
技术方案 · TPU v7x (Ironwood) on GKE · 运维

GKE + TPU v7x (Ironwood) 运维方案:交付验收、起飞前检查、监控与日志、故障定位

本文只覆盖运维:压测与交付验收、返修准入、起飞前检查、监控与告警、日志、上报与报修、故障定位与处置。

验证集群
GKE 集群(下称“验证集群”),us-central1-c,GKE · us-central1-c
TPU
2 × tpu7x-standard-4t · 拓扑 2x2x2
软件
CHS 0.3.2 · TPUMS 027cd62 · libtpu 0.0.34 / 0.0.48 / 0.0.50
验证日期
2026-11-03
验证环境只有一个 2x2x2 slice:DCN、多 slice 与 4x4x4 及以上拓扑未实测,文中实测与估算耗时均为 2x2x2 数值。
版本 v2 · 2026-11-03证据标记:实测文档未验证估算说明

如何使用本文 · 按任务进入

0 阅读指引与结论摘要#

0.1 范围#

本文只覆盖运维:压测与交付验收、返修准入、起飞前检查、监控与告警、日志、上报与报修、故障定位与处置。调度、排队、拓扑感知调度与容量规划不在范围内。第 1 章归纳客户需求,第 2 章按工具给出接口、实测值与注意事项,第 3 章把工具串成端到端流程,第 4 章逐条答复客户问题。实机过程、与上一版相比的更正、来源索引和未验证项见附录。

0.2 验证环境#

项值
集群验证用 GKE 集群(下称“验证集群”),us-central1-c,GKE 1.36.4-gke.2326000
TPU 节点池2 × tpu7x-standard-4t,拓扑 2x2x2(一个多主机 slice,tpu7x-16),每节点 4 芯片
节点Container-Optimized OS 129(19506.505.8),内核 6.12.110+,containerd 2.2.7,224 vCPU;guest 内只见网卡 eth0(gVNIC,MTU 8896,ethtool 速率 200 Gbps)实测,机型文档列 2 块物理网卡、单 VM 最高 400 Gbps 文档
GKE 组件tpu-device-plugin 1.36.14-gke.1(含 sidecar-log-collector)
软件基础镜像 jax-ai-image/tpu(jax 0.9.0、libtpu 0.0.34);TPUMS commit 027cd62(jax 0.12.0、libtpu 0.0.50);CHS 0.3.2(测试负载镜像内 jax 0.11.1、libtpu 0.0.48)
日期2026-11-03

验证环境只有一个 2x2x2 slice:DCN、多 slice 与 4x4x4 及以上拓扑未实测,文中实测与估算耗时均为 2x2x2 数值。上报、cordon、fault-behavior 标签等会改变节点状态的操作未在验证环境执行,只核对了文档、--help 与 --dry-run=server。

0.3 证据标记#

  • 实测:在上述集群上测得,过程见附录 A。
  • 文档:公开文档、开源代码,或客户问答表与 GitHub 中 Google 的答复,附链接。
  • 未验证:未能确认,表述保持中性,汇总见附录 D。
  • 估算:由实测单项累加或外推,未整体运行;耗时不含镜像冷拉取(CHS 测试负载镜像冷拉取实测 95 s,在 CPU 节点上测得)。
  • 文中阈值凡标“起始值”的,均需按上线后 2 周的实测基线调整。

0.4 关键结论#

  1. 交付验收可在客户侧完成:CHS 0.3.2 standard 作为 DCGM EUD 的对应物做节点池级验收,输出带门限判定的 Bill of Health,TPUMS 做逐项深挖;2x2x2 上 lite 9 min 31 s(5 项)、standard 17 min 58 s(8 项)全部通过 实测;CHS 不打标、不 cordon,隔离由客户自动化执行(2.2、2.3、3.1)。
  2. 数值必须带单位口径:TPU7x 每芯片 2 个 TensorCore,JAX 每主机 8 个 device。HBM 规格 7380 GB/s 为 per chip,单 device 实测 3233 GB/s,为 per-device 峰值的 87.6%;CHS psum 门限与 TPUMS all_reduce 结果负载不同,不能互相套用(2.2.2、2.3.4)。
  3. 客户可控的 SDC 手段是 XSC 与公开 playbook 中的 7 个 xla_tpu_ici_sdc_test_* flag,只用于诊断运行(实测 XSC 使 step 变为 2.08 倍);libtpu 遇到未知 flag 会启动即退出,上一版给出的 10 个 flag 中 9 个不存在(2.4、附录 B)。
  4. 起飞前检查 precheck_v2 逐项映射常见 GPU 预检 9 项(2 项无等价项,互联错误计数改用带外指标);initContainer 9–10 s、Pod 创建到主容器完成 22–24 s 实测,在 10 min 级的预检时间预算内(2.9、3.3)。
  5. 带外健康指标 infra_health、chip_state 实测入库延迟 256–382 s,告警窗口不少于 10 min 且用 last_over_time;instance/tpu/accelerator/* 在验证集群 10-29 后中断,TPU 负载期间也无数据,需对数据缺失告警。DCGM 16 项在 TPU 上没有一一对应的指标(2.6)。
  6. libtpu 日志经 GKE sidecar-log-collector 进入 Cloud Logging,severity 恒为 INFO,需按文本中的 glog 级别过滤;TPU 没有 XID 式公开错误码表(2.7)。
  7. 致命和不可纠正错误由平台自动处理。平台未检出的问题:GKE 管理的 TPU 节点先隔离再开支持工单,不对其 VM 调用 report-host-as-faulty;GKE fault-behavior 标签流程的文档只列 GPU 机型,TPU 需 Google 确认后再接入自动化(2.10)。
  8. 告警以作业进度为主信号(停滞、启动超时、步时 p50 高于基线 1.10 倍触发;1.05 倍恢复门限需另加条件实现,未验证),进度缺失告警需按作业状态门控。同步训练中各 worker 步时相同,慢节点靠带内指标定位:主机侧慢节点 duty_cycle 最低,计算侧慢节点 TensorCore 利用率最高,15 s 指标 40–41 s 可辨识 实测;不凭统计结论单独 cordon;回池采用 quick 与 soak 两级检查和复发观察(3.4、3.5)。

1 客户需求归纳#

来源为客户问答表各 tab 与评论线程、客户私有 GitHub 仓库中的 issue 与讨论记录(需访问权限),以及客户提供的 GPU 预检说明,共 46 条原子需求(RQ-01 至 RQ-46),归并为 15 条(R-01 至 R-15)。表中每条只链接首个来源,全部来源按 RQ 编号列于附录 C.1(客户问答表)与 C.2、C.3(GitHub issue、客户文档、公开仓库)。Google 侧向客户共享的运维资料(基线文件、告警样例、15 s 采集器配置)不作为需求来源。调度、排队与容量类问题已剔除。

R-ID需求原子需求与来源实现工具章节实机过程(附录)状态
R-01TPU 版 DCGM EUD:客户侧可运行、逐芯片或逐节点给出 pass/fail 的深度诊断与交付验收套件,并给出时长RQ-01 客户问答表;RQ-02;RQ-03;RQ-09;RQ-10CHS standard/lite;TPUMS2.3、2.2、3.1A.3.1、A.2.1实测(CHS lite、standard,TPUMS)
R-02ICI/DCN 集合通信性能基线、验收方法与参考指标;网络压测与连通性检查RQ-05 客户问答表;RQ-06;RQ-02TPUMS 集合通信;CHS collectives/network-stress;precheck_v22.2、2.3、2.9、3.1A.2.1、A.3.1、A.12ICI 实测(2x2x2);DCN 未测
R-03同步脉冲(di/dt 阶跃)负载压测RQ-04 TPUMS#145TPUMS 无此模式,实验脚本2.2(2.2.4)A.2.2、A.2.3、A.2.4实验脚本实测;无官方工具
R-04SDC 检测机制、客户可用的 SDC 工具与推荐时长、逐位一致性边界RQ-07 客户问答表;RQ-08libtpu SDC 检测;CHS stress 比对2.4、2.3、3.5.5A.4.1–A.4.4、A.3.1实测(开销、日志落点、确定性)
R-05对标客户现有 GPU 预检脚本的 TPU 起飞前检查:sidecar 或 initContainer 形态、退出码、时长预算、通信就绪与版本一致性RQ-11 客户问答表;RQ-12;RQ-13;RQ-14precheck_v2;节点与芯片健康2.9、3.3A.9.1、A.1.3、A.1.4实测(initContainer 9–10 s)
R-06GKE 上 K8s/TPU 监控组件与指标名,以及接入客户 Prometheus 或自研采集的方式RQ-15 客户问答表;RQ-17;RQ-22;RQ-24Cloud Monitoring 系统指标;device plugin :2112;collector-15s2.1、2.5、2.6A.5.1、A.6.1、A.1.2实测(带外、device plugin、15 s 采集器)
R-07客户 16 项 DCGM 指标的 TPU 对应关系与缺口RQ-18 客户问答表(清单见客户问答表指标补充 tab);RQ-19;RQ-20;RQ-21Cloud Monitoring2.6A.6.1实测(可见指标与标签)
R-08租户可自采的 ICI/DCN 网络指标、仅 GCP 可见的部分、“RDMA 监控”的 TPU 等价方案RQ-16 客户问答表;RQ-29Cloud Monitoring ICI/NIC 指标2.6、3.4A.6.1、A.6.2标签实测;负载期间 accelerator/* 仍无数据
R-09硬件告警规则(掉卡、链路、ECC、健康态),按 fatal/非 fatal 分级接入现有告警与 Pod 替换流程;带外能力边界RQ-23 客户问答表;RQ-27;RQ-28;RQ-33Cloud Monitoring;device plugin;日志2.6、3.4A.6.1、A.11.2查询与延迟实测
R-10可被 operator 消费的故障信号:Slice/partition 状态 watch、定位到 node、node 与 partition 映射、已屏蔽列表RQ-25 客户仓库 infra#27;RQ-26;RQ-39节点与芯片健康(partition 标签与状态)2.1、3.5.1A.1.1、A.1.3文档(验证环境无 Dynamic Slicing)
R-11硬件错误上报渠道与日志位置、错误分级(致命或可忽略)、日志盘容量控制RQ-30 客户问答表;RQ-31;RQ-32;RQ-38日志;Cloud Monitoring 错误计数2.7、2.10、3.4A.7.1、A.7.2、A.7.3实测(日志落点、TPU_LOG_DIR、sidecar)
R-12常见故障类型与典型诊断流程(Hang、降速、ICI 链路、DCN 拥塞、Host 异常、慢节点)RQ-34 客户问答表;RQ-35;RQ-36;RQ-37故障处置 runbook;在线遥测;离线复测3.5A.11.1、A.8.1、A.1.5实测(慢节点与 hang 注入、检出时延);多 slice 未测
R-13故障节点上报、隔离与报修(R&R)路径RQ-40 客户问答表;RQ-43;RQ-41节点隔离加支持工单;fault-behavior 标签(TPU 待确认);All Capacity 上报2.10、3.5A.10.1文档、--help 与 --dry-run,未实操
R-14局部故障降级运行与恢复时间;hang 或慢节点的 checkpoint 恢复与自动踢除RQ-42 客户问答表;RQ-45;RQ-46故障处置 runbook3.5—文档
R-15修复后回归准入(修复节点需经长时间深度压测才回池)与修复时长信息RQ-41 客户仓库 infra#29;RQ-44CHS standard 循环;TPUMS soak;libtpu SDC3.2、3.5.7A.3.1、A.2.1估算(单项均已实测,整轮未连续运行)

“状态”指本文答复所依据证据的完备程度。

2 能力工具箱#

本章每节对应一个工具或信号源:先列它回答的需求,再给接口、实测值与注意事项。公共初始化只在 2.0 写一次。

2.0 公共初始化#

第 2、3 章的命令共用本节的凭据、Pod 模板与安全规则。

2.0.1 凭据与命名空间#

bash
export PROJECT=<PROJECT> LOCATION=<ZONE> CLUSTER=<CLUSTER> NS=tpu-verify
gcloud container clusters get-credentials "$CLUSTER" --location "$LOCATION" --project "$PROJECT"
kubectl create namespace "$NS"

2.0.2 Pod 模板#

TPU Pod 必须同时带 cloud.google.com/gke-tpu-accelerator 与 cloud.google.com/gke-tpu-topology 两个 nodeSelector(GKE 准入约束 tpu-accelerator-topology-constraints),只写 kubernetes.io/hostname 不够 实测。单主机模式(多主机 slice 的单个节点独立运行,用于逐节点检测):

yaml
apiVersion: v1
kind: Pod
metadata: {name: tpu-sh-<NODE>, namespace: tpu-verify}
spec:
  restartPolicy: Never
  terminationGracePeriodSeconds: 5
  nodeSelector:
    cloud.google.com/gke-tpu-accelerator: tpu7x
    cloud.google.com/gke-tpu-topology: 2x2x2      # 与节点池拓扑一致
    kubernetes.io/hostname: <NODE>
  tolerations: [{key: google.com/tpu, operator: Exists, effect: NoSchedule}]
  containers:
  - name: main
    image: us-docker.pkg.dev/cloud-tpu-images/jax-ai-image/tpu@sha256:<DIGEST>
    command: ["bash", "-c", "sleep infinity"]
    resources: {requests: {google.com/tpu: 4}, limits: {google.com/tpu: 4}}
bash
kubectl -n "$NS" exec tpu-sh-<NODE> -- env TPU_HOST_BOUNDS=1,1,1 python3 <test.py>

整 slice 模式:headless Service(clusterIP: None,selector: {job-name: tpu-mh})加 Indexed Job,无需 JobSet;作业带 initContainer 预检时 Service 须设 publishNotReadyAddresses: true(2.9)。spec.template.spec 同上,去掉 hostname 选择器并加 subdomain:

yaml
apiVersion: batch/v1
kind: Job
metadata: {name: tpu-mh, namespace: tpu-verify}
spec:
  completions: 2              # = slice 节点数,parallelism 相同
  parallelism: 2
  completionMode: Indexed
  backoffLimit: 0
  template:
    spec:
      subdomain: tpu-mh-svc   # = Service 名

各 Pod 须并发 kubectl exec 同时启动测试进程,进程内调用 jax.distributed.initialize() 实测。完整清单见附录 A.0。

2.0.3 GKE 注入的环境与挂载#

GKE 注入 TPU_WORKER_ID、TPU_LOG_DIR、TPU_TOPOLOGY、TPU_HOST_BOUNDS、TPU_RUNTIME_METRICS_PORTS 等变量并挂载 /dev/vfio、/tmp/tpu_logs,2x2x2 上的取值见附录 A.0 实测。/tmp/tpu_logs 是宿主机 tmpfs 上的目录,Pod 删除后仍在,同节点下次分配 TPU 时被清空(2.7)实测。基础镜像 jax-ai-image/tpu:latest 验证时含 jax 0.9.0、libtpu 0.0.34,不含 tpu-info 实测;生产按 digest 固定。

2.0.4 清理与安全#

bash
kubectl -n "$NS" delete job,svc,pod --all --wait=true && kubectl delete namespace "$NS"
  • 只在空闲节点或 slice 上运行,先确认目标节点上没有请求 google.com/tpu 的 Running 或 Pending Pod(脚本见附录 A.0)实测。
  • 不覆盖 TPU_HOST_BOUNDS 时,单节点初始化 JAX 约 3 s 后失败:Expected 2 worker addresses, got 1. 实测
  • 只覆盖 TPU_HOST_BOUNDS=1,1,1 时本机 4 颗芯片间 ICI 可用;CHS 的 --deepsea_hal_test_allow_multichip_skip_slicebuilder 在 libtpu 0.0.34 上被拒绝,两个 skip_slicebuilder 标志在 0.0.50 上关闭 ICI 实测。
  • 实机过程见附录 A.0、A.1.3。

2.1 节点与芯片健康#

回答 R-10,并为 R-05、R-09、R-13 提供节点级判据。

命令 / 对象测什么实测值判定标准
node allocatable["google.com/tpu"]可用芯片数4 实测等于 4,下降即掉卡
Node conditions26 种,含 NPD 的 CperHardwareErrorFatal,无 TPU 专用项除 SysctlChanged=True 外均为默认值 实测Ready=True、CperHardwareErrorFatal=False
Pod 内 ls /dev/vfio设备是否挂入8 个组号加 vfio 实测8 个数字节点
tpu-info、tpu-info -p芯片列表、HBM 用量、duty cycle、持有 vfio 的 PID4 行 TPU7x chip,HBM 189.49 GiB/芯片;安装 0.9 s 实测4 行芯片
device plugin :2112/metrics按容器的 tensorcore_utilization、memory_bandwidth_utilization空闲为 0 实测有作业时非 0
sysfs PCI(特权只读 Pod,约 20 s)TPU PCI function 与驱动8 个 1ae0:0076,vfio-pci 实测8 个且均为 vfio-pci
bash
kubectl get nodes -l cloud.google.com/gke-tpu-accelerator=tpu7x -o custom-columns='NAME:.metadata.name,TPU:.status.allocatable.google\.com/tpu'
kubectl get node <NODE> -o jsonpath='{range .status.conditions[*]}{.type}={.status}{"\n"}{end}'
kubectl -n "$NS" exec tpu-sh-<NODE> -- bash -c 'pip install -q tpu-info && tpu-info && tpu-info -p'

注意事项:

  • 芯片健康以带外 infra_health、chip_state 为准,见 2.6 实测。
  • TPU PCI function 无 AER sysfs 文件,link speed 读出 Unknown;改用 pcie_*_error_count(2.6)实测。
  • 空闲时 tpu-info 提示 Libtpu metrics unavailable,属正常。作业运行时 -p 列出全部 8 个 vfio 组,其中 4 个由 JAX 进程持有,其余为 None:libtpu 只打开每芯片的 function 0 实测。
  • 不申请 TPU 的特权 hostPID Pod 可与作业并存;kubectl debug node/<NODE> --profile=sysadmin 中扫描 /proc/*/fd 可找出持有 /dev/vfio/* 的 PID 及其 Pod cgroup(kubectl debug 不加 -i 时立即返回,扫描结果用 kubectl -n $NS logs <DEBUG_POD> 查看)实测,fuser -v /host/dev/vfio/* 则找不到:容器内的 /dev/vfio/N 是 inode 不同的独立设备节点 实测(附录 A.1.4)。
  • 每节点 4 颗芯片(TPU_CHIPS_PER_HOST_BOUNDS=2,2,1),即一个 2x2x1 partition 实测。
  • Dynamic Slicing 集群的节点按每层 partition 带状态标签(如 cloud.google.com/gke-tpu-partition-4x4x4-state),节点或 ICI 故障时各层 partition 变为 UNHEALTHY、活动 Slice 变为 FAILED,只有 4x4x4 层可能为 DEGRADED(Google 答复,客户问答表)文档。PartitionTree 健康聚合与传播见客户仓库中 Google 侧提供的 PartitionTree 健康说明。
  • Dynamic Slicing 集群另有 kubernetes.io/accelerator/partition/state、slice/state 指标(Beta,60 s);验证集群未启用 Dynamic Slicing,无 partition 标签,这两个指标也无数据 实测。
  • operator 可 watch 节点的 partition 状态标签,并列出已屏蔽节点;验证环境无 Dynamic Slicing,以下命令未执行 未验证:kubectl get nodes -L cloud.google.com/gke-tpu-partition-4x4x4-state -w、kubectl get nodes --field-selector spec.unschedulable=true。
  • 实机过程见附录 A.1.3、A.1.2、A.1.1。

2.2 TPUMS 微基准#

回答 R-01、R-02、R-03、R-15。TPUMS(accelerator-microbenchmarks v2.0,tpums CLI)不带 pass/fail 门限 文档。实测版本 commit 027cd62,jax 0.12.0,libtpu 0.0.50 实测;main 几乎每天变更,须钉 commit。Pod 模板见 2.0。

单位:TPU7x 每芯片 2 个 TensorCore,JAX 中每个 TensorCore 为一个 device,4 芯片主机共 8 个 device 实测;TPUMS 的 gemm、集合通信按 chip 输出,hbm、device_to_device 按 device 输出,主机传输按 host 输出。

2.2.1 接口与实测值#

配置或任务测什么实测值耗时判定标准
2x2x1/gemm.yamlbf16、fp8 GEMM16384³:bf16 2107.6、fp8 4441.6 TFLOP/s/chip,为规格的 91%、96% 实测35 s不低于机群中位数 −5%
2x2x1/hbm.yamlHBM copy,256 MiB–2 GiB3210–3242 GB/s/device 实测22 s同上
2x2x1/host_to_device.yaml、device_to_host.yamlH2D、D2Htpu_sync 后端约 226 GB/s/host;jax 后端每 device 4–8 GiB 时 H2D 46–47、D2H 61 GB/s/host,16 GiB 时降至 24.7、14.6 实测278 s、336 s同后端、同大小比较
gemm_chained(sample config)链式 GEMM,跨 device checksum三个 checksum 字段均为 True 实测15 s任一 False 即隔离
gemm_throttling(min_duration_s: 240)满载 soakslowdown 1.002,throttle 0%,性能状态全程不变 实测279 s不劣于机群基线
device_to_device,--direction uni、bi本机 56 个 device 对uni:同芯片 342–343、跨芯片 46.6;bi:689–692、93.3 GB/s/device 实测571 s、440 s跨芯片对无离群
2x2x2/ all_reduce、all_gather、all_to_all(整 slice)ICI 集合通信,bf16all_reduce 214.6–278.6、all_gather 260.9–272.0、all_to_all 155.5–161.2 GB/s/chip 实测61、27、24 s不低于同拓扑基线

判定标准均为起始值。配置路径相对 configs/tpu7x/,用 tpums benchmark run-config 运行;device_to_device 用 tpums benchmark run(bi 加 --warmup_tries 2 --num_runs 5)。hbm 行只是 device 0 的值。覆盖本机 8 个 device 用下面的命令,只设 TPU_HOST_BOUNDS=1,1,1,不加 --standalone_host_init(加了会在 device 2 卡住):实测 124 s、32 组结果,8 个 device 均为 3201.7–3241.5 GB/s/device 实测(附录 A.2.1)。

bash
TPU_HOST_BOUNDS=1,1,1 tpums benchmark run hbm --xprof_timing --op_type copy --dtype bfloat16 \
  --warmup_tries 2 --num_runs 5 --num_elements 67108864 134217728 268435456 536870912 \
  --device_id 0 1 2 3 4 5 6 7

2.2.2 口径#

  • HBM:官方规格 7380 GB/s 为 per chip(TPU7x)文档。TPUMS 以 3690 GB/s 为 per-device 峰值,单 device copy 实测 3233 GB/s/device(87.6%)实测。共享运维手册中的 HBM 基线(客户仓库中 Google 侧共享的基线文件)按 8 device 并发读写计,基线数据以该文件为准,单 device copy 值乘 2 不能代替并发实测。
  • 计时:只用 xprof_*;多主机 all_reduce 的 wall_clock_* 只有 7.6–15.8 GB/s/chip(bf16 默认配置;fp32 对齐运行 11.8–14.3),含主机侧开销,构成未单独测定 实测。
  • 性能状态:TPUMS 默认基准配置(op_flags.yaml 的 gemm 项,共 10 个 libtpu 参数,含性能状态参数)使链式 GEMM 吞吐比默认作业配置高约 17%(1867–1869 对 1595–1604 TFLOP/s/chip),其中只设性能状态参数时高约 10–14%(附录 A.2.2、A.2.4);对 all_reduce 无可测影响 实测;用 TPUMS 结果给生产作业定基线时需注意这一差异。

2.2.3 注意事项#

  • 多主机 slice 的单个节点:gemm、hbm.yaml(只测 device 0)、主机传输、gemm_throttling 可加 --standalone_host_init;gemm_chained、device_to_device 和 hbm 的 8 device 扫描只设 TPU_HOST_BOUNDS=1,1,1,加该参数时 gemm_chained 与 hbm 扫描(device 2 起)卡住,device_to_device 被拒绝 实测。
  • hbm.yaml 只测 device 0(#145 中指出);run-config 会静默忽略追加的 --device_id(实测仍只测 device 0),须用 2.2.1 的 tpums benchmark run hbm 命令;多值参数按笛卡尔积依次执行,8 个 device 逐个测试而非并发 实测。
  • op_flags.yaml 覆盖 Pod 的 LIBTPU_INIT_ARGS,改 flag 用 --xla_flags_file_path;tpums 命令行的未知参数(如 --warmup_runs)被静默忽略,libtpu 的未知 flag 则使进程退出(2.4.3)实测。参数名、温度字段等见附录 A.2.1.5。
  • 实机过程见附录 A.2.1。

2.2.4 同步脉冲(di/dt)#

TPUMS 无脉冲模式,上游 #145 截至 2026-11-03 仍为 open 文档。实验脚本 gemm_pulse_didt.py(附录 A.2.2)让 8 个 device 空闲 50/200/500/1000 ms 后同时启动链式 8192³ bf16 GEMM 并逐 device 比对 checksum,结果全部 PASS,空闲间隙未见降频 实测。只作参考,不作门限;能否筛出供电瞬态问题未经验证 未验证。

另一脚本 pulse145_v2.py 不算校验和,把每次突发的输出与 HBM 中的参考结果逐位比对:jax 0.9.0 与 0.12.0 上空闲 50/200/500/1000 ms 均 0 次不一致;脚本检查参考结果有限、8 个 device 逐位一致,参考结果非零由打印统计的变体确认(nonzero_frac=1.0);吞吐 1594–1632 TFLOP/s/chip,单次 19.4–19.7 s 实测(附录 A.2.3)。默认配置下性能状态在 50–500 ms 空闲间隙中保持不变,首次突发与中位数持平 实测(附录 A.2.4)。

2.3 CHS 集群健康扫描#

回答 R-01、R-02、R-04、R-15。CHS 0.3.2(镜像 us-docker.pkg.dev/gce-ai-infra/chs/chs:0.3.2)按节点池提交测试 Job,比对门限后输出 Bill of Health(BoH)文档,用作节点池级验收,对应 GPU 侧的 DCGM EUD。负载镜像 accelerator-microbenchmarks:1.1.1 内是旧版 TPUMS(jax 0.11.1、libtpu 0.0.48,无 tpums CLI),参数与 2.2 不通用 实测;0.3.x 只以镜像发布,用法以镜像内 README 为准 文档。

2.3.1 测试项与门限#

测试测什么门限实测(2x2x2)耗时
tpu-infoJAX device 数==888 s
tpu-gemm16384³ bf16≥950 TFLOP/s/device1042.1–1066.94 min 16 s
tpu-hbm单 device copy,4 GiB 处判定≥3040 GB/s/device3221.9–3222.73 min 10 s
tpu-host-devicepinned memory H2D、D2H≥182、≥48 GiB/s/host204.5–206.4、53.8–54.144 s
tpu-collectivespsum,fp322x2x2 ≥190、4x4x4 ≥352 GB/s(另有 2x2x1 124、2x2x4 133、2x4x4 162);表外拓扑没有 psum 门限,状态为 UNKNOWN 文档210.8–211.51 min 46 s(lite 45 s)
tpu-compute-stress每 device 1500 轮、每轮 8 次 16384² bf16 matmul,与 device 0 逐位比对≥869 TFLOP/s/device920.8–921.52 min 23 s
tpu-hbm-stress固定高性能状态,每 device 约 16 GiB(不超过 HBM 20%,向下取 2 的幂)上 bitwise_not 15000 轮,逐 device checksum 与 device 0 比对≥6108 GB/s/chip,为规格 7380 的 83%6364.13 min 10 s
tpu-network-stress每轴邻居 ppermute 1 GiB,payload 比对每轴 ≥152 GB/s(实为 GiB/s,见 2.3.3)170.8–171.31 min 40 s

门限取自镜像内 thresholds.yaml,type: min 的值在运行时乘 0.95 取整(如 psum 200→190、370→352)文档;实测列为 2026-11-03 standard 运行的两节点取值,8 项均为 RESULT_STATUS_SUCCESS,stress 测试无数据不一致 实测(附录 A.3.1);standard 的 psum 扫描更多消息大小,峰值与 lite 相同。compute-stress、hbm-stress 发现数据不一致时不输出该节点的 metric,因缺 metric 判 FAILED(compute-stress 的失败行含 SDC (Bit flips) Detected,同时被错误检测器判为硬失败);network-stress 只丢出错轴的 metric,由错误检测器匹配 SDC (Bit flips) Detected 判为硬失败;错误检测器命中(PJRT 初始化失败、ICI 链路故障、OOM 等)均记为硬失败 文档。

2.3.2 套件、用法与耗时#

套件测试工具自报实测
lite(默认)info、gemm、hbm、host-device、collectives~5 min9 min 31 s 实测
standardlite 加三项 stress~30 min17 min 58 s 实测
bash
chs configure storage gcs <bucket>          # 报告桶必需
chs run --nodepools=<TPU_POOL> --suite=standard --run-id=<run-id> -y
chs results <run-id>-<4 位后缀>              # CHS 在 --run-id 后追加 4 个随机字符

报告写入 gs://<bucket>/bills_of_health/(HTML 与 JSON),原始日志在 gs://<bucket>/workspaces/ 文档。同一节点池上的测试 Job 逐个串行 实测;目标节点不重叠的 Job(如多个节点池)可同时运行 文档。

2.3.3 注意事项#

  • 目标必须用 --nodepools 指定,整个 slice 空闲才会测试 文档。
  • CHS 不打标、不加污点、不 cordon,隔离由客户按 BoH 执行(2.10)文档。
  • tpu7x 测试 Pod 只容忍 google.com/tpu 污点,CLI 无 toleration 参数:节点带其他 NoSchedule 污点时 Job 无法调度,被取消并记为 DEADLINE;节点池中有 cordon 或 NotReady 节点时 CHS 不测试该池 文档。返修节点因此用标签门控而非污点(3.2)。
  • 在集群内 Pod 中运行 chs 时,集群名先取节点标签 container.googleapis.com/cluster_name,没有该标签时需提供带 current-context 的 ServiceAccount kubeconfig(建议用 gke_<PROJECT>_<LOCATION>_<CLUSTER>),否则报 Failed to retrieve cluster name from the scheduler 实测(附录 A.3.2)。
  • chs 进程须在整个 run 期间运行;chs cancel --all 会取消集群上所有用户的 run,共享集群禁用 文档。
  • 0.3.2 的 tpu-collectives 只跑 psum;tpu-network-stress 按 GiB/s 计算但标为 GB/s 文档。
  • 实机过程见附录 A.3.1。

2.3.4 CHS psum 与 TPUMS all_reduce 的口径#

两者都是设备侧计时(profiler trace 与 XProf),差别在负载和带宽公式:CHS 为 fp32(lite 16–64 MiB、standard 64 KiB–64 MiB,峰值都出现在 64 MiB)、默认性能状态;TPUMS 2x2x2/all_reduce.yaml 为 bf16、128–512 MiB shard、使用 TPUMS 基准配置的性能状态 文档。按 CHS 配置对齐的 TPUMS 运行(fp32,16/32/64 MiB,4x2x2,默认性能状态)得到 191.5/207.1/210.8 GB/s/chip(固定 TPUMS 性能状态时为 191.8/207.0/210.8),64 MiB 时与 CHS 一致 实测。TPUMS 默认配置的 215–279 GB/s/chip 不能套用 CHS 的 190 或 352 门限;其他来源(另一套脚本)的 1D all_reduce 基线也不混用。

2.4 libtpu SDC 检测#

回答 R-04、R-15。客户可控的手段是 LIBTPU_INIT_ARGS 中的 XSC、ici-sdc-test flag,以及带数据校验的离线负载:CHS 三项 stress(compute、network 逐位比对,hbm 比对校验和,2.3)、TPUMS gemm_chained(跨 device checksum,2.2)。

2.4.1 检测层次#

层次机制客户可控来源
硬件MXU 内置 FBIST,在制造、burn-in 和运行期间执行;VPU 硬件 replay 在空闲 VLIW 槽随机抽样冗余执行;问题芯片经 OCS 移出维修否IEEE Micro 2026 文档
HBM ECC不可纠正错误使 libtpu abort 或 OS panic否,见 2.7ecc-errors 文档
XLA SDC Checker(XSC)HLO 重跑并比对输出 checksum,或扫描 NaN/Inf是non-determinism triage 文档
ici-sdc-test程序开头注入 ICI 传输校验,定位慢链路与传输错误是ICI straggler triage 文档

2.4.2 用法(仅用于诊断运行)#

bash
# XSC:默认对非平凡 HLO 各重跑 1 次并比对输出 checksum,发现不一致即中止作业
LIBTPU_INIT_ARGS="--xla_tpu_enable_sdc_checker=true"

# XSC 定位:不中止、记录全部不一致,用于 3.5.5 按芯片与 HLO 分布判断
LIBTPU_INIT_ARGS="--xla_tpu_enable_sdc_checker=true --xla_tpu_sdc_check_halt_on_detection=false"

# ICI 慢链路诊断:公开 wiki 给出的 11 个 flag(7 个 ici_sdc_test、3 个 XSC、1 个 log recorder;
# repeat_count=0 不重跑 HLO,不做计算 SDC 比对)
LIBTPU_INIT_ARGS="--xla_tpu_enable_sdc_checker=true --xla_tpu_sdc_check_repeat_count=0 \
 --xla_tpu_sdc_check_halt_on_detection=false --xla_tpu_ici_sdc_test_run_on_program_start=true \
 --xla_tpu_ici_sdc_test_iterations=5000 --xla_tpu_ici_sdc_test_max_distance=1 \
 --xla_tpu_ici_sdc_test_pipeline_depth=13 --xla_tpu_ici_sdc_test_buffer_size_chunks=256 \
 --xla_tpu_ici_sdc_test_packet_size_chunks=256 --xla_tpu_ici_sdc_test_sflag_wait_timeout_ms=5 \
 --xla_tpu_enable_log_recorder=true"

2.4.3 开销、日志与时长#

  • XSC:wiki 给出标准模型减速 1.8–2.5 倍,只用于离线诊断或少量 step 的诊断运行 文档。本集群 8 device 链式 bf16 matmul 的 step 中位数由 27.9 ms 增至 57.8 ms,即 2.08 倍;上一版给出的 5 个 XSC flag 组合为 2.32–2.34 倍 实测(附录 A.4.3)。XSC 重跑时不插桩异步集合通信(如 all-reduce-start、all-reduce-done),无报错不等于没有 SDC 文档。
  • ici-sdc-test:run_on_program_start=true 时每个 step 开头都执行;wiki 示例中 5000 次迭代使 step 从约 3.46 s 增至约 7.38 s,建议只在诊断运行中短时开启或每 100 step 开一次 文档;按 step 开启需用 compiler_options 单独编译,ici_sdc_test flag 是否支持该方式 未验证。本集群 2x2x2、8 MiB psum(基线 0.56 ms/step):只开 run_on_program_start(默认 10 次迭代)无可测开销(中位数 0.576 对 0.56 ms,在波动范围内);上面 11 个 flag 中 iterations 取 10 时增加 1.4 ms,取 5000 时增加 228 ms 实测(附录 A.4.2)。
  • 日志:XSC 命中为 [XLA_SDC_CHECKER] chip [...] host [...] ::> OUTPUT data checksum does not match(sdc-checksum-mismatch);ICI 诊断检索 XLA_SDC_CHECKER、ICI transfer wait、Wait timeout on sflag 文档。实测 [XLA_SDC_CHECKER] 不一致行、XSC 生效标记 HLO is instrumented (HLO rerun) 和 IciSdcTest :: ICI BW: … (GiB/s)(每主机每 step 8 行,每个 TensorCore 一行)只写入 $TPU_LOG_DIR/tpu_driver.INFO,默认 TPU_STDERR_LOG_LEVEL 下 stderr 为空;11 个 flag 的健康运行中 ICI 结果只以 IciSdcTest 行出现,XLA_SDC_CHECKER 为 0 行。sidecar 只上传每个容器第一个 libtpu 进程的日志,诊断运行若不是容器内第一个 libtpu 进程,需从 Pod 内取日志 实测(附录 A.4.2、A.4.3)。
  • 未知 flag 使 libtpu 启动即退出:libtpu 0.0.34、0.0.50.1、0.0.51 均在 0.4 s 内打印 ERROR: Unknown command line flag '<name>' 并以 rc=1 退出;上一版的 10 个 ICI flag 中 9 个不存在 实测(附录 A.4.1)。只用上面列出的 flag,新 flag 先在目标 libtpu 版本上验证。
  • 按 step 抽检:jax.jit(..., compiler_options={...}) 或 jit(...).lower(...).compile(compiler_options={...}) 可为单次编译传入 flag(jax.jit、jax.stages 中 Lowered.compile)文档,后者实测可用(附录 A.4.3),据此只在部分 step 使用开启 XSC 的可执行体。实测可行:开启 XSC 的可执行体同为 2.08 倍,额外编译 1.5–2.9 s,每 10 step 用一次时平均 step 增加约 11%;开启与未开启 XSC 的输出不逐位相同,不能互相比对 实测(附录 A.4.3)。
  • 时长:Google 未公开 SDC 筛查时长;硬件侧在制造和数据中心 burn-in 阶段用 FBIST 筛查,运行期间由 FBIST 与 VPU replay 持续检测 文档。客户侧:交付与返修跑 CHS standard、gemm_chained 和 XSC、ICI 诊断运行(3.1、3.2),疑似 SDC 时用 XSC 定位模式跑少量 step,ICI 问题用 11 个 flag 短时诊断(3.5)。
  • 逐位一致性:同一 jax、libtpu 版本下,同节点与跨节点重跑的 HLO 和输出逐位一致;libtpu 0.0.50.1 升到 0.0.51 输出相同但 HLO 不同;jax 0.9.0/libtpu 0.0.34 与 jax 0.12.0/libtpu 0.0.50.1 的输出不同(jax 与 libtpu 同时变化,无法归因)实测(附录 A.4.4)。跨版本一致不作保证,升级前后需重建参考结果。

2.5 带内 15 s 遥测#

回答 R-06(辅助 R-07、R-08)。GKE 默认以 60 s 粒度导出 TPU 利用率系统指标;客户未要求 15 s 粒度,15 s 采集器只作可选增强。

端点或指标内容实测
:8431(多进程至 8438)libtpu 运行时指标,仅 TPU 程序运行时存在,需声明 containerPort: 8431(GKE TPU)文档注入 TPU_RUNTIME_METRICS_PORTS=8431..8438 实测
kubernetes.io/{node,container}/accelerator/*GKE 系统指标,60 sduty_cycle、memory_* 仅在容器持有 TPU 时有数据,memory_used 延迟 1–31 s;tensorcore_utilization 空闲也有,延迟 48–78 s 实测
:2112tpu-device-plugin Prometheus 端点,与系统指标同为 tpu-exporter 的对应物(客户问答表)文档device plugin 已配置 实测
:211315 s 采集器 exporter,GMP 15 s 抓取,存为 prometheus.googleapis.com/<name>/gauge 或 /histogram 实测GMP 样本间隔 15.0 s,可见延迟 p50 1.3 s、最大 2.3 s 实测

单 slice JAX 作业在 :2113 上有 13 个指标名:duty_cycle、memory_used、memory_total、tensorcore_utilization、memory_bandwidth_utilization 及各自的 _node 版本,hlo_execution_timing_microsecond(直方图)、hlo_queue_size、ml_runtime_uptime_seconds;Megascale 与 DCN 指标不出现,框架 :9431 指标因作业未开启也不出现 实测(附录 A.5.1)。

15 s 采集器使用客户仓库中 Google 侧提供的 15 s 采集器配置;本次以命名空间化变体在验证集群部署(附录 A.5.1)实测。部署注意:

  • 镜像 0.1.4 在 registry 中标记 deprecated-public-image,已有 0.1.5、0.1.6;GKE 自带的 kube-system/ai-telemetry-collector 为 0.1.1 实测;上线前向 GKE 确认版本。
  • 原文件复用有 node update/patch 权限的 tpu-device-plugin-sa 文档;命名空间化配置在 TPU 节点上以命名空间 Role(pods)加 nodes 只读 ClusterRole 正常运行,tpuhost 从节点 label 识别 TPU 代际;缺 nodes 权限时 k8s_attributes 报 nodes forbidden(CPU 节点)实测;model、tpu_topology 取自节点 label,因此取不到 未验证。只给 Role 的对照在 CPU 节点上进行,tpuhost 随后因取不到 accelerator-type 退出;TPU 节点上未单独测试(附录 A.5.1)。
  • tpuhost 读 sysfs BAR,以 privileged root 运行 文档;非 TPU 节点上取不到加速器类型而退出,须保留 TPU nodeSelector 实测。
  • 芯片编号随来源不同:libtpu 来源的序列用全局设备号(第二台主机为 -4 至 -7),BAR 来源与 hlo_* 用本机芯片号 0–3;PodMonitoring 的 namespace 标签覆盖指标自带的同名标签,后者改名为 exported_namespace 实测。
  • 指标过滤为白名单,新增指标不加 rename 与白名单会被静默丢弃 文档。单 slice 作业实测每节点 13 个指标名、约 1,280 条序列,其中 1,216 条为 hlo_execution_timing_microsecond 直方图桶 实测;多 slice 训练加入 Megascale 直方图后每节点序列数明显增加 文档;GMP 按样本计费。
  • 可见每芯片利用率与 HBM、框架指标,Megascale 与 H2D/D2H 时延直方图仅多 slice 作业有数据;不含温度、功耗、ECC、PCIe 错误、ICI 链路状态(见 2.6)、核心频率与 PCIe 吞吐 文档。

实测部署:apply 后 6 s 两个 Pod 就绪(镜像 46 MB),tpuhost 从节点 label 识别 TPU 代际;双机作业期间每 Pod 11–18 mCPU、88–95 MiB(limit 256Mi)实测。慢节点检出时间:15 s 带内信号约 40 s;GKE 60 s 系统指标约 130 s(样本时间;duty_cycle 另加入库延迟(以同一描述符与管道的 memory_used 实测 1–31 s 作代理,duty_cycle 本身未单独测),约 2.5 min 可查询;计算侧 tensorcore_utilization 按 10% 差值 131 s、25% 差值 431 s,另加 48–78 s 入库延迟;见 3.4.3)实测。

2.6 带外 Cloud Monitoring 指标#

回答 R-07、R-08、R-09(辅助 R-06、R-11)。带外指标由 Google 主机侧遥测写入项目的 Cloud Monitoring,节点上无需 agent;租户可用的带外能力为这些指标与报修接口(2.10),公开文档未提供 BMC/IPMI 访问 未验证。定义见 Monitor TPUs 文档,实测见附录 A.6.1。

指标(前缀 compute.googleapis.com/)要点周期,实测延迟验证集群数据
instance/tpu/infra_health BETA值恒为 1,看 health_status、unhealthy_category 标签60 s,350–382 s 实测连续;24 h 内 3 次 UNHEALTHY,各 11–12 min 实测
instance/tpu/chip_state BETA值为该 state 的芯片数;芯片不健康时 HEALTHY 序列消失,出现 state=UNHEALTHY 序列 实测60 s,256–296 s 实测平时 HEALTHY=4;上述 3 次片段中 UNHEALTHY=4 实测
instance/tpu/accelerator/*(20 项)BETA温度、功耗、core_throttling_indicator、hbm_uncorrectable_count、pcie_*_error_count、network/ici_*描述符无采样周期;10-27 至 10-29 实测 60 s 实测仅 10-27 至 10-29 有 15 项,此后中断 实测
tpu/network/nic_packets_*(4 项)BETA收发包与 rx/tx 丢包同上同上 实测
instance/tpu/failure_prediction_{status,score} BETA状态标签为 Value文档 60 s,540 s42 天 0 序列 实测

注意事项:

  • instant 查询回看 5 min,短于 infra_health 延迟,结果为空;一律用 last_over_time 或 max_over_time 加 [10m] 实测。
  • hbm_uncorrectable_count、pcie_* 用 increase();ici_link_flaps 在 42 h 内各端口值恒定(1–9)、不回落,用 delta() 看增长 实测。完整 15 min 窗口实测均有 15 点,持续类条件可加 count_over_time(x[15m]) >= 14 实测。
  • unhealthy_category 文档值为 BAD_TPU_CHIP、NETWORKING_ISSUE、BAD_SC_CHIP,实测出现未文档的 INFRA(同项目其他实例还出现 INTERNAL INFRA),同时段无 TPU 相关日志 实测;告警不要按类别值白名单过滤。
  • core_throttling_indicator:reason 为空的序列恒为 0,ldidt_droop_clocks_skipped 偶发非零(最大约 0.005)实测;无公开阈值,按每芯片基线偏离判断,不按 > 0 告警。
  • NIC 丢包:tx 计数 42 h 内增至 65–70 万,rx 为 0–20 实测;tx 按速率偏离基线告警,不按增量大于 0。
  • accelerator/* 中断期间同 zone 非 GKE 的 TPU7x VM 仍在上报,原因未确认 未验证;按尽力而为使用,并对缺失告警(3.4)。
  • VM label 在 PromQL 中为 metadata_user_<key>,可按 goog-k8s-node-pool-name 分组(2.6.3 第 3 条)实测。

59 min 双机 TPU 作业期间 accelerator/* 仍无数据,只有 active_chips、scheduled_chips、utilized_chips、chip_state、infra_health;TPU 负载不会使其恢复 实测。

2.6.1 DCGM 16 项的对应关系#

客户清单(客户问答表)的 16 项在 TPU 上均无一一对应指标 文档,缺口按 feature request 跟进。

DCGM 类别(项数)TPU 最接近的信号结论
SM 与显存当前、最大频率(4)core_throttling_indicator间接;不公开频率
PCIe 吞吐、链路宽度与代数(8)H2D/D2H 时延与大小直方图(2.5,仅多 slice 作业有数据);sysfs 链路速度 Unknown、宽度 0 实测未公开
单比特 ECC(2)仅 hbm_uncorrectable_count缺口
行重映射(2)能否继续使用看 infra_health、chip_state缺口

2.6.2 ICI 与 NIC#

  • 租户可见 ici_link_health(1–5 短暂抖动,6–9 持续降级,10 致命并自动驱逐 workload)、ici_link_flaps、ici_packets_*(只有包数)、NIC 收发与丢包 文档;光模块、OCS 等链路级细节无公开接口,经支持渠道获取(2.10)。
  • 2x2x2 实测:ici_link_health 按物理端口上报,带 accelerator_id(0–3)与 port_id,每芯片 2 个 .int 和 1 个 .ext,42 h 内全为 0;ici_link_flaps 每芯片 6 条;port_id 形如 tray0.chip0.ici1.int 实测;后缀含义无公开说明 未验证。
  • DCN 指标只在多 slice 时有(2.5 的 Megascale 时延、compute.googleapis.com/tpu/multislice/*),单 slice 为 0 序列 实测。
  • “RDMA 问题监控”对应 ICI 健康、抖动与 NIC 丢包告警(3.4)。

2.6.3 查询与接入#

指标名映射:第一个 / 换成 :,其余特殊字符换成 _。第 1、2 条按 60 s 步长对实测时段回放(按数据时间,不含入库延迟),3 次 UNHEALTHY 片段均命中,第 1 条每次非空 22 min、第 2 条每次非空 21 min 实测;第 4、5 条已在验证集群执行 实测。第 3 条原用 max by,实测对 2 节点 × 4 芯片的池返回 4(单节点最大值),现改为 sum by 求池内健康芯片总数,实测返回 8;某节点 HEALTHY 序列消失超过 10 min 后降为 4 实测。<TPU_POOL>、<N> 换成节点池名与节点数。以上查询作用于整个项目;一个项目有多个集群时加 "metadata_user_goog-k8s-cluster-name"="<CLUSTER>" 过滤(写法见附录 A.6.1 Z3)。

PromQL
# 1 节点健康异常
max by (instance_id, health_status, unhealthy_category) (last_over_time(compute_googleapis_com:instance_tpu_infra_health{monitored_resource="gce_instance", health_status!="HEALTHY"}[10m]))
# 2 非 HEALTHY 芯片数大于 0
max by (instance_id) (last_over_time(compute_googleapis_com:instance_tpu_chip_state{monitored_resource="gce_instance", state!="HEALTHY"}[10m])) > 0
# 3 按节点池求健康芯片总数
sum by ("metadata_user_goog-k8s-node-pool-name") (last_over_time({"__name__"="compute.googleapis.com/instance/tpu/chip_state", monitored_resource="gce_instance", state="HEALTHY"}[10m]))
# 4 节点池内上报 chip_state 的节点数少于规模
(count(max by (instance_id) (last_over_time({"__name__"="compute.googleapis.com/instance/tpu/chip_state", monitored_resource="gce_instance", "metadata_user_goog-k8s-node-pool-name"="<TPU_POOL>"}[10m]))) or vector(0)) < <N>
# 5 有健康数据、无硬件指标的节点
count by (instance_id) (last_over_time(compute_googleapis_com:instance_tpu_infra_health{monitored_resource="gce_instance"}[10m])) unless count by (instance_id) (last_over_time(compute_googleapis_com:instance_tpu_accelerator_tray_temperature{monitored_resource="gce_instance"}[30m]))

接入客户 Prometheus:Cloud Monitoring 提供 Prometheus 兼容查询 API(实验室以 curl 调用 实测),Grafana 可直接对接(GMP 查询)文档;或部署 stackdriver_exporter(默认监听 :9255,需 roles/monitoring.viewer;--monitoring.metrics-interval 默认 5m,是每次抓取的查询窗口而非拉取周期)文档。--monitoring.metrics-prefixes 每个前缀单独写一次,逗号拼接时取不到 TPU 序列;带外健康指标入库延迟超过默认窗口,需加 --monitoring.metrics-offset=7m(或 --monitoring.metrics-ingest-delay),默认窗口下 infra_health 无数据 实测:

bash
stackdriver_exporter --google.project-ids=<PROJECT> \
  --monitoring.metrics-prefixes=compute.googleapis.com/instance/tpu/ \
  --monitoring.metrics-prefixes=compute.googleapis.com/tpu/network/ \
  --monitoring.metrics-interval=5m --monitoring.metrics-offset=7m

2.7 日志#

回答 R-11(辅助 R-09)。TPU 没有 GPU XID 式的公开错误码表(客户问答表),错误定位依靠下列日志和 2.6 的计数指标,实测见附录 A.7.1。

来源Cloud Logging 位置要点
libtpu tpu_driver.INFOkube-system/tpu-device-plugin-* 的 sidecar-log-collector 容器 stdout行前缀 [/tmp/tpu_logs/<容器名>/tpu_driver.INFO];severity 恒为 INFO;pod_name 为 device plugin Pod 实测
workload stdout/stderrworkload 命名空间的 k8s_containerlibtpu 默认只把 FATAL 写到 stderr 文档;stderr 中的 glog 行被解析为 jsonPayload.message,severity 取 glog 级别,非 glog 行记为 ERROR,过滤用 jsonPayload.message 实测
tpu-device-plugin、节点tpu-device-plugin 容器 stderr;k8s_node 的 kubelet、node-problem-detector、events噪声项见下方分级表 实测

libtpu 日志变量(TPU 故障排查):GKE 注入 TPU_LOG_DIR=/tmp/tpu_logs/<容器名> 实测;TPU_STDERR_LOG_LEVEL 默认 3,设为 2 时 ERROR 及以上同时写入 stderr;TPU_MAX_LOG_SIZE_MB 默认 1024 文档。健康初始化实测 level 0 输出 181 行 stderr、level 2 为 0 行,启动耗时无差异 实测;Megascale hang 摘要的日志级别无公开说明 未验证。建议生产用 2,诊断运行用 0。

按文本中的 glog 级别筛 ERROR、FATAL 行的 gcloud logging read 写法见附录 A.7.1。

注意事项:

  • sidecar 只扫描 /tmp/tpu_logs/**/tpu_driver.INFO(DaemonSet 配置,文件含全部级别),且同一容器内只上传第一个 libtpu 进程的日志,后续进程新建的文件不上传 实测(附录 A.4.2);据此,TPU_LOG_DIR 移出该目录后日志不会进入 Cloud Logging 未验证。
  • 延迟:glog 行时间到 Logging 接收端到端 p50 3.8 s、p95 6.9–7.4 s(两次实测,其中 59 min 作业 845 条)实测。
  • /tmp/tpu_logs 位于主机 tmpfs,同节点下一次 TPU 分配时被清空,Pod 删除时不清空 实测;sidecar 日志可见 Log file ... removed 实测;需保留的内容从 Cloud Logging 取。
  • Cloud TPU 文档列出 FINGERPRINT_MISMATCH、DATA_INPUT_STALL 等 5 类健康原因,验证集群 30 天 0 命中 实测。
  • 项目范围全文检索即使限定 resource.type=k8s_container,7–8 天窗口也多次超过 240 s 或报 API deadline too short(4 个窗口仅 1 个 57 s 返回);全文检索应限定集群(30 天约 97 s)或 logName(2–14 s)实测。
  • containerLogMaxSize 默认 10Mi(可设 10Mi–500Mi),containerLogMaxFiles 默认 5,经节点系统配置调整 文档。

错误分级(计数类见客户问答表,ici_link_health 取值见 Monitor TPU):

级别信号平台行为与客户动作
致命hbm_uncorrectable_count、pcie_fatal_error_count 增量大于 0;ici_link_health = 10平台自动下线机器或驱逐 workload;客户恢复作业(见 3.5.6)
非致命pcie_nonfatal_error_count 增量;ici_link_health 1–9;降频影响负载时经 R&R 接口报修(见 2.10)
噪声device plugin 的 :8431 connection refused 与 BAR 读取 Corrupt data found(checksum didn't match 每节点每天 16–23 次,11-03 前 12 h 为 12–17 次;unable to deserialize 在两节点 6 min 样本中 33 次);otelsvc、config-reloader 的 OOMKilling 实测不告警;BAR 错误频繁且串口日志出现 vbar_control_agent 被 OOM kill 时,记录节点与时间后报修 未验证

2.8 维护事件与 ML Diagnostics#

回答 R-09、R-12。主机维护期间作业可能变慢或中断,2.6 的健康指标不一定反映 未验证,排查慢作业先查维护(3.5.2)。

  • 验证集群一次计划维护的通知依次为(时间戳见附录 A.7.1):审计日志 compute.instances.upcomingMaintenance(SCHEDULED、PENDING)→ K8s event MaintenanceWindowScheduled(注解 maintenance.gke.io/*)→ 日志 maintenance.googleapis.com/maintenance_events;节点带 label cloud.google.com/scheduled-maintenance-time 与注解 node.gke.io/upcoming-maintenance(JSON,含窗口与 can_reschedule)实测。
  • 非计划维护同样有审计记录:项目内其他节点(含 tpu7x)有 5 条 UNSCHEDULED、FAILURE_INFRA 实测。
  • GKE 1.35 起发出维护全生命周期 K8s 事件,集群内只保留 60 min,历史查 Cloud Logging(GKE);维护日志可直接查历史,无需轮询(TPU)文档。
bash
kubectl get nodes -L cloud.google.com/scheduled-maintenance-time
gcloud compute instances describe NODE --zone=ZONE --flatten=resourceStatus.upcomingMaintenance

审计日志查询见附录 A.7.1。

ML Diagnostics 在 GKE 1.36.0-gke.4447000 起自动为每个 TPU Job 建 ML run,监控聚合 duty cycle(默认下降 15% 记为性能下降),检测 hang、编排中断与终止,并运行 ICI、温度、降频、HBM、Megascale XLA hang 等分析器;需启用 Cluster Director API(Workload Monitoring)文档。

  • 集群内无需安装组件,run 由服务端创建;两次实测 Job 创建后 1–4 s 出现 run(Job 创建时间为秒精度);事件写入日志 ml_diagnostics_workload_event,CLI 为 gcloud alpha mldiagnostics 实测。
  • 59 min 双机作业依次注入计算侧慢节点、主机侧慢节点(步时 +48%、+73%,后者聚合 duty cycle 约降 20%)和 12 min hang:两类慢节点均无事件;hang 开始 37 s 后出现 1 个 PERFORMANCE_DEGRADATION,13 个分析器均为 NOT_DETECTED,没有 hang 类型事件,该事件持续到 run 结束 实测。
  • 因此慢节点与 hang 的告警以 3.4 的 B1、B4、B6 为主,ML Diagnostics 事件只作旁证(C3)。

2.9 起飞前检查 precheck_v2#

回答 R-05(RQ-11~14):对标客户现有 GPU 预检脚本(依据客户提供的 GPU 预检说明文档),替换上一版的预检脚本(缺陷见附录 B)。脚本 precheck_v2b.sh 全文见附录 A.9.2(清理实验期注释后的发布版),部署与实测见附录 A.9.1。

#GPU 检查项TPU 等价项步骤(退出码)
1空闲/dev/vfio 占用检测(只检测不杀进程;默认镜像无 fuser,容器内也看不到其他 Pod 的进程,实际固定为 WARN)。空闲由 3.3 的绑定前检查保证,残留占用预计表现为第 10 步失败 未验证2(102)
2P2P本机 4 芯片 all-reduce10(120)
3驱动错误态8 个 1ae0:0076 绑定 vfio-pci、revision 非 0xff,vBAR socket 存在1、3(101、103~105)
4模式无 TPU 等价项—
5网卡 DOWN网卡 up、MTU、TCP data split 为 off(需 hostNetwork)5(109、110)
6根分区使用率/、/tmp 使用率低于 90%6(111)
7框架设备初始化JAX 本机 8 device,GEMM 结果逐位一致10(120)
8宿主机业务端口无等价项,改为解析对端主机名(只告警)9
9互联错误计数guest 内无 ICI 计数器,用带外 ici_link_health(见 2.6)预检外
增补—AER 与 PCIe 链路(v7x guest 内不可见,只告警;可见时按 106~108 失败)、主机内存、软件指纹4、7、8(106~108、112~114)

网卡参数:tpu7x-standard-4t 机型有 2 个物理网卡(TPU 机型)文档,验证集群节点 guest 内只见 eth0(gVNIC,MTU 8896)实测。按节点实际可见的网卡设 PRECHECK_NICS(验证集群为 eth0)与 PRECHECK_EXPECT_MTU=8896(MTU 不符只告警),否则默认的 eth1 会多一条 WARN。

第 10 步在多主机 slice 的节点上只把 TPU_HOST_BOUNDS 改为 1,1,1,保留本机 ICI,不用会关闭 ICI 的 --deepsea_hal_test_* 标志(见 2.0)实测。按该配方(发布版即 precheck_v2b),libtpu 0.0.34 上本机 8 device GEMM 加 all-reduce 通过;原 --deepsea_hal_test_* 配方在 0.0.34 上因未知 flag 失败,退出码 120 实测(附录 A.9.1)。

退出码:跑完全部检查,每项输出 PASS、WARN 或 FAIL 并汇总,以第一个失败项的码(100~120)退出,0 为通过,WARN 不算失败;PRECHECK_FAIL_FAST=1 时遇错即停。编排侧只区分成功与失败时,由外层把非 0 视为失败。

时长:TPU 冒烟超时默认 PRECHECK_TPU_TIMEOUT_S=180(实验中设 120),对端解析最多等 30 s,在 10 min 级的预检时间预算内。2x2x2 实测:initContainer 9–10 s,Pod 创建到主容器完成 22–24 s;headless Service 未设 publishNotReadyAddresses: true 时,initContainer 中对端主机名无法解析,第 9 步等满 30 s 后告警 实测(附录 A.9.1)。

多主机通信冒烟(RQ-13):各 Pod 同时执行 jax.distributed.initialize() 加全 slice psum,2x2x2 上初始化 3.9 s、脚本 6.6 s 实测;需要全部 worker 进程同时在线。headless Service 设 publishNotReadyAddresses: true 时,各 initContainer 可同时完成多主机初始化,10 s 通过,但该次冒烟的 all-reduce 只覆盖本机 device 实测;未设时放在主容器入口第一步。对端 8471 端口在 initContainer 阶段关闭、主容器中 libtpu 启动后打开 实测。

版本一致性(RQ-14):第 8 步打印 jax、jaxlib、libtpu 版本、libtpu.so sha256 与 LIBTPU_INIT_ARGS 摘要,各 worker 除内核外须一致。Google 答复:libtpu 与标准 Linux 驱动 vfio-pci 解耦,运行时在 libtpu 内,libtpu 与 JAX 靠版本钉定兼容(客户问答表)文档,镜像按 digest 固定即可。

2.10 故障上报与隔离#

回答 R-13(RQ-40、41、43)。本节核对文档、--help 与 dry-run;验证环境未实际上报或打标。

场景推荐做法平台动作与限制
GKE 管理的 TPU 节点(本文场景)先隔离节点(cordon;Dynamic Slicing 集群中即一个 2x2x1 partition,固定拓扑多主机节点池中整个 slice 随之不可用于多主机作业),再开支持工单,附下方证据清单不对其 VM 调用 report-host-as-faulty(node isolation)文档
GKE 节点标签 cloud.google.com/fault-behavior公开调试 wiki 将其列为 GKE 管理的 TPU 节点的上报方式;GKE 文档尚未列 TPU 机型,TPU v7x 是否支持需 Google 确认,确认前不接入自动化 文档取值 PERFORMANCE、SDC、XID、unspecified,注解 cloud.google.com/fault-description(GKE 1.35.6-gke.1017000 或 1.36.0-gke.3251000 起);驱逐 Pod(遵守 PDB 与 terminationGracePeriodSeconds)、禁止调度、调用 GCE 接口标记主机;要求 GKE 1.32.3-gke.1057001 起与 reservation-bound,可能按 reservation 每月限流(All Capacity 模式不限流),进行中拒绝新请求 文档
TPU VM(All Capacity 模式)按 TPU 文档执行 gcloud compute instances report-host-as-faulty(GA),--disruption-schedule 与 --fault-reasons=behavior=…,description=… 必填;TPU 文档列出的 behavior 为 PERFORMANCE、SILENT_DATA_CORRUPTION、BEHAVIOR_UNSPECIFIED 文档VM 保持 RUNNING 约 10–12 min,随后在原主机停机修复 3–14 天或更久;仅 v6e 及以后、reservation-bound 文档。gcloud 参考的枚举另有 UNRECOVERABLE_GPU_ERROR、CHIP_ERROR,TPU 文档未列,不用于 TPU 文档;SDK 591.0.0 --help 与参考页一致,见附录 A.10.1 实测

Google 确认 TPU 支持标签通道后,上报写法如下(标签与注解同一请求,只打一次)。命令已用 --dry-run=client 校验,同形 patch(换成测试用键名)经 --dry-run=server 接受 实测;实际驱逐与上报效果未验证 未验证:

bash
kubectl patch node <NODE> --type merge -p '{"metadata":{"labels":{"cloud.google.com/fault-behavior":"SDC"},
  "annotations":{"cloud.google.com/fault-description":"XLA_SDC_CHECKER mismatch, chip 1, 2026-11-03T10:30Z"}}}'
kubectl get node <NODE> -L cloud.google.com/report-and-replace-status   # PodsEvicted, OperationRUNNING, OperationDONE, OperationFAILED, Error

注意事项:

  • 上报时机按 2.7 的错误分级:致命错误由平台自动处理,非致命错误影响作业时才上报。
  • GKE 标签通道的主动上报可能按 reservation 限流(All Capacity 模式不限流,报告故障主机),且有成本,只用于平台未检出的疑难问题;修复后 Google 跑 burn-in 再归还,无修复时长统计(客户仓库 infra#29)文档。
  • GKE 文档只说明修复后移除它自己加的污点与 fault-behavior 标签,未提及客户自加的 cordon 或污点,修复后需人工检查并撤销 未验证。
  • 工单内容:项目、zone、集群、节点名与 instance id、UTC 时间窗、故障类别(PERFORMANCE、SDC 等)、证据(指标名、取值、时间戳、日志原文)、预检或复测输出、jax 与 libtpu 版本、是否在其他节点复现、已做操作。

3 端到端运维方案#

按节点池生命周期组织:交付验收、返修准入、起飞前检查、日常监控与告警、故障处置,各步骤引用第 2 章的接口。

告警环境类问题,重试硬件问题,上报修复回池判定 3.5.7交付验收 3.1起飞前检查 3.3日常监控与告警3.4故障处置 3.5返修准入 3.2
点击图中节点可跳转到对应章节

3.1 交付验收#

回答 R-01、R-02、R-04。新节点池接业务前确认每个 chip、每台主机和 slice 内 ICI 达标,并留存基线。TPUMS 与诊断运行的门限均为起始值,按上线后 2 周实测基线调整。

步骤内容范围通过条件耗时
1节点与芯片健康(2.1)每节点见 2.1见 2.1
2CHS standard(2.3)每节点池,整 slice 空闲BoH 8 项均为 RESULT_STATUS_SUCCESS,内置门限见 2.3.1;表外拓扑的 psum 为 UNKNOWN,改按步骤 4 判定17 min 58 s 实测
3TPUMS 单主机项:gemm、hbm(device 0–7)、主机传输、gemm_chained、gemm_throttling 240 s(2.2)每主机,各主机并行gemm 16384³ bf16 TFLOP/s/chip、hbm 各 device GB/s、tpu_sync H2D 与 D2H GB/s/host 不低于机群中位数 −5%;gemm_chained 三个 checksum 字段全为 True;gemm_throttling 的 xprof_slowdown_ratio ≤ 1.02,hbm_throttle_time_pct、vdd_core_throttle_time_pct 为 0(实测 1.002、0)约 18 min 估算
4TPUMS all_reduce、all_gather、all_to_all(2.2)每 slice各项 xprof GB/s/chip 不低于同拓扑基线 −5%112 s,不含安装 45 s 实测
5XSC 诊断运行:--xla_tpu_enable_sdc_checker=true(2.4),TPU_HOST_BOUNDS=1,1,1每主机rc=0;HLO is instrumented 行数大于 0(XSC 已生效);[XLA_SDC_CHECKER] 行数为 0约 15 s(50 step 链式 matmul 测试程序,含初始化)实测
6ICI 诊断运行,11 个 flag(2.4)每 slice每主机每 step 8 行 IciSdcTest :: ICI BW 齐全;无 XLA_SDC_CHECKER、ICI transfer wait、Wait timeout on sflag 行;各 TensorCore 的 ICI BW 不低于同 slice 中位数 −5%(实测 iterations 5000 时 16 个 TensorCore 均为 130 GiB/s)约 22 s(50 step 的 8 MiB psum 测试程序,含初始化;每 step 另加 228 ms)实测
7归档 BoH JSON、TPUMS summary.csv 与诊断日志;通过的节点打 tpu-health=pass(3.2)每节点池作为返修准入与复测基线—

步骤 5、6 的测试程序见附录 A.4.3、A.4.2,也可用客户自己的短程作业。两步的日志只写入 Pod 内 $TPU_LOG_DIR/tpu_driver.INFO(GKE 注入 /tmp/tpu_logs/<容器名>),stderr 为空,sidecar 不上传非首个 libtpu 进程的日志(2.4.3)实测。诊断进程结束后在每个 Pod 内读取(tpu_driver.INFO 指向最近一个 libtpu 进程的日志):

bash
grep -c 'HLO is instrumented' $TPU_LOG_DIR/tpu_driver.INFO                                 # 步骤 5:大于 0
grep -c 'XLA_SDC_CHECKER\|ICI transfer wait\|Wait timeout on sflag' $TPU_LOG_DIR/tpu_driver.INFO  # 步骤 5、6:0
grep -o 'ICI BW: [0-9]*' $TPU_LOG_DIR/tpu_driver.INFO | sort | uniq -c                   # 步骤 6:总行数 = 8 × 执行次数(50 step 测试程序为 408),各值不低于中位数 −5%

单 slice(2x2x2)合计约 42 min 估算:步骤 2 实测 17 min 58 s;步骤 3 为 2.2 单项实测之和(hbm 8 device 扫描实测 124 s),加安装约 18 min;步骤 4 为安装 45 s 加三项 112 s;步骤 1 约 1 min;步骤 5、6 实测约 15 s、0.5 min,按各 1 min 留余量。耗时不含镜像冷拉取:CHS 负载镜像冷拉取实测 95 s(在 CPU 节点上测得),jax-ai-image 未测。CHS 与 TPUMS 都独占 TPU,须串行。4x4x4 及以上拓扑的 CHS 集合通信、network-stress 和 TPUMS 集合通信耗时随拓扑增长,需首轮实跑后修订。

3.2 返修准入#

回答 R-15。GCP 归还前已跑 burn-in,无修复时长统计(见 2.10)。客户现有流程要求硬件异常节点经长时间深度压测、结果正常后才回可调度池(客户问答表),下面把它落成可执行的循环:轮数 N = ⌈T_req ÷ T_round⌉,T_req 为要求的总压测时长,T_round 为单轮时长。

门控用客户自有的节点标签,不用污点,也不 cordon:CHS 0.3.2 的 tpu7x 测试 Pod 只容忍 google.com/tpu,节点带其他 NoSchedule 污点时 CHS Job 无法调度并被判失败;节点池中有 cordon 节点时 CHS 不测试该池(2.3.3)文档。训练 Pod 模板加 required nodeAffinity,只落在 tpu-health=pass 的节点上;CHS 的 nodeSelector 只用机型、加速器与拓扑标签 文档,CHS、TPUMS 与诊断 Pod 不带该约束,仍可在待验节点上运行(依据 CHS 0.3.2 平台配置中的 nodeSelector 与容忍)文档;标签命令与 nodeAffinity 已用 --dry-run=server 与测试 Pod 核对 实测;带标签节点上的 CHS 实跑未做 未验证。该约束只作用于调度,标签改为 pending 或 fail 不会驱逐运行中的 Pod,摘除按 3.5.1 执行。

yaml
# 训练 Pod 模板 spec.template.spec 片段
affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
      - matchExpressions:
        - key: tpu-health
          operator: In
          values: ["pass"]
项每轮耗时依据
TPUMS 单主机项(3.1 步骤 3),gemm_throttling 改为 min_duration_s: 3600约 74 min单项均为实测:3600 s soak 实测 3640 s,xprof_slowdown_ratio 1.0054,throttle 0%,性能状态不变;累加为 估算
XSC 诊断运行(3.1 步骤 5,每主机)约 15 s实测 13–15 s
CHS standard(整 slice)约 18 min实测 17 min 58 s
ICI 诊断运行(3.1 步骤 6,整 slice)约 0.5 min实测 22 s 加 Pod 启动 5 s
单轮合计 T_round约 1.55 h估算

例如要求不少于 8 h 时,N = ⌈8 ÷ 1.55⌉ = 6,总计约 9.3 h 估算。时长按 2x2x2 实测外推,不含镜像冷拉取;4x4x4 及以上拓扑需首轮实跑后修订。

  1. 节点回到集群后确认已 uncordon、无客户自加的 NoSchedule 污点,打 tpu-health=pending。kubectl 打的节点标签在节点重建时丢失(GKE 节点升级),重建后的节点没有 tpu-health=pass,同样不接训练 Pod 文档。
  2. 循环 N 轮,每轮须满足 3.1 步骤 2、3、5、6 的全部通过条件(gemm_throttling 按 3600 s 判定);第 2 轮起 gemm TFLOP/s/chip 与 hbm GB/s/device 不低于第 1 轮的 98%(起始值)。
  3. 任一轮失败即停止,打 tpu-health=fail;XSC 或 ICI 诊断失败时先用定位模式(2.4.2)收集全部事件,再按 2.10 重新上报。
  4. 全部通过后打 tpu-health=pass。节点池升级或其他重建节点的操作可能清除 tpu-health=pass(同一 GKE 文档)文档,自动化需在 quick 检查(3.5.7)通过后重新打标,否则训练 Pod 无节点可用。
bash
kubectl label nodes <NODE> tpu-health=pending --overwrite   # 步骤 1
kubectl label nodes <NODE> tpu-health=fail --overwrite      # 步骤 3
kubectl label nodes <NODE> tpu-health=pass --overwrite      # 步骤 4
kubectl get nodes -l cloud.google.com/gke-nodepool=<TPU_POOL> -L tpu-health

CHS standard 要求整 slice 空闲,2x2x2 及以上节点池中被修节点的同 slice 节点也会停用。固定拓扑多主机节点池中被修节点所在 slice 本就无法承载多主机作业,按上表整 slice 循环即可。不能长时间占用整 slice 时(主要是 Dynamic Slicing 集群),只循环单主机项与 XSC 诊断运行(单轮约 1.24 h,覆盖本机 4 个 chip 的计算、HBM 与主机传输;本机 ICI 需另加 device_to_device --direction bi,实测 440 s),最后对整 slice 跑一次 CHS standard 与 ICI 诊断运行;同样以 8 h 为例,N = 7,总计约 9.0 h;加 device_to_device --direction bi 后单轮约 1.36 h,N = ⌈8 ÷ 1.36⌉ = 6,总计约 8.5 h 估算;跨主机 ICI 只能在整 slice 上验证。GCP 侧已做 burn-in,客户侧轮数可按风险偏好下调。

3.3 起飞前检查#

回答 R-05。precheck_v2(2.9)嵌入每个训练作业的启动过程,分三段执行:

阶段内容失败时
绑定前(客户编排器)目标节点上没有 Running 或 Terminating 的 TPU Pod(Running 用附录 A.0.2 的检查脚本,Terminating 用 3.5.6 的命令)换节点,残留按 3.5.6 处理
initContainerprecheck_v2 第 1–10 步,单主机模式按下表
主容器第一步(或 initContainer,见 2.9)多主机通信冒烟;由编排器汇总各 worker initContainer 日志中的 FINGERPRINT 行比对冒烟失败,或除 kernel 外指纹不一致,即删除整个作业后重建

训练 Pod 的 terminationGracePeriodSeconds 按收到 SIGTERM 后保存 checkpoint 所需时间设置;不依赖终止信号保存 checkpoint 的作业可设 1–5 s,缩短旧容器持有 /dev/vfio 的时间 未验证。无论取值,绑定前都检查 Terminating Pod。

退出码归类动作
100镜像 bash 版本低于 4镜像问题,不隔离节点
101、103设备或 vBAR socket 未就绪重建 Pod 一次,再失败按节点问题处理
102/dev/vfio 被占用(默认配置下不会出现,见 2.9)见 3.5.6
104、105TPU PCI 设备缺失或驱动异常隔离节点,按 2.10 上报
106~108PCIe AER 致命计数或链路降级(v7x guest 内不可见时只告警)隔离节点,按 2.10 上报
109、110网卡 down 或 TCP data split 为 on隔离节点,核对 GKE 版本与节点池配置
111、113磁盘使用率或可用内存不足清理节点后重试
112MemTotal 低于下限(节点内存缺失)隔离节点,按 2.10 上报
114软件指纹失败镜像问题,不隔离节点
120TPU 冒烟失败或超时先看 stderr:Unknown command line flag、import 错误、等待对端超时属镜像或作业配置问题,不隔离;同镜像在其他节点通过、本节点复测仍失败时才隔离并做 quick 检查(3.5.7)

常见 GPU 预检方案在失败时删 Pod 并屏蔽节点;TPU 侧建议只对硬件类失败(104~108、112,以及排除镜像与配置原因后仍失败的 120)屏蔽节点,环境类失败重试。

时长:TPU 冒烟硬超时默认 180 s(实验设 120 s)加对端解析 30 s,在 10 min 级的预检时间预算内(2.9)。precheck 第 10 步冒烟 4.2 s(v2b)、5.3 s(single);两主机通信冒烟 6.6 s;initContainer 9–10 s(Service 设 publishNotReadyAddresses: true;未设时 33–37 s),Pod 创建到主容器完成 22–24 s(其中主容器为 12–13 s 的 psum 测试)实测。

3.4 日常监控与告警#

日常监控回答四个问题:作业是否健康、节点与 slice 状态、芯片时间去向(3.4.5)、由谁处理(告警目录负责方列)。告警级别与 2.7 的错误分级一致,可接入客户现有的分级告警与 Pod 替换流程(R-09)。

3.4.1 信号与读取路径#

层来源实测可见延迟见
作业自报step 行、loss、Goodput 库—3.4.5
带内GKE 系统指标、可选 15 s 采集器1–78 s2.5
带外compute.googleapis.com/instance/tpu/*256–382 s2.6
日志sidecar、device plugin、节点、串口p95 约 7 s2.7
平台事件维护审计与事件、ML Diagnostics、Slice 状态—2.8
  • Cloud Monitoring 承载指标、log-based 指标、告警和看板;Observability Analytics(原 Log Analytics) 与关联 BigQuery 数据集用于 step 行、维护与审计事件的 SQL 分析和时间对齐,SQL 告警为 Preview 文档。
  • 日志分层:冗长 INFO 可在排除过滤器中用 sample(insertId, 0.99) 排除 99%、保留约 1% 文档,step 行和 WARNING 以上全量保留,sidecar 行按文本中的 glog 级别写条件(2.7);维护、审计与事件日志路由到长保留期日志桶。

用 gcloud 给 _Default sink 加排除过滤器时,过滤条件里的逗号会被当作参数分隔符,需用 ^@^ 改分隔符(语法在验证项目中核对,未应用到共享 sink)实测:

bash
gcloud logging sinks update _Default --project=<PROJECT> --add-exclusion='^@^name=tpu-verbose-info@filter=resource.type="k8s_container" AND severity=INFO AND NOT textPayload:"completed step" AND NOT resource.labels.container_name="sidecar-log-collector" AND sample(insertId, 0.99)'

C5 的事件过滤条件(Preempting 是 action 而非 reason,用它匹配不到;Killing 是正常删除 Pod 的事件,不计入)实测:

bash
gcloud logging read 'logName="projects/<PROJECT>/logs/events" AND resource.type="k8s_pod" AND jsonPayload.reason=("Evicted" OR "Preempted" OR "TaintManagerEviction") AND resource.labels.cluster_name="<CLUSTER>"' --freshness=1d

3.4.2 告警卫生规则#

  • 对状态变化的起始沿告警,粘滞型状态不按电平重复告警。
  • 计数器只用 increase() 或 delta()。
  • 带外指标窗口不少于 10 min,持续类条件加覆盖率门限(2.6)。
  • 节点创建后短时间内的启动瞬态(如 kubelet NetworkNotReady 事件)不告警。
  • 处置动作后 10 min 内抑制由该动作引起的告警。
  • 下表阈值均为起始值,按上线后 2 周实测基线调整。

3.4.3 告警目录#

负责方:平台 = 平台运维,训练 = 训练值班。查询写法见 2.6.3 与附录 A.6.1。

编号与信号查询或来源窗口级别负责方Runbook
A1 节点不健康2.6.3 第 1 条(last_over_time[10m])非空持续 5 minERROR平台3.5.6
A2a 芯片非健康2.6.3 第 2 条(非 HEALTHY 芯片数大于 0,last_over_time[10m]);第 4 条(节点池内上报节点数少于规模)10 minERROR(工单或群消息,不呼叫)平台3.5.6
A2b 芯片非健康持续或伴随停滞非 HEALTHY 序列 count_over_time(...[20m]) >= 19(芯片实际不健康约 20 min 以上),或该节点上运行的作业同时出现 B1 进度停滞,或该节点出现 B420 min,或与 B1、B4 同时CRITICAL(呼叫)平台、训练3.5.6
A3 不可纠正错误hbm_uncorrectable_count、pcie_fatal_error_count 的 increase() 大于 015 minCRITICAL平台、训练3.5.6
A4a ICI 致命ici_link_health = 1010 minCRITICAL平台、训练3.5.3、3.5.6
A4b ICI 降级ici_link_health 6–9;1–5 或 ici_link_flaps 增长只记录10 minERROR平台3.5.3
A5 非致命与降级pcie_nonfatal_error_count 增量、NIC rx 丢包增量与 tx 丢包速率偏离基线、降频偏离基线15 minWARNING平台3.5.2
B1 进度停滞训练阶段 step 行 log-based 计数指标缺失超过 max(15 × 平均步时, 15 min),且作业仍在运行(作业状态门控,写法见表后 B1);或 max_productive_steps 不增长同左CRITICAL训练3.5.4
B2 启动超时Pod Running 后超过 T_dev 仍无 device 列表行,或超过 T_first 仍无首个 step;T_dev、T_first 取本作业类型的实测基线加余量(起始值:基线 × 1.5,且至少多 5 min;写法见表后 B2;T_dev 需另建匹配 device 列表行的 log-based 指标,写法同 A.11.2 未验证)T_dev、T_firstERROR训练3.5.4
B3 步时回退步时 p50 高于基线 1.10 倍触发(恢复门限 1.05 倍需用第二条条件或下游去抖实现,未验证);同步训练各 worker 步时相同,定位慢节点用 B615 minWARNING训练3.5.2
B4 活跃度兜底节点 duty_cycle 5 min 内全为 0,且该作业 60 min 内有过 step(相位门控,排除启动与编译)5 min 后再持续 1 minERROR训练3.5.4
B5 数值异常loss 为 NaN 或突增(作业自报)即时CRITICAL训练3.5.5
B6 慢节点同一作业各节点的带内 15 s 信号相差 25% 以上:主机侧慢节点 duty_cycle 最低,计算侧慢节点 tensorcore_utilization_node 最高,两者 hlo_execution_timing_microsecond 平均值均最低连续 2 个样本WARNING训练3.5.2
C1 计划维护K8s event MaintenanceWindowScheduled事件WARNING训练、平台3.5.2
C2 非计划维护审计 upcomingMaintenance 为 UNSCHEDULED事件ERROR平台3.5.2
C2b 维护终止K8s event TerminateOnHostMaintenance事件ERROR训练、平台3.5.2
C3 ML Diagnostics 事件日志 ml_diagnostics_workload_event(实测 hang 开始 37 s 后出现 PERFORMANCE_DEGRADATION,作业结束有 WORKLOAD_TERMINATION;两类慢节点无事件)事件WARNING训练3.5.2、3.5.4
C4 Slice 降级Slice 状态 ACTIVE_DEGRADED(仅 Dynamic Slicing 的顶层 4x4x4 拓扑)事件ERROR平台3.5.3
C5 驱逐风暴K8s event reason 为 Evicted、Preempted 或 TaintManagerEviction(按 Pod 去重计数),同一作业 30 min 内不少于 3 个 Pod,合并为一条30 minERROR训练3.5.6
D1 带外数据缺失整池 absent_over_time(compute_googleapis_com:instance_tpu_accelerator_tray_temperature{monitored_resource="gce_instance", "metadata_user_goog-k8s-node-pool-name"="<TPU_POOL>"}[30m]);逐节点用 2.6.3 第 5 条30 minWARNING平台2.6
D2 采集与导出链路15 s 采集器在线目标数少于 TPU 节点数(写法见表后 D2,10 min;不依赖 kube-state-metrics;采集器部署在 kube-system 时,只要有同名 PodMonitoring 抓取即同样适用 未验证);kube-state-metrics 无数据(absent(kube_pod_status_phase{cluster="<CLUSTER>"}),10 min);logging.googleapis.com/exports/error_count 大于 0(15 min)见左WARNING平台2.5、2.7

B1、B2、D2 的写法(Cloud Monitoring PromQL)。GKE 托管的 kube-state-metrics 没有 kube_job_status_active 与 kube_pod_start_time,门控改用 kube_pod_status_phase;step 计数用附录 A.11.2 创建的 log-based 指标 tpu-verify-step-count(PromQL 名 logging_googleapis_com:user_tpu_verify_step_count;生产作业按自身的命名空间与容器名改写 A.11.2 指标的 filter);空结果要用 or vector(0) 补 0,否则作业挂起或采集器全部消失时条件为空、不会触发。B1 带首步门控(6 h 内出现过 step),首个 step 之前不由 B1 判定,由 B2 覆盖;首步门控未在验证集群单独测试 未验证。门控按 Pod 名前缀统计 6 h 内的 step,6 h 内以同名 Job 重新提交时上一轮的 step 仍会满足门控,启动阶段可能误报,作业名需唯一(例如带提交时间戳)。B1、B2 其余部分在验证集群用缩短的窗口实测:B1 在最后一个 step 后约 3.7 min(窗口 3m)持续触发、step 期间不触发;B2 只对从未出现 step 的 Pod 触发;D2 在采集器未部署和全部删除时触发、2/2 在线时不触发 实测。JobSet 作业把 B1 左侧换成 kube_jobset_active_replicas{jobset_name="<JOBSET>"} > 0,验证集群没有 JobSet,只核对了指标存在 未验证。

PromQL
# B1 进度停滞(普通 Job):Pod 仍在 Running,已出现过 step(首步门控),且 15 min 内没有新 step
(count(kube_pod_status_phase{cluster="<CLUSTER>", namespace="<NS>", pod=~"<JOB>-.*", phase="Running"} == 1) > 0)
  and on () (sum(sum_over_time(logging_googleapis_com:user_tpu_verify_step_count{monitored_resource="k8s_container", namespace_name="<NS>", pod_name=~"<JOB>-.*"}[6h])) > 0)
  and on () ((sum(increase(logging_googleapis_com:user_tpu_verify_step_count{monitored_resource="k8s_container", namespace_name="<NS>", pod_name=~"<JOB>-.*"}[15m])) or vector(0)) == 0)

# B2 启动超时:Pod Running 已满 <T_FIRST_MIN> 分钟,且 1 h 内没有任何 step
(max by (pod) (count_over_time((kube_pod_status_phase{cluster="<CLUSTER>", namespace="<NS>", pod=~"<JOB>-.*", phase="Running"} == 1)[<T_FIRST>:1m])) >= <T_FIRST_MIN>)
  unless on (pod) label_replace(sum by (pod_name) (sum_over_time(logging_googleapis_com:user_tpu_verify_step_count{monitored_resource="k8s_container", namespace_name="<NS>"}[1h])) > 0, "pod", "$1", "pod_name", "(.*)")

# D2 15 s 采集器在线目标数少于 TPU 节点数
(count(up{job="ai-telemetry-collector-15s", cluster="<CLUSTER>"} == 1) or vector(0)) < <N_TPU_NODES>
  • 按验证集群数据核对(附录 A.6.1):24 h 内 3 次 UNHEALTHY/INFRA 片段均在约 12 min 内自行恢复且无 TPU 日志 实测;按 60 s 步长回放这 3 次片段(按数据时间,不含入库延迟):第 1 条每次非空 22 min,A1(持续 5 min)每次触发;第 2 条每次非空 21 min,A2a 每次触发;A2b 均不触发(20 min 窗口内非 HEALTHY 点数最多 11 个,门限 19)实测。因此 A2 分两级:A2a 只发工单,持续 20 min 以上或与作业停滞同时出现才呼叫(A2b);两级窗口均为起始值,按上线后 2 周实测基线调整。
  • A3–A5 依赖 accelerator/*,验证集群该族自 10-29 起无数据,此时 A3–A5 无法触发,由 D1 兜底;D1 当前即会触发(absent_over_time 对 tray_temperature 返回 1)实测。
  • A4 按根因与连带区分,只隔离根因主机(见 3.5.3)。
  • C4 依赖 Slice 对象 文档;验证集群为静态节点池,无 Slice CRD 实测。

实测(附录 A.11.1、A.11.2;双机作业 59 min,依次注入计算侧慢节点、主机侧慢节点和 12 min hang):

  • B1:缺失条件 300 s 时,最后一个 step 后 10 min 52 s 告警,恢复后 3 min 40 s 关闭;作业正常结束 11 min 24 s 后同样告警,因此必须加作业状态门控 实测。
  • B2:验证作业容器启动到 device 列表行 4 s,JAX 初始化 1.4–1.9 s(单机、双机探测分别为 2.8 s、3.9 s,附录 A.1.3),首个 step 编译加执行 2.2–2.3 s;该作业人为加入 6 min 空闲,进程启动到首个 step 381 s 实测。按 B2 起始值,该作业 T_dev 取 5 min,T_first 取约 11 min(381 s × 1.5 = 572 s 与 381 s + 5 min = 681 s 取大)估算;生产作业按自身模型的编译耗时重新测基线。
  • B4:不加门控时在启动阶段(首个 step 前 1 min)误报;加 step 计数门控与 1 min 持续后只在 hang 时触发,时间为 hang 开始后 5 min 24 s;改用 GKE 节点级 duty_cycle 结果相同,容器级指标在 Pod 刚启动时只有 1 个样本,需加 count_over_time 门限 实测。
  • B6:主机侧慢节点 duty_cycle 58.5 对 100,计算侧慢节点 TensorCore 利用率 67.5 对 40.6;15 s 带内信号 40–41 s 检出;GKE 60 s 系统指标约 130 s(样本时间;duty_cycle 另加入库延迟(以同一描述符与管道的 memory_used 实测 1–31 s 作代理,duty_cycle 本身未单独测),约 2.5 min 可查询;计算侧 tensorcore_utilization 按 10% 差值 131 s、25% 差值 431 s,另加 48–78 s 入库延迟);两段期间各 worker 步时相同(+48%、+73%),ML Diagnostics 均无事件 实测。按“连续 2 个 15 s 样本”回放,主机侧规则在注入阶段开始后 40 s 触发并持续到阶段结束,计算侧规则 41 s 触发;计算侧规则在作业启动阶段和 hang 恢复瞬间也有连续 2 个样本命中,单样本条件每 30 s 抖动一次,因此必须要求连续 2 个样本,并把规则限定到具体作业的 Pod,按 3.5.1 只作嫌疑 实测。

3.4.4 通知治理#

  • 级别映射:P0 为 CRITICAL,P1 为 ERROR,P2 为 WARNING,即 AlertPolicy 的 severity 文档。
  • 通知渠道按负责方列拆分。
  • log-based 告警设 notificationRateLimit,指标告警设 autoClose 文档。
  • 计划维护窗口内对受影响节点的 A 组告警使用 snooze 文档。
  • 每条策略的 documentation 写明 runbook 编号。

3.4.5 KPI 与看板#

  • 作业 Goodput:训练代码接入 ml-goodput-measurement 后,指标写入 compute.googleapis.com/workload/*(goodput_time、badput_time、max_productive_steps 等,BETA,见 Compute Engine 指标列表)(Goodput)文档。
  • 芯片时间去向:节点池芯片总数 → 云侧健康(chip_state 无非 HEALTHY 芯片且无进行中维护)→ 已被容器请求(kubernetes.io/container/accelerator/request)→ 有效训练(goodput_time)。
  • “租户侧可用与云侧健康”对照面板:通过回池判定且未 cordon 的节点(3.5.7)与 infra_health、chip_state 健康的节点并列,差值为待处理节点;带外序列按 VM label 关联节点池(2.6)。
  • 每个看板首行显示各信号的最新数据时间。

3.4.6 上线前告警演练#

  • B1、B4:作业运行中暂停 step 输出(如对训练进程发 SIGSTOP);B2:在首个 step 之前暂停或延长启动;B3、B6:在一个 worker 注入固定 sleep(附录 A.11.1);记录各条告警时间。
  • A1、A2a、A2b、C1:回放 24 h 内已出现的 UNHEALTHY 片段与已有 MaintenanceWindowScheduled 事件(附录 A.6.1、A.7.1),确认表达式与通知路由。
  • D1:回放 absent_over_time(...tray_temperature...[30m])(验证集群当前为 1),确认通知路由;D2:删除测试命名空间中的采集器 Pod。
  • 每个通知渠道收到一次测试通知,runbook 链接可打开。

3.5 故障处置 runbook#

回答 R-12、R-13、R-14。按症状组织,每节含检测、定位、处置;阈值均为起始值,按上线后 2 周实测基线调整。Google 给出的常见故障来源依次为 Host 至 TPU tray 链路或 tray、ICI/OCS、DCN、host、电源(少见但影响面大);MTBF 需先经安全政策评估,目前未提供(客户问答表)文档。DCN 拥塞需多 slice 环境,本文未覆盖,见附录 D(跨 slice DCN)。

3.5.1 自动化护栏与处置步骤#

  • 检测器只产出嫌疑,执行器复核后动作;新规则先只记录不执行。
  • 不凭统计结论单独 cordon,须有维护事件、带外健康异常或复测失败佐证;自动化最多执行到下面第 2 步。
  • 1 h 内判坏 3 个节点即熔断,停止自动隔离并呼叫值班;每轮隔离设上限。
  • 人工标签与 cordon 优先;动作的操作者、原因、时间写入节点注解。

处置步骤(自动化最多执行第 1、2 步,其余逐条人工执行;节点命令在验证集群用 --dry-run=server 核对,作业删除、等待与宽限期行为用测试作业实测,cordon 与上报未实际执行):

  1. 确认证据:至少一项独立证据(维护事件、带外健康异常、预检或复测失败)。只有统计嫌疑时停在本步,作业结束后对该节点做 quick 复测(3.5.7)。
  2. 隔离:kubectl cordon <NODE> 只阻止新调度,运行中的 Pod 不受影响;同时撤销健康标签 kubectl label node <NODE> tpu-health-,并记录 kubectl annotate node <NODE> ops.example.com/isolation="<操作者>;<原因>;<UTC>" --overwrite。cordon 后不立即删除 Pod。
  3. 保存 checkpoint:按作业框架触发,确认最新 checkpoint 已完整写入存储;依赖 SIGTERM 保存的作业在第 4 步的优雅删除中完成,前提是 terminationGracePeriodSeconds 足够(3.3)。
  4. 腾空:删除整个作业(多主机作业的全部 Pod 一起删),不加 --grace-period:kubectl delete job <JOB> -n <NS>,再等待退出:kubectl wait --for=delete pod -l job-name=<JOB> -n <NS> --timeout=<宽限期加 60>s。
  5. 卡住的 Pod:节点仍 Ready 而 Pod 超过宽限期仍 Terminating 时,kubectl delete pod <POD> -n <NS> --grace-period=1(不加 --force),用 3.5.6 的命令确认已消失。
  6. 上报:按 2.10 开支持工单并附证据;fault-behavior 标签只在 Google 确认支持 TPU 后使用,且只打一次。
  7. 强制删除:只有节点 NotReady 或 VM 已重置、重建后仍有 Terminating Pod,才用 kubectl delete pod <POD> -n <NS> --force --grace-period=0。
  8. 恢复作业:Dynamic Slicing 集群在健康 partition 上重建 Slice 后重新提交;固定拓扑节点池等 GKE 重建 slice 或改用其他节点池;从第 3 步的 checkpoint 恢复。具体编排属调度范畴。
  9. 回池:修复后 kubectl uncordon <NODE>(无健康标签,训练 Pod 不会落上,见 3.2),按 3.5.7 检查,通过后 kubectl label node <NODE> tpu-health=pass --overwrite,并删除第 2 步的注解。

3.5.2 慢但指标正常(含维护与慢节点三级定位)#

  • 检测:3.4 的 B3 步时回退。同步训练中各 worker 的步时完全相同,步时只能发现作业变慢,不能定位慢节点 实测。ML Diagnostics 在两类注入慢节点(步时 +48%、+73%)期间都没有产生事件,不能用来发现慢节点(2.8)实测。
  • L0 维护:把 node.gke.io/upcoming-maintenance 注解、cloud.google.com/scheduled-maintenance-time 标签(Unix 时间,即维护窗口开始)、MaintenanceWindowScheduled 事件与回退时间对齐(2.8)实测。
  • L1 末位到达:统计每步最后完成的 worker,先按到达间隔门控(实测用 5 ms,起始值),再对门控后的步做单侧二项检验(p<0.01)。不加门控时,健康阶段 0.3 ms 量级的抖动也会给出 p≈1e-90 的误报;加门控后只标出 host 型慢节点:该阶段 667 步全部命中,第一个 50 步窗口(约 45 s)即可判定 实测。占比阈值不用 max(50%, 3/K):K=2 时 3/K 为 150%,永远不会触发 实测。
  • L2 带内信号(15 s,2.5):host 型慢节点(每步前多出主机侧耗时)duty_cycle 最低(58.5 对 100);compute 型慢节点(每步多做本地计算)tensorcore_utilization 最高(67.5 对 40.6,等待中的同伴下降);两类慢节点的 hlo_execution_timing 都最低(等待最少)实测。按连续 2 个采样相差 25% 判定,15 s 采集器 40–41 s 检出;GKE 60 s 系统指标(kubernetes.io/node/accelerator/*)130–431 s,另加入库延迟(duty_cycle 按同组 memory_used 实测 1–31 s,tensorcore_utilization 48–78 s)实测。真正的带外指标 compute.googleapis.com/instance/tpu/accelerator/* 在整个实验期间无数据 实测。各节点基线的 TensorCore 利用率本身相差 4–13 个点,离群阈值不宜低于 25% 实测。降频型慢节点未测试 未验证。
PromQL
avg by (node)(duty_cycle{cluster="<CLUSTER>"})
avg by (node)(tensorcore_utilization_node{cluster="<CLUSTER>"})
sum by (node)(rate(hlo_execution_timing_microsecond_sum{cluster="<CLUSTER>"}[1m]))
  / sum by (node)(rate(hlo_execution_timing_microsecond_count{cluster="<CLUSTER>"}[1m]))
  • 单 slice 作业没有 multislice 时延序列,tpu-info 的 collective_e2e_latency 也报不可用 实测;多 slice 作业中慢 slice 的 collective_end_to_end_latencies 最低属推断 未验证。
  • L3 交叉核实:同池对比 infra_health、chip_state、维护状态,作业结束后对嫌疑节点做 quick 复测。实测两类注入期间 L3 全部正常,只列入嫌疑,不 cordon 实测;L1、L2 只构成嫌疑,停在 3.5.1 第 1 步。
  • 处置:维护引起的改期或迁走作业;确认的慢节点按 3.5.1 第 2–9 步处理,上报类别为 PERFORMANCE。

3.5.3 ICI 链路错误(根因与连带)#

  • 检测:ici_link_health ≥ 6(分级见 2.6.2);ici_link_flaps 增长作辅助记录(与 3.4.3 A4 一致)文档;Slice 变为 FAILED。
  • 定位:同一时间窗内按主机和 port_id(如 tray0.chip0.ici1.int)分组 实测。有 .int 劣化或 chip_state、infra_health 非 HEALTHY 的主机为根因,只有 .ext 报错的邻居为连带,不隔离;.int、.ext 分指主机内、主机间链路 未验证。细定位用 sflag 超时日志(2.4)或 tpu-network-stress 逐轴带宽(2.3)。
  • 处置:Dynamic Slicing 集群中 ICI 断链后 Slice 自动解散、无备用链路,按 3.5.1 第 8 步重建,Google 答复通常 2 min 内完成、无 SLO;OCS 劣化时 cube 可降级运行,是否更换由客户决定(客户问答表)文档。固定拓扑多主机节点池中任一节点修复都会关停整个 slice 的 VM 并驱逐全部 Pod(GKE TPU)文档。根因主机的持续非致命错误按 3.5.1 第 2–6 步隔离上报。

3.5.4 Hang#

  • 检测:B1 进度停滞(3.4)用 step 日志的 log-based 计数指标加缺失条件:实测缺失窗口 300 s 时,告警在最后一个 step 后 10 min 52 s 打开,恢复后 3 min 40 s 关闭;作业正常结束后 11 min 24 s 也会打开,须按作业状态门控,只对仍在运行的作业告警 实测。
  • B4 duty_cycle 为 0 持续 5 min:hang 后 5 min 24 s 触发,但首个 step 之前的启动阶段也会误报;加 step 计数门控(过去 60 min 内出现过 step)后启动阶段不再触发 实测。
  • ML Diagnostics:hang 开始后 37 s 产生一条 PERFORMANCE_DEGRADATION,13 个分析器均为 NOT_DETECTED,没有 hang 类事件 实测;可作最早的提示,但不能区分 hang 与降速(2.8)。
  • 定位:多 slice 作业在 slice 0 的 task 0 日志中查 Full error digest 列出的可疑 worker,同一主机在多次 hang 中出现超过 3 次才判为很可能故障(Megascale)文档;SLICE_FAILURE_* 通常是更早故障的后果(类型含芯片驱动错误、软件注入、worker 失联等),报错 worker 未必是根因;先查同一 worker 更早的日志与 K8s 事件,再重试判断是否可复现(slice failure)文档。libtpu 日志见 2.7。
  • 处置:进程仍存活时先存 checkpoint(3.5.1 第 3 步),再按第 4、8 步删除重建并从 checkpoint 恢复;重建前先取走旧 Pod 的 libtpu 日志,同节点下次分配 TPU 时 /tmp/tpu_logs 会被清空(2.7)实测;反复出现的主机按第 2–6 步隔离上报。

3.5.5 NaN 或 SDC 疑似#

  • 检测:loss 突跳、NaN、梯度范数异常;[XLA_SDC_CHECKER] checksum 不一致;hbm_uncorrectable_count、CperHardwareErrorFatal。
  • 定位:硬件故障通常间歇出现、集中在同一芯片;编译器或内核问题在相同输入与编译 flag 下可稳定复现(non-determinism)文档。据此可用最近的健康 checkpoint 和相同种子在另一 slice 重放:复现偏向模型、数据或软件,不复现怀疑硬件,前提是输入管线逐位确定。开 --xla_tpu_enable_sdc_checker=true 做诊断运行(2.4):同一芯片在不同 HLO 报错强烈指向硬件,多芯片在同一 HLO 报错偏向软件(SDC mismatch)文档。
  • 处置:按 loss、梯度范数、评估指标选回滚点;嫌疑主机按 3.5.1 第 2–6 步隔离上报(SDC 类);修复后做 soak 与确定性复核。

3.5.6 节点丢失与 Terminating#

  • 检测:节点 NotReady、allocatable 小于 4、chip_state 出现 state="UNHEALTHY" 序列或 state="HEALTHY" 序列消失(2.6)实测、Pod 长时间 Terminating;下面命令只列出正在删除的 Pod 实测:
bash
kubectl get pods -A --field-selector spec.nodeName=<NODE> \
  -o jsonpath='{range .items[?(@.metadata.deletionTimestamp)]}{.metadata.namespace}/{.metadata.name}{"\n"}{end}'
  • 定位:用节点级 /proc/*/fd 扫描找出 /dev/vfio/* 持有者及其 Pod(2.1、附录 A.1.4);新 Pod 内的 tpu-info -p 看不到其他 Pod 的进程,只在旧 Pod 仍可 exec 时在旧 Pod 内使用。
  • 处置:按 3.5.1 第 5、7 步删除;--force 只删 API 对象,进程可能仍占用 /dev/vfio 致新 Pod 失败(force delete、stuck termination)文档。进程停在 D 状态时按 3.5.1 第 2、6 步隔离上报。
  • 回池:恢复 Ready 后先做 quick 检查(3.5.1 第 9 步)。

3.5.7 回池判定#

层级适用内容时长
quick空闲节点定期抽检、被怀疑的节点TPUMS gemm、hbm(device 0–7,2.2.1 的扫描命令)、gemm_chained(单主机);整 slice 空闲时加 CHS lite单主机 3 项合计约 3 min 估算(35 s + 124 s + 15 s,均为实测),另加安装 16–28 s;CHS lite 9 min 31 s 实测
soak新交付、修复归还、因硬件问题被摘除3.2 的循环,暴露需持续满载才出现的热、电源与链路问题每轮约 1.55 h 估算;轮数 N = ⌈T_req ÷ T_round⌉,T_round 取实测单轮时长(3.2)
  • 三态结论:环境干扰(链路抖动、镜像拉取超时、抢占)作废重排;不达标自动复测一次 quick,仍不达标判坏,只隔离被点名主机并上报。
  • 复发观察:归还后 24 h 内再失败,或 7 d 内第二次因硬件劣化被摘除,转人工保留直至确认物理更换。

3.6 耗时汇总#

下表为验证集群 2x2x2 上的数值;“类型”区分实测、估算与文档,耗时均不含镜像冷拉取(冷拉取单列)。

阶段步骤耗时类型依据
通用Pod 进入 Running(镜像已缓存):单主机 Pod、整 slice Indexed Job1 s、3 s实测附录 A.1.3
通用CHS 测试负载镜像冷拉取(CPU 节点上测得;其余耗时均不含冷拉取)95 s实测附录 A.3.3
交付验收TPUMS 安装,两 Pod 并行45 s实测附录 A.2.1
交付验收TPUMS 单主机项(gemm、hbm 全部 device、主机传输、gemm_chained、gemm_throttling 240 s)约 18 min估算:单项实测累加(hbm 8 device 扫描实测 124 s)2.2、附录 A.2.1
交付验收TPUMS 集合通信 3 项,整 slice112 s实测附录 A.2.1
交付验收CHS lite9 min 31 s实测附录 A.3.1
交付验收CHS standard17 min 58 s实测附录 A.3.1
交付验收XSC 诊断运行(每主机,50 step 链式 matmul 测试程序,含初始化)13–15 s实测附录 A.4.3
交付验收ICI 诊断运行(11 个 flag,iterations 5000)约 22 s(50 step 的 8 MiB psum 测试程序,含初始化);每 step 另加 228 ms实测附录 A.4.2
交付验收单 slice(2x2x2)合计约 42 min估算3.1
返修准入每轮(单主机项 1 h soak、XSC 与 ICI 诊断运行加 CHS standard)约 1.55 h估算3.2
返修准入例:要求不少于 8 h 时 6 轮约 9.3 h估算3.2
起飞前precheck 第 10 步单主机冒烟(v2b)、两主机通信冒烟4.2 s、6.6 s实测附录 A.9.1、A.1.3
起飞前precheck_v2 initContainer;Pod 创建到主容器完成9–10 s;22–24 s实测附录 A.9.1
监控chip_state、infra_health 变化在 Cloud Monitoring 可见256–296 s、350–382 s实测附录 A.6.1
监控计划维护通知进入 maintenance_events 日志8 s 内实测附录 A.7.1
监控15 s 采集器滚动部署;新序列在 GMP 首次可见6 s;p50 1.3 s实测附录 A.5.1
监控libtpu 日志经 sidecar 进入 Cloud Logging(glog 行到可检索)p50 3.8 s、p95 6.9–7.4 s实测附录 A.7.3
监控注入慢节点到带内 15 s 指标可辨识;GKE 60 s 系统指标可辨识40–41 s;约 130 s(样本时间;duty_cycle 另加入库延迟(同一描述符下的 memory_used 实测 1–31 s),约 2.5 min 可查询;计算侧 tensorcore_utilization 按 10% 差值 131 s、25% 差值 431 s,另加 48–78 s 入库延迟)实测附录 A.11.1
监控注入 hang 到 log-based 缺失告警打开;恢复后告警关闭10 min 52 s;3 min 40 s实测附录 A.11.2
监控注入 hang 到 ML Diagnostics 记录 PERFORMANCE_DEGRADATION(无 hang 事件)37 s实测附录 A.8.1
故障处置ICI 断链后在健康 partition 上重建 Slice通常 2 min 内,非 SLO文档3.5.3
故障处置GCE TPU VM 上报后停机修复(All Capacity)VM 先保持 RUNNING 10–12 min,修复 3–14 天或更久文档2.10
故障处置Google 内部修复无统计文档2.10
回池quick:TPUMS 单主机 3 项(hbm 8 device);CHS lite约 3 min 加安装;9 min 31 s实测3.5.7

4 客户问题答复#

按归并需求答复;来源见第 1 章与附录 C.1、C.2,依据与数值见所引章节。

4.1 交付验收与压测#

R-01 DCGM EUD 类深度诊断工具,能否在客户侧运行,耗时多少(RQ-01、02、03、09、10)。

可在客户侧运行。节点池级验收用 CHS 0.3.2:lite 含 tpu-info、GEMM、HBM、主机传输、psum,standard 另加三项带数据校验的压力测试(compute、network 逐位比对,hbm 比对校验和),输出带门限判定的 Bill of Health;逐项深挖与离群定位用 TPUMS。CHS 不打标、不 cordon,隔离由客户自动化执行。2x2x2 上 lite 9 min 31 s(5 项)、standard 17 min 58 s(8 项),全部通过 实测;单 slice(2x2x2)完整验收约 42 min 估算,4x4x4 及以上拓扑需首轮实跑后修订(2.2、2.3、3.1)。

R-02 ICI/DCN 集合通信基线与验收方法(RQ-02、05、06)。

ICI 以 TPUMS all_reduce、all_gather、all_to_all 和 CHS psum 为基线,2x2x2 实测值与门限见 2.2.1、2.3.1;两者负载与带宽公式不同,门限不能互相套用(2.3.4)。TPUMS 不带官方门限,按同拓扑机群基线判定。DCN 需多 slice,TPUMS 提供 dcn_all_reduce、dcn_all_to_all 文档,本集群未实测。连通性检查并入起飞前检查(2.9)。

R-03 同步脉冲(di/dt)压测(RQ-04)。

TPUMS 暂无脉冲模式,上游 #145 仍为 open。实验脚本在单主机 8 device 上(2 个节点分别运行)全部通过、空闲间隙未见降频 实测,只作参考,不作验收门限(2.2.4)。

4.2 SDC#

R-04 SDC 检测机制、工具与推荐时长,逐位一致性边界(RQ-07、08)。

硬件层检测由 Google 侧执行。客户可控的是 XSC 与公开 playbook 中的 7 个 xla_tpu_ici_sdc_test_* flag,只用于诊断运行,以及 CHS standard 三项 stress 和 TPUMS gemm_chained 的离线比对(2.4)。libtpu 遇未知 flag 启动即退出,只使用 2.4 列出的 flag。Google 未公开 SDC 筛查时长。本集群实测:XSC 使 step 变为 2.08 倍;ici-sdc-test 诊断组合 iterations=5000 时每 step 增加 228 ms;同一 jax、libtpu 版本下,单主机 8 device 程序在同节点与另一节点上重跑结果逐位一致;跨 slice、跨物理位置未实测;libtpu 0.0.50.1 升到 0.0.51 输出相同但 HLO 不同,跨版本不作保证 实测(2.4、附录 A.4.4)。

4.3 起飞前检查#

R-05 对标客户现有 GPU 预检脚本的起飞前检查(RQ-11、12、13、14)。

precheck_v2 以 initContainer 运行单主机检查,常见 GPU 预检 9 项逐项映射,无等价项已标明;退出码 0 为通过,非 0 为首个失败项的码,建议只对硬件类失败屏蔽节点(2.9、3.3)。多主机通信就绪在主容器入口检查,2x2x2 上 6.6 s;initContainer 实测 9–10 s,Pod 创建到主容器完成 22–24 s 实测。版本一致性:libtpu 与 vfio-pci 驱动解耦,随镜像钉版本,预检在各 worker 打印版本与 libtpu.so sha256(FINGERPRINT 行),由编排侧跨 worker 比对,除内核外须一致。

4.4 监控指标#

R-06 K8s/TPU 监控组件、tpu-exporter 的对应物、接入客户 Prometheus(RQ-15、17、22、24)。

tpu-exporter 的对应物是 Cloud Monitoring 系统指标加 tpu-device-plugin 的 :2112 端点,libtpu 运行时指标在 :8431(2.5)。客户 Prometheus 或 Grafana 直接查询 Cloud Monitoring 的 Prometheus 兼容 API,或部署 stackdriver_exporter(2.6.3)。15 s 采集器为可选增强:验证集群上命名空间化部署 6 s 完成,:2113 输出 13 个指标名,GMP 样本间隔 15.0 s,样本从抓取到可查询 p50 1.3 s,需 nodes 只读 ClusterRole 实测(2.5、附录 A.5.1)。

R-07 16 项 DCGM 指标的 TPU 对应关系(RQ-18、19、20、21)。

没有一一对应的指标:降频只能用 core_throttling_indicator 间接判断,PCIe 吞吐与链路宽度未公开,ECC 只公开不可纠正计数,行重映射未公开,芯片能否继续使用看 infra_health 与 chip_state(2.6.1)。降频、ECC 等指标属 instance/tpu/accelerator/*(BETA),验证集群 10-29 后中断、原因未确认,需配数据缺失告警(2.6、3.4)实测。缺口按 feature request 跟进。

R-08 租户可见的 ICI/DCN 网络指标与“RDMA 监控”等价方案(RQ-16、29)。

租户可见 ici_link_health、ici_link_flaps、ICI 包数与 NIC 丢包,链路级细节经支持渠道获取;DCN 时延指标只在多 slice 时存在。上述 ICI 与 NIC 指标属 instance/tpu/accelerator/* 与 tpu/network/*(BETA),验证集群 10-29 后中断、原因未确认,需配数据缺失告警;其中 accelerator/*(含 ICI 指标)在 TPU 负载期间同样无数据 实测。“RDMA 监控”的对应做法是 ICI 健康与抖动加 NIC 丢包告警(2.6.2、3.4.3)。

4.5 告警#

R-09 硬件告警规则与 fatal/非 fatal 分级,带外能力边界(RQ-23、27、28、33)。

告警目录见 3.4.3,分级与 2.7 一致:致命错误由平台自动下线机器或驱逐 workload,非致命错误影响负载时经报修接口处理。带外健康指标入库延迟 256–382 s,窗口不少于 10 min(2.6)。租户可用的带外能力是 Cloud Monitoring 指标与报修接口,公开文档未提供 BMC/IPMI 访问 未验证。

4.6 日志与错误分级#

R-11 错误上报渠道、日志位置、错误分级、日志盘控制(RQ-30、31、32、38)。

TPU 没有 XID 式公开错误码表。libtpu 日志由 sidecar-log-collector 送入 Cloud Logging,severity 恒为 INFO,按文本级别过滤;分级表见 2.7。TPU_LOG_DIR(/tmp/tpu_logs/<容器名>)在节点 tmpfs 上,Pod 删除后保留、同节点下一次 TPU 分配时清空,sidecar 只上传每个容器第一个 libtpu 进程的日志,需保留的内容从 Cloud Logging 取 实测(2.7)。容器日志轮转由 containerLogMaxSize(默认 10Mi)与 containerLogMaxFiles(默认 5)控制,可经节点系统配置调整(2.7)。

4.7 故障信号与定位#

R-10 可被 operator 消费的故障信号接口(RQ-25、26、39)。

节点级信号为 allocatable 下降、NotReady、CperHardwareErrorFatal 与带外 infra_health、chip_state。Dynamic Slicing 集群中每层 partition 带状态标签,节点与 2x2x1 partition 一一对应,可作为隔离与屏蔽列表的单位,operator 可 watch 节点的 partition 状态标签,或轮询 Cloud Monitoring 的 kubernetes.io/accelerator/partition/state 指标(2.1)。验证环境未启用 Dynamic Slicing,此部分为文档结论。

R-12 常见故障类型与诊断流程(RQ-34、35、36、37)。

Google 给出的常见故障顺序为 Host 至 TPU tray 链路或 tray、ICI/OCS、DCN、host、电源,MTBF 需先经安全政策评估,目前未提供。runbook 按症状组织:慢但指标正常、ICI 链路错误、Hang、NaN 或 SDC、节点丢失与 Terminating(3.5)。单 slice 注入实验中,同步训练各 worker 的步时相同,不能单凭步时定位慢节点;主机侧慢节点表现为 duty_cycle 最低,计算侧慢节点表现为 TensorCore 利用率最高,两者的 hlo_execution_timing 均最低,带内 15 s 指标 40–41 s 可辨识;ML Diagnostics 未对慢节点报事件;hang 由进度缺失告警检出(实测缺失窗口 300 s 时为最后一步后 10 min 52 s;按 B1 的 15 min 窗口约 21 min 估算),该告警需按作业状态门控 实测(3.4、3.5.2、3.5.4、附录 A.11)。嫌疑节点离线复测确认。

4.8 上报、隔离与恢复#

R-13 故障节点的上报、隔离与报修(RQ-40、41、43)。

平台检出的致命错误由 GCP 自动处理。平台未检出但影响作业的问题:GKE 管理的 TPU 节点先隔离(粒度为节点,即一个 2x2x1 partition),再开支持工单并附证据清单,不对其 VM 调用 report-host-as-faulty;GKE 的 cloud.google.com/fault-behavior 标签流程文档只列 GPU 机型,TPU 需 Google 确认后再接入自动化;All Capacity 模式的 TPU VM 按 TPU 文档上报,原主机停机修复 3–14 天或更久。GKE 标签通道的主动上报可能按 reservation 限流,且有成本,只用于疑难问题(2.10)。

R-14 局部故障降级、恢复时间、checkpoint 恢复与自动踢除(RQ-42、45、46)。

ICI 断链时 Slice 变为 FAILED,在健康 partition 上重建并从 checkpoint 恢复,Google 答复通常 2 min 内,非 SLO;OCS 劣化时 cube 可降级运行(3.5.3)。Hang 与慢节点删除作业全部 Pod 后重建并恢复;自动踢除以节点或 partition 健康态为触发,统计嫌疑须有第二信号佐证(3.5.1、3.5.4)。具体编排属调度范畴,本文不展开。

4.9 回归准入#

R-15 修复后回归准入(RQ-41、44)。

GCP 修复流程归还前会跑 burn-in,修复时长没有统计。客户“修复后长时间深度压测才回池”的要求可落成循环:轮数 N = ⌈T_req ÷ T_round⌉,每轮为 TPUMS 单主机项、XSC 与 ICI 诊断运行加 CHS standard,T_round 约 1.55 h;例如要求不少于 8 h 时 N = 6,总计约 9.3 h 估算(2x2x2;各单项实测,整轮未连续运行);不能长时间占用整 slice 时只循环单主机项,最后跑一次 CHS standard。门控用客户自有节点标签 tpu-health 加训练 Pod 的 nodeAffinity,不用污点或 cordon,否则 CHS 无法在该节点运行;节点重建后标签丢失,需重新检查后打标(3.2)。

附录

以下为附录:A 实机验证完整过程、B 与上一版相比的主要更正、C 来源索引、D 已知限制与未验证项。章节编号与正文交叉引用一致。

A 实机验证完整过程#

附录 A 的每个实验是一张可折叠卡片,标题行给出服务的需求、实测耗时与证据标记。

本附录记录 2026-11-03 在验证集群(GKE 1.36.4-gke.2326000,tpu7x 2x2x2 节点池,2 节点 × 4 芯片)上完成的实验,正文 实测 数据均出自这里。公共初始化见 A.0,各实验按目的、前置、命令、裁剪输出、实测耗时、判定标准、注意事项组织。安全约束:所有对象建在自有命名空间并在实验后删除;只使用没有其他 Pod 申请 google.com/tpu 的空闲节点;不 cordon、drain、taint、label 节点,不打 cloud.google.com/fault-behavior 标签,report-host-as-faulty、reset、delete 只查看 --help。“复核实验”指发布前在同一验证集群上按本文命令原样复跑的验证(2026-11-03)。

A.0 环境与公共初始化#

A.0.1

A.0.1 验证环境#

公共初始化被其他演示的“前置”引用
占位符 或 项目验证集群取值
<PROJECT>Google 测试项目(不公开)
<LOCATION>us-central1-c(ML Diagnostics 使用 region us-central1)
<CLUSTER>验证集群名(已隐去),GKE 1.36.4-gke.2326000
<NODE>验证集群的两个 TPU 节点,文中记作 <node-a>、<node-b>(简称 node-a、node-b;单机 holder Pod 为 sh-node-a、sh-node-b)
TPU 节点池2 × tpu7x-standard-4t,拓扑 2x2x2,一个多机 slice
节点软件COS 129,kernel 6.12.110+,containerd 2.2.7
节点资源(每节点)google.com/tpu capacity = allocatable = 4,taint google.com/tpu=present:NoSchedule,224 vCPU,约 944 GiB 内存
JobSet未安装,多机实验使用 Indexed Job + headless Service
A.0.2

A.0.2 凭据与命名空间#

公共初始化被其他演示的“前置”引用

使用独立 kubeconfig。使用 TPU 前确认目标节点上没有其他 Running 或 Pending 的 Pod 申请 google.com/tpu。

bash
export PROJECT=<PROJECT> LOCATION=<LOCATION> CLUSTER=<CLUSTER> NS=tpu-verify
export KUBECONFIG=$PWD/kubeconfig
gcloud container clusters get-credentials $CLUSTER --location $LOCATION --project $PROJECT
kubectl create namespace $NS --dry-run=client -o yaml | kubectl apply -f -
# 节点名与 VM instance id(查询 gce_instance 指标时用)
kubectl get nodes -l cloud.google.com/gke-tpu-accelerator=tpu7x \
  -o custom-columns='NAME:.metadata.name,INSTANCE_ID:.metadata.annotations.container\.googleapis\.com/instance_id'
# 安全检查:列出申请 google.com/tpu 且处于 Running/Pending 的 Pod
kubectl get pods -A -o json | python3 -c 'import json,sys;[print(p["metadata"]["namespace"],p["metadata"]["name"],p["status"]["phase"],p["spec"].get("nodeName")) for p in json.load(sys.stdin)["items"] if "google.com/tpu" in json.dumps(p["spec"]["containers"]) and p["status"]["phase"] in ("Running","Pending")]'
A.0.3

A.0.3 基础镜像与 GKE 注入的 TPU 环境变量#

公共初始化被其他演示的“前置”引用实测

基础镜像 us-docker.pkg.dev/cloud-tpu-images/jax-ai-image/tpu:latest(digest sha256:d3dbf1a00bf1c5b61bbd1d7456cca3ec090fd3200536a4b61a8fbd3de8ef23f3):Debian 12,Python 3.12.12,jax/jaxlib 0.9.0,libtpu 0.0.34,不含 tpu-info;也是 TPUMS 的默认镜像。节点已缓存时从调度到容器运行 1 s,冷拉取未测量 实测。GKE 向每个申请 TPU 的容器注入 实测:

bash
TPU_ACCELERATOR_TYPE=tpu7x-16  TPU_TOPOLOGY=2x2x2  TPU_TOPOLOGY_WRAP=false,false,false  TPU_TOPOLOGY_ALT=false
TPU_CHIPS_PER_HOST_BOUNDS=2,2,1  TPU_HOST_BOUNDS=1,1,2  TPU_SKIP_MDS_QUERY=true
TPU_WORKER_ID=0  TPU_WORKER_HOSTNAMES=localhost  TPU_PROCESS_ADDRESSES=localhost:8471  TPU_PROCESS_PORT=8471
TPU_RUNTIME_METRICS_PORTS=8431,8432,8433,8434,8435,8436,8437,8438  TPU_LOG_DIR=/tmp/tpu_logs/<容器名>
A.0.4

A.0.4 单机模式:在多机 slice 的一个节点上运行#

公共初始化被其他演示的“前置”引用
环境变量结果
仅 GKE 注入值(TPU_HOST_BOUNDS=1,1,2)约 3 s 后失败:TPU initialization failed: Invalid --deepsea_slice_builder_worker_addresses specified. Expected 2 worker addresses, got 1.
只覆盖 TPU_HOST_BOUNDS=1,1,1可用:8 个 JAX device(4 芯片 × 2 TensorCore),backend 初始化 2.8 s;本机 4 芯片间 ICI 可用(为 2x2x1 子 slice 运行 SliceBuilder)
CHS tpu-node-local-init 组合(TPU_HOST_BOUNDS=1,1,1 与 localhost worker 变量,加 --deepsea_hal_test_skip_slicebuilder=true --deepsea_hal_test_allow_multichip_skip_slicebuilder=true --xla_tpu_use_enhanced_launch_barrier=false)libtpu 0.0.34:Unknown command line flag;libtpu 0.0.50:可用但 Skipping slicebuilder for all chips within machine, ICI will not work.,只能跑不用 ICI 的负载,与 TPUMS --standalone_host_init 相同

单机 holder Pod 申请整节点 4 芯片并 sleep infinity,测试用 kubectl exec 执行;两个节点可各跑一个。

yaml
# sed "s/__NODE__/<NODE>/; s/__NAME__/sh-node-a/" manifest_singlehost_pod.yaml | kubectl -n $NS apply -f -
apiVersion: v1
kind: Pod
metadata: {name: __NAME__, labels: {app: tpu-singlehost}}
spec:
  restartPolicy: Never
  terminationGracePeriodSeconds: 5
  nodeSelector:
    cloud.google.com/gke-tpu-accelerator: tpu7x
    cloud.google.com/gke-tpu-topology: 2x2x2
    kubernetes.io/hostname: __NODE__
  tolerations: [{key: google.com/tpu, operator: Exists, effect: NoSchedule}]
  containers:
  - name: main
    image: us-docker.pkg.dev/cloud-tpu-images/jax-ai-image/tpu:latest
    imagePullPolicy: IfNotPresent
    command: ["bash", "-c", "sleep infinity"]
    resources: {requests: {google.com/tpu: "4"}, limits: {google.com/tpu: "4"}}
A.0.5

A.0.5 多机模式:2 个 Pod 覆盖整个 2x2x2 slice#

公共初始化被其他演示的“前置”引用实测

清单中不写任何 TPU 环境变量 实测。

yaml
apiVersion: v1
kind: Service
metadata: {name: tpu-mh-svc}
spec: {clusterIP: None, selector: {job-name: tpu-mh}}
yaml
apiVersion: batch/v1
kind: Job
metadata: {name: tpu-mh}
spec:
  backoffLimit: 0
  completionMode: Indexed
  completions: 2
  parallelism: 2
  template:
    spec:
      subdomain: tpu-mh-svc
      restartPolicy: Never
      terminationGracePeriodSeconds: 5
      nodeSelector: {cloud.google.com/gke-tpu-accelerator: tpu7x, cloud.google.com/gke-tpu-topology: 2x2x2}
      tolerations: [{key: google.com/tpu, operator: Exists, effect: NoSchedule}]
      containers:
      - name: main
        image: us-docker.pkg.dev/cloud-tpu-images/jax-ai-image/tpu:latest
        imagePullPolicy: IfNotPresent
        ports: [{containerPort: 8471}, {containerPort: 8476}, {containerPort: 8431}]   # SliceBuilder、jax 协调器、runtime metrics
        command: ["bash", "-c", "env | grep -E '^(TPU_|JOB_COMPLETION_INDEX|HOSTNAME)' | sort; sleep infinity"]
        resources: {requests: {google.com/tpu: "4"}, limits: {google.com/tpu: "4"}}

多机 JAX 要求每个 host 一个进程且同时启动,用 run_mh.sh 在两个 Pod 中并发执行同一命令:

bash
# run_mh.sh <outdir> <name> '<command>'
OUT=$1; NAME=$2; CMD=$3
mapfile -t PODS < <(kubectl -n $NS get pods -l job-name=tpu-mh -o jsonpath='{range .items[*]}{.metadata.annotations.batch\.kubernetes\.io/job-completion-index}{" "}{.metadata.name}{"\n"}{end}' | sort -n | awk '{print $2}')
for i in 0 1; do ( kubectl -n $NS exec ${PODS[$i]} -- bash -c "$CMD; echo rc=\$?" > $OUT/${NAME}_p$i.log 2>&1 ) & done
wait
  • 两个 Pod 各落一个节点,kubectl apply 后 3 s Running;删除 Job 和 Service 后 8 s 内消失 实测。
  • GKE 按 Pod 注入 TPU_WORKER_ID=<completion index>、TPU_WORKER_HOSTNAMES=tpu-mh-0.tpu-mh-svc,tpu-mh-1.tpu-mh-svc、TPU_PROCESS_ADDRESSES=tpu-mh-0.tpu-mh-svc:8471,tpu-mh-1.tpu-mh-svc:8471,其余同 A.0.3 实测。
A.0.6

A.0.6 主机检查 Pod(特权、hostPID、hostNetwork,不申请 TPU)#

公共初始化被其他演示的“前置”引用实测

只容忍 TPU taint,不申请 google.com/tpu,可与训练任务并行。首次 Ready 4 s、安装工具 9 s;后续各轮 Ready 加装工具 6 到 14 s 实测。

yaml
apiVersion: v1
kind: Pod
metadata: {name: host-inspect}
spec:
  nodeSelector: {kubernetes.io/hostname: <NODE>}
  tolerations: [{key: google.com/tpu, operator: Exists, effect: NoSchedule}]
  hostPID: true
  hostNetwork: true
  dnsPolicy: ClusterFirstWithHostNet
  restartPolicy: Never
  activeDeadlineSeconds: 2400        # 40 min 后自动结束
  containers:
  - name: inspect
    image: debian:bookworm-slim
    command: ["/bin/bash", "-c", "apt-get update -qq && DEBIAN_FRONTEND=noninteractive apt-get install -y -qq ethtool pciutils iproute2 procps kmod >/tmp/apt.log 2>&1; touch /tmp/ready; sleep 2400"]
    securityContext: {privileged: true}
    resources: {requests: {cpu: 100m, memory: 128Mi}, limits: {cpu: "1", memory: 512Mi}}
    volumeMounts: [{name: host, mountPath: /host, readOnly: true}]
  volumes: [{name: host, hostPath: {path: /, type: Directory}}]

用法:kubectl apply 后等待 Ready 和 /tmp/ready,kubectl exec -i host-inspect -- bash -s < inspect.sh 执行检查脚本,结束后删除 Pod。

A.0.7

A.0.7 TPUMS 安装#

公共初始化被其他演示的“前置”引用实测

TPUMS(accelerator-microbenchmarks,tpums CLI)没有 PyPI 包,在 TPU Pod 内从 GitHub 安装。验证使用 commit 027cd628b15e5ede2d0057e0d3c0187b954f42ad(pyproject version = "2.0");仓库只有 v1.1-legacy 一个 tag,1.1.1 是 CHS 自带镜像的 tag(见附录 A.3.3)实测。

bash
git clone https://github.com/AI-Hypercomputer/accelerator-microbenchmarks.git /tmp/tpums
cd /tmp/tpums && git checkout 027cd628b15e5ede2d0057e0d3c0187b954f42ad
pip install -e .
tpums platform describe      # 单机模式先 export TPU_HOST_BOUNDS=1,1,1
tpums benchmark list
  • 耗时:clone 0.5 到 0.7 s,pip install -e . 15.6 s 和 27.1 s 实测。
  • 安装后 jax/jaxlib 0.12.0,libtpu 0.0.50,tpu-info 被固定为 0.7.1(需要 0.14.2 时随后 pip install -U tpu-info)实测。
  • tpums benchmark list 只列出 all_gather, all_reduce, all_to_all, dcn_all_reduce, dcn_all_to_all, device_to_device, device_to_host, gemm, hbm, host_to_device;gemm_throttling、gemm_chained、reduce_scatter 等实验性任务只能用 tpums benchmark run-config <yaml> 实测。
A.0.8

A.0.8 Cloud Monitoring 与 Cloud Logging 访问#

公共初始化被其他演示的“前置”引用实测
bash
export TOKEN=$(gcloud auth application-default print-access-token)
H=(-H "Authorization: Bearer $TOKEN" -H "x-goog-user-project: $PROJECT")
curl -s "${H[@]}" "https://monitoring.googleapis.com/v3/projects/$PROJECT/metricDescriptors" --get \
  --data-urlencode 'filter=metric.type=starts_with("compute.googleapis.com/instance/tpu")'
# PromQL
curl -s "${H[@]}" "https://monitoring.googleapis.com/v1/projects/$PROJECT/location/global/prometheus/api/v1/query" \
  --data-urlencode "query=kubernetes_io:node_accelerator_tensorcore_utilization{monitored_resource=\"k8s_node\",cluster_name=\"$CLUSTER\"}"
# MQL:POST https://monitoring.googleapis.com/v3/projects/$PROJECT/timeSeries:query,body {"query": "..."}
# Logging:先列 log name,再按 logName 或 resource 加时间窗查询
gcloud logging logs list --project $PROJECT | sed 's#.*/logs/##'
gcloud logging read "$FILTER" --project $PROJECT --limit 50 --format=json
  • PromQL 命名:compute.googleapis.com/instance/tpu/infra_health 写作 compute_googleapis_com:instance_tpu_infra_health,kubernetes.io/node/accelerator/tensorcore_utilization 写作 kubernetes_io:node_accelerator_tensorcore_utilization,并加 monitored_resource 标签 实测。
  • 验证用工作站上用户凭据 token 调 REST 返回 401 ACCESS_TOKEN_TYPE_UNSUPPORTED,ADC token 可用 实测。
  • metricDescriptors 过滤用 starts_with(...);has_substring("tpu") 会匹配 output_* 等无关指标 实测。
A.0.9

A.0.9 清理#

公共初始化被其他演示的“前置”引用
bash
kubectl -n $NS delete job,svc,pod --all --wait=true
kubectl delete namespace $NS
A.0.10

A.0.10 libtpu flag 设置#

公共初始化被其他演示的“前置”引用实测

单机实验在 A.0.4 的 holder Pod 中使用三套 Python 环境,覆盖三个 libtpu 版本 实测:

Pythonjax、jaxliblibtpu安装方式安装耗时
/opt/venv/bin/python3(镜像默认)0.9.00.0.34jax-ai-image tpu:latest—
/tmp/v050/bin/python30.12.00.0.50.1python3 -m venv /tmp/v050 && /tmp/v050/bin/pip install "jax[tpu]==0.12.0"(与 TPUMS 固定版本相同)15 到 36 s
/tmp/v051/bin/python30.12.00.0.51同上,再 pip install --no-deps libtpu==0.0.51约 30 s
bash
# 传递 flag:每个用例一个新进程;单机模式始终加 TPU_HOST_BOUNDS=1,1,1
LIBTPU_INIT_ARGS="--flag=value ..." TPU_HOST_BOUNDS=1,1,1 python3 script.py
# 上线前在目标镜像上验证 flag 是否被接受
LIBTPU_INIT_ARGS="$FLAGS" TPU_HOST_BOUNDS=1,1,1 python3 -c 'import jax; print(jax.devices())'; echo rc=$?
# 读取诊断日志行:覆盖容器内所有 libtpu 进程的日志文件(默认 TPU_STDERR_LOG_LEVEL 下这些行不进 stderr)
kubectl -n $NS exec <POD> -- bash -c 'grep -h "IciSdcTest\|XLA_SDC_CHECKER\|HLO is instrumented\|ICI transfer wait\|Wait timeout on sflag" $TPU_LOG_DIR/tpu_driver.*.log.INFO.*'
  • 任何未知 flag 在 TPU 初始化前中止进程:0.4 s 内 rc=1,stderr 每个未知 flag 一行 ERROR: Unknown command line flag '<name>',不回退到 CPU;可接受的 flag 启动耗时 5.1 到 5.5 s(见附录 A.4.1)实测。
  • JAX 会自行在 LIBTPU_INIT_ARGS 后追加 --xla_tpu_use_enhanced_launch_barrier=true;libtpu 实际收到的完整参数会回显在 tpu_driver.INFO 中 实测。
  • TPUMS 用 op_flags.yaml 覆盖 LIBTPU_INIT_ARGS,在 TPUMS 中改 flag 需使用 --xla_flags_file_path,做 flag 实验时直接用 JAX(见附录 A.2.1)实测。
  • 不改环境变量、只对单个编译开启 XSC:jax.jit(f).lower(x).compile(compiler_options={'xla_tpu_enable_sdc_checker': True}),jax 0.9.0 和 0.12.0 均可用(见附录 A.4.3)实测。
  • 同一个 Pod 内两个进程不能同时使用 TPU,用例需串行执行 实测。
  • 从 CI 或脚本 shell 用 kubectl exec ... & 放到后台的进程会随 shell 退出而终止;长时间用例在 Pod 内用 nohup ... > /tmp/x.log 2>&1 < /dev/null & 启动,再用 kubectl cp 取回日志 实测。
  • libtpu 0.0.34 不产生固件性能状态 trace 事件;0.0.50(TPUMS 环境)与 0.0.50.1 均可读取(见附录 A.2.4)实测。
A.0.11

A.0.11 CHS 初始化#

公共初始化被其他演示的“前置”引用实测

CHS 0.3.2 的 README 用法是在工作站上 docker run ... chs:latest(本文固定为 chs:0.3.2)并挂载 ~/.kube 与 gcloud 凭据。验证环境没有 docker,CHS 以长期运行的 runner Pod 形式跑在 CPU 节点上,与 README 用法的差异见附录 A.3.2 实测。

最小权限 RBAC(根据 CHS 0.3.2 实际调用的 API 确定,比镜像自带 Helm chart 授予的集群级 create/delete 窄):

范围资源动作用途
ClusterRolenodesget、list、watch节点发现
ClusterRolepods(所有命名空间)get、list、watch检查节点是否忙
ClusterRolenamespacesget、list、create创建 chs 命名空间,不授予 delete
ClusterRoleaccelerator.gke.io slicesget、listSlice CRD 探测;返回 403 而非 404 会中止运行
ClusterRolenetworking.gke.io networksget、list网络发现(失败只告警)
Role(命名空间 chs)pods、pods/log、services、configmaps、secrets;batch jobs(get 到 delete);resource.nvidia.com computedomains(get、list、delete)见资源列测试 Job、worker Service、日志、清理

manifest_chs_runner.yaml 共 7 个对象:ServiceAccount、ClusterRole、ClusterRoleBinding、Namespace chs(Role 与 RoleBinding 所在,须先于二者创建)、Role、RoleBinding、runner Pod。

yaml
# ServiceAccount(RoleBinding、ClusterRoleBinding 绑定到它)
apiVersion: v1
kind: ServiceAccount
metadata: {name: chs-runner, namespace: tpu-verify}
yaml
# runner Pod(ServiceAccount chs-runner 绑定上表 ClusterRole 与 chs 命名空间内的 Role)
apiVersion: v1
kind: Pod
metadata: {name: chs-runner, namespace: tpu-verify}
spec:
  serviceAccountName: chs-runner
  restartPolicy: Never
  terminationGracePeriodSeconds: 5      # sleep infinity 作为 PID 1 不响应 SIGTERM,避免删除时等满默认 30 s
  nodeSelector: {cloud.google.com/gke-nodepool: <CPU_NODE_POOL>}
  containers:
  - name: chs
    image: us-docker.pkg.dev/gce-ai-infra/chs/chs:0.3.2
    command: ["bash", "-c", "sleep infinity"]                # 镜像 entrypoint 为 chs
    resources: {requests: {cpu: "1", memory: 2Gi}}
    volumeMounts: [{name: chs-state, mountPath: /workspace/.local/share}]   # CHS 状态:存储配置、workspace
  volumes: [{name: chs-state, emptyDir: {}}]

集群内运行必需的 kubeconfig(仍以 Pod 的 ServiceAccount 身份认证;需设置 current-context,建议 context 名采用 GKE 格式,CHS 取最后一段为集群名;原因见附录 A.3.2):

yaml
# runner Pod 内 /workspace/.kube/config
apiVersion: v1
kind: Config
clusters:
- name: gke_<PROJECT>_<LOCATION>_<CLUSTER>
  cluster:
    server: https://kubernetes.default.svc
    certificate-authority: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
users:
- name: chs-runner
  user: {tokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token}
contexts:
- name: gke_<PROJECT>_<LOCATION>_<CLUSTER>
  context: {cluster: gke_<PROJECT>_<LOCATION>_<CLUSTER>, user: chs-runner, namespace: chs}
current-context: gke_<PROJECT>_<LOCATION>_<CLUSTER>
bash
kubectl apply -f manifest_chs_runner.yaml   # 对象自带 namespace(SA、Pod 在 $NS,Role、RoleBinding 在 chs),不要加 -n
kubectl -n $NS wait --for=condition=Ready pod/chs-runner --timeout=300s
kubectl -n $NS exec chs-runner -- mkdir -p /workspace/.kube
kubectl cp chs_kubeconfig.yaml $NS/chs-runner:/workspace/.kube/config   # 上面的 kubeconfig
kubectl -n $NS exec chs-runner -- kubectl auth whoami             # system:serviceaccount:tpu-verify:chs-runner
gcloud storage buckets create gs://<BUCKET> --project $PROJECT --location <REGION> --uniform-bucket-level-access
kubectl -n $NS exec chs-runner -- chs configure storage gcs <BUCKET>
# 清理(先拷出结果)
gcloud storage cp -r gs://<BUCKET>/* ./chs_results/
kubectl -n chs get jobs        # 只剩自己 run ID 的 Job 时才删除命名空间;有他人 Job 时只执行 chs cancel <完整 run ID> -y
kubectl delete namespace chs; kubectl -n $NS delete pod chs-runner
kubectl delete clusterrolebinding chs-runner; kubectl delete clusterrole chs-runner
kubectl -n $NS delete serviceaccount chs-runner
gcloud storage rm -r gs://<BUCKET>
  • runner Pod Ready 5 s(镜像已缓存);chs configure storage gcs 3 s;CHS 工作负载镜像 accelerator-microbenchmarks:1.1.1 在 CPU 节点上冷拉取实测 95 s(TPU 节点未单测);首个 Job tpu-info 的 activeDeadlineSeconds 为 120 s,拉取时间计入其中,新节点上先预拉镜像 实测。
  • CHS 通过 metadata server 使用节点 SA 访问 GCS;输出为 gs://<BUCKET>/bills_of_health/<workspace>.{html,json} 和 gs://<BUCKET>/workspaces/<workspace>.tar.gz,<workspace> 为 <YYYYMMDD-HHMMSS>_<run-id> 实测。启用 Workload Identity Federation for GKE 的节点池上,runner Pod 以其 KSA 身份访问 GCS,需给该身份授予桶的 Storage Object Admin(Workload Identity)文档。
  • 一次只运行一个套件,运行前确认整个 TPU 节点池空闲;chs 进程须全程存活 实测。
  • 清理前确认 chs 命名空间中只有自己的 Job;只用 chs cancel <完整 run ID> -y 取消自己的运行 文档。
A.0.12

A.0.12 GKE 注入的环境变量与挂载来源#

公共初始化被其他演示的“前置”引用实测
变量 / 挂载来源2x2x2 上的值
TPU_WORKER_ID、TPU_LOG_DIR控制面准入写入 Pod spec 的 env(kubectl get pod -o yaml 可见,Job 模板中没有)completion index(裸 Pod 为 0);/tmp/tpu_logs/<容器名> 实测
TPU_WORKER_HOSTNAMES、TPU_PROCESS_ADDRESSES控制面准入写入 Pod spec,按 Job 与 subdomain 生成<job>-<i>.<svc> 列表,端口 8471;裸 Pod 为 localhost 实测
TPU_TOPOLOGY、TPU_ACCELERATOR_TYPE、TPU_HOST_BOUNDS、TPU_CHIPS_PER_HOST_BOUNDS、TPU_SKIP_MDS_QUERY、TPU_RUNTIME_METRICS_PORTSdevice plugin Allocate2x2x2、tpu7x-16、1,1,2、2,2,1、true、8431..8438 实测
/dev/vfio/*、/var/run/tpu-plugin(只读,含 vbar.sock)、/tmp/tpu_logsdevice plugin Allocate8 个 vfio 组(0–7)加 vfio;各芯片 function .0 对应的组号因节点而异 实测

A.1 节点与芯片健康(对应 2.1)#

A.1.1

A.1.1 集群与 TPU 节点环境盘点#

服务需求R-10实测耗时整套只读命令约 60 s实测

服务需求:R-10(见第 1 章);正文:2.1。

目的:只读记录 GKE 在 tpu7x-standard-4t 节点池上部署的内容:版本、节点标签、annotation、taint、condition,tpu-device-plugin DaemonSet,TPU Pod 被注入的内容,启用的监控与日志组件。

前置:A.0.2。

命令:

bash
gcloud container clusters describe $CLUSTER --location $LOCATION --project $PROJECT \
  --format="yaml(currentMasterVersion,releaseChannel,monitoringConfig,loggingConfig)"
gcloud container node-pools describe <NODE_POOL> --cluster $CLUSTER --location $LOCATION --project $PROJECT \
  --format="yaml(config.machineType,placementPolicy,upgradeSettings,management,config.resourceLabels)"
kubectl get nodes -l cloud.google.com/gke-tpu-accelerator=tpu7x -o json | jq -r '.items[] |
  .metadata.name, (.spec.taints|tostring), (.status.allocatable|tostring), ([.status.conditions[].type]|join(","))'
kubectl get node <NODE> -o jsonpath='{.metadata.annotations.node\.gke\.io/upcoming-maintenance}'
kubectl -n kube-system get ds tpu-device-plugin -o yaml
kubectl -n kube-system get pods -l k8s-app=tpu-device-plugin -o wide
kubectl get mutatingwebhookconfigurations; kubectl get crd
gcloud compute instances describe <NODE> --zone $LOCATION --project $PROJECT --format="json(id,name,status,machineType.basename(),labels.goog-k8s-node-pool-name,resourceStatus.upcomingMaintenance)"   # instance id;COS 版本见下行
gcloud compute disks describe <NODE> --zone $LOCATION --project $PROJECT --format='value(sourceImage)'   # 启动盘镜像名含 COS 版本,例如 ...-cos-129-19506-505-8-...
# 不要导出或粘贴完整的 instance JSON:metadata 中的 kube-env 含凭据

盘点时以 --format=json 采集后汇总;上面的投影写法为等价只读命令,未逐字运行;下面的输出为汇总而非原样。

裁剪输出(2026-11-03 09:36 到 09:40 UTC):

输出
currentMasterVersion: 1.36.4-gke.2326000        # releaseChannel REGULAR
monitoringConfig.enableComponents: [SYSTEM_COMPONENTS, STORAGE, HPA, POD, DAEMONSET, DEPLOYMENT, STATEFULSET, CADVISOR, KUBELET, DCGM, JOBSET]
managedPrometheus: true
loggingConfig.enableComponents: [SYSTEM_COMPONENTS, WORKLOADS]
nodepool: {machineType: tpu7x-standard-4t, nodes: 2, tpuTopology: 2x2x2, upgradeSettings: {strategy: SURGE, maxSurge: 1},
           autoRepair: true, autoUpgrade: true, resourceLabels: {goog-gke-tpu-node-pool-type: single-host}}
taints: google.com/tpu=present:NoSchedule
allocatable: {google.com/tpu: 4, cpu: 223370m}
node.gke.io/upcoming-maintenance: '{"type":"SCHEDULED","maintenance_status":"PENDING","window_start_time":"2026-11-09T20:00:00+00:00",...,"can_reschedule":true}'
conditions: 26 种,含 NPD 的 KernelDeadlock、ReadOnlyRootFileSystem、CperHardwareErrorFatal 等;无 TPU 专用 condition
tpu-device-plugin pods: 每个 TPU 节点 READY 3/3 Running
tpu-device-plugin DS containers:
  tpu-device-plugin: 1.36.14-gke.1 --enable-alloc-wait --enable-flock-wait --enable-vbar-uds(:2112 metrics)
  sidecar-log-collector: 每 5 s glob /tmp/tpu_logs/**/tpu_driver.INFO,tail -f 到 stdout,行前缀 [<file>]
  vbar-control-agent: env TPU_SKIP_MDS_QUERY=true TPU_ON_GKE=true
ai-telemetry-collector DS: 抓取暴露 9431 端口的 Pod,scrape_interval 60s,保留 jax_orbax_*、jax_checkpoint_*、grain_python_*
maintenance-handler DS: --taint=cloud.google.com/impending-node-termination::NoSchedule --tpu-vm-timeout=5m
mutatingwebhookconfigurations: 5 个,均非 TPU 相关
CRDs: 32 个,无 Slice、JobSet、Kueue

实测耗时:整套只读命令约 60 s;单次 instance describe 约 3.0 s(复核实验,--format=json;projection 形式为同一 API 调用)。

判定标准:每个 TPU 节点 google.com/tpu allocatable = 4 且带 NoSchedule taint;tpu-device-plugin 3/3 Running;monitoringConfig 包含 SYSTEM_COMPONENTS(kubernetes.io/*/accelerator/* 指标依赖它)。

注意事项:

  • GKE 节点上没有 TPU 专用 condition,芯片健康需要依赖 Cloud Monitoring 指标(见附录 A.6.1)和日志 实测。
  • 没有 TPU 命名的 MutatingWebhookConfiguration;TPU_WORKER_ID、TPU_LOG_DIR 和 TPU toleration 在控制面准入阶段写入 Pod spec(对比 Job 模板与实际 Pod 得出),拓扑类变量、/tmp/tpu_logs 与 /var/run/tpu-plugin 挂载、/dev/vfio/* 来自 device plugin 的 Allocate 响应,不出现在 Pod spec 中(见附录 A.1.2)实测。
  • node.gke.io/upcoming-maintenance annotation 是集群内可读的计划维护信号,含窗口时间和 can_reschedule 实测。
  • 节点池 resource label goog-gke-tpu-node-pool-type=single-host 与实际的 2 host 2x2x2 slice 不符,不能用它判断单机或多机 实测。
  • 验证集群 kube-system 中另有用户自行部署的 DaemonSet,盘点时需与 GKE 组件区分 实测。
↩ 返回需求R-10正文2.1
A.1.2

A.1.2 节点主机只读检查(不占用 TPU)#

服务需求R-05R-09实测耗时Pod Ready 4 s(镜像已缓存),装工具 9 s,检查 7 s实测

服务需求:R-05、R-09(见第 1 章);正文:2.1。

目的:不申请 google.com/tpu,核对起飞前检查和运维脚本依赖的主机事实:TPU PCI function、AER sysfs、PCIe 链路、内存、挂载参数、/dev/vfio、vbar.sock、/tmp/tpu_logs、网卡参数、主机监听端口、内核日志。

前置:A.0.2,主机检查 Pod 见 A.0.6。

命令(Pod 内执行):

bash
grep -E '^(BUILD_ID|VERSION_ID)=' /host/etc/os-release; uname -r; nproc; lscpu | grep -E '^(Model name|NUMA node\(s\))'
for d in /sys/bus/pci/devices/*; do [ "$(cat $d/vendor)" = 0x1ae0 ] && echo "$(basename $d) $(cat $d/device) $(basename $(readlink -f $d/driver)) $(cat $d/current_link_speed 2>/dev/null) x$(cat $d/current_link_width 2>/dev/null) aer_fatal=$([ -e $d/aer_dev_fatal ] && echo present || echo ABSENT)"; done | grep ' 0x0076 '     # 只保留 TPU function(vendor 0x1ae0 下还有桥、gVNIC、NVMe)
grep -E 'MemTotal|MemAvailable' /host/proc/meminfo
findmnt --task 1 -n -o TARGET,FSTYPE,OPTIONS --target /tmp
ls -la /host/dev/vfio /host/run/tpu-plugin /host/tmp/tpu_logs/*/
chroot /host /usr/sbin/ethtool -g eth0          # COS 自带 ethtool 6.11
ss -ltnp
dmesg -T > /tmp/d.txt
grep -ciE 'gve.*reset|NETDEV WATCHDOG' /tmp/d.txt; grep -ciE 'Machine check|CPER|EDAC' /tmp/d.txt
grep -iE 'AER|pcieport.*error' /tmp/d.txt
grep -oE 'Killed process [0-9]+ \([^)]*\)' /tmp/d.txt | sed -E 's/Killed process [0-9]+ //' | sort | uniq -c | sort -rn

裁剪输出(node-a 2026-11-03 11:32 UTC;dmesg 部分为两节点 11:56 UTC):

输出
BUILD_ID=19506.505.8 (COS 129, kernel 6.12.110+)   MemTotal: 990725056 kB   CPU: Xeon Platinum 8581C, 224 vCPU, 2 NUMA
0000:00:03.0 0x0076 vfio-pci Unknown x0 aer_fatal=ABSENT
...  # 共 8 个 1ae0:0076:00:03.0/.1 00:04.0/.1 在 NUMA0,c0:00.0/.1 c0:02.0/.1 在 NUMA1
/tmp => tmpfs rw,nosuid,nodev,noexec    /var => ext4 rw,nosuid,nodev,noexec    / => ext2 ro
/dev/vfio: 0 1 2 3 4 5 6 7 vfio (crw-rw-rw-)    /run/tpu-plugin/vbar.sock srw-rw-rw- root:root
/tmp/tpu_logs/main/tpu_driver.sh-node-a.root.log.INFO.20261103-113131.42  (+ symlink tpu_driver.INFO)
eth0 gve 1.0.0 mtu=8896 speed=200000 rings RX/TX 1024/1024 (max 4096) channels 16/16
ethtool 6.11 -g: "TCP data split:\t\toff"       # 容器内 ethtool 6.1 为 "TCP data split:\toff"
LISTEN *:2112 tpu-device-plugin  *:8353 vbar_control_agent  *:8203 otelsvc  *:10250 kubelet   # 主机 netns 无 8431、8471、9431
Device-plugin Allocate(解码 kubelet_internal_checkpoint):
  env TPU_TOPOLOGY=2x2x2 TPU_HOST_BOUNDS=1,1,2 TPU_RUNTIME_METRICS_PORTS=8431..8438 VBAR_CONTROL_SERVICE_URL=unix:///var/run/tpu-plugin/vbar.sock
  MOUNT /var/run/tpu-plugin (ro), /tmp/tpu_logs (rw); DEV /dev/vfio/0-7 + /dev/vfio/vfio
dmesg(自 2026-10-26 开机): gve reset/NETDEV WATCHDOG 0;Machine check/CPER/EDAC 0
AER 匹配 2 行,均为开机 "_OSC: OS now controls [PCIeHotplug PME AER PCIeCapability]"
oom-kill 行 504(node-a)、524(node-b);node-a 被杀进程 otelsvc 162 次,config-reloader 90 次

实测耗时:Pod Ready 4 s(镜像已缓存),装工具 9 s,检查 7 s;后续各轮 Ready 加装工具 6 到 14 s,检查 2 到 3 s。

判定标准:恰好 8 个 1ae0:0076 且全部绑定 vfio-pci;/dev/vfio/0 到 7 和 vfio 存在;vbar.sock 为 socket;MemTotal 约 990,725,056 kB;eth0 200000 Mb/s、MTU 8896、TCP data split: off;dmesg 无 gve reset、NETDEV WATCHDOG、Machine check、CPER、EDAC。

注意事项:

  • 该 VM 上 146 个 Google PCI 设备都没有 aer_dev_fatal、aer_dev_nonfatal、aer_dev_correctable 文件,以 [[ -f aer_dev_fatal ]] 为前提的 AER 检查会静默通过;PCIe 错误改用 compute.googleapis.com/instance/tpu/accelerator/pcie_fatal_error_count 等指标(见附录 A.6.1)实测。
  • TPU function 的 PCIe 链路速率和宽度在 guest 内为 Unknown 和 0,无法检查 Gen5 实测。
  • 机型文档列 tpu7x-standard-4t 物理网卡 2 块、单 VM 最高 400 Gbps(TPU 机型)文档;验证集群节点 guest 内只见一张网卡 eth0(gVNIC,MTU 8896,链路速率 200 Gbps,读自 /sys/class/net/eth0/speed)实测。
  • ethtool -g 在 TCP data split: 后输出 TAB;只删空格的 awk 得到 \toff,永远不等于 on。应使用 awk -F: '/TCP data split/{gsub(/[[:space:]]/,"",$2);print $2}' 实测。
  • 直接 grep AER 会命中开机 _OSC 行,需排除 实测。
  • /tmp、/var、/home、/mnt/stateful_partition 为 noexec,只有 /home/kubernetes/bin、/var/lib/kubelet、/var/lib/containerd、/var/lib/toolbox 可执行 实测。
  • /tmp/tpu_logs 在主机 tmpfs 上,按容器名分子目录,更早 Pod 的目录已不存在(同节点下一次 TPU 分配时清空,见附录 A.7.2);日志需转发出节点(sidecar-log-collector 转发 tpu_driver.INFO,见附录 A.7.1)实测。
  • 两节点各有数百次 memcg OOM kill,被杀的是 otelsvc(gke-metrics-agent)和 config-reloader 容器,不是 TPU 负载;内核日志巡检应按进程和 cgroup 分类后再告警 实测。
↩ 返回需求R-05 R-09正文2.1
A.1.3

A.1.3 芯片与节点健康检查(单机与多机)#

服务需求R-05R-06R-10实测耗时holder Pod 调度到 Running 1 s(镜像已缓存)实测

服务需求:R-05、R-06、R-10(见第 1 章);正文:2.0、2.1。

目的:演示 GKE 上检查 TPU v7x 健康的节点级和 Pod 内命令:节点 allocatable 与 condition、/dev/vfio、tpu-info、jax.devices() 清点和 psum 冒烟测试,分别在 slice 的单个节点和整个 slice 上运行。

前置:A.0.2 到 A.0.5。

psum 冒烟脚本 devices_probe.py(核心部分;每个 device 贡献 序号+1,结果应为 n(n+1)/2):

python
import argparse, json, numpy as np, jax
from jax.sharding import Mesh, NamedSharding, PartitionSpec as P
from jax import shard_map
p = argparse.ArgumentParser(); p.add_argument("--distributed", action="store_true")
if p.parse_args().distributed:
    jax.distributed.initialize()                  # 多机:TPU_WORKER_ID 等由 GKE 注入
devs, local = jax.devices(), jax.local_devices()
print("PROBE_INFO", json.dumps({"process_count": jax.process_count(), "global_device_count": len(devs), "local_device_count": len(local)}))
n = len(devs); mesh = Mesh(np.array(devs), ("i",))
vals = {d.id: float(i + 1) for i, d in enumerate(devs)}
x = jax.make_array_from_single_device_arrays((n,), NamedSharding(mesh, P("i")),
        [jax.device_put(np.array([vals[d.id]], np.float32), d) for d in local])
y = jax.jit(shard_map(lambda v: jax.lax.psum(v, "i"), mesh=mesh, in_specs=P("i"), out_specs=P("i")))(x)
got = sorted({float(np.asarray(s.data)[0]) for s in y.addressable_shards})
print("PSUM_RESULT", json.dumps({"n_devices": n, "expected": n * (n + 1) / 2, "pass": got == [n * (n + 1) / 2]}))

命令:

bash
kubectl get nodes -l cloud.google.com/gke-tpu-accelerator=tpu7x \
  -o custom-columns='NAME:.metadata.name,TPU_ALLOC:.status.allocatable.google\.com/tpu,TOPO:.metadata.labels.cloud\.google\.com/gke-tpu-topology'
kubectl get node <NODE> -o jsonpath='{range .status.conditions[*]}{.type}={.status}{"\n"}{end}'
kubectl -n $NS cp devices_probe.py sh-node-a:/tmp/ && kubectl -n $NS cp busy_loop.py sh-node-a:/tmp/
kubectl -n $NS exec sh-node-a -- ls -la /dev/vfio
kubectl -n $NS exec sh-node-a -- bash -c 'cd /tmp && TPU_HOST_BOUNDS=1,1,1 python3 devices_probe.py'
# tpu-info 需在有负载时查询:busy_loop.py 在 8 个 device 上循环 bf16 8192x8192 matmul 70 s
kubectl -n $NS exec sh-node-a -- bash -c 'pip install -q tpu-info; cd /tmp; (TPU_HOST_BOUNDS=1,1,1 python3 busy_loop.py --seconds 70 &); sleep 20;
  tpu-info; tpu-info -p; tpu-info --metric duty_cycle_percent --metric hbm_usage --metric tensorcore_utilization'
# 整 slice:两个 Pod 同时各起一个进程
./run_mh.sh . mh_probe 'cd /tmp && python3 devices_probe.py --distributed'

busy_loop.py(在所有本地 device 上循环 bf16 matmul,供 tpu-info 读取实时指标):

python
import argparse, time
import jax, jax.numpy as jnp
p = argparse.ArgumentParser(); p.add_argument("--seconds", type=float, default=60); p.add_argument("--n", type=int, default=8192)
a = p.parse_args()
devs = jax.local_devices()
xs = [jax.device_put(jnp.ones((a.n, a.n), jnp.bfloat16), d) for d in devs]
f = jax.jit(lambda x: (x @ x) * 1e-4)
t_end, it = time.time() + a.seconds, 0
while time.time() < t_end:
    xs = [f(x) for x in xs]
    if it % 50 == 0:
        jax.block_until_ready(xs)
    it += 1
jax.block_until_ready(xs)

裁剪输出(PROBE_INFO、LOCAL_DEVICE、PSUM_RESULT 行来自完整版脚本,另打印版本、坐标与耗时字段;上面的核心部分只输出 PROBE_INFO 的 3 个计数与 PSUM_RESULT 的前 3 个字段):

输出
<node-a>  TPU_ALLOC 4  TOPO 2x2x2
/dev/vfio: 0 1 2 3 4 5 6 7 vfio
tpu-info version: 0.14.2, libtpu version: 0.0.34, accelerator type: 7x
Chip /dev/vfio/3 /dev/vfio/5 /dev/vfio/6 /dev/vfio/7: Type TPU7x chip, Devices 2, PID 4393
Chip 0..3: HBM Usage 5.00 GiB / 189.49 GiB, Duty cycle 42.73% 到 42.84%
tpu-info -p: /dev/vfio/{3,5,6,7} -> 4393 python3; /dev/vfio/{0,1,2,4} -> None
空闲时: WARNING: Libtpu metrics unavailable. Is there a framework using the TPU?
# 单机,TPU_HOST_BOUNDS=1,1,1
PROBE_INFO {"jax": "0.9.0", "libtpu": "0.0.34", "process_count": 1, "global_device_count": 8, "local_device_count": 8, "init_seconds": 2.76}
LOCAL_DEVICE id=0 coords=(0,0,0) core_on_chip=0 ... id=7 coords=(1,1,0) core_on_chip=1
PSUM_RESULT {"n_devices": 8, "expected": 36.0, "pass": true, "compile_plus_run_s": 0.305, "total_script_s": 4.35}
# 整 slice,2 个 Pod
PROBE_INFO {"process_index": 0, "process_count": 2, "global_device_count": 16, "local_device_count": 8, "init_seconds": 3.88}
LOCAL_DEVICE (pod 1) id=8..15 coords=(0,0,1)..(1,1,1)
PSUM_RESULT {"n_devices": 16, "expected": 136.0, "pass": true, "compile_plus_run_s": 0.302, "total_script_s": 6.57}

实测耗时:holder Pod 调度到 Running 1 s(镜像已缓存);Indexed Job 两个 Pod Running 3 s;pip install tpu-info 0.9 s;单机 probe 4.4 s(backend 初始化 2.8 s,psum 0.3 s),含 kubectl exec 8 s;多机 probe 6.6 s(初始化 3.9 s),含 kubectl exec 11 s;不覆盖 TPU_HOST_BOUNDS 的单机启动约 3 s 后失败。

判定标准:节点 allocatable = 4,Ready=True,CperHardwareErrorFatal=False,KernelDeadlock=False;Pod 内 /dev/vfio 有 8 个编号设备加 vfio;负载运行时 tpu-info 列出 4 行 TPU7x chip,每行 2 个 device;单机 8 个 TPU7x device、多机 16 个且 process_count 2;psum 等于 n(n+1)/2。

注意事项:

  • pip install tpu-info 得到 0.14.2(安装 TPUMS 后降为 0.7.1);没有 JAX 进程占用 TPU 时不显示利用率 实测。
  • tpu-info 0.14.2 只有 flag(-p、--streaming、--rate、--list_metrics、--metric、-f),无子命令;--metric hlo_exec_timing -f ... 返回 does not support filters;core_state、sequencer_state 输出约 250 行,不适合日常巡检 实测。
  • libtpu 0.0.34 加 tpu-info 0.14.2 时 TensorCore 利用率只显示 6 个核(每节点 8 个);libtpu 0.0.50 加 tpu-info 0.7.1 显示全部 8 个 实测。
  • libtpu 只打开每个芯片的 PCI function .0,8 个 vfio group 中 4 个被 JAX 进程持有;两节点都有 /dev/vfio/0 到 7,各芯片 function .0 对应的组号因节点而异(一个节点为 3、5、6、7,另一节点为 1、2、3、4),tpu-info 按 vfio 路径标识芯片,JAX 按 coords 实测。
  • 未知 libtpu flag 会中止启动:上一版报告所列的 SparseCore embedding 确定性参数在 libtpu 0.0.50 上报 Unknown command line flag,在 0.0.51 上被接受(pip install libtpu==0.0.51 4 s,pip 提示 tpu-sync-jax 要求 0.0.50)实测。
↩ 返回需求R-05 R-06 R-10正文2.0 2.1
A.1.4

A.1.4 /dev/vfio 持有者定位#

服务需求R-05R-12实测耗时debug Pod 调度到输出约 4 s,安装 psmisc 另需约 4 s,整个检查…实测

服务需求:R-05、R-12(见第 1 章);正文:2.1、3.5.6。

目的:验证从节点 debug Pod 用 fuser -v /dev/vfio/* 查找 TPU 占用进程的做法,并给出在 JAX 进程实际占用芯片时能定位到进程和所属 Pod 的方法。

前置:A.0.4 holder Pod 在 node-a 上运行 busy_loop.py 占用全部 4 个芯片(见附录 A.1.3)。节点 debug Pod 建在自己的命名空间,结束后删除;不使用 fuser -k。

命令:

bash
# 原方法:fuser
kubectl debug node/<NODE> -n $NS --profile=sysadmin --image=ubuntu:24.04 -- bash -c \
  'apt-get -qq update && apt-get -qq install -y psmisc >/dev/null; fuser -v /host/dev/vfio/*; echo fuser_rc=$?'
kubectl -n $NS logs <DEBUG_POD>   # DEBUG_POD 为上一条命令打印的 Creating debugging pod <name> 中的名称;不带 -i 时结果只在 Pod 日志中
# 修正方法:在 hostPID 的 debug Pod 中扫描 /proc/*/fd,输出 PID、持有的设备、命令行与 cgroup(含 Pod UID)
kubectl debug node/<NODE> -n $NS --profile=sysadmin --image=ubuntu:24.04 -- bash -c 'for fd in /proc/[0-9]*/fd/*; do l=$(readlink "$fd" 2>/dev/null) || continue; case "$l" in /dev/vfio/*|/dev/accel*) p=${fd#/proc/}; p=${p%%/*}; echo "$p $l";; esac; done | sort -u > /tmp/h; awk "{print \$1}" /tmp/h | sort -u | while read p; do echo "PID $p fds=$(grep -c "^$p " /tmp/h) [$(grep "^$p " /tmp/h | awk "{print \$2}" | sort -u | tr "\n" " ")] cmd=$(tr "\0" " " < /proc/$p/cmdline | cut -c1-80) cgroup=$(cut -c1-150 /proc/$p/cgroup | tail -1)"; done'
kubectl -n $NS logs <DEBUG_POD>
# cgroup 中 pod<uid> 的 "-" 写作 "_",反查前替换回 "-"
POD_UID=$(echo <cgroup 中的 uid> | tr _ -)
kubectl get pods -A -o jsonpath="{range .items[?(@.metadata.uid==\"$POD_UID\")]}{.metadata.namespace}/{.metadata.name}{\"\n\"}{end}"
kubectl -n $NS delete pod <DEBUG_POD>

裁剪输出:

输出
crw-rw-rw- 1 root root 244, 2 Oct 26 07:48 /host/dev/vfio/0  ...  /host/dev/vfio/7, /host/dev/vfio/vfio
fuser_rc=1                       # busy_loop.py 占用全部 4 个芯片时 fuser 无结果
PID 1144441 fds=5 [/dev/vfio/3 /dev/vfio/5 /dev/vfio/6 /dev/vfio/7 /dev/vfio/vfio ] cmd=python3 /tmp/busy_loop.py --seconds 150
  cgroup=0::/kubepods.slice/kubepods-besteffort.slice/kubepods-besteffort-pod<POD_UID>.slice/cri-containerd-1edb3da8...

实测耗时:debug Pod 调度到输出约 4 s,安装 psmisc 另需约 4 s,整个检查不到 15 s。

判定标准:能列出持有 /dev/vfio/* 的 PID、命令行和 cgroup(含 Pod UID)。实测 fuser 无结果,/proc/*/fd 扫描可以定位。

注意事项:

  • fuser(lsof 同理,未单测)对 /host/dev/vfio/* 按 inode 匹配;容器内的 /dev/vfio/N 是容器 /dev 中另建的设备节点(major:minor 与宿主机同名节点相同,例如 /dev/vfio/0 为 244:2,编号 N 不等于 minor;inode 不同),所以看不到容器内的持有者 实测。
  • cgroup 路径中的 pod<uid> 即 Pod UID,处置前先用 UID 反查到具体 Pod,不要直接杀进程 实测。
  • libtpu 只持有每个芯片的 PCI function .0(本例 /dev/vfio/3,5,6,7)加 /dev/vfio/vfio(见附录 A.1.3)实测。
↩ 返回需求R-05 R-12正文2.1 3.5.6
A.1.5

A.1.5 Terminating Pod 列表命令#

服务需求R-12实测耗时每次调用约 1.5 到 2 s(两节点各一次加 sleep 1,每轮 4 到 5 s)实测含未验证

服务需求:R-12(见第 1 章);正文:3.5.6。

目的:验证列出某节点上处于 Terminating 状态 Pod 的单行命令。

前置:A.0.2。验证时删除两个 holder Pod(terminationGracePeriodSeconds: 5),同时循环执行命令(每轮两节点各一次,轮间 sleep 1,实测每轮 4 到 5 s)。

命令:

bash
kubectl -n $NS delete pod sh-node-a sh-node-b --wait=false
kubectl get pods -A --field-selector spec.nodeName=<NODE> \
  -o jsonpath='{range .items[?(@.metadata.deletionTimestamp)]}{.metadata.namespace}/{.metadata.name}{"\n"}{end}'

裁剪输出:

输出
# t+N 为轮次序号,不是秒
--- t+1s 12:26:51
tpu-verify/sh-node-a
[<node-a> rc=0]
tpu-verify/sh-node-b
[<node-b> rc=0]
--- t+2s 12:26:56
[<node-a> rc=0]
[<node-b> rc=0]

实测耗时:每次调用约 1.5 到 2 s(两节点各一次加 sleep 1,每轮 4 到 5 s)。

判定标准:只列出带 deletionTimestamp(Terminating)的 Pod;没有时输出为空且 rc=0。实测第 1 轮(12:26:51)列出两个 Pod,第 2 轮(12:26:56)起到第 12 轮(12:27:40)输出为空,rc=0。

注意事项:

  • 以 bash -c 'sleep infinity' 作为 PID 1 的容器会忽略 SIGTERM,删除时总是等满整个 grace period 实测。
  • 该命令只调用 pods 的 list(所有命名空间)未验证。
↩ 返回需求R-12正文3.5.6

A.2 TPUMS 与同步脉冲(对应 2.2)#

A.2.1

A.2.1 TPUMS 微基准(单机与整 slice)#

服务需求R-01R-02R-15实测耗时Pod 已运行、镜像已缓存:tpums platform describe 单机 6 …实测

服务需求:R-01、R-02、R-15(见第 1 章);正文:2.2、3.1。

目的:在单个 tpu7x-standard-4t 节点和整个 2x2x2 slice 上运行 TPUMS CLI:GEMM(bf16、fp8)、HBM 带宽、host 与 device 间传输、device 间传输(芯片内与跨芯片 ICI)、chained GEMM 确定性校验和、240 s 热与降频 soak、ICI 集合通信,记录可用命令、关键数值和耗时。

前置:A.0.4、A.0.5、A.0.7。TPUMS 027cd62,jax/jaxlib 0.12.0,libtpu 0.0.50。

单位:每节点 8 个 JAX device(4 芯片 × 2 TensorCore)。*_per_device 指单个 TensorCore,*_per_host 指整节点,*_per_chip 为 TPUMS 的每芯片口径。GEMM 的 per chip 值经日志核对为每 device 值的 2 倍:bf16 16384³ 单次 total_flops 8.796e12,xprof p50 8.3469 ms,即每 device 1053.8 TFLOP/s,TPUMS 报 2107.6 per chip 实测。集合通信的 *_per_chip 沿用 TPUMS 列名。

A.2.1.1 单机#

单节点有两种方式:--standalone_host_init(TPUMS 自带,无 ICI)用于 gemm、hbm.yaml(只测 device 0)、host_to_device、device_to_host、gemm_throttling;只设 TPU_HOST_BOUNDS=1,1,1(本机 ICI 可用)用于 device_to_device、gemm_chained 和 hbm 的 8 device 扫描。

bash
cd /tmp/tpums
tpums benchmark run-config configs/tpu7x/2x2x1/gemm.yaml           --standalone_host_init --output_dir /tmp/results/gemm
tpums benchmark run-config configs/tpu7x/2x2x1/hbm.yaml            --standalone_host_init --output_dir /tmp/results/hbm
tpums benchmark run-config configs/tpu7x/2x2x1/host_to_device.yaml --standalone_host_init --output_dir /tmp/results/h2d
tpums benchmark run-config configs/tpu7x/2x2x1/device_to_host.yaml --standalone_host_init --output_dir /tmp/results/d2h
tpums benchmark run-config /tmp/gemm_throttling_240s.yaml          --standalone_host_init --output_dir /tmp/results/thr
# 3600 s 浸泡(复核实验):同一文件的副本,min_duration_s 改为 3600
tpums benchmark run-config /tmp/gemm_throttling_3600s.yaml         --standalone_host_init --output_dir /tmp/results/thr3600
TPU_HOST_BOUNDS=1,1,1 tpums benchmark run-config configs/sample_configs/gemm_chained.yaml --output_dir /tmp/results/chained
TPU_HOST_BOUNDS=1,1,1 tpums benchmark run device_to_device --xprof_timing --data_size_mib 1024 --direction uni --dtype bfloat16
# hbm 8 device 扫描(复核实验):不加 --standalone_host_init,只设 TPU_HOST_BOUNDS=1,1,1
TPU_HOST_BOUNDS=1,1,1 tpums benchmark run hbm --xprof_timing --op_type copy --dtype bfloat16 --warmup_tries 2 --num_runs 5 \
  --num_elements 67108864 134217728 268435456 536870912 --device_id 0 1 2 3 4 5 6 7
# fp8 GEMM 交互式写法(复核实验运行:16384³ xprof 4438.9 TFLOP/s per chip,16.0 s;表中 fp8 数值来自 gemm.yaml)
tpums benchmark run gemm --standalone_host_init --xprof_timing --m 16384 --k 16384 --n 16384 \
  --in_dtype float8_e4m3fn --out_dtype bfloat16 --num_runs 50 --warmup_tries 10
yaml
# 保存为 /tmp/gemm_throttling_240s.yaml:sample_configs/gemm_throttling.yaml 的副本,min_duration_s 由 120 改为 240(3600 s 浸泡版只把该值改为 3600.0)
benchmark:
  name: gemm_throttling
  xprof_timing: true
  xprof_device_timing_aggregation: local_slowest_device
  params: {warmup_tries: 10, min_duration_s: 240.0, in_dtype: bfloat16, out_dtype: bfloat16, m: 16384, k: 16384, n: 16384, samples_per_run: 25}

裁剪输出(xprof 为设备侧计时):

输出
# gemm.yaml(node-b)           wall_clock_tflops_per_chip  xprof_p50_ms  xprof_tflops_per_chip
bfloat16       8192^3                      1606.35        1.0083                2180.91
bfloat16      16384^3                      2017.85        8.3469                2107.64
float8_e4m3fn  8192^3                      2558.54        0.5210                4220.90
float8_e4m3fn 16384^3                      4020.78        3.9608                4441.57
# hbm.yaml(只测 device_id 0,bf16 copy 256 到 2048 MiB): xprof 3210.1 到 3242.3 GB/s per device
# hbm 8 device 扫描(复核实验,node-a,256 到 2048 MiB,大小在外层、device 在内层依次执行,124 s): xprof 3201.7 到 3241.5 GB/s per device,32 组
# host_to_device / device_to_host(8 device,每 device 4、8、16 GiB)
jax       H2D 46.1 / 47.4 / 24.7 GB/s per host      D2H 61.1 / 61.0 / 14.6 GB/s per host
tpu_sync  H2D 226.4 / 227.0 / 227.2 GB/s per host   D2H 225.3 / 225.9 / 226.2 GB/s per host(约 28.3 GB/s per device)
# gemm_chained(node-a,chain 100,m=k=8192)
all_devices_valid_checksum=True intra_host_checksum_match=True global_checksum_match=True xprof_tflops_per_chip=2013.8
# gemm_throttling(node-b,bf16 16384^3,240 s)
xprof_tflops_per_chip=1989.18 xprof_slowdown_ratio=1.002 wall_clock_slowdown_ratio=1.010
hbm_peak_temp_c=44.0 (pre-soak 45.0) peak_temp_c=<空> hbm_throttle_time_pct=0.0 vdd_core_throttle_time_pct=0.0
vdd_core_power_mean_w=417.1 hbm_power_mean_w=50.6 total_power_mean_w=467.0 pstate_min=… pstate_max=… pstate_changes=0
# gemm_throttling 3600 s 浸泡(复核实验,node-b,RC 0,墙钟 3640 s)
total_duration_s=3621.1 actual_runs=404125 xprof_tflops_per_chip=1988.3 xprof_slowdown_ratio=1.0054 wall_clock_slowdown_ratio=1.0104
hbm_throttle_time_pct=0.0 vdd_core_throttle_time_pct=0.0 total_power_mean_w=465.8 hbm_peak_temp_c=43.0 peak_temp_c=<空> pstate_changes=0
# device_to_device(node-a,56 个有向 device 对,1024 MiB)
uni: 芯片内 342.3 到 343.5,跨芯片 ICI 46.63 到 46.64 GB/s per device;bi: 688.9 到 691.6,93.27 到 93.29 GB/s per device
A.2.1.2 整 slice 集合通信(16 device,2 Pod)#

两个 Pod 都安装 TPUMS(并行 45 s),用 run_mh.sh 同时启动同一命令,TPUMS 自行调用 jax.distributed.initialize()。

bash
./run_mh.sh . all_reduce 'cd /tmp/tpums; tpums benchmark run-config configs/tpu7x/2x2x2/all_reduce.yaml'
./run_mh.sh . all_gather 'cd /tmp/tpums; tpums benchmark run-config configs/tpu7x/2x2x2/all_gather.yaml'
./run_mh.sh . all_to_all 'cd /tmp/tpums; tpums benchmark run-config configs/tpu7x/2x2x2/all_to_all.yaml'
# fp32 all_reduce:TPUMS 默认 op_flags(all_reduce 项含性能状态参数)与去掉该参数的副本各一次
./run_mh.sh . ar_fp32_base   'cd /tmp/tpums; tpums benchmark run-config /tmp/all_reduce_fp32.yaml'
./run_mh.sh . ar_fp32_noperf 'cd /tmp/tpums; tpums benchmark run-config /tmp/all_reduce_fp32.yaml --xla_flags_file_path /tmp/op_flags_noperf.yaml'

all_reduce_fp32.yaml:name: all_reduce,xprof_timing: true,xprof_device_timing_aggregation: global_slowest_per_step,params {warmup_tries: 2, num_runs: 20, dtype: float32, reduce_op: sum, mesh_shape: 4x2x2, sharding_strategy: 4x2x2},sweep matrix_dim: [4096, 8192, 16384]。

输出
tpums platform describe (2 pods): "topology": "2x2x2", "total_devices": 16, "local_devices": 8, "process_count": 2
AllReduce bf16 mesh 4x2x2: sharding 4x2x1 xprof 275.4 / 277.7 / 278.6;sharding 4x2x2 214.6 / 214.9 / 216.4 GB/s per chip
AllGather bf16 mesh 4x2x2: sharding 4x2x1 267.2 / 270.4 / 272.0;sharding 4x2x2 260.9 / 263.8 / 265.6 GB/s per chip
AllToAll  bf16 mesh 4x2x2: 155.5 / 159.3 / 161.2 GB/s per chip,xprof_ici_roofline_efficiency 88.9% 到 92.1%(TPUMS 取 175 GB/s per chip)
AllReduce fp32 4x2x2: 默认 op_flags 191.8 / 207.0 / 210.8;去掉性能状态参数 191.5 / 207.1 / 210.8 GB/s per chip(16 / 32 / 64 MiB shard)
  同批 wall_clock_bw_per_chip 11.8 到 14.3 GB/s

未运行:跨 host device_to_device(约 40 min)、reduce_scatter、dcn_*(需至少 2 个 slice)。

A.2.1.3 实测耗时#

Pod 已运行、镜像已缓存:tpums platform describe 单机 6 s、多机 10 s;gemm.yaml 35 s;hbm.yaml 22 s;host_to_device 278 s;device_to_host 336 s;gemm_chained 15 s(--standalone_host_init 下卡住,242 s 时 kill);gemm_throttling 279 s(3600 s 浸泡版 3640 s,复核实验);device_to_device uni 571 s(56 对,10 次 warmup 加 10 次 run),bi 440 s(--warmup_tries 2 --num_runs 5);all_reduce、all_gather、all_to_all 61 s、27 s、24 s;fp32 all_reduce 21 到 22 s。以上耗时均不含镜像冷拉取(实测的冷拉取只有 CHS 工作负载镜像在 CPU 节点上的 95 s,见 A.0.11)实测。hbm.yaml 只测 device 0(22 s);8 个 device 扫描(命令见 A.2.1.1)实测 124 s,32 组结果 实测。

A.2.1.4 判定标准#

TPUMS 不提供通过阈值。下表为本集群实测参考值,作为基线起始值,按上线后 2 周实测基线调整。

测试参考值(xprof)
GEMM 16384³bf16 约 2100、fp8 约 4400 TFLOP/s per chip 以上
HBM copy约 3200 GB/s per device 以上
H2D、D2H(tpu_sync)约 226 GB/s per host
gemm_chained三个 checksum 字段均为 True
gemm_throttlingthrottle_time_pct 为 0,xprof_slowdown_ratio 约 1.00,性能状态全程不变(pstate_changes=0)
device_to_device uni芯片内约 342、跨芯片约 46.6 GB/s per device,48 个跨芯片对一致
2x2x2 集合通信all_reduce bf16(4x2x2)约 214、all_gather 约 260、all_to_all 约 155 GB/s per chip 以上
A.2.1.5 注意事项#
  • --in_dtype fp8_e4m3fn 报 invalid choice 并 rc=2,正确名称是 float8_e4m3fn;--warmup_runs 被静默忽略(正确为 --warmup_tries),未知参数不报错 实测。
  • --standalone_host_init 下 device_to_device 和集合通信被拒绝;gemm_chained 在该模式下编译后卡住,需改用 TPU_HOST_BOUNDS=1,1,1 实测。
  • --standalone_host_init 下 hbm 8 device 扫描在 device 2 卡住(device 0、1 各 2 s 完成,之后无进展);单测 --device_id 2 120 s 超时(device 1 为 7 s 完成),8 device 扫描须只设 TPU_HOST_BOUNDS=1,1,1;run-config hbm.yaml 追加 --device_id 0 1 被静默忽略,仍只测 device 0 实测。
  • gemm_throttling 在该平台不输出 peak_temp_c,peak_temp_c < 85 类判定无法执行,改用 hbm_peak_temp_c、*_throttle_time_pct、xprof_slowdown_ratio、pstate_* 实测。
  • Pod 中的 LIBTPU_INIT_ARGS 被 TPUMS op_flags.yaml 覆盖,后者的 gemm、all_reduce 等项含性能状态参数(见 TPUMS 公开仓库 op_flags.yaml),自定义 flag 用 --xla_flags_file_path;该参数对 all_reduce 无可测影响,对 GEMM 类吞吐的影响见附录 A.2.2 实测。
  • device_to_device 的 uni 与 bi 相差 2 倍,引用数值必须注明方向 实测。
  • 集合通信 wall-clock 带宽含每步 host 调度开销(all_reduce bf16 仅 7.6 到 15.8 GB/s per chip),判定使用 xprof_* 实测。
  • configs/tpu7x/2x2x1/hbm.yaml 未设 device_id,按默认只测 device 0;jax 后端 H2D、D2H 在每 device 16 GiB 时下降,tpu_sync 不受影响 实测。
  • CHS tpu-collectives psum 与 TPUMS all_reduce 均为设备侧计时,差别在 dtype、消息大小与性能状态;按 CHS 配置对齐(fp32,16/32/64 MiB shard)时 64 MiB 结果一致(210.8 GB/s per chip),TPUMS 默认配置结果不能套用 CHS 门限(见 2.3.4)实测。
↩ 返回需求R-01 R-02 R-15正文2.2 3.1
A.2.2

A.2.2 同步脉冲(di/dt)GEMM 测试与确定性校验和#

服务需求R-03实测耗时Pod 已运行(调度到 Running 1 s,无需安装)实测

服务需求:R-03(见第 1 章);正文:2.2。

目的:参考 accelerator-microbenchmarks#145(2026-10-29 提出的功能请求,TPUMS 尚无脉冲基准)做阶跃负载测试:单 host 的 8 个 TensorCore 空闲 50、200、500(v2 加 1000)ms 后,在同一次 jax.jit dispatch 中同时开始 30 次 bf16 8192³ 链式 GEMM。所有 device 输入相同,每个 device 的校验和必须等于预热参考值,不一致时输出该 device 的 coords 和 core_on_chip。

前置:A.0.4 单机 holder Pod(TPU_HOST_BOUNDS=1,1,1)。jax-ai-image 原样可用(jax 0.9.0、libtpu 0.0.34),安装 TPUMS 后(jax 0.12.0、libtpu 0.0.50)也已验证。脚本 gemm_pulse_didt.py 只依赖 JAX 和 NumPy,核心如下:

python
mesh = Mesh(np.array(devs), ("d",))
CHK_DT = jnp.uint32                                  # --x64 时改为 64 位无符号整型并启用 jax_enable_x64

def _burst(w, xs):
    acc = xs[0]
    for _ in range(args.chain):
        acc = jnp.matmul(w, acc, preferred_element_type=jnp.float32).astype(jnp.bfloat16)
    bits = jax.lax.bitcast_convert_type(acc, jnp.uint16).astype(CHK_DT)
    weights = jnp.arange(bits.size, dtype=CHK_DT).reshape(bits.shape) * CHK_DT(2) + CHK_DT(1)
    chk = jnp.sum(bits * weights, dtype=CHK_DT)      # uint32 按 2^32 回绕,奇数权重
    finite = jnp.all(jnp.isfinite(acc)).astype(jnp.int32)
    return chk.reshape(1), finite.reshape(1), acc[0, 0].astype(jnp.float32).reshape(1)

burst = jax.jit(shard_map(_burst, mesh=mesh, in_specs=(P(), P("d")), out_specs=(P("d"), P("d"), P("d"))))
barrier = jax.jit(shard_map(lambda t: jax.lax.psum(t, "d"), mesh=mesh, in_specs=P("d"), out_specs=P("d")))
# 每个脉冲:barrier(token).block_until_ready() -> time.sleep(idle_ms/1000) -> burst(w, x) -> 逐 device 比对参考校验和

命令:

bash
kubectl -n $NS cp gemm_pulse_didt.py sh-node-a:/tmp/
kubectl -n $NS exec sh-node-a -- bash -c 'cd /tmp; TPU_HOST_BOUNDS=1,1,1 python3 gemm_pulse_didt.py --json_out /tmp/pulse_default.json'
# 对照组:只把 TPUMS 默认 op_flags.yaml 中 gemm 项里的性能状态参数(1 个)经 LIBTPU_INIT_ARGS 传入,其余 9 个调度/VMEM 参数不传,运行同一脚本
# 负对照:必须在 device 3 报 FAIL 并 exit 1。原实验带性能状态参数这 1 个;复核实验按下面不带参数的命令运行,同样在第 3 个脉冲报 device 3 FAIL 并 exit 1(吞吐 1595 到 1612 TFLOP/s per chip)
kubectl -n $NS exec sh-node-a -- bash -c 'cd /tmp; TPU_HOST_BOUNDS=1,1,1 python3 gemm_pulse_didt.py --idle_ms 50 --pulses 5 --inject_fault --fault_device 3'
# 逐间隔采集性能状态、功耗、温度(需已安装 TPUMS)
kubectl -n $NS exec sh-node-b -- bash -c 'cd /tmp; TPU_HOST_BOUNDS=1,1,1 python3 gemm_pulse_didt.py --xprof_dir /tmp/pulse_xprof --json_out /tmp/pulse_xprof.json'

裁剪输出(jax 0.12.0、libtpu 0.0.50,加性能状态参数,node-a):

输出
jax 0.12.0 | libtpu 0.0.50 | TPU7x | 8 local devices on 4 chips (2 devices/chip) | backend init 2.9s
compile+first burst 1.9s | reference checksum 0x67ef0060 (uint32 mod 2^32) | sample out[0,0]=-0.9961
[idle=  50ms pulse=1] PASS burst=  37.25 ms    885.5 TFLOP/s/device   1771.1 TFLOP/s/chip (76.8% of bf16 peak)
[idle= 500ms pulse=5] PASS burst=  36.57 ms    901.9 TFLOP/s/device   1803.8 TFLOP/s/chip (78.2% of bf16 peak)
  idle=50ms: avg=1787.0   idle=200ms: avg=1805.9   idle=500ms: avg=1802.9  (TFLOP/s/chip)
# 负对照(原实验,jax 0.9.0,带性能状态参数)
[idle=  50ms pulse=3] FAIL burst=  36.75 ms    897.4 TFLOP/s/device   1794.9 TFLOP/s/chip  diverging devices=[3]
# v2 --xprof_dir(node-b,默认作业配置,idle 50 ms;性能状态取值已隐去)
{"hbm_peak_temp_c": 39.0, "total_power_mean_w": 204.96, "pstate_min": "…", "pstate_max": "…", "pstate_changes": 0, "peak_temp_c": null}

平均吞吐(TFLOP/s per chip = per device × 2):

运行节点jax、libtpu性能状态参数(有/无)空闲 50、200、500(、1000)ms结论
v1 defaultnode-a0.9.0、0.0.34无1581.5、1594.1、1599.3PASS
v1 defaultnode-a0.12.0、0.0.50无1583.6、1584.7、1594.3PASS
v1 仅性能状态参数node-a0.9.0、0.0.34有1806.9、1798.9、1801.1PASS
v1 仅性能状态参数node-a0.12.0、0.0.50有1787.0、1805.9、1802.9PASS
v1 注入故障node-a0.9.0、0.0.34有第 3 个脉冲 device 3 校验和 0x3df6cb65FAIL(预期)
v2 defaultnode-b0.12.0、0.0.50无1588.4、1599.6、1590.4、1590.0PASS
v2 仅性能状态参数node-b0.12.0、0.0.50有1760.6、1777.3、1778.1、1767.5PASS
v2 xprofnode-b0.12.0、0.0.50无、有性能状态全程不变(pstate_changes=0)PASS

上表“有”只表示传入了性能状态参数这 1 个,不是 TPUMS gemm 项的全部 10 个参数。复核实验在同一节点、同一会话中补测(jax 0.9.0、libtpu 0.0.34,空闲 50、200、500 ms 平均 TFLOP/s per chip):完整 gemm 项(10 个参数)1866.8、1869.0、1868.7;仅性能状态参数 1788.3、1815.1、1805.9;不加参数 1597.5、1595.3、1603.9;10 个参数均被 libtpu 0.0.34 接受 实测。

实测耗时:Pod 已运行(调度到 Running 1 s,无需安装);backend 初始化 2.8 到 3.0 s,编译加首个 burst 1.9 到 2.2 s,每个 burst 36 到 44 ms;50、200、500 ms 各 5 个脉冲脚本 11 s(含 kubectl exec 11 到 16 s);加 1000 ms 脚本 16.5 s(含 kubectl exec 21 s);带 --xprof_dir 166 到 175 s(每个间隔 trace 28 到 38 s)。

判定标准:

  • 每个 burst 为 PASS:8 个 device 校验和等于参考值且输出全部有限;参考值为 0 或含 inf、NaN 时脚本 exit 2(退化的校验和无法证明没有 SDC)。
  • 负对照准确报出注入的 device 并 exit 1。
  • 吞吐无公开绝对阈值。两节点各间隔平均值:默认作业配置 1581 到 1604、只加性能状态参数 1760 到 1815、完整 gemm 项 1867 到 1869 TFLOP/s per chip;单个 burst 最低 1512(默认,首个脉冲)与 1642(加参数)。建议按机群分布判定,例如平均值低于中位数 5% 以上的 host 复查(起始值,按上线后 2 周实测基线调整)。

注意事项:

  • 上一版报告发布的脉冲脚本无法运行:jax 0.9.0 上 NameError: Found an unbound axis name: i(@jax.pmap 未指定 axis_name),并有 3 条 uint64 ... truncated to uint32 警告;jax 0.12.0 上 AttributeError: jax.device_put_replicated is deprecated 实测。
  • 未开启 jax_enable_x64 时 JAX 的 64 位无符号整型被静默截断为 uint32;修正脚本显式用 uint32 模 2^32 运算;--x64 运行得到 0xf00b1b1767ef0060,低 32 位与 uint32 结果相同,结论 PASS 实测。
  • 参考校验和 0x67ef0060 在两套 jax/libtpu、有无性能状态参数、两个节点上一致 实测。
  • TPUMS 公开仓库 op_flags.yaml gemm 项中的性能状态参数被 libtpu 0.0.34 和 0.0.50 接受,只加这 1 个参数时 burst 吞吐高约 11% 到 14%,加完整 gemm 项(10 个参数)时约高 17%;任何未知 flag 会在 0.4 s 内以 ERROR: Unknown command line flag 中止(rc=1,见附录 A.4.1)实测。
  • 默认作业配置下该负载的性能状态全程不变,50 到 1000 ms 空闲间隔内无变化;加性能状态参数后同样全程不变,处于较高的工作状态。该参数提高的是整个运行的工作点,数据不支持“防止空闲期间降频”的说法 实测。
  • TPUMS total_power_mean_w 随间隔从 50 到 1000 ms 下降(默认作业配置 205 到 81 W,加性能状态参数 236 到 93 W,窗口含空闲时间);peak_temp_c 为 null,hbm_peak_temp_c 38 到 40 C 实测。
  • 只设 TPU_SKIP_MDS_QUERY=true 的单 Pod Job 在 2x2x2 节点池上实测会在 TPU 初始化时失败(更大的多机拓扑同理,未单测),需设 TPU_HOST_BOUNDS=1,1,1(见附录 A.1.3)实测。
  • 每个 burst 约 40 ms,本测试只检查空闲后上升沿的正确性和吞吐,长时间热行为用 TPUMS gemm_throttling(见附录 A.2.1)实测。
↩ 返回需求R-03正文2.2
A.2.3

A.2.3 pulse145_v2:正文采用的同步脉冲脚本#

服务需求R-03实测耗时每次运行墙钟 19.4 到 19.7 s(TPU 初始化约 5 s,编译加约 1 Gi…实测含未验证

服务需求:R-03(见第 1 章);正文:2.2。

目的:验证正文采用的同步脉冲(di/dt)GEMM 脚本 pulse145_v2.py 在 jax 0.9 与 0.12 两代环境上都能运行,参考输出有限且非零,0 个不一致,并按空闲间隔输出最小、平均、最大吞吐。该脚本不是官方工具,accelerator-microbenchmarks#145 仍是未完成的功能请求。与附录 A.2.2 的 gemm_pulse_didt.py 不同,它不计算校验和,而是把每个 burst 的输出与保存在 HBM 中的参考输出逐位比较。

前置:A.0.4 单机 holder Pod(node-a,TPU_HOST_BOUNDS=1,1,1),A.0.10 的 jax 0.9.0/libtpu 0.0.34 与 jax 0.12.0/libtpu 0.0.50.1 环境。

脚本核心(共 109 行;参数 --dim 8192、--chain 30、--idle-ms(默认 50 200 500)、--bursts 5、--devices-per-chip 2、--min-tflops-chip):

python
w = (rng.standard_normal((d, d), dtype=np.float32) * 0.02).astype(jnp.bfloat16)   # 0.02 缩放避免 30 次链乘后溢出
run = jax.jit(jax.vmap(burst), out_shardings=shard)          # 8 个 device 各算一份相同的 30 次 GEMM 链
mismatches = jax.jit(jax.vmap(lambda a, r: jnp.sum(
    jax.lax.bitcast_convert_type(a, jnp.uint16) != jax.lax.bitcast_convert_type(r, jnp.uint16),
    dtype=jnp.int32)), out_shardings=NamedSharding(mesh, P("d")))   # 每 device 不一致的 bf16 字数
ref = run(W, X)                       # 参考输出:须有限(否则 exit 2),8 个 device 逐位一致(否则 exit 3)
for idle in args.idle_ms:
    for b in range(args.bursts):
        time.sleep(idle / 1000.0)
        t0 = time.perf_counter(); out = run(W, X); out.block_until_ready(); dt = time.perf_counter() - t0
        bad = np.asarray(mismatches(out, ref))                     # 任一 device 不一致即 exit 4
        vals.append(2.0 * d * d * d * chain / dt / 1e12 * args.devices_per_chip)   # TFLOP/s per chip
# 最慢 burst 低于 --min-tflops-chip 时 exit 5

命令:

bash
kubectl -n $NS cp pulse145_v2.py sh-node-a:/tmp/
kubectl -n $NS exec sh-node-a -- bash -c 'TPU_HOST_BOUNDS=1,1,1 python3 /tmp/pulse145_v2.py --min-tflops-chip 0 --idle-ms 50 200 500 1000'
kubectl -n $NS exec sh-node-a -- bash -c 'TPU_HOST_BOUNDS=1,1,1 /tmp/v050/bin/python3 /tmp/pulse145_v2.py --min-tflops-chip 0 --idle-ms 50 200 500 1000'

裁剪输出(另加 4 行打印参考输出统计):

输出
=== jax 0.9.0 libtpu 0.0.34
reference: finite=True absmax=6.423e+06 nonzero_frac=1.0000 sha256(dev0 bf16 bits)=421ebd60e079b118 identical_on_8_devices=True
idle=50ms bursts=5 0-mismatch TFLOP/s/chip min=1601.8 avg=1614.2 max=1632.0
idle=200ms bursts=5 0-mismatch TFLOP/s/chip min=1606.1 avg=1609.2 max=1611.9
idle=500ms bursts=5 0-mismatch TFLOP/s/chip min=1612.7 avg=1618.4 max=1622.9
idle=1000ms bursts=5 0-mismatch TFLOP/s/chip min=1602.9 avg=1611.7 max=1626.8
rc=0 wall_ms=19706
=== jax 0.12.0 libtpu 0.0.50.1
reference: finite=True absmax=6.423e+06 nonzero_frac=1.0000 sha256(dev0 bf16 bits)=421ebd60e079b118 identical_on_8_devices=True
idle=50ms bursts=5 0-mismatch TFLOP/s/chip min=1593.6 avg=1601.9 max=1611.8
idle=200ms bursts=5 0-mismatch TFLOP/s/chip min=1607.9 avg=1616.3 max=1627.2
idle=500ms bursts=5 0-mismatch TFLOP/s/chip min=1596.8 avg=1609.1 max=1615.2
idle=1000ms bursts=5 0-mismatch TFLOP/s/chip min=1610.3 avg=1616.2 max=1631.6
rc=0 wall_ms=19397

实测耗时:每次运行墙钟 19.4 到 19.7 s(TPU 初始化约 5 s,编译加约 1 GiB 参考输出拷回 host,4 个间隔各 5 个 burst)。

判定标准:rc=0(脚本检查参考输出有限、8 个 device 逐位一致、所有 burst 0 个不一致字);参考输出非零需用打印统计的变体确认(本次 nonzero_frac=1.0)。两套环境均满足。默认作业配置下吞吐 1593.6 到 1632.0 TFLOP/s per chip;性能状态参数的影响见附录 A.2.4。

注意事项:

  • --min-tflops-chip 0 时脚本不会因速度失败;作为门禁使用时需设下限,例如默认作业配置 1450 TFLOP/s per chip(实测最低 1593.6 的约 91%,起始值,按上线后 2 周实测基线调整);TPUMS 基准配置下本脚本未运行,下限需先实测 未验证。
  • 50 到 1000 ms 空闲间隔下没有首个 burst 变慢的现象,每个间隔的最小值都在平均值的 1% 以内 实测。
  • 该输入在 jax 0.9.0 与 0.12.0 上参考输出的 sha256 相同,但这不构成跨版本保证(见附录 A.4.4)实测。
  • per chip 吞吐按 --devices-per-chip 2 换算(TPU7x 每芯片 2 个 TensorCore,即 2 个 JAX device),用于其他芯片时需修改该参数 实测。
↩ 返回需求R-03正文2.2
A.2.4

A.2.4 空闲间隙的性能状态行为#

服务需求R-03实测耗时libtpu 0.0.34 每个 tag 15 s实测

服务需求:R-03(见第 1 章);正文:2.2。

目的:确认 TPU7x 在 50、200、500 ms 的 host 空闲间隙中是否降低性能状态,以及 TPUMS 公开仓库 op_flags.yaml 中性能状态参数的实际作用,用于修正“禁止休眠期降频”的说法。

前置:A.0.4 单机 holder Pod(node-b,TPU_HOST_BOUNDS=1,1,1),A.0.10 的两套环境。性能状态来自 TPUMS gemm_throttling 使用的同一组固件 trace 事件(见附录 A.2.1)。

命令:idle_gap_probe.py 对每个空闲设置执行 8 个 burst(10 次 bf16 8192² matmul 链,每个约 13 到 15 ms),burst 之间 time.sleep(idle),整个过程采集 XProf trace,再从 *.xplane.pb 中解析固件性能状态事件。

bash
# /tmp/v050 环境先执行 /tmp/v050/bin/pip install -q protobuf(解析 xplane.pb 需要)
TPU_HOST_BOUNDS=1,1,1 python3 idle_gap_probe.py --tag default --idle-ms 50 200 500
# 对照组:只把 TPUMS 默认 op_flags.yaml 中 gemm 项里的性能状态参数(1 个)经 LIBTPU_INIT_ARGS 传入,其余 9 个调度/VMEM 参数不传,运行同一脚本,--tag perf
python
opts = jax.profiler.ProfileOptions()
opts.host_tracer_level = 0
opts.advanced_configuration = {
    "tpu_trace_mode": "TRACE_ONLY_XLA", "tpu_num_sparse_cores_to_trace": 0,
    "tpu_num_sparse_core_tiles_to_trace": 0, "tpu_perf_counters": False,
    "tpu_e2e_enable_fw_thermal_event": True, "tpu_e2e_enable_fw_power_level_event": True,
    "tpu_e2e_enable_fw_throttle_event": True, "tpu_power_trace_level": 1}
with jax.profiler.trace(tdir, profiler_options=opts):
    for _ in range(bursts):
        time.sleep(idle / 1000.0)
        t0 = time.time_ns(); f(W).block_until_ready(); t1 = time.time_ns()

裁剪输出(jax 0.12.0、libtpu 0.0.50.1;脚本名、tag 与输出前缀已改写,性能状态取值已隐去):

输出
IDLE_RESULT {"tag": "v050_default", "idle_ms": 50,  "first_vs_median_burst": 1.026, "tflops_chip_median": 1467.9, "pstate_values": {"...": 8},  "pstate_changes_first_plane": 0}
IDLE_RESULT {"tag": "v050_default", "idle_ms": 500, "first_vs_median_burst": 1.001, "tflops_chip_median": 1483.9, "pstate_values": {"...": 8},  "pstate_changes_first_plane": 0}
IDLE_RESULT {"tag": "v050_perf",    "idle_ms": 50,  "first_vs_median_burst": 0.997, "tflops_chip_median": 1660.9, "pstate_values": {"...": 72}, "pstate_changes_first_plane": 0}
IDLE_RESULT {"tag": "v050_perf",    "idle_ms": 500, "first_vs_median_burst": 1.008, "tflops_chip_median": 1647.9, "pstate_values": {"...": 72}, "pstate_changes_first_plane": 0}
环境空闲间隙默认作业配置:中位 TFLOP/s per chip性能状态参数(有):中位 TFLOP/s per chip
jax 0.9.0、libtpu 0.0.3450、200、500 ms1480.1、1500.1、1481.0(无性能状态事件)1649.7、1646.7、1654.5
jax 0.12.0、libtpu 0.0.50.150、200、500 ms1467.9、1460.8、1483.9(默认状态,全程不变)1660.9、1654.8、1647.9(较高工作状态,全程不变)

实测耗时:libtpu 0.0.34 每个 tag 15 s;libtpu 0.0.50.1 默认 tag 74 s(主要是 trace 采集和解析,加参数 tag 未单独计时)。

判定标准:记录每个空闲设置的性能状态取值和变化次数。结果:默认作业配置下性能状态全程不变,每个空闲设置第 1 个 burst 的耗时与中位数之比为 0.993 到 1.026,未观察到空闲降频;只加性能状态参数(gemm 项 10 个参数中的 1 个)后同样全程不变,吞吐高约 10% 到 13%。

注意事项:

  • 该性能状态参数提高的是整个运行的工作点,而不是防止空闲期降频;在不超过 500 ms 的间隙中不存在需要防止的降频 实测。
  • libtpu 0.0.34 不产生固件性能状态事件;0.0.50(TPUMS 环境)与 0.0.50.1 均可读取 实测。
  • XPlane 设备时间戳不是 epoch 时间,无法与 host time.time_ns() 窗口对齐,只能像 TPUMS 一样看最小值、最大值和变化次数 实测。
  • 事件采样较粗(默认作业配置下每 device 每次 trace 1 个事件,加参数后 9 个),只能排除持续性的空闲降频,不能排除亚毫秒级波动;burst 计时同样未显示波动 实测。
  • 本实验每个 burst 只有 10 次 matmul,吞吐低于附录 A.2.2 和 A.2.3 的 30 次链式 GEMM,两者不能直接比较 实测。
↩ 返回需求R-03正文2.2

A.3 CHS(对应 2.3)#

A.3.1

A.3.1 CHS lite 与 standard 实测#

服务需求R-01R-02R-04R-15实测耗时lite 9 min 31 s · standard 17 min 58 s实测

服务需求:R-01、R-02、R-04、R-15(见第 1 章);正文:2.3、3.1、3.2。

目的:在 2x2x2 节点池上实测 CHS 0.3.2 lite 和 standard 套件的真实耗时、实际运行的测试、各测试的数值与门限,并确认 standard 中的 tpu-network-stress 是否无条件运行。

前置:A.0.11(集群内 runner Pod、最小权限 RBAC、带 current-context 的 SA kubeconfig、GCS 存储);整个 TPU 节点池空闲(没有 Pod 申请 google.com/tpu)。两次运行依次进行,standard 紧接 lite。

命令:

bash
kubectl -n $NS exec chs-runner -- bash -c \
  'cd /workspace; nohup chs -v run --nodepools=<NODE_POOL> --suite=lite --run-id=<RUN_ID> -y > /workspace/<RUN_ID>.log 2>&1 < /dev/null &'
# standard 同上,--suite=standard
# CHS 在运行结束时删除自己的 Job,逐测试耗时需在运行期间记录
kubectl -n chs get jobs -o custom-columns=NAME:.metadata.name,START:.status.startTime,DONE:.status.completionTime
# 结束后取回健康报告(Bill of Health)
gcloud storage cp -r gs://<BUCKET>/bills_of_health gs://<BUCKET>/workspaces .

裁剪输出(lite):

输出
CHS Execution Preview: Target Cluster: <CLUSTER>  Machine Type: tpu7x-standard-4t  Nodes under test: 2
  Tests Scheduled: tpu-info, tpu-gemm, tpu-hbm, tpu-host-device, tpu-collectives
12:38:57 Running in-cluster. Assuming auto-approve.
12:39:09 All Jobs submitted successfully. (Elapsed: 11s)
12:39:19 / 12:43:36 / 12:46:48 / 12:47:34 / 12:48:19  Fetching log for completed job (info / gemm / hbm / host-device / collectives)
12:48:24 Interactive health report generated successfully.
12:48:28 Workspace archive uploaded successfully.  CHS CLI finished.
# 健康报告 JSON 摘要(jq 提取,命令见下文注意事项)
tpu-gemm    Throughput  1041.91 950.0   RESULT_STATUS_SUCCESS
tpu-collectives Peak Bandwidth (median) 211.50616489930974  190.0   RESULT_STATUS_SUCCESS

裁剪输出(standard):

输出
Tests Scheduled: tpu-info, tpu-hbm, tpu-gemm, tpu-host-device, tpu-collectives, tpu-compute-stress, tpu-hbm-stress, tpu-network-stress
13:01:53 NODE:<node-b> EVENT:MEASURE_END DURATION:114.55s TFLOPs: 921.48   EVENT:STRESS_PASS
13:05:05 NODE:<node-a> EVENT:MEASURE_END DURATION:161.97s BANDWIDTH_GBPS:6364.07   EVENT:STRESS_PASS
13:06:49 Host: <node-b> | Axis: X | 171.18 GB/s   Axis: Y | 171.01 GB/s   Axis: Z | 170.82 GB/s
13:07:01 Interactive health report generated successfully.   13:07:06 CHS CLI finished.

各测试数值与门限(两个节点各一个值,node-b 和 node-a;门限为基准值 × 0.95,取自健康报告的 validation_criteria):

测试指标与单位lite 实测standard 实测门限结果
tpu-infoJAX device 数(每节点)8、88、8等于 8SUCCESS
tpu-gemmTFLOP/s per device(JAX device,半个芯片)1041.91、1066.96(MFU 90.3%、92.5%)1042.12、1066.86不低于 950SUCCESS
tpu-hbm带宽中位数 GB/s per device3222.3、3222.13221.9、3222.7不低于 3040SUCCESS
tpu-host-deviceH2D、D2H GiB/s(每节点一个结果)H2D 204.8、204.9;D2H 54.5、53.9H2D 206.4、204.5;D2H 53.8、54.1H2D 不低于 182,D2H 不低于 48SUCCESS
tpu-collectivespsum 峰值带宽中位数 GB/s(CHS profiler trace 计时,mesh 4x2x2)211.5、210.8211.5、210.8不低于 190SUCCESS
tpu-compute-stressTFLOP/s per device不运行921.48、920.81不低于 869SUCCESS,STRESS_PASS
tpu-hbm-stressGB/s per chip不运行6364.08、6364.07不低于 6108SUCCESS,STRESS_PASS
tpu-network-stress各轴带宽最小值,CHS 输出标注 GB/s不运行170.82、170.81(X、Y、Z 轴 170.8 到 171.3)不低于 152SUCCESS

耗时:

项litestandard
CLI 墙钟(CHS 日志)9 min 31 s(571 s;含 kubectl 的驱动脚本 582 s)17 min 58 s(1078 s;驱动脚本 1089 s)
suites.yaml 中的 est_time 与 deadline约 5 min,1080 s约 30 min,3600 s
提交12 s11 s
tpu-info10 s8 s
tpu-gemm257 s256 s
tpu-hbm192 s190 s
tpu-host-device46 s44 s
tpu-collectives45 s106 s(standard 扫描更多消息大小,峰值相同)
tpu-compute-stress—143 s(测量段 114.55 s)
tpu-hbm-stress—190 s(测量段 161.97 s)
tpu-network-stress—约 100 s(每轴约 29 s)
报告生成与上传9 s11 s

实测耗时:见上表。测试 Job 严格串行,间隔 1 到 5 s;首次在新节点上运行还需加上 CHS 工作负载镜像的冷拉取(CPU 节点上实测 95 s,TPU 节点未单测,见 A.0.11)。

判定标准:所有测试状态为 RESULT_STATUS_SUCCESS;compute-stress、hbm-stress 记录 EVENT:STRESS_PASS,检测到数据不一致时记录 EVENT:STRESS_FAIL,该节点缺少指标,测试判为失败(compute-stress 的失败行含 SDC (Bit flips) Detected,同时被错误检测器判为硬失败);network-stress 不输出 STRESS 事件,出错轴记为 FAILED: SDC (Bit flips) Detected,由错误检测器判为硬失败。

注意事项:

  • lite 实测 9 min 31 s,不是约 5 min;standard 实测 17 min 58 s,不是约 30 min(2 节点 2x2x2 池)实测。
  • standard 中 tpu-network-stress 无条件调度并运行,所有测试都在 tier 1 中 实测。
  • 各测试单位不同:tpu-gemm、tpu-hbm、tpu-compute-stress 按 JAX device(每芯片 2 个),tpu-hbm-stress 按芯片;tpu-network-stress 的数值标注为 GB/s,按 CHS 源码以 GiB 计算 文档。
  • tpu-collectives 的 psum 与 TPUMS all_reduce 都用设备侧计时(profiler trace 与 XProf)。按 CHS 配置对齐(fp32,16/32/64 MiB,4x2x2,默认性能状态)后,TPUMS 为 191.5/207.1/210.8 GB/s per chip(固定性能状态时 191.8/207.0/210.8),64 MiB 时与 CHS 一致。TPUMS 默认配置的数值不能套用 CHS 门限(见 2.3.4)实测。
  • CHS 在运行结束时删除自己的 Job;逐测试耗时只能从 CHS 调试日志(Fetching log for completed job)或运行期间的 kubectl -n chs get jobs 获得 实测。
  • 非 TTY 下 chs results 只输出报告链接。指标和逐指标判定在健康报告 JSON 的 test_results[].metrics[].validation_criteria(expected_value、result_status)中,可用下面的命令提取(在下载健康报告 JSON 的机器上执行,chs:0.3.2 runner 镜像不含 jq)实测。
bash
jq -r '.test_results[] | .test_name as $t | .metrics[] | select(.validation_criteria) | [$t, .key, .value, .validation_criteria.expected_value, .validation_criteria.result_status] | @tsv' <workspace>.json
↩ 返回需求R-01 R-02 R-04 R-15正文2.3 3.1 3.2
A.3.2

A.3.2 CHS CLI 与集群内运行#

服务需求R-01实测耗时全部 help 命令约 15 s实测

服务需求:R-01(见第 1 章);正文:2.3。

目的:记录 CHS 0.3.2 chs CLI 的实际帮助文本,并说明在集群内(runner Pod)运行 CHS 时与 README 用法的差异和必需的修正。

前置:A.0.11(runner Pod、RBAC、SA kubeconfig、GCS 存储)。CLI 查询不需要 TPU。

命令(在 runner Pod 内执行):

bash
chs --version; chs --help; chs run --help; chs list suites --tpu; chs list tests --tpu
chs list machine-types; chs list schedulers; chs cancel --help; chs configure storage show

裁剪输出:

输出
$ chs --version
chs 0.3.2
$ chs list suites --tpu
  Name       Est. Time   Description                              Tests
  lite       ~5 mins     Quick health check.                      tpu-info, tpu-gemm, tpu-hbm, tpu-host-device, tpu-collectives
  standard   ~30 mins    Thorough network & collective testing.   tpu-info, tpu-hbm, tpu-gemm, tpu-host-device, tpu-collectives, tpu-compute-stress,
                                                                  tpu-hbm-stress, tpu-network-stress
$ chs run --help   (options)
  -s, --suite SUITE_NAME   lite or standard (default lite)        -t, --tests TEST_LIST
  --nodes NODE_LIST        Note: Individual nodes are NOT supported for TPUs. Please use --nodepools instead.
  --nodelists / --partitions (Slurm)   --nodepools NODEPOOL_LIST (recommended and required way to target TPU resources)
  -y, --auto-approve       --run-id TEXT
  Supported TPU benchmarks: tpu-collectives, tpu-compute-stress, tpu-gemm, tpu-hbm, tpu-hbm-stress, tpu-host-device, tpu-info, tpu-network-stress
$ chs list machine-types   ... ct6e-standard-4t, tpu7x-standard-4t(另有 6 种 GPU 机型)
$ chs list schedulers      kubernetes, slurm
$ chs cancel --help
  --all               Cancel EVERY CHS run on the cluster, including runs started by other users, and delete all CHS resources.
# 集群内首次运行(未做 kubeconfig 修正)
ERROR : Failed to retrieve cluster name from the scheduler.
# 修正后
Running in-cluster. Assuming auto-approve.

子命令:run、list {suites,tests,schedulers,machine-types} [--tpu|--gpu]、results [RUN_ID]、history(最近 5 次)、cancel [RUN_ID] [--all] [-y]、configure storage {gcs <bucket>, show, remove}。

集群内运行与 README 用法的差异:

项README 用法集群内 runner Pod
运行位置工作站上 docker run ... chs:latest(本文固定为 chs:0.3.2),挂载 ~/.kube 和 gcloud 凭据CPU 节点上长期运行的 Pod(镜像 us-docker.pkg.dev/gce-ai-infra/chs/chs:0.3.2,sleep infinity),CHS 检测到 KUBERNETES_SERVICE_HOST 后自动确认
权限用户自己的 kubeconfig专用 ServiceAccount 加最小权限 RBAC(A.0.11),比镜像自带 Helm chart 的集群级 create/delete 窄
集群名从 kubeconfig context 解析从节点标签 container.googleapis.com/cluster_name 或 kubeconfig current-context 解析;验证集群节点无该标签,首次运行 1 s 失败,需提供带 current-context 的 SA kubeconfig(建议 context 名用 gke_<PROJECT>_<LOCATION>_<CLUSTER>,CHS 取最后一段为集群名;见 A.0.11)
GCS 访问用户 gcloud 凭据节点 SA(metadata server);启用 Workload Identity Federation for GKE 时为 runner 的 KSA 身份

实测耗时:全部 help 命令约 15 s;chs configure storage gcs <BUCKET> 3 s(写入一个探测对象);集群内首次运行在未修正 kubeconfig 时 1 s 失败。

判定标准:保存 CLI 原始帮助文本;修正后 kubectl auth whoami 在 runner Pod 内返回 runner 的 ServiceAccount,chs run 打印 Running in-cluster. Assuming auto-approve. 并开始提交测试 Job。

注意事项:

  • TPU 只能用 --nodepools 指定目标,--nodes 不支持 TPU 实测。
  • --run-id X 会被追加 4 个随机字符(如 X-3nai),chs results 需使用完整 ID 实测;chs cancel 同样按完整 ID 匹配 文档。
  • chs run 前必须配置 GCS bucket;集群内运行时用节点 SA 访问 bucket(验证项目中默认 compute SA 已有项目级 storage 角色,未做 IAM 变更)实测;启用 Workload Identity Federation for GKE 的节点池上 runner Pod 以其 KSA 身份访问 GCS,需另行授权(见 A.0.11)文档。
  • 共享集群上禁止 chs cancel --all,它会取消其他用户的运行并删除 chs 命名空间;只取消自己的完整 run ID 文档。
  • chs 进程必须在整个运行期间保持存活,它负责逐个放行挂起的测试 Job(客户端 gang 准入,超时 300 s);在 runner Pod 内用 nohup 启动 实测。
  • lite 包含 tpu-host-device,与 chs list suites --tpu 一致 实测。
↩ 返回需求R-01正文2.3
A.3.3

A.3.3 CHS 自带微基准镜像内容核查#

服务需求R-01实测耗时冷拉取时 Pod 调度到容器启动 95 s实测

服务需求:R-01(见第 1 章);正文:2.3。

目的:核实 CHS 实际使用的微基准镜像 us-docker.pkg.dev/gce-ai-infra/chs/accelerator-microbenchmarks:1.1.1 的软件版本和目录结构,判断能否在其中调用 TPUMS 2.0 tpums CLI 或旧版 JAX API。

前置:A.0.2。在 CPU 节点池运行,不申请 TPU。

命令(Pod 要点:nodeSelector cloud.google.com/gke-nodepool: <CPU_NODE_POOL>,restartPolicy: Never,镜像如上):

bash
pwd; head -2 /etc/os-release; python3 --version; which tpums tpu-info python3 pip
ls /app/accelerator-microbenchmarks /app/accelerator-microbenchmarks/Ironwood/configs
pip list 2>/dev/null | grep -E '^(jax|jaxlib|libtpu|tpu-info|numpy|flax|xprof) '
python3 -c "import jax; print('device_put_replicated', hasattr(jax, 'device_put_replicated'))"
tpu-info --version

裁剪输出(2026-11-03 12:12 UTC):

输出
/app/accelerator-microbenchmarks
PRETTY_NAME="Debian GNU/Linux 13 (trixie)"   Python 3.12.15
which: /usr/local/bin/tpu-info /usr/local/bin/python3 /usr/local/bin/pip      # 无 tpums
ls: Dockerfile Ironwood LICENSE README.md configs docs requirements.txt src
Ironwood/configs: collectives hbm host_device inference throttling training
flax 0.12.7  jax 0.11.1  jaxlib 0.11.1  libtpu 0.0.48  numpy 2.5.4  tpu-info 0.14.2  xprof 2.24.0
device_put_replicated False
tpu-info version: 0.14.2, libtpu version: 0.0.48, accelerator type: unknown (no TPU chips found)

镜像 digest sha256:aec7783d2a0d67b8363187a4df1fe96d9de9a341a7218db580621e087562737d。

实测耗时:冷拉取时 Pod 调度到容器启动 95 s;容器内命令 4 s。

判定标准:jax 0.11.1、libtpu 0.0.48、Python 3.12.15、tpu-info 0.14.2,无 tpums,旧版 TPUMS 目录布局。

注意事项:

  • 镜像为 TPUMS 1.x 布局,没有 tpums CLI;运维脚本不能在 CHS 镜像内调用 tpums,需按 A.0.7 安装或自建镜像 实测。
  • jax 0.11.1 已无 jax.device_put_replicated,依赖它的脚本(如上一版报告脉冲脚本,见附录 A.2.2)无法运行 实测。
  • 冷拉取约 95 s,批量验收前应预拉镜像或计入时间预算 实测。
↩ 返回需求R-01正文2.3

A.4 libtpu SDC 检测(对应 2.4)#

A.4.1

A.4.1 libtpu flag 矩阵#

服务需求R-04实测耗时holder Pod Ready 3 s实测

服务需求:R-04(见第 1 章);正文:2.4。

目的:验证 LIBTPU_INIT_ARGS 中的未知 flag 是否中止作业,确认上一版报告 ICI SDC flag 块中哪些 flag 真实存在,上一版报告所列的 SparseCore embedding 确定性参数从哪个 libtpu 版本开始可用,以及 11 个诊断 flag 组合和 5 个 XSC flag 组合是否被接受。

前置:A.0.4 单机 holder Pod(TPU_HOST_BOUNDS=1,1,1),A.0.10 的三套 libtpu 环境(0.0.34、0.0.50.1、0.0.51)。

命令:每个用例为一个新进程。

bash
LIBTPU_INIT_ARGS="<flags>" TPU_HOST_BOUNDS=1,1,1 timeout 180 python3 -c "import jax; d=jax.devices(); print('DEVICES', len(d), d[0].platform, d[0].device_kind)"; echo rc=$?

用例:无 flag;性能状态参数(取自 TPUMS 公开仓库 op_flags.yaml,作对照);上一版报告 ICI 块整体及其 10 个 flag 逐个;SparseCore embedding 确定性参数(下文记为 <SC 确定性参数>);11 个诊断 flag 组合;5 个 XSC flag 组合(其中 SparseCore SDC checker 参数记为 <SC SDC checker 参数>)。

bash
# 上一版报告 ICI 块(10 个,其中 9 个不存在,仅作反例,勿使用)
--xla_tpu_enable_ici_sdc_test_on_startup=true --xla_tpu_ici_sdc_test_run_count=1 --xla_tpu_ici_sdc_test_iterations=10
--xla_tpu_ici_sdc_test_packet_size=4KB --xla_tpu_ici_sdc_test_Log_level=0 --xla_tpu_ici_sdc_test_timeout_secs=60
--xla_tpu_ici_sdc_test_random_payload=true --xla_tpu_ici_sdc_test_verify_checksum=true
--xla_tpu_ici_sdc_test_fail_on_error=true --xla_tpu_ici_sdc_test_enable_all_links=true
# 11 个诊断 flag 组合
--xla_tpu_enable_sdc_checker=true --xla_tpu_sdc_check_repeat_count=0 --xla_tpu_sdc_check_halt_on_detection=false
--xla_tpu_ici_sdc_test_run_on_program_start=true --xla_tpu_ici_sdc_test_iterations=5000 --xla_tpu_ici_sdc_test_max_distance=1
--xla_tpu_ici_sdc_test_pipeline_depth=13 --xla_tpu_ici_sdc_test_buffer_size_chunks=256 --xla_tpu_ici_sdc_test_packet_size_chunks=256
--xla_tpu_ici_sdc_test_sflag_wait_timeout_ms=5 --xla_tpu_enable_log_recorder=true
# 5 个 XSC flag 组合(上一版报告)
--xla_tpu_enable_sdc_checker=true --xla_tpu_sdc_check_repeat_count=1 --xla_tpu_sdc_check_halt_on_detection=true
--xla_tpu_sdc_check_inputs=true <SC SDC checker 参数>

裁剪输出(libtpu 0.0.34,node-a;0.0.50.1、0.0.51 模式相同):

输出
case=F0_none rc=0 wall=5.2s
    DEVICES 8 tpu TPU7x
case=F1_fabricated_run_count rc=1 wall=0.4s
    ERROR: Unknown command line flag 'xla_tpu_ici_sdc_test_run_count'
case=F2_report_321_block rc=1 wall=0.4s
    ERROR: Unknown command line flag 'xla_tpu_enable_ici_sdc_test_on_startup'
    ERROR: Unknown command line flag 'xla_tpu_ici_sdc_test_run_count'
    ERROR: Unknown command line flag 'xla_tpu_ici_sdc_test_packet_size'
    ...  # 采集时截取前 4 行;逐个测试时每个未知 flag 各报一行
case=F3_report_single --xla_tpu_ici_sdc_test_iterations rc=0 wall=5.2s
case=F4_<SC 确定性参数> rc=1 wall=0.4s
    ERROR: Unknown command line flag '<SC 确定性参数>'
case=F5_diag11_set rc=0 wall=5.2s
case=F6_report_xsc5_set rc=0 wall=5.1s
# libtpu 0.0.51
case=F4_<SC 确定性参数> rc=0 wall=5.5s
    DEVICES 8 tpu TPU7x
flag 组合libtpu 0.0.340.0.50.10.0.51
上一版报告 ICI 块(10 个 ICI flag 加 SparseCore embedding 确定性参数)rc=1rc=1rc=1
10 个 ICI flag 逐个9 个未知,仅 iterations 可用同左同左
SparseCore embedding 确定性参数未知未知接受
11 个诊断 flag 组合接受接受接受
5 个 XSC flag 组合接受接受接受
性能状态参数(TPUMS op_flags.yaml 默认带入)接受接受接受

实测耗时:holder Pod Ready 3 s;venv 安装 15 到 36 s(0.0.50.1)、30 到 32 s(0.0.51);未知 flag 0.4 s 内退出;可接受的 flag 5.1 到 5.5 s(import jax 加 TPU 初始化);每个环境整个矩阵约 70 s。

判定标准:未知 flag 返回 rc≠0 并输出 ERROR: Unknown command line flag;真实 flag 返回 rc=0 且 8 个 device 可见。

注意事项:

  • 中止发生在 libtpu 解析 flag 阶段,早于任何 TPU 操作,不会回退到 CPU;LIBTPU_INIT_ARGS 中只要有一个拼错或不存在的 flag,作业的每个 Pod 都会在首次初始化 TPU 后端时失败(最小探针中为启动后 0.4 s)。上线新 flag 前先用上面的一行命令在目标镜像上验证 实测。
  • 上一版报告 ICI 块的 10 个 flag 中只有 --xla_tpu_ici_sdc_test_iterations 存在,其余 9 个在三个版本上都是未知 flag,整块使用会导致每个作业启动失败 实测。
  • 在测试的三个版本中只有 libtpu 0.0.51 接受 SparseCore embedding 确定性参数(0.0.34、0.0.50.1 为未知 flag);该参数无公开文档,本文不列出名称 实测。
  • 本实验用 pip install --no-deps libtpu==0.0.51 安装;不加 --no-deps 也可安装,已安装 TPUMS 时 pip 会提示 tpu-sync-jax 要求 0.0.50 实测。
↩ 返回需求R-04正文2.4
A.4.2

A.4.2 ici-sdc-test:真实 flag 的每步开销与日志位置#

服务需求R-04R-12实测耗时Job 两个 Pod Ready 5 s实测含未验证

服务需求:R-04、R-12(见第 1 章);正文:2.4、3.5.3。

目的:在整个 2x2x2 slice 上测量真实 ICI SDC 测试 flag 对每个训练步的开销,并确定 IciSdcTest :: ICI BW 日志行出现的位置。上一版报告的 ICI flag 块中 9 个 flag 不存在(见 A.4.1),本实验只使用真实 flag。

前置:A.0.5 多机 Indexed Job(GKE 注入多机变量),A.0.10。镜像默认环境 jax 0.9.0、libtpu 0.0.34。

命令:与 A.0.5 run_mh.sh 相同,用两个并发 kubectl exec 在两个 Pod 中同时启动 ici_bench.py:jax.distributed.initialize() 后,对 16 个 device 做 jit 的 shard_map psum,每 device 8 MiB bf16,编译和 1 次预热后计时 50 步。

bash
# A:无 flag
LIBTPU_INIT_ARGS=""
# B:11 个诊断 flag 组合
LIBTPU_INIT_ARGS="--xla_tpu_enable_sdc_checker=true --xla_tpu_sdc_check_repeat_count=0 --xla_tpu_sdc_check_halt_on_detection=false \
   --xla_tpu_ici_sdc_test_run_on_program_start=true --xla_tpu_ici_sdc_test_iterations=5000 --xla_tpu_ici_sdc_test_max_distance=1 \
   --xla_tpu_ici_sdc_test_pipeline_depth=13 --xla_tpu_ici_sdc_test_buffer_size_chunks=256 --xla_tpu_ici_sdc_test_packet_size_chunks=256 \
   --xla_tpu_ici_sdc_test_sflag_wait_timeout_ms=5 --xla_tpu_enable_log_recorder=true"
# C:只开 run_on_program_start,其余取默认值
LIBTPU_INIT_ARGS="--xla_tpu_ici_sdc_test_run_on_program_start=true"
# D:同 B,但 --xla_tpu_ici_sdc_test_iterations=10
# 读取诊断日志行:覆盖容器内所有 libtpu 进程的日志文件
kubectl -n $NS exec <POD> -- bash -c 'grep -h "IciSdcTest\|XLA_SDC_CHECKER\|HLO is instrumented\|ICI transfer wait\|Wait timeout on sflag" $TPU_LOG_DIR/tpu_driver.*.log.INFO.*'

裁剪输出(Pod 0):

输出
case A  step_ms_median 0.56   compile_s 0.73  ICI BW lines 0
case B  step_ms_median 228.62 compile_s 0.81  ICI BW lines 408 (per host)
  I1103 12:28:35.377108 llo_sdc_checker_emitters.cc:381] IciSdcTestEmitter :: Emitting code for buffer_size_chunks:256 packet_size_chunks:256
        iterations:5000 max_neighbors:6 max_distance:1 pipeline_depth:13 pipeline_factor:14 delay_mask:0
  I1103 12:28:36.224962 llo_log_report_handler.cc:679] [<prefix>.0x1x0_TC0@1]: IciSdcTest :: ICI BW: 130 (GiB/s), clock: 1900 (MHz), data: 30000 (MiB),
        time: 224 (ms), delay iterations: -1
case C  step_ms_median 0.576  compile_s 0.69  ICI BW lines 0 (1 emitter line: buffer 32, packet 4, iterations 10, pipeline_depth 4)
case D  step_ms_median 1.973  compile_s 0.79  ICI BW lines 408
  [<prefix>.1x1x0_TC1@1]: IciSdcTest :: ICI BW: 122 (GiB/s), clock: 1900 (MHz), data: 60 (MiB), time: 0 (ms), delay iterations: -1
stderr lines (all cases): 0
用例每步中位数相对 A 的增量ICI BW 行
A 无 flag0.56 ms—0
C 只开 run_on_program_start0.576 ms无可测开销(在波动范围内)0
D 诊断组合,iterations=101.97 ms+1.4 ms每 host 每步 8 行
B 诊断组合,iterations=5000228.6 ms+228 ms每 host 每步 8 行

日志位置:

位置是否出现 IciSdcTest 行
$TPU_LOG_DIR/tpu_driver.INFO(/tmp/tpu_logs/main/)是,I 级别,llo_log_report_handler.cc:679
容器 stderr(默认 TPU_STDERR_LOG_LEVEL)否,所有用例 0 行
Cloud Logging sidecar-log-collector未找到:sidecar 只转发了容器内第一个 libtpu 进程(用例 A)的日志,后续进程新建的 tpu_driver.*.INFO.<pid> 文件未被转发(同时间窗 332 行,0 行 IciSdcTest)

实测耗时:Job 两个 Pod Ready 5 s;每个用例墙钟 9 到 22 s(初始化 0.4 到 2.5 s,编译 0.7 到 0.8 s,51 次执行);4 个用例合计约 2 min TPU 时间。

判定标准:记录各用例的每步开销和日志位置;开启诊断组合后,ICI BW 行为每个 TensorCore 每步一行(每 host 8 行,标签形如 [<prefix>.<x>x<y>x<z>_TC<n>@<k>],<prefix> 为主机名前缀,<k> 为程序执行序号)。

注意事项:

  • --xla_tpu_ici_sdc_test_run_on_program_start=true 会把测试插入每个编译出的多核程序,即每一步都执行,而不是只在启动时执行一次;单步含多个 jit 程序时开销叠加 未验证。开销随 iterations 增长:10 次 +1.4 ms/步,5000 次 +228 ms/步,固定开销与每次迭代的开销未分离。只在诊断运行中短时开启,不常驻 实测。
  • 只开 run_on_program_start(用例 C)时不输出 ICI BW 行;同时设置 xla_tpu_enable_log_recorder 和 SDC checker 的用例 B、D 每步输出 8 行 实测。
  • 本负载(单个 psum 程序)编译时间无可测变化(0.69 到 0.81 s);大模型上的编译开销未测 实测。
  • 这些行只在节点本地的 tpu_driver.INFO 中,要集中收集需在作业内自行转发,或保证训练进程是容器内第一个 libtpu 进程:sidecar 只转发每个容器第一个 libtpu 进程的日志(见附录 A.7.3)实测。
↩ 返回需求R-04 R-12正文2.4 3.5.3
A.4.3

A.4.3 XSC(XLA SDC checker)#

服务需求R-04实测耗时每个用例墙钟 11.7 到 14.9 s(初始化 4.7 到 4.9 s,编译 1.5…实测含未验证

服务需求:R-04(见第 1 章);正文:2.4、3.5.5。

目的:验证 XSC 的启用方式、HLO is instrumented (HLO rerun) 标记、[XLA_SDC_CHECKER] ... checksum does not match 消息、步时开销,以及通过 compiler_options 按编译粒度启用。

前置:A.0.4 单机 holder Pod(node-b,TPU_HOST_BOUNDS=1,1,1,TPU_MIN_LOG_LEVEL=0),A.0.10 的 libtpu 0.0.34 和 0.0.50.1 环境。

命令:xsc_bench.py 在 8 个本地 device 上 vmap 一个 20 次 bf16 8192² matmul 链,预热 1 次后计时 50 步,每个用例一个新进程,结束后 grep $TPU_LOG_DIR/tpu_driver.INFO。

bash
# a:无 flag
LIBTPU_INIT_ARGS="" python3 xsc_bench.py
# b:XSC
LIBTPU_INIT_ARGS="--xla_tpu_enable_sdc_checker=true" python3 xsc_bench.py
# c:上一版报告 5 个 flag
LIBTPU_INIT_ARGS="--xla_tpu_enable_sdc_checker=true --xla_tpu_sdc_check_repeat_count=1 --xla_tpu_sdc_check_halt_on_detection=true \
  --xla_tpu_sdc_check_inputs=true <SC SDC checker 参数>" python3 xsc_bench.py
# d:另用客户不可用的内部调试机制注入校验和不一致,此处不列出
LIBTPU_INIT_ARGS="--xla_tpu_enable_sdc_checker=true --xla_tpu_sdc_check_halt_on_detection=false" python3 xsc_bench.py
# e:按编译粒度启用
python3 xsc_bench.py --per-compile
grep -ci 'instrumented' /tmp/tpu_logs/main/tpu_driver.INFO; grep -c 'HLO is instrumented' /tmp/tpu_logs/main/tpu_driver.INFO
grep -c 'XLA_SDC_CHECKER' /tmp/tpu_logs/main/tpu_driver.INFO
python
# 用例 e:同一个 lowered 程序编译两次,c1 开启 XSC,每 10 步用一次 c1
lowered = jax.jit(jax.vmap(step), out_shardings=shard).lower(W, X)
c0 = lowered.compile()
c1 = lowered.compile(compiler_options={"xla_tpu_enable_sdc_checker": True})
for i in range(steps):
    fn = c1 if i % 10 == 0 else c0
    out = fn(W, X)

裁剪输出(jax 0.9.0、libtpu 0.0.34):

输出
=== case=a_none        step_ms_median 27.86  compile_s 1.97   instrumented INFO: 0
=== case=b_xsc         step_ms_median 57.81  compile_s 1.81   instrumented INFO: 16
  I1103 12:15:26.222972 llo_sdc_checker_code_processor.cc:1410] HLO is instrumented (HLO rerun) :: copy
  W1103 12:15:26.187782 llo_sdc_checker_code_processor.cc:1051] HLO is NOT instrumented (HLO rerun) :: ENTRY parameter() with HLO rerun :: param
  W1103 12:15:26.022935 tpu_plumb_vmem_info.cc:183] Scavenging is being disabled. INVALID_ARGUMENT: (AGGRESSIVE) Vmem scavenging is not allowed
        when ... --xla_tpu_enable_sdc_checker is enabled.
=== case=c_report_xsc5 step_ms_median 64.51
=== case=d_xsc_inject  step_ms_median 57.83  rc=0   XLA_SDC_CHECKER INFO: 424  stderr: 0
  W1103 12:15:53.546369 sdc_checker_report.cc:241] [XLA_SDC_CHECKER] chip [0x1x0_TC0] host [<host>] ::> OUTPUT data checksum does not match :: fusion, HLO :: ...
=== case=e_percompile  c0 27.73 ms; c1 (compiler_options) 57.72 ms ratio 2.082, extra compile 1.54 s; c1 every 10th step: mean 30.8 ms
用例libtpu 0.0.34 每步(倍数)libtpu 0.0.50.1 每步(倍数)tpu_driver.INFO 中的标记行数(instrumented 按 grep -ci instrumented 计,含 HLO is NOT instrumented 行)
a 无27.86 ms(1.00)27.93 ms(1.00)0
b XSC57.81 ms(2.08)58.18 ms(2.08)含 instrumented 16 到 25 行(其中 HLO is instrumented (HLO rerun) 9 行,libtpu 0.0.34)
c 上一版报告 5 个 flag64.51 ms(2.32)65.34 ms(2.34)16 到 32 行
d XSC 加故障注入57.83 ms(2.08)58.19 ms(2.08)424 行 [XLA_SDC_CHECKER] ... OUTPUT data checksum does not match
e compiler_optionsc1 为 2.082 倍;每 10 步一次时平均 30.8 ms(+11%)2.079 倍;平均 31.1 ms(+11%)7 到 14 行(仅 c1)

无 XSC 时该负载为 1578.6 TFLOP/s per chip(中位数),开启 XSC 后 760.7 TFLOP/s per chip 实测。

实测耗时:每个用例墙钟 11.7 到 14.9 s(初始化 4.7 到 4.9 s,编译 1.5 到 3.2 s,51 步);用例 e 18.5 到 19.4 s;每个环境 5 个用例合计约 70 s。

判定标准:只有开启 XSC 时出现 instrumented 标记(用例 a 为 0);只有故障注入时出现不一致消息;开销实测为 2.08 倍,上一版报告 5 个 flag 组合为 2.32 到 2.34 倍。

注意事项:

  • 所有 XSC 日志行只写入 tpu_driver.INFO;默认 TPU_STDERR_LOG_LEVEL 下容器 stderr 为 0 行,依赖 stderr 或 kubectl logs 的告警看不到 XSC 结果 实测。
  • halt_on_detection=false 时作业在出现不一致后继续运行(rc=0)并持续记录 实测。用例 d 的不一致由客户不可用的内部调试机制注入;客户侧演练告警链路需要另找用户可用的注入方法 未验证。
  • 环境变量方式开启时,编译时间在 libtpu 0.0.34 上不变(1.5 到 2.0 s),在 0.0.50.1 上从 1.75 s 增至 3.1 到 3.2 s;compiler_options 方式额外编译 1.54 s(0.0.34)和 2.86 s(0.0.50.1)实测。
  • XSC 插桩后的可执行文件输出与未插桩版本不逐位相等(两个版本均如此);XSC 开启时日志显示 VMEM scavenging 被关闭,代码生成不同是可能原因;不能用 XSC 开与关的输出是否相等作为 SDC 信号 实测。
  • 本实验中开启 XSC 的用例均出现 Scavenging is being disabled ... 警告,不影响运行结果 实测。
↩ 返回需求R-04正文2.4 3.5.5
A.4.4

A.4.4 逐位确定性#

服务需求R-04实测耗时每个进程 9.2 到 9.8 s(初始化、编译、运行、计算哈希)实测

服务需求:R-04(见第 1 章);正文:2.4。

目的:确认同一程序在相同软件栈下,同节点重复运行、跨节点运行的输出是否逐位一致,以及升级 libtpu 或 jax 后是否还能一致。

前置:A.0.4 两个节点各一个 holder Pod(TPU_HOST_BOUNDS=1,1,1,各为 2x2x1 子 slice),A.0.10 的三套环境。

脚本 det.py(bf16 matmul 加 gelu,按 8 个本地 device 分片,求和时跨 device all-reduce;输出编译后 HLO 文本和结果的 sha256):

python
import jax, jax.numpy as jnp, numpy as np, hashlib, libtpu
from jax.sharding import Mesh, NamedSharding, PartitionSpec as P
mesh = Mesh(np.array(jax.devices()), ('d',))
x = jax.device_put(jax.random.normal(jax.random.key(0), (8 * 1024, 4096), jnp.bfloat16), NamedSharding(mesh, P('d', None)))
w = jax.random.normal(jax.random.key(1), (4096, 4096), jnp.bfloat16)
f = jax.jit(lambda x, w: jnp.sum(jax.nn.gelu(x @ w).astype(jnp.float32), axis=0))
c = f.lower(x, w).compile(); out = np.asarray(c(x, w))
print("VER", jax.__version__, libtpu.__version__)
print("HLO", hashlib.sha256(c.as_text().encode()).hexdigest())
print("OUT", hashlib.sha256(out.tobytes()).hexdigest())
print("COORDS", [tuple(d.coords) + (d.core_on_chip,) for d in jax.devices()])

命令:每个环境在同一节点上以两个独立进程各运行一次,另一节点同样执行。

bash
kubectl -n $NS exec sh-node-a -- bash -c 'export TPU_HOST_BOUNDS=1,1,1; for v in /opt/venv /tmp/v050 /tmp/v051; do for i in 1 2; do $v/bin/python3 /tmp/det.py; done; done'
kubectl -n $NS exec sh-node-b -- bash -c 'export TPU_HOST_BOUNDS=1,1,1; for v in /opt/venv /tmp/v050; do for i in 1 2; do $v/bin/python3 /tmp/det.py; done; done'

裁剪输出(哈希截断显示):

输出
--- /tmp/v050 run1 host=sh-node-a   VER 0.12.0 0.0.50.1  HLO acb82c6a...8bc0  OUT e8d7cf47...dfbf5
--- /tmp/v050 run2 host=sh-node-a   VER 0.12.0 0.0.50.1  HLO acb82c6a...8bc0  OUT e8d7cf47...dfbf5
--- /tmp/v050 run1 host=sh-node-b   VER 0.12.0 0.0.50.1  HLO acb82c6a...8bc0  OUT e8d7cf47...dfbf5
--- /opt/venv run1 host=sh-node-a   VER 0.9.0 0.0.34     HLO a4c4eb75...f939  OUT db2d9686...d285
--- /opt/venv run1 host=sh-node-b   VER 0.9.0 0.0.34     HLO a4c4eb75...f939  OUT db2d9686...d285
--- /tmp/v051 run1 host=sh-node-a   VER 0.12.0 0.0.51    HLO 7c637f91...2a36  OUT e8d7cf47...dfbf5
COORDS [(0, 0, 0, 0), (0, 0, 0, 1), (1, 0, 0, 0), (1, 0, 0, 1), (0, 1, 0, 0), (0, 1, 0, 1), (1, 1, 0, 0), (1, 1, 0, 1)]   # 两个节点相同
软件栈运行HLO sha256输出 sha256结论
jax 0.12.0、libtpu 0.0.50.1node-a 2 次、node-b 2 次acb82c6a9c88...e8d7cf47ca91...同节点、跨节点全部一致
jax 0.9.0、libtpu 0.0.34node-a 2 次、node-b 2 次a4c4eb7534bd...db2d9686df74...同节点、跨节点全部一致
jax 0.12.0、libtpu 0.0.51node-a 2 次7c637f91e3c2...e8d7cf47ca91...两次一致;输出与 0.0.50.1 相同,HLO 文本不同

实测耗时:每个进程 9.2 到 9.8 s(初始化、编译、运行、计算哈希)。

判定标准:相同软件栈下同节点重复运行输出 sha256 相同(3 套环境均满足);跨节点 HLO 和输出 sha256 相同(2 套环境均满足)。

注意事项:

  • libtpu 0.0.50.1 升级到 0.0.51 后输出相同但优化后的 HLO 文本不同;jax 0.9/libtpu 0.0.34 换成 jax 0.12/libtpu 0.0.50.1 后输出改变(两者同时变化,无法归因)。跨 worker 或跨时间比较校验和时必须固定整个软件栈(镜像 digest、jax、libtpu),对应附录 A.9.1 起飞前检查第 8 步的 fingerprint 实测。
  • 两个节点的子 slice 本地 coords 相同,因此同一程序在两个节点上的设备布局一致 实测。
  • 本结论只适用于这个稠密计算程序,不涉及 SparseCore embedding(测试的三个版本中只有 libtpu 0.0.51 接受 SparseCore embedding 确定性参数,见附录 A.4.1)实测。
  • XSC 插桩后的程序与未插桩程序输出不逐位相等(见附录 A.4.3),确定性比较不能跨 XSC 开关进行 实测。
↩ 返回需求R-04正文2.4

A.5 带内 15 s 遥测(对应 2.5)#

A.5.1

A.5.1 15 s 带内采集器部署与指标清单#

服务需求R-06实测耗时两个 TPU 节点上 apply 到 DaemonSet Pod 全部 Ready 6…实测

服务需求:R-06(见第 1 章);正文:2.5。

目的:以最小权限在独立命名空间部署 15 s 采集器配置(客户仓库 ai-telemetry-collector-15s.yaml,镜像 ai-telemetry-collector 0.1.4,内含 OpenTelemetry Collector contrib v0.159.0),确认它在 :2113 实际导出的指标名与标签,以及 Managed Service for Prometheus(GMP)中的采样间隔和入库延迟。

前置:A.0.2;命名空间中需要有 TPU 负载(本实验为附录 A.11.1 的 2 Pod Job,容器名 straggler)。与原文件相比的改动:

项原文件本实验原因
命名空间与 SAkube-system,复用有 node update/patch 权限的 tpu-device-plugin-satpu-verify,专用 SA最小权限
Pod 发现范围k8s_observer 监视所有命名空间namespaces: [tpu-verify]只看本命名空间
receiver 规则排除 kube-system 等 8 个命名空间namespace == "tpu-verify" && labels["k8s-app"] != "ai-telemetry-collector-15s"只抓实验 Pod,并排除采集器自身
k8s_attributes集群范围 Pod informerfilter: {namespace: tpu-verify}Role 即可读 Pod
优先级system-node-critical删除实验 Pod 不抢占
GMP 对象ClusterPodMonitoring命名空间内 PodMonitoring(endpoint、15 s interval、targetLabels.metadata: [node] 相同)不建集群级对象

镜像 digest、receiver、processor、OTTL 改名、allowlist、0.0.0.0:2113 exporter、metric_expiration: 1m、privileged root 和 15 s 间隔与原文件相同 实测。

命令:

yaml
# 最小 RBAC:命名空间内 Role(pods)+ ClusterRole(只读 nodes)
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata: {name: tpu-collector, namespace: tpu-verify}
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata: {name: tpu-collector}
rules:
- apiGroups: [""]
  resources: ["nodes"]
  verbs: ["get", "list", "watch"]
# 另需 ServiceAccount 与 RoleBinding、ClusterRoleBinding 把两者绑定到采集器 SA
bash
kubectl apply -f manifest_rbac.yaml -f manifest_rbac_cluster_nodes.yaml -f manifest_collector_ns.yaml
kubectl -n tpu-verify rollout status ds/ai-telemetry-collector-15s --timeout=180s
kubectl -n tpu-verify get podmonitoring ai-telemetry-collector-15s -o jsonpath='{.status}'
# 镜像为 distroless,没有 shell,用 port-forward 读 :2113
P=$(kubectl -n tpu-verify get pod -l k8s-app=ai-telemetry-collector-15s --field-selector spec.nodeName=<node-b> -o name)
kubectl -n tpu-verify port-forward $P 22113:2113 & sleep 3
curl -s localhost:22113/metrics | grep -v '^#' | sed 's/{.*//' | sort | uniq -c
PromQL
avg by (node)(duty_cycle{cluster="<CLUSTER>"})
avg by (node)(tensorcore_utilization_node{cluster="<CLUSTER>"})
sum by (node, pod)(memory_used{cluster="<CLUSTER>", exported_namespace="tpu-verify"}) / 2^30
histogram_quantile(0.5, sum by (node, le)(rate(hlo_execution_timing_microsecond_bucket{cluster="<CLUSTER>"}[1m])))

裁剪输出(2026-11-03 13:22 UTC,基线阶段,worker 1):

输出
# :2113 共 13 个指标名,每节点 1,281 条序列(导出共 1,307 行,含 26 行 HELP/TYPE),其中 1,216 条为直方图桶
duty_cycle{accelerator_id="<instance_id>-4",container="straggler",make="cloud-tpu",model="tpu7x",namespace="tpu-verify",pod="straggler-1-dfsc7",tpu_topology="2x2x2"} 100
duty_cycle_node{accelerator_id="<instance_id>-4",make="cloud-tpu",model="tpu7x",tpu_topology="2x2x2"} 100
tensorcore_utilization{accelerator_id="<instance_id>-0",container="straggler",...} 78.07
tensorcore_utilization_node{accelerator_id="<instance_id>-0",...} 78.08
memory_bandwidth_utilization{...-0,...} 40.40        memory_bandwidth_utilization_node{...-0,...} 40.38
memory_used{...-4,...} 2.436228096e+09               memory_total{...-4,...} 2.03465670656e+11   (另有 _node 副本)
hlo_execution_timing_microsecond_{bucket,sum,count}{...-0,core_type="tensor_core",...}   (每节点 8 条 = 4 芯片 x 2 TensorCore)
hlo_queue_size{...,core_type="tensor_core",...} 8
ml_runtime_uptime_seconds{container="straggler",ml_framework_name="jax",ml_framework_version="jax-0.9.0",...} 450
# GMP 原始样本:每条序列 5 min 内 20 个点,间隔全部为 15.0 s
# GMP 类型:prometheus.googleapis.com/duty_cycle/gauge,.../hlo_execution_timing_microsecond/histogram(CUMULATIVE DISTRIBUTION)
# 抓取时间戳到可查询(2 s 轮询,23 个样本):p50 1.3 s,最大 2.3 s
# 采集器 Pod:11 到 18 mCPU,88 到 95 MiB

指标清单 实测:

:2113 指标名来源每节点序列数
duty_cycle、memory_used、memory_totallibtpu runtime gRPC <podIP>:8431,带 Pod 标签;accelerator_id 为 slice 内全局序号4
duty_cycle_node、memory_used_node、memory_total_node同上,去掉 Pod 标签的副本4
tensorcore_utilization、memory_bandwidth_utilization主机 BAR 读数(tpuhost,Pod 级),accelerator_id 为 host 内序号4
tensorcore_utilization_node、memory_bandwidth_utilization_node主机 BAR 读数(节点级,没有 Pod 时也有)4
hlo_execution_timing_microsecond(直方图)、hlo_queue_sizelibtpu runtime,带 core_type8(4 芯片 × 2 TensorCore)
ml_runtime_uptime_secondslibtpu runtime,带框架名与版本1
端口 :9431Orbax、Grain 指标,需 ENABLE_ORBAX_PROMETHEUS_TELEMETRY、ENABLE_PYGRAIN_PROMETHEUS_TELEMETRY 设为 true(Orbax、Grain)文档本实验未启用

实测耗时:两个 TPU 节点上 apply 到 DaemonSet Pod 全部 Ready 6 s(含 46 MB 镜像拉取);负载初始化 libtpu 后 15 s 内出现非零值;样本在抓取后 0.3 到 2.3 s(p50 1.3 s)可在 GMP 查询(另加最多 15 s 采集间隔和 15 s 抓取间隔)。

判定标准:负载运行期间 :2113 有 duty_cycle、tensorcore_utilization、memory_bandwidth_utilization、memory_used、memory_total(含 _node)和 hlo_*,带 Pod 与容器标签;GMP 中每条序列间隔 15 s;PodMonitoring 状态为 ConfigurationCreateSuccess。

注意事项:

  • 在 CPU 节点上只授予命名空间 Role(pods)时,k8s_attributes 报 nodes forbidden,tpuhost 也因节点无加速器类型而 failed to start "tpuhost" receiver,容器退出;补 ClusterRole(nodes get/list/watch)并去掉 tpuhost 后正常启动。k8s_attributes 需读 nodes 以取得 model、tpu_topology 标签,因此保留 nodes 只读 ClusterRole;replicasets、namespaces 权限不需要;Role-only 在 TPU 节点上的行为未单独测试 实测。
  • 原文件复用 tpu-device-plugin-sa,该 SA 有 node update/patch 权限 文档。
  • tpuhost 读 sysfs BAR,清单以 privileged root 运行;在没有 TPU 的节点上取不到加速器类型,整个 pipeline 启动失败,须保留 TPU nodeSelector 实测。
  • receiver 规则会匹配采集器 Pod 自身,未按 label 排除时会出现 :9431、:8431 的 connection refused 噪声 实测。
  • 同一 exporter 中芯片编号有两套:libtpu 来源的序列用 slice 内全局序号(worker 1 为 -4 到 -7),BAR 来源和 hlo_* 用 host 内序号(-0 到 -3);不要按 accelerator_id 跨指标关联,按 node、pod 聚合 实测。
  • 命名空间内的 PodMonitoring 总是写入目标标签 namespace(采集器所在命名空间),指标自带的 namespace 被改名为 exported_namespace;采集其他命名空间时按 exported_namespace 或 pod 查询 实测。
  • 单 slice JAX 作业没有 Megascale、DCN 类指标(collective_end_to_end_latencies_microsecond、dcn_*、grpc_tcp_* 等),也没有 :9431 框架指标 实测。
  • hlo_execution_timing p50(约 1.0 s)大于 0.52 s 的步时,因为包含在前一程序之后排队的时间 实测。
  • TPU Pod 启动后约 20 s 内每个芯片记录数次 BAR 读取错误(metrics fetch failed for N deviceID ... TPU device is offline,实测每芯片 4 次),不影响后续采集 实测。
  • 镜像 0.1.4 在仓库中带 deprecated-public-image 标签,已有 0.1.5、0.1.6;GKE 自带的 kube-system/ai-telemetry-collector 在验证集群上为 0.1.1。升级前需重新验证 OTTL 改名与 allowlist 实测。
↩ 返回需求R-06正文2.5

A.6 带外 Cloud Monitoring 指标(对应 2.6)#

A.6.1

A.6.1 Cloud Monitoring TPU 指标(带外与 GKE 系统指标):数据有无、间隔与入库延迟#

服务需求R-07R-08R-09实测耗时描述符导出 7 s实测

服务需求:R-07、R-08、R-09(见第 1 章);正文:2.6、3.4。

目的:确认两个 TPU 节点在 Cloud Monitoring 中实际有数据的 TPU 指标、采样间隔、标签和入库延迟,给出实测返回数据的查询。

前置:A.0.8,A.0.2 查到的 instance id(下文 <ID1>、<ID2>)。不需要集群权限。

实测返回数据的查询(2026-11-03 约 11:46 UTC):

PromQL
# P1b 节点健康(2 条,HEALTHY)
max by (instance_id, health_status, unhealthy_category) (last_over_time(compute_googleapis_com:instance_tpu_infra_health{monitored_resource="gce_instance", instance_id=~"<ID1>|<ID2>"}[10m]))
# P2b 芯片状态(2 条,HEALTHY=4)
sum by (instance_id, state) (last_over_time(compute_googleapis_com:instance_tpu_chip_state{monitored_resource="gce_instance", instance_id=~"<ID1>|<ID2>"}[10m]))
# P3 节点 TensorCore 利用率(node-a 0,node-b 82.7)
avg by (node_name) (kubernetes_io:node_accelerator_tensorcore_utilization{monitored_resource="k8s_node", cluster_name="<CLUSTER>"})
# P6 带外序列缺失检测(=1,tray_temperature 缺失)
absent_over_time(compute_googleapis_com:instance_tpu_accelerator_tray_temperature{monitored_resource="gce_instance", instance_id="<ID1>"}[30m])
# P8 告警表达式(健康时为空)
count by (instance_id) (last_over_time(compute_googleapis_com:instance_tpu_infra_health{monitored_resource="gce_instance", health_status!="HEALTHY"}[10m])) > 0
# Z3 用 VM 标签按集群过滤带外序列,按节点名聚合(node-a、node-b 各 4)
max by (metadata_system_name) (max_over_time({"__name__"="compute.googleapis.com/instance/tpu/chip_state", monitored_resource="gce_instance", state="HEALTHY", "metadata_user_goog-k8s-cluster-name"="<CLUSTER>"}[10m]))

等价 MQL(fetch gce_instance 加 metric 'compute.googleapis.com/instance/tpu/infra_health',按 resource.instance_id、metric.health_status 分组,within 30m)同样返回 2 条 实测。

指标特性(入库延迟为 30 s 精细轮询 20 min 的 最小、中位、最大值):

指标间隔入库延迟标签与取值验证集群上的数据
compute.googleapis.com/instance/tpu/infra_health(BETA)60 s350、367、382 shealth_status=HEALTHY 或 UNHEALTHY(文档另列 DEGRADED、UNKNOWN,验证期间未出现),unhealthy_category=空 或 INFRA;值恒为 1连续
instance/tpu/chip_state(BETA)60 s256、276、296 sstate;值为该状态的芯片数连续
instance/tpu/active_chips、scheduled_chips(GA),utilized_chips(BETA)60 s256、275、294 saccelerator_type=TPU_7X,reservation_id连续
kubernetes.io/node/accelerator/tensorcore_utilization、memory_bandwidth_utilization(GA)60 s48、63、78 saccelerator_id=<instance_id>-<0..3>(host 内序号),tpu_topology连续,空闲时也上报
kubernetes.io/node 与 container 的 accelerator/duty_cycle、memory_used、memory_total(GA)60 s1、17、31 saccelerator_id=<instance_id>-<slice 内序号>;memory_total 每芯片 203,448,893,440 B(约 189.5 GiB)仅在有容器占用 TPU 时
instance/tpu/accelerator/*(20 个 BETA)60 s无新点accelerator_id 0..3;ICI port_id=tray0.chip<N>.ici<0-5>.int 或 .ext<k>15 个仅在 10-27 11:44 到 10-29 06:20 UTC 有数据;duty_cycle、memory_*、tensorcore_utilization 从未出现
instance/tpu/failure_prediction_score、failure_prediction_status(BETA)———整个项目 42 天内 0 条序列

10-27 到 10-29 有数据期间两节点带外取值(每芯片):core_temperature 35.1 到 74.8 °C,power_draw 132 到 742 W,hbm_temperature 31 到 47 °C;hbm_uncorrectable_count、pcie_fatal_error_count、pcie_nonfatal_error_count、ici_link_health 均为 0;ici_link_flaps 为 1 到 9 的常数;tray_power(每 tray)1009 到 3375 W 实测。

裁剪输出:

输出
compute.googleapis.com/instance/tpu/infra_health | GAUGE INT64 | BETA | samplePeriod=60s ingestDelay=420s
infra_health node-b UNHEALTHY (UTC): 11-02T16:37-16:48, 11-03T09:58-10:09   node-a: 11-02T17:44-17:55   # 同期 chip_state UNHEALTHY
P1_infra_health_now      n_results=0     # 即时查询默认回看 5 min,小于入库延迟
P1b_infra_health_last10m n_results=2 (HEALTHY, HEALTHY)

实测耗时:描述符导出 7 s;117 个指标 24 h 普查 43 s;项目范围 7 天探测约 90 s;延迟轮询 606 s 加精细轮询 20 min。

判定标准:两个 instance id 都有 infra_health 和 chip_state,延迟不超过 7 min;kubernetes.io/node/accelerator/tensorcore_utilization 有 8 个 accelerator_id;对 absent_over_time(...tray_temperature[30m]) 配置告警以发现带外序列中断。

注意事项:

  • instance/tpu/accelerator/* 10-29 后对两个 GKE 节点无数据,11-03 约 1 h 的 TPU 负载期间也没有恢复(见附录 A.6.2),同 zone 非 GKE TPU7x VM 仍在上报;按尽力而为对待并对缺失告警;failure_prediction_* 项目内无数据 实测。
  • infra_health 即时 PromQL 返回空(约 6 min 入库延迟大于 5 min 默认回看),统一使用 last_over_time(...[10m]) 实测。
  • infra_health 值恒为 1,状态在标签中;验证期间 unhealthy_category 只出现空串和 INFRA 实测。
  • 同一节点的 accelerator_id 序号因指标而异:duty_cycle、memory_* 用 slice 内序号,tensorcore_utilization、memory_bandwidth_utilization 用 host 内序号 实测。
  • 24 h 内每个完整 15 min 窗口 infra_health、chip_state、节点 tensorcore_utilization 都有 15 个点 实测。
  • 带外序列带 VM 标签,可用 metadata_user_goog-k8s-cluster-name 等过滤,用 metadata_system_name 映射节点名 实测。
  • 节点 tensorcore_utilization 可能比非零 memory_used 早 1 到 2 min 出现 21% 到 57% 的读数;24 h 内未出现 HBM 小于 1 GiB 而利用率不低于 90% 的分钟 实测。
  • 3 段约 12 min 的 UNHEALTHY(INFRA)原因未在本实验中确认,同期也没有 TPU 相关日志(见附录 A.7.1)实测。
补充查询与指标#

以下两条为 2.6.3 未列出的告警写法,已在 10-28 有数据时段执行,语法与指标名有效,因无错误返回空 实测;未在故障场景验证。

PromQL
increase(compute_googleapis_com:instance_tpu_accelerator_hbm_uncorrectable_count{monitored_resource="gce_instance"}[15m]) > 0
max by (instance_id, port_id) (max_over_time(compute_googleapis_com:instance_tpu_accelerator_network_ici_link_health{monitored_resource="gce_instance"}[10m])) >= 6 < 10
指标(前缀 compute.googleapis.com/)要点周期,实测延迟本集群数据
instance/tpu/{scheduled,active,utilized}_chips带 reservation_id、block_id、subblock_id60 s,256–294 s 实测连续 实测
↩ 返回需求R-07 R-08 R-09正文2.6 3.4
A.6.2

A.6.2 负载期间的带外 accelerator 指标#

服务需求R-07R-08实测耗时本次查询未单独计时实测

服务需求:R-07、R-08(见第 1 章);正文:2.6。

目的:确认 TPU 负载运行期间,验证集群节点上已停止上报的 compute.googleapis.com/instance/tpu/accelerator/*(见附录 A.6.1)是否恢复。

前置:A.0.8;时间窗为附录 A.7.2、A.7.3、A.11.1 各作业所在的整个 TPU 负载窗口(2026-11-03 13:08 到 14:15 UTC)。

命令:按前缀列出指标类型,再逐类型查询两个节点(gce_instance)或本命名空间(k8s_container)的时间序列。

bash
# 1) 某前缀下的指标类型
curl -s "${H[@]}" "https://monitoring.googleapis.com/v3/projects/$PROJECT/metricDescriptors" --get \
  --data-urlencode 'filter=metric.type=starts_with("compute.googleapis.com/instance/tpu/")' --data-urlencode 'pageSize=500'
# 2) 每个类型在时间窗内的序列(以 accelerator/core_temperature 为例)
curl -s "${H[@]}" "https://monitoring.googleapis.com/v3/projects/$PROJECT/timeSeries" --get \
  --data-urlencode 'filter=metric.type="compute.googleapis.com/instance/tpu/accelerator/core_temperature" AND resource.labels.instance_id=one_of("<ID1>","<ID2>")' \
  --data-urlencode 'interval.startTime=<START>' --data-urlencode 'interval.endTime=<END>' --data-urlencode 'view=FULL'

裁剪输出:

输出
## gce_instance, prefix compute.googleapis.com/instance/tpu/  -> 5 types with data
   instance/tpu/active_chips     series=2 pts=136  2026-11-03T13:08:00Z..14:15:00Z
   instance/tpu/chip_state       series=2 pts=136
   instance/tpu/infra_health     series=2 pts=136
   instance/tpu/scheduled_chips  series=2 pts=136
   instance/tpu/utilized_chips   series=2 pts=136
# instance/tpu/accelerator/* 的 20 个类型:0 条序列
## kubernetes.io/container/multislice/*  -> 0 types with data
## kubernetes.io/container/accelerator/* (namespace tpu-verify) -> 6 types
   duty_cycle series=16, memory_bandwidth_utilization series=24, memory_total 16, memory_used 16, request 4, tensorcore_utilization 24

实测耗时:本次查询未单独计时。

判定标准:时间窗内 instance/tpu/accelerator/* 有数据即为恢复。结果:20 个类型在整个约 1 h 的 TPU 负载窗口内都没有数据,同一窗口内 instance/tpu/ 下另外 5 个类型和 kubernetes.io/container/accelerator/* 正常上报 实测。

注意事项:

  • TPU 负载运行不会让 instance/tpu/accelerator/* 恢复上报;芯片温度、功耗、HBM 不可纠正错误、ICI 链路等带外信号在验证集群上无法使用,告警需对这些序列配置缺失检测(见附录 A.6.1 的 P6)实测。
  • compute.googleapis.com/tpu/ 前缀下的 tpu/network/*、tpu/multislice/* 使用 gce_instance 资源,单指标查询可返回数据;tpu/capacity/*、tpu/slice/capacity/* 使用其他资源类型,按 instance_id 过滤返回 400(指标与资源组合无效);timeSeries 每次只能查一个指标类型,需逐类型查询 实测。
  • 单 slice 作业在 kubernetes.io/container/multislice/* 下没有任何序列 实测。
↩ 返回需求R-07 R-08正文2.6

A.7 日志(对应 2.7)#

A.7.1

A.7.1 Cloud Logging 中的 TPU 日志位置与过滤条件#

服务需求R-11实测耗时限定 logName 或 resource 的查询 2 到 14 s实测含未验证

服务需求:R-11(见第 1 章);正文:2.7。

目的:确定 libtpu、device plugin、节点、VM、维护事件和 ML Diagnostics 日志的 logName、resource 和标签,给出快速返回的过滤条件,并检查 Cloud TPU 文档列出的 5 个健康原因(DATA_INPUT_STALL、FINGERPRINT_MISMATCH、DIFFERENT_MODULE、UNRECOVERABLE_ERROR、UNKNOWN_CAUSE)及 Megascale detects a hang 文本是否出现。

前置:A.0.8。只读。

命令(2026-11-03 约 12:06 UTC):

bash
# libtpu tpu_driver 日志(sidecar-log-collector 的 stdout);只取 glog ERROR 行
gcloud logging read 'resource.type="k8s_container" AND resource.labels.cluster_name="<CLUSTER>"
  AND resource.labels.namespace_name="kube-system" AND resource.labels.container_name="sidecar-log-collector"
  AND textPayload:"] E1"' --project $PROJECT --freshness=3d --limit 20
# 计划维护通知(instance_id 标签为实例名)
gcloud logging read 'logName="projects/'$PROJECT'/logs/maintenance.googleapis.com%2Fmaintenance_events"
  AND resource.labels.instance_id=("<node-a>" OR "<node-b>")' --project $PROJECT --freshness=30d
# 维护审计(GKE 节点事件可用 jsonPayload.metadata.annotations."maintenance.gke.io/category"="HostMaintenance" 过滤)
gcloud logging read 'logName="projects/'$PROJECT'/logs/cloudaudit.googleapis.com%2Fsystem_event"
  AND protoPayload.methodName="compute.instances.upcomingMaintenance" AND timestamp>="<START>"' --project $PROJECT --limit 50
# ML Diagnostics(GKE TPU Job 自动创建 run)
gcloud alpha mldiagnostics monitored-events list --machine-learning-run=<RUN_ID> --location=<REGION> --project $PROJECT

日志位置 实测:

来源logNameresource 与关键标签说明
libtpu tpu_driver.INFOstdoutk8s_container,namespace_name=kube-system,pod_name=tpu-device-plugin-<hash>,container_name=sidecar-log-collector前缀 [/tmp/tpu_logs/<容器名>/tpu_driver.INFO];severity 恒为 INFO
TPU device pluginstderrk8s_container,container_name=tpu-device-pluginjsonPayload.message
节点kubelet、container-runtime、gke-node-problem-detector、eventsk8s_nodeNPD 产生 OOMKilling 事件
VM 串口serialconsole.googleapis.com%2Fserial_port_1_outputgce_instance,instance_id 为数字 id内核日志
计划维护maintenance.googleapis.com%2Fmaintenance_eventsgce_instance,instance_id 为实例名state、窗口、userControllable
维护审计cloudaudit.googleapis.com%2Fsystem_eventmethodName=compute.instances.upcomingMaintenancetype、maintenanceStatus、canReschedule
ML Diagnosticsml_diagnostics_workload_eventgeneric_node,node_id=<ML run id>WORKLOAD_PERFORMANCE_DEGRADATION、WORKLOAD_TERMINATION

裁剪输出:

输出
stdout sidecar-log-collector: [/tmp/tpu_logs/standard-container/tpu_driver.INFO] E1101 08:54:18.471410 1409 memory_space_assignment_util.cc:567] INVALID_ARGUMENT: 67108864 bytes of scoped Vmem requested ...
stderr tpu-device-plugin ERROR: {"message":"failed to update runtime Metrics: rpc error: code = DeadlineExceeded ... dial tcp <podIP>:8431: connect: connection refused"}
stderr tpu-device-plugin ERROR: {"message":"metrics fetch failed for 0 deviceID and /sys/bus/pci/devices/0000:00:03.0 device path with error: unable to deserialize the metrics data. Corrupt data found"}
maintenance_events node-b: {"state":"SCHEDULED","maintenanceScheduledStartTime":"2026-11-09T20:00:00Z","userControllable":true}
audit upcomingMaintenance node-a 2026-11-02T20:00:09Z {"type":"SCHEDULED","maintenanceStatus":"PENDING","canReschedule":true}
audit(同项目另一节点){"type":"UNSCHEDULED","maintenanceStatus":"ONGOING","maintenanceReasons":["FAILURE_INFRA"],"canReschedule":false}
events MaintenanceWindowScheduled (NodeTerminationHandler) 2026-11-02T20:00:11Z, maintenance.gke.io/category=HostMaintenance
events 最新 100 条节点事件: OOMKilling 90, KubeletConfigDriftDetected 8, MaintenanceWindowScheduled 2
mldiagnostics: 15 个 run 中 1 个有 2 条 PERFORMANCE_DEGRADATION,无 HANG 事件
health-cause 字符串: 集群全部容器 30 天 0 命中;runtime_monitor 7 天 0 命中

实测耗时:限定 logName 或 resource 的查询 2 到 14 s;maintenance_events 30 天 3.4 s;维护审计 8 天 21 s;HostMaintenance 节点事件 23 s;本集群全部容器 30 天全文检索 97 s;项目范围 8 天全文检索 57 s 到超过 240 s 超时或 API deadline too short。

判定标准:每次 TPU 负载运行在 sidecar 日志中都有前缀为 /tmp/tpu_logs/<容器名>/tpu_driver.INFO 的条目;device plugin stderr 存在;计划维护时审计 upcomingMaintenance、MaintenanceWindowScheduled 事件、maintenance_events 依次在 20:00:09、20:00:11、20:00:15 到 17 UTC 写入,8 s 内到齐。

注意事项:

  • sidecar 转发行 severity 恒为 INFO,按 glog 级别过滤需匹配正文,例如 textPayload:"] E1" 实测。
  • sidecar 条目的 pod_name 是 device plugin Pod,负载只能从前缀中的容器名目录和节点、时间对应;只转发 tpu_driver.INFO,且每个容器只转发第一个 libtpu 进程的文件(见附录 A.7.2、A.7.3)实测。
  • 三段 infra_health UNHEALTHY 时间窗内没有 TPU 相关日志(只有 autoscaling-metrics-exporter 错误和 device plugin 的 :8431 报错),这类故障只能依赖 Cloud Monitoring 发现 实测。
  • TPU Pod 未启动 libtpu metrics server 时 device plugin 每隔几秒报 connection refused :8431,告警规则应排除 实测。
  • device plugin 的 checksum didn't match with the metrics data. Corrupt data found 每节点每天 16 到 23 条(11-02 全天;11-03 前 12 h 为 12 到 17 条),告警阈值应高于这一背景量 实测。
  • OOMKilling 节点事件来自 otelsvc 和 config-reloader 容器,不是 TPU 错误(见附录 A.1.2)实测。
  • maintenance_events 的 instance_id 是实例名,串口日志是数字 id 实测。
  • 项目内未找到 TPU 健康原因日志条目(验证集群只有单 slice 作业),其格式和 log name 无法在本项目观察 实测。
  • 项目范围全文检索即使限定 resource.type=k8s_container,7 到 8 天窗口也多次超过 240 s 或报 API deadline too short(4 个窗口仅 1 个 57 s 返回);全文检索应限定集群(30 天约 97 s)或 logName(2 到 14 s)实测。
补充过滤条件与维护时间线#
bash
# libtpu ERROR/FATAL 行:severity 恒为 INFO,按文本中的 glog 级别匹配
gcloud logging read 'resource.type="k8s_container" AND resource.labels.cluster_name="CLUSTER"
  AND resource.labels.container_name="sidecar-log-collector"
  AND textPayload=~" [EF][0-9]{4} [0-9]{2}:[0-9]{2}:"' --freshness=1d --limit=50

实验室用子串 "] E1" 过滤可行 实测,但它只匹配 10–12 月的日期;上面的正则为通用写法 未验证。

来源Cloud Logging 位置要点
VM 串口serialconsole.googleapis.com/serial_port_1_output需开启 serial-port-logging-enable 文档
  • 本集群计划维护的通知顺序(2026-11-02 UTC):审计日志 compute.instances.upcomingMaintenance(20:00:09,SCHEDULED、PENDING,窗口 11-09 20:00 至 11-10 00:00)→ K8s event MaintenanceWindowScheduled(20:00:11,注解 maintenance.gke.io/*)→ 日志 maintenance.googleapis.com/maintenance_events(20:00:15);节点 label cloud.google.com/scheduled-maintenance-time=1794254400,节点注解 node.gke.io/upcoming-maintenance(JSON,含窗口与 can_reschedule)实测。
bash
gcloud logging read 'logName="projects/PROJECT/logs/cloudaudit.googleapis.com%2Fsystem_event"
  AND protoPayload.methodName="compute.instances.upcomingMaintenance"' --freshness=7d
↩ 返回需求R-11正文2.7
A.7.2

A.7.2 TPU_LOG_DIR、/tmp/tpu_logs 与 stderr 日志级别#

服务需求R-11实测耗时Pod A apply 到 Running 4 s,三次运行共 42 s,删除 Pod…实测含未验证

服务需求:R-11(见第 1 章);正文:2.7。

目的:用一个 TPU Pod 确认 GKE 注入的 TPU_LOG_DIR 和 /tmp/tpu_logs 的挂载方式、该目录何时被清空、TPU_STDERR_LOG_LEVEL 未设置、2、0 三种取值对 stderr 的影响,以及这些日志在 Cloud Logging 中的形态。

前置:A.0.2 到 A.0.4(单机 holder Pod,TPU_HOST_BOUNDS=1,1,1)。TPU Pod 必须同时带 cloud.google.com/gke-tpu-accelerator 和 cloud.google.com/gke-tpu-topology 两个 nodeSelector,即使已用 kubernetes.io/hostname 固定节点(GKE 准入约束)实测。验证用一个不申请 TPU、以只读 hostPath 挂载 /tmp/tpu_logs 的 Pod 查看主机侧文件。

命令(Pod A 内依次执行,每次一个新进程,间隔 12 s):

bash
grep tpu_logs /proc/self/mountinfo
PY='import jax, jax.numpy as jnp; jax.devices(); jnp.ones(1024).sum()'
for L in unset 2 0; do
  if [ $L = unset ]; then env -u TPU_STDERR_LOG_LEVEL TPU_HOST_BOUNDS=1,1,1 python3 -c "$PY"
  else TPU_STDERR_LOG_LEVEL=$L TPU_HOST_BOUNDS=1,1,1 python3 -c "$PY"; fi
  wc -l < $(readlink -f $TPU_LOG_DIR/tpu_driver.INFO); sleep 12
done
touch $TPU_LOG_DIR/marker_$(date +%s)
# 删除 Pod A 后,用 hostPath 只读 Pod 查看主机 /tmp/tpu_logs;再在同一节点创建申请 TPU 的 Pod B,查看 /tmp/tpu_logs
bash
# Cloud Logging:负载 stderr(glog 行被解析为 jsonPayload.message,severity 取 glog 级别);须给出时间上下界
gcloud logging read 'resource.type="k8s_container" AND resource.labels.namespace_name="tpu-verify"
  AND resource.labels.container_name="holder" AND log_id("stderr")
  AND timestamp>="<START>" AND timestamp<="<END>"' --project $PROJECT --format=json

裁剪输出:

输出
TPU_LOG_DIR=/tmp/tpu_logs/holder TPU_STDERR_LOG_LEVEL=<unset> TPU_MIN_LOG_LEVEL=<unset>
3542 3534 0:35 /tpu_logs /tmp/tpu_logs rw - tmpfs tmpfs rw          # 主机 /tmp(COS tmpfs)的 bind
ls /tmp/tpu_logs at start: total 4  (empty)
level=unset rc=0 wall_s=6.64 info_file=.../tpu_driver.holder-a.root.log.INFO.20261103-130818.13   info_lines=186 stderr: 0
level=2     rc=0 wall_s=5.58 info_file=.../tpu_driver.holder-a.root.log.INFO.20261103-130836.1896 info_lines=186 stderr: 0
level=0     rc=0 wall_s=5.56 info_file=.../tpu_driver.holder-a.root.log.INFO.20261103-130853.3788 info_lines=186 stderr: 181
tpu_driver.INFO -> tpu_driver.holder-a.root.log.INFO.20261103-130853.3788     # 符号链接指向最新进程
# Pod A 删除后(13:09:39)主机侧:/tmp/tpu_logs/holder 中 marker、3 个 INFO、3 个 WARNING 文件仍在
# 同节点 Pod B(13:10:08):/tmp/tpu_logs 为空
sidecar 13:08:23 New log file found, starting tail: /tmp/tpu_logs/holder/tpu_driver.INFO
sidecar 13:10:08 Log file '/tmp/tpu_logs/holder/tpu_driver.INFO' removed. Cleaning up tail process 142144.
# Cloud Logging:sidecar 188 条,全部来自第 1 次运行;stderr 181 条,只来自 level 0
{"jsonPayload":{"message":"Metric already exists: hlo.queue.size.gauge","pid":"4142"},"severity":"WARNING",
 "sourceLocation":{"file":"libtpu_telemetry_utils.cc","line":"44"}}
TPU_STDERR_LOG_LEVELstderr 中的 libtpu 行tpu_driver INFO 文件行数jax 初始化
未设置01863.23 s
20(本次初始化没有 ERROR 行)1863.14 s
01811863.16 s

实测耗时:Pod A apply 到 Running 4 s,三次运行共 42 s,删除 Pod A 7.7 s,Pod B apply 到 Ready 4.9 s;每次 Cloud Logging 查询约 2.9 s。

判定标准:TPU_LOG_DIR=/tmp/tpu_logs/<容器名>;/tmp/tpu_logs 是主机 /tmp/tpu_logs 的 bind,位于 COS /tmp tmpfs 上;Pod 删除后文件仍在,同节点下一次 TPU 分配时被清空;level 0 时每条 INFO 行复制到 stderr。

注意事项:

  • 日志目录在节点内存(tmpfs)中,节点重启后应随之丢失(未做重启测试)未验证;下一个申请 TPU 的 Pod 分配到该节点时目录被清空(sidecar 在 Pod B 分配时刻记录 removed,不是在 Pod A 删除时),需要保留的日志要在下一个作业前拷出 实测。
  • 每个 libtpu 进程写新的 tpu_driver.<pod>.root.log.INFO.<时间>.<pid> 文件,并把 tpu_driver.INFO 符号链接指向最新进程;sidecar 只跟踪第一次打开的文件,同一容器内第 2、3 个进程的日志没有进入 Cloud Logging(见附录 A.7.3)实测。
  • 负载 stderr 的 glog 行被 GKE 日志代理解析为 jsonPayload.message(加 pid、sourceLocation),severity 取 glog 级别(161 条 INFO、14 条 WARNING);textPayload: 过滤匹配不到这些行;非 glog 行的 severity 为 ERROR 实测。
  • 三种取值的 jax 初始化时间无可测差别(3.14 到 3.23 s)实测。
  • level 2 只增加 ERROR 和 FATAL 行,本次健康初始化没有这类行,所以与未设置相同;生产中把 ERROR 级 libtpu 日志送到 stderr 的取值未在故障场景中验证 未验证。
  • 日志目录在 tmpfs 中:TPU_MIN_LOG_LEVEL 默认 0(各级别都落盘),单个文件按 TPU_MAX_LOG_SIZE_MB(默认 1024)滚动(TPU 故障排查)文档;加大 TPU_VMODULE 会增加节点内存占用 未验证。
↩ 返回需求R-11正文2.7
A.7.3

A.7.3 sidecar 日志:运行中作业的 tpu_driver.INFO#

服务需求R-11实测耗时sidecar 在 5 s 发现周期内跟上新文件(本次文件创建后不到 1 s,附录 A…实测

服务需求:R-11(见第 1 章);正文:2.7。

目的:确认运行中的 2 Pod 作业的 libtpu tpu_driver.INFO 经 sidecar-log-collector 进入 Cloud Logging,如何找到本作业的行,以及入库延迟;同时检查作业启动时是否出现 TensorCore 利用率尖峰。

前置:A.0.8;负载为附录 A.11.1 的 Job(容器名 straggler,TPU_LOG_DIR=/tmp/tpu_logs/straggler;独特的容器名让前缀可区分)。

命令:

bash
gcloud logging read 'resource.type="k8s_container" AND resource.labels.cluster_name="<CLUSTER>"
  AND resource.labels.namespace_name="kube-system" AND resource.labels.container_name="sidecar-log-collector"
  AND log_id("stdout") AND textPayload:"/tmp/tpu_logs/straggler/"
  AND timestamp>="<START>" AND timestamp<="<END>"' --project $PROJECT --format=json
# 按节点:AND labels."compute.googleapis.com/resource_name"="<node-b>"
# 只看 WARNING/ERROR(severity 恒为 INFO):AND (textPayload:"] W1" OR textPayload:"] E1")

裁剪输出:

输出
13:14:28.998Z New log file found, starting tail: /tmp/tpu_logs/straggler/tpu_driver.INFO
[/tmp/tpu_logs/straggler/tpu_driver.INFO] Log file created at: 2026/11/03 13:14:28
[/tmp/tpu_logs/straggler/tpu_driver.INFO] Running on machine: straggler-0
[/tmp/tpu_logs/straggler/tpu_driver.INFO] W1103 13:14:3x ... libtpu_telemetry_utils.cc:44] Metric already exists: ...
sidecar: 845 entries (node-a 240 / node-b 605), severity INFO 845 (glog I 785, W 34, 其他 26)
         receiveTimestamp-timestamp p50 3.0 s / p95 3.9 s / max 4.9 s; glog 行时间到条目 timestamp p50 1.3 s / p95 3.0 s
         glog 行时间到 receiveTimestamp(端到端,819 行 glog)p50 3.8 s / p95 6.9 s;另一次 25 min 测试 989 行 p50 3.8 s / p95 7.4 s
workload stdout: 7616 entries (= kubectl logs 行数), receive lag p50 2.5 s / p95 4.8 s
tensorcore_utilization_node (15 s): 13:14:30 到 13:21:00 为 0,13:21:15 起 37% 到 78%(第一步 13:20:47),启动时无尖峰

实测耗时:sidecar 在 5 s 发现周期内跟上新文件(本次文件创建后不到 1 s,附录 A.7.2 中为 4.6 s),条目约 3 s 后可检索(glog 行时间到可检索端到端 p50 3.8 s,p95 6.9 到 7.4 s);查询 845 条 sidecar 日志 4.9 s,7,616 条负载日志 24.2 s。

判定标准:能按 [/tmp/tpu_logs/<容器名>/tpu_driver.INFO] 前缀找到本作业的行;入库延迟为秒级。

注意事项:

  • 条目的 pod_name 是 device plugin Pod,作业只能靠前缀中的容器名目录加节点标签 compute.googleapis.com/resource_name 识别;容器名不要用 main 这类通用名 实测。
  • severity 恒为 INFO,按正文中的 glog 级别字母过滤 实测。
  • 每个容器只有第一个 libtpu 进程的日志被转发(原因见附录 A.7.2);容器内重启训练进程或依次运行多个脚本时,后续进程的 driver 日志不会进入 Cloud Logging,应一个容器一个 libtpu 进程,或自行转发文件,或使用 TPU_STDERR_LOG_LEVEL 实测。
  • worker 1 的行数是 worker 0 的 2.5 倍,只因为它多编译了一个程序(计算型慢节点阶段),各节点行数不是健康信号 实测。
  • 没有诊断 flag 时不会出现 ICI BW 或 XLA_SDC_CHECKER 行(见附录 A.4.2)实测。
  • 本负载启动阶段(约 6 min 空闲)TensorCore 利用率为 0,第一步后才上升,启动阶段没有利用率尖峰;规则中仍保留 HBM 门限,因为这与负载有关 实测。
↩ 返回需求R-11正文2.7

A.8 维护事件与 ML Diagnostics(对应 2.8)#

A.8.1

A.8.1 ML Diagnostics 工作负载监控#

服务需求R-12实测耗时两次实测 run 出现时间为 Job 创建后不超过 1.9 s(Job createT…实测

服务需求:R-12(见第 1 章);正文:2.8、3.5.2。

目的:确认 ML Diagnostics 工作负载监控在 GKE TPU Job 上无需配置即自动创建 run,并记录它在慢节点和 hang 阶段产生的 monitored events。

前置:A.0.8;项目已满足 ML Diagnostics 的 API 与 IAM 前提。负载为附录 A.11.1 的 2 Pod Job(straggler,2 × 4 芯片),各阶段时间见该节。集群上没有 ML Diagnostics 的 CRD 或专用命名空间,run 在服务端创建(标签 created_by=diagon_mon)实测。

命令:

bash
gcloud alpha mldiagnostics machine-learning-run list --location=<REGION> --project $PROJECT --limit=50 --format=json
# 按 workloadDetails.gke.{cluster,namespace,id} 匹配本作业的 run,再列出事件
gcloud alpha mldiagnostics monitored-events list --machine-learning-run=$RID --location=<REGION> --project $PROJECT --format=json
gcloud alpha mldiagnostics monitored-events describe $EVENT_ID --machine-learning-run=$RID --location=<REGION> --project $PROJECT

裁剪输出(每 120 s 轮询一次):

输出
3969c22b...ea17 straggler-1793711665 ACTIVE 2026-11-03T13:14:26Z      # Job apply 于 13:14:22
=== poll 13:29:20Z runPhase=ACTIVE  []
=== poll 13:58:24Z runPhase=ACTIVE
  {"displayName": "straggler-performance_degradation-1793714188", "startTime": "2026-11-03T13:56:28.392Z", "type": "PERFORMANCE_DEGRADATION"}
=== poll 14:15:03Z runPhase=COMPLETED 2026-11-03T14:13:24Z   (event endTime 14:13:24Z)
describe: analyzerReports = 13 analyzers (ICI Link, Thermal, TPU Throttling, HBM Bandwidth/Capacity, PyGrain Data, CPU,
          Host Memory, Async Checkpointing, Megascale Network Transfer Latency, ToR NIC Link, ToR NIC Link FEC, ToR Uplink
          Congestion) -> all "detectionState": "NOT_DETECTED"
作业阶段(UTC)变化ML Diagnostics
13:14:30 到 13:20:47 启动空闲duty cycle 0%无事件
13:20:47 到 13:35:48 基线—无事件
13:35:48 到 13:45:49 计算型慢节点步时 +48%,两个 host 的 duty cycle 均约 100%无事件
13:45:49 到 13:55:50 host 型慢节点步时 +73%,worker 1 duty cycle 约 59%(总体约 −20%)10 min 内无事件
13:55:51 到 14:07:51 hang所有芯片 duty cycle 0%,进程存活PERFORMANCE_DEGRADATION 13:56:28 开始(hang 开始后 37 s,host 型阶段开始后 10.6 min),13:58:24 的轮询可见
14:07:51 到 14:13:19 恢复回到基线事件保持打开,直到 run 结束 14:13:24

实测耗时:两次实测 run 出现时间为 Job 创建后不超过 1.9 s(Job createTime 12:05:14Z,秒精度;run createTime 12:05:15.88Z)和 4 s(本节作业,kubectl apply 后);Job 完成后 1 s run 变为 COMPLETED;事件在 startTime 后不超过一个轮询周期(120 s)可见;每次 CLI 调用约 3 s。

判定标准:run 自动创建且带 created_by=diagon_mon;能列出事件。本次只有 1 个 PERFORMANCE_DEGRADATION,13 个根因分析器都是 NOT_DETECTED,与慢节点为人为注入、不是基础设施故障一致。

注意事项:

  • 12 min 的全空闲 hang 没有产生 hang 类事件,只出现 duty cycle 类的 PERFORMANCE_DEGRADATION;Megascale 的 hang 检测需要多 slice(DCN)作业,单 slice 无法验证 实测。
  • 单个 host 慢节点使总体 duty cycle 下降约 20% 持续 10 min,没有产生事件;计算型慢节点 duty cycle 不变,duty cycle 检测器本身看不到。慢节点检测仍需作业级步时和逐节点信号(见附录 A.11.1)实测。
  • 性能恢复后事件不关闭,随 run 结束 实测。
  • 实际分析器列表中有 4 个(Async Checkpointing、PyGrain Data、Megascale Network Transfer Latency、ToR NIC Link FEC)在公开页面上没有对应小节 实测。
  • run 列表覆盖整个项目和区域(含其他集群),按 workloadDetails.gke.{cluster,namespace,id} 匹配本作业 实测。
↩ 返回需求R-12正文2.8 3.5.2

A.9 起飞前检查(对应 2.9)#

A.9.1

A.9.1 precheck_v2 作为 initContainer 运行#

服务需求R-05实测耗时对端 DNS 可解析时检查本身 9 到 10 s(其中 TPU 冒烟约 5 s),不可…实测

服务需求:R-05(见第 1 章);正文:2.9、3.3。

目的:把起飞前检查脚本放在多机 Job 每个 worker 的 initContainer 中运行,记录各检查项结果、总耗时、TCP 8471 的状态,以及 PRECHECK_TPU_MODE=single(slice 级多机初始化)能否在 initContainer 中完成。

结论:应发布的是 precheck_v2b.sh。它与 precheck_v2.sh 的唯一区别是单机 TPU 冒烟测试的配方:只设置 TPU_HOST_BOUNDS=1,1,1 和 localhost worker 变量,不加 --deepsea_hal_test_* flag,因此在 libtpu 0.0.34 上可用并保留本机 ICI,冒烟测试为 gemm 加本机 all-reduce。按原样发布的 precheck_v2.sh 在默认镜像(libtpu 0.0.34)上于第 10 步失败。slice 级多机冒烟(single 模式)在 initContainer 中可以完成,前提是 headless Service 设置 publishNotReadyAddresses: true 且两个 Pod 同时启动;该模式下 libtpu 完成跨两个 host 的初始化,计算检查覆盖每个 host 的 8 个本地 device。

前置:A.0.5 多机 Indexed Job(JobSet 未安装),A.0.10。脚本以 ConfigMap 挂载;initContainer 申请 google.com/tpu: 4。

bash
kubectl -n $NS create configmap precheck --from-file=precheck_v2b.sh
kubectl -n $NS apply -f manifest_precheck_job.yaml
kubectl -n $NS logs <POD> -c precheck

YAML 要点(Service 与 Job 模板的关键字段):

yaml
apiVersion: v1
kind: Service
metadata: {name: precheck-job}
spec:
  clusterIP: None
  publishNotReadyAddresses: true          # initContainer 阶段 Pod 未 Ready,否则对端 DNS 无法解析
  selector: {job-name: precheck-job}
yaml
# Job(completionMode: Indexed,completions: 2,parallelism: 2)的 Pod 模板;nodeSelector、tolerations 同 A.0.5
spec:
  subdomain: precheck-job
  restartPolicy: Never
  hostNetwork: true
  dnsPolicy: ClusterFirstWithHostNet       # hostNetwork Pod 解析 <job>-<i>.<svc> 需要
  volumes: [{name: precheck, configMap: {name: precheck, defaultMode: 0755}}]
  initContainers:
  - name: precheck
    image: us-docker.pkg.dev/cloud-tpu-images/jax-ai-image/tpu:latest
    command: ["bash", "/precheck/precheck_v2b.sh"]
    env:
    - name: MY_NODE_NAME
      valueFrom: {fieldRef: {fieldPath: spec.nodeName}}
    - {name: PRECHECK_NICS, value: "eth0"}
    - {name: PRECHECK_EXPECT_MTU, value: "8896"}
    - {name: PRECHECK_TPU_MODE, value: "auto"}         # 或 single(slice 级多机初始化)
    - {name: PRECHECK_TPU_TIMEOUT_S, value: "120"}     # 实验值;脚本默认 180
    volumeMounts: [{name: precheck, mountPath: /precheck}]
    resources: {requests: {google.com/tpu: "4"}, limits: {google.com/tpu: "4"}}
  containers:
  - name: main                                          # 训练容器,同样申请 google.com/tpu: 4

实测时 tpu:latest 解析为 tpu@sha256:d3dbf1a0…(jax 0.9.0、libtpu 0.0.34);生产按 digest 固定(见 2.9)。

[init-8471] 与 MAIN_RESULT 行来自实验附加探针(initContainer 末尾的 8471 探测、main 容器的 16 device psum),不属于 precheck。

裁剪输出(R1:原脚本,Service 默认设置;Pod 0):

输出
[precheck][<node-b>] PASS  8 VFIO group nodes: /dev/vfio/0 ... /dev/vfio/7
[precheck][<node-b>] PASS  vBAR socket present: ///var/run/tpu-plugin/vbar.sock
[precheck][<node-b>] WARN  fuser (psmisc) not installed or no VFIO nodes; holder check skipped
[precheck][<node-b>] PASS  8 TPU PCI functions present        # 各 function 另有一行 driver=vfio-pci rev=0x00
[precheck][<node-b>] WARN  aer_dev_fatal not exposed in this VM/container; rely on Cloud Monitoring pcie_*_error_count
[precheck][<node-b>] PASS  eth0 up, MTU=8896, TCP data split=off
[precheck][<node-b>] WARN  dmesg not permitted in this container; gve reset check skipped
[precheck][<node-b>] PASS  / usage 28%   PASS /tmp usage 28%   PASS MemTotal 944 GiB, MemAvailable 934 GiB
FINGERPRINT jax=0.9.0 jaxlib=0.9.0 libtpu=0.0.34 libtpu_sha256=66a7299e... flags_sha256_16=7da78b8c... kernel=6.12.110+ python=3.12.12
[precheck][<node-b>] WARN  2/2 worker hostnames unresolved after 30s
[precheck][<node-b>] [10/10] TPU smoke test (mode=auto)
ERROR: Unknown command line flag 'deepsea_hal_test_allow_multichip_skip_slicebuilder'
[precheck][<node-b>] FAIL  (exit 120) TPU smoke test failed (python rc=1)
[precheck][<node-b>] SUMMARY fails=1 warns=4 elapsed=32s exit=120
[init-8471] peer <job>-1.<svc>:8471 -> closed (gaierror: [Errno -2] Name or service not known)
# R4:precheck_v2b.sh,publishNotReadyAddresses: true
TPU init: 8 local devices, standalone=True, init 3.1s, kinds=['TPU7x']
TPU smoke test PASSED in 4.2s (gemm+allreduce on 8 devices, recipe=hostbounds)
[precheck][<node-b>] SUMMARY fails=0 warns=3 elapsed=9s exit=0
[init-8471] peer <job>-1.<svc>:8471 -> closed (ConnectionRefusedError: [Errno 111] Connection refused)
MAIN_RESULT {"process_count": 2, "global_devices": 16, "local_devices": 8, "psum_ok": true, "peer_8471": {...: "open"}}
# R2:precheck_v2.sh,PRECHECK_TPU_MODE=single,publishNotReadyAddresses: true
PASS  all 2 worker hostnames resolve
TPU init: 8 local devices, standalone=False, init 4.1s, kinds=['TPU7x']
TPU smoke test PASSED in 5.3s (gemm+allreduce on 8 devices)
运行脚本、libtpu、Service第 9 步对端 DNS第 10 步 TPU 冒烟initContainerPod 创建到 main 结束
R1 autov2、0.0.34、默认WARN(等待 30 s)FAIL,未知 deepsea_* flag33 s,rc 120,Init:ErrorJob 34 s 失败
R2 singlev2、0.0.34、publishNotReadyAddresses: truePASSPASS,两个 init 同时完成多机初始化(4.1 s),gemm 加 all-reduce 5.3 s10 s24 s
R3 autov2、0.0.50.1(init 内 pip 安装 15.5 s)、默认WARN(30 s)PASS,standalone,仅 gemm(ICI 关闭)53 s 和 72 s87 s
R4 autov2b、0.0.34、publishNotReadyAddresses: truePASSPASS,gemm 加本机 all-reduce9 s22 s

第 1 到 8 步在所有运行中结果相同:1 PASS(8 个 VFIO 节点和 vBAR socket),2 WARN(镜像无 fuser),3 PASS(8 个 function,vfio-pci,rev 0x00),4 WARN(无 aer_dev_fatal),5 PASS(eth0 MTU 8896,TCP data split off),5b WARN(无 dmesg 权限),6、7、8 PASS 实测。

实测耗时:对端 DNS 可解析时检查本身 9 到 10 s(其中 TPU 冒烟约 5 s),不可解析时 32 到 38 s(30 s DNS 等待);Pod 创建到 main 容器结束 22 到 24 s(基础镜像),在 initContainer 内 pip 安装时 87 s。

判定标准:SUMMARY fails=0 且 exit 0;每个 WARN 都有原因;main 容器 psum_ok: true 且 16 个全局 device 可见。复核实验原样重跑了上面的 Service 与 Pod 模板和附录 A.9.2 的全文脚本:2 个 worker 均 fails=0(3 个 WARN 同上),两个 worker 的对端主机名均可解析,Pod 创建到 init 结束 10 s、main 结束 19 s 实测。

注意事项:

  • precheck_v2.sh 的 auto/standalone 配方沿用 TPUMS 的 --deepsea_hal_test_* flag,libtpu 0.0.34 拒绝该 flag,作业在 init 阶段失败;发布 precheck_v2b.sh 的 HOST_BOUNDS 配方,或要求 libtpu 0.0.50.1 及以上(该配方在 0.0.50.1 上 ICI 关闭,只能做 gemm)实测。
  • 第 9 步需要 headless Service 设置 publishNotReadyAddresses: true(init 阶段 Pod 未 Ready);手写的 Service 默认不设置 实测。
  • single 模式在 initContainer 中不会超时:设置 publishNotReadyAddresses: true 后两个 initContainer 同时启动并完成多机初始化(10 s);Service 未设置时会先等待 DNS 实测。
  • hostNetwork Pod 必须使用 dnsPolicy: ClusterFirstWithHostNet 才能解析 <job>-<i>.<svc> 实测。
  • GKE 向 initContainer 注入 TPU_WORKER_ID、TPU_WORKER_HOSTNAMES、TPU_HOST_BOUNDS=1,1,2,不注入 TPU_PROCESS_ADDRESSES 实测。
  • 对端 TCP 8471 在 init 阶段关闭(拒绝连接或无 DNS),main 容器的 libtpu 运行后才打开;在 initContainer 中探测 8471 永远不会通过 实测。
  • 默认镜像没有 fuser,容器也无法读取 dmesg 和 AER 计数,相应检查固定为 WARN;PCIe 错误改用 Cloud Monitoring(见附录 A.6.1)实测。
  • 附录 A.9.2 为发布版全文,可执行代码与实验运行版本相同 实测。
↩ 返回需求R-05正文2.9 3.3
A.9.2

A.9.2 precheck_v2b.sh 全文#

服务需求R-05实测

服务需求:R-05(见第 1 章);正文:2.9。

下面是附录 A.9.1 中 R4 运行通过(SUMMARY fails=0 warns=3 elapsed=9s exit=0)的脚本全文,复核实验从本附录原样提取后在 2 Pod Job 的 initContainer 中重跑,2 个 worker 均 SUMMARY fails=0 warns=3 elapsed=9s exit=0 实测。与实验运行的版本相比,只删除或改写了注释(去掉实验期标记、内部路径和旧章节号,补充 initContainer 注入变量、PRECHECK_STANDALONE_RECIPE 等说明),并改写了两条失败提示的文字(exit 102:章节引用与 /dev/vfio 被占用时的处置建议;exit 110:删去客户仓库引用);复核运行后 exit 102 的提示文字又改写过一次,可执行代码未改动 实测。

  • 用法:以 ConfigMap 挂载到 initContainer(见附录 A.9.1 的 YAML),bash /precheck/precheck_v2b.sh;退出码 0 表示全部通过,否则为第一个失败项的退出码(100 到 120)。
  • 实验使用的环境变量:PRECHECK_NICS=eth0、PRECHECK_EXPECT_MTU=8896、PRECHECK_TPU_MODE=auto、PRECHECK_TPU_TIMEOUT_S=120、MY_NODE_NAME(downward API);其余取脚本默认值。
  • 默认 PRECHECK_NICS="eth0 eth1";验证集群 guest 内只见 eth0,看不到的网卡只记 WARN。
bash
#!/usr/bin/env bash
# =============================================================================
# precheck_v2b.sh — GKE TPU7x (tpu7x-standard-4t) pre-flight check
#
# HOW TO RUN (recommended): as an initContainer of every TPU worker pod, or as
# the first command of the worker container entrypoint.
#   * The container running this MUST request `google.com/tpu: 4` so the GKE
#     TPU device plugin mounts /dev/vfio/* and /var/run/tpu-plugin/vbar.sock and
#     injects the TPU_* env vars. (K8s lets app containers reuse devices that
#     were allocated to an init container.) GKE injects TPU_WORKER_ID,
#     TPU_WORKER_HOSTNAMES and TPU_HOST_BOUNDS into the initContainer;
#     TPU_PROCESS_ADDRESSES is not injected there.
#   * NIC checks (step 5) are only meaningful with `hostNetwork: true`; in a
#     non-hostNetwork pod eth0 is a veth and is skipped. A NIC that is not
#     visible only produces a WARN (set PRECHECK_NICS to the names you expect).
#   * No privileged mode needed. dmesg (step 5b) and cross-pod process
#     inspection (step 2) are best-effort and are skipped when not permitted.
#
# BEHAVIOUR: runs ALL checks, prints one PASS/WARN/FAIL line per check and a
# summary, then exits with the FIRST failing check's code (0 = all passed).
# Set PRECHECK_FAIL_FAST=1 to stop at the first failure.
#
# Required tools in the image: bash>=4, coreutils (cat readlink basename df
# timeout tr cut sort date), grep, awk, python3 + jax[tpu] (jax, jaxlib,
# libtpu) and numpy. Optional: psmisc (fuser) for step 2, ethtool for step 5,
# util-linux dmesg (+permission) for step 5b, getent (libc-bin) for step 9
# (falls back to python). Pass MY_NODE_NAME via the downward API
# (spec.nodeName) so log lines carry the node name.
#
# Tunables (env):
#   EXPECTED_TPU_DEVICES=8   EXPECTED_VFIO=8   EXPECTED_PCI_FUNCS=8
#   MIN_MEMTOTAL_GIB=900     MIN_MEMAVAIL_GIB=850
#   PRECHECK_DISK_PATHS="/ /tmp"  PRECHECK_DISK_MAX_PCT=90
#   PRECHECK_NICS="eth0 eth1"     PRECHECK_EXPECT_MTU=""   (e.g. 8896)
#   PRECHECK_DNS_WAIT_S=30        PRECHECK_TPU_TIMEOUT_S=180
#   PRECHECK_TPU_MODE=auto|single|standalone|skip
#   PRECHECK_STANDALONE_RECIPE=hostbounds (default) | any other value = TPUMS standalone flags
#   PRECHECK_FAIL_FAST=0
# =============================================================================
set -uo pipefail   # deliberately NOT -e: every check handles its own errors
if [[ -z "${BASH_VERSINFO:-}" || "${BASH_VERSINFO[0]}" -lt 4 ]]; then
  echo "[precheck] FAIL bash>=4 required" >&2; exit 100
fi

START_TS=$(date +%s)
NODE="${MY_NODE_NAME:-${NODE_NAME:-${HOSTNAME:-unknown}}}"
FIRST_FAIL=0
N_FAIL=0
N_WARN=0

EXPECTED_TPU_DEVICES="${EXPECTED_TPU_DEVICES:-8}"
EXPECTED_VFIO="${EXPECTED_VFIO:-8}"
EXPECTED_PCI_FUNCS="${EXPECTED_PCI_FUNCS:-8}"
MIN_MEMTOTAL_GIB="${MIN_MEMTOTAL_GIB:-900}"
MIN_MEMAVAIL_GIB="${MIN_MEMAVAIL_GIB:-850}"
PRECHECK_DISK_PATHS="${PRECHECK_DISK_PATHS:-/ /tmp}"
PRECHECK_DISK_MAX_PCT="${PRECHECK_DISK_MAX_PCT:-90}"
PRECHECK_NICS="${PRECHECK_NICS:-eth0 eth1}"
PRECHECK_EXPECT_MTU="${PRECHECK_EXPECT_MTU:-}"
PRECHECK_DNS_WAIT_S="${PRECHECK_DNS_WAIT_S:-30}"
PRECHECK_TPU_TIMEOUT_S="${PRECHECK_TPU_TIMEOUT_S:-180}"
PRECHECK_TPU_MODE="${PRECHECK_TPU_MODE:-auto}"
PRECHECK_FAIL_FAST="${PRECHECK_FAIL_FAST:-0}"

log()  { printf '[precheck][%s] %s\n' "${NODE}" "$*"; }
pass() { log "PASS  $*"; }
warn() { log "WARN  $*"; N_WARN=$((N_WARN + 1)); }
fail() {  # fail <exit_code> <message>
  local code="$1"; shift
  log "FAIL  (exit ${code}) $*" >&2
  N_FAIL=$((N_FAIL + 1))
  if [[ "${FIRST_FAIL}" -eq 0 ]]; then FIRST_FAIL="${code}"; fi
  if [[ "${PRECHECK_FAIL_FAST}" == "1" ]]; then finish; fi
}
finish() {
  local dur=$(( $(date +%s) - START_TS ))
  log "SUMMARY fails=${N_FAIL} warns=${N_WARN} elapsed=${dur}s exit=${FIRST_FAIL}"
  exit "${FIRST_FAIL}"
}

# -----------------------------------------------------------------------------
# 1/10  VFIO device nodes + vBAR control socket
#   /dev/vfio/<N> nodes are named after IOMMU groups, so count numeric entries
#   instead of assuming 0..7.
# -----------------------------------------------------------------------------
log "[1/10] VFIO device nodes and vBAR socket"
shopt -s nullglob
VFIO_NODES=(/dev/vfio/[0-9]*)
shopt -u nullglob
if [[ "${#VFIO_NODES[@]}" -ne "${EXPECTED_VFIO}" ]]; then
  fail 101 "expected ${EXPECTED_VFIO} numeric /dev/vfio/<group> nodes, found ${#VFIO_NODES[@]} (${VFIO_NODES[*]:-none}); is google.com/tpu: 4 requested by THIS container?"
else
  pass "${#VFIO_NODES[@]} VFIO group nodes: ${VFIO_NODES[*]}"
fi
[[ -c /dev/vfio/vfio ]] || fail 101 "/dev/vfio/vfio container device missing"
VBAR_URL="${VBAR_CONTROL_SERVICE_URL:-unix:/var/run/tpu-plugin/vbar.sock}"
VBAR_SOCK="${VBAR_URL#unix:}"
if [[ -S "${VBAR_SOCK}" ]]; then
  pass "vBAR socket present: ${VBAR_SOCK}"
else
  fail 103 "vBAR socket ${VBAR_SOCK} missing (tpu-device-plugin / vbar-control-agent not ready?)"
fi

# -----------------------------------------------------------------------------
# 2/10  Processes holding /dev/vfio (DETECT ONLY — never kill from a workload pod)
#   Without hostPID a container only sees its own pod's processes, so stale
#   holders from OTHER pods are invisible here; use a hostPID node-debug pod
#   for that (/proc/*/fd scan). The TPU device plugin itself waits on device
#   locks before allocating (args --enable-alloc-wait / --enable-flock-wait).
# -----------------------------------------------------------------------------
log "[2/10] processes holding /dev/vfio (visible PID namespace only)"
if command -v fuser >/dev/null 2>&1 && [[ "${#VFIO_NODES[@]}" -gt 0 ]]; then
  # psmisc prints file names on stderr and PIDs on stdout, sometimes with an
  # access-type suffix (e.g. "1234m" for mmap) -> keep digits only.
  BUSY_PIDS=$(fuser "${VFIO_NODES[@]}" 2>/dev/null | tr -cs '0-9' '\n' | grep -E '^[0-9]+$' | sort -un | tr '\n' ' ' || true)
  BUSY_PIDS="${BUSY_PIDS%% }"
  if [[ -n "${BUSY_PIDS}" ]]; then
    for pid in ${BUSY_PIDS}; do
      st=$(awk '/^State:/ {print $2}' "/proc/${pid}/status" 2>/dev/null || echo "?")
      cmd=$(tr '\0' ' ' 2>/dev/null < "/proc/${pid}/cmdline" | cut -c1-120 || true)
      log "      holder pid=${pid} state=${st} cmd=${cmd}"
    done
    fail 102 "/dev/vfio is held by pid(s) ${BUSY_PIDS}; D-state => cordon node and open a support case, R/S-state => terminate the owning pod (see 3.5.6)"
  else
    pass "no visible process holds /dev/vfio"
  fi
else
  warn "fuser (psmisc) not installed or no VFIO nodes; holder check skipped"
fi

# -----------------------------------------------------------------------------
# 3/10  PCI functions 0x1ae0:0x0076: count, vfio-pci binding, lost device
# -----------------------------------------------------------------------------
log "[3/10] PCI functions 0x1ae0:0x0076 (vfio-pci binding, revision)"
PCI_DEVS=()
for d in /sys/bus/pci/devices/*; do
  v=$(cat "$d/vendor" 2>/dev/null || true)
  dev=$(cat "$d/device" 2>/dev/null || true)
  [[ "$v" == "0x1ae0" && "$dev" == "0x0076" ]] || continue
  PCI_DEVS+=("$d")
  drv="none"
  if [[ -L "$d/driver" ]]; then drv=$(basename "$(readlink -f "$d/driver")"); fi
  rev=$(cat "$d/revision" 2>/dev/null || echo "?")
  numa=$(cat "$d/numa_node" 2>/dev/null || echo "?")
  log "      $(basename "$d") driver=${drv} rev=${rev} numa=${numa}"
  [[ "${drv}" == "vfio-pci" ]] || fail 104 "$(basename "$d") bound to '${drv}', expected vfio-pci"
  [[ "${rev}" != "0xff" ]] || fail 105 "$(basename "$d") revision 0xff (device fell off the bus)"
done
if [[ "${#PCI_DEVS[@]}" -ne "${EXPECTED_PCI_FUNCS}" ]]; then
  fail 105 "expected ${EXPECTED_PCI_FUNCS} TPU PCI functions, found ${#PCI_DEVS[@]}"
else
  pass "${#PCI_DEVS[@]} TPU PCI functions present"
fi

# -----------------------------------------------------------------------------
# 4/10  PCIe AER fatal counters + link state (informational on GCE)
#   aer_dev_fatal lists per-type counters PLUS a TOTAL_ERR_FATAL line, so read
#   TOTAL_ERR_FATAL instead of summing everything.
#   On GCE the TPU functions report current_link_speed=Unknown / width=0,
#   so link speed cannot be gated here; use the Cloud Monitoring
#   pcie_fatal_error_count / pcie_nonfatal_error_count metrics instead.
#   On GKE TPU VMs aer_dev_fatal is not exposed, so this step reports WARN.
# -----------------------------------------------------------------------------
log "[4/10] PCIe AER counters / link state"
aer_seen=0
for d in "${PCI_DEVS[@]}"; do
  if [[ -r "$d/aer_dev_fatal" ]]; then
    aer_seen=1
    tot=$(awk '$1=="TOTAL_ERR_FATAL" {print $2}' "$d/aer_dev_fatal" 2>/dev/null)
    tot="${tot:-0}"
    [[ "${tot}" =~ ^[0-9]+$ && "${tot}" -eq 0 ]] || fail 106 "$(basename "$d") TOTAL_ERR_FATAL=${tot}"
  fi
  spd=$(cat "$d/current_link_speed" 2>/dev/null || echo "Unknown")
  wid=$(cat "$d/current_link_width" 2>/dev/null || echo "0")
  if [[ "${spd}" != "Unknown" && "${spd}" != *"32.0 GT/s"* ]]; then
    fail 107 "$(basename "$d") PCIe link speed degraded: ${spd}"
  fi
  if [[ "${wid}" != "0" && "${wid}" != "16" ]]; then
    fail 108 "$(basename "$d") PCIe link width degraded: x${wid}"
  fi
done
if [[ "${aer_seen}" -eq 1 ]]; then pass "AER fatal counters checked"; else warn "aer_dev_fatal not exposed in this VM/container; rely on Cloud Monitoring pcie_*_error_count"; fi

# -----------------------------------------------------------------------------
# 5/10  DCN NICs (hostNetwork pods only): operstate, MTU, TCP data split
#   'TCP data split' is an ethtool RING parameter (-g), printed as
#   "TCP data split:<TAB><TAB>off" — strip spaces AND tabs, otherwise "on"
#   is never detected. Do NOT toggle it at runtime
#   (re-allocates rings under traffic).
# -----------------------------------------------------------------------------
log "[5/10] DCN NICs"
for nic in ${PRECHECK_NICS}; do
  if [[ ! -d "/sys/class/net/${nic}" ]]; then
    warn "${nic} not visible (pod without hostNetwork, or different NIC name); skipped"
    continue
  fi
  if [[ -e "/sys/class/net/${nic}/device" ]]; then :; else
    warn "${nic} is a virtual interface (no PCI device) — pod is not hostNetwork; skipped"
    continue
  fi
  st=$(cat "/sys/class/net/${nic}/operstate" 2>/dev/null || echo "unknown")
  [[ "${st}" == "up" ]] || fail 109 "${nic} operstate=${st}"
  mtu=$(cat "/sys/class/net/${nic}/mtu" 2>/dev/null || echo "?")
  if [[ -n "${PRECHECK_EXPECT_MTU}" && "${mtu}" != "${PRECHECK_EXPECT_MTU}" ]]; then
    warn "${nic} MTU=${mtu}, expected ${PRECHECK_EXPECT_MTU}"
  fi
  if command -v ethtool >/dev/null 2>&1; then
    tds=$(ethtool -g "${nic}" 2>/dev/null | awk -F: 'tolower($1) ~ /tcp data split/ {v=$2; gsub(/[ \t]/, "", v); print v; exit}')
    case "${tds}" in
      on)  fail 110 "${nic} TCP data split=on (gve TX-timeout risk); fix via GKE upgrade + pool recreate, not ethtool at runtime" ;;
      off) pass "${nic} up, MTU=${mtu}, TCP data split=off" ;;
      *)   warn "${nic} up, MTU=${mtu}, TCP data split not reported (ethtool $(ethtool --version 2>/dev/null | awk '{print $NF}'))" ;;
    esac
  else
    warn "${nic} up, MTU=${mtu}; ethtool missing — TCP data split not checked"
  fi
done
# 5b: gve reset / NETDEV WATCHDOG in the kernel log (needs dmesg permission)
if dmesg_out=$(dmesg 2>/dev/null); then
  resets=$(printf '%s\n' "${dmesg_out}" | grep -ciE 'gve.*reset|NETDEV WATCHDOG' || true)
  if [[ "${resets}" -gt 0 ]]; then warn "kernel log has ${resets} gve reset / NETDEV WATCHDOG lines"; else pass "no gve reset in kernel log"; fi
else
  warn "dmesg not permitted in this container; gve reset check skipped"
fi

# -----------------------------------------------------------------------------
# 6/10  Disk usage of the paths this container writes to
# -----------------------------------------------------------------------------
log "[6/10] disk usage"
for mp in ${PRECHECK_DISK_PATHS}; do
  use_pct=$(df -P "${mp}" 2>/dev/null | awk 'NR==2 {gsub(/%/, "", $5); print $5}')
  if [[ ! "${use_pct}" =~ ^[0-9]+$ ]]; then warn "df failed for ${mp}"; continue; fi
  if [[ "${use_pct}" -ge "${PRECHECK_DISK_MAX_PCT}" ]]; then
    fail 111 "${mp} usage ${use_pct}% >= ${PRECHECK_DISK_MAX_PCT}%"
  else
    pass "${mp} usage ${use_pct}%"
  fi
done

# -----------------------------------------------------------------------------
# 7/10  Host memory (/proc/meminfo shows NODE values in a GKE container)
#   Idle tpu7x-standard-4t node: MemTotal 990725056 kB (944.8 GiB),
#   MemAvailable about 934 GiB. 900/850 GiB are defaults;
#   lower MIN_MEMAVAIL_GIB if the pod uses memory-backed emptyDir / big caches.
# -----------------------------------------------------------------------------
log "[7/10] host memory"
mem_tot_kb=$(awk '/^MemTotal:/ {print $2}' /proc/meminfo)
mem_avl_kb=$(awk '/^MemAvailable:/ {print $2}' /proc/meminfo)
min_tot_kb=$(( MIN_MEMTOTAL_GIB * 1024 * 1024 ))
min_avl_kb=$(( MIN_MEMAVAIL_GIB * 1024 * 1024 ))
if [[ "${mem_tot_kb:-0}" -lt "${min_tot_kb}" ]]; then
  fail 112 "MemTotal ${mem_tot_kb} kB < ${MIN_MEMTOTAL_GIB} GiB (${min_tot_kb} kB)"
elif [[ "${mem_avl_kb:-0}" -lt "${min_avl_kb}" ]]; then
  fail 113 "MemAvailable ${mem_avl_kb} kB < ${MIN_MEMAVAIL_GIB} GiB (${min_avl_kb} kB)"
else
  pass "MemTotal $((mem_tot_kb / 1048576)) GiB, MemAvailable $((mem_avl_kb / 1048576)) GiB"
fi

# -----------------------------------------------------------------------------
# 8/10  Software fingerprint (compare this line across all workers)
#   libtpu.__version__ / libtpu.get_library_path() exist. The hash of
#   LIBTPU_INIT_ARGS/XLA_FLAGS is printed because differing flags across
#   workers produce different program fingerprints (FINGERPRINT_MISMATCH).
# -----------------------------------------------------------------------------
log "[8/10] software fingerprint"
if ! python3 - <<'PY'
import hashlib, os, platform, sys
try:
    import jax, jaxlib
except Exception as e:  # noqa: BLE001
    print(f"FINGERPRINT_ERROR cannot import jax: {e}", file=sys.stderr); sys.exit(1)
lt_ver, lt_path = "n/a", None
try:
    import libtpu
    lt_ver = getattr(libtpu, "__version__", "n/a")
    lt_path = libtpu.get_library_path()
except Exception as e:  # noqa: BLE001
    lt_path = os.environ.get("TPU_LIBRARY_PATH")
digest = "n/a"
if lt_path and os.path.exists(lt_path):
    h = hashlib.sha256()
    with open(lt_path, "rb") as f:
        for chunk in iter(lambda: f.read(1 << 20), b""):
            h.update(chunk)
    digest = h.hexdigest()
flags = hashlib.sha256((os.environ.get("LIBTPU_INIT_ARGS", "") + "|" + os.environ.get("XLA_FLAGS", "")).encode()).hexdigest()[:16]
print(f"FINGERPRINT jax={jax.__version__} jaxlib={jaxlib.__version__} libtpu={lt_ver} "
      f"libtpu_sha256={digest} flags_sha256_16={flags} kernel={platform.release()} python={platform.python_version()}")
PY
then
  fail 114 "software fingerprint failed (jax/libtpu not importable)"
else
  pass "fingerprint printed (grep FINGERPRINT across workers; all fields except kernel must match)"
fi

# -----------------------------------------------------------------------------
# 9/10  Peer name resolution (WARN only)
#   TCP 8471 (libtpu) is only bound after libtpu starts in the WORKER
#   container, so it is not probed here (it is always closed during init).
#   DNS of all TPU_WORKER_HOSTNAMES is checked instead (catches a
#   missing peer pod / headless-service record).
#   A hand-written headless Service needs publishNotReadyAddresses: true,
#   otherwise pods in init are not published and this stays a WARN.
# -----------------------------------------------------------------------------
log "[9/10] peer DNS (TPU_WORKER_HOSTNAMES)"
if [[ -n "${TPU_WORKER_HOSTNAMES:-}" && "${TPU_WORKER_HOSTNAMES}" != "localhost" ]]; then
  IFS=',' read -r -a PEERS <<< "${TPU_WORKER_HOSTNAMES}"
  deadline=$(( $(date +%s) + PRECHECK_DNS_WAIT_S ))
  pending=("${PEERS[@]}")
  while :; do
    still=()
    for p in "${pending[@]}"; do
      if command -v getent >/dev/null 2>&1; then
        getent hosts "${p}" >/dev/null 2>&1 || still+=("${p}")
      else
        python3 -c "import socket,sys; socket.getaddrinfo(sys.argv[1], None)" "${p}" >/dev/null 2>&1 || still+=("${p}")
      fi
    done
    pending=(${still[@]+"${still[@]}"})
    [[ "${#pending[@]}" -eq 0 || $(date +%s) -ge ${deadline} ]] && break
    sleep 3
  done
  if [[ "${#pending[@]}" -eq 0 ]]; then
    pass "all ${#PEERS[@]} worker hostnames resolve"
  else
    warn "${#pending[@]}/${#PEERS[@]} worker hostnames unresolved after ${PRECHECK_DNS_WAIT_S}s: ${pending[*]:0:8}"
  fi
else
  log "      TPU_WORKER_HOSTNAMES unset/localhost (single-host or not injected into this container); skipped"
fi

# -----------------------------------------------------------------------------
# 10/10  TPU smoke test (bounded by PRECHECK_TPU_TIMEOUT_S)
#   * jax.device_put_replicated is gone in current JAX (absent in 0.11.1 and
#     0.12.0); this uses jit + NamedSharding.
#   * single-host slice (TPU_HOST_BOUNDS unset or 1,1,1): per-device GEMM +
#     an all-reduce over the 8 local devices (exercises local ICI/D2D).
#   * multi-host slice node (mode auto), default recipe "hostbounds":
#     TPU_HOST_BOUNDS=1,1,1 + localhost worker env isolates this host and keeps
#     the local 2x2x1 ICI, so GEMM + local all-reduce run (libtpu 0.0.34 OK).
#     Any other PRECHECK_STANDALONE_RECIPE uses the TPUMS standalone-host flags
#     (needs libtpu >= 0.0.50.1, disables ICI, GEMM only).
#   * mode single: full multi-host libtpu init; all workers must start
#     together and peer DNS must resolve. Unknown LIBTPU_INIT_ARGS flags abort
#     the process before TPU init.
# -----------------------------------------------------------------------------
log "[10/10] TPU smoke test (mode=${PRECHECK_TPU_MODE})"
if [[ "${PRECHECK_TPU_MODE}" == "skip" ]]; then
  warn "TPU smoke test skipped by PRECHECK_TPU_MODE=skip"
else
  PRECHECK_TPU_MODE="${PRECHECK_TPU_MODE}" EXPECTED_TPU_DEVICES="${EXPECTED_TPU_DEVICES}" \
  timeout "${PRECHECK_TPU_TIMEOUT_S}" python3 - <<'PY'
import os, sys, time
t_start = time.time()
mode = os.environ.get("PRECHECK_TPU_MODE", "auto")
host_bounds = os.environ.get("TPU_HOST_BOUNDS", "").replace(" ", "")
multi_host_env = (host_bounds not in ("", "1,1,1")) or ("," in os.environ.get("TPU_WORKER_HOSTNAMES", ""))
standalone = mode == "standalone" or (mode == "auto" and multi_host_env)
if standalone:
    # Same recipe as accelerator-microbenchmarks src/accelerator_microbenchmarks/core/standalone_host.py
    os.environ.update({"TPU_HOST_BOUNDS": "1,1,1", "TPU_SKIP_MDS_QUERY": "true",
                       "TPU_WORKER_ID": "0", "TPU_WORKER_HOSTNAMES": "localhost"})
    for k in ("TPU_PROCESS_ADDRESSES", "TPU_PROCESS_ADDRESSES_PATH"):
        os.environ.pop(k, None)
recipe = os.environ.get("PRECHECK_STANDALONE_RECIPE", "hostbounds")
if standalone and recipe == "hostbounds":
    # Default: TPU_HOST_BOUNDS=1,1,1 (+ localhost worker env) alone isolates this host AND keeps the local
    # 2x2x1 ICI (SliceBuilder runs for the sub-slice); no deepsea_* flags -> works on libtpu 0.0.34 too.
    pass
elif standalone:
    flags = {}
    for tok in os.environ.get("LIBTPU_INIT_ARGS", "").split():
        name, sep, val = tok.partition("=")
        flags[name] = val if sep else None
    flags.update({"--deepsea_hal_test_skip_slicebuilder": "true",
                  "--deepsea_hal_test_allow_multichip_skip_slicebuilder": "true",
                  "--xla_tpu_use_enhanced_launch_barrier": "false"})
    os.environ["LIBTPU_INIT_ARGS"] = " ".join(k if v is None else f"{k}={v}" for k, v in flags.items())

import numpy as np
import jax
import jax.numpy as jnp
from jax.sharding import Mesh, NamedSharding, PartitionSpec as P

devs = jax.local_devices()
want = int(os.environ.get("EXPECTED_TPU_DEVICES", "8"))
print(f"TPU init: {len(devs)} local devices, standalone={standalone}, "
      f"init {time.time() - t_start:.1f}s, kinds={sorted({d.device_kind for d in devs})}")
if len(devs) != want:
    print(f"FATAL: expected {want} local TPU devices, got {len(devs)}", file=sys.stderr)
    sys.exit(2)

n = len(devs)
mesh = Mesh(np.array(devs), ("d",))
shard = NamedSharding(mesh, P("d"))

# (a) Per-device GEMM on identical inputs -> outputs must be bitwise identical.
rng = np.random.default_rng(1234)
a = (rng.standard_normal((2048, 2048), dtype=np.float32) * 0.02).astype(jnp.bfloat16)
x = jax.device_put(np.broadcast_to(a, (n, 2048, 2048)).copy(), shard)
gemm = jax.jit(jax.vmap(lambda m: jnp.matmul(m, m, preferred_element_type=jnp.float32)),
               out_shardings=shard)
out = np.asarray(gemm(x))
if not np.all(np.isfinite(out)):
    print("FATAL: non-finite GEMM output", file=sys.stderr); sys.exit(3)
bits = out.view(np.uint32)
bad = [i for i in range(n) if not np.array_equal(bits[i], bits[0])]
if bad:
    print(f"FATAL: GEMM output differs from device 0 on devices {bad} ({[str(devs[i]) for i in bad]})", file=sys.stderr)
    sys.exit(4)

# (b) All-reduce across local devices (only when ICI is configured).
if not standalone or recipe == "hostbounds":
    ones = jax.device_put(np.ones((n, 1024, 1024), dtype=jnp.bfloat16), shard)
    total = np.asarray(jax.jit(lambda t: jnp.sum(t, axis=0, dtype=jnp.float32))(ones))
    if not np.all(total == float(n)):
        print(f"FATAL: all-reduce mismatch (expected {n})", file=sys.stderr); sys.exit(5)

print(f"TPU smoke test PASSED in {time.time() - t_start:.1f}s "
      f"(gemm{'+allreduce' if (not standalone or recipe == 'hostbounds') else ''} on {n} devices, recipe={recipe if standalone else 'none'})")
PY
  rc=$?
  case "${rc}" in
    0)   pass "TPU smoke test" ;;
    124) fail 120 "TPU smoke test timed out after ${PRECHECK_TPU_TIMEOUT_S}s (multi-host init waiting for peers? set PRECHECK_TPU_MODE=standalone)" ;;
    *)   fail 120 "TPU smoke test failed (python rc=${rc})" ;;
  esac
fi

finish
↩ 返回需求R-05正文2.9

A.10 故障上报 CLI(对应 2.10)#

A.10.1

A.10.1 故障上报与节点池升级相关 CLI(仅查看帮助)#

服务需求R-13实测耗时全部 help 和 explain 调用共 18 s实测

服务需求:R-13(见第 1 章);正文:2.10。

目的:确认运维手册引用的命令和 flag 写法,不执行任何破坏性操作。

前置:A.0.2。Google Cloud SDK 591.0.0。

命令:

bash
gcloud compute instances report-host-as-faulty --help            # GA;beta、alpha 也可用
gcloud container node-pools update --help | sed -n '/^ *--autoscaled-rollout-policy=/,/^ *--boot-disk-provisioned-iops/p'
kubectl get crd -o name | grep -i -E 'slice|jobset|kueue|leaderworkerset'
kubectl explain slice

裁剪输出:

输出
gcloud compute instances report-host-as-faulty INSTANCE_NAME
    --disruption-schedule=DISRUPTION_SCHEDULE
    --fault-reasons=[behavior=BEHAVIOR],[description=DESCRIPTION] [--async] [--zone=ZONE]
REQUIRED FLAGS
 --disruption-schedule=DISRUPTION_SCHEDULE   ... must be one of: IMMEDIATE, FUTURE.
 --fault-reasons=[behavior=BEHAVIOR],[description=DESCRIPTION]
    ['BEHAVIOR_UNSPECIFIED', 'PERFORMANCE', 'SILENT_DATA_CORRUPTION', 'UNRECOVERABLE_GPU_ERROR', 'CHIP_ERROR']
EXAMPLE
 gcloud compute instances report-host-as-faulty test-instance \
   --fault-reasons=behavior=SILENT_DATA_CORRUPTION,description="affecting our ML job" --disruption-schedule=IMMEDIATE
--max-surge-upgrade=MAX_SURGE_UPGRADE              Must be used in conjunction with '--max-unavailable-upgrade'.
--max-unavailable-upgrade=MAX_UNAVAILABLE_UPGRADE  Must be used in conjunction with '--max-surge-upgrade'.
--enable-surge-upgrade  --enable-blue-green-upgrade  --node-pool-soak-duration
--standard-rollout-policy=[batch-node-count=BATCH_NODE_COUNT,batch-percent=BATCH_NODE_PERCENTAGE,batch-soak-duration=BATCH_SOAK_DURATION,...]
kubectl get crd (slice/jobset/kueue/leaderworkerset)  ->  无输出
kubectl explain slice  ->  error: the server doesn't have a resource type "slice"

实测耗时:全部 help 和 explain 调用共 18 s。

判定标准:报告中的命令和 flag 与帮助文本一致,GA 轨道即可使用。

注意事项:

  • --disruption-schedule 和 --fault-reasons 都列在 REQUIRED FLAGS 下;帮助正文虽提到默认 IMMEDIATE,命令行仍应显式给出 实测。
  • behavior 枚举没有 TPU_* 取值;All Capacity 模式的 TPU VM 按 TPU 文档 使用 PERFORMANCE、SILENT_DATA_CORRUPTION 或 BEHAVIOR_UNSPECIFIED,CHIP_ERROR 不在 TPU 文档列出的取值中 文档;GKE 管理的 TPU 节点不使用该命令,按 2.10 隔离并开支持工单。
  • 验证集群没有 Slice、JobSet、Kueue、LeaderWorkerSet CRD,kubectl explain slice 无法演示 实测。
↩ 返回需求R-13正文2.10

A.11 告警与故障处置演练(对应 3.4、3.5)#

A.11.1

A.11.1 慢节点与 hang:信号、检测时延与判定门限#

服务需求R-12实测耗时apply 到两个 Pod Running 4 s,device 就绪 8 s,6 m…实测含估算

服务需求:R-12(见第 1 章);正文:3.4、3.5.2、3.5.4。

目的:在同步的 2 host JAX 作业(一个 2x2x2 slice,16 个 TensorCore)中注入慢 host,测量哪些信号能指出慢节点以及多快:带内 15 s 采集器指标(GMP)、60 s GKE 系统指标(kubernetes.io/node/accelerator/*)、步日志(三级方法:L1 最后到达者加二项检验,L2 最低集合通信等待,L3 健康与维护交叉核对)、ML Diagnostics;随后制造 12 min hang。两类慢节点:计算型(worker 1 每步多做 50% 设备计算)和 host 型(worker 1 每步前 sleep 900 ms,模拟慢输入管线)。

前置:A.0.5(Indexed Job 加 headless Service),附录 A.5.1 的采集器部署在同一命名空间,附录 A.11.2 的 log-based metric。负载 straggler.py:每 device 384 次链式 bf16 8192² matmul,加 16 device 的 fp32 8192² psum;阶段切换通过步内 pmax 协商,两个 worker 在同一步切换;每步输出一行步日志。

命令:

yaml
# Job 容器的阶段参数(manifest_job.yaml 摘录)
env:
- {name: MAT_N, value: "8192"}
- {name: K, value: "384"}                 # 每步每 device 的 matmul 次数
- {name: EXTRA_K, value: "192"}           # 计算型慢节点额外次数(+50%)
- {name: HOST_SLEEP_MS, value: "900"}     # host 型慢节点每步前 sleep
- {name: STRAGGLER, value: "1"}           # 慢节点 worker 序号
- {name: STARTUP_IDLE_S, value: "360"}    # 模拟 6 min 启动
- {name: HANG_S, value: "720"}
- {name: PHASES, value: "base:900,compute:600,host:600,hang:30,base:1020"}   # 时间表从首个 step 起按墙钟计;hang 实际停 HANG_S 秒,最后的 base 约 5.5 min
bash
kubectl -n $NS create configmap straggler-script --from-file=straggler.py --dry-run=client -o yaml > manifest_cm.yaml
kubectl -n $NS apply -f manifest_cm.yaml -f manifest_job.yaml     # Job 挂载 straggler-script;straggler.py、analyze_steps.py 未随本文发布
# 步日志格式(每个 worker 每步一行)
# completed step: <s>, seconds: <dt>, worker: <w>, phase: <p>, wait_ms: <blocked>, host_ms: <prep>, t_disp: <epoch>, t: <epoch>
python3 analyze_steps.py main_w0.log main_w1.log > analysis.json     # L1(原始与 5 ms 门限)、L2
PromQL
avg by (node)(duty_cycle{cluster="<CLUSTER>"})                                   # 带内 15 s
avg by (node)(tensorcore_utilization_node{cluster="<CLUSTER>"})
sum by (node)(rate(hlo_execution_timing_microsecond_sum{cluster="<CLUSTER>"}[1m]))
  / sum by (node)(rate(hlo_execution_timing_microsecond_count{cluster="<CLUSTER>"}[1m]))
avg by (node_name)(kubernetes_io:node_accelerator_duty_cycle{monitored_resource="k8s_node", cluster_name="<CLUSTER>"})   # GKE 系统指标 60 s

L1 门限:一步中两个 worker 的到达时间差小于 5 ms 时视为平局,不计入;只对差值不小于 5 ms 的步统计最后到达者占比,并对 1/K(K 为 worker 数)做单侧二项检验 实测。

裁剪输出(各阶段均值,正常节点 / 慢节点):

输出
phase      step_s  duty15s      TCutil15s(node)  hlo_exec_mean_ms  GKE duty60s   GKE TCutil60s  host_wait_ms   L1 (5 ms gate)
base       0.520   99.96/99.89  63.7/67.8        1039/1039         99.8/100      64.7/69.5      519/519        no flag
compute    0.772   97.4/97.5    40.6/67.5 (*)    1550/1271 (*)     88.9/100      39.4/67.9 (*)  771/771        no flag
host       0.901   100/58.5 (*) 37.6/37.8        1790/562 (*)      100/56.8 (*)  45.0/37.2      900/0.2 (*)    w1 667/667, p 1.6e-201
hang       -       0/0          0/0              -                 0/0           0/0            -              -
recovery   0.520   99.7/99.7    64.6/66.3        1038/1038         100/99.9      64.2/77.6      519/519        no flag
(*) = 能区分慢节点
不加门限的原始二项检验:base "worker0 73.7 %, p=5.7e-90",recovery "worker1 81 %, p=1.1e-59"(到达差 0.3 ms)-> 误报
L3:infra_health HEALTHY,chip_state 4/4 HEALTHY,维护只有 2026-11-09 的计划窗口 -> 只列入可疑名单,不 cordon
多 slice 指标(collective_e2e_latency、kubernetes.io/container/multislice/*):单 slice 作业无数据

检测时延(连续 2 个样本相差至少 25%,以样本时间计)实测:

慢节点类型信号慢节点上的表现检测时延
host 型带内 duty_cycle(15 s)最低(58.5 对 100)40 s
host 型带内 hlo_execution_timing 均值最低(562 对 1790 ms)40 s
host 型GKE 系统指标 node/accelerator/duty_cycle(60 s)最低(56.8 对 100)130 s,另加入库延迟(以同一描述符的 memory_used 实测 1 到 31 s 作代理)
host 型步日志 L1(5 ms 门限)、L2最后到达 667/667 步;host 等待最低(0.2 对 900 ms)阶段开始后第一个 50 步窗口(约 45 s)
计算型带内 tensorcore_utilization_node(15 s)最高(67.5 对 40.6,正常节点在等待中下降)41 s
计算型带内 hlo_execution_timing 均值最低(1271 对 1550 ms)71 s
计算型GKE 系统指标 node/accelerator/tensorcore_utilization(60 s)最高(67.9 对 39.4)131 s(10% 门限)到 431 s(25% 门限),另加 48 到 78 s 入库延迟
两类步时、log-based 步数两个 worker 相同(同步),只反映作业级变慢:每分钟 112.1 步降到 78.5(计算型)、67.1(host 型)不能定位节点

实测耗时:apply 到两个 Pod Running 4 s,device 就绪 8 s,6 min 模拟启动后首步编译加运行 2.2 s;各阶段 15、10、10、12、5.5 min,整个 Job 59 min(3,794 步);另有一次 3 min 的冒烟 Job;每次快照约 20 s,分析约 15 s。

判定标准:每类慢节点至少有一个指标能指出 worker 1。host 型:duty_cycle 最低(带内 15 s 和 GKE 系统指标 60 s)、host 等待最低、加门限后的最后到达者;计算型:tensorcore_utilization、memory_bandwidth_utilization 最高;两类:hlo_execution_timing 最低。

注意事项:

  • 同步 SPMD 中所有 worker 的步时相同,逐 worker 步时永远无法识别慢节点 实测。
  • “慢节点 TensorCore 利用率最高”只对设备侧慢节点成立(它多做计算,其他节点在等待);host 侧慢节点的利用率与其他节点相同,duty_cycle 最低。降频导致的慢节点未测试 实测。
  • 不加门限的最后到达者二项检验在健康阶段也给出极小 p 值(0.3 ms 的到达差由抖动和时钟偏差决定),会误报;先过滤到达差(本实验取 5 ms)再检验后,只有 host 型慢节点被标出,计算型未被标出 实测。
  • “最后到达占比不低于 max(50%, 3/K)”的规则在 K=2 时不可能触发(3/K=150%;本实验 host 型慢节点占比 100% 也未触发)实测;K=3 时要求 100%,K≥6 时门限才降到 50% 估算。
  • host 侧延迟短于设备步时会被异步派发掩盖(冒烟测试中 150 ms sleep 对 170 ms 步时,没有变慢)实测。
  • 60 s GKE 系统指标噪声大(阶段边界有一个 0 值样本,阶段内 TensorCore 利用率也在 10% 到 78% 间跳动),带内 15 s 序列干净;基线阶段两个节点的 TensorCore 利用率已相差 4 到 13 个百分点 实测。建议判定至少用 3 个样本的窗口,离群门限不低于 25%(起始值,按上线后 2 周实测基线调整)。
  • compute.googleapis.com/instance/tpu/accelerator/* 在整个 TPU 负载期间都没有数据(见附录 A.6.2)实测。
  • 单 slice 作业中 tpu-info 0.14.2 的 collective_e2e_latency 报 unavailable(需要多 slice)实测。
  • 只有统计信号、L3 健康与维护检查都正常时,只列入可疑名单,不自动 cordon 实测。
  • 节点标签 cloud.google.com/scheduled-maintenance-time=1794254400 即 2026-11-09T20:00:00Z,与 GCE upcomingMaintenance 窗口开始时间一致(canReschedule: true,onHostMaintenance: TERMINATE);分区与拓扑标签在该静态节点池上为空,physicalHost、physicalHostTopology 未返回;节点上没有 Megascale 或 SliceError 类 condition 实测。
  • ML Diagnostics 对两类慢节点都没有产生事件,hang 开始后 37 s 出现一个 PERFORMANCE_DEGRADATION(见附录 A.8.1)实测。
↩ 返回需求R-12正文3.4 3.5.2 3.5.4
A.11.2

A.11.2 进度告警:log-based metric 与 duty cycle 规则#

服务需求R-09R-12实测耗时创建 log-based metric 每个 3 s,创建告警策略 4 s实测

服务需求:R-09、R-12(见第 1 章);正文:3.4。

目的:不改代码、不加 sidecar,把训练循环的 completed step: N, seconds: X 日志行变成 Cloud Monitoring 指标,在进度停止时告警,测量触发与恢复时延(实验取 5 min 无进度以缩短演练,生产阈值见 3.4.3 B1);并与简单的“duty_cycle == 0 持续 5 min”规则比较,后者在启动和编译阶段也会触发。

前置:A.0.8;负载 stdout 进入 Cloud Logging(GKE 工作负载日志);负载为附录 A.11.1 的 Job(每个 worker 每步一行,0.52 s 步时下约每分钟 115 行)。实验对象不配置通知渠道,实验后删除。

命令:

yaml
# lbm_step_count.yaml(计数器,按 worker 打标签)
name: tpu-verify-step-count
filter: >-
  resource.type="k8s_container" AND resource.labels.cluster_name="<CLUSTER>"
  AND resource.labels.namespace_name="tpu-verify" AND resource.labels.container_name="straggler"
  AND textPayload:"completed step:"
labelExtractors:
  worker: 'REGEXP_EXTRACT(textPayload, "worker: ([0-9]+)")'
metricDescriptor:
  metricKind: DELTA
  valueType: INT64
  unit: "1"
  labels:
  - key: worker
    valueType: STRING
# lbm_step_seconds.yaml 相同 filter,另加 valueExtractor: 'REGEXP_EXTRACT(textPayload, "seconds: ([0-9.]+)")',
# 标签 worker、phase,DELTA DISTRIBUTION,单位 s。提取表达式含 ": ",必须加引号
json
{
 "displayName": "tpu-verify-step-absent",
 "documentation": {"content": "No 'completed step' line for 5 min from any worker.", "mimeType": "text/markdown"},
 "combiner": "OR",
 "conditions": [{
   "displayName": "no step progress for 5 min",
   "conditionAbsent": {
     "filter": "resource.type = \"k8s_container\" AND metric.type = \"logging.googleapis.com/user/tpu-verify-step-count\"",
     "aggregations": [{"alignmentPeriod": "60s", "perSeriesAligner": "ALIGN_SUM", "crossSeriesReducer": "REDUCE_SUM", "groupByFields": ["metric.label.worker"]}],
     "duration": "300s",
     "trigger": {"count": 1}
   }
 }],
 "alertStrategy": {"autoClose": "1800s"},
 "enabled": true,
 "notificationChannels": []
}
bash
gcloud logging metrics create tpu-verify-step-seconds --config-from-file=lbm_step_seconds.yaml --project $PROJECT
gcloud logging metrics create tpu-verify-step-count   --config-from-file=lbm_step_count.yaml   --project $PROJECT
gcloud alpha monitoring policies create --policy-from-file=policy_step_absent.json --project $PROJECT
PromQL
sum by (worker)(rate(logging_googleapis_com:user_tpu_verify_step_count{monitored_resource="k8s_container"}[2m])) * 60      # 每分钟步数
# 按阶段门控的 duty cycle 规则:duty cycle 为 0 持续 5 min,且该作业 60 min 内已有步数
(max by (node)(max_over_time(duty_cycle{cluster="<CLUSTER>"}[5m])) == 0)
  and on() (sum(sum_over_time(logging_googleapis_com:user_tpu_verify_step_count{monitored_resource="k8s_container", pod_name=~"straggler-.*"}[60m])) > 0)

上面的 duty cycle 部分按集群聚合;生产中限定到本作业所在节点(同 B6),否则其他作业空闲或挂起的 TPU 节点也会触发。

裁剪输出:

输出
steps/min per worker (log-based metric): base 112 | compute straggler 78.5 | host straggler 67 | hang - | recovery 105
last step line before the hang          13:55:51.07Z  (both workers)
alert OPEN  worker=0 / worker=1         14:06:43Z  -> 最后一步后 10 min 52 s(300 s 缺失窗口加约 5.9 min 管线延迟)
alert CLOSED                            14:11:31Z  (14:07:51Z 恢复出步 -> +3 min 40 s)
正常结束:最后一步 14:13:19Z(exit 0)-> alert OPEN 14:24:43Z(+11 min 24 s,误报)
duty_cycle==0 for 5 min (in-band 15 s): TRUE 13:19:30-13:21:00 (启动空闲,误报) and 14:01:15-14:08:00 (hang,+5 min 24 s)
同一规则用 GKE 系统指标 kubernetes.io/container duty: 13:15:00 起即为 TRUE([5m] 内只有 1 个样本,max==0);
  加覆盖门限 count_over_time(...[5m])>=4 后推迟到 13:18:00;hang 段 14:01:00-14:08:00
按阶段门控:duty0_5m AND sum_over_time(step_count{pod_name=~"straggler-.*"}[60m])>0 -> 启动段被抑制
  (13:21:00 首批步数计入时有一次单点,告警策略加 60 s 持续时间即可消除);hang 14:01:15 触发
规则hang 检测时延启动阶段正常结束后
log-based 步数缺失 300 s10 min 52 s;恢复后 3 min 40 s 关闭不触发(尚无序列)11 min 24 s 后误报
带内 duty_cycle == 0 持续 5 min5 min 24 s误报(13:19:30)未评估
同上加步数门控5 min 24 s(14:01:15)抑制(加 60 s 持续时间后无单点)未评估

告警演练步骤(每项记录告警时间):

  • B1、B4:运行中对训练进程发 SIGSTOP;B2:在首步前暂停或延长启动;B3、B6:在一个 worker 注入固定 sleep(附录 A.11.1)。
  • A 组:对 24 h 内已出现的 UNHEALTHY 片段回放查询(附录 A.6.1),确认表达式与通知路由。
  • C1:对已有的 MaintenanceWindowScheduled 事件回放日志条件(附录 A.7.1)。
  • D1:回放 absent_over_time(...tray_temperature...[30m])(本集群当前为 1),确认通知路由;D2:删除测试命名空间中的采集器 Pod。
  • 每个通知渠道收到一次测试通知,runbook 链接可打开。

实测耗时:创建 log-based metric 每个 3 s,创建告警策略 4 s;首批计数在第一批匹配日志后约 1 min 可见;hang 到告警 10 min 52 s,恢复到关闭 3 min 40 s;带内 duty cycle 规则在 hang 开始后 5 min 24 s 触发。

判定标准:计数器和分布指标按 worker 有数据;5 min 缺失被检测到(实际晚于配置的 5 min);简单 duty cycle 规则在启动阶段误报,加步数门控后消除。

注意事项:

  • log-based metric 有入库延迟,基于它的缺失告警在“持续时间加数分钟”后才触发(本次比 300 s 晚约 5.9 min);分钟级 hang 检测用带内 15 s duty_cycle 加阶段或进度门控,log-based 告警作为零侵入的兜底 实测。
  • 缺失告警在作业正常结束后也会触发(11 min 24 s 后),必须按作业状态门控(例如 Job 是否仍为 active)实测。
  • DELTA 类 log-based metric 在 PromQL 中以一个 0 值点开始,门控用 sum_over_time(...) > 0,不要用 count_over_time 实测。
  • max_over_time(x[5m]) == 0 在窗口内只有一个样本时也成立,需加覆盖门限(count_over_time >= N)实测。
  • 告警策略设置 documentation.content 时必须同时给 documentation.mimeType;v3 projects.alerts 列表 API 用 filter=policy.name="projects/.../alertPolicies/ID" 过滤,不支持 policy.displayName 实测。
  • 按 15 倍平均步时设停滞门限(本作业为 7.8 s)只有进程内或日志流检测器能做到,经 Cloud Monitoring 的路径会增加 0.5 到 11 min 实测。
  • 启动看门狗按本作业类型的实测基线加余量设置(规则见 3.4.3 B2)。本作业的基线:容器启动后 4 s 输出 device 列表(JAX 初始化 1.4 到 1.9 s;附录 A.1.3 中单机 2.8 s、两机 3.9 s),进程启动到首步 381 s(含有意设置的 360 s 空闲;首步编译加运行 2.2 到 2.3 s)。以 device 列表行和首步为条件的看门狗只要门限高于基线就不会在启动阶段误报,而简单 duty cycle 规则在 5 min 时误报 实测。
↩ 返回需求R-09 R-12正文3.4

A.12 DCN 与主机网络#

A.12.1

A.12.1 DCN all-reduce 限时试验(仅实验室方法,非 DCN 基准)#

服务需求R-02实测耗时Job Ready 约 12 s实测

服务需求:R-02(见第 1 章);正文:2.2。

目的:验证集群只有一个 slice 时,能否让 megascale 把每个 host 当作独立 slice,使跨 host 的 all-reduce 走 DCN 路径,以及测得的数值代表什么。限时 20 min。

前置:A.0.5 多机 Indexed Job(额外开放端口 8080)。

命令:每个 Pod 覆盖单机变量(并删除 GKE 注入的 TPU_PROCESS_ADDRESSES)并设置 megascale 变量,dcn_probe.py 调用 jax.distributed.initialize,建立 (dcn=2, ici=8) mesh,对 dcn 轴做 shard_map psum(每 device 64 MiB 和 256 MiB bf16,各 20 次)。

bash
export TPU_HOST_BOUNDS=1,1,1 TPU_WORKER_ID=0 TPU_WORKER_HOSTNAMES=localhost; unset TPU_PROCESS_ADDRESSES
export MEGASCALE_COORDINATOR_ADDRESS=<JOB>-0.<SVC>:8080 MEGASCALE_NUM_SLICES=2 MEGASCALE_SLICE_ID=$JOB_COMPLETION_INDEX MEGASCALE_PORT=8080
python3 dcn_probe.py      # jax.distributed.initialize(coordinator_address="<JOB>-0.<SVC>:8476", num_processes=2, process_id=$JOB_COMPLETION_INDEX)

裁剪输出:

输出
DCN_INFO {"process_index": 0, "n_devices": 16, "slice_indices": [0, 1], "init_s": 29.07}
DCN_RESULT {"mib_per_device": 64, "ok": true, "median_ms": 83.02, "per_device_GBps": 0.81, "per_host_aggregate_GBps": 6.47}
DCN_RESULT {"mib_per_device": 256, "ok": true, "median_ms": 321.51, "per_device_GBps": 0.83, "per_host_aggregate_GBps": 6.68}
每 device 数据量中位耗时(两个 Pod)GB/s per deviceGB/s per host(8 个 device 合计,单方向)
64 MiB83.02、84.41 ms0.81、0.806.47、6.36
256 MiB321.51、317.58 ms0.83、0.856.68、6.76

实测耗时:Job Ready 约 12 s;megascale 加 distributed 初始化 29 s;整个探测 46 s;限时实际用了约 1.5 min。

判定标准:两个 slice 可见(slice_indices 为 0 和 1),psum 结果正确。

注意事项:

  • 这是实验室方法:一个 2x2x2 slice 拆成两个 2x2x1 的“slice”,经 Pod 网络(非 hostNetwork)由 megascale 连接,只有 2 个参与方,没有多网卡调优。约 6.4 到 6.8 GB/s per host 不是 DCN 带宽,不能作为 DCN 基准引用 实测。
  • 机型文档列 tpu7x-standard-4t 物理网卡 2 块、单 VM 最高 400 Gbps(TPU 机型)文档;验证集群节点 guest 内只见 eth0(gVNIC,MTU 8896,链路速率 200 Gbps,读自 /sys/class/net/eth0/speed)实测。
  • 真实 DCN 测试需要至少 2 个 slice;本试验数值不作为 DCN 基线。
↩ 返回需求R-02正文2.2
A.12.2

A.12.2 两个 TPU 节点间的主机网卡带宽(iperf3)#

服务需求R-02实测耗时Pod Running 3 s,安装 iperf3 约 10 s,四个测试 110 s…实测含估算

服务需求:R-02(见第 1 章);正文:2.2。

目的:测量同一 slice 两个 tpu7x-standard-4t 节点之间主机网卡的 TCP 带宽,替代无来源的主机网络带宽数字。这是经 VPC 的主机 TCP,不是 ICI,也不是多 slice 的 DCN。

前置:A.0.2;TPU 空闲。两个 Pod 不申请 google.com/tpu,只容忍 TPU taint,hostNetwork: true。机型文档列 tpu7x-standard-4t 物理网卡 2 块、单 VM 最高 400 Gbps(TPU 机型)文档;验证集群节点 guest 内只见 eth0(gVNIC,MTU 8896)实测。

命令:

yaml
apiVersion: v1
kind: Pod
metadata: {name: iperf-server, labels: {app: iperf}}
spec:
  hostNetwork: true
  restartPolicy: Never
  activeDeadlineSeconds: 1200
  nodeSelector: {kubernetes.io/hostname: <node-a>}
  tolerations: [{key: google.com/tpu, operator: Exists, effect: NoSchedule}]
  containers:
  - name: iperf
    image: debian:trixie-slim                 # iperf3 3.18,多线程;bookworm 的 3.12 为单线程
    command: ["bash", "-c", "apt-get -qq update >/dev/null && apt-get -qq install -y iperf3 >/dev/null && iperf3 -s -p 15201"]
# 客户端 Pod 相同,固定到 <node-b>,依次运行下面的四个测试
bash
kubectl -n tpu-verify apply -f manifest_iperf.yaml
# 客户端内:S 为服务端节点的内网 IP
for args in "-P 16 -t 30" "-P 16 -t 30 -R" "-P 32 -t 30" "-P 1 -t 20"; do iperf3 -c $S -p 15201 $args -i 0 -J; done
kubectl -n tpu-verify logs iperf-client > client.log
kubectl -n tpu-verify delete pods -l app=iperf

裁剪输出:

输出
iperf 3.18 (cJSON 1.7.15)      mtu=8896   tcp_mss_default=8844
-P 16 -t 30      node-b -> node-a   190.74 Gbit/s  (23.8 GB/s)  retr 19954  cpu snd 192 % / rcv 527 %
-P 16 -t 30 -R   node-a -> node-b   190.75 Gbit/s  (23.8 GB/s)  retr 17442
-P 32 -t 30      node-b -> node-a   190.76 Gbit/s  (23.8 GB/s)  retr 18540
-P 1  -t 20      node-b -> node-a    49.69 Gbit/s  ( 6.2 GB/s)  retr  1030

实测耗时:Pod Running 3 s,安装 iperf3 约 10 s,四个测试 110 s,含一次服务端重建共 221 s。

判定标准:两个方向、16 到 32 个流的结果一致(190.7 Gbit/s,每方向)即为这对节点的主机网卡上限;单流约 50 Gbit/s。

注意事项:

  • 每方向 190.7 Gbit/s(23.8 GB/s)是经 VPC 的主机 TCP 带宽,不是 ICI 带宽,也不是多 slice DCN 带宽 实测。
  • 需要多线程的 iperf3(3.16 起各流由不同线程处理,发行说明)文档;本实验单流时接收端占满一个 CPU 核(49.7 Gbit/s),单线程版本预计达不到 190 Gbit/s 估算。
  • 16 个以上并行流在线速下出现数千到数万次重传属正常,不代表网卡错误 实测。
  • debian:trixie-slim 没有 iproute2(ip),不要把服务端启动命令接在 ip ... 之后用 && 连接(本实验因此重建过一次服务端)实测。
  • 只在 slice 空闲时测试:它与运行中作业的 jax.distributed 和 DCN 流量共用 eth0 实测。
  • 复核实验按本节服务端 YAML 与客户端循环原样重跑:-P 16、-R、-P 32 分别为 190.75、190.72、190.79 Gbit/s,-P 1 为 50.59 Gbit/s(发送端,与上表同口径),客户端 Pod 从启动到 Completed 119 s;另一次运行与同节点的 TPU 测试重叠,首个 -P 16 只有 161.9 Gbit/s,因此前置条件要求 TPU 空闲 实测。
↩ 返回需求R-02正文2.2

B 与上一版相比的主要更正#

本版逐条核对了上一版(2026-11-02)的 752 条断言:已核实 271、更正 357、删除 56、无法核实 43、待实测 25(待实测项已由附录 A 覆盖或列入附录 D)。上一版 120 个唯一链接中,34 个支撑所附说法、44 个部分支撑、42 个不支撑;其中 30 个目标已不存在(404、本地路径缺失或锚点失效),在线文档读者实际打不开 31 个(含全部 23 个本地文件链接)。旧版第 2 章有 22 条“客户诉求”无一手来源或引错来源:删除 9 条(8 条无客户来源,1 条属调度),改源或收窄 13 条。下表只列影响结论的更正。“依据”列给公开链接、附录 A 的实测或附录 C 的来源;没有公开出处、经逐条核对确认的写“核实记录”。

B.1 验收与压测#

旧版位置旧版说法更正后依据
全文工具称为“TPUMS 1.1.1”1.1.1 是 CHS 自带镜像的标签,内容为 legacy TPUMS 快照;当前 TPUMS 是 GitHub main 上的 v2.0,提供 tpums CLITPUMS 仓库、实测(附录 A.3.3)
1.1、3.1.2镜像路径 /workspace/...,入口 /usr/local/bin/tpums,jax 0.9.2;镜像名 health-scan/tpu- benchmarks:v1.1.0-0.3.2;--in_dtype fp8_e4m3fn --warmup_runs镜像为 us-docker.pkg.dev/gce-ai-infra/chs/accelerator-microbenchmarks:1.1.1,路径 /app/accelerator-microbenchmarks,入口 python3 Ironwood/src/run_benchmark.py --config,无 tpums;jax 0.11.1、libtpu 0.0.48。旧版 3.1.2 的 tpums 命令需按附录 A.0.7 安装 TPUMS v2 后运行:fp8 取值为 float8_e4m3fn(原命令因此 rc=2),warmup 参数为 --warmup_tries(--warmup_runs 被静默忽略)实测(附录 A.3.3、A.0.7、A.2.1)
3.1.1、3.1.3chs run --tpu-Generation=7x --slice-Wait-timeout=15m、--nodes=<node>、测试 tpu-Inventory这些 flag 不存在。TPU 用 chs run --suite=<lite 或 standard> --nodepools=<pool> -y(--nodes 不支持 TPU),测试名为 tpu-info实测(附录 A.3.2)
1.3降额为 int(x*0.95);2x2x2 psum 门限 205→195,--tests 时 200→190boh_generator.py 对 min 型门限做 round(x*0.95);2x2x2 psum 在所有路径上都是 190(yaml 200)实测(附录 A.3.1)、核实记录
1.2、3.1.1、Q1.3psum 门限 2x2x2 ≥195、4x4x4 ≥216 GB/s;all_gather ≥204、all_to_all ≥27CHS 0.3.2 降额后:2x2x2 psum 190、all_gather 162、all_to_all 71;4x4x4 psum 352、all_gather 475、all_to_all 79(yaml ×0.95)。216 不是 CHS 门限实测(附录 A.3.1)、核实记录
1.1、1.2collectives 跑 psum、all_gather、all_to_all;DEGRADED 时自动触发 Tier-2 network-stress0.3.2 的 CLI 只跑 psum;分层触发未生效,standard 套件在同一轮无条件执行 tpu-network-stress实测(附录 A.3.1)
1.1、1.5.1、Q1.2、Q1.10、3.1.1、3.1.3(及客户问答表 H3)CHS 自动给节点打 chs/healthcheck 等标签,返修后自动 uncordon、去污点CHS 0.3.2 不打标签、不 cordon、不改污点,只输出 bill_of_health;隔离与回池由客户自动化完成实测(附录 A.3.1)、核实记录
1.5CHS psum 为“端到端墙钟中位数 @16384 MiB FP32”,与 TPUMS 差 2.3%,“完全吻合”;TPUMS HBM 6444.5 GB/s/chipCHS psum 为 profiler trace 计时、单步 64 MiB,那次 TPUMS 墙钟值仅 8.05 GB/s/chip,2.3% 属巧合;按 CHS 配置对齐(fp32,16/32/64 MiB,4x2x2)后 TPUMS 64 MiB 为 210.8 GB/s/chip,与 CHS 一致;6444.5 是 CHS 单 device 值乘 2;实测 TPUMS hbm copy 3210–3242 GB/s/device实测(附录 A.2.1、A.3.1)
Q1.3、3.1.1把一份共享基线文件中的 BF16、FP8、HBM 数值写成验收门限,并称“实测固化”旧版所列数值与该文件不一致;文件中的 pass/warn 是推断值,覆盖的软件版本有限,不是验收门限;6108 GB/s/chip 是 CHS tpu-hbm-stress 门限,负载不同。基线数据见客户仓库 Google 侧共享的基线文件附录 C.2
3.1.1验收表把验证集群实测值与外部基线混在一列;BF16 985.39–996.46 TFLOP/s/core;4x4x4 psum 256 GB/s拆为“验证集群 2x2x2 实测”“共享基线文件”“未实测”;CHS tpu-gemm 实测 1042.1–1066.9 TFLOP/s/device(2026-11-03 standard,附录 A.3.1);4x4x4 未测,删除 256实测(附录 A.3.1)
3.1.1、Q1.3双网卡聚合 45.2 GB/s(≥42);dcn_all_reduce 7.6–8.5 GB/s/chip(≥6.5);MaxText 600–669 TFLOPS/device、门限 ≥480均无公开来源、未实测,删除(见附录 D)。两节点间主机网卡 iperf3 实测每方向 190.7 Gbit/s(23.8 GB/s),这是经 VPC 的主机 TCP,不是 DCN 集合通信带宽实测(附录 A.12.2)、核实记录
1.2、1.4、Q1.6、3.1.1gemm_throttling 设 duration_seconds: 240,每 5 s 采 XProf;门限 <85 °C、液冷 ≤72 °C、slowdown ≤1.03时长参数是 min_duration_s(示例 120);遥测取自浸泡前后两个 trace 窗口;TPUMS 无内置门限,三个阈值删除。实测 240 s 浸泡总耗时 279 s,hbm_peak_temp_c 44 °C(浸泡前窗口 45 °C),降频 0%gemm_throttling.yaml、实测(附录 A.2.1)
Q1.5、3.1.1、3.1.2脉冲脚本“本方案实机验证”,64 位校验和“0 SDC”,峰值 1910.6–1926.4旧版 3.1.2 脚本从未跑通:jax 0.9.0 上 @jax.pmap 缺 axis_name 报 NameError,JAX 0.10.0 起 jax.device_put_replicated 已移除;jnp.uint64 未开 jax_enable_x64 被截为 uint32。唯一一次实机运行用的是另一段内联脚本,参考校验和全为 0x0,“0 SDC”不成立。修订脚本校验和非零,故障注入可检出实测(附录 A.2.2)
Q1.5、2.5 H5#145 空闲窗口 50/200/500 ms;脉冲压测作为对客户的 SDC 工具#145 提议 50/200/1000 ms,是 open 状态的功能请求,上游无实现;不作为正式工具对外提供上游 TPUMS #145
3.1.3、Q1.10返修 SOP:单节点 7.5 h MaxText Llama-3.1-70B + XSC,throttle_pct == 0%SOP 是方案设计,未实测;70B 训练状态(fp32 参数、Adam 状态与 bf16 梯度,未计激活)约 0.98 TB,超过单台 768 GiB HBM,单节点改用 8B 级模型或整 slice;throttle_pct 不是 TPUMS 字段TPU7x、TPUMS 仓库
3.2.2、Q1.9预检用 jax.device_put_replicated;initContainer 中 fuser -k -9 清理 /dev/vfio;校验 PCIe 32 GT/s x16前者在 JAX ≥0.10 必然失败;initContainer 看不到其他 Pod 进程,清理无效,残留占用要在节点级排查;guest 内 TPU 链路速率显示 Unknown,改看 pcie_*_error_count实测(附录 A.1.2、A.1.4、A.9.1)
3.2.2、Q2.7awk 判定 ethtool -g/-k 的 TCP data split;双 200G 网卡 eth0/eth1awk 未去掉制表符,判定永不触发;该项是 ring 参数,只在 ethtool -g,起因是 GKE network optimizer,1.35.13-gke.0+、1.36.4-gke.0+ 已修复。机型文档列 tpu7x-standard-4t 物理网卡 2 块、单 VM 最高 400 Gbps 文档;验证集群节点 guest 内只见 eth0(gVNIC,MTU 8896,ethtool 速率 200 Gbps)实测TPU 机型、ethtool netlink、实测(附录 A.1.2)、核实记录
3.2.2、Q1.98471 是“ICI 会话协调端口”,initContainer 内对端“100% 可达”;只设 TPU_SKIP_MDS_QUERY=true 即可单机初始化;预检 15–25 s8471 是 libtpu worker 间 DCN/TCP 协调端口,initContainer 阶段未监听属正常;单机隔离需 TPU_HOST_BOUNDS=1,1,1;headless Service 设 publishNotReadyAddresses: true 时预检本身 9–10 s,未设置时因等待 DNS 为 33–37 s在 GKE 中部署 TPU 工作负载、实测(附录 A.9.1、A.1.3)
1.1、3.1CHS lite 约 5 min、standard 约 30 min(工具自报)2x2x2 实测 lite 9 min 31 s(5 项)、standard 17 min 58 s(8 项),全部 SUCCESS;compute-stress 920.8–921.5 TFLOP/s/device、hbm-stress 6364 GB/s/chip、network-stress 各轴 170.8–171.3(CHS 标注 GB/s,按 GiB/s 计算)实测(附录 A.3.1)

B.2 SDC 检测#

旧版位置旧版说法更正后依据
3.2.1、Q3.310 个 ici-sdc-test flag(含 xla_tpu_ici_sdc_test_packet_size=4KB、xla_tpu_ici_sdc_test_run_count)9 个不存在。公开 ICI straggler playbook 用到的 xla_tpu_ici_sdc_test_* 共 7 个:run_on_program_start、iterations、max_distance、packet_size_chunks、buffer_size_chunks、pipeline_depth、sflag_wait_timeout_ms;其余同前缀 flag 用于测试或调试,不推荐使用。libtpu 遇未知 flag 启动即退出,原配置会让所有作业失败ICI straggler triage、实测(附录 A.4.1、A.2.2)
3.2.1、Q3.3ici-sdc-test 只在 SliceBuilder 初始化时跑一次(3–5 s),不影响步耗时,可常驻run_on_program_start 把测试注入每个多核程序,即每步执行。8 MiB psum(基线 0.56 ms/步)实测:只开该 flag(默认参数)无可测开销(中位数 0.576 对 0.56 ms,在波动范围内),11 个诊断 flag 组合 iterations=10 时 +1.4 ms、5000 时 +228 ms;只在诊断运行中短时开启,或约每 100 step 开一次ICI straggler triage、实测(附录 A.4.2)
Q3.2、Q3.3开启 ici-sdc-test 或任意 ICI 超时时 tpu_driver.INFO 都有 sflag 记录;错误串“ICI SDC Test Failure”;S0 = Core 0 SENDici-sdc-test 在 tpu_driver.INFO 中输出 IciSdcTest :: ICI BW 行(每 TensorCore 每步一行);带迭代号和 SEND/RECV 的 ICI transfer wait 记录只在 ici-sdc-test 设 sflag_wait_timeout_ms>0 并开 xla_tpu_enable_log_recorder 时产生,普通 hang 只有不带迭代号的 Wait timeout on sflag;“ICI SDC Test Failure” 不存在,按公开 playbook 检索 ICI transfer wait、Wait timeout on sflag 与 XLA_SDC_CHECKER;S0 是直连故障链路、卡在 SEND 的 coreICI straggler triage、实测(附录 A.4.2)
Q1.4XSC 开销 1.8–2.5 倍;新负载前 24 h 每步开 XSC;Google 建议新硬件筛查 96 h1.8–2.5 倍对应只校验输出、重跑 1 次的配置,XSC 定位为诊断工具;“24 h”“96 h”无可访问来源,删除;验证集群实测 2.08 倍,上一版的 5 个 XSC flag 组合 2.32–2.34 倍实测(附录 A.4.3)、Data non-determinism triage
Q1.4、第 4 章VPU 重放单元在空闲周期重算向量指令,出错自动后台修复;论文标题 “Ironwood: The Seventh-Generation TPU”论文写的是在空闲 VLIW 槽随机抽样向量 bundle 重放,检出后经 OCS 移出生产再修复;标题为 “Google's Training Supercomputers from TPU v2 to Ironwood: Architectural Stability, Scale, Resilience, Power Efficiency, and Sustainability Across Five Generations”arXiv 2606.15870
Q1.7、3.2.1、2.5 H6SparseCore embedding 确定性参数作为常驻 flag只有 SparseCore embedding 负载需要;libtpu 0.0.34、0.0.50.1 报未知 flag 并启动即退出,0.0.51 起被接受;有性能开销,无公开文档实测(附录 A.4.1)、核实记录
Q1.7同机重跑逐位一致等写成确定结论;引 JAX “Numerical accuracy” 页这些是工程预期,无文档保证;该页讲数学函数精度,与确定性无关,删除;实测同一 jax、libtpu 版本下同节点与跨节点逐位一致,跨 libtpu 版本不保证实测(附录 A.4.4)

B.3 监控#

旧版位置旧版说法更正后依据
Q1.1、Q3.2、3.3.1tpu/infra_health 为 HEALTHY、ici_link_health == 0、hbm_uncorrectable_count == 0、increase(ici_link_flaps[10m]) >= 3用完整类型名;HEALTHY 是 health_status 标签值;ici_link_health 在 accelerator/network/ 下,取值 0–10,10 为致命;错误计数为 CUMULATIVE,用 increase();ici_link_flaps 是 GAUGE,用 delta(...[10m]) > 0(完整写法见表后);阈值 3 无来源,删除。Cloud Monitoring PromQL 中的短名(如 ici_link_flaps)返回空结果且不报错,看起来像“没有 flap”,必须写完整指标名Monitor TPU、实测(附录 A.6.1)
Q2.1、3.3.1“19 项公开 Beta 指标”,出自 Topic 1 H14Beta 表共 41 项;19 项是 Google 侧初步答复(E14)挑出的硬件与网络指标子集,不是文档分类;旧版清单还混入 3 个健康指标、漏了 2 个 NIC 丢包计数;H14 只说明两类来源Monitor TPU、附录 C.1(Topic 1 E14、H14)
Q2.3、3.4.2所有带外指标 60 s 采样、延迟 420–540 s;“60 秒法则”三步排查文档只对 infra_health、failure_prediction_* 给出 60 s 与 420/540 s。实测可见延迟:infra_health 350–382 s,chip_state 256–296 s,GKE 节点 tensorcore_utilization 48–78 s;首轮排查按分钟计Monitor TPU、实测(附录 A.6.1)
Q3.8、3.3.1failure_prediction_status 标签 prediction_status;0–1 概率、内部阈值 0.7、ECC 斜率等特征标签为 Value,取值 NO_DEGRADATION_PREDICTED、DEGRADATION_PREDICTED、POSSIBLE_DEGRADATION_PREDICTED,文档定义为预测未来 5 小时内是否进入降级状态;阈值与特征无来源,删除。验证项目 42 天内无该序列Monitor TPU、实测(附录 A.6.1)
Q1.6、3.3.1宿主机 BAR4 时钟指标 tpu_bar4_core_clock_mhz(:9105),基线 1500 MHz,<1450 MHz 判降频没有公开的时钟频率指标,exporter 与阈值删除;降频看 core_throttling_indicator(带 reason)Monitor TPU
Q2.2、Q2.5、3.3.215 s YAML 含 otlp :4317、batch、transform/fix_nan(IsNaN);TPU_METRIC_EXPORT_INTERVAL_MS、MEGASCALE_OTEL_EXPORT_INTERVAL_MS;指标 grain_data_stall_seconds交付 YAML 中没有这些配置,OTTL 无 IsNaN;两个环境变量与该指标名都不存在。实际是 collector 每 15 s 拉取 libtpu :8431;实测 collector 0.1.4 在 :2113 输出 13 个指标名,GMP 中样本间隔 15.0 s,命名空间部署还需 ClusterRole(nodes 只读);框架指标真实名称如 grain_python_dataset_next_duration_ns附录 C.2(Google 侧提供的 15 s 采集器配置)、实测(附录 A.5.1)、核实记录
Q2.1方案 100% 覆盖客户关注的 16 项 DCGM 指标这 16 项(时钟、PCIe 吞吐与宽度、SBE ECC、行重映射)在 TPU 上没有对应指标,如实说明缺口附录 C.1(指标补充)、Monitor TPU
Q3.1、3.4.2慢节点公式“已生产验证”;megascale_collective_end_to_end_latencies;降频慢节点 tensorcore_utilization 最高规则文件中标为推断;时延类指标只覆盖 multislice(单 slice 上无数据),所写指标名不存在。单 slice 实测:步耗时在各 worker 上相同;主机侧慢节点 duty_cycle 最低,计算型慢节点 TensorCore 利用率最高,两类慢节点 hlo_execution_timing 均最低;“降频慢节点 TCU 最高”未复现,仍为假设。ML Diagnostics 对两类慢节点均未报事件,不能替代慢节点检测实测(附录 A.11.1、A.8.1)、ML Diagnostics、附录 C.2(Google 侧共享的告警来源清单)

ici_link_flaps 告警的完整写法(验证项目中按 10 min 窗口能命中真实 flap 实例):

PromQL
delta(compute_googleapis_com:instance_tpu_accelerator_network_ici_link_flaps{monitored_resource="gce_instance"}[10m]) > 0

B.4 日志#

旧版位置旧版说法更正后依据
Q2.4、3.2.1、2.5 H4生产容器设 TPU_STDERR_LOG_LEVEL=0公开文档只给出默认值 3;建议生产用 2(ERROR 及以上进 stderr,经验值,公开文档未确认);0 会把全部 INFO 复制到 stderr,只在诊断时用。实测健康初始化:不设与设 2 时 stderr 无 libtpu 行,设 0 时 181 行(INFO 文件均 186 行),初始化耗时无差别TPU 故障排查、实测(附录 A.7.2)
Q2.4、第 4 章公开排障文档说明 sidecar-log-collector;webhook 挂载 /tmp/tpu_logs公开文档只有 tpu-device-plugin 日志查询。实测 libtpu 日志由 sidecar-log-collector 送入 Cloud Logging,severity 恒为 INFO,接收延迟 p50 约 3 s,同容器后续进程的日志未采集;TPU_LOG_DIR 由 webhook 注入,挂载来自 device plugin,底层是主机 /tmp/tpu_logs(COS /tmp tmpfs),Pod 删除后保留,下次分配 TPU 时清空GKE TPU 故障排除、实测(附录 A.0.12、A.7.1、A.7.2、A.7.3、A.4.2)
Q1.8、Q3.4、第 4 章FINGERPRINT_MISMATCH 由各 Worker 镜像或启动参数不一致引起,锁定 GKE ≥1.34.1-gke.1829001 可预防;健康原因 4 种文档写的是本应运行同一 TPU 模块的程序二进制指纹不同(多为编译问题),由 hang 检测记入 TPU 健康日志,机器保持 HEALTHY;该 GKE 版本只修复 tpu7x 芯片数上报,与此无关;原因共 5 种(含 UNKNOWN_CAUSE)TPU health、Megascale hang、GKE 已知问题
Q3.4MegascaleHangDetected 由 NPD 设置;SLICE_FAILURE_CHIP_DRIVER_ERROR 是无害的受害者错误该 condition 由谁写入没有公开说明,旧版“由 NPD 设置”无来源,删除;CHIP_DRIVER_ERROR 说明 slice 内确有芯片驱动或 ICI 故障,通常是对更早故障的报告;旧版所引 “Ensure all processes are healthy” 等原文查无出处Slice failure

B.5 故障处置#

旧版位置旧版说法更正后依据
Q3.6、3.4.3cloud.google.com/fault-behavior=replace;GKE ≥1.32.2-gke.1297000合法值为 PERFORMANCE、SDC、XID、unspecified;文档要求 1.32.3-gke.1057001+ 且只列 GPU 机型,TPU v7x 是否适用需与 Google 确认Manage AI-optimized GKE clusters
Q3.6、3.4.3同一 GKE 节点再调 report-host-as-faulty 作为换机第二通道不要对 GKE 托管的 TPU 节点直接调用 GCE 实例 API;TPU 的 report-host 只用于 All Capacity 模式,VM 在原主机停机修复 3–14 天或更久All Capacity 报修、Manage AI-optimized GKE clusters、Node isolation
3.4.3、Q3.7cordon 后即可 --force 删除 Terminating Pod;脚本在强删、打标、报修和删 Slice 四步忽略返回码,并重建同名 Slice节点 NotReady 或 VM 已重置后才强删;原脚本会掩盖失败、重复报修,已替换为分步处置流程(见 3.5.1)强制删除 Pod
Q3.8、2.4Topic 1 H19 批注给出生产统计排序 Host > ICI/OCS > HBM ECC > Thermal > SDC,并有 5 h 预测原文:多数情况依次为 host 到 TPU tray 的链路或 tray 本身、ICI/OCS、DCN、host,供电问题少见但影响范围大;没有给出 MTBF(需先确认安全政策),也没提 5 h 预测,不是生产统计(5 h 窗口出自 failure_prediction_status 的文档定义,见 B.3)附录 C.1(Topic 1 H19)、Monitor TPU

B.6 链接与引用#

旧版位置旧版说法更正后依据
Q3.6、第 4 章kubernetes-engine/docs/how-to/report-faulty-host、compute/docs/nodes/report-faulty-host两个链接都返回 404;改为 GKE report-faulty-hosts-how-to 锚点、gcloud report-host-as-faulty 参考页和 TPU All Capacity 报修页附录 C.3(C3-16 至 C3-18)
1.1、第 4、5 章CHS 门限出自一个内部配置文件和一份 CHS 设计文档的“门限定义”两处都不是公开资料,也不含门限,已删除;门限在 chs:0.3.2 镜像的 tests/<test>/thresholds.yaml实测(附录 A.3.1)、核实记录
2.1–2.4引用 4 个表中不存在的提问人或批注人和 D5 评论线程;以 H16 为 ICI 与报修依据;称 D1 批注建议开源 TPUMS旧版所列 4 个提问人或批注人和 D5 评论线程在表中都不存在;H16 讲 DRA;F20 是客户追问;报修答复在 D4 线程;D1 唯一的批注是 Google 侧转述客户主要想要 CHS 或 DCGM 类工具,未提开源 TPUMS附录 C.1(D1、D4、F20)
2.1–3.4infra#20、#18、#31、#15、#29、#27、#30 作为门限、采集 YAML、慢节点、伴生报错、Terminating 的出处这些 issue 都不含所引内容;改引正确 issue 或公开文档附录 C.2
1.2、2.1–3.4、第 5 章脚本 a1_env_check.py、b2_hbm_bw.py、c2_dcn_collectives.py、00-node-precheck.sh、11-diagnose-node.sh 及其数值仓库中从未存在,相关数值删除核实记录
全文23 个本地文件链接;tpu-info CLI 文档作为指标出处;JAX accuracy 页作为确定性出处本地链接删除,改为附录摘录或公开 URL;指标改引 monitor-tpu#beta;accuracy 页删除Monitor TPU、核实记录
第 2 章25 个归纳问题都标了“客户诉求”出处,如 Q2.2 15 s 采集与 NaN 修复、Q2.5 Data Input Stall、Q2.7 TCP data split其中 22 条无一手来源或引错来源:9 条删除(8 条无客户来源,1 条属调度),13 条改源或收窄;第 1 章已按此重写附录 C.1、C.2

C 来源索引#

只列公开或已向客户共享的来源;C.3 列主要公开文档,正文其他链接以出现处为准。链接于 2026-11-03 核对可访问(客户问答表与客户私有 GitHub 仓库需访问权限)。

C.1、C.2 的“需求”列为第 1 章归并需求编号(R-xx),“原子需求”列为第 1 章与第 4 章引用的原子需求编号(RQ-xx),RQ-01 至 RQ-46 均可在两表中找到来源;Google 答复与 Google 侧共享资料不是客户诉求,原子需求记为“—”;Google 成员在评论中转述或记录的客户诉求(质量检测+压测+运维适配 D1、Topic 1 E18、H17)保留 RQ 编号,主题列注明“Google 评论”或“Google 待办”。

C.1 客户问答表单元格#

tab 名为简称,取原 tab 名的前缀或中文译名;单元格引用供有权限的读者对照,公开版不附链接。

需求原子需求tab / 单元格主题链接
R-01RQ-01质量检测+压测+运维适配 B3类似 DCGM EUD 的芯片级诊断工具与时长客户问答表
R-11RQ-30、RQ-31质量检测+压测+运维适配 B4硬件错误上报位置与错误码分级客户问答表
R-04RQ-07质量检测+压测+运维适配 B5SDC 检测机制与工具客户问答表
R-04RQ-08质量检测+压测+运维适配 B6逐位一致性的四种情形客户问答表
R-01、R-02RQ-02质量检测+压测+运维适配 B7ICI 带宽测试与硬件诊断工具客户问答表
R-05RQ-14质量检测+压测+运维适配 B8libtpu、固件、运行时版本一致性客户问答表
R-01RQ-09质量检测+压测+运维适配 D1Google 评论:客户需要 CHS 或 DCGM 类工具客户问答表
R-02、R-08、R-12、R-14RQ-05、RQ-16、RQ-35、RQ-42QnA B2网络架构、集合通信基线、可观测性与故障定位(4 问)客户问答表
R-01RQ-10QnA B5压测、检测、监控、诊断能力总括客户问答表
R-09RQ-23QnA B6服务器带外能力是否开放客户问答表
R-08、R-12RQ-29、RQ-36QnA B10RDMA 类监控与快慢节点检测客户问答表
R-06RQ-15Topic 1 B14KSM、cAdvisor、tpu-exporter 对标客户问答表
R-09RQ-33Topic 1 B17TPU 现有异常检测机制客户问答表
R-11RQ-31Topic 1 B18错误码清单客户问答表
R-12RQ-34Topic 1 B19常见故障类型与 MTBF客户问答表
R-11RQ-32Topic 1 B26kubelet 日志参数(containerLogMaxSize)客户问答表
R-06、R-09RQ-17、RQ-27Topic 1 B27带内采集指令与硬件告警逻辑客户问答表
R-11RQ-38Topic 1 E18Google 待办:故障指标与定位专题(评论)客户问答表
R-05RQ-13Topic 1 F20Pod 内 libtpu 通信条件判断客户问答表
R-06、R-12RQ-24、RQ-37Topic 1 H17Google 待办:指标接入与 straggler 检测(评论)客户问答表
R-02RQ-05Topic4 B3集合通信基线与验收方法客户问答表
R-08RQ-16Topic4 B4租户侧 ICI/DCN 网络指标采集客户问答表
R-12、R-14RQ-35、RQ-42Topic4 B5故障诊断案例与降级运行客户问答表
R-05RQ-11调度+容错+指标采集 B14对标 GPU 预检的 TPU 预检命令客户问答表
R-07RQ-18调度+容错+指标采集 B15TPU 补充指标进展(16 项清单见指标补充 tab)客户问答表
R-13RQ-40调度+容错+指标采集 B19通过 GKE 接口标记异常节点(续见 B20)客户问答表
R-07RQ-18指标补充 A2:G5DCGM 时钟类指标(4 项;另一 tab 有相同清单)客户问答表
R-07RQ-19指标补充 A6:G11DCGM PCIe 吞吐、宽度与代数(另见 A16:G17)客户问答表
R-07RQ-20指标补充 A12:G13DCGM 单比特 ECC 计数客户问答表
R-07RQ-21指标补充 A14:G15DCGM 行重映射客户问答表
R-02、R-06RQ-06、RQ-22客户问答表(另一 tab)见第 1 章对应原子需求客户问答表
R-09、R-15RQ-28、RQ-44GCP问题反馈 C3客户现有告警分级与回归准入流程客户问答表
R-11、R-13—质量检测+压测+运维适配 D4Google 答复:fatal 与 non-fatal 错误的报修路径(评论)客户问答表
R-06—Topic 1 H14Google 答复:tpu-exporter 对应 Cloud Monitoring 与 device plugin 端点(评论)客户问答表
R-06—Topic 1 E14Google 初步答复:挑出的 19 项硬件与网络指标客户问答表
R-12—Topic 1 H19Google 答复:常见故障类型排序(评论)客户问答表
R-10、R-14—QnA D3Google 答复:partition 与 Slice 故障状态、恢复通常 2 min 内、无 SLO(评论)客户问答表
R-11—Topic 1 H18Google 答复:TPU 无 XID 对应物(评论)客户问答表
R-05—质量检测+压测+运维适配 D8Google 答复:libtpu 与 vfio-pci 解耦、版本钉定(评论)客户问答表

C.2 GitHub issue、评论与客户共享文档#

以下链接指向客户私有 GitHub 仓库(需访问权限)。其中 Google 侧编写、共享给客户的资料(基线文件、ICI 分轴带宽脚本、15 s 采集器配置、告警来源清单)不代表客户诉求。

需求原子需求来源主题链接
R-01、R-03RQ-03、RQ-04infra#4EUD 式验收套件与同步脉冲压测诉求客户仓库 infra#4
R-05RQ-11infra#20对标 GPU 预检的 TPU 检测脚本诉求客户仓库 infra#20
R-05RQ-13infra#24 评论Pod 内 libtpu 通信条件如何判断(客户追问)客户仓库 infra#24 评论
R-05—infra#24 评论Google 书面回复:Pod 网络模型与 8471、8431 端口客户仓库 infra#24 评论
R-07RQ-18infra#21补齐对标 DCGM 的 TPU 指标(清单在客户问答表·指标补充 tab)客户仓库 infra#21
R-09、R-15RQ-28、RQ-44infra#8 评论客户告警分级与回归准入流程客户仓库 infra#8 评论
R-10、R-14RQ-25、RQ-45、RQ-46infra#8 评论故障信息获取、hang 处置与自动踢除客户仓库 infra#8 评论
R-10RQ-25infra#27故障信息推拉方式与 node 状态客户仓库 infra#27
R-10RQ-39infra#28partition 异常定位到 node客户仓库 infra#28
R-10RQ-26infra#344 个故障信号接口诉求客户仓库 infra#34
R-13RQ-43infra#26资源屏蔽粒度客户仓库 infra#26
R-13、R-15RQ-41infra#29修复流程、修后验证与修复时长客户仓库 infra#29
R-05RQ-12客户 GPU 预检说明客户现有 GPU 预检脚本的检查项说明客户提供的 Drive 文件,不提供公开链接(客户问答表 调度+容错+指标采集 B14 中有引用)
R-01、R-02—Google 侧共享的基线文件基线与 pass/warn 推断值客户仓库 基线文件
R-02—Google 侧共享的 ICI 分轴带宽脚本ICI 分轴带宽测试客户仓库 分轴带宽脚本
R-06—Google 侧提供的 15 s 采集器配置与说明15 s 带内采集配置与说明客户仓库 采集器配置、客户仓库 采集器说明
R-09—Google 侧共享的告警来源清单告警来源清单(离群规则标为推断)客户仓库 告警来源清单

C.3 官方文档与公开仓库#

编号文档用于链接
C3-01TPUMS(accelerator-microbenchmarks)v2.0 与 tpums CLI、benchmark 配置GitHub
C3-02TPUMS issue #145上游功能请求:EUD 式套件与同步脉冲压测(open,RQ-03、RQ-04;另见 C.2 infra#4)#145
C3-03Cluster Health Scanner仓库 main 仍是 legacy v1(cluster_diag、Helm);0.3.x 只以镜像 gce-ai-infra/chs/chs:0.3.2 分发GitHub
C3-04tpu-info本地芯片状态 CLI文档、GitHub
C3-05TPU7x(Ironwood)芯片规格、HBM 192 GiB/chip、主机内存文档
C3-06TPU 机型tpu7x-standard-4t 规格文档
C3-07GKE 上的 IronwoodGKE 最低版本文档
C3-08在 GKE 中部署 TPU 工作负载运行时指标端口 8431、worker 协调端口 8471Standard、Autopilot
C3-09自定义 OS 镜像vfio-pci 绑定与 vBar agent文档
C3-10GKE 已知问题tpu7x 芯片数上报问题与修复版本文档
C3-11监控 TPUCloud Monitoring TPU 指标与 Beta 表文档
C3-12TPU 健康状态infra_health 与 Cloud Logging 健康原因文档
C3-13GKE TPU 故障排除tpu-device-plugin 日志查询文档
C3-14ML Diagnostics 工作负载监控托管的性能下降与 hang 检测文档
C3-15COS 磁盘与文件系统只读根分区与 noexec 挂载文档
C3-16报告故障主机(GKE)cloud.google.com/fault-behavior 标签与取值文档
C3-17gcloud report-host-as-faulty命令与 flag参考
C3-18All Capacity 模式报修TPU VM 报修流程与时长文档
C3-19Jouppi 等,IEEE Micro 2026FBIST 与 VPU 硬件重放arXiv 2606.15870
C3-20ML Workload Debugging WikiSDC 校验和不一致、ICI straggler、slice failure、Megascale hang、节点隔离、数据非确定性、ECC 错误、Terminating 卡住恢复SDC、ICI、slice、Megascale hang、隔离、非确定性、ECC、Terminating 恢复
C3-21OpenXLA Megascale 调试流程hang 诊断摘要与 Data input stall文档
C3-22OpenXLA 确定性确定性边界(GPU 对照)文档
C3-23Kubernetes 强制删除 Pod强删的前提与风险文档
C3-24ethtool netlinkTCP data split 是 ring 参数文档
C3-25GKE 中的 TPU多主机节点池中节点修复对整个 slice 的影响文档
C3-26GKE 节点系统配置kubelet containerLogMaxSize、containerLogMaxFiles文档
C3-27查看 GKE 维护事件维护事件通知与日志文档
C3-28TPU All Capacity 维护事件TPU 维护事件日志文档
C3-29GKE Slice 对象Slice CRD 字段文档
C3-30TPU Goodput作业 Goodput 指标(BETA)文档
C3-31TPU 故障排查libtpu 日志环境变量(TPU_STDERR_LOG_LEVEL 等)文档
C3-32Logging 查询语言日志过滤条件与 sample()文档
C3-33Observability Analytics(原 Log Analytics)日志 SQL 分析文档
C3-34SQL 告警基于 SQL 查询的日志告警文档
C3-35Cloud Monitoring PromQLPromQL 查询与标签文档
C3-36告警 snooze维护窗口内静默告警文档
C3-37AlertPolicy API告警策略字段文档
C3-38stackdriver_exporter把 Cloud Monitoring 指标导出给 PrometheusGitHub

D 已知限制与未验证项#

项目现状原因 / 尝试过什么建议措辞或后续
跨 slice DCN 带宽、网卡聚合带宽未测验证集群只有 1 个 2x2x2 slice(2 台主机),没有真实跨 slice 路径。机型文档列 tpu7x-standard-4t 物理网卡 2 块、单 VM 最高 400 Gbps(TPU 机型)文档;验证集群节点 guest 内只见 eth0(gVNIC,MTU 8896,ethtool 速率 200 Gbps)实测不给 DCN 门限;节点间 iperf3 结果见附录 A.12.2;多 slice 环境就绪后用 TPUMS dcn_* 实测
4x4x4 及更大拓扑未测只有 2x2x2 节点池CHS 门限(4x4x4 psum 352 等)标为 文档,大拓扑交付时实测
accelerator/* Beta 指标2026-10-27 至 10-29 有约 42.5 h 数据(60 s 间隔),此后 5 天以上无数据点;2026-11-03 约 1 h TPU 负载期间仍无数据原因不明;同期同 zone 非 GKE 的 TPU7x VM 仍在上报,原因未确认;accelerator/duty_cycle 等在 7 天内从未出现;同一时段 chip_state、infra_health、active_chips 等正常上报,TPU 负载不能使其恢复(附录 A.6.2、A.11.1)实测告警同时检查数据缺失;按芯片利用率改用 GKE 容器指标 kubernetes.io/container/accelerator/* 或带内 15 s 采集
failure_prediction_status、failure_prediction_score验证项目 30 天、42 天内均为 0 条序列只能核对文档中的标签 Value 与三种取值写“按文档配置,尚未见到实际数据 未验证”
TPU 健康原因日志(FINGERPRINT_MISMATCH 等)30 天内 0 命中文档未给日志名;项目级 30 天全文检索超时先按文档字段建查询,首次出现后再校准
报修路径(fault-behavior 标签、report-host-as-faulty)只核对文档与 --help验证环境不允许对节点打标签或报修;GKE 文档只列 GPU 机型写“文档,TPU v7x 是否适用需与 Google 确认”
Slice 删除重建耗时、Dynamic Slicing未测验证集群没有 Slice、JobSet CRD;属调度范畴本文不展开
慢节点规则(TCU 最高即降频、集合通信延迟最低即慢节点)部分实测单 slice 2 worker 同步作业演示:步耗时在两个 worker 上相同;主机侧慢节点 duty_cycle 最低(58.5 对 100),计算型慢节点 TensorCore 利用率最高(67.5 对 40.6),两类慢节点的 hlo_execution_timing 均最低(附录 A.11.1)实测;降频型慢节点未复现,multislice 时延指标在单 slice 上无数据按实测写三类信号,只用于生成嫌疑名单;“TCU 最高即降频”写“推断 未验证”
维护期间健康指标是否反映性能下降未验证无文档,验证期间未遇到维护事件慢作业先查维护事件(3.5.2)
ICI 故障方向(±X/±Y/±Z)无法确定port_id 只标出 tray、芯片与端口(int/ext),方向映射无文档;.int、.ext 分指主机内、主机间链路属推断写“可定位到主机、芯片和端口”,方向待 Google 确认
温度、功耗门限(85 °C、液冷 45–72 °C、空闲 60 W、突发 450 W)无来源TPUMS、CHS、公开文档均无;实测 240 s 浸泡 hbm_peak_temp_c 44 °C(浸泡前窗口 45 °C),peak_temp_c(核心)字段为空用同批节点相对基线告警,起始值按上线后 2 周实测基线调整
同步脉冲对供电与去耦老化的筛查效果未验证工程假设,无公开数据;上游 #145 仍是功能请求写“用于施加瞬态负载,筛查效果待验证 未验证”
返修准入循环时长(3.2,N = ⌈要求总时长 ÷ 单轮时长⌉,单轮约 1.55 h;要求不少于 8 h 时 N = 6,总计约 9.3 h)估算单轮各项已分别实测(8 device HBM 扫描 124 s,3201.7–3241.5 GB/s/device,附录 A.2.1),3600 s soak 实测 3640 s,XProf slowdown 1.0054(墙钟 1.0104),throttle 0%;整轮未连续运行,单轮时长为各项之和;Google 已对返修主机做 burn-in标 估算,首轮实跑后按实测修订
H2D、D2D、ICI 验收门限无一手门限旧版 ≥46 GB/s/chip、D2D ≥600、ICI ≥85 GB/s 无来源。实测 TPUMS host_to_device(jax 后端,4 GiB/device)约 46 GB/s/host;单机模式 D2D 片内 342、跨芯片 46.6 GB/s/device只给实测参考值并注明口径,不设硬门限
MaxText 吞吐与 MFU未测计划中的 MaxText 运行因 TPU 使用时间窗口取消,本次未在集群上运行 MaxText不给数值
固件版本与升级流程不可见Google 未公开写“客户镜像无需安装 TPU 驱动或固件(vfio-pci 为标准内核驱动);固件由 Google 管理,版本与升级流程未公开 未验证”
“带外指标来自主机 BMC”无来源公开文档未提 BMC写“Google 写入 Cloud Monitoring 的主机侧带外遥测”
Terminating 卡住的根因(子进程继承 /dev/vfio 句柄)假设未复现写“可能原因之一”
sidecar-log-collector 覆盖范围实测限制同一容器内第二个及以后的 libtpu 进程,其新日志文件未上传 Cloud Logging:sidecar 一直跟踪首次发现的文件,libtpu 新进程写新文件并改指 tpu_driver.INFO 符号链接;日志条目的 pod_name 是 device plugin Pod,工作负载只能由 <容器名> 目录与节点区分(附录 A.7.2、A.7.3)实测多进程诊断运行直接从 Pod 内 $TPU_LOG_DIR 取日志;按 textPayload 中的 /tmp/tpu_logs/<容器名>/ 过滤
/tmp/tpu_logs 生命周期实测限制TPU_LOG_DIR=/tmp/tpu_logs/<容器名> 挂载自主机 /tmp/tpu_logs,位于 COS /tmp tmpfs;Pod 删除后文件仍在,下一次在该节点分配 TPU 时被清空(附录 A.7.2)实测;位于 tmpfs,节点重启后应丢失 未验证需要保留的 libtpu 日志在作业结束前复制到持久存储,或依赖 sidecar 上传(只覆盖首个进程)
旧版引用的原文串(如 “Timed out waiting for slice construction”)无出处代码与文档检索均未命中改写为 DEADLINE_EXCEEDED(下游症状)
libtpu 直方图冷启动输出 NaN未复现无来源;Prometheus 直方图本身没有 min/max删除
CHS stress 测试的 SDC 结果已实测2026-11-03 standard 中 compute-stress、hbm-stress 均记录 STRESS_PASS,network-stress(不输出 STRESS 事件)三轴均有带宽值,三项均无数据不一致(附录 A.3.1)只代表该次运行与 2 个节点,不推广为机群结论
单台主机 VFIO 异常导致多机作业挂起未复现推断合理,但没有测试写“多机作业会因任一主机异常整体失败或超时,单机清点应先做”
作业退出后 condition 残留属误报,chip_state 为 4 即可保留节点无来源文档与实验均未覆盖只写判定式(PromQL 见表后):10 min 内最近一次 HEALTHY 芯片数为 4,且同一 instance 没有非 HEALTHY 序列;unless 部分不可省,单用 HEALTHY 为 4 时 last_over_time 会把故障期间的数据空档桥接过去;用瞬时查询会因 256–296 s 入库延迟漏掉节点;短指标名返回空结果(实测)。不写误报结论
ICI 单轴理论 90 GB/s、XLA 在非对称环面上跑不满三个环无来源TPUMS 规格写每链路每方向 100 GB/s只保留实测值,不写百分比与成因
与 GPU 工具的对应(nvidia-smi、dcgmi diag -r 1..4)非官方类比无文档给出一一对应写“类似”,并注明非官方表述
微基准上的 SDC 工具开销实测值来自小负载XSC 用 8 device 链式 matmul,ici-sdc-test 用 8 MiB psum(附录 A.4.2、A.4.3)真实模型的开销需在客户负载上复测,正文数值只作量级参考
逐位确定性小程序实测bf16 matmul、gelu 与跨 device all-reduce,2 个节点、3 个 jax/libtpu 组合(附录 A.4.4)完整模型、输入管线与多 slice 的确定性需客户负载复测
两台主机各作一个伪 slice 的 DCN 探测不代表 DCN两个伪 slice 经 Pod 网络通信,6.4–6.8 GB/s/host,不经过真实 DCN 路径(附录 A.12.1)不引用该数值作为 DCN 基线
precheck_v2 发布版本以 v2b 为准原配方在 libtpu 0.0.34 上因未知 flag 失败;v2b 只改 TPU_HOST_BOUNDS(附录 A.9.1)发布前在客户镜像的 libtpu 版本上复跑一次
CHS 集群内运行实验做法与 Helm 部署不同实验用最小权限 runner Pod 与带 GKE context 名的 SA kubeconfig(附录 A.3.2)客户按 CHS 官方部署方式运行,遇 Failed to retrieve cluster name 时参考附录 A.3.2
ici_sdc_test 能否按 step 用 compiler_options 开启未验证只验证了 XSC 的 compiler_options 方式写“需先在目标 libtpu 上验证”
Megascale hang 摘要的日志级别未验证无公开说明按文本检索,不按 severity 过滤
TPU_LOG_DIR 移出 /tmp/tpu_logs 后的采集未验证依据 sidecar DaemonSet 的扫描路径推断保持默认 TPU_LOG_DIR
vbar_control_agent OOM 与报修未验证验证期间未遇到记录节点与时间后报修
修复后客户自加的 cordon 与污点未验证GKE 文档只说明移除它自己加的污点与标签回池前人工检查并撤销
带 tpu-health 标签节点上的 CHS 实跑未验证只做了 --dry-run=server 与测试 Pod 核对首次使用时实跑确认
terminationGracePeriodSeconds 设 1–5 s 的效果未验证未测按 checkpoint 保存所需时间设置

节点保留判定式(对应上表“作业退出后 condition 残留”一行):

PromQL
(max by (instance_id) (last_over_time(compute_googleapis_com:instance_tpu_chip_state{monitored_resource="gce_instance", state="HEALTHY"}[10m])) == 4) unless on (instance_id) (max by (instance_id) (last_over_time(compute_googleapis_com:instance_tpu_chip_state{monitored_resource="gce_instance", state!="HEALTHY"}[10m])) > 0)

带内遥测、日志、慢节点与告警演练(2026-11-03,单个 2x2x2 slice)带来的限制:

项目现状原因 / 尝试过什么建议措辞或后续
慢节点演示规模单 slice,K=22 worker 同步作业;“末到者占比 ≥ max(50%, 3/K)”规则在 K=2 时 3/K=150%,永远不会触发,至少需 K≥6;不加门限的末到者二项检验在健康阶段也报出“慢节点”(两 worker 间隔约 0.3 ms),加 ≥5 ms 间隔门限后只标出主机侧慢节点(附录 A.11.1)实测在生产多主机作业上按实际 K 重新校准;统计结论只进嫌疑名单,不自动 cordon
multislice 时延与集合通信端到端指标单 slice 上无数据kubernetes.io/container/multislice/* 无序列,带内 :2113 无 collective_end_to_end_latencies_microsecond,tpu-info 的 collective_e2e_latency 报不可用(仅 multislice)(附录 A.11.1)实测多 slice 环境就绪后复测;单 slice 用 duty_cycle、TensorCore 利用率与 hlo_execution_timing 代替
ML Diagnostics 检测范围未报慢节点与 hang作业创建后 4 s 自动建 run;计算型与主机侧慢节点各持续 10 min,均无事件;hang 开始后 37 s 报一条 PERFORMANCE_DEGRADATION(13 个分析器均为 NOT_DETECTED),没有 hang 类事件(附录 A.8.1)实测作为补充信号,不替代进度告警与 duty_cycle 告警;慢节点定位用带内指标
主机网卡 iperf3 与 DCN只代表主机 TCP同 zone 两台 tpu7x-standard-4t 节点经 VPC 的主机 TCP:16、32 流每方向 190.7 Gbit/s(23.8 GB/s),单流 49.7 Gbit/s;不经过 ICI,也不是多 slice DCN 集合通信带宽(附录 A.12.2)实测只作主机网络基线,不作 DCN 门限
无进度告警与 duty_cycle==0 告警实测有误报log-based 步数指标加 300 s absence 告警:hang 后 10 min 52 s 开启,恢复后 3 min 40 s 关闭;作业正常结束后 11 min 24 s 同样开启。duty_cycle==0 持续 5 min 的规则在启动阶段(首步前约 6 min 空闲)误报,hang 后 5 min 24 s 触发(附录 A.11.2)实测absence 告警只在作业仍 active 时生效;duty_cycle 规则以步数计数器做阶段门控(已出现训练步后才告警)
collector 部署权限需集群级只读权限15 s collector 0.1.4 只给命名空间 Role 时 k8s_attributes 报 nodes forbidden;在 CPU 节点上 tpuhost 随后因取不到 accelerator-type 退出 实测;TPU 节点上未单独测试 未验证;最小权限为 Role(pods)加 ClusterRole(nodes 的 get、list、watch)(附录 A.5.1)部署前由集群管理员授予该 ClusterRole