版本：v26.06

InferNex前置校验工具 ​

特性介绍 ​

InferNex前置校验工具（infernex-checker）是一个独立的CLI（Command-Line Interface，命令行界面）工具，用于在执行helm install部署InferNex之前对目标环境进行系统性验证。该工具通过检测硬件、K8s集群及业务配置与环境匹配的关键环节，将环境问题的识别从运行时提前至部署前，有效降低部署失败风险并提升系统稳定性。

应用场景 ​

  • 首次部署前全量检查：在首次部署InferNex前运行全量校验，工具依次验证硬件、K8s集群以及业务配置与环境匹配情况。检查完成后，报告显示所有环节正常，确认环境就绪后执行helm install完成部署。
  • 部署失败快速定位：首次部署前运行全量校验时，硬件层出现致命错误（如所有节点NPU驱动未正确部署），工具立即停止并输出详细错误描述和修复建议。按照建议完成修复后，重新运行全量校验，剩余环节顺利通过，最终确认环境就绪并完成部署。
  • 按需分层检查：按照用户需要支持仅某一层级的校验（硬件、K8s或业务配置与环境），无需重复校验或者校验不关注的部分，提高校验效率。

能力范围 ​

  • 系统性环境校验：在helm install前对InferNex部署环境进行系统性校验，覆盖硬件、K8s集群及业务配置与环境匹配的关键环节。
  • 灵活的执行模式：支持全量校验（硬件 → K8s → 业务配置与环境）或按层级执行（用户可选择仅运行硬件检查、K8s检查或业务配置与环境匹配相关校验）。
  • 结构化校验报告：输出终端报告和JSON格式结果文件，对每个失败项提供详细错误描述与修复建议，便于用户快速定位问题。

实现原理 ​

逻辑视图 ​

infernex_checker_logic_view

infernex-checker内部划分为以下模块：

表1 infernex-checker模块说明

模块名功能
HardwareChecker实现硬件层检查，对外提供infernex-checker hardware --nodes命令。
K8sChecker实现K8s集群状态检查，对外提供infernex-checker k8s --nodes命令。
ConfigEnvChecker实现业务配置与环境匹配校验，对外提供infernex-checker config-env --nodes --values命令。
AllChecker按硬件 → K8s → 业务配置与环境顺序依次调用上述三个Checker，对外提供infernex-checker all --nodes --values命令。
Parser解析CLI参数及输入文件：通过--nodes参数读取节点信息文件，通过--values参数读取InferNex部署配置文件。
NodeExecutor节点访问统一入口，封装SSH命令执行和Kubernetes API调用。
Log记录工具运行日志（SSH连接、命令执行、异常堆栈等）。
Output整理并呈现校验结果，生成终端报告与JSON结果文件。

校验流程 ​

硬件层校验流程

  1. 阶段1 - 单节点校验（多节点并发执行）。

    • H-01：NPU驱动固件安装状态
    • H-02：Ascend Device Plugin安装状态
    • H-03：NPU型号检查
    • H-04：NPU可用数量统计
    • H-05：主机关键文件与目录检查
    • H-06：hccn.conf配置正确性（仅910系列）
    • H-07：单机HCCS通信测试（仅910系列）

  2. 阶段2 - 跨节点校验（需至少2个910系列节点通过单机校验）。

    • H-08：跨机卡侧RoCE RDMA通信测试

K8s层校验流程

  • K-01：集群CoreDNS检查（失败则终止后续K8s层校验）
  • K-02：节点就绪状态（所有节点均不Ready则终止后续K8s层校验）
  • K-03：节点污点检查
  • K-04：节点可用资源统计

业务配置与环境层校验流程

  • B-01：模型缓存路径可用性（目录存在性与可写性）
  • B-02：Driver与CANN版本兼容性

校验中断逻辑 ​

表2 校验中断逻辑说明

触发条件中断范围说明
H-01~H-07中任意一项失败跳过该节点后续所有硬件校验项节点内串行执行，单节点失败不影响其他节点并发执行。
H-03结果为非910系列跳过该节点H-06~H-08HCCS/RoCE相关校验仅适用于910系列。
通过单机校验的910系列节点少于2个跳过H-08跨机通信校验跨机校验至少需要2个节点。
全量模式下无节点通过硬件层校验终止K8s层和业务配置与环境层无节点可继续，后续层整体终止。
K-01失败终止K8s层后续校验DNS不可用时节点和资源检查结果不可靠。
K-02所有节点均非Ready终止K8s层后续校验无可用节点，后续校验无意义。
B-01失败跳过该节点后续所有业务校验项节点内串行执行，单节点失败不影响其他节点。

