Label Studio 主动学习循环搭建实战：基于 ML Backend 与 Webhook 的端到端方案-二趣网

Label Studio 主动学习循环搭建实战：基于 ML Backend 与 Webhook 的端到端方案

【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio

导读

本指南面向使用 Label Studio 构建「标注—训练—预测」闭环的机器学习工程师与数据标注团队。文章以 Label Studio 文档 active_learning.md 为核心骨架，系统讲解主动学习（Active Learning）的原理、在 Label Studio 中搭建自动化主动学习循环的完整步骤，并深入结合仓库源码（如 label_studio/ml/models.py、label_studio/ml/api_connector.py、label_studio/webhooks/models.py）剖析 Webhook 触发训练、预测召回、不确定度采样等底层实现。读完本文，你将掌握：如何把自定义模型接入 Label Studio 作为 ML backend、如何配置 Webhook 驱动fit()训练、如何用预测分数做任务采样，以及社区版（Community Edition）下如何手动模拟主动学习。

注意：本文所描述的「自动化主动学习循环」依赖 Label Studio Enterprise Edition 的任务采样能力；若使用开源社区版，可采用文末的「手动主动学习」批处理方案。

关于主动学习（About Active Learning）

为监督式机器学习模型创建标注训练数据既昂贵又耗时。主动学习是机器学习的一个分支，其核心目标是通过策略性地抽样那些能为问题带来新认知的样本，最小化标注所需的数据总量。

与从无标签数据池中随机抽取样本不同，主动学习算法借助预测分数（prediction scores），优先挑选多样化且信息量大的观测样本交给标注者。其思想是：让标注者的精力集中在模型最不确定的样本上，从而以更少的标注量获得更高的模型收益。

在 Label Studio 的项目设置中，这一理念对应着不确定度采样（Uncertainty Sampling）：当启用了 ML backend 时，Label Studio 会策略性地选出模型预测分数最低（最不确定）的任务优先展示给标注者，详见 project_settings_lse.md 中 Task Ordering Method 的Uncertainty选项说明。

自动化主动学习循环的工作原理

在 Label Studio Enterprise Edition 中，可以搭建如下的自动化主动学习循环：

标注者在 Label Studio 中完成一个标注（Annotation）；
项目配置的Webhook将「标注已创建/已更新」事件发送给 ML backend；
ML backend 的fit()方法被调用，用新标注数据训练/更新模型；
标注者进入下一个任务时，Label Studio 从 ML backend 拉取该任务的最新预测，即调用predict()方法；
模型版本更新后，标注者看到的始终是最新模型版本产生的预测，且任务顺序按预测分数升序（最不确定优先）排列。

这一闭环正是文档 active_learning.md 中流程图所描绘的：Labeling in Label Studio → Webhook event sent → ML Backend fit() → New model version deployed → ML Backend predict() → Task predictions returned → Labeling。

源码侧印证：训练与预测的真实调用链

从仓库源码可以确认上述流程的落点：

训练请求的构造：在 label_studio/ml/api_connector.py 中，MLApi.train(project)会筛选出「至少有一条标注」的任务（annotate(num_annotations=Count('annotations')).filter(num_annotations__gt=0)），将任务与标注序列化为 payload 后 POST 到 ML backend 的/train端点；当功能开关开启时，也可改为向/webhook发送START_TRAINING动作。其连接超时、训练超时等均可用环境变量控制，例如ML_TIMEOUT_TRAIN（默认 30 秒）、ML_TIMEOUT_PREDICT（默认 100 秒，见 api_connector.py）。
预测请求的构造：make_predictions(tasks, project, context)将任务序列化后 POST 到/predict端点（见 api_connector.py），请求体中包含tasks、project、label_config等字段。
预测结果的落库：在 label_studio/ml/models.py 的MLBackend.predict_tasks()中，Label Studio 会先排除「已包含当前模型版本预测」的任务，再批量请求预测，并用PredictionSerializer将结果保存到预测表；同时该方法会通过update_state()同步 ML backend 的连接状态与model_version（见 models.py）。
训练状态机：MLBackend模型使用MLBackendState枚举（CONNECTED/DISCONNECTED/ERROR/TRAINING/PREDICTING）管理后端状态，并存在MLBackendTrainJob记录训练任务（见 models.py、models.py）。

