Video-Depth-Anything-Base-MLX API参考:VideoDepthPredictor全部参数与返回值详解
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 面非常小,核心记忆点只有三个:
- 构造:
VideoDepthPredictor(model, processor),两个对象都来自load() - 推理:
infer(frames)接受(B, T, H, W, 3)(H/W 为 14 的倍数),返回(T, H, W)float32 相对深度 - 读视频:
read_video_frames(path, max_len, target_fps)是配套的官方读帧工具
配合 config.json 中的模型参数,你可以根据 num_frames、out_channels 等配置评估不同硬件下的推理负载,在 Apple 芯片上流畅跑起视频深度估计。