2toINF/X-VLA-Pt on Ascend NPU

1. 简介

• 模型来源: 2toINF/X-VLA-Pt（HuggingFace Hub）
• 模型类型: 视觉-语言-动作（Vision-Language-Action）策略，基于 flow-matching 训练
• 参数量: ≈ 0.9B（Florence-2-large encoder-only 骨干网络 + 24 层 SoftPromptedTransformer）
• 输入 / 输出: 多视角图像（≤3 视角，224×224）+ 本体状态（20 维）+ 语言指令 → 连续动作（chunk=30 步 × 20 维，ee6d 动作空间）
• VLM 骨干网络: microsoft/Florence-2-large（encoder-only，DaViT 视觉塔 + BART 文本编码器）
• 论文: Zheng et al., 2025, X-VLA: Soft-Prompted Transformer as Scalable Cross-Embodiment Vision-Language-Action Model（arXiv:2510.10274）
• 参考实现: https://github.com/2toINF/X-VLA

X-VLA 将「可学习软提示（soft prompt）」思想引入跨本体机器人学习，为每个不同的本体（embodiment/domain）维护一套独立的可学习嵌入，从而在一个模型内高效利用异构机器人数据。其架构为「Florence-2 编码器（视觉-语言表征）→ SoftPromptedTransformer（flow-matching 动作去噪）→ Action Hub（ee6d 动作空间 / 损失）」，是一个简洁、可扩展的通用 VLA 策略。

X-VLA-Pt 为 2toINF 发布的通用基础（Pt）权重，action_mode=ee6d（双组 6D 位姿 + 双组 3D 位置 + 双夹爪），num_domains=30（30 个本体域），可在具体机器人/任务上继续微调。

本目录完成了该模型在昇腾 Ascend NPU（torch_npu 推理引擎）上的完整适配与部署，包含可直接运行的推理脚本 inference.py、批量测试脚本 run_test_cases.py、依赖清单 requirements.txt、运行用 venv 环境、50 组实测测试用例及输出结果，以及适配过程总结 AGENT_WORKFLOW.md。

2. 验证环境

模型权重路径：

3. NPU 适配说明

X-VLA-Pt 为自定义 HuggingFace 架构（XVLA，model_type="xvla"），不在 vllm-ascend / sglang 的模型注册表内（Florence-2 亦在 vllm-ascend「未支持」列表中，Issue #2259），且输出为连续动作而非自回归 token，因此推理引擎选用 torch_npu¹，通过 AutoModel.from_pretrained(..., trust_remote_code=True) 加载远端代码直接推理。

关键实现（均在 inference.py / run_test_cases.py 中，不修改任何三方库源码）：

1. 通过 AutoConfig.from_pretrained 加载 XVLAConfig，并在 config._attn_implementation 与 config.florence_config._attn_implementation 上显式设置 "eager"；
2. 通过 AutoModel.from_pretrained(..., trust_remote_code=True, dtype=bf16) 加载权重，执行 model.to('npu:0')；加载后将 encoder.embed_tokens.weight 重绑到 shared.weight；
3. 通过 AutoProcessor.from_pretrained(..., trust_remote_code=True) 加载 XVLAProcessor；
4. 调用 model.generate_actions(input_ids, image_input, image_mask, domain_id, proprio, steps) 完成 flow-matching 去噪，输出 (B, num_actions=30, dim_action=20) 动作；
5. 夹爪通道（索引 9/19）经 action_space.postprocess 的 sigmoid 归一至 [0,1]。

4. 分步推理操作流程

4.1 环境依赖

# 使用清华镜像安装 Python 依赖（本目录已创建 venv，继承系统级 torch/torch-npu）
cd /opt/atomgit/model_adapt/X-VLA-Pt-NPU
./venv/bin/pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
# 或使用阿里云镜像
# ./venv/bin/pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

