企业官网建设流程全解析

• 人工智能
• 深度学习
• 计算机视觉
• 科研

导读：deeplabcut.merge_datasets是 DeepLabCut 标记数据精炼（refinement）流程中承上启下的核心 API。它负责将用户手动精炼后的异常帧标注合并回训练集，并把项目config.yaml中的iteration（迭代）号自动 +1，为重新生成训练集、重新训练网络做好准备。阅读本文后，你将掌握该函数在精炼工作流中的位置、其校验逻辑与参数语义，以及从extract_outlier_frames→refine_labels→merge_datasets→create_training_dataset的完整实战闭环。

一、函数定位：精炼迭代中的“合并”节点

DeepLabCut 的模型训练遵循“标注—训练—评估—精炼”的迭代循环。当网络在某段视频上预测不佳时，用户会先提取异常帧、在 GUI 中手动修正标签，最后调用merge_datasets把修正结果并入训练数据。官方用户指南将该步骤描述为：

“在修正了所有子目录中所有帧的标签之后，用户应合并数据集以创建新的数据集。在此步骤中，config.yaml文件中的iteration参数会被自动更新。”——见 docs/maDLC_UserGuide.md 与 docs/main-workflows/user-guide.md 中的 “Merge datasets” 章节。

该函数位于 deeplabcut/refine_training_dataset/outlier_frames.py，并通过 deeplabcut/init.py 以deeplabcut.merge_datasets的形式暴露为公开 API，同时被收录进 docs/HelperFunctions.md 的辅助函数清单。

二、函数签名与参数语义

merge_datasets的完整签名与 docstring 定义于 deeplabcut/refine_training_dataset/outlier_frames.py#L1027-L1045：

def merge_datasets(config: str | Path, forceiterate=None): """Merge the original training dataset with the newly refined data. Checks if the original training dataset can be merged with the newly refined training dataset. To do so it will check if the frames in all extracted video sets were relabeled. If this is the case then the ``"iteration"`` variable is advanced by 1. """

官方示例用法：

deeplabcut.merge_datasets("/analysis/project/reaching-task/config.yaml")

从源码看，该函数具有副作用：成功时会把iteration值写回config.yaml。配置的读取与回写分别经由 deeplabcut/core/config/utils.py 中的read_config/write_config完成；iteration字段本身则被定义在 deeplabcut/core/config/project_config.py 的ProjectConfig中（iteration: NonNegativeInt）。

三、合并前的校验逻辑：逐文件夹检查是否已精炼

merge_datasets的核心工作不是“搬文件”，而是校验。源码（outlier_frames.py#L1047-L1078）中的逻辑如下：

1. 读取config，定位项目根目录；
2. 遍历labeled-data/下的所有子文件夹，跳过名称含_labeled的文件夹以及以.开头的临时目录；
3. 对每个视频文件夹检查是否存在以下任一标记文件：
   • MachineLabelsRefine.h5—— 该文件夹已被手动精炼过；
   • CollectedData_<scorer>.h5—— 该文件夹包含人工标注数据（<scorer>即config.yaml中的scorer字段）；
4. 若存在任何文件夹两种标记文件都没有，则打印 “The following folder was not manually refined, ...”，并将内部标志flagged置为True；
5. 仅当所有文件夹都通过校验（flagged == False）时，才推进iteration：
   • forceiterate为真值时，cfg["iteration"] = forceiterate；
   • 否则cfg["iteration"] = int(iter_prev + 1)；
6. 写回配置，并打印提示：现在可以调用create_training_dataset为扩充后的标注图像创建新训练集。

若校验失败，函数会打印提示并要求用户补齐标注或删除未修正的文件夹，iteration不会被修改。也就是说：只要有一个视频文件夹的异常帧没有精炼，合并就不会发生，这保证了训练集不会混入未经人工确认的机器预测标签。

四、完整工作流：从异常帧提取到数据集合并

merge_datasets位于精炼链路末端，理解其上下文才能正确使用。推荐流程如下：

1. 提取异常帧

当网络预测在某视频上表现不佳时，先运行 extract_outlier_frames（实现位于 outlier_frames.py#L183-L209）：

deeplabcut.extract_outlier_frames(config_path, ["videofile_path"])

主用户指南（docs/main-workflows/user-guide.md）列出了可选的outlieralgorithm：

• "uncertain"：某关键点（或全部关键点）的似然低于p_bound时选中该帧；
• "jump"：某关键点（或全部）相较上一帧跳变超过epsilon像素时选中；
• "fitting"：对每个关键点的时间序列拟合 ARIMA 状态空间模型，预测点与拟合值平均偏差超过epsilon时选中；
• "manual"：人工目视挑选。

