YOLO 自动标注实战：Label Studio + Docker Compose 部署

1. 概述

Label Studio 是一个开源的数据标注平台，配合 YOLO ML Backend 可以实现：

• 目标检测（Bounding Box）
• 旋转目标检测（OBB）
• 实例分割（Segmentation）
• 关键点检测（Pose Estimation）
• 多目标跟踪（Tracking）

本文详细介绍如何使用 Docker Compose 一键部署 Label Studio + YOLO 自动标注后端。

2. 架构

flowchart LR
    A[📁 Images<br>Dataset] --> B[🏷️ Label Studio<br>Web UI :8006]
    B --> C[🔗 YOLO ML<br>Backend :9090]
    C --> D[🤖 YOLO Model<br>Inference]
    
    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#e8f5e9
    style D fill:#ffebee

3. 目录结构

label-studio-yolo/
├── docker-compose.yml
├── models/              # YOLO 模型目录
│   └── my_model.pt
├── data/server/          # Label Studio 数据
├── cache_dir/            # 缓存
├── images/               # 待标注图片
└── label-studio/data/   # Label Studio 存储

4. Docker Compose 配置

4.1 docker-compose.yml

version: '3.8'

services:
  label-studio:
    image: heartexlabs/label-studio:latest
    container_name: label-studio
    ports:
      - "8006:8080"
    environment:
      - LABEL_STUDIO_LOCAL_FILES_SERVING_ENABLED=true
      - LABEL_STUDIO_LOCAL_FILES_ROOT=/label-studio/data
    volumes:
      - ./label-studio/data:/label-studio/data
      - ./images:/images:ro
    restart: unless-stopped

  yolo-backend:
    container_name: yolo
    image: heartexlabs/label-studio-ml-backend:yolo-20250811.131142-master-c3d746b
    environment:
      # 基础认证（可选）
      - BASIC_AUTH_USER=admin
      - BASIC_AUTH_PASS=admin+123
      
      # 日志级别
      - LOG_LEVEL=DEBUG
      
      # 服务参数
      - WORKERS=1
      - THREADS=8
      
      # 模型目录
      - MODEL_DIR=/data/models
      - MODEL_ROOT=/app/models
      - PYTHONPATH=/app
      
      # Label Studio 连接配置
      # ⚠️ 不要使用 localhost 或 127.0.0.1，Docker 容器内无法访问
      # 使用实际 IP 或 host.docker.internal
      - LABEL_STUDIO_HOST=http://192.168.0.179:8006/
      - LABEL_STUDIO_API_KEY=你的API密钥
      
      # YOLO 参数
      - ALLOW_CUSTOM_MODEL_PATH=true
      - DEBUG_PLOT=false
      - MODEL_SCORE_THRESHOLD=0.5
    extra_hosts:
      - "host.docker.internal:host-gateway"
    ports:
      - "9090:9090"
    volumes:
      - ./data/server:/data
      - ./models:/app/models
      - ./cache_dir:/app/cache_dir
    restart: unless-stopped

4.2 关键配置说明

4.3 获取 API Key

1. 登录 Label Studio
2. 点击右上角头像 → Settings
3. 选择 Account 标签
4. 复制 API Key

⚠️ 注意：LABEL_STUDIO_HOST 必须使用实际 IP，不能用 localhost，因为 Docker 容器之间通过网络通信。

5. 放置模型

将训练好的 YOLO 模型文件放到 models/ 目录：

mkdir -p models
# 放入你的模型，如 best.pt 或 yolov8n.pt
cp /path/to/your/custom_model.pt models/my_model.pt

模型在标注配置的 model_path 参数中指定，无需在 docker-compose.yml 中配置。

模型文件要求

6. Label Studio 标注配置

6.1 目标检测（推荐）

<View>
  <Image name="image" value="$image"/>
  <RectangleLabels name="label" toName="image" 
    model_path="fire_20260512.pt"
    model_score_threshold="0.1"
    model_nms_threshold="0.3">
    <Label value="fire" background="green"/>
    <Label value="smoke" background="blue"/>
    <Label value="other" background="#FFA39E"/>
  </RectangleLabels>
</View>

关键参数说明：

⚠️ 注意：模型文件需要预先放入 models/ 目录，并在 ML Backend 中完成连接配置。

7. 部署步骤

7.1 启动 Label Studio

docker compose up -d label-studio

等待启动完成后访问 http://localhost:8006，注册账号并登录。

7.2 启动 ML Backend

docker compose up -d yolo-backend

7.3 新建项目

