X-VLA-WidowX:可将 X-VLA-WidowX 机械臂操作模型部署到昇腾 NPU 上，提供 FastAPI 服务化推理接口，支持健康检查、动作预测等功能。项目完成了 CUDA 到 NPU 的迁移适配，修复多个兼容性问题，并附带完整测试用例，便于快速验证和部署。【此简介由AI生成】 - AtomGit AI社区

X-VLA-WidowX 昇腾 NPU 迁移与服务化推理指南

模型: 2toINF/X-VLA-0.9B-WidowX — 基于流匹配 (Flow Matching) 的视觉-语言-动作 (VLA) 大模型，参数量约 0.9B，用于 WidowX 机械臂操作任务。 本项目: 将原 CUDA/PyTorch 权重通过 torch_npu 迁移到昇腾 NPU，提供 FastAPI 服务化推理 (inference.py) 与完整测试用例 (test_client.py)。

1. 架构说明

X-VLA-WidowX 由三部分组成：

组件	说明
Florence-2 Encoder	视觉-语言表示骨干（encoder-only），处理多路相机图像 + 语言指令
SoftPromptedTransformer	流匹配动作去噪器，每个机器人本体 (embodiment) 有独立的可学习 soft prompt
Action Hub	定义动作空间 (`ee6d`)、掩码规则、预处理/后处理与损失

推理流程：多路图像 + 语言指令 + 本体状态(proprio) → Florence-2 编码 → 迭代去噪 (默认 10 步) → 输出 [num_actions=30, dim_action=20] 的动作序列（ee6d 双臂控制：每臂位置3 + 6D旋转6 + 夹爪1，共 10×2=20 维，夹爪通道经 sigmoid 后处理）。

2. 环境要求

项目	要求	本机验证值
硬件	Ascend910 系列 (≥1 卡)	Ascend910 × 8
OS	openEuler / Ubuntu (aarch64)	openEuler 22.03 SP4 (aarch64)
CANN	≥ 8.0	25.5.0
Python	3.8 – 3.11	3.11.14
PyTorch	与 CANN 配套	2.9.0+cpu
torch_npu	与 PyTorch 版本一致	2.9.0.post1

3. 目录结构

X-VLA-WidowX-npu/
├── inference.py          # 服务化推理脚本 (NPU 适配, FastAPI)
├── test_client.py        # 测试用例 (T1 NPU设备 / T2 离线推理 / T3 服务端到端)
├── requirements.txt      # 运行环境依赖
├── README.md             # 本指南
├── assets/               # 截图 (npu_device_call.png / model_result.png / agent_workflow.png)
├── logs/                 # 服务与测试日志
└── X-VLA-WidowX/         # 模型代码 (信任远程代码目录, 权重为符号链接)
    ├── modeling_xvla.py          # XVLA 主模型 + 内置 FastAPI
    ├── modeling_florence2.py     # Florence-2 视觉语言编码器
    ├── configuration_florence2.py / configuration_xvla.py
    ├── transformer.py            # SoftPromptedTransformer
    ├── action_hub.py             # 动作空间 (ee6d)
    ├── processing_xvla.py        # XVLAProcessor
    ├── preprocessor_config.json / tokenizer.json / vocab.json
    └── model.safetensors -> /mnt/old_data/whl/models/2toINF/X-VLA-WidowX/model.safetensors

权重 (3.5GB) 以符号链接方式引用原目录，避免重复占用磁盘；如需完全自包含，可 cp --dereference 复制权重文件。

4. 环境准备

# 1) 初始化 CANN 环境
source /usr/local/Ascend/ascend-toolkit/set_env.sh

# 2) 指定可见 NPU (可选, 默认全部)
export ASCEND_RT_VISIBLE_DEVICES=0

# 3) 安装依赖 (推荐华为镜像源)
export PIP_INDEX_URL=https://repo.huaweicloud.com/repository/pypi/simple/
pip install -r requirements.txt

# 4) 验证 torch_npu 基础可用
python3 -c "import torch, torch_npu; a = torch.randn(3,4).npu(); print(a + a)"
# 期望输出: tensor(..., device='npu:0')

