DeepLabCut 快速入门指南：高层标准 API 与 PyTorch 底层接口实战

DeepLabCut 官方仓库（deeplabcut）在 3.0 版本中引入了 PyTorch 引擎，与既有的 TensorFlow 工作流并行。本文以官方开发文档 dev-docs/docs/get-started/quickstart.md 为骨架，完整讲解两种接入方式：面向大多数用户的高层标准 API（引擎无关、零迁移成本）和面向进阶用户的底层 PyTorch API（直接控制数据加载、训练器与推理流程），并附带如何查询可用模型与检测器。读完本文，你将能够用 10 行以内的代码跑通"建训练集 → 训练 → 评估 → 视频分析"完整链路，也能按需切换到 PyTorch 底层接口精细控制训练参数。

两种接入方式：高层标准 API 与底层 PyTorch API

DeepLabCut 的 PyTorch 后端位于 deeplabcut.pose_estimation_pytorch 包内，而顶层 deeplabcut 命名空间会对两种引擎做统一分发。引擎的定义可以在 deeplabcut/core/engine.py 中看到：PyTorch 引擎对应的模型目录名为 dlc-models-pytorch、模型配置文件名为 pytorch_config.yaml、评估结果目录为 evaluation-results-pytorch，而 TensorFlow 引擎则沿用 dlc-models、pose_cfg.yaml 与 evaluation-results。这意味着两种引擎在同一项目目录下互不干扰。

选择哪种接口取决于你的需求：

• 高层标准 API：与旧版 DeepLabCut 完全一致，PyTorch 模型可以"无缝"接入既有工作流，适合绝大多数训练与推理场景；
• 底层 PyTorch API：直接操作 DLCLoader、训练器（runner）与配置字典，适合需要自定义数据增强、多卡训练、恢复训练（snapshot 续训）或精细调参的进阶用户。

高层标准 API：无缝复用现有 DeepLabCut 工作流

官方文档给出的高层用法与经典 DeepLabCut 完全一致：

import deeplabcut

config = "/path/to/project/config.yaml"

# Standard workflow works with both engines
deeplabcut.create_training_dataset(config)
deeplabcut.train_network(config, shuffle=1)
deeplabcut.evaluate_network(config, shuffle=[1])
deeplabcut.analyze_videos(config, videos=["/path/to/video.mp4"])

引擎的选择在创建训练集时通过 engine 参数确定；未显式指定时由项目配置与可用框架自动推断。单动物项目与多动物追踪的完整操作指南分别见 docs/standardDeepLabCut_UserGuide.md 与 docs/maDLC_UserGuide.md。

create_training_dataset：划分训练/测试集并生成模型配置

该函数定义于 deeplabcut/generate_training_dataset/trainingsetmanipulation.py。它会将已标注帧的标签合并为单个 .h5 文件，并按 TrainingFraction 切分训练/测试集。除 config 外，常用参数包括：

• num_shuffles：创建多少个 shuffle（默认 1）；
• Shuffles：也可直接传入 shuffle 列表，例如 [1, 2, 3]；
• net_type：指定网络类型，PyTorch 引擎下取值须为 available_models() 中的成员（详见下文）；
• engine：Engine.PYTORCH / Engine.TENSORFLOW，决定生成哪套模型配置；
• superanimal_name、weight_init：用于从 SuperAnimal 预训练模型初始化，ctd_conditions 则用于配置 CTD（conditional top-down）模型的条件来源。

创建训练集时会同步生成 dlc-models-pytorch/.../train/pytorch_config.yaml，这是后续训练与推理的核心配置文件。

train_network：训练网络

高层入口 deeplabcut.train_network 内部会构造一个 DLCLoader 并路由到 PyTorch 后端，其完整签名在 deeplabcut/pose_estimation_pytorch/apis/training.py。除了 config 与 shuffle，值得关注的高阶参数：

• snapshot_path / detector_path：分别指定恢复训练的 pose 快照与（top-down 模型的）检测器快照；
• load_head_weights：续训时是否加载模型 head 权重（等价于 TensorFlow 的 keepdeconvweights）。如果改变了 bodypart 数量，必须设为 False；
• batch_size / epochs / save_epochs / display_iters：直接覆盖 pytorch_config.yaml 中的对应训练设置；
• detector_batch_size / detector_epochs / detector_save_epochs：仅对 top-down 模型生效的检测器训练覆盖项（detector_epochs=0 表示不训练检测器）；
• pytorch_cfg_updates：以"点路径"字典形式任意覆盖配置，例如 {"runner.gpus": [0, 1, 2, 3]}。

底层实现中，若 train_settings 里配置了 weight_init 且启用 memory replay，还会调用 deeplabcut/pose_estimation_pytorch/modelzoo/memory_replay.py 先为 SuperAnimal 微调生成伪标签数据集。

evaluate_network：评估快照

