如何用 Label Studio + YOLO 快速构建自定义目标检测数据集（保姆级教程）

📁 开源项目

前言：为什么需要自定义目标检测数据集？

在上一篇文章中，我们介绍了三大数据标注开源神器。今天，我们来实战演练：如何用 Label Studio + YOLO 从零构建一个自定义目标检测数据集。

🎯 你可能遇到的场景

  • 工业质检：检测产品缺陷、划痕、污渍
  • 智慧城市：识别违章停车、垃圾堆放、占道经营
  • 零售行业：货架商品识别、库存盘点
  • 农业应用：作物病虫害检测、成熟度判断
  • 安防监控：异常行为检测、人员追踪

这些场景的共同点是：通用数据集（如 COCO、VOC）无法满足需求，必须自己标注数据。

💪 本文目标

完成本教程后，你将学会：

✅ 使用 Label Studio 高效标注图像数据
✅ 导出符合 YOLO 格式的训练数据
✅ 训练自己的 YOLOv8 目标检测模型
✅ 评估和优化模型性能
✅ 部署模型进行实时检测

预计耗时：2-3 小时（包含标注 100 张图片）

一、环境准备：搭建工作环境

1.1 安装 Label Studio

方法一：使用 Docker（推荐）

1
2
3
4
5
6
7
8
9
# 拉取镜像
docker pull heartexlabs/label-studio:latest

# 启动容器
docker run -it -p 8080:8080 \
  -v $(pwd)/label-studio-data:/label-studio/data \
  heartexlabs/label-studio:latest

# 访问 http://localhost:8080

方法二：使用 pip

1
2
3
4
5
6
7
8
9
# 创建虚拟环境
python -m venv labelstudio-env
source labelstudio-env/bin/activate  # Windows: labelstudio-env\Scripts\activate

# 安装 Label Studio
pip install label-studio

# 启动服务
label-studio start

1.2 安装 YOLOv8

1
2
3
4
5
# 安装 Ultralytics（YOLOv8 官方库）
pip install ultralytics

# 验证安装
yolo version

1.3 准备数据集目录结构

1
2
3
4
5
6
7
8
9
10
11
12
custom-detection-project/
├── images/              # 原始图片
│   ├── train/          # 训练集图片
│   ├── val/            # 验证集图片
│   └── test/           # 测试集图片
├── labels/              # YOLO 格式标注文件
│   ├── train/
│   ├── val/
│   └── test/
├── label-studio-export/ # Label Studio 导出数据
├── models/              # 训练好的模型
└── dataset.yaml         # YOLO 数据集配置文件

二、Label Studio 项目配置

2.1 创建项目

  1. 访问 http://localhost:8080
  2. 注册账号并登录
  3. 点击 “Create Project”
  4. 填写项目信息：
    • Project Name: 自定义目标检测
    • Description: 使用 YOLO 检测特定物体

2.2 配置标注界面

在 Labeling Setup 页面，选择 “Computer Vision” → “Object Detection with Bounding Boxes”，或使用自定义配置：

1
2
3
4
5
6
7
8
9
<View>
  <Image name="image" value="$image" zoom="true" zoomControl="true"/>
  <RectangleLabels name="label" toName="image">
    <Label value="目标类别1" background="#FF0000"/>
    <Label value="目标类别2" background="#00FF00"/>
    <Label value="目标类别3" background="#0000FF"/>
    <!-- 根据实际需求添加更多类别 -->
  </RectangleLabels>
</View>

配置说明：

  • zoom="true"：允许放大图片，方便精确标注
  • zoomControl="true"：显示缩放控制按钮
  • Label value：替换为你的实际类别名称
  • background：设置不同颜色便于区分

2.3 导入图片数据

方法一：本地文件上传

  1. 点击 “Import” 按钮
  2. 选择 “Upload Files”
  3. 批量选择图片（支持 JPG、PNG、WebP）
  4. 点击 “Import”

方法二：云存储导入（推荐大数据集）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 使用 Label Studio SDK 批量导入
from label_studio_sdk import Client

ls = Client(url='http://localhost:8080', api_key='你的API密钥')
project = ls.get_project(id=1)

# 从本地目录导入
import os
image_dir = './images/train'
tasks = []

for img_file in os.listdir(image_dir):
    if img_file.endswith(('.jpg', '.png', '.jpeg')):
        tasks.append({
            'data': {
                'image': f'/data/local-files/?d={image_dir}/{img_file}'
            }
        })

project.import_tasks(tasks)

三、高效标注技巧

