企业官网建设流程全解析

• 深度学习
• 计算机视觉
• NLP
• 多模态
• 模型训练
• 大模型

本文以 CoreNet 仓库中 CatLIP 多标签图像分类指南 为主线，完整介绍如何将 CatLIP 预训练的 ViT-B/ViT-L 在 COCO 数据集上微调为 80 类多标签分类模型，并给出评估命令、复现指标、预训练权重列表，以及配置文件逐项拆解与底层源码原理。

CoreNet（CoreNet: A library for training deep neural networks）提供了一整套训练与评估深度神经网络的工程化框架。其中 CatLIP（CLIP-level Visual Recognition Accuracy with 2.7x Faster Pre-training on Web-scale Image-Text Data）提出了一种弱监督预训练方案：把大规模图文预训练重新建模为分类任务，规避对比学习中逐对相似度计算的算力瓶颈，从而在保持高质量视觉表征的同时显著加速预训练。本文聚焦 CatLIP 的下游任务之一——COCO 多标签图像分类，手把手带你在四卡 A100 上复现 ViT-B 微调，完成验证集评估并对照官方预训练权重精度。

一、任务背景：什么是 COCO 多标签分类

COCO（Common Objects in Context）2017 数据集通常被用于目标检测与实例分割，但它的标注同样可以转化为多标签图像分类任务：一张图片中可能同时出现多个物体类别，模型需要输出每个类别的存在概率，而非单标签分类的互斥 one-hot 输出。CoreNet 为此在分类任务族中专门实现了COCOClassification数据集类，注册名为"coco"，对应实现位于 corenet/data/datasets/classification/coco.py。

该数据集类在__getitem__中构建多标签目标，其处理逻辑值得细读：

• 通过pycocotools读取annotations/instances_train2017.json（训练）或annotations/instances_val2017.json（验证）；
• 将标注按目标面积分组：area < 32×32为小物体，32×32 <= area < 96×96为中物体，其余为大物体；
• 对每个类别，在这三个尺度分组的标签上取最大值（target.amax(dim=0)），从而把检测框标注聚合为 80 维的 0/1 多标签向量；
• n_classes为 80，class_names列表覆盖 person、bicycle、car……toothbrush 共 80 个 COCO 类别（见 coco.py）。

因此，评估多标签分类效果时不能使用单标签的 Top-1/Top-5 准确率，而应使用平均精度（Average Precision）类指标，这一点在下面的评估章节会具体展开。

二、在 COCO 上微调 CatLIP 预训练模型

官方指南给出的微调命令非常简洁，前提是你已经安装好 CoreNet（pip install .后即可获得corenet-train/corenet-eval等命令行入口，入口映射定义在 corenet/cli/entrypoints.py）：

export CFG_FILE=projects/catlip/multi_label_image_classification/vit_base.yaml corenet-train --common.config-file $CFG_FILE --common.results-loc classification_results

官方默认假设训练与验证数据位于/mnt/vision_datasets/coco，目录结构需符合 COCO 官方布局：annotations/instances_{train|val}2017.json与images/{train|val}2017。如果你的数据不在该路径，可以通过--common.override-kwargs dataset.root_train=... dataset.root_val=...覆盖。

2.1 配置解读：vit_base.yaml 逐项剖析

微调行为完全由 vit_base.yaml 决定，下面按配置块逐一解释，并注明其对应的源码实现。

common 段：训练基础设施

common: run_label: "train" log_freq: 500 auto_resume: true mixed_precision: true mixed_precision_dtype: "bfloat16" grad_clip: 1.0 save_all_checkpoints: true

• mixed_precision_dtype: "bfloat16"：在 A100 上使用 BF16 混合精度训练，兼顾显存与数值稳定性；
• grad_clip: 1.0：梯度裁剪阈值 1.0，防止训练早期梯度爆炸；
• auto_resume: true：若结果目录存在中断的 checkpoint，自动断点续训；
• save_all_checkpoints: true：保存每个 epoch 的 checkpoint，方便回溯。

dataset 段：数据与批大小

dataset: root_train: "/mnt/vision_datasets/coco" root_val: "/mnt/vision_datasets/coco" # effective batch size is 128 (32 * 4 A100 80 GB GPU) train_batch_size0: 32 val_batch_size0: 50 eval_batch_size0: 50 workers: -1 # use all CPUs persistent_workers: true pin_memory: true name: "coco" category: "classification"

• train_batch_size0: 32表示单卡批大小，4 卡 A100 的有效批大小为 32×4=128（配置注释也明确标注了这一点）；如果你的 GPU 数量不同，需按batch_size0 × GPU 数推算有效批大小；
• workers: -1表示使用全部 CPU 核心做数据加载，persistent_workers与pin_memory分别开启常驻加载进程与锁页内存，提升吞吐。

image_augmentation 段：训练/评估数据增强

image_augmentation: random_resized_crop: enable: true interpolation: "bilinear" random_horizontal_flip: enable: true resize: enable: true size: 512 interpolation: "bilinear" center_crop: enable: true size: 512

