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
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 关键结论#
- 交付验收可在客户侧完成:CHS 0.3.2
standard作为 DCGM EUD 的对应物做节点池级验收,输出带门限判定的 Bill of Health,TPUMS 做逐项深挖;2x2x2 上lite9 min 31 s(5 项)、standard17 min 58 s(8 项)全部通过 实测;CHS 不打标、不 cordon,隔离由客户自动化执行(2.2、2.3、3.1)。 - 数值必须带单位口径: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)。
- 客户可控的 SDC 手段是 XSC 与公开 playbook 中的 7 个
xla_tpu_ici_sdc_test_*flag,只用于诊断运行(实测 XSC 使 step 变为 2.08 倍);libtpu 遇到未知 flag 会启动即退出,上一版给出的 10 个 flag 中 9 个不存在(2.4、附录 B)。 - 起飞前检查 precheck_v2 逐项映射常见 GPU 预检 9 项(2 项无等价项,互联错误计数改用带外指标);initContainer 9–10 s、Pod 创建到主容器完成 22–24 s 实测,在 10 min 级的预检时间预算内(2.9、3.3)。
- 带外健康指标
infra_health、chip_state实测入库延迟 256–382 s,告警窗口不少于 10 min 且用last_over_time;instance/tpu/accelerator/*在验证集群 10-29 后中断,TPU 负载期间也无数据,需对数据缺失告警。DCGM 16 项在 TPU 上没有一一对应的指标(2.6)。 - libtpu 日志经 GKE
sidecar-log-collector进入 Cloud Logging,severity 恒为 INFO,需按文本中的 glog 级别过滤;TPU 没有 XID 式公开错误码表(2.7)。 - 致命和不可纠正错误由平台自动处理。平台未检出的问题:GKE 管理的 TPU 节点先隔离再开支持工单,不对其 VM 调用
report-host-as-faulty;GKEfault-behavior标签流程的文档只列 GPU 机型,TPU 需 Google 确认后再接入自动化(2.10)。 - 告警以作业进度为主信号(停滞、启动超时、步时 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-01 | TPU 版 DCGM EUD:客户侧可运行、逐芯片或逐节点给出 pass/fail 的深度诊断与交付验收套件,并给出时长 | RQ-01 客户问答表;RQ-02;RQ-03;RQ-09;RQ-10 | CHS standard/lite;TPUMS | 2.3、2.2、3.1 | A.3.1、A.2.1 | 实测(CHS lite、standard,TPUMS) |
| R-02 | ICI/DCN 集合通信性能基线、验收方法与参考指标;网络压测与连通性检查 | RQ-05 客户问答表;RQ-06;RQ-02 | TPUMS 集合通信;CHS collectives/network-stress;precheck_v2 | 2.2、2.3、2.9、3.1 | A.2.1、A.3.1、A.12 | ICI 实测(2x2x2);DCN 未测 |
| R-03 | 同步脉冲(di/dt 阶跃)负载压测 | RQ-04 TPUMS#145 | TPUMS 无此模式,实验脚本 | 2.2(2.2.4) | A.2.2、A.2.3、A.2.4 | 实验脚本实测;无官方工具 |
| R-04 | SDC 检测机制、客户可用的 SDC 工具与推荐时长、逐位一致性边界 | RQ-07 客户问答表;RQ-08 | libtpu SDC 检测;CHS stress 比对 | 2.4、2.3、3.5.5 | A.4.1–A.4.4、A.3.1 | 实测(开销、日志落点、确定性) |
| R-05 | 对标客户现有 GPU 预检脚本的 TPU 起飞前检查:sidecar 或 initContainer 形态、退出码、时长预算、通信就绪与版本一致性 | RQ-11 客户问答表;RQ-12;RQ-13;RQ-14 | precheck_v2;节点与芯片健康 | 2.9、3.3 | A.9.1、A.1.3、A.1.4 | 实测(initContainer 9–10 s) |
| R-06 | GKE 上 K8s/TPU 监控组件与指标名,以及接入客户 Prometheus 或自研采集的方式 | RQ-15 客户问答表;RQ-17;RQ-22;RQ-24 | Cloud Monitoring 系统指标;device plugin :2112;collector-15s | 2.1、2.5、2.6 | A.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-21 | Cloud Monitoring | 2.6 | A.6.1 | 实测(可见指标与标签) |
| R-08 | 租户可自采的 ICI/DCN 网络指标、仅 GCP 可见的部分、“RDMA 监控”的 TPU 等价方案 | RQ-16 客户问答表;RQ-29 | Cloud Monitoring ICI/NIC 指标 | 2.6、3.4 | A.6.1、A.6.2 | 标签实测;负载期间 accelerator/* 仍无数据 |
| R-09 | 硬件告警规则(掉卡、链路、ECC、健康态),按 fatal/非 fatal 分级接入现有告警与 Pod 替换流程;带外能力边界 | RQ-23 客户问答表;RQ-27;RQ-28;RQ-33 | Cloud Monitoring;device plugin;日志 | 2.6、3.4 | A.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.1 | A.1.1、A.1.3 | 文档(验证环境无 Dynamic Slicing) |
| R-11 | 硬件错误上报渠道与日志位置、错误分级(致命或可忽略)、日志盘容量控制 | RQ-30 客户问答表;RQ-31;RQ-32;RQ-38 | 日志;Cloud Monitoring 错误计数 | 2.7、2.10、3.4 | A.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.5 | A.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.5 | A.10.1 | 文档、--help 与 --dry-run,未实操 |
| R-14 | 局部故障降级运行与恢复时间;hang 或慢节点的 checkpoint 恢复与自动踢除 | RQ-42 客户问答表;RQ-45;RQ-46 | 故障处置 runbook | 3.5 | — | 文档 |
| R-15 | 修复后回归准入(修复节点需经长时间深度压测才回池)与修复时长信息 | RQ-41 客户仓库 infra#29;RQ-44 | CHS standard 循环;TPUMS soak;libtpu SDC | 3.2、3.5.7 | A.3.1、A.2.1 | 估算(单项均已实测,整轮未连续运行) |
“状态”指本文答复所依据证据的完备程度。
2 能力工具箱#
本章每节对应一个工具或信号源:先列它回答的需求,再给接口、实测值与注意事项。公共初始化只在 2.0 写一次。
2.0 公共初始化#
第 2、3 章的命令共用本节的凭据、Pod 模板与安全规则。
2.0.1 凭据与命名空间#
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 的单个节点独立运行,用于逐节点检测):
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}}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:
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 清理与安全#
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 conditions | 26 种,含 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 的 PID | 4 行 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 |
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 的特权
hostPIDPod 可与作业并存;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.yaml | bf16、fp8 GEMM | 16384³:bf16 2107.6、fp8 4441.6 TFLOP/s/chip,为规格的 91%、96% 实测 | 35 s | 不低于机群中位数 −5% |
2x2x1/hbm.yaml | HBM copy,256 MiB–2 GiB | 3210–3242 GB/s/device 实测 | 22 s | 同上 |
2x2x1/host_to_device.yaml、device_to_host.yaml | H2D、D2H | tpu_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) | 满载 soak | slowdown 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 集合通信,bf16 | all_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)。
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 72.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-info | JAX device 数 | ==8 | 8 | 8 s |
tpu-gemm | 16384³ bf16 | ≥950 TFLOP/s/device | 1042.1–1066.9 | 4 min 16 s |
tpu-hbm | 单 device copy,4 GiB 处判定 | ≥3040 GB/s/device | 3221.9–3222.7 | 3 min 10 s |
tpu-host-device | pinned memory H2D、D2H | ≥182、≥48 GiB/s/host | 204.5–206.4、53.8–54.1 | 44 s |
tpu-collectives | psum,fp32 | 2x2x2 ≥190、4x4x4 ≥352 GB/s(另有 2x2x1 124、2x2x4 133、2x4x4 162);表外拓扑没有 psum 门限,状态为 UNKNOWN 文档 | 210.8–211.5 | 1 min 46 s(lite 45 s) |
tpu-compute-stress | 每 device 1500 轮、每轮 8 次 16384² bf16 matmul,与 device 0 逐位比对 | ≥869 TFLOP/s/device | 920.8–921.5 | 2 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.1 | 3 min 10 s |
tpu-network-stress | 每轴邻居 ppermute 1 GiB,payload 比对 | 每轴 ≥152 GB/s(实为 GiB/s,见 2.3.3) | 170.8–171.3 | 1 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 min | 9 min 31 s 实测 |
standard | lite 加三项 stress | ~30 min | 17 min 58 s 实测 |
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.7 | ecc-errors 文档 |
| XLA SDC Checker(XSC) | HLO 重跑并比对输出 checksum,或扫描 NaN/Inf | 是 | non-determinism triage 文档 |
ici-sdc-test | 程序开头注入 ICI 传输校验,定位慢链路与传输错误 | 是 | ICI straggler triage 文档 |
2.4.2 用法(仅用于诊断运行)#
# 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 s | duty_cycle、memory_* 仅在容器持有 TPU 时有数据,memory_used 延迟 1–31 s;tensorcore_utilization 空闲也有,延迟 48–78 s 实测 |
:2112 | tpu-device-plugin Prometheus 端点,与系统指标同为 tpu-exporter 的对应物(客户问答表)文档 | device plugin 已配置 实测 |
:2113 | 15 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 s | 42 天 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)。
# 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 无数据 实测:
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=7m2.7 日志#
回答 R-11(辅助 R-09)。TPU 没有 GPU XID 式的公开错误码表(客户问答表),错误定位依靠下列日志和 2.6 的计数指标,实测见附录 A.7.1。
| 来源 | Cloud Logging 位置 | 要点 |
|---|---|---|
libtpu tpu_driver.INFO | kube-system/tpu-device-plugin-* 的 sidecar-log-collector 容器 stdout | 行前缀 [/tmp/tpu_logs/<容器名>/tpu_driver.INFO];severity 恒为 INFO;pod_name 为 device plugin Pod 实测 |
| workload stdout/stderr | workload 命名空间的 k8s_container | libtpu 默认只把 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 eventMaintenanceWindowScheduled(注解maintenance.gke.io/*)→ 日志maintenance.googleapis.com/maintenance_events;节点带 labelcloud.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)文档。
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) |
| 2 | P2P | 本机 4 芯片 all-reduce | 10(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 接受 实测;实际驱逐与上报效果未验证 未验证:
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.1 交付验收#
回答 R-01、R-02、R-04。新节点池接业务前确认每个 chip、每台主机和 slice 内 ICI 达标,并留存基线。TPUMS 与诊断运行的门限均为起始值,按上线后 2 周实测基线调整。
| 步骤 | 内容 | 范围 | 通过条件 | 耗时 |
|---|---|---|---|---|
| 1 | 节点与芯片健康(2.1) | 每节点 | 见 2.1 | 见 2.1 |
| 2 | CHS standard(2.3) | 每节点池,整 slice 空闲 | BoH 8 项均为 RESULT_STATUS_SUCCESS,内置门限见 2.3.1;表外拓扑的 psum 为 UNKNOWN,改按步骤 4 判定 | 17 min 58 s 实测 |
| 3 | TPUMS 单主机项: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 估算 |
| 4 | TPUMS all_reduce、all_gather、all_to_all(2.2) | 每 slice | 各项 xprof GB/s/chip 不低于同拓扑基线 −5% | 112 s,不含安装 45 s 实测 |
| 5 | XSC 诊断运行:--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 测试程序,含初始化)实测 |
| 6 | ICI 诊断运行,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 进程的日志):
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 执行。
# 训练 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 及以上拓扑需首轮实跑后修订。
- 节点回到集群后确认已 uncordon、无客户自加的 NoSchedule 污点,打
tpu-health=pending。kubectl 打的节点标签在节点重建时丢失(GKE 节点升级),重建后的节点没有tpu-health=pass,同样不接训练 Pod 文档。 - 循环 N 轮,每轮须满足 3.1 步骤 2、3、5、6 的全部通过条件(
gemm_throttling按 3600 s 判定);第 2 轮起 gemm TFLOP/s/chip 与 hbm GB/s/device 不低于第 1 轮的 98%(起始值)。 - 任一轮失败即停止,打
tpu-health=fail;XSC 或 ICI 诊断失败时先用定位模式(2.4.2)收集全部事件,再按 2.10 重新上报。 - 全部通过后打
tpu-health=pass。节点池升级或其他重建节点的操作可能清除tpu-health=pass(同一 GKE 文档)文档,自动化需在 quick 检查(3.5.7)通过后重新打标,否则训练 Pod 无节点可用。
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-healthCHS 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 处理 |
| initContainer | precheck_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、105 | TPU PCI 设备缺失或驱动异常 | 隔离节点,按 2.10 上报 |
| 106~108 | PCIe AER 致命计数或链路降级(v7x guest 内不可见时只告警) | 隔离节点,按 2.10 上报 |
| 109、110 | 网卡 down 或 TCP data split 为 on | 隔离节点,核对 GKE 版本与节点池配置 |
| 111、113 | 磁盘使用率或可用内存不足 | 清理节点后重试 |
| 112 | MemTotal 低于下限(节点内存缺失) | 隔离节点,按 2.10 上报 |
| 114 | 软件指纹失败 | 镜像问题,不隔离节点 |
| 120 | TPU 冒烟失败或超时 | 先看 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 s | 2.5 |
| 带外 | compute.googleapis.com/instance/tpu/* | 256–382 s | 2.6 |
| 日志 | sidecar、device plugin、节点、串口 | p95 约 7 s | 2.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)实测:
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 的事件,不计入)实测:
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=1d3.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 min | ERROR | 平台 | 3.5.6 |
| A2a 芯片非健康 | 2.6.3 第 2 条(非 HEALTHY 芯片数大于 0,last_over_time[10m]);第 4 条(节点池内上报节点数少于规模) | 10 min | ERROR(工单或群消息,不呼叫) | 平台 | 3.5.6 |
| A2b 芯片非健康持续或伴随停滞 | 非 HEALTHY 序列 count_over_time(...[20m]) >= 19(芯片实际不健康约 20 min 以上),或该节点上运行的作业同时出现 B1 进度停滞,或该节点出现 B4 | 20 min,或与 B1、B4 同时 | CRITICAL(呼叫) | 平台、训练 | 3.5.6 |
| A3 不可纠正错误 | hbm_uncorrectable_count、pcie_fatal_error_count 的 increase() 大于 0 | 15 min | CRITICAL | 平台、训练 | 3.5.6 |
| A4a ICI 致命 | ici_link_health = 10 | 10 min | CRITICAL | 平台、训练 | 3.5.3、3.5.6 |
| A4b ICI 降级 | ici_link_health 6–9;1–5 或 ici_link_flaps 增长只记录 | 10 min | ERROR | 平台 | 3.5.3 |
| A5 非致命与降级 | pcie_nonfatal_error_count 增量、NIC rx 丢包增量与 tx 丢包速率偏离基线、降频偏离基线 | 15 min | WARNING | 平台 | 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_first | ERROR | 训练 | 3.5.4 |
| B3 步时回退 | 步时 p50 高于基线 1.10 倍触发(恢复门限 1.05 倍需用第二条条件或下游去抖实现,未验证);同步训练各 worker 步时相同,定位慢节点用 B6 | 15 min | WARNING | 训练 | 3.5.2 |
| B4 活跃度兜底 | 节点 duty_cycle 5 min 内全为 0,且该作业 60 min 内有过 step(相位门控,排除启动与编译) | 5 min 后再持续 1 min | ERROR | 训练 | 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 min | ERROR | 训练 | 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 min | WARNING | 平台 | 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,只核对了指标存在 未验证。
# 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_cycle58.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 与上报未实际执行):
- 确认证据:至少一项独立证据(维护事件、带外健康异常、预检或复测失败)。只有统计嫌疑时停在本步,作业结束后对该节点做 quick 复测(3.5.7)。
- 隔离:
kubectl cordon <NODE>只阻止新调度,运行中的 Pod 不受影响;同时撤销健康标签kubectl label node <NODE> tpu-health-,并记录kubectl annotate node <NODE> ops.example.com/isolation="<操作者>;<原因>;<UTC>" --overwrite。cordon 后不立即删除 Pod。 - 保存 checkpoint:按作业框架触发,确认最新 checkpoint 已完整写入存储;依赖 SIGTERM 保存的作业在第 4 步的优雅删除中完成,前提是
terminationGracePeriodSeconds足够(3.3)。 - 腾空:删除整个作业(多主机作业的全部 Pod 一起删),不加
--grace-period:kubectl delete job <JOB> -n <NS>,再等待退出:kubectl wait --for=delete pod -l job-name=<JOB> -n <NS> --timeout=<宽限期加 60>s。 - 卡住的 Pod:节点仍 Ready 而 Pod 超过宽限期仍 Terminating 时,
kubectl delete pod <POD> -n <NS> --grace-period=1(不加--force),用 3.5.6 的命令确认已消失。 - 上报:按 2.10 开支持工单并附证据;
fault-behavior标签只在 Google 确认支持 TPU 后使用,且只打一次。 - 强制删除:只有节点 NotReady 或 VM 已重置、重建后仍有 Terminating Pod,才用
kubectl delete pod <POD> -n <NS> --force --grace-period=0。 - 恢复作业:Dynamic Slicing 集群在健康 partition 上重建 Slice 后重新提交;固定拓扑节点池等 GKE 重建 slice 或改用其他节点池;从第 3 步的 checkpoint 恢复。具体编排属调度范畴。
- 回池:修复后
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_utilization48–78 s)实测。真正的带外指标compute.googleapis.com/instance/tpu/accelerator/*在整个实验期间无数据 实测。各节点基线的 TensorCore 利用率本身相差 4–13 个点,离群阈值不宜低于 25% 实测。降频型慢节点未测试 未验证。
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 实测:
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 Job | 1 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 项,整 slice | 112 s | 实测 | 附录 A.2.1 |
| 交付验收 | CHS lite | 9 min 31 s | 实测 | 附录 A.3.1 |
| 交付验收 | CHS standard | 17 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)。
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 回归准入#
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 实机验证完整过程#
本附录记录 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.1A.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.2A.0.2 凭据与命名空间#
使用独立 kubeconfig。使用 TPU 前确认目标节点上没有其他 Running 或 Pending 的 Pod 申请 google.com/tpu。
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.3A.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 的容器注入 实测:
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.4A.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 执行;两个节点可各跑一个。
# 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.5A.0.5 多机模式:2 个 Pod 覆盖整个 2x2x2 slice#
清单中不写任何 TPU 环境变量 实测。
apiVersion: v1
kind: Service
metadata: {name: tpu-mh-svc}
spec: {clusterIP: None, selector: {job-name: tpu-mh}}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 中并发执行同一命令:
# 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.6A.0.6 主机检查 Pod(特权、hostPID、hostNetwork,不申请 TPU)#
只容忍 TPU taint,不申请 google.com/tpu,可与训练任务并行。首次 Ready 4 s、安装工具 9 s;后续各轮 Ready 加装工具 6 到 14 s 实测。
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.7A.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)实测。
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.8A.0.8 Cloud Monitoring 与 Cloud Logging 访问#
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.9A.0.9 清理#
kubectl -n $NS delete job,svc,pod --all --wait=true
kubectl delete namespace $NSA.0.10A.0.10 libtpu flag 设置#
单机实验在 A.0.4 的 holder Pod 中使用三套 Python 环境,覆盖三个 libtpu 版本 实测:
| Python | jax、jaxlib | libtpu | 安装方式 | 安装耗时 |
|---|---|---|---|---|
/opt/venv/bin/python3(镜像默认) | 0.9.0 | 0.0.34 | jax-ai-image tpu:latest | — |
/tmp/v050/bin/python3 | 0.12.0 | 0.0.50.1 | python3 -m venv /tmp/v050 && /tmp/v050/bin/pip install "jax[tpu]==0.12.0"(与 TPUMS 固定版本相同) | 15 到 36 s |
/tmp/v051/bin/python3 | 0.12.0 | 0.0.51 | 同上,再 pip install --no-deps libtpu==0.0.51 | 约 30 s |
# 传递 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.11A.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 窄):
| 范围 | 资源 | 动作 | 用途 |
|---|---|---|---|
| ClusterRole | nodes | get、list、watch | 节点发现 |
| ClusterRole | pods(所有命名空间) | get、list、watch | 检查节点是否忙 |
| ClusterRole | namespaces | get、list、create | 创建 chs 命名空间,不授予 delete |
| ClusterRole | accelerator.gke.io slices | get、list | Slice CRD 探测;返回 403 而非 404 会中止运行 |
| ClusterRole | networking.gke.io networks | get、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。
# ServiceAccount(RoleBinding、ClusterRoleBinding 绑定到它)
apiVersion: v1
kind: ServiceAccount
metadata: {name: chs-runner, namespace: tpu-verify}# 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):
# 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>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 gcs3 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.12A.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_PORTS | device plugin Allocate | 2x2x2、tpu7x-16、1,1,2、2,2,1、true、8431..8438 实测 |
/dev/vfio/*、/var/run/tpu-plugin(只读,含 vbar.sock)、/tmp/tpu_logs | device plugin Allocate | 8 个 vfio 组(0–7)加 vfio;各芯片 function .0 对应的组号因节点而异 实测 |
A.1 节点与芯片健康(对应 2.1)#
A.1.1A.1.1 集群与 TPU 节点环境盘点#
目的:只读记录 GKE 在 tpu7x-standard-4t 节点池上部署的内容:版本、节点标签、annotation、taint、condition,tpu-device-plugin DaemonSet,TPU Pod 被注入的内容,启用的监控与日志组件。
前置:A.0.2。
命令:
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-maintenanceannotation 是集群内可读的计划维护信号,含窗口时间和can_reschedule实测。- 节点池 resource label
goog-gke-tpu-node-pool-type=single-host与实际的 2 host2x2x2slice 不符,不能用它判断单机或多机 实测。 - 验证集群
kube-system中另有用户自行部署的 DaemonSet,盘点时需与 GKE 组件区分 实测。
A.1.2A.1.2 节点主机只读检查(不占用 TPU)#
服务需求:R-05、R-09(见第 1 章);正文:2.1。
目的:不申请 google.com/tpu,核对起飞前检查和运维脚本依赖的主机事实:TPU PCI function、AER sysfs、PCIe 链路、内存、挂载参数、/dev/vfio、vbar.sock、/tmp/tpu_logs、网卡参数、主机监听端口、内核日志。
命令(Pod 内执行):
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 分类后再告警 实测。
A.1.3A.1.3 芯片与节点健康检查(单机与多机)#
服务需求: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 上运行。
psum 冒烟脚本 devices_probe.py(核心部分;每个 device 贡献 序号+1,结果应为 n(n+1)/2):
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]}))命令:
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 读取实时指标):
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-info0.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.514 s,pip 提示tpu-sync-jax要求 0.0.50)实测。
A.1.4A.1.4 /dev/vfio 持有者定位#
/dev/vfio 持有者定位#服务需求: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。
命令:
# 原方法: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)实测。
A.1.5A.1.5 Terminating Pod 列表命令#
目的:验证列出某节点上处于 Terminating 状态 Pod 的单行命令。
前置:A.0.2。验证时删除两个 holder Pod(terminationGracePeriodSeconds: 5),同时循环执行命令(每轮两节点各一次,轮间 sleep 1,实测每轮 4 到 5 s)。
命令:
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(所有命名空间)未验证。
A.2 TPUMS 与同步脉冲(对应 2.2)#
A.2.1A.2.1 TPUMS 微基准(单机与整 slice)#
服务需求: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 扫描。
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# 保存为 /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 deviceA.2.1.2 整 slice 集合通信(16 device,2 Pod)#
两个 Pod 都安装 TPUMS(并行 45 s),用 run_mh.sh 同时启动同一命令,TPUMS 自行调用 jax.distributed.initialize()。
./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_throttling | throttle_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 2120 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被 TPUMSop_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)实测。
A.2.2A.2.2 同步脉冲(di/dt)GEMM 测试与确定性校验和#
目的:参考 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,核心如下:
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 比对参考校验和命令:
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 default | node-a | 0.9.0、0.0.34 | 无 | 1581.5、1594.1、1599.3 | PASS |
| v1 default | node-a | 0.12.0、0.0.50 | 无 | 1583.6、1584.7、1594.3 | PASS |
| v1 仅性能状态参数 | node-a | 0.9.0、0.0.34 | 有 | 1806.9、1798.9、1801.1 | PASS |
| v1 仅性能状态参数 | node-a | 0.12.0、0.0.50 | 有 | 1787.0、1805.9、1802.9 | PASS |
| v1 注入故障 | node-a | 0.9.0、0.0.34 | 有 | 第 3 个脉冲 device 3 校验和 0x3df6cb65 | FAIL(预期) |
| v2 default | node-b | 0.12.0、0.0.50 | 无 | 1588.4、1599.6、1590.4、1590.0 | PASS |
| v2 仅性能状态参数 | node-b | 0.12.0、0.0.50 | 有 | 1760.6、1777.3、1778.1、1767.5 | PASS |
| v2 xprof | node-b | 0.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.yamlgemm 项中的性能状态参数被 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_c38 到 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)实测。
A.2.3A.2.3 pulse145_v2:正文采用的同步脉冲脚本#
目的:验证正文采用的同步脉冲(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):
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命令:
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),用于其他芯片时需修改该参数 实测。
A.2.4A.2.4 空闲间隙的性能状态行为#
目的:确认 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 中解析固件性能状态事件。
# /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 perfopts = 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.34 | 50、200、500 ms | 1480.1、1500.1、1481.0(无性能状态事件) | 1649.7、1646.7、1654.5 |
| jax 0.12.0、libtpu 0.0.50.1 | 50、200、500 ms | 1467.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,两者不能直接比较 实测。
A.3 CHS(对应 2.3)#
A.3.1A.3.1 CHS lite 与 standard 实测#
服务需求: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。
命令:
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-info | JAX device 数(每节点) | 8、8 | 8、8 | 等于 8 | SUCCESS |
| tpu-gemm | TFLOP/s per device(JAX device,半个芯片) | 1041.91、1066.96(MFU 90.3%、92.5%) | 1042.12、1066.86 | 不低于 950 | SUCCESS |
| tpu-hbm | 带宽中位数 GB/s per device | 3222.3、3222.1 | 3221.9、3222.7 | 不低于 3040 | SUCCESS |
| tpu-host-device | H2D、D2H GiB/s(每节点一个结果) | H2D 204.8、204.9;D2H 54.5、53.9 | H2D 206.4、204.5;D2H 53.8、54.1 | H2D 不低于 182,D2H 不低于 48 | SUCCESS |
| tpu-collectives | psum 峰值带宽中位数 GB/s(CHS profiler trace 计时,mesh 4x2x2) | 211.5、210.8 | 211.5、210.8 | 不低于 190 | SUCCESS |
| tpu-compute-stress | TFLOP/s per device | 不运行 | 921.48、920.81 | 不低于 869 | SUCCESS,STRESS_PASS |
| tpu-hbm-stress | GB/s per chip | 不运行 | 6364.08、6364.07 | 不低于 6108 | SUCCESS,STRESS_PASS |
| tpu-network-stress | 各轴带宽最小值,CHS 输出标注 GB/s | 不运行 | 170.82、170.81(X、Y、Z 轴 170.8 到 171.3) | 不低于 152 | SUCCESS |
耗时:
| 项 | lite | standard |
|---|---|---|
| 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 s | 11 s |
| tpu-info | 10 s | 8 s |
| tpu-gemm | 257 s | 256 s |
| tpu-hbm | 192 s | 190 s |
| tpu-host-device | 46 s | 44 s |
| tpu-collectives | 45 s | 106 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 s | 11 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.2runner 镜像不含 jq)实测。
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>.jsonA.3.2A.3.2 CHS CLI 与集群内运行#
目的:记录 CHS 0.3.2 chs CLI 的实际帮助文本,并说明在集群内(runner Pod)运行 CHS 时与 README 用法的差异和必需的修正。
前置:A.0.11(runner Pod、RBAC、SA kubeconfig、GCS 存储)。CLI 查询不需要 TPU。
命令(在 runner Pod 内执行):
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一致 实测。
A.3.3A.3.3 CHS 自带微基准镜像内容核查#
目的:核实 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,镜像如上):
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 目录布局。
注意事项:
A.4 libtpu SDC 检测(对应 2.4)#
A.4.1A.4.1 libtpu flag 矩阵#
目的:验证 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)。
命令:每个用例为一个新进程。
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 参数>)。
# 上一版报告 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.34 | 0.0.50.1 | 0.0.51 |
|---|---|---|---|
| 上一版报告 ICI 块(10 个 ICI flag 加 SparseCore embedding 确定性参数) | rc=1 | rc=1 | rc=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 实测。
A.4.2A.4.2 ici-sdc-test:真实 flag 的每步开销与日志位置#
服务需求: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 步。
# 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 无 flag | 0.56 ms | — | 0 |
C 只开 run_on_program_start | 0.576 ms | 无可测开销(在波动范围内) | 0 |
D 诊断组合,iterations=10 | 1.97 ms | +1.4 ms | 每 host 每步 8 行 |
B 诊断组合,iterations=5000 | 228.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)实测。
A.4.3A.4.3 XSC(XLA SDC checker)#
服务需求: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。
# 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# 用例 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 XSC | 57.81 ms(2.08) | 58.18 ms(2.08) | 含 instrumented 16 到 25 行(其中 HLO is instrumented (HLO rerun) 9 行,libtpu 0.0.34) |
| c 上一版报告 5 个 flag | 64.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_options | c1 为 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 ...警告,不影响运行结果 实测。
A.4.4A.4.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):
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()])命令:每个环境在同一节点上以两个独立进程各运行一次,另一节点同样执行。
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.1 | node-a 2 次、node-b 2 次 | acb82c6a9c88... | e8d7cf47ca91... | 同节点、跨节点全部一致 |
| jax 0.9.0、libtpu 0.0.34 | node-a 2 次、node-b 2 次 | a4c4eb7534bd... | db2d9686df74... | 同节点、跨节点全部一致 |
| jax 0.12.0、libtpu 0.0.51 | node-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 开关进行 实测。
A.5 带内 15 s 遥测(对应 2.5)#
A.5.1A.5.1 15 s 带内采集器部署与指标清单#
目的:以最小权限在独立命名空间部署 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)。与原文件相比的改动:
| 项 | 原文件 | 本实验 | 原因 |
|---|---|---|---|
| 命名空间与 SA | kube-system,复用有 node update/patch 权限的 tpu-device-plugin-sa | tpu-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 informer | filter: {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 间隔与原文件相同 实测。
命令:
# 最小 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 把两者绑定到采集器 SAkubectl 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 -cavg 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_total | libtpu 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_size | libtpu runtime,带 core_type | 8(4 芯片 × 2 TensorCore) |
ml_runtime_uptime_seconds | libtpu runtime,带框架名与版本 | 1 |
端口 :9431 | Orbax、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_timingp50(约 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 实测。
A.6 带外 Cloud Monitoring 指标(对应 2.6)#
A.6.1A.6.1 Cloud Monitoring TPU 指标(带外与 GKE 系统指标):数据有无、间隔与入库延迟#
服务需求: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):
# 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 s | 350、367、382 s | health_status=HEALTHY 或 UNHEALTHY(文档另列 DEGRADED、UNKNOWN,验证期间未出现),unhealthy_category=空 或 INFRA;值恒为 1 | 连续 |
instance/tpu/chip_state(BETA) | 60 s | 256、276、296 s | state;值为该状态的芯片数 | 连续 |
instance/tpu/active_chips、scheduled_chips(GA),utilized_chips(BETA) | 60 s | 256、275、294 s | accelerator_type=TPU_7X,reservation_id | 连续 |
kubernetes.io/node/accelerator/tensorcore_utilization、memory_bandwidth_utilization(GA) | 60 s | 48、63、78 s | accelerator_id=<instance_id>-<0..3>(host 内序号),tpu_topology | 连续,空闲时也上报 |
kubernetes.io/node 与 container 的 accelerator/duty_cycle、memory_used、memory_total(GA) | 60 s | 1、17、31 s | accelerator_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 有数据时段执行,语法与指标名有效,因无错误返回空 实测;未在故障场景验证。
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_id | 60 s,256–294 s 实测 | 连续 实测 |
A.6.2A.6.2 负载期间的带外 accelerator 指标#
服务需求: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)的时间序列。
# 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/*下没有任何序列 实测。
A.7 日志(对应 2.7)#
A.7.1A.7.1 Cloud Logging 中的 TPU 日志位置与过滤条件#
目的:确定 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):
# 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日志位置 实测:
| 来源 | logName | resource 与关键标签 | 说明 |
|---|---|---|---|
libtpu tpu_driver.INFO | stdout | k8s_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 plugin | stderr | k8s_container,container_name=tpu-device-plugin | jsonPayload.message |
| 节点 | kubelet、container-runtime、gke-node-problem-detector、events | k8s_node | NPD 产生 OOMKilling 事件 |
| VM 串口 | serialconsole.googleapis.com%2Fserial_port_1_output | gce_instance,instance_id 为数字 id | 内核日志 |
| 计划维护 | maintenance.googleapis.com%2Fmaintenance_events | gce_instance,instance_id 为实例名 | state、窗口、userControllable |
| 维护审计 | cloudaudit.googleapis.com%2Fsystem_event | methodName=compute.instances.upcomingMaintenance | type、maintenanceStatus、canReschedule |
| ML Diagnostics | ml_diagnostics_workload_event | generic_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_healthUNHEALTHY 时间窗内没有 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)实测。
补充过滤条件与维护时间线#
# 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 eventMaintenanceWindowScheduled(20:00:11,注解maintenance.gke.io/*)→ 日志maintenance.googleapis.com/maintenance_events(20:00:15);节点 labelcloud.google.com/scheduled-maintenance-time=1794254400,节点注解node.gke.io/upcoming-maintenance(JSON,含窗口与can_reschedule)实测。
gcloud logging read 'logName="projects/PROJECT/logs/cloudaudit.googleapis.com%2Fsystem_event"
AND protoPayload.methodName="compute.instances.upcomingMaintenance"' --freshness=7dA.7.2A.7.2 TPU_LOG_DIR、/tmp/tpu_logs 与 stderr 日志级别#
目的:用一个 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):
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# 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_LEVEL | stderr 中的 libtpu 行 | tpu_driver INFO 文件行数 | jax 初始化 |
|---|---|---|---|
| 未设置 | 0 | 186 | 3.23 s |
| 2 | 0(本次初始化没有 ERROR 行) | 186 | 3.14 s |
| 0 | 181 | 186 | 3.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会增加节点内存占用 未验证。
A.7.3A.7.3 sidecar 日志:运行中作业的 tpu_driver.INFO#
目的:确认运行中的 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;独特的容器名让前缀可区分)。
命令:
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 门限,因为这与负载有关 实测。
A.8 维护事件与 ML Diagnostics(对应 2.8)#
A.8.1A.8.1 ML Diagnostics 工作负载监控#
服务需求: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)实测。
命令:
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}匹配本作业 实测。
A.9 起飞前检查(对应 2.9)#
A.9.1A.9.1 precheck_v2 作为 initContainer 运行#
目的:把起飞前检查脚本放在多机 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。
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 precheckYAML 要点(Service 与 Job 模板的关键字段):
apiVersion: v1
kind: Service
metadata: {name: precheck-job}
spec:
clusterIP: None
publishNotReadyAddresses: true # initContainer 阶段 Pod 未 Ready,否则对端 DNS 无法解析
selector: {job-name: precheck-job}# 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 冒烟 | initContainer | Pod 创建到 main 结束 |
|---|---|---|---|---|---|
| R1 auto | v2、0.0.34、默认 | WARN(等待 30 s) | FAIL,未知 deepsea_* flag | 33 s,rc 120,Init:Error | Job 34 s 失败 |
| R2 single | v2、0.0.34、publishNotReadyAddresses: true | PASS | PASS,两个 init 同时完成多机初始化(4.1 s),gemm 加 all-reduce 5.3 s | 10 s | 24 s |
| R3 auto | v2、0.0.50.1(init 内 pip 安装 15.5 s)、默认 | WARN(30 s) | PASS,standalone,仅 gemm(ICI 关闭) | 53 s 和 72 s | 87 s |
| R4 auto | v2b、0.0.34、publishNotReadyAddresses: true | PASS | PASS,gemm 加本机 all-reduce | 9 s | 22 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 为发布版全文,可执行代码与实验运行版本相同 实测。
A.9.2A.9.2 precheck_v2b.sh 全文#
下面是附录 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。
#!/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
finishA.10 故障上报 CLI(对应 2.10)#
A.10.1A.10.1 故障上报与节点池升级相关 CLI(仅查看帮助)#
目的:确认运维手册引用的命令和 flag 写法,不执行任何破坏性操作。
前置:A.0.2。Google Cloud SDK 591.0.0。
命令:
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无法演示 实测。
A.11 告警与故障处置演练(对应 3.4、3.5)#
A.11.1A.11.1 慢节点与 hang:信号、检测时延与判定门限#
服务需求: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 在同一步切换;每步输出一行步日志。
命令:
# 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 minkubectl -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 门限)、L2avg 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 sL1 门限:一步中两个 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-info0.14.2 的collective_e2e_latency报 unavailable(需要多 slice)实测。 - 只有统计信号、L3 健康与维护检查都正常时,只列入可疑名单,不自动 cordon 实测。
- 节点标签
cloud.google.com/scheduled-maintenance-time=1794254400即 2026-11-09T20:00:00Z,与 GCEupcomingMaintenance窗口开始时间一致(canReschedule: true,onHostMaintenance: TERMINATE);分区与拓扑标签在该静态节点池上为空,physicalHost、physicalHostTopology未返回;节点上没有 Megascale 或 SliceError 类 condition 实测。 - ML Diagnostics 对两类慢节点都没有产生事件,hang 开始后 37 s 出现一个
PERFORMANCE_DEGRADATION(见附录 A.8.1)实测。
A.11.2A.11.2 进度告警:log-based metric 与 duty cycle 规则#
服务需求: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 行)。实验对象不配置通知渠道,实验后删除。
命令:
# 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。提取表达式含 ": ",必须加引号{
"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": []
}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 $PROJECTsum 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 s | 10 min 52 s;恢复后 3 min 40 s 关闭 | 不触发(尚无序列) | 11 min 24 s 后误报 |
带内 duty_cycle == 0 持续 5 min | 5 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;v3projects.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 时误报 实测。
A.12 DCN 与主机网络#
A.12.1A.12.1 DCN all-reduce 限时试验(仅实验室方法,非 DCN 基准)#
目的:验证集群只有一个 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 次)。
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 device | GB/s per host(8 个 device 合计,单方向) |
|---|---|---|---|
| 64 MiB | 83.02、84.41 ms | 0.81、0.80 | 6.47、6.36 |
| 256 MiB | 321.51、317.58 ms | 0.83、0.85 | 6.68、6.76 |
实测耗时:Job Ready 约 12 s;megascale 加 distributed 初始化 29 s;整个探测 46 s;限时实际用了约 1.5 min。
判定标准:两个 slice 可见(slice_indices 为 0 和 1),psum 结果正确。
注意事项:
- 这是实验室方法:一个
2x2x2slice 拆成两个 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 基线。
A.12.2A.12.2 两个 TPU 节点间的主机网卡带宽(iperf3)#
目的:测量同一 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)实测。
命令:
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>,依次运行下面的四个测试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 空闲 实测。
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 CLI | TPUMS 仓库、实测(附录 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.3 | chs 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→190 | boh_generator.py 对 min 型门限做 round(x*0.95);2x2x2 psum 在所有路径上都是 190(yaml 200) | 实测(附录 A.3.1)、核实记录 |
| 1.2、3.1.1、Q1.3 | psum 门限 2x2x2 ≥195、4x4x4 ≥216 GB/s;all_gather ≥204、all_to_all ≥27 | CHS 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.2 | collectives 跑 psum、all_gather、all_to_all;DEGRADED 时自动触发 Tier-2 network-stress | 0.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.5 | CHS psum 为“端到端墙钟中位数 @16384 MiB FP32”,与 TPUMS 差 2.3%,“完全吻合”;TPUMS HBM 6444.5 GB/s/chip | CHS 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.1 | gemm_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.7 | awk 判定 ethtool -g/-k 的 TCP data split;双 200G 网卡 eth0/eth1 | awk 未去掉制表符,判定永不触发;该项是 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.9 | 8471 是“ICI 会话协调端口”,initContainer 内对端“100% 可达”;只设 TPU_SKIP_MDS_QUERY=true 即可单机初始化;预检 15–25 s | 8471 是 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.1 | CHS 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.3 | 10 个 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.3 | ici-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 SEND | ici-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 的 core | ICI straggler triage、实测(附录 A.4.2) |
| Q1.4 | XSC 开销 1.8–2.5 倍;新负载前 24 h 每步开 XSC;Google 建议新硬件筛查 96 h | 1.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 H6 | SparseCore 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.1 | tpu/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 H14 | Beta 表共 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.1 | failure_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.2 | 15 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 实例):
delta(compute_googleapis_com:instance_tpu_accelerator_network_ici_link_flaps{monitored_resource="gce_instance"}[10m]) > 0B.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.4 | MegascaleHangDetected 由 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.3 | cloud.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.7 | cordon 后即可 --force 删除 Terminating Pod;脚本在强删、打标、报修和删 Slice 四步忽略返回码,并重建同名 Slice | 节点 NotReady 或 VM 已重置后才强删;原脚本会掩盖失败、重复报修,已替换为分步处置流程(见 3.5.1) | 强制删除 Pod |
| Q3.8、2.4 | Topic 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.4 | infra#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-01 | RQ-01 | 质量检测+压测+运维适配 B3 | 类似 DCGM EUD 的芯片级诊断工具与时长 | 客户问答表 |
| R-11 | RQ-30、RQ-31 | 质量检测+压测+运维适配 B4 | 硬件错误上报位置与错误码分级 | 客户问答表 |
| R-04 | RQ-07 | 质量检测+压测+运维适配 B5 | SDC 检测机制与工具 | 客户问答表 |
| R-04 | RQ-08 | 质量检测+压测+运维适配 B6 | 逐位一致性的四种情形 | 客户问答表 |
| R-01、R-02 | RQ-02 | 质量检测+压测+运维适配 B7 | ICI 带宽测试与硬件诊断工具 | 客户问答表 |
| R-05 | RQ-14 | 质量检测+压测+运维适配 B8 | libtpu、固件、运行时版本一致性 | 客户问答表 |
| R-01 | RQ-09 | 质量检测+压测+运维适配 D1 | Google 评论:客户需要 CHS 或 DCGM 类工具 | 客户问答表 |
| R-02、R-08、R-12、R-14 | RQ-05、RQ-16、RQ-35、RQ-42 | QnA B2 | 网络架构、集合通信基线、可观测性与故障定位(4 问) | 客户问答表 |
| R-01 | RQ-10 | QnA B5 | 压测、检测、监控、诊断能力总括 | 客户问答表 |
| R-09 | RQ-23 | QnA B6 | 服务器带外能力是否开放 | 客户问答表 |
| R-08、R-12 | RQ-29、RQ-36 | QnA B10 | RDMA 类监控与快慢节点检测 | 客户问答表 |
| R-06 | RQ-15 | Topic 1 B14 | KSM、cAdvisor、tpu-exporter 对标 | 客户问答表 |
| R-09 | RQ-33 | Topic 1 B17 | TPU 现有异常检测机制 | 客户问答表 |
| R-11 | RQ-31 | Topic 1 B18 | 错误码清单 | 客户问答表 |
| R-12 | RQ-34 | Topic 1 B19 | 常见故障类型与 MTBF | 客户问答表 |
| R-11 | RQ-32 | Topic 1 B26 | kubelet 日志参数(containerLogMaxSize) | 客户问答表 |
| R-06、R-09 | RQ-17、RQ-27 | Topic 1 B27 | 带内采集指令与硬件告警逻辑 | 客户问答表 |
| R-11 | RQ-38 | Topic 1 E18 | Google 待办:故障指标与定位专题(评论) | 客户问答表 |
| R-05 | RQ-13 | Topic 1 F20 | Pod 内 libtpu 通信条件判断 | 客户问答表 |
| R-06、R-12 | RQ-24、RQ-37 | Topic 1 H17 | Google 待办:指标接入与 straggler 检测(评论) | 客户问答表 |
| R-02 | RQ-05 | Topic4 B3 | 集合通信基线与验收方法 | 客户问答表 |
| R-08 | RQ-16 | Topic4 B4 | 租户侧 ICI/DCN 网络指标采集 | 客户问答表 |
| R-12、R-14 | RQ-35、RQ-42 | Topic4 B5 | 故障诊断案例与降级运行 | 客户问答表 |
| R-05 | RQ-11 | 调度+容错+指标采集 B14 | 对标 GPU 预检的 TPU 预检命令 | 客户问答表 |
| R-07 | RQ-18 | 调度+容错+指标采集 B15 | TPU 补充指标进展(16 项清单见指标补充 tab) | 客户问答表 |
| R-13 | RQ-40 | 调度+容错+指标采集 B19 | 通过 GKE 接口标记异常节点(续见 B20) | 客户问答表 |
| R-07 | RQ-18 | 指标补充 A2:G5 | DCGM 时钟类指标(4 项;另一 tab 有相同清单) | 客户问答表 |
| R-07 | RQ-19 | 指标补充 A6:G11 | DCGM PCIe 吞吐、宽度与代数(另见 A16:G17) | 客户问答表 |
| R-07 | RQ-20 | 指标补充 A12:G13 | DCGM 单比特 ECC 计数 | 客户问答表 |
| R-07 | RQ-21 | 指标补充 A14:G15 | DCGM 行重映射 | 客户问答表 |
| R-02、R-06 | RQ-06、RQ-22 | 客户问答表(另一 tab) | 见第 1 章对应原子需求 | 客户问答表 |
| R-09、R-15 | RQ-28、RQ-44 | GCP问题反馈 C3 | 客户现有告警分级与回归准入流程 | 客户问答表 |
| R-11、R-13 | — | 质量检测+压测+运维适配 D4 | Google 答复:fatal 与 non-fatal 错误的报修路径(评论) | 客户问答表 |
| R-06 | — | Topic 1 H14 | Google 答复:tpu-exporter 对应 Cloud Monitoring 与 device plugin 端点(评论) | 客户问答表 |
| R-06 | — | Topic 1 E14 | Google 初步答复:挑出的 19 项硬件与网络指标 | 客户问答表 |
| R-12 | — | Topic 1 H19 | Google 答复:常见故障类型排序(评论) | 客户问答表 |
| R-10、R-14 | — | QnA D3 | Google 答复:partition 与 Slice 故障状态、恢复通常 2 min 内、无 SLO(评论) | 客户问答表 |
| R-11 | — | Topic 1 H18 | Google 答复:TPU 无 XID 对应物(评论) | 客户问答表 |
| R-05 | — | 质量检测+压测+运维适配 D8 | Google 答复:libtpu 与 vfio-pci 解耦、版本钉定(评论) | 客户问答表 |
C.2 GitHub issue、评论与客户共享文档#
以下链接指向客户私有 GitHub 仓库(需访问权限)。其中 Google 侧编写、共享给客户的资料(基线文件、ICI 分轴带宽脚本、15 s 采集器配置、告警来源清单)不代表客户诉求。
| 需求 | 原子需求 | 来源 | 主题 | 链接 |
|---|---|---|---|---|
| R-01、R-03 | RQ-03、RQ-04 | infra#4 | EUD 式验收套件与同步脉冲压测诉求 | 客户仓库 infra#4 |
| R-05 | RQ-11 | infra#20 | 对标 GPU 预检的 TPU 检测脚本诉求 | 客户仓库 infra#20 |
| R-05 | RQ-13 | infra#24 评论 | Pod 内 libtpu 通信条件如何判断(客户追问) | 客户仓库 infra#24 评论 |
| R-05 | — | infra#24 评论 | Google 书面回复:Pod 网络模型与 8471、8431 端口 | 客户仓库 infra#24 评论 |
| R-07 | RQ-18 | infra#21 | 补齐对标 DCGM 的 TPU 指标(清单在客户问答表·指标补充 tab) | 客户仓库 infra#21 |
| R-09、R-15 | RQ-28、RQ-44 | infra#8 评论 | 客户告警分级与回归准入流程 | 客户仓库 infra#8 评论 |
| R-10、R-14 | RQ-25、RQ-45、RQ-46 | infra#8 评论 | 故障信息获取、hang 处置与自动踢除 | 客户仓库 infra#8 评论 |
| R-10 | RQ-25 | infra#27 | 故障信息推拉方式与 node 状态 | 客户仓库 infra#27 |
| R-10 | RQ-39 | infra#28 | partition 异常定位到 node | 客户仓库 infra#28 |
| R-10 | RQ-26 | infra#34 | 4 个故障信号接口诉求 | 客户仓库 infra#34 |
| R-13 | RQ-43 | infra#26 | 资源屏蔽粒度 | 客户仓库 infra#26 |
| R-13、R-15 | RQ-41 | infra#29 | 修复流程、修后验证与修复时长 | 客户仓库 infra#29 |
| R-05 | RQ-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-01 | TPUMS(accelerator-microbenchmarks) | v2.0 与 tpums CLI、benchmark 配置 | GitHub |
| C3-02 | TPUMS issue #145 | 上游功能请求:EUD 式套件与同步脉冲压测(open,RQ-03、RQ-04;另见 C.2 infra#4) | #145 |
| C3-03 | Cluster Health Scanner | 仓库 main 仍是 legacy v1(cluster_diag、Helm);0.3.x 只以镜像 gce-ai-infra/chs/chs:0.3.2 分发 | GitHub |
| C3-04 | tpu-info | 本地芯片状态 CLI | 文档、GitHub |
| C3-05 | TPU7x(Ironwood) | 芯片规格、HBM 192 GiB/chip、主机内存 | 文档 |
| C3-06 | TPU 机型 | tpu7x-standard-4t 规格 | 文档 |
| C3-07 | GKE 上的 Ironwood | GKE 最低版本 | 文档 |
| C3-08 | 在 GKE 中部署 TPU 工作负载 | 运行时指标端口 8431、worker 协调端口 8471 | Standard、Autopilot |
| C3-09 | 自定义 OS 镜像 | vfio-pci 绑定与 vBar agent | 文档 |
| C3-10 | GKE 已知问题 | tpu7x 芯片数上报问题与修复版本 | 文档 |
| C3-11 | 监控 TPU | Cloud Monitoring TPU 指标与 Beta 表 | 文档 |
| C3-12 | TPU 健康状态 | infra_health 与 Cloud Logging 健康原因 | 文档 |
| C3-13 | GKE TPU 故障排除 | tpu-device-plugin 日志查询 | 文档 |
| C3-14 | ML Diagnostics 工作负载监控 | 托管的性能下降与 hang 检测 | 文档 |
| C3-15 | COS 磁盘与文件系统 | 只读根分区与 noexec 挂载 | 文档 |
| C3-16 | 报告故障主机(GKE) | cloud.google.com/fault-behavior 标签与取值 | 文档 |
| C3-17 | gcloud report-host-as-faulty | 命令与 flag | 参考 |
| C3-18 | All Capacity 模式报修 | TPU VM 报修流程与时长 | 文档 |
| C3-19 | Jouppi 等,IEEE Micro 2026 | FBIST 与 VPU 硬件重放 | arXiv 2606.15870 |
| C3-20 | ML Workload Debugging Wiki | SDC 校验和不一致、ICI straggler、slice failure、Megascale hang、节点隔离、数据非确定性、ECC 错误、Terminating 卡住恢复 | SDC、ICI、slice、Megascale hang、隔离、非确定性、ECC、Terminating 恢复 |
| C3-21 | OpenXLA Megascale 调试流程 | hang 诊断摘要与 Data input stall | 文档 |
| C3-22 | OpenXLA 确定性 | 确定性边界(GPU 对照) | 文档 |
| C3-23 | Kubernetes 强制删除 Pod | 强删的前提与风险 | 文档 |
| C3-24 | ethtool netlink | TCP data split 是 ring 参数 | 文档 |
| C3-25 | GKE 中的 TPU | 多主机节点池中节点修复对整个 slice 的影响 | 文档 |
| C3-26 | GKE 节点系统配置 | kubelet containerLogMaxSize、containerLogMaxFiles | 文档 |
| C3-27 | 查看 GKE 维护事件 | 维护事件通知与日志 | 文档 |
| C3-28 | TPU All Capacity 维护事件 | TPU 维护事件日志 | 文档 |
| C3-29 | GKE Slice 对象 | Slice CRD 字段 | 文档 |
| C3-30 | TPU Goodput | 作业 Goodput 指标(BETA) | 文档 |
| C3-31 | TPU 故障排查 | libtpu 日志环境变量(TPU_STDERR_LOG_LEVEL 等) | 文档 |
| C3-32 | Logging 查询语言 | 日志过滤条件与 sample() | 文档 |
| C3-33 | Observability Analytics(原 Log Analytics) | 日志 SQL 分析 | 文档 |
| C3-34 | SQL 告警 | 基于 SQL 查询的日志告警 | 文档 |
| C3-35 | Cloud Monitoring PromQL | PromQL 查询与标签 | 文档 |
| C3-36 | 告警 snooze | 维护窗口内静默告警 | 文档 |
| C3-37 | AlertPolicy API | 告警策略字段 | 文档 |
| C3-38 | stackdriver_exporter | 把 Cloud Monitoring 指标导出给 Prometheus | GitHub |
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 残留”一行):
(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=2 | 2 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 |