这些源码路径表明：文档描述的「标注提交 → 训练 → 新版本部署 → 预测返回」并非概念示意，而是由 Label Studio 服务端与 ML backend 之间的 HTTP 协议（/setup、/health、/train、/predict、/webhook、/job_status等端点）真实承载的。

搭建自动化主动学习循环的五个步骤

按以下顺序搭建完整的主动学习循环：

将 ML 模型配置为可用于主动学习的 ML backend；
将 ML backend 连接到 Label Studio 项目以获取预测；
（可选）配置 Webhook，将训练事件发送给 ML backend；
设置基于预测分数的任务采样；
开始标注任务。

随着标注的进行，Label Studio 会不断向 ML backend 发送 Webhook 事件并促使其重训；模型重训后，最新模型版本的预测会实时出现在 Label Studio 中。

步骤一：将 ML 模型配置为 ML backend

Label Studio 的 ML backend 本质上是一个 SDK：它把你的机器学习代码包装成一个 Web 服务器，Label Studio 通过 HTTP 与之通信。

使用示例模型（推荐快速上手）

参考 ml.md 中「Set up an example ML backend」一节：从label-studio-ml-backend仓库选择一个示例模型（例如 Segment Anything 的segment_anything_model），在其目录下配置docker-compose.yml后启动：

git clone https://github.com/HumanSignal/label-studio-ml-backend.git cd label-studio-ml-backend/label_studio_ml/examples/segment_anything_model docker-compose up

模型默认运行在http://localhost:9090。可通过 UI 中模型溢出菜单的Send Test Request，或执行以下命令验证：

curl http://localhost:9090 {"model_class":"SamMLBackend","status":"UP"}

注意（localhost 与 Docker 容器）：localhost会回环到本机。若 Label Studio 与 ML backend 都运行在 Docker 容器中，应改用http://host.docker.internal:9090或容器的内部 IP，而不是localhost。

编写自定义 ML backend

参考 ml_create.md：安装 SDK 后创建空后端骨架：

git clone https://github.com/HumanSignal/label-studio-ml-backend.git cd label-studio-ml-backend/ pip install -e . label-studio-ml create my_ml_backend

生成的my_ml_backend/目录结构如下：

my_ml_backend/ ├── Dockerfile ├── .dockerignore ├── docker-compose.yml ├── model.py ├── _wsgi.py ├── README.md ├── requirements-base.txt ├── requirements-test.txt ├── requirements.txt └── test_api.py

其中model.py是核心文件。你的模型类需继承LabelStudioMLBase，并重写两个关键方法：

predict()：对任务做推理，返回预测结果数组。tasks参数是 Label Studio 任务 JSON（格式见 task_format.md），context参数用于交互式预标注场景。
fit()：用标注数据训练模型（可选）。典型用法是读取事件与 payload，更新模型权重并持久化：

def fit(self, event, data, **kwargs): """Train the model on the labeled data.""" old_model = self.get('old_model') # write your logic to update the model self.set('new_model', new_model)

其中event为事件类型（如'ANNOTATION_CREATED'、'ANNOTATION_UPDATED'），data为事件 payload（详见 webhook_reference.md）；self.set(key, value)/self.get(key)用于在 ML backend 侧存取持久化数据（例如在predict()中取出new_model权重）。

关于predict()的返回：从源码看，Label Studio 服务端期望 ML backend 返回形如{"results": [...]}的 dict，其中每个预测项需包含result字段，并可携带score与model_version——这些字段会由 label_studio/ml/models.py 中的预测解析逻辑读取并写入预测记录。score正是主动学习任务采样所依赖的预测分数。

此外，LabelStudioMLBase还提供self.label_interface（标注界面对象）与self.model_version（当前模型版本）等属性。启动服务器时可用-p与--host修改端口与主机（例如label-studio-ml start my_ml_backend -p 9091 --host 0.0.0.0），--debug可输出更详细的训练日志。

步骤二：将 ML backend 连接到 Label Studio

创建项目后，进入项目设置的Model页面，点击Connect Model并填写：

字段	说明
Name	为模型命名。
Backend URL	模型服务地址。按上文步骤则为`http://localhost:9090`；若 Label Studio 运行于 Docker，参考上文关于`localhost`的说明。
Select authentication method	若访问模型需要账号密码，选择Basic Authentication并填写。
Extra params	传递给模型的附加参数。
Interactive preannotations	启用后，标注者交互（如绘制矩形、选中文本、向 LLM 提问）时，ML backend 会实时返回预测建议。

