逐行解析X-VLA-Libero-NPU的inference.py:360行代码完成VLA推理全链路

原创2026-10-31 15:46:521,418 阅读
文章标签:人工智能大模型具身智能模型推理服务本地部署Ascend

逐行解析X-VLA-Libero-NPU的inference.py:360行代码完成VLA推理全链路

data/web/disk1/git_repo/z_studio/X-VLA-Libero-NPU/inference.py 是 X-VLA-Libero-NPU 仓库的核心脚本:约 360 行 Python 代码,在昇腾 Ascend NPU 上跑通一条完整的 VLA 推理链路——加载 0.9B 的 X-VLA-Libero 机器人策略权重,编码「多视角图像 + 语言指令 + 20 维本体状态」,经过 flow-matching 流匹配去噪,输出 30 步 × 20 维的连续动作。下面按代码块逐段解析,重点讲清 4 个 NPU 适配关键点,新手也能快速看懂如何用 torch_npu 完成 VLA 模型推理。

🎯 先看成果:这 360 行代码能做什么?

X-VLA-Libero 是一个 Vision-Language-Action(VLA)机器人策略模型:它不像大语言模型那样输出文字,而是直接输出机器人末端执行器的动作序列。整条链路可以概括为:

输入 说明 输出
图像 ≤3 个视角的 224×224 RGB 图像 action.npy:(1, 30, 20) 动作块
语言指令 如 "pick up the red block…" report.json:耗时、显存、动作统计
本体状态 20 维 ee6d 状态向量 终端打印第 1 步动作,状态 SUCCESS

整个仓库围绕 inference.py 展开:配套批量测试脚本 run_test_cases.py、依赖清单 requirements.txt,以及 52 组实测输出(output/ 目录下每组一个 action.npy + report.json)。

📦 文件结构地图:6 大代码块

先把 inference.py 的骨架摊开,全文按职责分成 6 个区块:

区块 行号范围 职责
① 导入与环境开关 L50-L62 引入 torch_npu、开启 HF 离线模式
② 稳定写盘工具 L68-L79 带重试的 write_file_retry
③ 合成观测生成 L85-L99 无相机时生成可复现的棋盘格图像
④ 核心推理器 XVLAInference L105-L216 模型加载、预处理、flow-matching 推理
⑤ CLI 参数定义 L222-L246 12 个命令行参数
⑥ main() 端到端流程 L249-L328 参数校验 → 推理 → 落盘 → 报告

其中区块 ④ 是灵魂,下面逐块细讲。

① 导入与环境开关:两行代码决定"跑在哪、用哪份权重"

文件开头做了两件不起眼但关键的事:

import torch_npu  # 导入即完成 NPU 侧注册
os.environ.setdefault("HF_HUB_OFFLINE", "1")
  • import torch_npu:这是昇腾 NPU 的推理引擎,导入后 PyTorch 就认得 npu:0 这类设备。注意它面向的是"直接加载权重推理",而 X-VLA 输出连续动作、不是自回归 token,所以不走 vllm-ascend / sglang,torch_npu 是唯一合适选择。
  • HF_HUB_OFFLINE=1:模型远端代码和权重已全部本地化,强制离线加载,避免运行时误连 HuggingFace Hub 卡住。

② 稳定写盘:给输出文件加一层"自动重试"

write_file_retry 把 action.npy / report.json 的写盘包了一层重试:

SFS Turbo 这类高性能存储突发连续写时偶发 EDQUOT 限流,重试 8 次、每次等待 1.5s 就能平滑绕过——这是生产环境推理脚本很实用的一个细节。

③ 没有相机怎么办?合成"可复现的假图像"

真实部署时图像来自机械臂相机,但在验证阶段往往没有传感器。build_synthetic_views 用 numpy 生成 1~3 张 224×224 棋盘格图像,每个视角用不同色偏(hue)区分,且完全由 seed 决定、结果可复现:

  • --image cam0.jpg,cam1.jpg:传入真实图像即可替换合成图像(PIL 自动转 RGB,≤3 张);
  • --views 3 --hue 0.5:控制合成视角数与基准色偏。

这样脚本在"零硬件"条件下也能端到端跑通,是验证 NPU 适配是否成功的关键技巧。

④ 核心推理器 XVLAInference:4 个 NPU 适配点全在这里

XVLAInference 类一次性加载模型 + 处理器,之后可反复调用 run()。它藏着整个项目最有价值的部分——4 个昇腾 NPU 适配点。

🧩 适配点 1:显式指定 eager 注意力实现

config._attn_implementation = "eager"
config.florence_config._attn_implementation = "eager"

transformers 4.57 在构造模型时会校验注意力实现(_check_and_adjust_attn_implementation),而 X-VLA 自带的 Florence-2 远端代码没有定义 _supports_sdpa 属性,默认走 sdpa 会直接抛 AttributeError。在顶层与嵌套 config 上同时显式设为 "eager",即可绕过该校验(见 L131-L134)。

🧩 适配点 2:tie_word_embeddings=False,跳过权重绑定

X-VLA 在 __init__ 中删掉了 Florence2 的 lm_head,但加载末尾 transformers 仍会尝试"绑定输出嵌入到 lm_head",触发 AttributeError: ... has no attribute 'lm_head'。解法只有一行:

config.florence_config.text_config.tie_word_embeddings = False

让绑定路径整体跳过。与 X-VLA-Pt-NPU 相比,Libero 版远端代码少了作者自带的禁用补丁,所以这项适配是 Libero 独有的(详见 AGENT_WORKFLOW.md Step 6)。