评估入口定义于 deeplabcut/pose_estimation_pytorch/apis/evaluation.py，结果写入 evaluation-results-pytorch 目录下的 .h5 与 .csv 文件。常用参数：

• shuffles：要评估的 shuffle 列表（文档示例中传 [1]）；
• snapshotindex：要评估的快照索引，-1 表示最后一个，"all" 表示全部；
• snapshots_to_evaluate：直接给出快照名列表（如 ["snapshot-50", "snapshot-75"]），此时忽略 snapshotindex；
• plotting：在训练/测试图像上绘制预测，可取 True、"bodypart"、"individual"；
• per_keypoint_evaluation：逐关键点计算 RMSE 并输出 {model_name}-keypoint-results.csv；
• pcutoff：计算指标时的置信度截断值，可传标量、逐 bodypart 列表或字典。

analyze_videos：视频推理

deeplabcut.analyze_videos 路由到 PyTorch 后端的同名函数，完整定义见 deeplabcut/pose_estimation_pytorch/apis/videos.py。它的参数非常丰富，几个关键项：

• videos：单个视频路径、路径列表，或一个目录（目录模式下按 video_extensions 过滤，如 "mp4" 或 ["mp4", "avi"]）；
• snapshot_index / detector_snapshot_index：选择用于推理的 pose 快照与检测器快照；
• destfolder：分析结果输出目录，不传则写在视频同目录；注意后续分析也要传入同一目录；
• dynamic：(state, detection threshold, margin) 三元组，开启动态裁剪可显著加速长视频推理；
• ctd_conditions / ctd_tracking：CTD 模型的专有配置，前者指定用于生成条件的 BU 模型，后者让 CTD 模型直接做个体跟踪；
• auto_track / n_tracks：多动物项目自动追踪与指定轨迹数；
• save_as_csv：多动物项目在 auto_track=True 时顺带把轨迹存为 CSV。

底层 PyTorch API：直接操控训练与推理

当需要比高层 API 更细的控制粒度时，可以直接导入 PyTorch 后端：

import deeplabcut.pose_estimation_pytorch as dlc_torch

# Create a data loader
loader = dlc_torch.DLCLoader(
    config="/path/to/project/config.yaml",
    trainset_index=0,
    shuffle=1,
)

DLCLoader：项目数据加载器

DLCLoader 定义于 deeplabcut/pose_estimation_pytorch/data/dlcloader.py，接受 config（项目 config.yaml 路径）、trainset_index（使用 TrainingFraction 列表中的第几个切分）、shuffle 与 modelprefix。它负责解析项目配置、定位 PyTorch 模型目录与 pytorch_config.yaml，并惰性加载训练/测试集切分与标注 DataFrame。通过 loader.model_cfg 可以访问完整的 PyTorch 模型配置（PoseConfig），通过 loader.project_cfg 访问项目配置。

调用训练并正确传入 epoch/batch 参数

文档中的底层训练示例为：

dlc_torch.train(
    loader=loader,
    run_config=loader.model_cfg,
    task=loader.pose_task,
    device="cuda",
    max_epochs=200,
    batch_size=8,
)

需要说明的是：按当前源码（deeplabcut/pose_estimation_pytorch/apis/training.py），train() 的签名参数为 loader, run_config, task, device, gpus, logger_config, snapshot_path, transform, inference_transform, max_snapshots_to_keep, load_head_weights，max_epochs 与 batch_size 并不在签名中，它们属于 run_config["train_settings"]。正确的做法是先修改配置再传入，例如：

from deeplabcut.pose_estimation_pytorch.task import Task

loader.model_cfg.train_settings.epochs = 200
loader.model_cfg.train_settings.batch_size = 8
loader.model_cfg.train_settings.dataloader_workers = 4

dlc_torch.train(
    loader=loader,
    run_config=loader.model_cfg,
    task=Task(loader.model_cfg.get("method", "bu")),  # 从配置推导任务类型
    device="cuda",
)

从实现上看，train() 会依次完成：根据 weight_init/snapshot_path 决定是否使用预训练主干权重 → 构建模型（Task.DETECT 走 DETECTORS.build，其余走 PoseModel.build）→ 解析设备（device="auto" 时调用 resolve_device）→ 构建训练/验证 DataLoader（batch_size、dataloader_workers、dataloader_pin_memory 均来自 train_settings）→ 交给 build_training_runner 返回的 runner 执行 fit。

其中设备解析逻辑见 deeplabcut/pose_estimation_pytorch/utils.py：设置为 "auto" 时，优先选择 cuda:0（NVIDIA GPU），macOS 下且网络类型包含 resnet 时选择 mps，否则回退 cpu。代码中还特别注明：Task.DETECT 目前不支持在 MPS 上训练检测器（会自动降级为 CPU）。

关于 task：Task 枚举包含 BOTTOM_UP、TOP_DOWN、COND_TOP_DOWN、DETECT 等成员，高层入口 train_network 正是通过 Task(loader.model_cfg.get("method", "bu")) 推导的，你也可以直接按此方式传入。