5. 适配过程总结

原模型为 CUDA/PyTorch + HuggingFace 远程代码格式，迁移到昇腾 NPU 的关键点：

#	适配项	原始 (CUDA)	适配后 (NPU)	位置
1	NPU 后端注入	—	`import torch_npu` + `from torch_npu.contrib import transfer_to_npu`	入口脚本首部
2	设备映射	`model.cuda()` / `device('cuda')`	`.to('npu:0')` / `transfer_to_npu` 自动映射	inference.py `load_model`
3	精度	FP32/BF16	BF16 (训练精度 BP16, Ascend910 原生支持)	`--dtype bf16`
4	注意力实现	flash_attn / SDPA	eager (flash_attn 昇腾不可用；XVLA 类未声明 `_supports_sdpa`，需显式注入)	`from_pretrained`
5	多卡后端	nccl	hccl (`transfer_to_npu` 自动映射; 单卡推理无需分布式)	—
6	算子	—	全部为标准 PyTorch 算子 (attention/embedding/interpolate), torch_npu 原生支持	代码零改动
7	随机种子	—	`torch.manual_seed(42)` 固定, 保证可复现	入口脚本

适配调试记录 (transformers 4.57.6 兼容性修复)

迁移过程中定位并修复了 4 个兼容性问题（全部在入口脚本内修复，模型源码零改动）：

问题	现象	根因	修复
FIX-1 sdpa 派发失败	`ValueError: XVLA does not support ... scaled_dot_product_attention`	XVLA 远程代码类未声明 `_supports_sdpa`，transformers 4.5x+ 构造时强校验	加载前注入 `config._attn_implementation="eager"`，嵌套 `florence_config` 同步注入
FIX-2 tie_weights 崩溃	`AttributeError: ... has no attribute 'lm_head'`	XVLA 构造时删除 `lm_head`（encoder-only），transformers 4.5x+ `tie_weights` 递归访问子模块 embedding	嵌套 `config.tie_word_embeddings=False`
FIX-3 tied embedding 丢失	`Some weights newly initialized: encoder.embed_tokens.weight`	checkpoint 将 tied embedding 存为 `model.shared.weight`；禁用 tie 后 `encoder.embed_tokens` 与 shared 未绑定	加载后恢复权重共享 `encoder.embed_tokens.weight = shared.weight`（数值验证差异 = 0.0）
FIX-4 dtype 不匹配	`conv/layer_norm: input float32 vs weight bfloat16`	图像处理器输出 fp32、proprio 默认 fp32，与 bf16 权重冲突	输入张量与 proprio 显式转为模型 dtype (bf16)

关键结论: 模型源码 100% 使用标准 PyTorch 算子（无 torch.cuda.* 硬依赖、无自定义 CUDA kernel、flash_attn 为可选依赖），无需修改任何模型源码，仅在入口脚本注入 torch_npu、显式迁移设备并处理上述 4 个 transformers 兼容点即可。

6. 服务化推理 (inference.py)

# 启动服务 (默认 npu:0, bf16, 端口 8000)
python inference.py --model_path ./X-VLA-WidowX --device npu:0 --port 8000

# 可选参数
#   --dtype bf16|fp16|fp32    推理精度 (默认 bf16)
#   --warmup_steps N          预热去噪步数, 触发算子编译 (默认 4; 0=跳过)
#   --host 0.0.0.0            监听地址

服务启动后自动执行 NPU 预热（一次 dummy 推理，完成算子编译，避免首个请求超时），然后提供：

接口	方法	说明
`/healthz`	GET	服务健康状态 + 设备信息 (device/dtype/NPU 名称)
`/act`	POST	输入图像 + 指令 + 本体状态, 返回动作序列
`/docs`	GET	OpenAPI 交互式文档

/act 请求中的 proprio 为 20 维本体状态向量（与 ee6d 动作空间同维）。

`/act` 请求示例

curl -X POST http://127.0.0.1:8000/act -H "Content-Type: application/json" -d '{
  "image0": "<base64/jpg>",            # 相机图像, json_numpy 编码
  "language_instruction": "pick up the blue cup",
  "proprio": "<json_numpy 编码的 7 维向量>",
  "domain_id": 0,
  "steps": 10
}'

