# label-studio-ml-backend **Repository Path**: get-resource/label-studio-ml-backend ## Basic Information - **Project Name**: label-studio-ml-backend - **Description**: No description available - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-08-15 - **Last Updated**: 2025-08-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 什么是Label Studio机器学习后端？ Label Studio机器学习后端是一个SDK，可帮助你封装机器学习代码并将其转换为Web服务器。该Web服务器可以连接到运行中的[Label Studio](https://labelstud.io/)实例，以实现标注任务的自动化。 如果你只需要将静态的预标注数据加载到Label Studio中，运行机器学习后端可能有些多余。这种情况下，你可以直接[导入预标注数据](https://labelstud.io/guide/predictions.html)。 # 快速开始 要开始使用这些模型，请使用[docker-compose](https://docs.docker.com/compose/install/)运行机器学习后端服务器。 使用以下命令在`http://localhost:9090`启动机器学习后端服务： ```bash git clone https://github.com/HumanSignal/label-studio-ml-backend.git cd label-studio-ml-backend/label_studio_ml/examples/{MODEL_NAME} docker-compose up ``` 将`{MODEL_NAME}`替换为你要使用的模型名称（见下文）。 ## 允许机器学习后端访问Label Studio数据 在大多数情况下，你需要设置`LABEL_STUDIO_URL`和`LABEL_STUDIO_API_KEY`环境变量，以允许机器学习后端访问Label Studio中的媒体数据。[在文档中了解更多](https://labelstud.io/guide/ml#Allow-the-ML-backend-to-access-Label-Studio-data)。 **警告：** 目前，机器学习后端仅支持 Legacy Tokens（传统令牌），不支持 Personal Tokens（个人令牌）。如果使用个人令牌，会出现“未授权错误”。 # 模型 本仓库支持以下模型。其中一些无需额外设置即可使用，另一些则需要配置额外参数。 查看“必填参数”列，了解是否需要设置额外参数。 - **预标注**列表示模型是否可用于Label Studio中的预标注：打开标注页面或对一批数据运行预测后，可查看预标注数据。 - **交互模式**列表示模型是否可用于Label Studio中的交互式标注：在标注页面执行操作时可查看交互式预测。 - **训练**列表示模型是否可用于Label Studio中的训练：基于提交的标注更新模型状态。 | 模型名称 | 描述 | 预标注 | 交互模式 | 训练 | 必填参数 | 支持任意标签还是固定标签？ | |--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|----------------|------------------|----------|----------------------|----------------------------------------------------------------------------| | [bert_classifier](/label_studio_ml/examples/bert_classifier) | 基于[Huggingface](https://huggingface.co/transformers/v3.0.2/model_doc/auto.html#automodelforsequenceclassification)的文本分类 | ✅ | ❌ | ✅ | 无 | 任意| | [easyocr](/label_studio_ml/examples/easyocr) | 自动化OCR。基于[EasyOCR](https://github.com/JaidedAI/EasyOCR) | ✅ | ❌ | ❌ | 无 | 固定（字符） | | [flair](/label_studio_ml/examples/flair) | 基于[flair](https://flairnlp.github.io/)的命名实体识别（NER） | ✅ | ❌ | ❌ | 无 | 任意| | [gliner](/label_studio_ml/examples/gliner) | 基于[GLiNER](https://huggingface.co/spaces/tomaarsen/gliner_medium-v2.1)的命名实体识别（NER） | ❌ | ✅ | ✅ | 无 | 任意| | [grounding_dino](/label_studio_ml/examples/grounding_dino) | 支持提示词的目标检测。[详情](https://github.com/IDEA-Research/GroundingDINO) | ❌ | ✅ | ❌ | 无 | 任意 | | [grounding_sam](/label_studio_ml/examples/grounding_sam) | 基于[提示词](https://github.com/IDEA-Research/GroundingDINO)和[SAM 2](https://github.com/facebookresearch/segment-anything-2)的目标检测 | ❌ | ✅ | ❌ | 无 | 任意 | | [huggingface_llm](/label_studio_ml/examples/huggingface_llm) | 基于[Hugging Face](https://huggingface.co/tasks/text-generation)的大语言模型（LLM）推理 | ✅ | ❌ | ❌ | 无 | 任意 | | [huggingface_ner](/label_studio_ml/examples/huggingface_ner) | 基于[Hugging Face](https://huggingface.co/docs/transformers/en/tasks/token_classification)的命名实体识别（NER） | ✅ | ❌ | ✅ | 无 | 任意 | | [interactive_substring_matching](/label_studio_ml/examples/interactive_substring_matching) | 简单关键词搜索 | ❌ | ✅ | ❌ | 无 | 任意 | | [langchain_search_agent](/label_studio_ml/examples/langchain_search_agent) | 基于谷歌搜索和[Langchain](https://langchain.com/)的RAG流水线 | ✅ | ✅ | ✅ | OPENAI_API_KEY、GOOGLE_CSE_ID、GOOGLE_API_KEY | 任意 | | [llm_interactive](/label_studio_ml/examples/llm_interactive) | 基于[OpenAI](https://platform.openai.com/)、Azure大语言模型的提示词工程。 | ✅ | ✅ | ✅ | OPENAI_API_KEY | 任意 | | [mmdetection](/label_studio_ml/examples/mmdetection-3) | 基于[OpenMMLab](https://github.com/open-mmlab/mmdetection)的目标检测 | ✅ | ❌ | ❌ | 无 | 任意 | | [nemo_asr](/label_studio_ml/examples/nemo_asr) | 基于[NVIDIA NeMo](https://github.com/NVIDIA/NeMo)的语音自动语音识别（ASR） | ✅ | ❌ | ❌ | 无 | 固定（词汇和字符） | | [segment_anything_2_image](/label_studio_ml/examples/segment_anything_2_image) | 基于[SAM 2](https://github.com/facebookresearch/segment-anything-2)的图像分割 | ❌ | ✅ | ❌ | 无| 任意| | [segment_anything_model](/label_studio_ml/examples/segment_anything_model) | 基于[Meta](https://segment-anything.com/)的图像分割 | ❌ | ✅ | ❌ | 无 | 任意 | | [sklearn_text_classifier](/label_studio_ml/examples/sklearn_text_classifier) | 基于[scikit-learn](https://scikit-learn.org/stable/)的文本分类 | ✅ | ❌ | ✅ | 无 | 任意 | | [spacy](/label_studio_ml/examples/spacy) | 基于[SpaCy](https://spacy.io/)的命名实体识别（NER） | ✅ | ❌ | ❌ | 无 | 固定 [(参见文档)](https://spacy.io/usage/linguistic-features) | | [tesseract](/label_studio_ml/examples/tesseract) | 交互式OCR。[详情](https://github.com/tesseract-ocr/tesseract) | ❌ | ✅ | ❌ | 无 | 固定（字符） | | [timeseries_segmenter](/label_studio_ml/examples/timeseries_segmenter) | 基于小型LSTM网络的时间序列分割 | ✅ | ✅ | ✅ | 无 | 固定 | | [watsonX](/label_studio_ml/exampels/watsonx)| 基于[WatsonX](https://www.ibm.com/products/watsonx-ai)的大语言模型推理，支持与[WatsonX.data](watsonx.data)集成| ✅ | ✅| ❌ | 无| 任意| | [yolo](/label_studio_ml/examples/yolo) | 支持所有YOLO任务：[YOLO](https://docs.ultralytics.com/tasks/) | ✅ | ❌ | ❌ | 无 | 任意 | # （高级用法）开发你的模型 要开始开发自己的机器学习后端，请按照以下步骤操作。 ## 1. 安装 从仓库下载并安装`label-studio-ml`： ```bash git clone https://github.com/HumanSignal/label-studio-ml-backend.git cd label-studio-ml-backend/ pip install -e . ``` ## 2. 创建空的机器学习后端： ```bash label-studio-ml create my_ml_backend ``` 你可以进入`my_ml_backend`目录并修改代码，实现自己的推理逻辑。 目录结构如下： ``` my_ml_backend/ ├── Dockerfile ├── docker-compose.yml ├── model.py ├── _wsgi.py ├── README.md └── requirements.txt ``` `Dockerfile`和`docker-compose.yml`用于通过Docker运行机器学习后端。 `model.py`是主要文件，你可以在其中实现自己的训练和推理逻辑。 `_wsgi.py`是辅助文件，用于通过Docker运行机器学习后端（无需修改）。 `README.md`是包含运行机器学习后端说明的文档。 `requirements.txt`是Python依赖文件。 ## 3. 实现预测逻辑 在你的模型目录中，找到`model.py`文件（例如`my_ml_backend/model.py`）。 `model.py`文件包含一个继承自`LabelStudioMLBase`的类声明。该类为Label Studio与机器学习后端通信的API方法提供了封装。你可以重写这些方法以实现自己的逻辑： ```python def predict(self, tasks, context, **kwargs): """为任务生成预测结果。""" return predictions ``` `predict`方法用于为任务生成预测，参数说明如下： - `tasks`：[JSON格式的Label Studio任务](https://labelstud.io/guide/task_format.html) - `context`：[JSON格式的Label Studio上下文](https://labelstud.io/guide/ml_create#Support-interactive-pre-annotations-in-your-ML-backend)——用于交互式标注场景 - `predictions`：[JSON格式的预测数组](https://labelstud.io/guide/export.html#Raw-JSON-format-of-completed-tasks) 实现`predict`方法后，你可以在Label Studio中看到来自连接的机器学习后端的预测结果。 ## 4. 实现训练逻辑（可选） 你也可以实现`fit`方法来训练模型。`fit`方法通常用于在标注数据上训练模型，不过也可用于任何需要数据持久化的操作（例如，将标注数据存储在数据库中、保存模型权重、记录大语言模型提示词历史等）。 默认情况下，`fit`方法会在Label Studio中的任何数据操作（如创建新任务或更新标注）时被调用。你可以在项目设置的**Webhooks**下修改此行为。 要实现`fit`方法，需要在`model.py`文件中重写`fit`方法： ```python def fit(self, event, data, **kwargs): """在标注数据上训练模型。""" old_model = self.get('old_model') # 编写更新模型的逻辑 self.set('new_model', new_model) ``` 参数说明： - `event`：事件类型，可能是`'ANNOTATION_CREATED'`、`'ANNOTATION_UPDATED'`等。 - `data`：从事件接收的 payload（更多信息参见[Webhook事件参考](https://labelstud.io/guide/webhook_reference.html)） 此外，有两个辅助方法可用于在机器学习后端中存储和检索数据： - `self.set(key, value)`——在机器学习后端中存储数据 - `self.get(key)`——从机器学习后端中检索数据 这两个方法可在机器学习后端的其他代码中使用，例如在`predict`方法中获取新的模型权重。 ### 其他方法和参数 `LabelStudioMLBase`类中还有其他可用的方法和参数： - `self.label_config`——返回[Label Studio标注配置](https://labelstud.io/guide/setup.html)（XML字符串格式）。 - `self.parsed_label_config`——返回[Label Studio标注配置](https://labelstud.io/guide/setup.html)（JSON格式）。 - `self.model_version`——返回当前模型版本。 - `self.get_local_path(url, task_id)`——此辅助函数用于下载并缓存通常存储在`task['data']`中的URL，并返回其本地路径。该URL可以是：LS上传的文件、LS本地存储、LS云存储或任何其他http(s) URL。 ### 不使用Docker运行 要在不使用Docker的情况下运行（例如，出于调试目的），可以使用以下命令： ```bash label-studio-ml start my_ml_backend ``` ### 测试你的机器学习后端 修改`my_ml_backend/test_api.py`以确保你的机器学习后端正常工作。 ### 修改端口 要修改端口，请使用`-p`参数： ```bash label-studio-ml start my_ml_backend -p 9091 ``` # 将机器学习后端部署到GCP 开始之前： 1. 安装[gcloud](https://cloud.google.com/sdk/docs/install)。 2. 如果尚未[激活](https://console.cloud.google.com/project/_/billing/enable)，请为你的账户初始化账单。 3. 初始化gcloud，输入以下命令并通过浏览器登录： ```bash gcloud auth login ``` 4. 激活Cloud Build API。 5. 找到你的GCP项目ID。 6. （可选）将`GCP_REGION`与你的默认区域添加到环境变量中。 开始部署： 1. 创建自己的机器学习后端 2. 开始部署到GCP： ```bash label-studio-ml deploy gcp {ml-backend-local-dir} \ --from={model-python-script} \ --gcp-project-id {gcp-project-id} \ --label-studio-host {https://app.heartex.com} \ --label-studio-api-key {YOUR-LABEL-STUDIO-API-KEY} ``` 3. Label Studio部署模型后，你可以在控制台中找到模型端点。 # 故障排除 ## Windows上Docker构建故障排除 在Windows上运行`docker-compose up --build`时，如果你遇到类似以下的错误： ``` exec /app/start.sh : No such file or directory exited with code 1 ``` 此问题可能是由于Windows对文本文件换行符的处理方式导致的，这会影响`start.sh`等脚本。要解决此问题，请按照以下步骤操作： ### 步骤1：调整Git配置 克隆仓库之前，确保你的Git配置为在检出文件时不自动将换行符转换为Windows风格（CRLF）。可以通过将`core.autocrlf`设置为`false`来实现。打开Git Bash或你偏好的终端，执行以下命令： ``` git config --global core.autocrlf false ``` ### 步骤2：重新克隆仓库 如果在调整Git配置之前已经克隆了仓库，需要重新克隆以确保换行符被正确保留： 1. **删除现有的本地仓库**。确保已备份任何更改或正在进行的工作。 2. **重新克隆仓库**。使用标准的Git克隆命令将仓库克隆到本地机器。 ### 步骤3：构建并运行Docker容器 导航到克隆仓库中包含Dockerfile和`docker-compose.yml`的相应目录。然后，执行以下Docker命令： 1. **构建Docker容器**：运行`docker-compose build`，根据`docker-compose.yml`中指定的配置构建Docker容器。 2. **启动Docker容器**：构建过程完成后，使用`docker-compose up`启动容器。 ### 补充说明 - 此解决方案专门解决Windows上因换行符自动转换导致的问题。如果你使用其他操作系统，此解决方案可能不适用。 - 请检查项目的`.gitattributes`文件（如果存在），因为它也会影响Git对文件换行符的处理方式。 按照这些步骤，你应该能够解决Windows上由于换行符转换导致Docker无法识别`start.sh`脚本的问题。 ## Docker镜像中Pip缓存重置故障排除 有时，你可能需要重置pip缓存，以确保安装的是依赖项的最新版本。例如，Label Studio机器学习后端库在requirements.txt中被指定为`label-studio-ml @ git+https://github.com/HumanSignal/label-studio-ml-backend.git`。假设该库已更新，你希望在包含机器学习模型的docker镜像中使用最新版本。 你可以使用以下命令从头开始重建docker镜像： ```bash docker compose build --no-cache ``` ## “网关错误（Bad Gateway）”和“服务不可用（Service Unavailable）”错误故障排除 如果发送多个并发请求，可能会看到这些错误。 请注意，提供的机器学习后端示例是在开发模式下提供的，不支持生产级别的推理服务。 ## 机器学习后端无法进行简单自动标注或无法查看预测结果的故障排除 你必须确保机器学习后端可以访问你的Label Studio数据。如果无法访问，可能会遇到以下问题： * 服务器日志中出现“no such file or directory”错误。 * 在Label Studio中加载任务时无法看到预测结果。 * 你的机器学习后端似乎连接正常，但无法在任务中完成任何自动标注。 要解决此问题，请确保已设置`LABEL_STUDIO_URL`和`LABEL_STUDIO_API_KEY`环境变量。有关更多信息，请参见[允许机器学习后端访问Label Studio数据](https://labelstud.io/guide/ml#Allow-the-ML-backend-to-access-Label-Studio-data)。