底层视频推理

底层 API 直接复用同一个推理函数：

predictions = dlc_torch.analyze_videos(
    config="/path/to/project/config.yaml",
    videos=["/path/to/video.mp4"],
    shuffle=1,
)

它与高层 deeplabcut.analyze_videos 是同一个实现，返回预测 DataFrame 并默认在视频同目录（或 destfolder）写出结果。

查询可用模型与检测器

官方文档提供了两个便捷函数：

from deeplabcut.pose_estimation_pytorch import available_models, available_detectors

# List all pose estimation models
models = available_models()
print(models)

# List all object detectors (for top-down models)
detectors = available_detectors()
print(detectors)

这两个函数定义于 deeplabcut/pose_estimation_pytorch/config/utils.py。available_models() 的逻辑是：扫描 backbones/ 目录下的所有 YAML 得到主干名（如 hrnet_w18），对每个主干同时注册 top_down_<backbone> 变体，再遍历 ctd/、dekr/、dlcrnet/、rtmpose/、animaltokenpose/ 等架构目录，把其中每个 YAML 变体都加入列表。available_detectors() 则直接读取 detectors/ 目录。

以当前仓库实际配置文件（deeplabcut/pose_estimation_pytorch/config）为准，你可以获得的模型包括：

• 主干网络（backbones）：hrnet_w18、hrnet_w32、hrnet_w48、resnet_50、resnet_101、cspnext_s/m/x；
• 完整架构：dlcrnet_stride16_ms5、dlcrnet_stride32_ms5（bottom-up 的 DLCRNet）、dekr_w18/w32/w48、rtmpose_s/m/x、ctd_coam_w32/w48、ctd_prenet_hrnet_w32/w48、ctd_prenet_rtmpose_s/m/x 等；
• 检测器（detectors，供 top-down 模型使用）：fasterrcnn_mobilenet_v3_large_fpn、fasterrcnn_resnet50_fpn_v2、ssdlite。

注意：文档示例注释中列出的输出（如 dlcrnet_ms5、yolox_s）仅为示意，实际可用列表以你本仓库 config/ 目录下真实存在的 YAML 文件为准——这也是建议你在项目中先调用 available_models() 打印一遍的原因。

与查询配套的还有两个判断函数（同样位于 config/utils.py）：

• is_model_top_down(net_type)：判断某个模型是否为 top-down 架构（名字以 top_down_ 开头，或配置文件 method 为 "TD"）；
• is_model_cond_top_down(net_type)：判断是否为 CTD 条件 top-down 模型（名字以 ctd_ 开头）。

这两个函数在推理管线中选择动态裁剪策略、决定是否需要检测器时都会被内部调用。

从模型配置文件读懂网络结构

如果你想进一步理解某个模型到底长什么样，可以直接查看它的 YAML 配置。以 deeplabcut/pose_estimation_pytorch/config/dlcrnet/dlcrnet_stride16_ms5.yaml 为例，它完整描述了：

• model.backbone：DLCRNet 主干，model_name: resnet50、output_stride: 16，主干输出 2304 通道；
• model.heads：bodypart head 使用 DLCRNetHead，其中 PartAffinityFieldPredictor 负责 PAF 亲和场预测（num_animals、num_multibodyparts 会按项目 bodypart/个体数自动解析），HeatmapPlateauGenerator 生成热图与 locref，PartAffinityFieldGenerator 生成 PAF 标签；
• criterion：热图用 WeightedBCECriterion（权重 1.0），locref 与 PAF 均用 WeightedHuberCriterion（权重 0.05 / 0.1）。

这些配置项由 deeplabcut/pose_estimation_pytorch/config 下的 base/、make_pose_config.py 等模块在创建训练集时合并进项目的 pytorch_config.yaml，属于进阶用户调参的入口。

小结

• 快速上手：优先使用高层 API，四行代码即可完成"训练集 → 训练 → 评估 → 视频分析"，且 PyTorch 与 TensorFlow 两种引擎可并行切换，无需改动调用习惯；
• 精细控制：需要自定义 epoch、batch size、数据增强、多卡训练或续训时，切换到 DLCLoader + dlc_torch.train 底层接口，所有可调项都集中在 pytorch_config.yaml 中；
• 选型参考：用 available_models() / available_detectors() 枚举当前安装支持的模型与检测器，用 is_model_top_down() / is_model_cond_top_down() 判断架构类型，再配合 pytorch_config.yaml 决定网络结构。

无论选择哪条路径，项目配置文件（config.yaml 与 dlc-models-pytorch/.../train/pytorch_config.yaml）都是核心枢纽——前者描述标注与数据划分，后者描述网络结构与训练超参，理解两者的分工，就能在 DeepLabCut 的 PyTorch 工作流中自由进出。