响应示例

{"action": [[0.123, -0.045, 0.002, 0.87, 0.01, 0.5], ... (30×6)], "latency_s": 0.42}

7. 测试用例 (test_client.py)

# 仅离线测试 (NPU 设备 + 直接推理, 无需服务)
python test_client.py --offline-only --model_path ./X-VLA-WidowX

# 完整测试 (需先启动 inference.py 服务)
python test_client.py --server http://127.0.0.1:8000

用例	验证内容	通过标准
T1 NPU 设备调用	`torch_npu.npu.is_available()`、设备名称、显存、张量落盘	张量 device 以 `npu:` 开头
T2 离线推理	模型加载到 NPU + `generate_actions` 10 步去噪	输出 shape=(1, 30, 20)，数值有限且幅度合理
T3 服务端到端	HTTP POST `/act`（兼容官方 client 协议）	服务端 device 为 NPU，返回 action shape=(30, 20)

测试结束后打印汇总 测试结果: N 通过 / M 失败，有失败时退出码为 1。

8. 测试结果

以下为本机实际运行结果 (2026-08-19, npu:0, bf16, 0.88B 参数)。

测试结论: 3/3 全部通过 ✅（完整日志见 logs/full_test_result.log）

用例	结果	关键数据
T1 NPU 设备调用	✅ PASS	Ascend910_9382 × 16, 单卡 61.3GB HBM, 张量 device='npu:0'
T2 离线推理	✅ PASS	action shape=(1, 30, 20), 10 步去噪耗时 0.44s
T3 服务端到端	✅ PASS	HTTP 200, action shape=(30, 20), 响应延迟 0.15s

实际输出示例:

[T1] NPU 设备调用验证
  NPU 可用: True | NPU 名称: Ascend910_9382 | NPU 数量: 16
  张量设备: npu:0 | 求和示例: 6.5292
  [PASS] T1 NPU 设备调用 device=npu:0

[T2] 离线推理验证 (模型加载到 NPU)
  模型设备: npu:0 | dtype: torch.bfloat16
  动作输出 shape: (1, 30, 20) | 耗时: 0.44s
  [PASS] T2 离线 NPU 推理 shape=(1, 30, 20) expected=(1, 30, 20) finite=True

