Y
YYPGD/UFM-Base
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

UFM-Base 昇腾NPU适配

1. 模型简介

UFM-Base 是卡内基梅隆大学发布的 UFM (UniFlowMatch) 系列的基础(base)模型(HF),出自论文 UFM: A Simple Path towards Unified Dense Correspondence with Flow (arXiv 2506.09278)。它是一个端到端训练的 Transformer 模型,直接回归像素位移场(光流),可同时服务于光流估计与宽基线匹配两类稠密对应任务。本权重为基础版本(不含精修模块):以 DINOv2-Large 为编码器骨干,经全局注意力跨视图信息共享模块融合双视图特征,DPT 头输出光流场与协可见度(covisibility)置信度,推理分辨率 560×420。

项值
参数量~0.4B(model.safetensors 约 1.3GB)
架构DINOv2-Large 编码器 + global attention 信息共享 + DPT 双头(flow / uncertainty)
推理分辨率560×420 (W×H)
输入图像对 (B, 3, H, W),uint8 或 float32
输出光流场 (B, 2, H, W) + 协可见度掩码 (B, H, W)
任务类型稠密对应/光流估计(其他)

2. 环境依赖

依赖版本说明
Python3.10+推荐 3.11
torch>=2.0CPU/NPU 均可
torch_npu与 CANN 配套昇腾NPU支持
huggingface_hub-PyTorchModelHubMixin 权重加载
opencv-python-headless-图像读取与预处理
timm / einops / jaxtyping-UniCeption 模块依赖
flow_vis / matplotlib / numpy / Pillow / scikit-learn-可视化与数据处理

依赖已安装到独立目录 /mnt/workspace/UFM-Base/libs(不污染共享环境):

pip install --target /mnt/workspace/UFM-Base/libs \
    -i https://pypi.tuna.tsinghua.edu.cn/simple \
    huggingface_hub opencv-python-headless flow_vis einops timm jaxtyping Pillow scikit-learn matplotlib numpy

模型代码:克隆 https://github.com/UniFlowMatch/UFM(含子模块 UniCeption),将其中 uniflowmatch/ 与 UniCeption/uniception/ 包目录复制至 /mnt/workspace/UFM-Base/libs(脚本自动加入 sys.path)。

模型权重:/home/developer/models/UFM-Base

3. 推理步骤

3.1 环境准备

确认权重与依赖就位后,脚本会自动将 /mnt/workspace/UFM-Base/libs 与仓库目录加入 PYTHONPATH,无需手动设置。可用 npu-smi info 检查 NPU 设备状态。

3.2 运行推理

python3 inference.py --model_path /home/developer/models/UFM-Base

脚本内置示例图像对(assets/fire_academy_*.png),只传 --model_path 即可跑通;设备自动选择(优先 NPU,不可用回退 CUDA/CPU),执行光流推理并打印耗时(耗时/elapsed 字段),结果图保存至 assets/model_result.png。

3.3 推理参数说明

参数类型默认值说明
--model_pathstr/home/developer/models/UFM-Base模型权重目录
--devicestr自动 (npu > cuda > cpu)指定推理设备
--outputstrassets/model_result.png结果图保存路径

4. 测试样例及输出结果

输入为内置示例图像对(fire_academy 场景两帧,缩放至 420×560)。NPU 实测输出示例:

[INFO] device = npu
[INFO] model_path = /home/developer/models/UFM-Base
[INFO] 模型加载完成 load_time=xx.xxs params=xxx.xM
[INFO] 推理完成 耗时/elapsed=x.xxs (input=560x420, device=npu)
[INFO] 光流输出形状: (2, 420, 560), 协可见度掩码形状: (420, 560)
[RESULT] status=ok device=npu 耗时/elapsed=x.xxs

结果截图见 assets/model_result.png。

5. Agent适配截图

5.1 Agent适配全过程截图

见 assets/agent_workflow.png。

5.2 NPU设备调用截图

见 assets/npu_device_call.png。

5.3 模型适配结果截图

见 assets/model_result.png。

6. 注意事项

  • 设备自动选择顺序为 NPU → CUDA → CPU,NPU 不可用时自动回退,保证脚本可移植;
  • 输入张量必须 float32(NPU 不支持 float64 算子),脚本内部由模型接口完成 uint8→float32 归一化转换;
  • 注意力使用原生 eager/sdpa 实现(DINOv2 编码器默认 use_pytorch_sdpa=True),勿启用 flash_attention_2;
  • 该模型依赖官方 GitHub 仓库代码(uniflowmatch + UniCeption),非 transformers 原生架构,需保证 /mnt/workspace/UFM-Base/libs 中存在这两个包并已在 sys.path 中;
  • ⚠️ libs 内的 UniCeption DINOv2 编码器已做离线改造:构建网络结构时不再从 torch hub 下载 DINOv2 预训练权重(UFM 的 model.safetensors 已包含全部编码器权重,加载时会完整覆盖),因此完全离线环境也可加载;torch hub 缓存目录 ~/.cache/torch/hub/facebookresearch_dinov2_main 需保留(仅用于构建网络结构代码);
  • 权重通过 PyTorchModelHubMixin 加载,config.json 中各子模块 pretrained_checkpoint_path 均为 null;
  • 依赖通过 pip install --target 隔离安装到 /mnt/workspace/UFM-Base/libs,勿直接装入共享环境。