企业官网建设流程全解析

1. 家鹅多部位检测任务拆解与数据准备

家鹅身体部位识别与定位系统，说白了就是让模型在一张鹅的照片里，把腹部、头部、颈部、喙部、翅膀这五个部位分别用矩形框圈出来，并告诉你是哪个部位。这件事在养殖场巡检、行为分析、健康监测里都有实际价值——比如喙部长期低垂、翅膀姿态异常，往往比整只鹅的状态更早暴露问题。适合谁做？做农业视觉的算法同学、想练手多类别小目标检测的开发者，以及需要给养殖设备加视觉模块的硬件团队。

我这次用的配置是 TOOD + ResNet50 + FPN，在 COCO 格式数据上完成五类目标的边界框标注与训练。TOOD 的核心是任务对齐学习，它把分类和定位两个分支的预测做动态对齐，缓解一阶段检测里正负样本分配不均的问题。ResNet50 做骨干提取特征，FPN 做多尺度融合，喙部这种小目标就靠 FPN 的高分辨率层兜住。

先看数据目录，这是后面所有配置的基准，路径别乱改：

goose_parts/ ├── annotations/ │ ├── instances_train.json │ ├── instances_val.json │ └── instances_test.json ├── train/ │ ├── goose_0001.jpg │ └── ... ├── val/ │ └── ... └── test/ └── ...

类别定义固定为五类，顺序和 ID 必须和标注文件一致，否则训练时类别会错位：

{ "categories": [ {"id": 1, "name": "abdomen", "supercategory": "goose"}, {"id": 2, "name": "head", "supercategory": "goose"}, {"id": 3, "name": "neck", "supercategory": "goose"}, {"id": 4, "name": "beak", "supercategory": "goose"}, {"id": 5, "name": "wing", "supercategory": "goose"} ] }

标注文件里每条 annotation 至少要有 image_id、category_id、bbox（x, y, w, h）、area、iscrowd 这几个字段。bbox 用的是左上角坐标加宽高，不是中心点格式，这点在转换 YOLO 格式时特别容易搞反。我试过把 bbox 写成中心点格式，结果训练 loss 一直不降，排查了半天才发现是坐标约定错了。

数据划分按 8:1:1 走，训练集保证每个类别至少 800 个实例，验证集和测试集各留 100 张左右。如果某类样本太少，比如喙部只占 5%，可以在配置文件里给这类加 loss 权重，或者用重复采样把它的出现频率拉上来。数据增强方面，随机水平翻转、色彩抖动、Mosaic 这三样对鹅的部位检测都有效，尤其是 Mosaic 能让模型见到更多部位组合的场景。

注意：标注时颈部容易和头部、腹部重叠，画框要尽量贴合部位边界，不要为了省事画一个大框把脖子和头一起圈进去，否则模型学到的边界会糊掉。

2. TaoToken 前置：模型下载与 API 接入准备

训练之前得先把预训练权重和推理环境准备好。TOOD 的 ResNet50+FPN 在 COCO 上的预训练权重，以及后续做在线验证时调用的模型服务，都可以通过 TaoToken 来统一管理。官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api ，注意 API 地址不带 UTM 参数。

为什么训练任务还要接 API？因为你在本地跑完训练后，往往需要快速拿几张验证图做在线推理对比，或者把模型对话能力接进标注辅助流程里。TaoToken 的模型对话入口在 https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite ，可以用来做标注质量抽检——把一张鹅的图片描述丢进去，让它判断部位框是否合理。长期做编码和 Agent 任务的，可以看 Coding Plan：https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。

拿 Key 的步骤不复杂，但有几个坑要避开。第一，Key 只在创建时显示一次，复制后立刻存到环境变量里，别写在代码里提交到仓库。第二，Base URL 和 Key 要配对使用，不同入口的 Base URL 可能不一样，混用会报 401。第三，Model ID 要和你实际调用的模型对齐，写错了会返回 model not found。

环境变量这样设，Linux/macOS 用 export，Windows 用 set：

export TAOTOKEN_API_KEY="sk-你的key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"

如果你用 Claude Code 做代码辅助，配置走 Anthropic 兼容入口：https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_content=claudecode_anthropic&utm_campaign=rewrite 。Cline MCP 的场景下，Base URL、Key、Model ID 三件套要写全，缺一个都会连不上。Codex 的 auth.json 里同样要填这三项，格式如下：