[T3] 服务化推理验证 (HTTP -> http://127.0.0.1:8000)
  /healthz: {'status': 'ok', 'device': 'npu:0', 'dtype': 'torch.bfloat16'}
  HTTP 状态码: 200 | 响应耗时: 0.15s | 返回动作 shape: (30, 20)
  [PASS] T3 服务化端到端 action_shape=(30, 20) expected=(30, 20)

测试结果: 3 通过 / 0 失败

截图见 assets/ 目录：NPU 设备调用 (npu_device_call.png)、测试结果 (model_result.png)、适配过程 (agent_workflow.png)。

9. 常见问题 (FAQ)

问题	原因	解决
`ValueError: XVLA does not support ... sdpa`	XVLA 类未声明 `_supports_sdpa`	加载时传 `attn_implementation="eager"` (本项目已处理)
`No module named 'decorator'`	torch_npu 运行时依赖缺失	`pip install decorator`
`SetPrecisionMode ... error code 500001`	CANN 环境未加载	`source /usr/local/Ascend/ascend-toolkit/set_env.sh`
`Device do not support double dtype`	Ascend910 不支持 fp64	无需处理, 自动降级 fp32 (warning)
首个请求耗时很长 (数分钟)	算子首次编译	用 `--warmup_steps 4` 预热 (本项目默认开启)
OOM	显存不足	减小 batch/图像分辨率, 或换用 fp16
`ERR99999` 进程退出	环境/驱动异常	检查 npu-smi 与 CANN 版本配套

10. 附录: 与官方 client 对接

本服务 /act 协议与官方 X-VLA 仓库的 client_widowx.py 完全兼容：

python client_widowx.py --server_ip <SERVER_IP> --server_port 8000 --output_dir logs/

📦 本仓库由 ascend-model-agent-plugin (ai4s-basic) 自动迁移适配生成

X-VLA-WidowX 昇腾 NPU 迁移与服务化推理指南

模型: 2toINF/X-VLA-0.9B-WidowX — 基于流匹配 (Flow Matching) 的视觉-语言-动作 (VLA) 大模型，参数量约 0.9B，用于 WidowX 机械臂操作任务。 本项目: 将原 CUDA/PyTorch 权重通过 torch_npu 迁移到昇腾 NPU，提供 FastAPI 服务化推理 (inference.py) 与完整测试用例 (test_client.py)。

1. 架构说明

X-VLA-WidowX 由三部分组成：

组件	说明
Florence-2 Encoder	视觉-语言表示骨干（encoder-only），处理多路相机图像 + 语言指令
SoftPromptedTransformer	流匹配动作去噪器，每个机器人本体 (embodiment) 有独立的可学习 soft prompt
Action Hub	定义动作空间 (`ee6d`)、掩码规则、预处理/后处理与损失

2. 环境要求

项目	要求	本机验证值
硬件	Ascend910 系列 (≥1 卡)	Ascend910 × 8
OS	openEuler / Ubuntu (aarch64)	openEuler 22.03 SP4 (aarch64)
CANN	≥ 8.0	25.5.0
Python	3.8 – 3.11	3.11.14
PyTorch	与 CANN 配套	2.9.0+cpu
torch_npu	与 PyTorch 版本一致	2.9.0.post1

3. 目录结构

X-VLA-WidowX-npu/
├── inference.py          # 服务化推理脚本 (NPU 适配, FastAPI)
├── test_client.py        # 测试用例 (T1 NPU设备 / T2 离线推理 / T3 服务端到端)
├── requirements.txt      # 运行环境依赖
├── README.md             # 本指南
├── assets/               # 截图 (npu_device_call.png / model_result.png / agent_workflow.png)
├── logs/                 # 服务与测试日志
└── X-VLA-WidowX/         # 模型代码 (信任远程代码目录, 权重为符号链接)
    ├── modeling_xvla.py          # XVLA 主模型 + 内置 FastAPI
    ├── modeling_florence2.py     # Florence-2 视觉语言编码器
    ├── configuration_florence2.py / configuration_xvla.py
    ├── transformer.py            # SoftPromptedTransformer
    ├── action_hub.py             # 动作空间 (ee6d)
    ├── processing_xvla.py        # XVLAProcessor
    ├── preprocessor_config.json / tokenizer.json / vocab.json
    └── model.safetensors -> /mnt/old_data/whl/models/2toINF/X-VLA-WidowX/model.safetensors

权重 (3.5GB) 以符号链接方式引用原目录，避免重复占用磁盘；如需完全自包含，可 cp --dereference 复制权重文件。

4. 环境准备

# 1) 初始化 CANN 环境
source /usr/local/Ascend/ascend-toolkit/set_env.sh

# 2) 指定可见 NPU (可选, 默认全部)
export ASCEND_RT_VISIBLE_DEVICES=0

# 3) 安装依赖 (推荐华为镜像源)
export PIP_INDEX_URL=https://repo.huaweicloud.com/repository/pypi/simple/
pip install -r requirements.txt

# 4) 验证 torch_npu 基础可用
python3 -c "import torch, torch_npu; a = torch.randn(3,4).npu(); print(a + a)"
# 期望输出: tensor(..., device='npu:0')

5. 适配过程总结

原模型为 CUDA/PyTorch + HuggingFace 远程代码格式，迁移到昇腾 NPU 的关键点：

#	适配项	原始 (CUDA)	适配后 (NPU)	位置
1	NPU 后端注入	—	`import torch_npu` + `from torch_npu.contrib import transfer_to_npu`	入口脚本首部
2	设备映射	`model.cuda()` / `device('cuda')`	`.to('npu:0')` / `transfer_to_npu` 自动映射	inference.py `load_model`
3	精度	FP32/BF16	BF16 (训练精度 BP16, Ascend910 原生支持)	`--dtype bf16`
4	注意力实现	flash_attn / SDPA	eager (flash_attn 昇腾不可用；XVLA 类未声明 `_supports_sdpa`，需显式注入)	`from_pretrained`
5	多卡后端	nccl	hccl (`transfer_to_npu` 自动映射; 单卡推理无需分布式)	—
6	算子	—	全部为标准 PyTorch 算子 (attention/embedding/interpolate), torch_npu 原生支持	代码零改动
7	随机种子	—	`torch.manual_seed(42)` 固定, 保证可复现	入口脚本

适配调试记录 (transformers 4.57.6 兼容性修复)

迁移过程中定位并修复了 4 个兼容性问题（全部在入口脚本内修复，模型源码零改动）：

问题	现象	根因	修复
FIX-1 sdpa 派发失败	`ValueError: XVLA does not support ... scaled_dot_product_attention`	XVLA 远程代码类未声明 `_supports_sdpa`，transformers 4.5x+ 构造时强校验	加载前注入 `config._attn_implementation="eager"`，嵌套 `florence_config` 同步注入
FIX-2 tie_weights 崩溃	`AttributeError: ... has no attribute 'lm_head'`	XVLA 构造时删除 `lm_head`（encoder-only），transformers 4.5x+ `tie_weights` 递归访问子模块 embedding	嵌套 `config.tie_word_embeddings=False`
FIX-3 tied embedding 丢失	`Some weights newly initialized: encoder.embed_tokens.weight`	checkpoint 将 tied embedding 存为 `model.shared.weight`；禁用 tie 后 `encoder.embed_tokens` 与 shared 未绑定	加载后恢复权重共享 `encoder.embed_tokens.weight = shared.weight`（数值验证差异 = 0.0）
FIX-4 dtype 不匹配	`conv/layer_norm: input float32 vs weight bfloat16`	图像处理器输出 fp32、proprio 默认 fp32，与 bf16 权重冲突	输入张量与 proprio 显式转为模型 dtype (bf16)

6. 服务化推理 (inference.py)

# 启动服务 (默认 npu:0, bf16, 端口 8000)
python inference.py --model_path ./X-VLA-WidowX --device npu:0 --port 8000

# 可选参数
#   --dtype bf16|fp16|fp32    推理精度 (默认 bf16)
#   --warmup_steps N          预热去噪步数, 触发算子编译 (默认 4; 0=跳过)
#   --host 0.0.0.0            监听地址

服务启动后自动执行 NPU 预热（一次 dummy 推理，完成算子编译，避免首个请求超时），然后提供：

接口	方法	说明
`/healthz`	GET	服务健康状态 + 设备信息 (device/dtype/NPU 名称)
`/act`	POST	输入图像 + 指令 + 本体状态, 返回动作序列
`/docs`	GET	OpenAPI 交互式文档

/act 请求中的 proprio 为 20 维本体状态向量（与 ee6d 动作空间同维）。

`/act` 请求示例

curl -X POST http://127.0.0.1:8000/act -H "Content-Type: application/json" -d '{
  "image0": "<base64/jpg>",            # 相机图像, json_numpy 编码
  "language_instruction": "pick up the blue cup",
  "proprio": "<json_numpy 编码的 7 维向量>",
  "domain_id": 0,
  "steps": 10
}'