3.1 标注流程

  1. 快速浏览：先快速浏览所有图片，了解数据分布
  2. 批量标注：按类别分批标注，提高一致性
  3. 使用快捷键：
    • 1, 2, 3...：快速切换标签类别
    • Ctrl + Enter：提交当前标注
    • Ctrl + Z：撤销上一步操作
    • Space：切换到下一张图片

3.2 标注质量控制

最佳实践：

✅ 边界框要紧贴目标：不要留太多空白
✅ 遮挡物体也要标注：即使只露出一部分
✅ 保持一致性：同一类别的标注标准要统一
✅ 定期休息：避免疲劳导致标注质量下降

示例：正确 vs 错误标注

1
2
3
✅ 正确：边界框紧贴目标，完整覆盖
❌ 错误：边界框过大，包含大量背景
❌ 错误：边界框过小，目标被裁切

3.3 使用 AI 辅助标注（可选）

如果已有预训练模型，可以集成到 Label Studio 进行预标注：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 创建 ML Backend
from label_studio_ml.model import LabelStudioMLBase
from ultralytics import YOLO

class YOLOBackend(LabelStudioMLBase):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.model = YOLO('yolov8n.pt')  # 使用预训练模型
    
    def predict(self, tasks, **kwargs):
        results = []
        for task in tasks:
            image_url = task['data']['image']
            # 运行推理
            predictions = self.model(image_url)
            # 转换为 Label Studio 格式
            # ... 格式转换代码
            results.append({'result': predictions})
        return results

四、导出 YOLO 格式数据

4.1 Label Studio 导出设置

  1. 在项目页面点击 “Export”
  2. 选择导出格式：“YOLO”
  3. 下载导出文件（ZIP 格式）

4.2 数据格式转换脚本

如果 Label Studio 导出的格式不完全符合 YOLO 要求，使用以下脚本转换：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
import json
import os
from pathlib import Path

def convert_labelstudio_to_yolo(json_file, output_dir, class_mapping):
    """
    将 Label Studio 导出的 JSON 转换为 YOLO 格式
    
    Args:
        json_file: Label Studio 导出的 JSON 文件路径
        output_dir: YOLO 标注文件输出目录
        class_mapping: 类别名称到索引的映射，如 {'cat': 0, 'dog': 1}
    """
    with open(json_file, 'r', encoding='utf-8') as f:
        data = json.load(f)
    
    Path(output_dir).mkdir(parents=True, exist_ok=True)
    
    for item in data:
        # 获取图片信息
        image_file = item['data']['image'].split('/')[-1]
        image_name = os.path.splitext(image_file)[0]
        
        # 获取图片尺寸
        img_width = item['annotations'][0]['original_width']
        img_height = item['annotations'][0]['original_height']
        
        # 处理标注
        yolo_annotations = []
        for annotation in item['annotations'][0]['result']:
            if annotation['type'] == 'rectanglelabels':
                # 获取类别
                label = annotation['value']['rectanglelabels'][0]
                class_id = class_mapping[label]
                
                # 获取边界框坐标（百分比）
                x = annotation['value']['x']
                y = annotation['value']['y']
                width = annotation['value']['width']
                height = annotation['value']['height']
                
                # 转换为 YOLO 格式（中心点坐标 + 宽高，归一化）
                x_center = (x + width / 2) / 100
                y_center = (y + height / 2) / 100
                norm_width = width / 100
                norm_height = height / 100
                
                yolo_annotations.append(
                    f"{class_id} {x_center:.6f} {y_center:.6f} {norm_width:.6f} {norm_height:.6f}"
                )
        
        # 保存为 .txt 文件
        output_file = os.path.join(output_dir, f"{image_name}.txt")
        with open(output_file, 'w') as f:
            f.write('\n'.join(yolo_annotations))
        
        print(f"已转换: {image_file} -> {output_file}")

# 使用示例
class_mapping = {
    '目标类别1': 0,
    '目标类别2': 1,
    '目标类别3': 2
}

convert_labelstudio_to_yolo(
    json_file='./label-studio-export/result.json',
    output_dir='./labels/train',
    class_mapping=class_mapping
)

4.3 数据集划分

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
import shutil
import random
from pathlib import Path

