feat(ml-backend): Start Training 按钮真正触发重训，启动/重训脚本进 scripts/

原先点 Label Studio 的 Start Training 只是把计数加一：START_TRAINING 和普通标注事件
走同一条阈值判断，没配 RETRAIN_COMMAND 时更是静默什么都不做。实际使用中用户点了按钮、
以为在训练，其实权重一直没变。

- Start Training 无条件触发重训；攒够 RETRAIN_AFTER 条新标注也自动触发。
- 只数 ANNOTATION_CREATED：UPDATED / DELETED 是对已有标注的修改，不该把阈值顶到。
- 已有重训在跑时重复点击被忽略，不叠加启动。
- 没配 RETRAIN_COMMAND 时打警告说明不会真的训练，并在返回值里说清楚。
- 子进程输出重定向到 RETRAIN_LOG（默认 /tmp/retrain.log），训练进度有地方看。

scripts/start_ml_backend.sh、scripts/retrain_from_label_studio.sh 放进仓库，
可从工作区直接启动。重训末尾把 runs/detect/current.pt 软链接指向新权重，
启动脚本默认读它，换模型不必改脚本。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

ml_backend/README.md

@@ -13,23 +13,26 @@ jinja2 3.1。装进主环境会直接弄坏 Label Studio。它本来就是个独
 
 ```bash
 uv venv .venv-ml --python 3.12
+# --no-deps 装本体：它把 label-studio-sdk pin 到了 GitHub 某个提交，
+# 那个仓库大、容易传输中断（服务器上实测失败过），依赖全部走 PyPI 更稳
+VIRTUAL_ENV=.venv-ml uv pip install --no-deps \
+    "label-studio-ml @ git+https://github.com/HumanSignal/label-studio-ml-backend.git"
 VIRTUAL_ENV=.venv-ml uv pip install \
-    "label-studio-ml @ git+https://github.com/HumanSignal/label-studio-ml-backend.git" \
+    "flask>2.3" "colorama~=0.4" "requests~=2.31" "semver~=3.0.2" \
-    ultralytics
+    "label-studio-sdk>=2.1" ultralytics
 ```
 
 ## 启动
 
 ```bash
-cd ml_backend
+bash scripts/start_ml_backend.sh
-YOLO_WEIGHTS=$PWD/../runs/detect/film/weights/best.pt \
-YOLO_DEVICE=cuda \
-LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT=/home/deep/labeling \
-../.venv-ml/bin/python _wsgi.py -p 9090
 ```
 
-**用 `python _wsgi.py` 而不是 `label-studio-ml start .`**：后者用 PATH 上的 python 起子进程，
+脚本会停掉旧进程、带齐环境变量重启，并打印权重、日志位置与网页端要填的 URL。
-在独立环境里会 `ModuleNotFoundError`。
+所有参数都能用环境变量覆盖，例如 `YOLO_WEIGHTS=... bash scripts/start_ml_backend.sh`。
+
+它内部用 `python _wsgi.py` 而不是 `label-studio-ml start .`：后者用 PATH 上的 python
+起子进程，在独立环境里会 `ModuleNotFoundError`。
 
 `LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT` 必须和启动 Label Studio 时的值一致——任务里的图片是
 `/data/local-files/?d=...`，后端要靠它把 URL 还原成磁盘路径。图片若来自上传或云存储，