响应示例

{"action": [[0.123, -0.045, 0.002, 0.87, 0.01, 0.5], ... (30×6)], "latency_s": 0.42}

7. 测试用例 (test_client.py)

# 仅离线测试 (NPU 设备 + 直接推理, 无需服务)
python test_client.py --offline-only --model_path ./X-VLA-WidowX

# 完整测试 (需先启动 inference.py 服务)
python test_client.py --server http://127.0.0.1:8000

用例	验证内容	通过标准
T1 NPU 设备调用	`torch_npu.npu.is_available()`、设备名称、显存、张量落盘	张量 device 以 `npu:` 开头
T2 离线推理	模型加载到 NPU + `generate_actions` 10 步去噪	输出 shape=(1, 30, 20)，数值有限且幅度合理
T3 服务端到端	HTTP POST `/act`（兼容官方 client 协议）	服务端 device 为 NPU，返回 action shape=(30, 20)

测试结束后打印汇总 测试结果: N 通过 / M 失败，有失败时退出码为 1。

8. 测试结果

以下为本机实际运行结果 (2026-08-19, npu:0, bf16, 0.88B 参数)。

测试结论: 3/3 全部通过 ✅（完整日志见 logs/full_test_result.log）

用例	结果	关键数据
T1 NPU 设备调用	✅ PASS	Ascend910_9382 × 16, 单卡 61.3GB HBM, 张量 device='npu:0'
T2 离线推理	✅ PASS	action shape=(1, 30, 20), 10 步去噪耗时 0.44s
T3 服务端到端	✅ PASS	HTTP 200, action shape=(30, 20), 响应延迟 0.15s

