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) |
| 任务类型 | 稠密对应/光流估计(其他) |
| 依赖 | 版本 | 说明 |
|---|---|---|
| Python | 3.10+ | 推荐 3.11 |
| torch | >=2.0 | CPU/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
确认权重与依赖就位后,脚本会自动将 /mnt/workspace/UFM-Base/libs 与仓库目录加入 PYTHONPATH,无需手动设置。可用 npu-smi info 检查 NPU 设备状态。
python3 inference.py --model_path /home/developer/models/UFM-Base脚本内置示例图像对(assets/fire_academy_*.png),只传 --model_path 即可跑通;设备自动选择(优先 NPU,不可用回退 CUDA/CPU),执行光流推理并打印耗时(耗时/elapsed 字段),结果图保存至 assets/model_result.png。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--model_path | str | /home/developer/models/UFM-Base | 模型权重目录 |
--device | str | 自动 (npu > cuda > cpu) | 指定推理设备 |
--output | str | assets/model_result.png | 结果图保存路径 |
输入为内置示例图像对(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。
见 assets/agent_workflow.png。
见 assets/npu_device_call.png。
见 assets/model_result.png。
/mnt/workspace/UFM-Base/libs 中存在这两个包并已在 sys.path 中;~/.cache/torch/hub/facebookresearch_dinov2_main 需保留(仅用于构建网络结构代码);pretrained_checkpoint_path 均为 null;pip install --target 隔离安装到 /mnt/workspace/UFM-Base/libs,勿直接装入共享环境。