训练阶段使用随机裁剪与水平翻转，评估阶段使用 resize 到 512 后 center crop 到 512。训练与验证的变换分别由 coco.py 中的_training_transforms与_validation_transforms提供（内部复用了BaseImageClassificationDataset的默认变换）。

sampler 段：可变批大小多尺度采样

sampler: name: "variable_batch_sampler" vbs: crop_size_width: 512 crop_size_height: 512 max_n_scales: 25 min_crop_size_width: 256 max_crop_size_width: 768 min_crop_size_height: 256 max_crop_size_height: 768 check_scale: 16

这里使用的是VariableBatchSampler（实现于 corenet/data/sampler/variable_batch_sampler.py）：每个 batch 在保持总计算量基本恒定的前提下，动态改变空间分辨率与批大小（即多尺度训练）。min/max_crop_size_*定义了 256~768 的尺度搜索区间，max_n_scales: 25表示最多采样 25 种尺度，check_scale: 16表示分辨率按 16 的倍数对齐。多尺度训练有助于提升模型对不同分辨率输入的鲁棒性。

loss 段：复合损失（BCE + 神经增强）

loss: category: "composite_loss" composite_loss: - loss_category: "classification" loss_weight: 1.0 classification: name: "binary_cross_entropy" binary_cross_entropy: reduction: "batch_mean" - loss_category: "neural_augmentation" loss_weight: 1.0 neural_augmentation: perceptual_metric: "psnr" target_value: [ 40, 20 ] curriculum_method: "cosine"

多标签分类的主损失是二元交叉熵（BCE），对应实现 corenet/loss_fn/classification/binary_cross_entropy.py。BinaryCrossEntropy使用binary_cross_entropy_with_logits，并对[B, C]形状的 logits 与 0/1 目标逐元素计算；reduction: "batch_mean"表示先对 batch 内所有元素求和，再除以第一维（batch size），等价于对每张图片的 80 类损失求平均。--loss.classification.binary-cross-entropy.reduction的合法取值包括sum / mean / none / batch_mean（默认mean），见该文件add_arguments。

第二个损失是NeuralAugmentation（RangeAugment 论文中的可学习增强损失，实现于 corenet/loss_fn/neural_augmentation.py）：

• perceptual_metric: "psnr"：用 PSNR 感知指标衡量原图与增强图差异；
• target_value: [40, 20]：目标 PSNR 从 40 逐渐下降到 20（即增强强度从弱到强），代码先把 PSNR 按MSE = 10^((20·log10(255) − PSNR)/10)换算为目标 MSE；
• curriculum_method: "cosine"：用余弦课程学习在训练期间平滑调度目标值，对应cosine_curriculum实现（neural_augmentation.py）。

composite_loss会把上述两个损失按loss_weight加权求和，这正是CompositeLoss的设计用途（见 corenet/loss_fn/composite_loss.py）。

optim / scheduler 段：优化器与学习率

optim: name: "adamw" weight_decay: 0.05 no_decay_bn_filter_bias: true adamw: beta1: 0.9 beta2: 0.999 scheduler: name: "cosine" max_epochs: 10 warmup_iterations: 500 warmup_init_lr: 1.e-6 cosine: max_lr: 0.00001 min_lr: 0.000001

• AdamW 优化器，权重衰减 0.05，且对 BN 参数与 bias 不施加衰减（no_decay_bn_filter_bias）；
• 余弦学习率调度：仅微调 10 个 epoch，先 warmup 500 步（初始学习率 1e-6），最大学习率 1e-5，最小学习率 1e-6。如此低的学习率与较短的训练周期体现了「微调大预训练模型」的常见策略。

model 段：模型结构与权重加载

model: activation_checkpointing: true # The number of classes in pre-trained model are 24320 while COCO has 80 classes. # so, we exclude the classifier while loading the pre-trained weights resume_exclude_scopes: [ "classifier" ] classification: name: "vit" n_classes: 80 pretrained: https://docs-assets.developer.apple.com/ml-research/models/corenet/v0.1.0/catlip/pretrained_models/vit_base.pt vit: mode: "base" norm_layer: "layer_norm_fp32" use_flash_attention: true learn_augmentation: brightness: true contrast: true noise: true mode: "distribution" activation: name: "gelu" layer: conv_init: "kaiming_normal" linear_init: "trunc_normal" linear_init_std_dev: 0.02

• 模型为 ViT-B/16，输入分类头n_classes: 80；
• 关键细节：CatLIP 预训练模型分类头有24320 个类别（ImageNet 21k 规模），而 COCO 只有 80 类，因此加载权重时必须用resume_exclude_scopes: ["classifier"]排除分类头、只加载骨干权重。这一点与配置注释完全一致，是微调成功与否的关键；
• use_flash_attention: true在 A100 上启用 FlashAttention 加速；
• learn_augmentation开启 brightness/contrast/noise 三个可学习增强算子，mode: "distribution"对应 RangeAugment 的分布式增强采样；
• norm_layer: "layer_norm_fp32"表示 LayerNorm 以 FP32 计算，避免混合精度下的数值不稳定。

ema / stats 段：指数滑动平均与监控指标