实际输出示例:

[T1] NPU 设备调用验证
  NPU 可用: True | NPU 名称: Ascend910_9382 | NPU 数量: 16
  张量设备: npu:0 | 求和示例: 6.5292
  [PASS] T1 NPU 设备调用 device=npu:0

[T2] 离线推理验证 (模型加载到 NPU)
  模型设备: npu:0 | dtype: torch.bfloat16
  动作输出 shape: (1, 30, 20) | 耗时: 0.44s
  [PASS] T2 离线 NPU 推理 shape=(1, 30, 20) expected=(1, 30, 20) finite=True

[T3] 服务化推理验证 (HTTP -> http://127.0.0.1:8000)
  /healthz: {'status': 'ok', 'device': 'npu:0', 'dtype': 'torch.bfloat16'}
  HTTP 状态码: 200 | 响应耗时: 0.15s | 返回动作 shape: (30, 20)
  [PASS] T3 服务化端到端 action_shape=(30, 20) expected=(30, 20)

测试结果: 3 通过 / 0 失败

截图见 assets/ 目录：NPU 设备调用 (npu_device_call.png)、测试结果 (model_result.png)、适配过程 (agent_workflow.png)。

9. 常见问题 (FAQ)

问题	原因	解决
`ValueError: XVLA does not support ... sdpa`	XVLA 类未声明 `_supports_sdpa`	加载时传 `attn_implementation="eager"` (本项目已处理)
`No module named 'decorator'`	torch_npu 运行时依赖缺失	`pip install decorator`
`SetPrecisionMode ... error code 500001`	CANN 环境未加载	`source /usr/local/Ascend/ascend-toolkit/set_env.sh`
`Device do not support double dtype`	Ascend910 不支持 fp64	无需处理, 自动降级 fp32 (warning)
首个请求耗时很长 (数分钟)	算子首次编译	用 `--warmup_steps 4` 预热 (本项目默认开启)
OOM	显存不足	减小 batch/图像分辨率, 或换用 fp16
`ERR99999` 进程退出	环境/驱动异常	检查 npu-smi 与 CANN 版本配套

10. 附录: 与官方 client 对接

本服务 /act 协议与官方 X-VLA 仓库的 client_widowx.py 完全兼容：

python client_widowx.py --server_ip <SERVER_IP> --server_port 8000 --output_dir logs/

📦 本仓库由 ascend-model-agent-plugin (ai4s-basic) 自动迁移适配生成

X-VLA-WidowX 昇腾 NPU 迁移与服务化推理指南

目录

1. 架构说明

2. 环境要求

3. 目录结构

4. 环境准备

5. 适配过程总结

适配调试记录 (transformers 4.57.6 兼容性修复)

6. 服务化推理 (inference.py)

/act 请求示例

响应示例

7. 测试用例 (test_client.py)

8. 测试结果

9. 常见问题 (FAQ)

10. 附录: 与官方 client 对接

X-VLA-WidowX 昇腾 NPU 迁移与服务化推理指南

目录

1. 架构说明

2. 环境要求

3. 目录结构

4. 环境准备

5. 适配过程总结

适配调试记录 (transformers 4.57.6 兼容性修复)

6. 服务化推理 (inference.py)

/act 请求示例

响应示例

7. 测试用例 (test_client.py)

8. 测试结果

9. 常见问题 (FAQ)

10. 附录: 与官方 client 对接

`/act` 请求示例

`/act` 请求示例