逐行解析X-VLA-Libero-NPU的inference.py:360行代码完成VLA推理全链路
逐行解析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() 把前面所有零件串成流水线:
- 状态校验:
--state必须恰好 20 维、--domain必须在 0~29,否则快速报错; - 图像准备:
--image非空则加载真实图像(PIL 转 RGB),否则生成合成棋盘格; - 执行推理:计时调用
runner.run(...),得到(1, 30, 20)动作; - 保存动作:
action.npy(float32)经write_file_retry落盘; - 生成报告: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 占用与进程状态:
运行一次 inference.py,终端完整输出如下(含 4 个适配点带来的加载告警、0.44s 推理耗时与首步动作):
仓库还提供了 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 个启示
- VLA 策略模型 ≠ LLM:输出连续动作而非 token,推理引擎选 torch_npu 直接加载远端代码,而不是 vllm-ascend / sglang;
- 适配可以"纯配置级"完成:4 个 NPU 适配点(eager 注意力、
tie_word_embeddings=False、fp32 输入、嵌入重绑)全部只改 config / 不改三方库源码,见 README.md 第 3 节; - 可复现是验证的第一要务:seed + 合成图像 + 52 组批量用例,让"适配是否成功"变成一个可量化、可回归的问题。
想深入每个适配点的来龙去脉(报错现场、diff 对比、修复过程),推荐配合阅读 AGENT_WORKFLOW.md 的 9 步工作流总览:


