m0_63918125/X-VLA-WidowX
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

X-VLA-WidowX on Ascend NPU (torch_npu 2.9.0.post1)

1. 简介

本文档记录 2toINF/X-VLA-WidowX(X-VLA 跨本体 Vision-Language-Action 策略模型,WidowX 单臂机器人 checkpoint)在华为昇腾 Ascend NPU 上的适配与真机验证结果。

  • 结构:Florence-2-large 编码器(DaViT 视觉 + BART 文本编码器)作为视觉-语言骨干 + SoftPromptedTransformer(24 层、flow-matching 动作去噪器、按本体注入 soft-prompt)动作头。
  • 参数量:≈0.88 B;dtype 全程 float32。
  • 任务:机器人操作策略(robotics / VLA)。输入 = 3 路相机图像 + 语言指令(+ 本体 proprio 状态 + domain_id 本体编号),输出 = 动作块 [B, num_actions=30, dim_action=20](ee6d 模式:xyz+6D 旋转+夹爪,夹爪通道 idx 9/19 经 sigmoid 落入 (0,1))。
  • 本 checkpoint 为 WidowX 单臂:真机推理中 arm0(通道 idx 0–9)为有效动作,arm1(通道 idx 10–19)近似为 0(单臂本体仅驱动一条臂),与模型定位一致。dim_action / num_actions / num_domains 在运行时从 model.action_space 与 model.config 读取,不硬编码。

适配要点:

  • 加载走 trust_remote_code=True 的 AutoModel + AutoProcessor(自定义架构 xvla)。
  • Florence-2 兼容补丁:随附 modeling_florence2.py 把 _supports_sdpa 写成读取 self.language_model 的 property,在 transformers>=4.5x 的 super().__init__() 阶段该子模块尚未建立 → AttributeError;本适配在实例化前把它改写为普通类属性 True。
  • get_output_embeddings 兼容补丁:XVLA.__init__ 会 del 掉 Florence2 语言骨干的 lm_head/decoder(编码器-only 用法),但 transformers>=4.5x 的 from_pretrained 仍会调用 tie_weights() → get_output_embeddings() → self.lm_head,lm_head 已被删除 → AttributeError;本适配把 Florence2LanguageForConditionalGeneration.get_output_embeddings 覆盖为「无 lm_head 时返回 None」,使 tie_weights 安全跳过。
  • 推理即 flow-matching 迭代去噪(默认 steps=10);无 flash-attn 依赖,内部动作 Transformer 使用 F.scaled_dot_product_attention,NPU 直跑。
  • 全程 float32、HF32 关闭以保证可复现。

相关获取地址:

  • 权重下载地址(HuggingFace):https://huggingface.co/2toINF/X-VLA-WidowX
  • 权重下载地址(GitCode 镜像):https://ai.gitcode.com/hf_mirrors/2toINF/X-VLA-WidowX
  • 论文:https://arxiv.org/abs/2510.10274

2. 验证环境

组件版本
CANN8.5.1
torch2.9.0+cpu
torch-npu2.9.0.post1
transformers4.57.6
numpy1.26.4
硬件Ascend 910 (65GB HBM) · npu:0

3. 环境准备与权重获取

export PATH=/usr/local/python3.11.14/bin:$PATH   # 使用带 torch/torch_npu 的 3.11 解释器
pip install --no-deps fastapi uvicorn json_numpy opencv-python-headless   # 见 requirements.txt

权重由 inference.py 自包含拉取(HF 镜像,model.safetensors 约 3.5 GB),缓存到 ~/.cache/models/X-VLA-WidowX/。 若手动下载:

from huggingface_hub import snapshot_download
snapshot_download("2toINF/X-VLA-WidowX", local_dir="~/.cache/models/X-VLA-WidowX",
                  ignore_patterns=["*.h5","*.msgpack","*.ot","tf_model*","flax_model*","*.onnx","*.tflite","*.mp4"])

4. 推理运行

flock -w 7200 /tmp/npu_card0.lock bash -c '
  export PATH=/usr/local/python3.11.14/bin:$PATH
  ASCEND_RT_VISIBLE_DEVICES=0 ASCEND_CACHE_PATH=/tmp/ascend_cache_X-VLA-WidowX \
  ASCEND_PROCESS_LOG_PATH=/tmp/ascend_log ASCEND_WORK_PATH=/tmp/ascend_work \
  python inference.py --device npu'

Demo 输入为合成 3 路相机图像(np.random.default_rng(0))+ 指令 "pick up the object" + 中性 proprio + domain_id=0。

5. Smoke 验证(NPU 真机 stdout)

[X-VLA-WidowX] device=npu:0 dtype=torch.float32
[load] params=0.879B  action_mode=ee6d  dim_action=20  num_actions=30  num_domains=30
[input] input_ids(1, 50), image_input(1, 3, 3, 224, 224), image_mask(1, 3), domain_id(1,), proprio(1, 20)

[OUTPUT] action chunk shape: (1, 30, 20) (batch, num_actions=30, dim_action=20)
[OUTPUT] action[0, t=0]:
         [0.0139, -0.0202, 0.0031, 0.2132, 0.0552, -0.0539, 0.1831, 0.0041, 0.0327, 0.9819, 0.0001, 0.0002, 0.0002, 0.0001, 0.0004, -0.0001, -0.0007, -0.0, -0.0006, 0.0]
[OUTPUT] gripper channels (sigmoid) idx 9/19: 0.9819 / 0.0000
[OUTPUT] chunk stats: mean=0.1516 std=0.3192 min=-0.3698 max=0.9865

动作块形状 [1, 30, 20] 与 ee6d 定义一致;夹爪通道落在 (0,1)。arm0(idx 0–9)为有效动作、夹爪 0.9819;arm1(idx 10–19)近似 0,符合 WidowX 单臂 checkpoint 只驱动一条臂的特性。

6. 性能参考(NPU 真机,float32,steps=10)

warmup 5 次(剔除首帧编译),计时 20 次;单样本一次完整 flow-matching 去噪为一个动作块。

指标数值
avg145.69 ms
min143.23 ms
max149.05 ms
p50144.11 ms
p90148.45 ms
p95148.70 ms
吞吐6.86 chunks/s
峰值 HBM3541.67 MB

7. 精度评测(三道加载门禁 + Gate-3 三证)

无监督真值(VLA 策略),采用「确定性 + 结构性 + 响应性」三证。

Gate 1(加载完整性):missing=0,unexpected=0,mismatched=0 → 0/0/0(本 checkpoint 加载完整,无 tied 死参告警)。

Gate 2(配置落地):config.json 全部关键 key 落到 model.config 实例,逐项一致(action_mode=ee6d、num_actions=30、hidden_size=1024、depth=24、num_heads=16、num_domains=30、len_soft_prompts=32、florence.projection_dim=1024 …)→ ALL OK。

Gate 3(无 GT 三证,torch.manual_seed+torch.npu.manual_seed_all 固定内部去噪噪声):

证据结果
决定性 ×2(bit-exact)maxdiff = 0.00e+00(两次运行逐元素完全相等)
结构性全部有限;夹爪通道 sigmoid ∈ (0,1)([0.000, 0.979]);非夹爪通道 `
轨迹平滑性(时间维 TV,越小越平滑)预训练 TV=0.0097 vs 随机初始化 TV=0.0568(5.9× 更平滑 → 预训练学到连贯轨迹)
指令响应性换指令 |Δ|_mean=0.0205、换图像 |Δ|_mean=0.0047(预训练对语义输入敏感)
预训练 vs 随机初始化同输入 |Δ|_mean=0.2933 显著区分

结论:预训练权重在结构性(有界夹爪、平滑轨迹)与决定性上决定性胜出随机初始化对照。

8. 适配截图

  • 适配流程
  • NPU 设备调用
  • 模型结果

9. 注意事项

最易踩的坑:Florence-2 骨干在新版 transformers 下加载即崩,且触发点有两处。

  • 现象一:AutoModel.from_pretrained(..., trust_remote_code=True) 直接抛 AttributeError: 'Florence2ForConditionalGeneration' object has no attribute '_supports_sdpa'。
    • 根因:随附 modeling_florence2.py 把 _supports_sdpa/_supports_flash_attn_2 写成读取 self.language_model.* 的 property;transformers>=4.5x 在基类 __init__ 阶段就访问该属性,而此时 language_model 尚未构建。不是 权重损坏、也不是 NPU 相关。
    • 处理:实例化前把这些类的 _supports_sdpa/_supports_flash_attn_2 覆盖为普通类属性 True(见 inference.py::_patch_florence)。
  • 现象二:加载在 model.tie_weights() 阶段抛 AttributeError: 'Florence2LanguageForConditionalGeneration' object has no attribute 'lm_head'(栈顶在 modeling_utils.py ... get_output_embeddings -> return self.lm_head)。
    • 根因:XVLA.__init__ 显式 del 掉 Florence2 语言骨干的 lm_head 与 decoder(编码器-only 用法),但 transformers>=4.5x 的 from_pretrained 仍会调用顶层 tie_weights() → get_output_embeddings() → self.lm_head。
    • 处理:_patch_florence 里把 Florence2LanguageForConditionalGeneration.get_output_embeddings 覆盖为「无 lm_head 时返回 None」,tie_weights 便安全跳过(本 WidowX checkpoint 因此 Gate 1 为 0/0/0)。
  • 注意:不要对顶层 XVLA 传 attn_implementation="sdpa"——XVLA 未声明 SDPA 支持会报另一处 ValueError;内部动作 Transformer 本就无条件用 F.scaled_dot_product_attention,无需该参数。

其余事项:

  1. 内部噪声决定确定性:generate_actions 内部用 torch.randn 采样初始噪声,复现/门禁前需同时 torch.manual_seed 与 torch.npu.manual_seed_all 固定,否则每次输出不同(并非 NPU 非确定性)。
  2. dtype:config 声明 float32,全程按 float32 加载与推理;HF32 关闭(torch.npu.conv/matmul.allow_hf32=False)保证可复现。
  3. 权重下载:model.safetensors 约 3.5 GB,经 HF 镜像 Xet CDN 时可能出现连接被节流/SSL EOF;inference.py 用 SIZE 守卫(>3e9 字节)判断是否需要重下,断点可续。
  4. 依赖:fastapi/uvicorn/json_numpy/cv2 为随附 modeling_xvla.py 顶部 import 所需(仅 FastAPI 服务用),本 inference.py 不起服务但需可导入。

10. 标签

#NPU #Ascend #torch_npu #robotics #VLA