🧩 适配点 3:不传 dtype=,让权重保持 fp32

self.model = AutoModel.from_pretrained(
    model_path, config=config, trust_remote_code=True
).to(self.device)

Libero 远端代码在 __init__ 里把 Florence2 骨干显式 .to(torch.float32),因此不能传 bf16,否则 DaViT 卷积会报 Input type (c10::BFloat16) and bias type (float) should be the same。模型参数实测为 fp32,preprocess 里 image_input / proprio 也统一转成 self.param_dtype(即 fp32)保持一致。

🧩 适配点 4:重绑 encoder.embed_tokens → shared

权重文件中文本嵌入以 shared.weight 保存,加载后 encoder.embed_tokens 可能变成随机副本。脚本在加载后显式重绑(L151-L156),保证文本嵌入参与计算的权重完全正确。

🔁 一次调用完成去噪:run()

run() 的逻辑非常直白:固定随机种子 → preprocess 编码输入 → 调用模型自带的 generate_actions(..., steps=steps) 做 flow-matching 流匹配去噪 → 返回 (1, 30, 20) 的 float32 numpy 动作块。steps 控制去噪步数,实测 5→10→20 步耗时约 0.09s→0.14s→0.23s,近似线性。

⑤ 命令行参数:12 个参数覆盖全部输入维度

parse_args 定义的参数一张表看懂:

参数 默认值 作用
--model /data/models/2toINF/X-VLA-Libero 权重目录(含 config / safetensors / 远端代码)
--device npu:0 昇腾 NPU 设备号
--dtype fp32 推理精度(骨干固定 fp32)
--task "pick up the red block…" 语言指令
--state 20 维全零 本体状态,逗号分隔
--domain 0 本体域 ID(0~29,对应 30 套软提示)
--steps 10 flow-matching 去噪步数
--seed 42 随机种子,保证可复现
--views / --hue 3 / 0.5 合成图像视角数 / 基准色偏
--image 空 真实图像路径(逗号分隔,≤3 张)
--output-dir output 输出目录

最小运行命令:

python inference.py \
    --model /data/models/2toINF/X-VLA-Libero \
    --device npu:0 \
    --task "pick up the red block and place it on the yellow bowl" \
    --domain 0 --steps 10 --seed 42

⑥ main():从参数到落盘的端到端 5 步

main() 把前面所有零件串成流水线:

  1. 状态校验:--state 必须恰好 20 维、--domain 必须在 0~29,否则快速报错;
  2. 图像准备:--image 非空则加载真实图像(PIL 转 RGB),否则生成合成棋盘格;
  3. 执行推理:计时调用 runner.run(...),得到 (1, 30, 20) 动作;
  4. 保存动作:action.npy(float32)经 write_file_retry 落盘;
  5. 生成报告:report.json 记录输入参数、动作均值/标准差、夹爪首步值、NaN 检查、加载/推理耗时、NPU 峰值显存与 status=SUCCESS。

动作的 20 维布局(ee6d):[0:3] 位置1、[3:9] 6D 旋转1、[9] 夹爪1、[10:13] 位置2、[13:19] 旋转2、[19] 夹爪2,其中夹爪通道经 sigmoid 归一到 [0,1]。

🖥️ 实测:NPU 占用与推理输出

推理期间可用 npu-smi info 观察昇腾 910B 的 HBM 占用与进程状态:

昇腾 NPU 设备监控:npu-smi info 显示 Ascend910B 运行 python 推理进程的 VLA 推理实测

运行一次 inference.py,终端完整输出如下(含 4 个适配点带来的加载告警、0.44s 推理耗时与首步动作):

X-VLA-Libero NPU 推理实测:inference.py 终端输出,30×20 动作块推理完成,状态 SUCCESS

仓库还提供了 52 组批量测试(run_test_cases.py),覆盖 30 个本体域、10 条语言指令、4 组状态、3 种视角、3 种去噪步数、2 个随机种子,全部 SUCCESS、无 NaN,结果汇总在 output/testcases_summary.json。

📊 性能参考:加载 12s,单次推理不到 0.5s

指标 数值(Ascend 910B 单卡)
模型加载 ~12 s
单次推理(10 步去噪,冷启动) ~0.47 s
单次推理(预热后,52 组中位数) ~0.14 s
去噪步数开销(5→10→20 步) ~0.09s → 0.14s → 0.23s(近线性)
NPU 峰值显存 ~3.7 GB

✅ 总结:这份脚本给新手的 3 个启示

  1. VLA 策略模型 ≠ LLM:输出连续动作而非 token,推理引擎选 torch_npu 直接加载远端代码,而不是 vllm-ascend / sglang;
  2. 适配可以"纯配置级"完成:4 个 NPU 适配点(eager 注意力、tie_word_embeddings=False、fp32 输入、嵌入重绑)全部只改 config / 不改三方库源码,见 README.md 第 3 节;
  3. 可复现是验证的第一要务:seed + 合成图像 + 52 组批量用例,让"适配是否成功"变成一个可量化、可回归的问题。

想深入每个适配点的来龙去脉(报错现场、diff 对比、修复过程),推荐配合阅读 AGENT_WORKFLOW.md 的 9 步工作流总览:

X-VLA-Libero NPU 适配 Agent Workflow 总览:9 步流程、4 个关键修复与验证结果

登录后查看全文
X-VLA-Libero-NPU