# label-studio

**Repository Path**: zhddzrai/label-studio

## Basic Information

- **Project Name**: label-studio
- **Description**: 基于 HumanSignal/label-studio 的二次开发版本，在原有数据标注功能基础上增加了 超级管理员（Superuser）权限体系、多组织管理能力 和 YOLO 模型训练集成
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2026-11-03
- **Last Updated**: 2026-11-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Label Studio（训练增强版）

基于 [HumanSignal/label-studio](https://github.com/HumanSignal/label-studio) 的二次开发版本，在原有数据标注能力上增加了 **YOLO 模型训练模块**（多项目导出、配置管理、训练机 SSH 派发、任务进度与模型下载）。

---

## 训练模块做什么

入口：**Projects → Train**（`/projects/train`）。

| 能力 | 说明 |
|------|------|
| 多项目训练 | 勾选多个项目合并导出后一起训练（类别须与配置 `classes` 一致） |
| 任务驱动 | 每次开训产生一条任务；进度 / 日志 / 报错 / 模型下载在任务详情中查看 |
| 配置管理 | 独立「配置管理」页，支持完整 YOLO 超参；开训可选 YOLO 版本与尺寸档位 |
| 数据流转 | 导出 YOLO → 划分数据集（训练 80% / 验证 15% / 测试 5%）→ `data.yaml` → 训练 |
| 预训练权重 | 本地 `cv-ultralytics/.../models/` 有对应 `.pt` 则直接用，否则国内镜像竞速下载 |
| 产物 | 可下载 `best.pt` / `last.pt`，并展示 F1 等曲线（若生成） |
| 训练调度 | 默认由标注端经 **SSH 派发**到 GPU 机；也支持本机 / RQ Worker |

支持任务类型：`obb`（旋转框）、`detect`（检测）、`cls`（分类）、`seg`（分割）。

**角色约定：**

| 端 | 职责 | GPU |
|----|------|-----|
| **A 标注端** | 网页、Postgres、Redis、导出数据包、SSH 派发、拉取产物 | 否 |
| **B 训练端** | 收包、YOLO 训练（`training.remote_runner`） | 是 |

默认流程：A 导出并 scp 到 B → SSH 拉起 `python -m training.remote_runner` → 训完后 **A 从 B 拉取** `best.pt` 等产物到 `mydata/media/training_xfer/job_<id>/artifacts/`。

---

## 上线发布流程

有代码变更需要上线时，按下面顺序做（前端 → Python 包 → 迁移 → 重启）。Docker 镜像构建会在镜像内完成前端与 Python 安装，不必在宿主机单独 `yarn` / `poetry build`；**非 Docker / 本地或 conda 部署**则要显式执行。

### 1）拉取代码

```bash
cd /path/to/label-studio
git pull
```

### 2）构建前端（有前端改动时必做）

```bash
cd web
yarn install --frozen-lockfile
yarn run build
cd ..
```

或：`make frontend-build`。

### 3）安装 / 打包 Python（按部署方式二选一）

```bash
# 开发或本机 conda：安装依赖
poetry install
# 若只验证分发包：
poetry build

# 或可编辑安装（GPU 训练机常用）
pip install -e .
```

训练相关还需本机已装好 `torch` / `ultralytics`（见下文训练端章节）。

### 4）数据库迁移（有模型/字段变更时必做）

```bash
# 本地 / Poetry
poetry run python label_studio/manage.py migrate

# 标注端 Docker
docker compose --env-file .env run --rm app \
  python3 /label-studio/label_studio/manage.py migrate
```

### 5）重启服务

```bash
# Docker 标注端
docker compose --env-file .env up -d --build nginx app db redis

# 本地开发
make run-dev
```

> 每次更新务必确认迁移已跑；有前端改动务必 `yarn build`（或镜像 `--build`），否则训练页不会生效。  
> B 训练机若走 SSH 派发，还需保证 B 上代码与 A 一致（尤其 `label_studio/training/`、`cv-ultralytics/`）。

### 生产 Docker 镜像（可选）

```bash
docker build -t <registry>/label-studio:<tag> .
# 镜像内已含前端生产构建与 Python 依赖
```

---

## 怎么选部署方式

| 场景 | 看哪一节 |
|------|----------|
| 生产标注网页 / DB / Redis | **方式一：标注端 Docker** |
| 本机改代码调试 | **方式二：本地 Poetry 开发** |
| GPU 训练（推荐） | **方式三：两机 SSH 派发** |
| 不走页面派发、常驻听队列 | **方式四：RQ Worker（conda 或 Docker）** |

---

## 方式一：标注端 Docker（推荐生产）

标注端 **不需要 GPU**。默认 `TRAINING_DATA_MODE=ssh`，由页面「训练机」SSH 派发，**不必**起本机 `training-worker`。

### 目录

```text
label-studio/
├── docker-compose.yml
├── .env.example          ← 复制成 .env
├── mydata/               ← 数据 / 媒体 / SSH 密钥
├── postgres-data/
├── redis-data/
└── cv-ultralytics/       ← 可空挂载；真正训练在 GPU 机
```

### 配置

```bash
cp .env.example .env
# 至少填写：
#   LABEL_STUDIO_HOST=http://<对外访问地址>:8080
#   TRAINING_A_BIND_HOST=<A 内网 IP>   # 写入远程环境，供 B 连 Postgres/Redis
```

### 启动

```bash
mkdir -p mydata postgres-data redis-data cv-ultralytics
chown -R 1001:0 mydata || true

docker compose --env-file .env up -d --build nginx app db redis

docker compose --env-file .env run --rm app \
  python3 /label-studio/label_studio/manage.py migrate
docker compose --env-file .env run --rm app \
  python3 /label-studio/label_studio/manage.py createsuperuser
```

浏览器打开 `LABEL_STUDIO_HOST`（默认宿主机 **8080**）。

### 开训前（网页）

1. **Train → 训练机**：显示名、内网 IP、SSH 用户/密码、**代码目录**、**conda 环境名** → **测试连接**（成功后公钥写入 B，密码不落库）。
2. **Train → 开始训练**：选项目、配置、训练机后开训。

状态「可派发」表示：SSH 通 + 远程代码目录含 `remote_runner` + conda 可激活并 import 成功（不是「训练进程正在跑」）。

### 更新标注端

```bash
git pull
docker compose --env-file .env up -d --build nginx app db redis
docker compose --env-file .env run --rm app \
  python3 /label-studio/label_studio/manage.py migrate
```

### 可选：同机 GPU RQ Worker

仅当标注与训练在同一 Docker 主机、且用共享盘时：

```bash
# .env 中 TRAINING_DATA_MODE=shared
docker compose --env-file .env --profile gpu up -d training-worker
```

多机 SSH 派发场景 **不要** 启用。

---

## 方式二：本地 Poetry 开发

```bash
pip install poetry
poetry install
# 若本机也要跑训练：
pip install torch torchvision ultralytics -i https://pypi.tuna.tsinghua.edu.cn/simple

export TRAINING_EXECUTOR=local
export TRAINING_DATA_MODE=shared

DJANGO_DB=sqlite DJANGO_SETTINGS_MODULE=core.settings.label_studio \
  poetry run python label_studio/manage.py migrate
DJANGO_DB=sqlite DJANGO_SETTINGS_MODULE=core.settings.label_studio \
  poetry run python label_studio/manage.py createsuperuser

TRAINING_EXECUTOR=local TRAINING_DATA_MODE=shared make run-dev
```

浏览器：`http://localhost:8080`。改前端后：

```bash
cd web && yarn install && yarn run build && cd ..
```

---

## 方式三：两机 SSH 派发（推荐 GPU 训练）

**A** 起标注服务；**B** 装好 conda + 代码即可，**不必**常驻 `rqworker`。训练进程由 A 临时拉起。

### B 上目录（须与网页「代码目录」一致）

```text
/root/label-studio/          # 或页面填写的 remote_root
├── label_studio/            # 含 training/
├── cv-ultralytics/
└── mydata/                  # 收包、临时产物（自动出现）
```

```bash
git clone <本仓库地址> /root/label-studio
cd /root/label-studio
```

### B 上 Python 环境

网页「训练机」里填写的 **conda 环境名** 须与本机一致（例如 `label-train` / `lable`）。

```bash
source /root/miniforge3/etc/profile.d/conda.sh   # 按实际路径改
conda create -n label-train python=3.11 -y
conda activate label-train

conda install -y "numpy>=2.2.6,<3" pandas pillow contourpy matplotlib \
  gxx_linux-64 gcc_linux-64 -c conda-forge

pip install torch torchvision \
  --index-url https://download.pytorch.org/whl/cu118 \
  --extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip install ultralytics -i https://pypi.tuna.tsinghua.edu.cn/simple

cd /root/label-studio
pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

python -c "import torch,django,ultralytics; print(torch.__version__, torch.cuda.is_available())"
```

AMP 需要样例图：`cv-ultralytics/ultralytics/ultralytics/assets/bus.jpg`（仓库已带）。

### 网络

| 方向 | 端口 | 用途 |
|------|------|------|
| A → B | 22 | 测连通、推包、拉起 `remote_runner`、拉取产物 |
| B → A | 5432 / 6379 | 远程写训练任务状态 |

```bash
systemctl enable --now sshd
# 防火墙：A→B:22；B→A:5432、6379
```

A 的 `.env` 必须填 `TRAINING_A_BIND_HOST=<A 内网 IP>`。

### 日志与产物（B / A）

```bash
# B：任务日志
tail -f /root/label-studio/mydata/media/training_xfer/job_<id>/remote_train.log

# B：训练目录
ls /root/label-studio/cv-ultralytics/runs/job_<id>/

# A：拉取后的产物（网页可下载）
ls mydata/media/training_xfer/job_<id>/artifacts/
```

---

## 方式四：RQ Worker（备选）

不走页面 SSH 派发时，B 常驻听 Redis `training` 队列。与方式三 **不要**在同一台机无说明地混用。

A 侧需 `TRAINING_EXECUTOR=rq`，且节点调度与队列一致。

### 4-A：conda 常驻 Worker

```bash
# 1）同方式三装好依赖与代码
# 2）准备能登录 A 的 SSH 私钥（Worker 拉包 / 回传）
mkdir -p /root/label-studio/ssh
# 放入私钥 → ./ssh/id_rsa ，chmod 600

cd /root/label-studio
export DJANGO_DB=default
export DJANGO_SETTINGS_MODULE=core.settings.label_studio
export POSTGRE_HOST=<A内网IP>
export POSTGRE_NAME=postgres
export POSTGRE_USER=postgres
export POSTGRE_PASSWORD=<密码>
export POSTGRE_PORT=5432
export REDIS_HOST=<A内网IP>
export REDIS_PORT=6379
export TRAINING_DATA_MODE=ssh
export TRAINING_SSH_HOST=<A内网IP>
export TRAINING_SSH_USER=root
export TRAINING_SSH_KEY=/root/label-studio/ssh/id_rsa
export TRAINING_SSH_REMOTE_DATA=/root/label-studio/mydata
export CV_ULTRA_PATH=/root/label-studio/cv-ultralytics

python label_studio/manage.py rqworker training
```

后台示例：

```bash
nohup python label_studio/manage.py rqworker training \
  > /root/label-studio/training-worker.log 2>&1 &
```

### 4-B：Docker 训练 Worker

```bash
# 前置：NVIDIA Container Toolkit；./ssh/id_rsa 能登 A；cv-ultralytics 齐全
export POSTGRE_HOST=<A内网IP>
export REDIS_HOST=<A内网IP>
export TRAINING_DATA_MODE=ssh
export TRAINING_SSH_HOST=<A内网IP>
export TRAINING_SSH_USER=root
export TRAINING_SSH_KEY=/ssh/id_rsa
export TRAINING_SSH_REMOTE_DATA=/root/label-studio/mydata

docker compose -f docker-compose.training.yml up -d --build
docker compose -f docker-compose.training.yml logs -f training-worker
```

---

## 训练端检查清单

| 项 | SSH 派发 | RQ / Docker Worker |
|----|----------|--------------------|
| 代码目录与页面一致 | ✅ | ✅ |
| conda + torch(CUDA) + ultralytics + 本仓库 | ✅ | ✅ |
| `cv-ultralytics` + `assets/bus.jpg` | ✅ | ✅ |
| A→B:22 | ✅ | 按需 |
| B→A:5432、6379 | ✅ | ✅ |
| 常驻 `rqworker` | ❌ | ✅ |
| A `.env` 中 `TRAINING_A_BIND_HOST` | ✅ | 按需 |
| 网页「conda 环境名」可 activate | ✅ | — |

---

## 出问题先看这

| 现象 | 怎么办 |
|------|--------|
| 网页起不来 | `docker compose ps` / `logs app nginx` |
| 测试连接失败 | 容器能否访问训练机 22；密码；镜像是否含 paramiko（需 `--build`） |
| 下拉里「离线」/ 不可派发 | 检查 SSH、代码目录、`remote_runner`、conda 环境名后重新「测试连接」 |
| 本地点训练没反应 | `TRAINING_EXECUTOR=local` |
| `mydata/ssh` 写不了 | `chown -R 1001:0 mydata` |
| 缺 `bus.jpg` | 放到 `cv-ultralytics/ultralytics/ultralytics/assets/` |
| Docker 无 GPU | 安装 nvidia-container-toolkit 并重启 dockerd |
| RQ Worker 起不来 | `POSTGRE_HOST` / `REDIS_HOST` 是否指向 A |
| SSH 派发后 B 无进程 | 看 `remote_train.log`；确认 conda 名与页面一致 |

---

## 训练 API 速查

```bash
# 配置列表
curl -H "Authorization: Token <token>" http://localhost:8080/api/train/configs

# 可选预训练权重
curl -H "Authorization: Token <token>" \
  "http://localhost:8080/api/train/weights?task_type=obb&version=8"

# 启动训练
curl -X POST -H "Authorization: Token <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "config_name": "tree-obb",
    "project_ids": [1, 2],
    "yolo_version": "8",
    "yolo_scale": "x",
    "train_params": {"epochs": 1000, "batch": 16}
  }' \
  http://localhost:8080/api/train

# 任务列表 / 详情
curl -H "Authorization: Token <token>" http://localhost:8080/api/train/jobs
curl -H "Authorization: Token <token>" http://localhost:8080/api/train/jobs/1
```

---

## 项目结构（训练相关）

```text
label-studio/
├── cv-ultralytics/                 # YOLO 引擎与权重
├── label_studio/training/          # 训练模块
│   ├── api.py                      # 训练 / 配置 / 训练机 API
│   ├── ssh_dispatch.py             # A→B SSH：测通、推包、开训、拉产物
│   ├── remote_runner.py            # B 上训练入口
│   ├── rq_jobs.py                  # RQ Worker 入口
│   ├── transfer.py                 # 打包 / 路径 / 备选回传
│   ├── tasks.py                    # 划分数据集 + 跑 YOLO
│   ├── weights.py / params.py      # 权重与超参
│   ├── models.py / serializers.py
│   └── migrations/                 # 含 0009 conda_env 等
├── web/.../TrainingPage/           # 训练前端
├── docker-compose.yml              # 标注端（可选 --profile gpu）
├── docker-compose.training.yml     # 独立 GPU RQ Worker
├── .env.example
└── pyproject.toml
```

---

## License

基于原版 [Apache 2.0 LICENSE](/LICENSE) © [Heartex](https://www.heartex.com/)。