连接后务必确保「Start model training on annotation submission」处于启用状态——该选项会在每次标注提交或更新后向 ML backend 发送训练请求，这是自动化主动学习循环得以运转的关键开关。

在源码层面，ML backend 连接信息对应 label_studio/ml/models.py 中的MLBackend模型：它持久化了url、title、auth_method、basic_auth_user/basic_auth_pass、extra_params、model_version、auto_update、timeout（默认 100 秒）等字段；auto_update=True时 Label Studio 会自动从后端拉取最新model_version。也可以通过 API 添加 ML backend，需要项目 ID 与后端 URL。

让 ML backend 能访问 Label Studio 的数据

当任务数据来自导入上传、本地存储或云存储（S3/GCS/Azure）时，ML backend 需要读取这些资源文件。此时应使用label_studio_tools提供的get_local_path()：

from label_studio_tools.core.utils.io import get_local_path class MLBackend(LabelStudioMLBase) def predict(tasks): task = tasks[0] local_path = get_local_path(task['data']['image'], task_id=task['id']) with open(local_path, 'r') as f: f.read()

get_local_path()会把 URI 解析为 URL，再下载并缓存文件。使用前必须在 ML backend 侧配置两个环境变量：

environment: - LABEL_STUDIO_URL=http://192.168.42.42:8080/ # 替换为你的真实 IP，勿用 localhost - LABEL_STUDIO_API_KEY=<your-label-studio-api-key>

注意：LABEL_STUDIO_URL必须以http://或https://开头，且对 ML backend 实例可访问；若 ML backend 运行在 Docker 中，不能使用localhost或0.0.0.0。API Key 可在 Label Studio 的用户账户页面（Access Token）获取，Enterprise 版中该用户还须对目标项目有访问权限。

步骤三：配置 Webhook 发送训练事件（可选）

默认情况下，Label Studio 会在每次标注创建或更新时自动通知 ML backend，以便其触发训练——这一默认行为在源码中有直接体现：label_studio/ml/models.py 的create_ml_webhook信号处理器会在 ML backend 创建时，自动向其{backend_url}/webhook注册一个 webhook（send_payload=True, send_for_all_actions=True）。

如果你希望对事件与 payload 做更精细的控制（例如根据事件类型驱动不同的训练逻辑），可以手动配置：

在 Label Studio UI 中打开用于主动学习的项目；
进入Settings > Webhooks；
点击Add Webhook；
Payload URL填写http://localhost:9090/webhook；
（可选）保留Send payload开启。ML backend 并不强制要求 payload，但你可以在代码中利用它获取项目相关信息，例如项目 ID（用于取回数据）、根据项目设置定义训练超参数、读取项目状态等；
关闭「Send for all actions」，仅启用Annotation created与Annotation updated；
点击Add Webhook。

关于 Webhook 事件 payload 的完整字段，可查看标注 Webhook 的 payload 详情。在仓库中，这些事件常量定义于 label_studio/webhooks/models.py：ANNOTATION_CREATED、ANNOTATIONS_CREATED、ANNOTATION_UPDATED、ANNOTATIONS_DELETED等，且ANNOTATION_CREATED/ANNOTATION_UPDATED均会携带嵌套的annotation与task序列化数据（见 models.py），可作为训练逻辑的数据来源。

需要说明的是：默认 webhook 的 payload 通常不包含标注本身。若训练逻辑需要完整标注，可修改 Label Studio 发送的 webhook 事件以携带完整 payload，或通过 Label Studio API / SDK 按任务 ID 拉取标注，或从已配置的目标存储中读取（参见 ml_create.md 中「Trigger training with webhooks」一节）。

步骤四：设置基于预测分数的任务采样

为了让模型训练效率与效果最大化，应让标注者优先标注模型最不自信（最不确定）的任务。做法是启用不确定度采样（Uncertainty Sampling）：在项目设置中，将Task Ordering Method设为Uncertainty（仅在使用 Automatic 任务分配时可用）。启用后，Label Studio 会策略性地选出预测分数最低的任务优先分发给标注者，目标是在最小化标注量的同时最大化模型性能（参见 project_settings_lse.md）。

