p
pnflly/INTACT-pi0-finetune-bridge
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

INTACT-pi0-finetune-bridge(昇腾 NPU 适配版)

将 juexzz/INTACT-pi0-finetune-bridge(Pi0 视觉-语言-动作 VLA 模型,基于 BridgeV2 数据微调)适配到华为昇腾 910 系列 NPU,通过 vLLM-Ascend 提供服务化多模态推理。

模型卡片元数据见本仓库 YAML frontmatter:hardware: NPU。


简介

本仓库交付 Pi0 VLA 模型在昇腾 NPU 上的 vLLM-Ascend 服务化适配。

Pi0(arXiv:2410.24164)是一个 流匹配(flow matching)视觉-语言-动作(VLA)模型,由三部分组成:

组件内容是否在本适配中服务化
PaliGemma 骨干SigLIP-So400m 视觉编码器(27 层, hidden 1152, 224×224)+ Gemma 语言模型(18 层, hidden 2048, 8 头 GQA, vocab 257152)+ 多模态投影器✅ 是(vLLM-Ascend 服务)
Gemma action expert流匹配动作专家(18 层, hidden 1024)❌ 否(随权重保留,不参与服务化)
策略头state_proj / action_in_proj / action_out_proj / action_time_mlp❌ 否(随权重保留)

本模型为 INTACT Probing Suite(arXiv:2506.09930)的一部分,在 BridgeV2 数据集上对 Pi0 进行微调,用于机器人操作任务的泛化边界研究。输入为「顶置相机图像(224×224,单相机)+ 自然语言指令 + 机器人状态(7 维)」,输出为 7 维动作序列(chunk_size=4)。

适配策略

Pi0 的 PaliGemma 骨干 结构与 HuggingFace 标准 PaliGemmaForConditionalGeneration 完全一致,且 vLLM 0.18 已内置该架构(vllm/model_executor/models/paligemma.py,已注册于 registry)。因此适配采用 「零 vLLM 源码改动 + checkpoint 转换」 策略:

  1. 从原始 model.safetensors(6,482,726,480 字节,776 个张量)中剥离 action expert(model.paligemma_with_expert.gemma_expert.*)与策略头(model.action_*、model.state_proj.*),共剥离 173 个张量;
  2. 保留 PaliGemma 骨干 603 个张量,重映射键名:
    • model.paligemma_with_expert.paligemma.* → model.*
    • language_model.model.* → language_model.*(适配 transformers 4.57 / vLLM 0.18 的 GemmaModel 命名)
  3. 补齐 config.json(PaliGemmaForConditionalGeneration)、tokenizer.json/tokenizer.model(PaliGemma-3B 词表,vocab 257152,含 <image> token id 257152)、preprocessor_config.json;
  4. 转换后 checkpoint 经 transformers 校验:MISSING=1(仅 tied 的 lm_head.weight,属预期)、UNEXPECTED=0。

转换后模型以 bf16 全精度部署,全部 603 个张量为 BF16(原 checkpoint 中的 11 个 F32 张量均位于被剥离的 action expert / 策略头部分)。

服务化能力

能力说明
服务化推理OpenAI 兼容 POST /v1/chat/completions
多模态输入图像(224×224)+ 文本指令
精度bfloat16,--enforce-eager
推理确定性temperature=0 时输出完全确定性

验证环境

项配置
硬件昇腾 Ascend910_9362 单卡(HBM 64GB),/dev/davinci6(逻辑 NPU0)/ /dev/davinci7(逻辑 NPU1)
操作系统Linux aarch64
CANN8.5.1
Python3.11.14
PyTorch2.9.0
torch_npu2.9.0.post1
transformers4.57.6
vLLM0.18.0
vllm_ascend0.18.0
safetensors0.7.0
部署方式vLLM-Ascend OpenAI API Server(ASCEND_RT_VISIBLE_DEVICES 指定逻辑卡)

权重来源与文件

