Video-Depth-Anything-Base-MLX API参考:VideoDepthPredictor全部参数与返回值详解

原创2026-10-17 09:11:211,937 阅读

Video-Depth-Anything-Base-MLX API参考:VideoDepthPredictor全部参数与返回值详解

本文是 Video-Depth-Anything-Base-MLX 的 API 参考指南。该项目是字节跳动 Video Depth Anything(CVPR 2025 高亮论文)的 MLX 深度估计模型移植版,能够对任意长度的视频做一致的单目深度估计(monocular depth estimation)。文中逐一讲解 VideoDepthPredictor 的构造参数、infer 方法、辅助函数 read_video_frames 以及模型配置文件,帮助新手快速上手苹果芯片上的视频深度估计。

30 秒快速上手

整个调用流程只需要四行代码:加载模型 → 创建预测器 → 读取视频帧 → 推理出深度。

from mlx_vlm import load
from mlx_vlm.models.video_depth_anything.generate import (
    VideoDepthPredictor,
    read_video_frames,
)

model, processor = load("mlx-community/Video-Depth-Anything-Base-MLX")
predictor = VideoDepthPredictor(model, processor)

frames, fps = read_video_frames("input.mp4", max_len=300, target_fps=15)
depths = predictor.infer(frames)  # 返回 (T, H, W) float32

该模型架构为 DINOv2 主干 + DPT 解码头 + AnimateDiff 风格时序运动模块,逐帧输出深度图(depth map),而非文本结果。

VideoDepthPredictor 类详解

构造函数参数

VideoDepthPredictor(model, processor)
参数 类型 说明
model 已加载的 MLX 模型 通过 load() 加载本仓库后得到的第一个返回值,内部为 fp32 权重
processor 预处理器 load() 返回的第二个对象,负责按 preprocessor_config.json 中的 input_size: 518 对输入帧做尺寸处理

返回值:一个预测器实例,后续通过它调用 infer 方法。

infer 方法

depths = predictor.infer(frames)

输入参数 frames:

属性 要求
形状 channel-last 格式 (B, T, H, W, 3),即「批, 帧, 高, 宽, 通道」
高 / 宽 必须是 14 的整数倍(DINOv2 主干的下采样约束)
数据类型 浮点图像数据(由 read_video_frames 返回,可放心直接传入)

返回值:

项 说明
类型 float32 张量
形状 (T, H, W),每帧一张深度图
含义 相对深度(本模型 metric: false,输出不是米制绝对深度)
时序一致性 非 metric 模型会跳过 scale/shift 窗口对齐,保证整段视频深度连贯

精度表现(来自 README.md 的 Notes 一节):

  • GPU(Metal)上结果与 PyTorch 参考实现相对误差约 1%(fast-math 影响)
  • CPU 上相对误差约 1e-5

辅助函数 read_video_frames 详解

read_video_frames 与 VideoDepthPredictor 位于同一模块 mlx_vlm.models.video_depth_anything.generate,负责把视频文件转成可直接推理的帧序列。

frames, fps = read_video_frames("input.mp4", max_len=300, target_fps=15)
参数 默认/示例值 说明
视频路径 "input.mp4" 待处理的视频文件
max_len 300 最多读取的帧数,控制显存/内存占用;"任意长视频"能力就是靠分段处理实现的
target_fps 15 目标帧率,对原视频做重采样,减少冗余帧

返回值:两个值——frames(送入 infer 的帧张量)和 fps(实际采样帧率,可用于后续合成深度视频)。

模型配置参数(config.json)

仓库根目录的 config.json 定义了模型结构,了解这些参数有助于你判断输出行为:

配置项 值 含义
model_type video_depth_anything 模型家族标识
encoder vitb Base 规格 ViT 编码器(本仓库为 Base 版本)
metric false ⚠️ 非度量模型,输出相对深度;度量模型才输出米制绝对深度并跳过窗口对齐
features 128 主干特征维度
out_channels [96, 192, 384, 768] DPT 解码头各级输出通道数
num_frames 32 时序模块单次处理的帧数窗口
pe ape 位置编码类型(Absolute Positional Encoding)

预处理配置见 preprocessor_config.json:input_size 为 518,即输入会被统一缩放到 518 像素(恰好是 14 的整数倍)。模型权重文件为 model.safetensors(fp32 格式)。

新手常见问题 FAQ

Q1:为什么 H 和 W 必须是 14 的整数倍? A:DINOv2 主干经过多级 2× 下采样,14 = 2 × 7,不满足会直接报错。用 read_video_frames + processor 的默认流程即可自动规避。

Q2:输出是绝对深度吗?能用它做 3D 重建吗? A:本模型 metric: false,输出的是相对深度,同一场景内帧间比例一致,适合深度可视化、背景虚化、视差效果;需要米制深度请寻找 metric 版本模型。

Q3:长视频会爆内存吗? A:用 max_len 限制帧数、用 target_fps 降低帧率即可;模型本身支持任意长度视频的流式处理。

Q4:商用可以用吗? A:注意本仓库沿用官方检查点许可,为 CC-BY-NC-4.0,仅限非商业用途(见 README.md 的 License 一节)。

小结

VideoDepthPredictor 的 API 面非常小,核心记忆点只有三个:

  1. 构造:VideoDepthPredictor(model, processor),两个对象都来自 load()
  2. 推理:infer(frames) 接受 (B, T, H, W, 3)(H/W 为 14 的倍数),返回 (T, H, W) float32 相对深度
  3. 读视频:read_video_frames(path, max_len, target_fps) 是配套的官方读帧工具

配合 config.json 中的模型参数,你可以根据 num_frames、out_channels 等配置评估不同硬件下的推理负载,在 Apple 芯片上流畅跑起视频深度估计。

登录后查看全文
Video-Depth-Anything-Base-MLX