ema: enable: true momentum: 0.0005 stats: train: [ "loss" ] val: [ "loss" , "multiclass_classification_pr(pred=logits)"] checkpoint_metric: "multiclass_classification_pr(pred=logits).macro" checkpoint_metric_max: true metrics: multiclass_classification_pr: suppress_warnings: true

• 开启 EMA（指数滑动平均，动量 0.0005），通常能带来更稳的验证精度；
• 验证阶段跟踪multiclass_classification_pr(pred=logits)指标，并以其中的macro 平均精度作为 checkpoint 选择依据（checkpoint_metric_max: true表示越大越好）。

2.2 ViT-L 变体

如需更大的模型，可直接改用 vit_large.yaml。与 vit_base.yaml 相比，主要差异为model.classification.vit.mode: "large"、预训练权重换成vit_large.pt，以及验证批大小改为 32（val_batch_size0 / eval_batch_size0: 32），其余配置（10 epoch、AdamW、BCE+NeuralAugmentation、EMA、multiclass PR 指标等）完全一致。

2.3 覆盖配置的通用方式

corenet-train支持通过--common.override-kwargs以「点分路径」方式覆盖 YAML 中的任意配置，例如：

corenet-train \ --common.config-file projects/catlip/multi_label_image_classification/vit_base.yaml \ --common.override-kwargs dataset.root_train=/path/to/coco \ dataset.root_val=/path/to/coco \ scheduler.max_epochs=12

三、在 COCO 验证集上评估

微调完成后（或直接使用官方预训练权重），用下面的命令在 COCO val2017 上评估 ViT-B：

export CFG_FILE=projects/catlip/multi_label_image_classification/vit_base.yaml export DATASET_PATH="/mnt/vision_datasets/coco" # change to the COCO validation path export MODEL_WEIGHTS=https://docs-assets.developer.apple.com/ml-research/models/corenet/v0.1.0/catlip/multi-label-classification/coco/vit_base.pt CUDA_VISIBLE_DEVICES=0 corenet-eval --common.config-file $CFG_FILE --common.override-kwargs dataset.root_val=$DATASET_PATH model.classification.pretrained=$MODEL_WEIGHTS model.resume_exclude_scopes=''

要点说明：

• 评估阶段通过--common.override-kwargs覆盖两处配置：一是把dataset.root_val指向你的 COCO 验证集路径；二是用 COCO 微调后的权重替换预训练权重，并把model.resume_exclude_scopes置为空字符串''——因为微调权重本身就包含 80 类分类头，无需再排除任何 scope；
• CUDA_VISIBLE_DEVICES=0指定单卡评估（corenet-eval的入口在 corenet/cli/main_eval.py）。

3.1 预期结果

官方指南给出 ViT-B 微调权重在 COCO val 上的参考结果：

'micro': 0.9118, 'macro': 0.8806, 'weighted': 0.8907

这里的 micro / macro / weighted 分别是 sklearn 定义的三种平均方式（计算逻辑见 corenet/metrics/multiclass_classification_pr.py 的compute方法）：

• micro：将所有样本-类别对视为整体计算平均精度，对每张图的每个类别贡献一视同仁；
• macro：逐类别计算 AP 后取未加权平均，每个类别权重相等；
• weighted：逐类别计算 AP 后按类别样本数加权平均。

MulticlassClassificationPR还会额外输出每类的ODS-F1、AP与Recall@P=50（在固定精度 0.5 下能达到的召回率，由get_recall_at_precision计算）。需要注意的是，多标签分类的 PR 指标与检测任务常用的 mAP 口径不同，对比精度时务必保持指标一致。

3.2 ViT-L 评估

将配置切换为vit_large.yaml，并把MODEL_WEIGHTS换成vit_large.pt（下载地址见下节表格），即可评估 ViT-L/16。

四、COCO 多标签分类预训练权重

官方提供了两个已微调好的多标签分类权重（对应下表 Macro mAP 为 COCO 验证集上的 macro 平均精度）：

使用方式：下载后把权重路径填入评估命令的MODEL_WEIGHTS，或放入本地目录后用model.classification.pretrained=/path/to/vit_base.pt指定。这两份权重即上文评估命令中使用的「COCO 微调权重」，可直接用于推理或作为下游任务初始点。

五、进一步阅读

• 想了解 CatLIP 预训练本身的配置与流程，参见 projects/catlip/README-pretraining.md；
• 单标签 ImageNet 分类微调见 projects/catlip/README-single-label-object-classification.md；
• 同一套预训练权重的检测与分割用法见 projects/catlip/README-object-detection.md 与 projects/catlip/README-semantic-segmentation.md；
• 相关核心源码位置：COCO 多标签数据集 corenet/data/datasets/classification/coco.py、BCE 损失 corenet/loss_fn/classification/binary_cross_entropy.py、神经增强损失 corenet/loss_fn/neural_augmentation.py、多标签 PR 指标 corenet/metrics/multiclass_classification_pr.py、可变批采样器 corenet/data/sampler/variable_batch_sampler.py、CLI 入口映射 corenet/cli/entrypoints.py。

• 深度学习
• 计算机视觉
• NLP
• 多模态
• 模型训练
• 大模型