1. 点击 Create Project
2. 填写项目名称（如：火灾检测）
3. 点击 Add Labeling Configuration，粘贴上述 XML 配置

7.4 配置 ML Backend

1. 进入 Settings → ML Backend
2. 点击 Add Backend
3. 填写：
   • URL: http://localhost:9090
   • Description: YOLO Auto Labeling
4. 点击 Check connection 确认连接成功

7.5 上传图片并标注

1. 进入项目 → Import
2. 上传待标注图片
3. 点击 Label 进入标注界面
4. 点击 Predict 或 Annotate 按钮触发自动标注

9. 批量导入图片

创建 tasks.json 格式的导入文件：

[
  {"image": "/images/img001.jpg"},
  {"image": "/images/img002.jpg"},
  {"image": "/images/img003.jpg"}
]

或者使用 Python SDK：

from label_studio_sdk import Client

ls = Client(
    url='http://localhost:8006',
    api_key='your-api-key'
)

project = ls.get_project(id=1)

# 批量导入
import glob
images = glob.glob('./images/*.jpg')

for img_path in images:
    project.create_task(data={'image': img_path})

10. 导出标注结果

导出为 YOLO 格式：

# 在 Label Studio UI 中
# Project → Export → YOLO ZIP

导出的目录结构：

yolo_export/
├── classes.txt
├── images/
│   ├── img001.jpg
│   └── img002.jpg
└── labels/
    ├── img001.txt
    └── img002.txt

classes.txt 内容：

person
car
dog
cat

img001.txt 内容（YOLO 格式）：

0 0.5 0.5 0.3 0.4
1 0.2 0.3 0.1 0.2

格式说明：class_id x_center y_center width height（归一化）

11. GPU 加速

如果使用 GPU 加速，修改 docker-compose.yml：

services:
  yolo-backend:
    image: heartexlabs/label-studio-ml-backend:yolo-20250811.131142-master-c3d746b
    runtime: nvidia  # 添加这行
    environment:
      - CUDA_VISIBLE_DEVICES=0
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

确保安装了 NVIDIA Container Toolkit。

12. 常见问题

Q1: ML Backend 连接失败

# 检查服务状态
docker compose ps

# 查看日志
docker compose logs yolo-backend

# 检查端口是否占用
netstat -tlnp | grep 9090

Q2: 标签名称不匹配

确保 Label Studio 的标签名与 YOLO 模型输出的类别名一致，或使用 predicted_values 属性映射。

Q3: 模型加载失败

# 检查模型文件是否存在
ls -la models/

# 手动测试模型
docker exec -it yolo python -c "from ultralytics import YOLO; YOLO('/app/models/yolov8n.pt')"

Q4: 内存不足

使用更小的模型或在标注配置中降低 model_score_threshold：

model_score_threshold="0.3"

13. 推荐模型

14. 完整项目结构

label-studio-yolo/
├── docker-compose.yml
├── README.md
├── models/              # YOLO 模型目录
│   └── my_model.pt     # 你的自定义模型
├── data/
│   └── server/          # Label Studio 数据
├── cache_dir/           # 缓存目录
├── images/              # 待标注图片
└── label-studio/
    └── data/           # Label Studio 存储

注意：不需要自定义 Dockerfile，使用官方预构建的 yolo-20250811.131142-master-c3d746b 镜像即可，该镜像已包含 YOLO 支持。

15. 一键启动

#!/bin/bash

# 创建目录
mkdir -p models data/server cache_dir images label-studio/data

# 下载默认模型（可选）
# wget -O models/yolov8n.pt \
#   https://github.com/ultralytics/assets/releases/download/v8.2.0/yolov8n.pt

# 启动服务
docker compose up -d

echo "======================================"
echo "  Label Studio: http://localhost:8006"
echo "  YOLO Backend: http://localhost:9090"
echo "======================================"
echo ""
echo "首次使用需要："
echo "1. 访问 http://localhost:8006 注册账号"
echo "2. Settings → Account → 获取 API Key"
echo "3. 更新 docker-compose.yml 中的 LABEL_STUDIO_API_KEY"
echo "4. Settings → ML Backend → 添加后端 http://localhost:9090"

首次部署后记得修改 LABEL_STUDIO_API_KEY 为你的实际密钥！

总结

使用 Docker Compose 部署 Label Studio + YOLO 自动标注后端，可以快速搭建一个完整的 AI 辅助标注系统。

关键点：

1. 使用 predicted_values 映射标签
2. 自定义模型放在 models/ 目录
3. 修改环境变量指定模型名称
4. GPU 加速需要添加 runtime: nvidia

有问题欢迎留言讨论！