PE-Lang-L14-448 on Ascend NPU

1. 简介

PE-Lang-L14-448（Perception Encoder Lang L/14 - 448px）是一个基于 ViT-L/14 架构的图像特征提取模型，输入分辨率为 448×448，产生 1024 维的 CLS token 嵌入向量。本仓库记录了该模型在华为昇腾 NPU（Ascend 910B4）上的适配、推理验证和精度评测结果。

模型架构要点：

• 主干：ViT-L/14（patch_size=14，hidden_dim=1024，num_heads=16）
• 层数：23 层 Transformer Block（含 LayerScale 机制）
• 输入：448×448 RGB 图像 → 1024 个 patch tokens + 1 个 CLS token
• 输出：CLS token 嵌入（1024 维）
• 参数量：~291.42M

相关获取地址：

• 权重下载地址（ModelScope）：https://modelscope.cn/models/AtomGit/PE-Lang-L14-448
• 权重下载地址（HuggingFace）：https://huggingface.co/AtomGit/PE-Lang-L14-448
• 权重下载地址（AtomGit）：https://atomgit.com/PE-Lang/PE-Lang-L14-448

2. 验证环境

• NPU：Ascend 910B4（1 逻辑卡）
• 工作目录：/opt/atomgit/PE-Lang-L14-448/PE-Lang-L14-448-ascend
• 权重路径：/opt/atomgit/PE-Lang-L14-448/PE-Lang-L14-448.pt

3. 推理脚本

3.1 文件结构

PE-Lang-L14-448-ascend/
├── inference.py    # 模型定义 + 权重加载 + 推理入口
├── eval.py         # 精度与性能评测脚本
└── log.txt         # 评测日志输出

3.2 单图推理

cd /opt/atomgit/PE-Lang-L14-448/PE-Lang-L14-448-ascend

# NPU 推理（bf16）
python3 inference.py \
  --checkpoint ../PE-Lang-L14-448.pt \
  --device npu:0 \
  --image-path /path/to/image.jpg

3.3 权重加载说明

权重文件（.pt）的 key 格式为 OpenCLIP 风格：

transformer.resblocks.0.attn.in_proj_weight
transformer.resblocks.0.attn.in_proj_bias
transformer.resblocks.0.mlp.c_fc.weight

脚本的 load_custom_weights() 方法自动将其映射为 PyTorch nn.Module 格式：

transformer.0.attn.in_proj.weight
transformer.0.attn.in_proj.bias
transformer.0.mlp.c_fc.weight

其中 in_proj_weight / in_proj_bias 被拆分为 in_proj.weight / in_proj.bias 以匹配 nn.Linear 的参数字典。

4. Smoke 验证

python3 inference.py \
  --checkpoint ../PE-Lang-L14-448.pt \
  --device npu:0 \
  --batch-size 1 \
  --num-iterations 5 \
  --num-warmup 3

预期输出：

[PE-Lang] Model initialized: 291.42M parameters
[PE-Lang] Output shape: torch.Size([1, 1024]), dtype: torch.bfloat16
[PE-Lang] Inference complete. Embedding shape: torch.Size([1, 1024])

5. 性能参考

测试条件：Ascend 910B4，batch_size=1/2/4，bf16，warmup=10，iterations=50。

6. 精度评测

6.1 评测方法

以 CPU float32 推理结果为参考，对比 NPU bf16 推理结果，共 2 张随机测试图像，逐一计算每条输出（1024 维向量）的余弦相似度和相对误差。

6.2 评测结果

python3 eval.py

精度结论：PASSED ✅（相对误差均值 0.58%，最大误差 0.62%，均低于 1% 阈值）

6.3 精度误差分析

NPU bf16 相比 CPU float32 的微小误差（~0.6%）主要来源于：

1. 精度差异：NPU 使用 bfloat16（7 位尾数），CPU 使用 float32（23 位尾数），低位宽数值表示会引入量化误差
2. 算子实现差异：Ascend NPU 的算子（GEMM、Softmax、LayerNorm 等）在数学上等价，但浮点运算顺序和中间精度与 CPU 实现存在微小差异
3. 随机测试图像：测试使用随机生成的图像数据，非自然图像分布，可能放大数值差异

7. 完整评测流程

# 运行完整精度与性能评测（输出自动写入 log.txt）
python3 eval.py

8. 注意事项

1. 权重一致性：.pt 文件必须包含完整的模型权重（~582MB）。如果文件大小仅为 100+ 字节，说明是 LFS 指针文件，需通过 git lfs pull 或从 HuggingFace / ModelScope 手动下载真实权重文件。
2. NPU 内存：单卡 Ascend 910B4 可容纳 batch_size=32 以上的推理，无需内存优化。
3. 日志文件：eval.py 会在当前目录自动创建 log.txt，若重复运行建议先删除旧日志：rm -f log.txt。
4. kernel_meta 目录：首次运行会在目录下生成 kernel_meta/（NPU 算子编译缓存），属于正常现象，可忽略。