def split_dataset(image_dir, label_dir, output_dir, train_ratio=0.7, val_ratio=0.2):
    """
    将数据集划分为训练集、验证集、测试集
    
    Args:
        image_dir: 图片目录
        label_dir: 标注文件目录
        output_dir: 输出目录
        train_ratio: 训练集比例
        val_ratio: 验证集比例
    """
    # 获取所有图片文件
    images = list(Path(image_dir).glob('*.jpg')) + list(Path(image_dir).glob('*.png'))
    random.shuffle(images)
    
    # 计算划分点
    total = len(images)
    train_end = int(total * train_ratio)
    val_end = train_end + int(total * val_ratio)
    
    # 划分数据
    splits = {
        'train': images[:train_end],
        'val': images[train_end:val_end],
        'test': images[val_end:]
    }
    
    # 复制文件
    for split_name, split_images in splits.items():
        img_out = Path(output_dir) / 'images' / split_name
        lbl_out = Path(output_dir) / 'labels' / split_name
        img_out.mkdir(parents=True, exist_ok=True)
        lbl_out.mkdir(parents=True, exist_ok=True)
        
        for img_path in split_images:
            # 复制图片
            shutil.copy(img_path, img_out / img_path.name)
            
            # 复制标注文件
            label_file = Path(label_dir) / f"{img_path.stem}.txt"
            if label_file.exists():
                shutil.copy(label_file, lbl_out / label_file.name)
        
        print(f"{split_name}: {len(split_images)} 张图片")

# 使用示例
split_dataset(
    image_dir='./images',
    label_dir='./labels',
    output_dir='./dataset',
    train_ratio=0.7,
    val_ratio=0.2
)

五、训练 YOLOv8 模型

5.1 创建数据集配置文件

创建 dataset.yaml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 数据集路径
path: ./dataset  # 数据集根目录
train: images/train  # 训练集图片路径（相对于 path）
val: images/val      # 验证集图片路径
test: images/test    # 测试集图片路径（可选）

# 类别
names:
  0: 目标类别1
  1: 目标类别2
  2: 目标类别3

# 类别数量
nc: 3

5.2 开始训练

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
from ultralytics import YOLO

# 加载预训练模型（迁移学习）
model = YOLO('yolov8n.pt')  # n: nano, s: small, m: medium, l: large, x: xlarge

# 训练模型
results = model.train(
    data='dataset.yaml',      # 数据集配置文件
    epochs=100,               # 训练轮数
    imgsz=640,                # 输入图片尺寸
    batch=16,                 # 批次大小（根据显存调整）
    name='custom-detection',  # 实验名称
    patience=20,              # 早停耐心值
    save=True,                # 保存最佳模型
    device=0,                 # GPU 设备（0 表示第一块 GPU，'cpu' 表示 CPU）
    workers=8,                # 数据加载线程数
    project='runs/detect',    # 项目目录
    exist_ok=True,            # 允许覆盖已存在的实验
    pretrained=True,          # 使用预训练权重
    optimizer='AdamW',        # 优化器
    lr0=0.01,                 # 初始学习率
    lrf=0.01,                 # 最终学习率（lr0 * lrf）
    momentum=0.937,           # 动量
    weight_decay=0.0005,      # 权重衰减
    warmup_epochs=3,          # 预热轮数
    warmup_momentum=0.8,      # 预热动量
    box=7.5,                  # 边界框损失权重
    cls=0.5,                  # 分类损失权重
    dfl=1.5,                  # DFL 损失权重
    hsv_h=0.015,              # 色调增强
    hsv_s=0.7,                # 饱和度增强
    hsv_v=0.4,                # 明度增强
    degrees=0.0,              # 旋转增强
    translate=0.1,            # 平移增强
    scale=0.5,                # 缩放增强
    shear=0.0,                # 剪切增强
    perspective=0.0,          # 透视增强
    flipud=0.0,               # 上下翻转概率
    fliplr=0.5,               # 左右翻转概率
    mosaic=1.0,               # Mosaic 增强概率
    mixup=0.0,                # Mixup 增强概率
)

print(f"训练完成！最佳模型保存在: {results.save_dir}")

5.3 训练参数说明

模型选择：

  • yolov8n.pt：最快，适合实时检测（推荐入门）
  • yolov8s.pt：速度与精度平衡
  • yolov8m.pt：更高精度
  • yolov8l.pt、yolov8x.pt：最高精度，需要更强算力

关键参数：

  • epochs：训练轮数，建议 100-300
  • batch：批次大小，根据显存调整（16GB 显存建议 16-32）
  • imgsz：图片尺寸，越大精度越高但速度越慢
  • patience：早停机制，验证集性能不提升的容忍轮数

5.4 监控训练过程

训练过程中会生成以下文件：

