UFM-Refine-336 是卡内基梅隆大学发布的 UFM (UniFlowMatch) 系列的精修(refinement)模型(HF),出自论文 UFM: A Simple Path towards Unified Dense Correspondence with Flow (arXiv 2506.09278)。它是一个端到端训练的 Transformer 模型,直接回归像素位移场(光流),可同时服务于光流估计与宽基线匹配两类稠密对应任务。本权重为低分辨率(336×252)精修版本:以 DINOv2-Large 为编码器骨干,经全局注意力跨视图信息共享模块融合双视图特征,DPT 头输出光流场与协可见度(covisibility)置信度。
| 项 | 值 |
|---|---|
| 参数量 | ~0.5B(model.safetensors 约 1.9GB) |
| 架构 | DINOv2-Large 编码器 + global attention 信息共享 + DPT 双头(flow / uncertainty) |
| 推理分辨率 | 336×252 |
| 输入 | 图像对 (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 | - | 可视化与数据处理 |
依赖安装到独立目录(不污染共享环境):
pip install --target /mnt/workspace/UFM-Refine-336/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 至 /mnt/workspace/UFM-Refine-336/code,并克隆其子模块 https://github.com/castacks/UniCeption.git 至 /mnt/workspace/UFM-Refine-336/code/UniCeption(脚本自动加入 sys.path)。
模型权重:/home/developer/models/UFM-Refine-336
确认权重与依赖就位后,脚本会自动将 /mnt/workspace/UFM-Refine-336/libs、/mnt/workspace/UFM-Refine-336/code(含 UniCeption 子模块)与仓库目录加入 PYTHONPATH,无需手动设置。可用 npu-smi info 检查 NPU 设备状态。
python3 inference.py --model_path /home/developer/models/UFM-Refine-336脚本内置示例图像对(assets/fire_academy_*.png),只传 --model_path 即可跑通;设备自动选择(优先 NPU,不可用回退 CUDA/CPU),执行光流推理并打印耗时(耗时/elapsed 字段),结果图保存至 assets/model_result.png。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--model_path | str | /home/developer/models/UFM-Refine-336 | 模型权重目录 |
--device | str | 自动 (npu > cuda > cpu) | 指定推理设备 |
--output | str | assets/model_result.png | 结果图保存路径 |
输入为内置示例图像对(fire_academy 场景两帧,缩放至 252×336)。NPU 实测输出示例:
[INFO] device = npu
[INFO] model_path = /home/developer/models/UFM-Refine-336
[INFO] 模型加载完成 load_time=xx.xxs
[INFO] 推理完成 耗时/elapsed=x.xxs (input=336x252, device=npu)
[INFO] 光流输出形状: (2, 252, 336), 协可见度掩码形状: (252, 336)
[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-Refine-336/code 存在并已在 sys.path 中;pretrained_checkpoint_path 均为 null,离线加载不会触发额外下载;pip install --target 隔离安装到 /mnt/workspace/UFM-Refine-336/libs,勿直接装入共享环境。