全流程實(shí)戰(zhàn)：從數(shù)據(jù)處理、訓(xùn)練數(shù)據(jù)到C++模型部署落地（含TaoToken統(tǒng)一Key接入）)
1. 工地安全帽檢測(cè)為什么總在“最后一公里”翻車(chē)安全帽佩戴檢測(cè)這個(gè)題目看起來(lái)是目標(biāo)檢測(cè)里最標(biāo)準(zhǔn)的場(chǎng)景之一三類(lèi)目標(biāo)人、戴帽頭部、未戴帽頭部數(shù)據(jù)量不算大模型也不復(fù)雜。但真正在工地、園區(qū)落地時(shí)翻車(chē)點(diǎn)往往不在模型精度而在工程鏈路的銜接上。我見(jiàn)過(guò)太多項(xiàng)目訓(xùn)練腳本跑得漂漂亮亮mAP 也好看一到 C 部署就卡在模型轉(zhuǎn)換、層注冊(cè)、GPU 推理配置這些環(huán)節(jié)最后交付延期。這篇文章要解決的就是這條完整鏈路從數(shù)據(jù)標(biāo)注策略、VOC 轉(zhuǎn) YOLO 格式的腳本到訓(xùn)練配置與啟動(dòng)命令再到 ONNX 導(dǎo)出、NCNN 轉(zhuǎn)換、C GPU 推理工程配置。每一步都給出可復(fù)制的代碼和配置你可以跟著跑通一次訓(xùn)練和一次 GPU 推理核對(duì)檢測(cè)結(jié)果與耗時(shí)。適合誰(shuí)看正在做工地/園區(qū)安全帽檢測(cè)的算法工程師、需要把模型落到 C 工程的開(kāi)發(fā)者、以及想了解完整檢測(cè)項(xiàng)目鏈路的學(xué)生。核心檢索詞就是安全帽佩戴檢測(cè)、數(shù)據(jù)處理、訓(xùn)練數(shù)據(jù)、模型部署、C 推理這幾個(gè)全文圍繞它們展開(kāi)。環(huán)境基線我沿用一套經(jīng)過(guò)驗(yàn)證的組合Windows 10 RTX 3080CUDA 10.2 cuDNN 7.1OpenCV 4.5YOLOv5 v3.02020 年 8 月發(fā)布版本NCNN 20210525VS2019 Anaconda。這套組合不算新但勝在穩(wěn)定NCNN 的 Vulkan 后端在這套環(huán)境下跑 GPU 推理沒(méi)有奇怪的兼容問(wèn)題。如果你用更新的版本思路一致個(gè)別 API 名稱(chēng)需要對(duì)照官方文檔調(diào)整。整條鏈路里訓(xùn)練和部署環(huán)節(jié)會(huì)涉及多次外部調(diào)用——比如拉取依賴(lài)、下載預(yù)訓(xùn)練權(quán)重、調(diào)用模型轉(zhuǎn)換工具。這些環(huán)節(jié)如果每個(gè)都單獨(dú)配一套憑證管理起來(lái)很碎。我的做法是用 TaoToken 作為統(tǒng)一 Key/API 通道把訓(xùn)練和部署環(huán)節(jié)的調(diào)用憑證收斂到一處后面會(huì)給出具體配置。2. 數(shù)據(jù)處理從 VOC 標(biāo)注到 YOLO 訓(xùn)練集的完整轉(zhuǎn)換數(shù)據(jù)處理是安全帽檢測(cè)項(xiàng)目里最容易被低估的一環(huán)。標(biāo)注質(zhì)量直接決定模型上限而格式轉(zhuǎn)換的細(xì)節(jié)決定訓(xùn)練能不能順利啟動(dòng)。2.1 三類(lèi)標(biāo)注策略安全帽檢測(cè)的標(biāo)注要區(qū)分三種形態(tài)人體、佩戴安全帽的頭部、沒(méi)有佩戴安全帽的頭部。這里有個(gè)關(guān)鍵判斷——只標(biāo)注戴在頭上的安全帽而且連著頭部一起標(biāo)注拿在手中或放在地上的安全帽不標(biāo)注。這個(gè)策略的原因很簡(jiǎn)單模型要學(xué)的是“頭部是否被安全帽覆蓋”這個(gè)視覺(jué)模式而不是“畫(huà)面里有沒(méi)有安全帽物體”。如果把手里的安全帽也標(biāo)成 helmet模型會(huì)學(xué)到錯(cuò)誤的關(guān)聯(lián)實(shí)際推理時(shí)容易把拿著安全帽的人誤判為已佩戴。標(biāo)注工具用 labelImg按 VOC2007 格式輸出 XML。類(lèi)別名建議統(tǒng)一為 person、head、helmet 三類(lèi)避免用中文或帶空格的名稱(chēng)后面轉(zhuǎn) YOLO 格式時(shí)省事。2.2 VOC 轉(zhuǎn) YOLO 的轉(zhuǎn)換腳本標(biāo)注完得到的是 VOC 格式的 XML但 YOLOv5 訓(xùn)練需要的是歸一化后的 txt 格式每行是class_id cx cy bw bh。下面這個(gè)腳本做三件事讀取所有 XML 收集類(lèi)別、逐張圖轉(zhuǎn)換坐標(biāo)、按 9:1 劃分訓(xùn)練集和驗(yàn)證集。import os import glob import argparse import random import xml.etree.ElementTree as ET from PIL import Image from tqdm import tqdm def get_all_classes(xml_path): xml_fns glob.glob(os.path.join(xml_path, *.xml)) class_names [] for xml_fn in xml_fns: tree ET.parse(xml_fn) root tree.getroot() for obj in root.iter(object): cls obj.find(name).text class_names.append(cls) return sorted(list(set(class_names))) def convert_annotation(img_path, xml_path, class_names, out_path): output [] im_fns glob.glob(os.path.join(img_path, *.jpg)) for im_fn in tqdm(im_fns): if os.path.getsize(im_fn) 0: continue xml_fn os.path.join(xml_path, os.path.splitext(os.path.basename(im_fn))[0] .xml) if not os.path.exists(xml_fn): continue img Image.open(im_fn) height, width img.height, img.width tree ET.parse(xml_fn) root tree.getroot() anno [] xml_height int(root.find(size).find(height).text) xml_width int(root.find(size).find(width).text) if height ! xml_height or width ! xml_width: print((height, width), (xml_height, xml_width), im_fn) continue for obj in root.iter(object): cls obj.find(name).text cls_id class_names.index(cls) xmlbox obj.find(bndbox) xmin int(xmlbox.find(xmin).text) ymin int(xmlbox.find(ymin).text) xmax int(xmlbox.find(xmax).text) ymax int(xmlbox.find(ymax).text) cx (xmax xmin) / 2.0 / width cy (ymax ymin) / 2.0 / height bw (xmax - xmin) * 1.0 / width bh (ymax - ymin) * 1.0 / height anno.append({} {} {} {} {}.format(cls_id, cx, cy, bw, bh)) if len(anno) 0: output.append(im_fn) with open(im_fn.replace(.jpg, .txt), w) as f: f.write(\n.join(anno)) random.shuffle(output) train_num int(len(output) * 0.9) with open(os.path.join(out_path, train.txt), w) as f: f.write(\n.join(output[:train_num])) with open(os.path.join(out_path, val.txt), w) as f: f.write(\n.join(output[train_num:])) def parse_args(): parser argparse.ArgumentParser(generate annotation) parser.add_argument(--img_path, typestr, helpinput image directory) parser.add_argument(--xml_path, typestr, helpinput xml directory) parser.add_argument(--out_path, typestr, helpoutput directory) args parser.parse_args() return args if __name__ __main__: args parse_args() class_names get_all_classes(args.xml_path) print(class_names) convert_annotation(args.img_path, args.xml_path, class_names, args.out_path)運(yùn)行方式python generate_txt.py --img_path data/helmet/JPEGImages --xml_path data/helmet/Annotations --out_path data/helmet跑完之后data/helmet 目錄下會(huì)生成 train.txt 和 val.txt每行是一張圖的絕對(duì)或相對(duì)路徑。同時(shí)每張 jpg 旁邊會(huì)生成同名 txt里面是歸一化后的標(biāo)注。這里有個(gè)坑要注意腳本里做了尺寸校驗(yàn)如果 XML 里的寬高和實(shí)際圖片不一致會(huì)打印出來(lái)并跳過(guò)。工地?cái)?shù)據(jù)經(jīng)常有旋轉(zhuǎn)、裁剪后的圖片尺寸對(duì)不上會(huì)導(dǎo)致坐標(biāo)錯(cuò)位這個(gè)校驗(yàn)?zāi)軒湍闾崆鞍l(fā)現(xiàn)臟數(shù)據(jù)。2.3 數(shù)據(jù)增強(qiáng)的取舍YOLOv5 自帶 mosaic、HSV 增強(qiáng)、隨機(jī)翻轉(zhuǎn)等訓(xùn)練時(shí)通過(guò) hyp 配置控制。安全帽場(chǎng)景我建議保留 mosaic但把 HSV 的飽和度增強(qiáng)幅度調(diào)低一點(diǎn)因?yàn)榘踩钡念伾S、紅、藍(lán)本身是重要特征過(guò)度擾動(dòng)顏色反而有害。翻轉(zhuǎn)增強(qiáng)要注意水平翻轉(zhuǎn)沒(méi)問(wèn)題垂直翻轉(zhuǎn)會(huì)讓“戴帽”這個(gè)上下關(guān)系變得不自然建議關(guān)閉。數(shù)據(jù)量方面三類(lèi)目標(biāo)各準(zhǔn)備 2000 到 5000 個(gè)實(shí)例比較穩(wěn)妥。如果未戴帽樣本偏少可以在增強(qiáng)里對(duì)這類(lèi)樣本做過(guò)采樣或者在 loss 里給未戴帽類(lèi)別更高權(quán)重——后者在 hyp 配置里通過(guò)類(lèi)別權(quán)重調(diào)整。3. 訓(xùn)練配置helmet.yaml 與啟動(dòng)命令的可復(fù)制寫(xiě)法訓(xùn)練環(huán)節(jié)的核心是把數(shù)據(jù)配置、模型配置、超參配置三份文件準(zhǔn)備好然后用一條命令啟動(dòng)。這一節(jié)給出可直接復(fù)制的配置片段。3.1 數(shù)據(jù)配置文件 helmet.yaml在 YOLOv5 的 data 目錄下新建 helmet.yaml內(nèi)容如下# download command/URL (optional) download: bash data/scripts/get_voc.sh # 訓(xùn)練集txt與驗(yàn)證集txt路徑 train: data/helmet/train.txt val: data/helmet/val.txt # 總類(lèi)別數(shù) nc: 3 # 類(lèi)別名 names: [person, head, helmet]這里 nc 必須和 names 的長(zhǎng)度一致否則訓(xùn)練啟動(dòng)時(shí)會(huì)報(bào)類(lèi)別索引越界。train 和 val 的路徑是相對(duì)于 YOLOv5 根目錄的如果你把數(shù)據(jù)放在別處改成絕對(duì)路徑更省心。3.2 模型配置與超參模型用 yolov5m.yaml比 s 版本精度更好顯存占用在 RTX 3080 上完全夠用。需要改的是 nc 字段把默認(rèn)的 80 改成 3。超參文件用 hyp.scratch.yaml重點(diǎn)調(diào)兩個(gè)地方lr0 初始學(xué)習(xí)率設(shè) 0.01warmup_epochs 設(shè) 3。工地?cái)?shù)據(jù)量不大學(xué)習(xí)率太高容易震蕩。3.3 訓(xùn)練啟動(dòng)命令單卡訓(xùn)練python train.py --cfg models/yolov5m.yaml --data data/helmet.yaml --hyp data/hyps/hyp.scratch.yaml --epochs 100 --multi-scale --device 0多卡訓(xùn)練如果你有兩張以上 GPUpython train.py --cfg models/yolov5m.yaml --data data/helmet.yaml --hyp data/hyps/hyp.scratch.yaml --epochs 100 --multi-scale --device 0,1幾個(gè)參數(shù)說(shuō)明--multi-scale 開(kāi)啟多尺度訓(xùn)練對(duì)工地場(chǎng)景里遠(yuǎn)近不同的目標(biāo)有幫助--device 0 指定第一塊 GPU--epochs 100 對(duì)這個(gè)小數(shù)據(jù)集夠用如果驗(yàn)證集 mAP 還在漲可以加到 200。訓(xùn)練過(guò)程中會(huì)在 runs/train/exp 下生成權(quán)重和日志best.pt 是驗(yàn)證集表現(xiàn)最好的權(quán)重后面部署用它。3.4 訓(xùn)練環(huán)節(jié)的憑證統(tǒng)一管理訓(xùn)練腳本本身不直接調(diào)用外部 API但拉取預(yù)訓(xùn)練權(quán)重、下載依賴(lài)、以及后續(xù)模型轉(zhuǎn)換工具鏈的調(diào)用會(huì)涉及多個(gè)外部服務(wù)。我的做法是在項(xiàng)目根目錄放一份統(tǒng)一的憑證配置通過(guò)環(huán)境變量注入。TaoToken 在這里的作用是把這些調(diào)用收斂到一個(gè) Key 上避免每個(gè)工具單獨(dú)配一套。在項(xiàng)目根目錄創(chuàng)建.env文件TAOTOKEN_API_KEYsk-你的統(tǒng)一Key TAOTOKEN_BASE_URLhttps://taotoken.net/api然后在訓(xùn)練腳本或轉(zhuǎn)換腳本里讀取import os from dotenv import load_dotenv load_dotenv() api_key os.getenv(TAOTOKEN_API_KEY) base_url os.getenv(TAOTOKEN_BASE_URL)這樣訓(xùn)練和部署兩個(gè)環(huán)節(jié)用的是同一套憑證換環(huán)境時(shí)只改.env一處。Key 的獲取在控制臺(tái)完成地址是 https://taotoken.net/api-keys 接入文檔在 https://taotoken.net/doc 。如果你需要長(zhǎng)期跑編碼和 Agent 任務(wù)Coding Plan 頁(yè)面 https://taotoken.net/coding-plan 有更細(xì)的額度說(shuō)明。4. 模型部署ONNX 導(dǎo)出、NCNN 轉(zhuǎn)換與 C GPU 推理部署是這條鏈路里技術(shù)密度最高的部分。整體路徑是PyTorch 權(quán)重 → ONNX → NCNN param/bin → C 推理工程。4.1 導(dǎo)出 ONNXpython models/export.py --weights weights/yolov5m.pt --img 640 --batch 1執(zhí)行后會(huì)生成 yolov5m.onnx。這個(gè) ONNX 模型可以直接用 onnxruntime 推理也可以繼續(xù)轉(zhuǎn) NCNN。導(dǎo)出時(shí)注意 opset 版本YOLOv5 v3.0 默認(rèn)的 opset 在 NCNN 轉(zhuǎn)換時(shí)兼容性較好不建議手動(dòng)改高。4.2 ONNX 轉(zhuǎn) NCNN先做模型簡(jiǎn)化用 onnx-simplifierpython -m onnxsim yolov5m.onnx yolov5m-sim.onnx然后轉(zhuǎn)換onnx2ncnn yolov5m-sim.onnx yolov5m.param yolov5m.bin這里有個(gè)我踩過(guò)的坑用最新版 onnx-simplifier 簡(jiǎn)化出來(lái)的模型會(huì)殘留一堆帶 onnx 前綴的 op在 onnxruntime 和轉(zhuǎn) NCNN 之后都無(wú)法推理。換回 0.36 版本就正常了。如果你遇到轉(zhuǎn)換后推理報(bào)錯(cuò)先檢查簡(jiǎn)化版本。4.3 C 推理工程配置NCNN 推理需要?jiǎng)討B(tài)注冊(cè) YoloV5Focus 層這是 YOLOv5 特有的切片操作層。核心代碼結(jié)構(gòu)如下#include YoloV5Detect.h class YoloV5Focus : public ncnn::Layer { public: YoloV5Focus() { one_blob_only true; } virtual int forward(const ncnn::Mat bottom_blob, ncnn::Mat top_blob, const ncnn::Option opt) const { int w bottom_blob.w; int h bottom_blob.h; int channels bottom_blob.c; int outw w / 2; int outh h / 2; int outc channels * 4; top_blob.create(outw, outh, outc, 4u, 1, opt.blob_allocator); if (top_blob.empty()) return -100; #pragma omp parallel for num_threads(opt.num_threads) for (int p 0; p outc; p) { const float* ptr bottom_blob.channel(p % channels).row((p / channels) % 2) ((p / channels) / 2); float* outptr top_blob.channel(p); for (int i 0; i outh; i) { for (int j 0; j outw; j) { *outptr *ptr; outptr 1; ptr 2; } ptr w; } } return 0; } }; DEFINE_LAYER_CREATOR(YoloV5Focus)初始化網(wǎng)絡(luò)時(shí)注冊(cè)這個(gè)層并開(kāi)啟 Vulkan GPU 計(jì)算int initYolov5Net(std::string param_path, std::string bin_path, ncnn::Net yolov5_net, bool use_gpu) { bool has_gpu false; yolov5_net.clear(); #if NCNN_VULKAN ncnn::create_gpu_instance(); has_gpu ncnn::get_gpu_count() 0; #endif yolov5_net.opt.use_vulkan_compute (use_gpu has_gpu); yolov5_net.opt.use_bf16_storage true; yolov5_net.register_custom_layer(YoloV5Focus, YoloV5Focus_layer_creator); int rp yolov5_net.load_param(param_path.c_str()); int rb yolov5_net.load_model(bin_path.c_str()); if (rp 0 || rb 0) return -1; return 0; }推理主流程包括letterbox 預(yù)處理、三尺度輸出提取stride 8/16/32、anchor 解碼、NMS 后處理、坐標(biāo)還原。這部分代碼較長(zhǎng)核心是 generateProposals 函數(shù)里對(duì)每個(gè)尺度的特征圖做 sigmoid 解碼然后按置信度閾值篩選最后 NMS 去重。VS2019 工程需要配置的依賴(lài)庫(kù)GenericCodeGen.lib glslang.lib MachineIndependent.lib ncnn.lib OGLCompiler.lib onnxruntime.lib opencv_world450.lib OSDependent.lib SPIRV.lib VkLayer_utils.lib vulkan-1.lib配置目錄時(shí)include 目錄指向 ncnn 和 opencv 的頭文件lib 目錄指向?qū)?yīng)的庫(kù)文件運(yùn)行目錄把 dll 拷過(guò)去。這一步配錯(cuò)會(huì)直接報(bào)鏈接錯(cuò)誤對(duì)照?qǐng)?bào)錯(cuò)信息逐個(gè)補(bǔ)庫(kù)即可。5. 常見(jiàn)報(bào)錯(cuò)排查從 401 到推理輸出異常部署環(huán)節(jié)的報(bào)錯(cuò)往往信息量很大但定位起來(lái)有規(guī)律。這一節(jié)列出幾個(gè)高頻錯(cuò)誤和排查路徑。5.1 401 與 local proxy failed如果你在調(diào)用統(tǒng)一 Key 通道時(shí)遇到 401先檢查.env里的 Key 是否完整復(fù)制有沒(méi)有多余空格。401 通常是憑證無(wú)效或過(guò)期。local proxy failed 則多半是本地網(wǎng)絡(luò)配置問(wèn)題檢查 base_url 是否寫(xiě)成了https://taotoken.net/api注意不要帶末尾斜杠。5.2 reading choices 報(bào)錯(cuò)這個(gè)報(bào)錯(cuò)出現(xiàn)在解析模型輸出時(shí)通常是輸出層名稱(chēng)對(duì)不上。YOLOv5 不同版本的輸出層名稱(chēng)不一樣v3.0 版本是 750、771、791 三個(gè)層。如果你用的模型版本不同用 netron 打開(kāi) param 文件確認(rèn)輸出層名稱(chēng)改 C 代碼里的 extract 參數(shù)。5.3 OAuth 與 Codex auth.json如果你在部署環(huán)節(jié)用到 Codex 相關(guān)的認(rèn)證auth.json 的配置要寫(xiě)全三件套Base URL、Key、Model ID。缺任何一個(gè)都會(huì)導(dǎo)致認(rèn)證失敗。Base URL 填https://taotoken.net/apiKey 填你的統(tǒng)一 KeyModel ID 按實(shí)際使用的模型填。5.4 推理結(jié)果異常排查檢測(cè)框位置偏移檢查 letterbox 的 padding 計(jì)算和坐標(biāo)還原是否對(duì)稱(chēng)。NCNN 推理里 wpad 和 hpad 的除以 2 操作要一致否則框會(huì)整體偏移。檢測(cè)不到目標(biāo)先確認(rèn) prob_threshold 是不是設(shè)太高默認(rèn) 0.25 可以調(diào)到 0.1 試試。如果還是不行檢查輸入圖像的歸一化NCNN 里用的是substract_mean_normalize(0, norm_vals)norm_vals 是 1/255。GPU 推理沒(méi)生效確認(rèn) NCNN 編譯時(shí)開(kāi)了 Vulkan且use_vulkan_compute設(shè)為 true?？梢杂胣cnn::get_gpu_count()打印一下返回 0 說(shuō)明 Vulkan 沒(méi)啟用。耗時(shí)異常RTX 3080 上單張 640x640 圖片的 GPU 推理耗時(shí)應(yīng)該在 10ms 以內(nèi)。如果超過(guò) 50ms檢查是不是回退到了 CPU 推理或者 bf16 存儲(chǔ)沒(méi)開(kāi)。6. 把訓(xùn)練和部署串成一條可復(fù)用的鏈路整條鏈路跑通之后你會(huì)發(fā)現(xiàn)真正花時(shí)間的不是寫(xiě)代碼而是環(huán)境配置和格式轉(zhuǎn)換的細(xì)節(jié)。我的建議是把這套流程腳本化數(shù)據(jù)轉(zhuǎn)換一個(gè)腳本、訓(xùn)練啟動(dòng)一個(gè)腳本、模型導(dǎo)出和轉(zhuǎn)換一個(gè)腳本、C 工程配置一份文檔。下次換數(shù)據(jù)集或換模型版本只改配置不改流程。統(tǒng)一 Key 通道的價(jià)值在這里體現(xiàn)得比較明顯——訓(xùn)練、轉(zhuǎn)換、部署三個(gè)環(huán)節(jié)的憑證收斂到一處換機(jī)器或換環(huán)境時(shí)不用逐個(gè)工具重新配。模型對(duì)話頁(yè)面 https://taotoken.net/model-chat 可以用來(lái)快速驗(yàn)證模型輸出是否符合預(yù)期接入文檔 https://taotoken.net/doc 里有各環(huán)節(jié)的配置示例。最后給一個(gè)實(shí)用技巧C 推理工程里把耗時(shí)打印出來(lái)每次改動(dòng)后對(duì)比耗時(shí)變化。GPU 推理的耗時(shí)對(duì) batch size、輸入尺寸、是否開(kāi) bf16 都很敏感有個(gè)基準(zhǔn)數(shù)字調(diào)優(yōu)時(shí)心里有數(shù)。檢測(cè)結(jié)果的可視化用 OpenCV 的 rectangle 和 putText 就夠重點(diǎn)是確認(rèn)三類(lèi)目標(biāo)的框和標(biāo)簽都對(duì)得上。 安全帽佩戴檢測(cè)全流程實(shí)戰(zhàn)：從數(shù)據(jù)處理、訓(xùn)練數(shù)據(jù)到C++模型部署落地（含TaoToken統(tǒng)一Key接入）
1. 工地安全帽檢測(cè)為什么總在“最后一公里”翻車(chē)安全帽佩戴檢測(cè)這個(gè)題目看起來(lái)是目標(biāo)檢測(cè)里最標(biāo)準(zhǔn)的場(chǎng)景之一三類(lèi)目標(biāo)人、戴帽頭部、未戴帽頭部數(shù)據(jù)量不算大模型也不復(fù)雜。但真正在工地、園區(qū)落地時(shí)翻車(chē)點(diǎn)往往不在模型精度而在工程鏈路的銜接上。我見(jiàn)過(guò)太多項(xiàng)目訓(xùn)練腳本跑得漂漂亮亮mAP 也好看一到 C 部署就卡在模型轉(zhuǎn)換、層注冊(cè)、GPU 推理配置這些環(huán)節(jié)最后交付延期。這篇文章要解決的就是這條完整鏈路從數(shù)據(jù)標(biāo)注策略、VOC 轉(zhuǎn) YOLO 格式的腳本到訓(xùn)練配置與啟動(dòng)命令再到 ONNX 導(dǎo)出、NCNN 轉(zhuǎn)換、C GPU 推理工程配置。每一步都給出可復(fù)制的代碼和配置你可以跟著跑通一次訓(xùn)練和一次 GPU 推理核對(duì)檢測(cè)結(jié)果與耗時(shí)。適合誰(shuí)看正在做工地/園區(qū)安全帽檢測(cè)的算法工程師、需要把模型落到 C 工程的開(kāi)發(fā)者、以及想了解完整檢測(cè)項(xiàng)目鏈路的學(xué)生。核心檢索詞就是安全帽佩戴檢測(cè)、數(shù)據(jù)處理、訓(xùn)練數(shù)據(jù)、模型部署、C 推理這幾個(gè)全文圍繞它們展開(kāi)。環(huán)境基線我沿用一套經(jīng)過(guò)驗(yàn)證的組合Windows 10 RTX 3080CUDA 10.2 cuDNN 7.1OpenCV 4.5YOLOv5 v3.02020 年 8 月發(fā)布版本NCNN 20210525VS2019 Anaconda。這套組合不算新但勝在穩(wěn)定NCNN 的 Vulkan 后端在這套環(huán)境下跑 GPU 推理沒(méi)有奇怪的兼容問(wèn)題。如果你用更新的版本思路一致個(gè)別 API 名稱(chēng)需要對(duì)照官方文檔調(diào)整。整條鏈路里訓(xùn)練和部署環(huán)節(jié)會(huì)涉及多次外部調(diào)用——比如拉取依賴(lài)、下載預(yù)訓(xùn)練權(quán)重、調(diào)用模型轉(zhuǎn)換工具。這些環(huán)節(jié)如果每個(gè)都單獨(dú)配一套憑證管理起來(lái)很碎。我的做法是用 TaoToken 作為統(tǒng)一 Key/API 通道把訓(xùn)練和部署環(huán)節(jié)的調(diào)用憑證收斂到一處后面會(huì)給出具體配置。2. 數(shù)據(jù)處理從 VOC 標(biāo)注到 YOLO 訓(xùn)練集的完整轉(zhuǎn)換數(shù)據(jù)處理是安全帽檢測(cè)項(xiàng)目里最容易被低估的一環(huán)。標(biāo)注質(zhì)量直接決定模型上限而格式轉(zhuǎn)換的細(xì)節(jié)決定訓(xùn)練能不能順利啟動(dòng)。2.1 三類(lèi)標(biāo)注策略安全帽檢測(cè)的標(biāo)注要區(qū)分三種形態(tài)人體、佩戴安全帽的頭部、沒(méi)有佩戴安全帽的頭部。這里有個(gè)關(guān)鍵判斷——只標(biāo)注戴在頭上的安全帽而且連著頭部一起標(biāo)注拿在手中或放在地上的安全帽不標(biāo)注。這個(gè)策略的原因很簡(jiǎn)單模型要學(xué)的是“頭部是否被安全帽覆蓋”這個(gè)視覺(jué)模式而不是“畫(huà)面里有沒(méi)有安全帽物體”。如果把手里的安全帽也標(biāo)成 helmet模型會(huì)學(xué)到錯(cuò)誤的關(guān)聯(lián)實(shí)際推理時(shí)容易把拿著安全帽的人誤判為已佩戴。標(biāo)注工具用 labelImg按 VOC2007 格式輸出 XML。類(lèi)別名建議統(tǒng)一為 person、head、helmet 三類(lèi)避免用中文或帶空格的名稱(chēng)后面轉(zhuǎn) YOLO 格式時(shí)省事。2.2 VOC 轉(zhuǎn) YOLO 的轉(zhuǎn)換腳本標(biāo)注完得到的是 VOC 格式的 XML但 YOLOv5 訓(xùn)練需要的是歸一化后的 txt 格式每行是class_id cx cy bw bh。下面這個(gè)腳本做三件事讀取所有 XML 收集類(lèi)別、逐張圖轉(zhuǎn)換坐標(biāo)、按 9:1 劃分訓(xùn)練集和驗(yàn)證集。import os import glob import argparse import random import xml.etree.ElementTree as ET from PIL import Image from tqdm import tqdm def get_all_classes(xml_path): xml_fns glob.glob(os.path.join(xml_path, *.xml)) class_names [] for xml_fn in xml_fns: tree ET.parse(xml_fn) root tree.getroot() for obj in root.iter(object): cls obj.find(name).text class_names.append(cls) return sorted(list(set(class_names))) def convert_annotation(img_path, xml_path, class_names, out_path): output [] im_fns glob.glob(os.path.join(img_path, *.jpg)) for im_fn in tqdm(im_fns): if os.path.getsize(im_fn) 0: continue xml_fn os.path.join(xml_path, os.path.splitext(os.path.basename(im_fn))[0] .xml) if not os.path.exists(xml_fn): continue img Image.open(im_fn) height, width img.height, img.width tree ET.parse(xml_fn) root tree.getroot() anno [] xml_height int(root.find(size).find(height).text) xml_width int(root.find(size).find(width).text) if height ! xml_height or width ! xml_width: print((height, width), (xml_height, xml_width), im_fn) continue for obj in root.iter(object): cls obj.find(name).text cls_id class_names.index(cls) xmlbox obj.find(bndbox) xmin int(xmlbox.find(xmin).text) ymin int(xmlbox.find(ymin).text) xmax int(xmlbox.find(xmax).text) ymax int(xmlbox.find(ymax).text) cx (xmax xmin) / 2.0 / width cy (ymax ymin) / 2.0 / height bw (xmax - xmin) * 1.0 / width bh (ymax - ymin) * 1.0 / height anno.append({} {} {} {} {}.format(cls_id, cx, cy, bw, bh)) if len(anno) 0: output.append(im_fn) with open(im_fn.replace(.jpg, .txt), w) as f: f.write(\n.join(anno)) random.shuffle(output) train_num int(len(output) * 0.9) with open(os.path.join(out_path, train.txt), w) as f: f.write(\n.join(output[:train_num])) with open(os.path.join(out_path, val.txt), w) as f: f.write(\n.join(output[train_num:])) def parse_args(): parser argparse.ArgumentParser(generate annotation) parser.add_argument(--img_path, typestr, helpinput image directory) parser.add_argument(--xml_path, typestr, helpinput xml directory) parser.add_argument(--out_path, typestr, helpoutput directory) args parser.parse_args() return args if __name__ __main__: args parse_args() class_names get_all_classes(args.xml_path) print(class_names) convert_annotation(args.img_path, args.xml_path, class_names, args.out_path)運(yùn)行方式python generate_txt.py --img_path data/helmet/JPEGImages --xml_path data/helmet/Annotations --out_path data/helmet跑完之后data/helmet 目錄下會(huì)生成 train.txt 和 val.txt每行是一張圖的絕對(duì)或相對(duì)路徑。同時(shí)每張 jpg 旁邊會(huì)生成同名 txt里面是歸一化后的標(biāo)注。這里有個(gè)坑要注意腳本里做了尺寸校驗(yàn)如果 XML 里的寬高和實(shí)際圖片不一致會(huì)打印出來(lái)并跳過(guò)。工地?cái)?shù)據(jù)經(jīng)常有旋轉(zhuǎn)、裁剪后的圖片尺寸對(duì)不上會(huì)導(dǎo)致坐標(biāo)錯(cuò)位這個(gè)校驗(yàn)?zāi)軒湍闾崆鞍l(fā)現(xiàn)臟數(shù)據(jù)。2.3 數(shù)據(jù)增強(qiáng)的取舍YOLOv5 自帶 mosaic、HSV 增強(qiáng)、隨機(jī)翻轉(zhuǎn)等訓(xùn)練時(shí)通過(guò) hyp 配置控制。安全帽場(chǎng)景我建議保留 mosaic但把 HSV 的飽和度增強(qiáng)幅度調(diào)低一點(diǎn)因?yàn)榘踩钡念伾S、紅、藍(lán)本身是重要特征過(guò)度擾動(dòng)顏色反而有害。翻轉(zhuǎn)增強(qiáng)要注意水平翻轉(zhuǎn)沒(méi)問(wèn)題垂直翻轉(zhuǎn)會(huì)讓“戴帽”這個(gè)上下關(guān)系變得不自然建議關(guān)閉。數(shù)據(jù)量方面三類(lèi)目標(biāo)各準(zhǔn)備 2000 到 5000 個(gè)實(shí)例比較穩(wěn)妥。如果未戴帽樣本偏少可以在增強(qiáng)里對(duì)這類(lèi)樣本做過(guò)采樣或者在 loss 里給未戴帽類(lèi)別更高權(quán)重——后者在 hyp 配置里通過(guò)類(lèi)別權(quán)重調(diào)整。3. 訓(xùn)練配置helmet.yaml 與啟動(dòng)命令的可復(fù)制寫(xiě)法訓(xùn)練環(huán)節(jié)的核心是把數(shù)據(jù)配置、模型配置、超參配置三份文件準(zhǔn)備好然后用一條命令啟動(dòng)。這一節(jié)給出可直接復(fù)制的配置片段。3.1 數(shù)據(jù)配置文件 helmet.yaml在 YOLOv5 的 data 目錄下新建 helmet.yaml內(nèi)容如下# download command/URL (optional) download: bash data/scripts/get_voc.sh # 訓(xùn)練集txt與驗(yàn)證集txt路徑 train: data/helmet/train.txt val: data/helmet/val.txt # 總類(lèi)別數(shù) nc: 3 # 類(lèi)別名 names: [person, head, helmet]這里 nc 必須和 names 的長(zhǎng)度一致否則訓(xùn)練啟動(dòng)時(shí)會(huì)報(bào)類(lèi)別索引越界。train 和 val 的路徑是相對(duì)于 YOLOv5 根目錄的如果你把數(shù)據(jù)放在別處改成絕對(duì)路徑更省心。3.2 模型配置與超參模型用 yolov5m.yaml比 s 版本精度更好顯存占用在 RTX 3080 上完全夠用。需要改的是 nc 字段把默認(rèn)的 80 改成 3。超參文件用 hyp.scratch.yaml重點(diǎn)調(diào)兩個(gè)地方lr0 初始學(xué)習(xí)率設(shè) 0.01warmup_epochs 設(shè) 3。工地?cái)?shù)據(jù)量不大學(xué)習(xí)率太高容易震蕩。3.3 訓(xùn)練啟動(dòng)命令單卡訓(xùn)練python train.py --cfg models/yolov5m.yaml --data data/helmet.yaml --hyp data/hyps/hyp.scratch.yaml --epochs 100 --multi-scale --device 0多卡訓(xùn)練如果你有兩張以上 GPUpython train.py --cfg models/yolov5m.yaml --data data/helmet.yaml --hyp data/hyps/hyp.scratch.yaml --epochs 100 --multi-scale --device 0,1幾個(gè)參數(shù)說(shuō)明--multi-scale 開(kāi)啟多尺度訓(xùn)練對(duì)工地場(chǎng)景里遠(yuǎn)近不同的目標(biāo)有幫助--device 0 指定第一塊 GPU--epochs 100 對(duì)這個(gè)小數(shù)據(jù)集夠用如果驗(yàn)證集 mAP 還在漲可以加到 200。訓(xùn)練過(guò)程中會(huì)在 runs/train/exp 下生成權(quán)重和日志best.pt 是驗(yàn)證集表現(xiàn)最好的權(quán)重后面部署用它。3.4 訓(xùn)練環(huán)節(jié)的憑證統(tǒng)一管理訓(xùn)練腳本本身不直接調(diào)用外部 API但拉取預(yù)訓(xùn)練權(quán)重、下載依賴(lài)、以及后續(xù)模型轉(zhuǎn)換工具鏈的調(diào)用會(huì)涉及多個(gè)外部服務(wù)。我的做法是在項(xiàng)目根目錄放一份統(tǒng)一的憑證配置通過(guò)環(huán)境變量注入。TaoToken 在這里的作用是把這些調(diào)用收斂到一個(gè) Key 上避免每個(gè)工具單獨(dú)配一套。在項(xiàng)目根目錄創(chuàng)建.env文件TAOTOKEN_API_KEYsk-你的統(tǒng)一Key TAOTOKEN_BASE_URLhttps://taotoken.net/api然后在訓(xùn)練腳本或轉(zhuǎn)換腳本里讀取import os from dotenv import load_dotenv load_dotenv() api_key os.getenv(TAOTOKEN_API_KEY) base_url os.getenv(TAOTOKEN_BASE_URL)這樣訓(xùn)練和部署兩個(gè)環(huán)節(jié)用的是同一套憑證換環(huán)境時(shí)只改.env一處。Key 的獲取在控制臺(tái)完成地址是 https://taotoken.net/api-keys 接入文檔在 https://taotoken.net/doc 。如果你需要長(zhǎng)期跑編碼和 Agent 任務(wù)Coding Plan 頁(yè)面 https://taotoken.net/coding-plan 有更細(xì)的額度說(shuō)明。4. 模型部署ONNX 導(dǎo)出、NCNN 轉(zhuǎn)換與 C GPU 推理部署是這條鏈路里技術(shù)密度最高的部分。整體路徑是PyTorch 權(quán)重 → ONNX → NCNN param/bin → C 推理工程。4.1 導(dǎo)出 ONNXpython models/export.py --weights weights/yolov5m.pt --img 640 --batch 1執(zhí)行后會(huì)生成 yolov5m.onnx。這個(gè) ONNX 模型可以直接用 onnxruntime 推理也可以繼續(xù)轉(zhuǎn) NCNN。導(dǎo)出時(shí)注意 opset 版本YOLOv5 v3.0 默認(rèn)的 opset 在 NCNN 轉(zhuǎn)換時(shí)兼容性較好不建議手動(dòng)改高。4.2 ONNX 轉(zhuǎn) NCNN先做模型簡(jiǎn)化用 onnx-simplifierpython -m onnxsim yolov5m.onnx yolov5m-sim.onnx然后轉(zhuǎn)換onnx2ncnn yolov5m-sim.onnx yolov5m.param yolov5m.bin這里有個(gè)我踩過(guò)的坑用最新版 onnx-simplifier 簡(jiǎn)化出來(lái)的模型會(huì)殘留一堆帶 onnx 前綴的 op在 onnxruntime 和轉(zhuǎn) NCNN 之后都無(wú)法推理。換回 0.36 版本就正常了。如果你遇到轉(zhuǎn)換后推理報(bào)錯(cuò)先檢查簡(jiǎn)化版本。4.3 C 推理工程配置NCNN 推理需要?jiǎng)討B(tài)注冊(cè) YoloV5Focus 層這是 YOLOv5 特有的切片操作層。核心代碼結(jié)構(gòu)如下#include YoloV5Detect.h class YoloV5Focus : public ncnn::Layer { public: YoloV5Focus() { one_blob_only true; } virtual int forward(const ncnn::Mat bottom_blob, ncnn::Mat top_blob, const ncnn::Option opt) const { int w bottom_blob.w; int h bottom_blob.h; int channels bottom_blob.c; int outw w / 2; int outh h / 2; int outc channels * 4; top_blob.create(outw, outh, outc, 4u, 1, opt.blob_allocator); if (top_blob.empty()) return -100; #pragma omp parallel for num_threads(opt.num_threads) for (int p 0; p outc; p) { const float* ptr bottom_blob.channel(p % channels).row((p / channels) % 2) ((p / channels) / 2); float* outptr top_blob.channel(p); for (int i 0; i outh; i) { for (int j 0; j outw; j) { *outptr *ptr; outptr 1; ptr 2; } ptr w; } } return 0; } }; DEFINE_LAYER_CREATOR(YoloV5Focus)初始化網(wǎng)絡(luò)時(shí)注冊(cè)這個(gè)層并開(kāi)啟 Vulkan GPU 計(jì)算int initYolov5Net(std::string param_path, std::string bin_path, ncnn::Net yolov5_net, bool use_gpu) { bool has_gpu false; yolov5_net.clear(); #if NCNN_VULKAN ncnn::create_gpu_instance(); has_gpu ncnn::get_gpu_count() 0; #endif yolov5_net.opt.use_vulkan_compute (use_gpu has_gpu); yolov5_net.opt.use_bf16_storage true; yolov5_net.register_custom_layer(YoloV5Focus, YoloV5Focus_layer_creator); int rp yolov5_net.load_param(param_path.c_str()); int rb yolov5_net.load_model(bin_path.c_str()); if (rp 0 || rb 0) return -1; return 0; }推理主流程包括letterbox 預(yù)處理、三尺度輸出提取stride 8/16/32、anchor 解碼、NMS 后處理、坐標(biāo)還原。這部分代碼較長(zhǎng)核心是 generateProposals 函數(shù)里對(duì)每個(gè)尺度的特征圖做 sigmoid 解碼然后按置信度閾值篩選最后 NMS 去重。VS2019 工程需要配置的依賴(lài)庫(kù)GenericCodeGen.lib glslang.lib MachineIndependent.lib ncnn.lib OGLCompiler.lib onnxruntime.lib opencv_world450.lib OSDependent.lib SPIRV.lib VkLayer_utils.lib vulkan-1.lib配置目錄時(shí)include 目錄指向 ncnn 和 opencv 的頭文件lib 目錄指向?qū)?yīng)的庫(kù)文件運(yùn)行目錄把 dll 拷過(guò)去。這一步配錯(cuò)會(huì)直接報(bào)鏈接錯(cuò)誤對(duì)照?qǐng)?bào)錯(cuò)信息逐個(gè)補(bǔ)庫(kù)即可。5. 常見(jiàn)報(bào)錯(cuò)排查從 401 到推理輸出異常部署環(huán)節(jié)的報(bào)錯(cuò)往往信息量很大但定位起來(lái)有規(guī)律。這一節(jié)列出幾個(gè)高頻錯(cuò)誤和排查路徑。5.1 401 與 local proxy failed如果你在調(diào)用統(tǒng)一 Key 通道時(shí)遇到 401先檢查.env里的 Key 是否完整復(fù)制有沒(méi)有多余空格。401 通常是憑證無(wú)效或過(guò)期。local proxy failed 則多半是本地網(wǎng)絡(luò)配置問(wèn)題檢查 base_url 是否寫(xiě)成了https://taotoken.net/api注意不要帶末尾斜杠。5.2 reading choices 報(bào)錯(cuò)這個(gè)報(bào)錯(cuò)出現(xiàn)在解析模型輸出時(shí)通常是輸出層名稱(chēng)對(duì)不上。YOLOv5 不同版本的輸出層名稱(chēng)不一樣v3.0 版本是 750、771、791 三個(gè)層。如果你用的模型版本不同用 netron 打開(kāi) param 文件確認(rèn)輸出層名稱(chēng)改 C 代碼里的 extract 參數(shù)。5.3 OAuth 與 Codex auth.json如果你在部署環(huán)節(jié)用到 Codex 相關(guān)的認(rèn)證auth.json 的配置要寫(xiě)全三件套Base URL、Key、Model ID。缺任何一個(gè)都會(huì)導(dǎo)致認(rèn)證失敗。Base URL 填https://taotoken.net/apiKey 填你的統(tǒng)一 KeyModel ID 按實(shí)際使用的模型填。5.4 推理結(jié)果異常排查檢測(cè)框位置偏移檢查 letterbox 的 padding 計(jì)算和坐標(biāo)還原是否對(duì)稱(chēng)。NCNN 推理里 wpad 和 hpad 的除以 2 操作要一致否則框會(huì)整體偏移。檢測(cè)不到目標(biāo)先確認(rèn) prob_threshold 是不是設(shè)太高默認(rèn) 0.25 可以調(diào)到 0.1 試試。如果還是不行檢查輸入圖像的歸一化NCNN 里用的是substract_mean_normalize(0, norm_vals)norm_vals 是 1/255。GPU 推理沒(méi)生效確認(rèn) NCNN 編譯時(shí)開(kāi)了 Vulkan且use_vulkan_compute設(shè)為 true?？梢杂胣cnn::get_gpu_count()打印一下返回 0 說(shuō)明 Vulkan 沒(méi)啟用。耗時(shí)異常RTX 3080 上單張 640x640 圖片的 GPU 推理耗時(shí)應(yīng)該在 10ms 以內(nèi)。如果超過(guò) 50ms檢查是不是回退到了 CPU 推理或者 bf16 存儲(chǔ)沒(méi)開(kāi)。6. 把訓(xùn)練和部署串成一條可復(fù)用的鏈路整條鏈路跑通之后你會(huì)發(fā)現(xiàn)真正花時(shí)間的不是寫(xiě)代碼而是環(huán)境配置和格式轉(zhuǎn)換的細(xì)節(jié)。我的建議是把這套流程腳本化數(shù)據(jù)轉(zhuǎn)換一個(gè)腳本、訓(xùn)練啟動(dòng)一個(gè)腳本、模型導(dǎo)出和轉(zhuǎn)換一個(gè)腳本、C 工程配置一份文檔。下次換數(shù)據(jù)集或換模型版本只改配置不改流程。統(tǒng)一 Key 通道的價(jià)值在這里體現(xiàn)得比較明顯——訓(xùn)練、轉(zhuǎn)換、部署三個(gè)環(huán)節(jié)的憑證收斂到一處換機(jī)器或換環(huán)境時(shí)不用逐個(gè)工具重新配。模型對(duì)話頁(yè)面 https://taotoken.net/model-chat 可以用來(lái)快速驗(yàn)證模型輸出是否符合預(yù)期接入文檔 https://taotoken.net/doc 里有各環(huán)節(jié)的配置示例。最后給一個(gè)實(shí)用技巧C 推理工程里把耗時(shí)打印出來(lái)每次改動(dòng)后對(duì)比耗時(shí)變化。GPU 推理的耗時(shí)對(duì) batch size、輸入尺寸、是否開(kāi) bf16 都很敏感有個(gè)基準(zhǔn)數(shù)字調(diào)優(yōu)時(shí)心里有數(shù)。檢測(cè)結(jié)果的可視化用 OpenCV 的 rectangle 和 putText 就夠重點(diǎn)是確認(rèn)三類(lèi)目標(biāo)的框和標(biāo)簽都對(duì)得上。