1
2
3
4
5
6
7
8
9
10
runs/detect/custom-detection/
├── weights/
│   ├── best.pt          # 最佳模型
│   └── last.pt          # 最后一轮模型
├── results.png          # 训练曲线图
├── confusion_matrix.png # 混淆矩阵
├── F1_curve.png         # F1 曲线
├── P_curve.png          # 精确率曲线
├── R_curve.png          # 召回率曲线
└── PR_curve.png         # PR 曲线

使用 TensorBoard 实时监控：

1
2
3
4
# 启动 TensorBoard
tensorboard --logdir runs/detect

# 访问 http://localhost:6006

六、模型评估与优化

6.1 评估模型性能

1
2
3
4
5
6
7
8
9
10
11
12
13
from ultralytics import YOLO

# 加载最佳模型
model = YOLO('runs/detect/custom-detection/weights/best.pt')

# 在验证集上评估
metrics = model.val(data='dataset.yaml')

# 打印关键指标
print(f"mAP50: {metrics.box.map50:.3f}")      # mAP@0.5
print(f"mAP50-95: {metrics.box.map:.3f}")     # mAP@0.5:0.95
print(f"Precision: {metrics.box.mp:.3f}")     # 精确率
print(f"Recall: {metrics.box.mr:.3f}")        # 召回率

6.2 性能指标解读

指标 说明 目标值
mAP50 IoU=0.5 时的平均精度 > 0.7
mAP50-95 IoU 从 0.5 到 0.95 的平均精度 > 0.5
Precision 预测为正例中真正例的比例 > 0.8
Recall 真正例中被预测为正例的比例 > 0.8

6.3 优化策略

如果精度不够：

  1. 增加数据量：标注更多图片（建议每类至少 500 张）
  2. 提高标注质量：重新审核标注，修正错误
  3. 使用更大模型：从 yolov8n 升级到 yolov8s 或 yolov8m
  4. 增加训练轮数：从 100 增加到 200-300
  5. 调整数据增强：增加 mosaic、mixup 等

如果速度不够：

  1. 使用更小模型：yolov8n 或量化模型
  2. 减小输入尺寸：从 640 降到 480 或 320
  3. 模型剪枝：使用 ultralytics 的剪枝功能
  4. 导出为 TensorRT：GPU 推理加速

6.4 错误分析

1
2
3
4
5
6
7
8
9
10
11
12
13
# 在测试集上推理并保存结果
results = model.predict(
    source='dataset/images/test',
    save=True,
    save_txt=True,
    conf=0.25,  # 置信度阈值
    iou=0.45,   # NMS IoU 阈值
    project='runs/detect',
    name='test-results'
)

# 查看预测结果
# runs/detect/test-results/ 目录下会保存标注后的图片

常见错误类型：

  • 漏检：目标未被检测到 → 增加数据、降低置信度阈值
  • 误检：背景被误识别为目标 → 增加负样本、提高置信度阈值
  • 定位不准：边界框偏移 → 提高标注质量、增加训练轮数

七、模型部署与推理

7.1 Python 推理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
from ultralytics import YOLO
import cv2

# 加载模型
model = YOLO('runs/detect/custom-detection/weights/best.pt')

# 单张图片推理
results = model('test-image.jpg')

# 处理结果
for result in results:
    boxes = result.boxes  # 边界框
    for box in boxes:
        # 获取坐标
        x1, y1, x2, y2 = box.xyxy[0].cpu().numpy()
        # 获取置信度和类别
        conf = box.conf[0].cpu().numpy()
        cls = int(box.cls[0].cpu().numpy())
        
        print(f"类别: {model.names[cls]}, 置信度: {conf:.2f}, 坐标: ({x1:.0f}, {y1:.0f}, {x2:.0f}, {y2:.0f})")

# 保存结果
result.save('output.jpg')

7.2 实时视频检测

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import cv2
from ultralytics import YOLO

model = YOLO('runs/detect/custom-detection/weights/best.pt')

# 打开摄像头
cap = cv2.VideoCapture(0)

while True:
    ret, frame = cap.read()
    if not ret:
        break
    
    # 推理
    results = model(frame, conf=0.5)
    
    # 绘制结果
    annotated_frame = results[0].plot()
    
    # 显示
    cv2.imshow('YOLOv8 Detection', annotated_frame)
    
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()

7.3 导出为其他格式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
from ultralytics import YOLO

model = YOLO('runs/detect/custom-detection/weights/best.pt')

# 导出为 ONNX（跨平台）
model.export(format='onnx')

# 导出为 TensorRT（NVIDIA GPU 加速）
model.export(format='engine', device=0)

# 导出为 CoreML（iOS/macOS）
model.export(format='coreml')

# 导出为 TFLite（移动端）
model.export(format='tflite')