这一机制与预测记录的score字段紧密相关：ML backend 在predict()返回结果中给出的score会被 Label Studio 持久化，并成为排序依据。因此，若你的模型尚未输出有区分度的score，建议先在predict()中自定义预测分数（见下文「自定义主动学习循环」）。

步骤五：开始标注

在项目数据管理页（Data Manager）选择Label All Tasks开始标注。

当模型重训并更新新版本后，标注者看到的任务始终是预测分数最低的那些（即模型置信度最低的），且任务对应的预测来自最新模型版本。

自定义主动学习循环

如果希望调整主动学习循环的行为，可以手动修改以下环节：

自定义预测分数：通过修改predict()推理调用，产出更适合业务语义的预测分数。可参考 ml_create.md 中「Make predictions with your ML backend」一节的示例代码。
切换展示给标注者的模型版本：在机器学习设置中更新用于展示预测的模型版本，参见 ml.md 中「Choose which predictions to display to annotators」一节（项目设置Annotation > Live Predictions中通过下拉菜单选择）。
模型重训后删除旧预测：可在数据管理页选中任务后选择Delete predictions，或用 API 删除指定项目的全部预测：

curl -H 'Authorization: Token <user-token-from-account-page>' -X POST \ "<host>/api/dm/actions?id=delete_tasks_predictions&project=<id>"

为全部任务批量获取预测：若数据量大，HTTP 请求可能因超时中断。建议对每个任务调用 Label Studio API 的 predictions 端点（POST），或参考 ml.md 中「Get predictions from a model」一节：可在数据管理页选中任务后执行Actions > Retrieve predictions；也可直接对 ML backend 的/predict端点 POST 任务列表：

{ "tasks": [ {"data": {"text":"some text"}} ] }

手动触发训练：除标注提交自动触发外，还可以在项目设置的 Model 页面通过Start Training手动发起训练（适合按批控制训练时机），或调用 API：

curl -X POST http://localhost:8080/api/ml/{id}/train

社区版的手动主动学习（Manual Active Learning）

如果你使用 Label Studio 开源社区版，标注者无法体验实时的主动学习循环。可以通过以下方式模拟主动学习体验：

手动从模型获取预测；
在数据管理页按预测分数对任务排序（该功能要求任务携带预测分数——无论是导入的预标注数据，还是 ML backend 输出的预测）；
标注时选择Label Tasks As Displayed，按排序后的顺序标注。

注意：这个手动循环不会像 Enterprise 版那样，随着每次新标注训练并产生新预测而自动更新标注者的任务顺序。因此它实现的是一种批量式主动学习（batched active learning）：先标注一段时间 → 暂停 → 训练模型 → 拉取新预测 → 再按新顺序继续标注。

常见问题与排查要点

ML backend 无法连接：确认 Backend URL 可访问、/health返回正常；检查 Label Studio 与 ML backend 是否处于同一网络（Docker 场景使用host.docker.internal或内网 IP）。
预测不出现：确认项目设置中已启用「Use predictions to prelabel tasks」，并在下拉菜单中选中了正确的模型；确认 ML backend 的predict()返回了包含result字段（必要时含score）的{"results": [...]}结构。
训练不触发：检查「Start model training on annotation submission」是否开启；若手动配置了 Webhook，确认仅勾选了Annotation created与Annotation updated，且 Payload URL 指向{backend_url}/webhook。
任务顺序不符合预期：确认任务分配方式为 Automatic，且 Task Ordering Method 设为Uncertainty；确认预测记录中确实存在有区分度的score。
需要调试日志：以--debug启动 ML backend 可输出更详细的训练日志；Label Studio 侧训练日志输出在 stdout 与控制台。

小结

主动学习的价值在于用更少的标注换取更好的模型。Label Studio Enterprise 通过「Webhook 事件驱动fit()训练 + 预测分数驱动任务采样 + 最新模型版本预测实时返回」三者的组合，将这一思想落地为可自动运转的循环；社区版用户则可通过「批量拉取预测 → 按分数排序 → 顺序标注」的方式近似实现。理解 label_studio/ml/models.py、label_studio/ml/api_connector.py 与 label_studio/webhooks/models.py 中的底层实现，有助于你在自定义模型、调优采样策略或排查故障时快速定位问题。

【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析