@@ -66,19 +69,22 @@ Label Studio 里：Settings → **Model** → Connect Model，URL 填 `http://lo
 
 ## 边标边训
 
-Label Studio 每产生一条标注就会 POST `/webhook`，后端在 `fit()` 里累加计数，
+**在 Label Studio 里点 Settings → Model → Start Training**，后端收到 `START_TRAINING`
-达到 `RETRAIN_AFTER` 就起一个**子进程**执行 `RETRAIN_COMMAND` 并立刻返回——
+事件，起一个子进程跑 `scripts/retrain_from_label_studio.sh`，立刻返回——训练要几十分钟，
-训练要几十分钟，绝不能在这个请求里同步做，否则会把 Label Studio 卡住。
+绝不能在这个请求里同步做，否则会把 Label Studio 卡住。
 
-```bash
+触发规则：
-RETRAIN_AFTER=200 \
-RETRAIN_COMMAND="/home/deep/ModelTrainEval/scripts/retrain.sh" \
-../.venv-ml/bin/python _wsgi.py -p 9090
-```
 
-`retrain.sh` 需要自己写，大致是：导出项目 → `build_yolo_dataset.py` 装配 → `detect.py` 训练 →
+- **Start Training 按钮无条件触发**，不看攒了多少条；
-把新权重放到 `YOLO_WEIGHTS` 指向的位置 → 重启本服务（或让它下次启动时加载新权重）。
+- 新增标注累计到 `RETRAIN_AFTER` 也会自动触发（默认 0 = 只手动）。只数
-**目前权重只在进程启动时加载一次**，重训完要重启服务才会生效。
+  `ANNOTATION_CREATED`，`UPDATED` / `DELETED` 是对已有标注的修改，不该把阈值顶到；
+- 已有重训在跑时重复点击会被忽略，不会叠起多个训练。
+
+重训脚本做四件事：导出标注 → `build_yolo_dataset.py` 装配 → `detect.py` 训练 →
+把 `runs/detect/current.pt` 软链接指向新权重并重启本服务。启动脚本默认读这个软链接，
+所以换模型不用改任何脚本。**权重只在进程启动时加载一次**，这也是重训末尾要重启服务的原因。
+
+训练进度看 `$RETRAIN_LOG`（默认 `/tmp/retrain.log`）；Label Studio 网页端不显示训练进度。
 
 ## 已验证的行为
 

ml_backend/model.py

@@ -6,8 +6,9 @@
     YOLO_CONF        置信度阈值，默认 0.25
     YOLO_IMGSZ       推理尺寸，默认 640
     YOLO_DEVICE      cuda / cpu / mps，默认 cuda（不可用时 ultralytics 自己退回）
-    RETRAIN_AFTER    累计多少条新标注后触发重训，默认 0=不触发
+    RETRAIN_AFTER    累计多少条新标注后自动触发重训，默认 0=只靠手动触发
-    RETRAIN_COMMAND  触发时执行的命令；不设则只记数不执行
+    RETRAIN_COMMAND  重训命令；不设则只记数不执行
+    RETRAIN_LOG      重训命令的输出写到哪，默认 /tmp/retrain.log
 """
 
 from __future__ import annotations
@@ -31,6 +32,7 @@ class FilmDefectDetector(LabelStudioMLBase):
 
     _model = None
     _lock = threading.Lock()
+    _retraining = None      # 正在跑的重训子进程
 
     def setup(self) -> None:
         """记录模型版本。
@@ -100,25 +102,53 @@ class FilmDefectDetector(LabelStudioMLBase):
         return ModelResponse(model_version=model_version, predictions=predictions)
 
     def fit(self, event, data, **kwargs):
-        """每产生一条标注就被调用一次，用来攒够数量后触发重训。
+        """Label Studio 的标注事件与 Start Training 按钮都走这里。
 
         这里**不能**直接训练：Label Studio 等着这个请求返回，长任务会把它卡住。
-        所以只累加计数，达到阈值后起一个子进程去跑，立刻返回。
+        所以只决定"要不要训"，真正的训练交给子进程，立刻返回。
         """
         if event not in self.TRAIN_EVENTS:
             return None
         after = int(os.environ.get("RETRAIN_AFTER", 0))
-        command = os.environ.get("RETRAIN_COMMAND", "")
 
-        count = int(self.get("annotations_since_training") or 0) + 1
+        count = int(self.get("annotations_since_training") or 0)
-        self.set("annotations_since_training", str(count))
+        if event == "ANNOTATION_CREATED":
-        logger.info("收到 %s，距上次训练已有 %d 条标注", event, count)
+            # 只数新增：UPDATED / DELETED 是对已有标注的修改，不该让阈值提前到点
+            count += 1
+            self.set("annotations_since_training", str(count))
+        logger.info("收到 %s，距上次训练已新增 %d 条标注", event, count)
 
-        if not after or count < after or not command:
+        # Start Training 是人明确点的，无条件训；攒够阈值则自动训
+        manual = event == "START_TRAINING"
+        if not manual and not (after and count >= after):
             return {"annotations_since_training": count}
+        return self._start_retraining(count, manual)
 
+    def _start_retraining(self, count: int, manual: bool) -> dict:
+        """起一个子进程跑重训命令，立刻返回。"""
+        command = os.environ.get("RETRAIN_COMMAND", "")
+        if not command:
+            logger.warning(
+                "%s，但没有设置 RETRAIN_COMMAND，不会真的训练"
+                "（在 scripts/start_ml_backend.sh 里配置）",
+                "收到 Start Training" if manual else f"已累计 {count} 条标注",
+            )
+            return {"annotations_since_training": count, "retrain_started": False,
+                    "detail": "RETRAIN_COMMAND 未设置"}
+
+        running = FilmDefectDetector._retraining
+        if running is not None and running.poll() is None:
+            # 重复点 Start Training 不该叠加启动多个训练
+            logger.warning("已有重训在跑（pid=%s），这次忽略", running.pid)
+            return {"annotations_since_training": count, "retrain_started": False,
+                    "detail": f"已有重训在跑 pid={running.pid}"}
+
+        log_path = os.environ.get("RETRAIN_LOG", "/tmp/retrain.log")
         self.set("annotations_since_training", "0")
-        logger.info("累计 %d 条标注，触发重训: %s", count, command)
+        logger.info("触发重训: %s（输出见 %s）", command, log_path)
-        # 不等它结束：训练要几十分钟，这个请求必须立刻返回
+        with open(log_path, "a", encoding="utf-8") as log:  # noqa: PTH123
-        subprocess.Popen(shlex.split(command))  # noqa: S603
+            FilmDefectDetector._retraining = subprocess.Popen(  # noqa: S603
-        return {"annotations_since_training": 0, "retrain_started": True}
+                shlex.split(command), stdout=log, stderr=subprocess.STDOUT, stdin=subprocess.DEVNULL,
+            )
+        return {"annotations_since_training": 0, "retrain_started": True,
+                "pid": FilmDefectDetector._retraining.pid, "log": log_path}

scripts/retrain_from_label_studio.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# 从 Label Studio 的最新标注重新训练检测模型，并让 ML backend 用上新权重。
+#
+#   bash scripts/retrain_from_label_studio.sh
+#
+# 也由 ML backend 在点击 Start Training 时自动调用（输出见 $RETRAIN_LOG）。
+# 四步：导出标注 -> 装配数据集 -> 训练 -> 切换权重并重启后端。
+set -euo pipefail
+
+REPO=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+cd "$REPO"
+
+PROJECT="${LS_PROJECT_ID:-39}"
+IMAGES="${LS_IMAGES_DIR:-$REPO/runs/boxes_shap_label_studio/images}"
+STAMP=$(date +%Y%m%d_%H%M)
+EXPORT="${LS_EXPORT_DIR:-/tmp}/ls_export_${STAMP}.zip"
+DATASET="$REPO/data/film_yolo_${STAMP}"
+WORK_DIR="$REPO/runs/detect/film_${STAMP}"
+
+PYTHON="${REPO_PYTHON:-$REPO/.venv/bin/python}"
+# 用跑着 Label Studio 的那个环境导出，确保读的是同一个库
+LS_BIN="${LS_BIN:-/home/deep/.v/label/bin/label-studio}"
+[ -x "$LS_BIN" ] || LS_BIN="$REPO/.venv/bin/label-studio"
+export LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT="${LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT:-/home/deep/labeling}"
+
+# 训练参数的额外覆盖，冒烟测试时用，如 RETRAIN_EXTRA_SET="train.epochs=1 train.fraction=0.02"
+EXTRA_SET="${RETRAIN_EXTRA_SET:-}"
+
+echo "===== [$(date '+%F %T')] 开始重训（项目 $PROJECT）====="
+
+echo "--- 1/4 导出标注 -> $EXPORT"
+"$LS_BIN" export "$PROJECT" YOLO --export-path="$EXPORT"
+
+echo "--- 2/4 装配数据集 -> $DATASET"
+"$PYTHON" scripts/build_yolo_dataset.py \
+    --export "$EXPORT" --images "$IMAGES" --out "$DATASET" --overwrite
+
+echo "--- 3/4 训练 -> $WORK_DIR"
+# shellcheck disable=SC2086  # EXTRA_SET 需要按空格拆成多个参数
+"$PYTHON" detect.py --config configs/detect/film.yaml \
+    --work-dir "$WORK_DIR" \
+    --set data.yaml="$DATASET/data.yaml" $EXTRA_SET
+
+echo "--- 4/4 切换权重并重启 ML backend"
+# 指向最新权重的稳定软链接：启动脚本读它，于是换模型不用改任何脚本
+ln -sfn "$WORK_DIR/weights/best.pt" "$REPO/runs/detect/current.pt"
+bash "$REPO/scripts/start_ml_backend.sh"
+
+echo "===== [$(date '+%F %T')] 重训完成：$WORK_DIR ====="
+echo "指标见 $WORK_DIR/metrics.json，曲线见 $WORK_DIR/results.png"

scripts/start_ml_backend.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# 启动 Label Studio 的 ML backend（预标注 + 触发重训）。
+#
+#   bash scripts/start_ml_backend.sh
+#
+# 会先停掉旧进程再起新的。所有参数都可以用环境变量覆盖，例如换权重：
+#
+#   YOLO_WEIGHTS=/path/to/best.pt bash scripts/start_ml_backend.sh
+#
+# 权重只在进程启动时加载一次，重训完必须重跑本脚本才会生效。
+set -euo pipefail
+
+REPO=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+
+# 默认用 runs/detect/current.pt 这个软链接：重训脚本训完会把它指向最新权重，
+# 这样换模型不用改脚本。链接不存在时退回第一版训练的结果。
+DEFAULT_WEIGHTS="$REPO/runs/detect/current.pt"
+[ -e "$DEFAULT_WEIGHTS" ] || DEFAULT_WEIGHTS="$REPO/runs/detect/film/weights/best.pt"
+
+export YOLO_WEIGHTS="${YOLO_WEIGHTS:-$DEFAULT_WEIGHTS}"
+export YOLO_DEVICE="${YOLO_DEVICE:-cuda}"
+export YOLO_CONF="${YOLO_CONF:-0.25}"
+export YOLO_IMGSZ="${YOLO_IMGSZ:-640}"
+
+# 必须与运行 Label Studio 时的值一致，否则按 ?d=... 还原不出图片路径
+export LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT="${LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT:-/home/deep/labeling}"
+
+# 点 Start Training 无条件触发；攒够 RETRAIN_AFTER 条新标注也会自动触发（0=只手动）
+export RETRAIN_AFTER="${RETRAIN_AFTER:-0}"
+export RETRAIN_COMMAND="${RETRAIN_COMMAND:-$REPO/scripts/retrain_from_label_studio.sh}"
+export RETRAIN_LOG="${RETRAIN_LOG:-/tmp/retrain.log}"
+
+PORT="${LS_ML_PORT:-9090}"
+LOG="${ML_BACKEND_LOG:-/tmp/mlb.log}"
+PYTHON="${ML_BACKEND_PYTHON:-$REPO/.venv-ml/bin/python}"
+
+if [ ! -x "$PYTHON" ]; then
+    echo "找不到 $PYTHON。先建独立环境（见 ml_backend/README.md）：" >&2
+    echo "  uv venv .venv-ml --python 3.12" >&2
+    exit 1
+fi
+if [ ! -e "$YOLO_WEIGHTS" ]; then
+    echo "找不到权重 $YOLO_WEIGHTS" >&2
+    exit 1
+fi
+
+# 模式里不要出现 _wsgi.py 的完整写法：ssh 单行执行时会匹配到命令自身，把会话一起杀掉
+pkill -f "wsgi" 2>/dev/null || true
+sleep 1
+
+cd "$REPO/ml_backend"
+setsid nohup "$PYTHON" ./_wsgi.py -p "$PORT" > "$LOG" 2>&1 < /dev/null &
+echo "ML backend 已启动 pid=$!"
+echo "  权重     : $YOLO_WEIGHTS"
+echo "  重训命令 : $RETRAIN_COMMAND (RETRAIN_AFTER=$RETRAIN_AFTER)"
+echo "  服务日志 : $LOG"
+echo "  重训日志 : $RETRAIN_LOG"
+echo "  网页端 URL: http://localhost:$PORT"

tests/test_ml_backend_convert.py

@@ -69,3 +69,37 @@ def test_score_is_kept_per_box():
         [("blackdot", [0.1, 0.1, 0.2, 0.2], 0.42)], 64, 64, FROM_NAME, TO_NAME, "v1"
     )
     assert prediction["result"][0]["score"] == pytest.approx(0.42)
+
+
+# ---------------- 重训触发的语义 ----------------
+#
+# fit() 本身要 import label_studio_ml，主环境里装不了，所以这里只把它的决策逻辑
+# 单独拎出来验证：什么情况下该训、什么情况下不该。规则见 ml_backend/model.py。
+
+
+def should_retrain(event: str, count: int, after: int) -> bool:
+    """与 FilmDefectDetector.fit 中的判定保持一致。"""
+    if event == "START_TRAINING":
+        return True
+    return bool(after and count >= after)
+
+
+@pytest.mark.parametrize(
+    "event,count,after,expected",
+    [
+        ("START_TRAINING", 0, 0, True),      # 人点的按钮，无条件训
+        ("START_TRAINING", 3, 200, True),    # 没攒够也训
+        ("ANNOTATION_CREATED", 199, 200, False),
+        ("ANNOTATION_CREATED", 200, 200, True),
+        ("ANNOTATION_CREATED", 999, 0, False),   # after=0 表示只手动触发
+    ],
+)
+def test_retrain_trigger_rules(event, count, after, expected):
+    assert should_retrain(event, count, after) is expected
+
+
+def test_only_new_annotations_count_toward_the_threshold():
+    """UPDATED / DELETED 是对已有标注的修改，不该把阈值提前顶到。"""
+    counted = [e for e in ("ANNOTATION_CREATED", "ANNOTATION_UPDATED", "ANNOTATION_DELETED",
+                           "START_TRAINING") if e == "ANNOTATION_CREATED"]
+    assert counted == ["ANNOTATION_CREATED"]