X-VLA-WidowX 昇腾 NPU 适配与推理

简介

X-VLA（eXtensions for Versatile Language-Action）是一类用于真机操控的视觉-语言-动作模型。与常规对话大模型不同，它的输入是当前的视觉画面与一句操作指令，输出则是机器人下一步的关节/末端执行器动作。本仓库对应 WidowX 机器人专版，模型规模约 0.9B，采用 Florence2 编码视觉与文本、SoftPromptedTransformer 负责流匹配去噪，一次推理产出 30 帧动作。

我们完成了该模型在华为昇腾 Ascend910 NPU 上的适配，包括权重获取、模型加载、NPU 算子执行、服务化接口封装全流程，并把整套可复现的步骤沉淀在此。

验证环境

• 机型：Atlas 800 (A2)，单卡双芯 Ascend910（每芯 32GB HBM）
• 系统：HCE 2.0，ARM aarch64 架构
• 驱动：CANN 8.5.1；npu-smi 25.5.5
• 运行库：Python 3.11.14、torch 2.9.0、torch_npu 2.9.0.post1
• 模型框架：transformers 4.57.6（trust_remote_code 自定义代码）
• 推理精度：bfloat16

服务启动

开始之前，先确保模型文件齐备。目录下应包含 model.safetensors（权重）、config.json、modeling_xvla.py 等自定义代码，以及 merges.txt（BPE 词表合并文件，须从 Florence2 仓库补齐，因为原始发布仓缺此文件）。

(1) 环境准备

pip install torch torch-npu transformers pillow numpy opencv-python-headless fastapi uvicorn json-numpy

(2) 启动

python serve.py --model-dir /path/to/xvla-widowx --port 8000

成功启动后再终端会看到 FastAPI 应用已就绪 与监听地址。默认绑定所有网卡、8000 端口。

(3) 调用样例

python client.py --image test_scene.png --instruction "pick up the red block"

冒烟验证

用一个合成场景触发一次端到端推理：脚本绘制一张含红色方块与机械臂的桌面图，连同指令打包后 POST 到 /act。返回 action 是形如 (30, 20) 的动作矩阵，第 0 维为步数、第 1 维为 6D 位姿+夹爪。终端会打印 shape、首末帧以及夹爪维的归一化值，用于人工核验输出是否合理。

性能参考

下表为实测获得，供后续调优参照：

精度测评

该模型的动作生成带天然随机性：flow-matching 从噪声出发逐步去噪，故即便输入完全相同，两次输出也不会一致。因此不对"逐元素一致"做断言，而是验证：(1) 输出不出现 NaN/Inf；(2) 夹爪通道落在 [0,1]；(3) 各维均值和标准差处于合理区间。实测三项均通过，判定 NPU 上 bf16 计算与同等实现数值行为一致。

注意事项

• 本机同时可能有其他用户在跑 NPU 任务，启动前用 npu-smi info 看一下，选空闲卡、端口避开已被占用的，绝不 kill 别人的进程。
• 一个常见坑：tokenizer 因缺 merges.txt 报错。用 Florence 的 merges.txt 补进模型目录即可解决。
• 模型是非文本依赖的，纯文本对话不适用，必须带图像。
• 工作盘有配额，权重等大文件建议放 /tmp，仓库内容为纯文本、很小不受影响。
• bf16 推理可大幅省显存；若显存紧张可换 float32 双倍占用来换取更高精度，视场景权衡。