此外还可通过extractionalgorithm="uniform"（随机抽样）或"kmeans"（对候选帧做 k-means 聚类）从候选集中进一步挑选，实际提取数量受config.yaml中numframes2extract等参数约束。

2. 在 GUI 中精炼标签

对提取出的疑似异常帧，调用refine_labels（API 文档见 docs/api/deeplabcut.refine_labels.rst）启动标注 GUI：

deeplabcut.refine_labels(config_path)

根据 docs/maDLC_UserGuide.md，用户在 GUI 中会遇到四类情况：

• (A)可见关键点且预测准确 —— 无需修改；
• (B)可见关键点但预测错误 —— 将标签移动到实际位置；
• (C)不可见/被遮挡的关键点 —— 用中键删除预测标签（低似然预测以空心圆显示，便于识别）；
• (D)无效图像 —— 移除该图像及其预测。

3. 合并数据集

当所有提取视频文件夹的标签都精炼完成后，执行：

deeplabcut.merge_datasets(config_path)

成功合并后，iteration自动 +1。后续训练数据集会存放在新的iteration-#子目录下（#即更新后的iteration值），与旧迭代的数据完全隔离。

五、GUI 中的一键合并：GUI 项目页集成

除了脚本调用，merge_datasets也深度集成在 DeepLabCut 的 GUI 中。在 deeplabcut/gui/tabs/extract_outlier_frames.py 中：

• GUI 提供 “Merge data” 按钮（self.merge_data_button）；
• 点击后弹出警告对话框，文案为：“请确保在合并数据集前已精炼所有标签。若合并数据集，需要在开始训练前重新创建训练数据集。准备好合并数据集了吗？”
• 用户确认后执行deeplabcut.merge_datasets(self.root.config_path, forceiterate=None)。

这验证了官方对merge_datasets的预期用法：它不是一个可以随意重复调用的工具，而是精炼阶段结束后的一次性提交动作。GUI 集成还出现在 deeplabcut/gui/tabs/refine_tracklets.py 中，用于追踪片段精炼后的数据合并。

六、合并之后：验证与新一轮训练

docs/maDLC_UserGuide.md 明确给出了合并后的标准后续动作：

1. 验证合并结果：通过“Plot Labels”步骤绘制全部标签，确认合并成功（对应check_labels相关 API，见 deeplabcut/generate_training_dataset 模块）；
2. 重新创建训练集：调用create_training_dataset，扩充后的标注图像会生成新的训练/测试划分，并存放于新的iteration-#目录；
3. 重新训练网络：调用train_network。指南特别建议：若原始标签有任何调整，应从全新权重开始训练（一般推荐）；否则可考虑沿用已训练好的网络权重继续训练；
4. 评估泛化：若新模型在数据上泛化良好，即可分析新视频；否则考虑继续标注更多数据，进入下一轮精炼迭代。

七、实践要点与常见问题

• 路径必须是项目config.yaml的完整路径：函数内部依赖Path(config).parents[0]定位labeled-data/目录，传错路径将导致校验失败或FileNotFoundError。
• 迭代号自增是幂等性风险点：正常流程下每次精炼只应调用一次；若需要把迭代号直接跳到指定值（例如从第 0 次直接跳到第 2 次），使用forceiterate=2，但该参数仅在所有数据集都已精炼时才生效。
• _labeled与隐藏目录会被跳过：以.开头的临时文件（如.DS_Store）以及含_labeled后缀的文件夹不会参与校验，避免误报“未精炼”。
• 合并≠拷贝文件：从源码可见，merge_datasets本身不做帧图像的物理搬运，它的职责是“确认所有视频的标签都经过人工确认”，然后通过更新iteration让后续create_training_dataset在新的迭代目录下重新组织数据集。
• 多动物（maDLC）项目同样适用：merge_datasets与单动物流程共用同一实现，精炼后的MachineLabelsRefine.h5机制对单/多动物项目一致，maDLC 专属的迭代目录与 shuffle 结构说明可参见 docs/maDLC_UserGuide.md。

八、小结

deeplabcut.merge_datasets(config, forceiterate=None)是 DeepLabCut 数据精炼循环的“提交点”：它通过逐文件夹校验MachineLabelsRefine.h5或CollectedData_<scorer>.h5的存在性，确保所有提取的异常帧都经过人工精炼，然后将config.yaml的iteration自增并写回，从而触发下一轮训练数据集与模型的版本隔离。无论通过 Python API 调用，还是点击 GUI 中的 “Merge data” 按钮，其语义完全一致。掌握它，你就能在“训练效果不佳 → 提取异常帧 → 精炼 → 合并 → 重训”的闭环中顺畅迭代，持续提升模型在目标实验场景下的姿态估计精度。

• 人工智能
• 深度学习
• 计算机视觉
• 科研