torch / torch-npu 必须与 CANN 版本严格对应，请通过昇腾官方渠道安装（参见 requirements.txt 末尾的版本对照表）。本目录下的 venv/ 环境由 python3 -m venv --system-site-packages venv 创建，会自动继承系统级的 torch / torch-npu，因此在 venv 内只需安装 timm / json-numpy 等纯 Python 依赖。

4.2 创建运行环境（首次）

```bash
# 创建 venv（继承系统 torch/torch-npu/transformers 等）
python3 -m venv --system-site-packages venv

# 安装模型远端代码所需依赖（清华镜像）
./venv/bin/pip install timm==1.0.15 json-numpy==2.1.1 \
    -i https://pypi.tuna.tsinghua.edu.cn/simple

4.3 准备模型权重

# 权重已本地化于 /data/models/2toINF/X-VLA-Pt（含 config.json / model.safetensors /
# modeling_xvla.py / modeling_florence2.py / transformer.py / action_hub.py /
# processing_xvla.py / tokenizer 等）
# 若需重新下载（HuggingFace 直连不可达时用 ModelScope）：
#   python3 -c "from modelscope import snapshot_download;
#       snapshot_download('2toINF/X-VLA-Pt',
#           local_dir='/data/models/2toINF/X-VLA-Pt')"

4.4 Running Inference (Single Shot)

cd /opt/atomgit/model_adapt/X-VLA-Pt-NPU
./venv/bin/python inference.py \
    --model /data/models/2toINF/X-VLA-Pt \
    --device npu:0 \
    --task "Pick up the red block and place it in the green bin." \
    --domain 0 --steps 10 --seed 42 \
    --output-dir output

生成的产物位于 output/：

--help 可查看全部参数（--task、--state 20 维、--domain 0~29、--steps、 --seed、--views、--hue、--image 真实图像路径等）。

4.5 批量测试用例（50 组）

./venv/bin/python run_test_cases.py \
    --model /data/models/2toINF/X-VLA-Pt \
    --device npu:0 \
    --output-dir output

每组输出到 output/testcase_NN/action.npy 和 output/testcase_NN/report.json， 所有结果汇总至 output/testcases_summary.json。使用 --cases 1,2,3 可运行子集并支持断点续跑。

5. 测试用例与输出结果

5.1 用例设计

共 50 组（满足≥44组的要求），模型仅加载一次、逐组推理，覆盖6类输入变化：

公共基线：合成三视角棋盘格图像（hue=0.5）、语言指令 "Pick up the red block and place it in the green bin."、state=全零20维、 domain_id=0、10步去噪、seed=42。

动作布局（ee6d）：[0:3]=pos1(xyz)、[3:9]=rot1(6D)、[9]=gripper1、 [10:13]=pos2(xyz)、[13:19]=rot2(6D)、[19]=gripper2。夹爪通道经 sigmoid 归一至 [0,1]。

5.2 组 A：domain_id 0~29（30组）

固定指令/状态/图像/seed=42/steps=10，仅切换 domain_id。各域输出明显不同 （mean_abs 0.120.40，夹爪 0.000.92），证明30组本体 soft prompt 均被正确激活。 first_step 为 action 第1步的完整20维向量（含 sigmoid 后夹爪值）。

5.3 Group B: Language Instructions (8 Cases)

With fixed domain=0 / zero-state / 3 views / seed=42 / steps=10, only the instruction is varied. The outputs for different instructions show differences (e.g., first_step dimension 1 ranges from -0.0437 to -0.0474); since the synthetic image content and the action magnitudes under near-zero state are generally close, the differences are small in scale but element-wise distinguishable (no NaN).

5.4 Group C: Proprioceptive States (4 Cases)

With fixed domain=0 / instruction / 3 views / seed=42 / steps=10, only the 20-dimensional state is switched.

5.5 组 D：图像视角 / 色偏（3 组）

固定 domain=0 / 指令 / state 全零 / seed=42 / steps=10，切换视角数与基准色偏 hue。

5.6 组 E：去噪步数（3 组）

固定 domain=0 / 指令 / 3 视角 / seed=42，切换 flow-matching 去噪步数。步数越多耗时越高（约线性），输出收敛稳定（mean_abs ≈ 0.1794~0.1795，无 NaN）。

5.7 组 F：随机种子（2 组）

固定其余输入，仅切换种子以体现初始噪声的随机性；输出受 seed 影响（逐元素可区分），幅度较小（flow-matching 去噪在合成输入下收敛良好）。

5.8 代表用例完整输出（用例 01）

output/testcase_01/report.json（关键字段）：

{
  "case_id": 1,
  "name": "domain_00",
  "device": "npu:0",
  "dtype": "bf16",
  "task": "Pick up the red block and place it in the green bin.",
  "domain_id": 0,
  "num_views": 3,
  "num_steps": 10,
  "seed": 42,
  "action_shape": [1, 30, 20],
  "action_first_step": [-0.0461, -0.1147, 0.2617, 0.1377, -0.2041, 0.1436, 0.0303,
      -0.0118, -0.4141, 0.4062, -0.0222, 0.1436, -0.1177, -0.04, -0.1475, -0.252,
      0.2773, -0.1309, 0.0156, 0.5703],
  "action_mean_abs": 0.1794,
  "action_std": 0.2319,
  "gripper_first_step": [0.4062, 0.5703],
  "has_nan": false,
  "infer_time_s": 0.539
}

验证结论：50 组用例全部 status=SUCCESS、无 NaN；30 个 domain 软提示、语言指令、本体状态、图像视角、去噪步数、随机种子六类输入变化均可在 Ascend 910B 上产生可区分的合法动作输出（夹爪通道稳定落在 [0,1]），模型可完整加载并在 NPU 上完成 VLA 推理，适配状态 SUCCESS。

6. 性能参考

测试条件：10 步 flow-matching 去噪，3 视角 224×224 图像 + 20 维 state，单张 Ascend 910B（单卡，npu:0）。

7. 注意事项

1. 推理引擎：X-VLA-Pt 为 VLA 策略，输出连续动作而非 token，非自回归 LLM，且 Florence-2 未在 vllm-ascend 支持列表中（Issue #2259），因此不适用 vllm-ascend / sglang，推理引擎为 torch_npu。¹
2. transformers 4.57.x 注意力检查：构造模型时 transformers 会执行 _check_and_adjust_attn_implementation，对本地 Florence2 远端代码（未定义 _supports_sdpa）会误判并报 AttributeError。inference.py 通过显式设 _attn_implementation="eager" 绕过。²
3. encoder.embed_tokens 重绑：X-VLA 将 Florence2 的 tie_weights 置空，加载后 encoder.embed_tokens 与 shared 解绑（保持随机初始化）。推理路径经 get_input_embeddings()（=shared）计算文本嵌入并直接传入 encoder，该随机模块本不 参与计算；inference.py 仍显式重绑以保证完全正确。³
4. 输入 dtype：处理器输出 fp32 图像，须转 bf16 与模型权重一致（DaViT Conv2d 要求 输入/权重同 dtype），否则报 Input type (float) and bias type (c10::BFloat16) should be the same。
5. 合成观测：无真实相机/机械臂时使用合成棋盘格图像。接入真实数据时，把 --image cam0.jpg,cam1.jpg,cam2.jpg 传入即可（≤3 视角，PIL 自动转 RGB）。
6. 权重离线化：HuggingFace 直连不可达时可用 ModelScope 下载并本地化（见 4.3）。
7. 文件写限流：本工作区为 SFS Turbo 存储，突发连续写可能偶发 EDQUOT 限流， inference.py 输出写盘已带自动重试。
8. 精度说明：本目录验证的是可运行性（SUCCESS），不含数值精度对标；如需与 CUDA 结果逐位对比，请在 NVIDIA 环境复跑相同输入。

贡献者: z_studio | 赛道: 模型适配赛道