安装 ​

前提条件 ​

硬件要求 ​

infernex-checker本身对硬件环境无特殊要求。

软件要求 ​

  • Kubernetes v1.33.0及以上版本。

网络要求 ​

  • 运行infernex-checker的主机能够通过SSH访问所有目标节点。
  • 运行infernex-checker的主机能够访问Kubernetes API Server。

权限要求 ​

  • 具备目标节点的SSH登录权限（用户名、密码或密钥）。
  • 具备K8s集群的访问权限（通过kubeconfig配置文件）。

开始安装 ​

二进制安装 ​

  1. 进入用于存放infernex-checker的目录。

    bash
    cd <目标目录>

  2. 根据主机架构下载对应的二进制文件。

    • Linux AMD64：
      bash
      wget https://static.openfuyao.cn/openFuyao/infernex/releases/download/release-26.6.0/bin/linux/amd64/infernex-checker
    • Linux ARM64：
      bash
      wget https://static.openfuyao.cn/openFuyao/infernex/releases/download/release-26.6.0/bin/linux/arm64/infernex-checker

  3. 添加执行权限。

    bash
    chmod +x infernex-checker

  4. 验证安装。

    bash
    ./infernex-checker --help

使用InferNex前置校验工具 ​

前提条件 ​

  • 已完成infernex-checker的安装。
  • 已准备节点信息文件（nodes.yaml）。
  • 已准备InferNex部署配置文件（values.yaml）（业务配置与环境层校验需要）。
  • 已配置K8s访问凭证（kubeconfig）。

准备节点信息文件 ​

创建nodes.yaml文件，填写目标节点的SSH连接信息：

yaml
nodes:
  - name: node-01
    ip: 192.168.1.10
    port: 22
    user: root
    # 使用密码认证
    password: "your-password"
  - name: node-02
    ip: 192.168.1.11
    port: 22
    user: root
    # 使用密钥认证
    keyFile: "/home/user/.ssh/id_rsa"

参数说明：

  • name：节点名称，需与K8s集群中的节点名称一致。
  • ip：节点IP地址。
  • port：SSH端口，默认22。
  • user：SSH登录用户名。
  • password：SSH登录密码（与keyFile二选一）。
  • keyFile：SSH私钥文件路径（与password二选一）。

执行全量校验 ​

全量校验按硬件层 → K8s层 → 业务配置与环境层顺序依次执行。

bash
infernex-checker all --nodes nodes.yaml --values values.yaml --output

参数说明：

  • --nodes：节点信息文件路径（必填）。
  • --values：InferNex部署配置文件路径（必填）。
  • --kubeconfig：Kubernetes配置文件路径（可选，默认使用~/.kube/config）。
  • --output：JSON结果文件输出路径（可选，不指定则不生成JSON结果文件）。
  • --log：日志文件输出路径（可选，默认为./infernex-checker.log）。

输出示例：

=== InferNex Checker ===

[Hardware Layer - Single Node: n2]
  ✅ H-01  NPU driver and firmware installed
  ✅ H-02  Ascend Device Plugin Running and NPU resource registered
  ✅ H-03  NPU model: 910B4
  ℹ️ H-04  NPU available: 4/8
  ✅ H-05  Key host files and directories are complete
  ✅ H-06  hccn.conf configuration is correct
  ✅ H-07  Step 1: NIC TLS switch states are consistent (no_cert)
  ✅ H-07  Step 2: Single-node NIC-to-NIC connectivity is normal

[Hardware Layer - Cross-Node]
  ⏭️ H-08  Only 1 910-series node(s) passed single-node checks, skipping cross-node check (at least 2 required)

[K8s Layer]
  ✅ K-01  CoreDNS Running, service domain names are resolvable
  ✅ K-02  n2 Ready
  ✅ K-03  n2 has no taints
  ℹ️ K-04  n2  Allocatable resources: CPU 256, Memory 1055115824Ki
    -> Please confirm this meets Infernex deployment requirements; if sufficient, consider releasing occupied resources or adjusting workloads