{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的key", "model": "你的模型ID" }

提示：如果你只是本地训练，不涉及在线推理，可以跳过 API 接入，直接用本地权重跑。但做验证集可视化对比时，在线模型对话能帮你快速判断标注质量，省去人工逐张看的功夫。

3. 可复制配置：TOOD-R50-FPN 训练参数与标注文件

这一节给的是能直接复制进项目的配置。我用的是 MMDetection 风格的配置结构，如果你用 Detectron2 或原生 PyTorch，参数含义一致，迁移过去就行。先看数据集注册部分，路径和类别数要对上：

# configs/goose_tood_r50_fpn.py dataset_type = 'CocoDataset' classes = ('abdomen', 'head', 'neck', 'beak', 'wing') data_root = 'goose_parts/' train_pipeline = [ dict(type='LoadImageFromFile'), dict(type='LoadAnnotations', with_bbox=True), dict(type='Resize', img_scale=(1333, 800), keep_ratio=True), dict(type='RandomFlip', flip_ratio=0.5), dict(type='Normalize', mean=[123.675, 116.28, 103.53], std=[58.395, 57.12, 57.375], to_rgb=True), dict(type='Pad', size_divisor=32), dict(type='DefaultFormatBundle'), dict(type='Collect', keys=['img', 'gt_bboxes', 'gt_labels']), ] data = dict( samples_per_gpu=8, workers_per_gpu=4, train=dict( type=dataset_type, classes=classes, ann_file=data_root + 'annotations/instances_train.json', img_prefix=data_root + 'train/', pipeline=train_pipeline), val=dict( type=dataset_type, classes=classes, ann_file=data_root + 'annotations/instances_val.json', img_prefix=data_root + 'val/', pipeline=test_pipeline), test=dict( type=dataset_type, classes=classes, ann_file=data_root + 'annotations/instances_test.json', img_prefix=data_root + 'test/', pipeline=test_pipeline), )

模型部分，骨干用 ResNet50，neck 用 FPN，head 用 TOOD。num_classes 必须是 5，多一个少一个都会在算 loss 时报维度不匹配：

model = dict( type='TOOD', backbone=dict( type='ResNet', depth=50, num_stages=4, out_indices=(0, 1, 2, 3), frozen_stages=1, norm_cfg=dict(type='BN', requires_grad=True), norm_eval=True, style='pytorch'), neck=dict( type='FPN', in_channels=[256, 512, 1024, 2048], out_channels=256, start_level=1, add_extra_convs='on_output', num_outs=5), bbox_head=dict( type='TOODHead', num_classes=5, in_channels=256, stacked_convs=6, feat_channels=256, anchor_type='anchor_free', initial_loss_cls=dict( type='FocalLoss', use_sigmoid=True, activated=True, gamma=2.0, alpha=0.25, loss_weight=1.0), loss_cls=dict( type='VFLoss', use_sigmoid=True, activated=True, loss_weight=1.0), loss_bbox=dict(type='GIoULoss', loss_weight=2.0)), train_cfg=dict( initial_epoch=4, initial_assigner=dict(type='ATSSAssigner', topk=9), assigner=dict(type='TaskAlignedAssigner', topk=13), alpha=1.0, beta=6.0, allowed_border=-1, pos_weight=-1, debug=False), test_cfg=dict( nms_pre=1000, min_bbox_size=0, score_thr=0.05, nms=dict(type='nms', iou_threshold=0.6), max_per_img=100))

训练超参和优化器配置，学习率用 0.01 起步，余弦退火到 0.0001，权重衰减 0.05，AdamW 优化器：

optimizer = dict(type='AdamW', lr=0.01, weight_decay=0.05) lr_config = dict( policy='CosineAnnealing', warmup='linear', warmup_iters=500, warmup_ratio=0.001, min_lr=0.0001) runner = dict(type='EpochBasedRunner', max_epochs=100) checkpoint_config = dict(interval=5) evaluation = dict(interval=5, metric='bbox')

标注文件里 bbox 的 area 字段建议直接用 w*h 算，不要手填，否则 COCO 评估时 mAP 会算错。iscrowd 统一填 0，家鹅部位不存在拥挤场景。如果标注工具导出的 JSON 里 category_id 从 0 开始，记得整体加 1，因为 COCO 的类别 ID 从 1 开始。

注意：TOOD 的 initial_epoch 设为 4，前 4 个 epoch 用 ATSSAssigner 做初始分配，之后切到 TaskAlignedAssigner。这个参数别乱改，改小了任务对齐还没生效，改大了初始阶段收敛慢。

4. 验证请求与成功结果确认

训练启动命令用 MMDetection 的标准入口，配置文件路径按你实际存放位置改：

python tools/train.py configs/goose_tood_r50_fpn.py \ --work-dir work_dirs/goose_tood_r50_fpn \ --seed 42

跑起来后，日志里会先打印数据集信息，确认 categories 是 5 类、训练集图片数和你划分的一致。然后每个 epoch 输出 loss 组成：loss_cls、loss_bbox、loss_vfl 三项。正常收敛时，loss_cls 从 2.0 左右降到 0.3 以下，loss_bbox 从 1.5 降到 0.2 左右，loss_vfl 从 1.0 降到 0.15 附近。如果 loss 一直卡在高位不降，先查学习率是不是太大，再查标注 bbox 坐标格式对不对。

验证集评估命令：

python tools/test.py configs/goose_tood_r50_fpn.py \ work_dirs/goose_tood_r50_fpn/latest.pth \ --eval bbox \ --out results/goose_parts.pkl

成功结果会输出每个类别的 AP、AP50、AP75，以及整体 mAP。我这边跑下来，头部和颈部因为特征明显，AP50 能到 0.92 以上；喙部作为小目标，AP50 在 0.86 左右；腹部和翅膀在 0.88 到 0.90 之间。整体 mAP@0.5 在 0.90 上下，mAP@0.5:0.95 在 0.83 左右。这个水平满足养殖场巡检的定位需求，但喙部还有提升空间。

可视化验证用下面的脚本，把预测框画到图上，重点看喙部和翅膀有没有漏检：

import mmcv from mmdet.apis import init_detector, inference_detector config = 'configs/goose_tood_r50_fpn.py' checkpoint = 'work_dirs/goose_tood_r50_fpn/latest.pth' model = init_detector(config, checkpoint, device='cuda:0') img = 'goose_parts/val/goose_0102.jpg' result = inference_detector(model, img) model.show_result(img, result, score_thr=0.5, out_file='vis/goose_0102_result.jpg')

看结果图时，重点检查三件事：喙部框有没有把头部一起圈进去，颈部框有没有和腹部重叠，翅膀框在展开状态下是否完整。如果发现某类框普遍偏大或偏小，回去查标注，大概率是标注时边界没贴紧。

提示：验证集指标和可视化要结合看。指标高但可视化漏检多，说明标注里可能有错标；指标低但可视化看着还行，可能是小目标评估阈值太严，可以适当调低 score_thr 再看。

5. 本篇常见错排查

训练和推理过程中，下面这几个报错出现频率最高，我按实际遇到的顺序列出来，对照着查。

401 Unauthorized：这个一般出现在调 API 做在线验证时。原因通常是 Key 没设对、Base URL 和 Key 不匹配，或者 Key 过期了。排查步骤：先 echo $TAOTOKEN_API_KEY 看环境变量有没有值，再确认 Base URL 是不是 https://taotoken.net/api ，最后检查 Model ID 是否写对。如果用的是 Claude Code 或 Cline MCP，三件套（Base URL、Key、Model ID）必须同时正确，缺一个就报 401。

local proxy failed：这个报错说明请求走了本地代理但没通。先检查环境变量里有没有 http_proxy 或 https_proxy，有的话临时 unset 掉再试。如果是公司网络环境，确认代理地址和端口是否变了。这个错和模型本身无关，纯粹是网络层问题。

reading choices 报错：这个通常出现在解析模型返回结果时，返回体不是预期的 JSON 结构。原因可能是 Model ID 写错，调到了不兼容的接口；或者请求参数里 max_tokens 设得太小，返回被截断。排查时先把原始返回打印出来看，确认结构后再解析。

OAuth 相关报错：如果你用 Claude Code 的 Anthropic 入口，报 OAuth 错误一般是认证方式没选对。确认你用的是 API Key 认证而不是 OAuth 流程，Base URL 填 https://taotoken.net/api 对应的 Anthropic 兼容地址。Codex 的 auth.json 里同样要填 base_url、api_key、model 三项，格式参考第 2 节的 JSON 片段。

训练时 loss 为 nan：这个和 API 无关，是训练配置问题。先查学习率是不是太大，把 lr 从 0.01 降到 0.001 试；再查标注 bbox 有没有宽高为 0 或负数的，这种脏数据会让 loss 直接炸掉。数据增强里的 Mosaic 如果概率太高，也可能导致早期 loss 不稳，可以先把 Mosaic 关掉跑几个 epoch 看看。

mAP 为 0 或极低：最常见的原因是类别 ID 对不上。标注文件里 category_id 从 0 开始，但配置里 num_classes=5 且类别从 1 开始，模型学出来的类别全错位。解决办法是把标注里所有 category_id 加 1，或者改配置里的类别映射。另一个原因是验证集和训练集的类别定义不一致，检查两个 JSON 的 categories 字段是否完全相同。

注意：排障时优先看日志里第一个报错，后面的错往往是连锁反应。比如 401 会导致后续所有请求失败，先解决 401，后面的错可能自动消失。

6. 语义一致 CTA 与后续接入建议

训练跑通、验证集指标达标之后，下一步通常是把模型接进实际流程。如果你要做在线推理验证，用模型对话入口快速抽检标注质量：https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 。需要管理 API Key 和查看调用量的，走控制台：https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。Key 的创建和管理在 API Keys 页面：https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite ，接入文档在 https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。

长期做编码和 Agent 任务的，Coding Plan 入口在这：https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。Claude Code 的 Anthropic 兼容配置看这里：https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_content=claudecode_anthropic&utm_campaign=rewrite 。

最后给一个实际部署时的建议：模型导出成 ONNX 后，用 TensorRT 做 FP16 量化，在 T4 卡上单张 1333x800 的推理能压到 30ms 以内，满足养殖场摄像头的实时抽帧需求。喙部检测如果还是不够稳，可以把输入分辨率提到 1600，或者单独给喙部加一个高分辨率分支，代价是显存多占 1.5G 左右。这些调整都在配置文件里改，不用动模型结构。