八、实战案例：工业缺陷检测

8.1 项目背景

某电子厂需要检测 PCB 板上的三种缺陷：

  • 划痕（Scratch）
  • 污渍（Stain）
  • 缺件（Missing）

8.2 数据准备

  1. 收集图片：拍摄 500 张 PCB 板图片
  2. Label Studio 标注：3 名标注员，每人标注 200 张，交叉验证
  3. 数据增强：使用 Albumentations 增强到 2000 张
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import albumentations as A
import cv2

# 定义增强策略
transform = A.Compose([
    A.RandomRotate90(p=0.5),
    A.Flip(p=0.5),
    A.RandomBrightnessContrast(p=0.3),
    A.GaussNoise(p=0.2),
    A.Blur(blur_limit=3, p=0.2),
], bbox_params=A.BboxParams(format='yolo', label_fields=['class_labels']))

# 应用增强
image = cv2.imread('original.jpg')
with open('original.txt', 'r') as f:
    bboxes = [list(map(float, line.split())) for line in f]

class_labels = [int(bbox[0]) for bbox in bboxes]
bboxes_coords = [bbox[1:] for bbox in bboxes]

transformed = transform(image=image, bboxes=bboxes_coords, class_labels=class_labels)

8.3 训练配置

1
2
3
4
5
6
7
8
9
10
11
12
model = YOLO('yolov8s.pt')  # 使用 small 模型平衡速度和精度

results = model.train(
    data='pcb-defect.yaml',
    epochs=200,
    imgsz=1024,  # PCB 图片细节多，使用更大尺寸
    batch=8,
    patience=30,
    mosaic=1.0,
    mixup=0.1,
    copy_paste=0.1,  # 复制粘贴增强
)

8.4 结果

  • mAP50: 0.89
  • mAP50-95: 0.72
  • 推理速度: 45 FPS（RTX 3060）
  • 部署: 集成到生产线，实时检测

九、常见问题与解决方案

Q1: 标注数据量要多少？

A: 取决于任务复杂度：

  • 简单场景（背景单一、目标明显）：每类 200-500 张
  • 中等复杂度：每类 500-1000 张
  • 复杂场景（遮挡、光照变化大）：每类 1000-5000 张

技巧：使用数据增强可以有效扩充数据集。

Q2: 训练时显存不足怎么办？

A:

  1. 减小 batch 大小（如从 16 降到 8 或 4）
  2. 减小 imgsz（如从 640 降到 480）
  3. 使用更小的模型（如 yolov8n）
  4. 使用梯度累积（修改源码）

Q3: 模型过拟合怎么办？

A:

  1. 增加数据量
  2. 增强数据增强强度
  3. 使用 Dropout（修改模型配置）
  4. 减小模型复杂度
  5. 早停（通过 patience 参数）

Q4: 小目标检测效果差？

A:

  1. 增大输入尺寸（如 imgsz=1280）
  2. 使用多尺度训练
  3. 调整 Anchor 尺寸
  4. 使用专门的小目标检测模型（如 YOLOv8-P2）

Q5: 如何处理类别不平衡？

A:

  1. 对少数类进行过采样
  2. 使用 Focal Loss（修改损失函数）
  3. 调整类别权重
  4. 使用 SMOTE 等合成数据方法

十、总结与进阶

🎉 你已经学会了

✅ 使用 Label Studio 高效标注数据
✅ 将标注数据转换为 YOLO 格式
✅ 训练自定义 YOLOv8 模型
✅ 评估和优化模型性能
✅ 部署模型进行实时检测

🚀 进阶方向

  1. 多模型集成：结合多个模型提升精度
  2. 主动学习：自动挑选难例进行标注
  3. 模型压缩：剪枝、量化、蒸馏
  4. 边缘部署：部署到树莓派、Jetson Nano
  5. 3D 目标检测：扩展到点云数据

📚 推荐资源

🎁 福利：完整代码仓库

我已将本教程的完整代码、配置文件、示例数据集整理到 GitHub：

仓库地址：（替换为你的实际仓库地址）

包含内容：

  • Label Studio 配置模板
  • 数据转换脚本
  • 训练脚本
  • 推理示例
  • 常用工具函数

如果这篇教程对你有帮助，记得点赞 + 在看 + 转发！

有任何问题欢迎在评论区留言，我会及时回复！

💡 关注我，持续分享 AI 实战教程、开源项目、行业洞察！
下期预告：《YOLOv8 vs YOLOv9 vs YOLOv10：目标检测模型全面对比》

🏷️ GitHub 教程 开源项目