[Config-Env Layer: n2]
  ✅ B-01  /home/llm_cache directory exists and is writable
  ✅ B-02  Driver 25.5.0 is compatible with image v0.13.0

────────────────────────────────
Result: 12 passed, 0 failed, 2 info

ℹ️ Info items:
  H-04 [n2]  NPU available: 4/8
  K-04 [n2]  n2  Allocatable resources: CPU 256, Memory 1055115824Ki

✅ Environment check passed, ready to deploy InferNex

执行分层校验 ​

仅执行硬件层校验 ​

bash
infernex-checker hardware --nodes nodes.yaml

仅执行K8s层校验 ​

bash
infernex-checker k8s --nodes nodes.yaml

仅执行业务配置与环境层校验 ​

bash
infernex-checker config-env --nodes nodes.yaml --values values.yaml

查看JSON结果文件 ​

通过--output参数指定JSON结果文件路径后，校验完成时会生成该文件，包含详细的校验结果：

json
{
   "summary": {
      "total": 14,
      "passed": 12,
      "failed": 0,
      "info": 2
   },
   "hardware": {
      "nodes": [
         {
            "name": "n2",
            "status": "passed",
            "is910Series": true,
            "checks": [
               {
                  "id": "H-01",
                  "status": "passed",
                  "message": "NPU driver and firmware installed"
               },
               {
                  "id": "H-02",
                  "status": "passed",
                  "message": "Ascend Device Plugin Running and NPU resource registered"
               },
               {
                  "id": "H-03",
                  "status": "passed",
                  "message": "NPU model: 910B4"
               },
               {
                  "id": "H-04",
                  "status": "info",
                  "message": "NPU available: 4/8",
                  "detail": {
                     "available": 4,
                     "total": 8,
                     "unhealthy": null
                  }
               },
               {
                  "id": "H-05",
                  "status": "passed",
                  "message": "Key host files and directories are complete"
               },
               {
                  "id": "H-06",
                  "status": "passed",
                  "message": "hccn.conf configuration is correct"
               },
               {
                  "id": "H-07",
                  "status": "passed",
                  "message": "Step 1: NIC TLS switch states are consistent (no_cert)"
               },
               {
                  "id": "H-07",
                  "status": "passed",
                  "message": "Step 2: Single-node NIC-to-NIC connectivity is normal"
               }
            ]
         }
      ],
      "cross_nodes": [
         {
            "id": "H-08",
            "status": "skipped",
            "message": "Only 1 910-series node(s) passed single-node checks, skipping cross-node check (at least 2 required)"
         }
      ]
   },
   "k8s": {
      "status": "passed",
      "checks": [
         {
            "id": "K-01",
            "status": "passed",
            "message": "CoreDNS Running, service domain names are resolvable"
         },
         {
            "id": "K-02",
            "status": "passed",
            "message": "n2 Ready"
         },
         {
            "id": "K-03",
            "status": "passed",
            "message": "n2 has no taints"
         },
         {
            "id": "K-04",
            "status": "info",
            "message": "n2  Allocatable resources: CPU 256, Memory 1055115824Ki",
            "suggestion": "Please confirm this meets InferNex deployment requirements; if insufficient, consider releasing occupied resources or adjusting workloads",
            "detail": {
               "cpu_allocatable": "256",
               "memory_allocatable": "1055115824Ki",
               "node": "n2"
            }
         }
      ]
   },
   "config_env": {
      "status": "passed",
      "checks": [
         {
            "id": "B-01",
            "node": "n2",
            "status": "passed",
            "message": "/home/llm_cache directory exists and is writable"
         },
         {
            "id": "B-02",
            "node": "n2",
            "status": "passed",
            "message": "Driver 25.5.0 is compatible with image v0.13.0",
            "detail": {
               "driver_version": "25.5.0"
            }
         }
      ]
   }
}
在GitCode上查看源文件

遵循 木兰宽松许可证第2版（MulanPSL2）

版权所有 © 2026 openFuyao 保留一切权利ICP备案号：粤A2-20044005号-306粤公网安备44030002007300号
隐私政策法律声明关于cookies
隐私政策法律声明关于cookies
遵循木兰宽松许可证第2版（MulanPSL2）
版权所有 © 2026 openFuyao 保留一切权利
粤公网安备44030002007300号ICP备案号：粤A2-20044005号-306