原始权重从 GitCode 拉取(https://ai.gitcode.com/hf_mirrors/juexzz/INTACT-pi0-finetune-bridge):

文件大小说明
model.safetensors6.48 GBPi0 全量权重(776 张量,bf16/f32)
config.json1.4 KBPi0 策略配置(type: pi0,BridgeV2 7-DoF)

转换后交付 checkpoint:

文件大小说明
model.safetensors5.85 GBPaliGemma 骨干(603 张量,全部 BF16)
config.json1.3 KBPaliGemmaForConditionalGeneration 配置
tokenizer.json / tokenizer.model17.5 MB / 4.3 MBPaliGemma-3B 词表(vocab 257152)
tokenizer_config.json / special_tokens_map.json / added_tokens.json小tokenizer 元数据
preprocessor_config.json699 B图像预处理(resize 224×224, do_rescale)

服务启动

1. 安装依赖

pip install -r requirements.txt

2. 启动 vLLM-Ascend 服务

# 指定可见 NPU 逻辑卡(按需调整)
export ASCEND_RT_VISIBLE_DEVICES=0
export HF_HUB_OFFLINE=1
export TRANSFORMERS_OFFLINE=1

vllm serve /path/to/INTACT-pi0-finetune-bridge \
  --served-model-name INTACT-pi0-finetune-bridge \
  --dtype bfloat16 \
  --max-model-len 2048 \
  --max-num-seqs 4 \
  --gpu-memory-utilization 0.25 \
  --enforce-eager \
  --port 8025 \
  --trust-remote-code

说明:本环境 NPU 竞争激烈(多窗口并行适配),服务端口与卡位按空闲资源动态选择。本次实际使用 ASCEND_RT_VISIBLE_DEVICES=0 + 端口 8025。若端口被占用可更换其他空闲端口,切勿杀掉其他进程。

3. 启动成功标志(本次实测日志)

Loading safetensors checkpoint shards: 100% Completed | 1/1 [00:16<00:00]
Loading weights took 17.00 seconds
Loading model weights took 5.4570 GB
Available KV cache memory: 9.40 GiB
GPU KV cache size: 547,456 tokens
init engine (profile, create kv cache, warmup model) took 3.28 seconds
INFO:     Started server process [119306]
INFO:     Application startup complete.

Smoke 验证

1. 就绪检查

curl -s http://127.0.0.1:8025/v1/models | python3 -m json.tool

输出(节选):

{
    "object": "list",
    "data": [
        {
            "id": "INTACT-pi0-finetune-bridge",
            "object": "model",
            "owned_by": "vllm",
            "max_model_len": 2048
        }
    ]
}

2. 多模态推理(图像 + 文本指令)

python3 inference.py /path/to/sample_scene.png "pick up the red object and place it in the green container"

3. 功能验证矩阵

特性状态说明
文本推理✅ 已验证请求成功,finish_reason=length
文本+图像推理(多模态)✅ 已验证单张 224×224 图像,256 视觉 token 正确注入
ACLGraph⚠️ 已禁用以 --enforce-eager 运行(昇腾默认编译路径兼容性优先)
MoE EPN/A非 MoE 模型
MTPN/Acheckpoint 不支持

性能参考

数据为本次适配实测,环境:Ascend910_9362 单卡 / CANN 8.5.1 / vLLM 0.18.0 + vllm_ascend 0.18.0 / bf16 / enforce-eager。NPU 竞争环境下测得,绝对值会随并发任务波动。

指标数值
模型权重加载耗时17.00 s(5.457 GB,单文件 safetensors)
引擎初始化(profile + KV cache + warmup)3.28 s
服务进程启动到就绪~2 min(含算子首次编译)
权重内存占用(EngineCore)15,704 MB
KV cache 可用9.40 GiB(547,456 tokens)
单次多模态请求(256 视觉 token + 短文本 → 64 输出 token)0.94 – 3.95 s
输出吞吐(64 token / 1.33 s 请求)~48 tokens/s
推理确定性(temperature=0)✅ 两次运行输出一致

首请求延迟较高(0.94–3.95s)与模型为 VLA prefix-encoder 特性、单卡并发竞争有关;服务预热后多请求稳定在秒级以内。


精度测评

权重精度一致性

  • 转换前原始 checkpoint:paligemma 骨干 全部 BF16;11 个 F32 张量全部位于 action expert / 策略头(gemma_expert.model.norm、state_proj、action_*),已被剥离;
  • 转换后服务化 checkpoint:603 个张量全部 BF16,无精度混排;
  • transformers 4.57.6 权重键覆盖校验:MISSING=1(仅 tied lm_head.weight,因 tie_word_embeddings=true 由 embed_tokens 共享,属预期),UNEXPECTED=0。

推理数值校验

  • 以 temperature=0 做两次推理,输出完全一致(确定性):
    run1: 'películamunicipimunicipi noblesse utop pamphRectangleBorder-...'
    run2: 'películamunicipimunicipi noblesse utop pamphRectangleBorder-...'
    deterministic: True
  • 多模态请求 usage 稳定:prompt_tokens≈265–272(含 256 图像 token + 文本指令 token),completion_tokens=16–64 符合设定。

说明

Pi0 语言模型在 VLA 架构中作为 prefix encoder 使用(将图像与语言指令编码为 action expert 的上下文),不用于开放式文本生成。因此服务化推理输出的文本 token 为 prefix 编码解码结果,呈现重复词表 token 属于该模型固有行为,并非服务或权重加载异常。完整 VLA 动作预测需要 action expert 与流匹配采样(本次适配不包含该部分服务化)。


注意事项

  1. NPU 卡位与端口竞争:本机多窗口并行适配模型,NPU 显存与端口均为共享资源。启动前先 npu-smi info 查看空闲卡,ss -tlnp 查看空闲端口;服务绑定失败(如端口被占用)时换端口重试,不要 kill 他人进程。
  2. 可见设备变量:使用 ASCEND_RT_VISIBLE_DEVICES=<逻辑索引>(本环境为 0 或 1),不要使用 ASCEND_VISIBLE_DEVICES(会破坏 torch.npu 设备映射)。
  3. 离线环境:本环境无法直连 huggingface.co,必须设置 HF_HUB_OFFLINE=1、TRANSFORMERS_OFFLINE=1,且模型目录需含完整 config.json + tokenizer 文件,否则会触发在线下载而失败。
  4. vllm serve 是正确入口:直接 python -m vllm.entrypoints.openai.api_server <path> 不会把位置参数映射为 --model,必须用 vllm serve <path> CLI。
  5. 图像预处理:PaliGemma 期望 224×224 图像,preprocessor_config.json 已配置 do_resize + do_rescale,图像像素归一化到 [-1, 1](SigLIP 约定)。
  6. VLA 语义:本适配交付的是 PaliGemma 骨干服务化推理(多模态 prefix 编码),不包含 flow-matching action expert 的动作采样;如需完整 VLA 动作输出,请配合 LeRobot Pi0Policy + action expert 权重使用。
  7. 磁盘配额:/opt/atomgit 挂载盘有项目配额限制(models 目录约 45GB),大规模权重建议存放于 /tmp 等大容量临时盘。

参考

  • Pi0 论文:https://arxiv.org/abs/2410.24164
  • INTACT 论文:https://arxiv.org/abs/2506.09930
  • INTACT Probing Suite 集合:https://huggingface.co/collections/ai4ce/intact-probing-suite-684e5601e9ed640fdd9b994b
  • vLLM-Ascend:https://github.com/vllm-project/vllm-ascend