Label Studio 交互式子串匹配 ML 后端：为 NER 任务实现关键词自动标注的完整实战指南

Label Studio 交互式子串匹配 ML 后端：为 NER 任务实现关键词自动标注的完整实战指南

【免费下载链接】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 开源仓库中的interactive_substring_matching教程文档，讲解如何部署一个专为命名实体识别（NER）任务设计的交互式 ML 后端：标注员选中文本中的某个关键词，后端自动在整段文本中匹配所有相同关键词并返回为实体标注建议。读完本文，你将掌握该 ML 后端的推荐标注配置、Docker 与源码两种部署方式、容器化运行参数、交互式预标注（Interactive Pre-annotations）的底层调用原理，以及如何在 Label Studio 项目中连接并启用这一能力。

一、该 ML 后端解决什么问题

在 NER 标注场景中，文本中同一实体（例如人名、组织名）往往反复出现。逐一手动标注重复实体既费时又容易遗漏。interactive_substring_matching这一 ML 后端正是为此设计：它的核心机制是——选择一个关键词，然后在提供的文本中自动匹配所有相同的关键词，从而把重复性的标注工作交给模型后端完成，标注员只需点击确认即可。

从 ML 后端模型列表 中的能力矩阵可以确认它的定位：

也就是说，它不是用于批量跑预测的模型，而是完全面向交互式标注场景：标注员在界面上做出动作（如高亮文本），ML 后端实时接收这个输入并返回预测。它不依赖任何外部模型权重或 API Key，开箱即用，非常适合用来理解 Label Studio 交互式 ML 后端的完整工作链路。

二、工作原理：交互式预测的完整链路

要理解这个 ML 后端，需要先了解 Label Studio 中 ML 后端（Machine Learning backend）的一般工作方式。根据 ML 集成指南 的说明，连接模型后每次标注的流程为：

1. 用户打开任务；
2. Label Studio 将请求发送到 ML 后端；
3. ML 后端返回预测结果；
4. 预测被加载进 Label Studio 标注界面展示给标注员。

对于交互式场景（即启用Interactive preannotations选项后），链路变成了：标注员在界面上高亮一段文本 → 前端把该动作连同任务数据发送到 ML 后端的/predict接口 → 后端解析标注动作并返回预测 → 界面即时展示自动匹配到的所有相同子串。

从源码视角看，predict()方法的签名会接收到两类关键数据（详见 编写自己的 ML 后端）：

• tasks参数：被预标注的任务数据，例如{"data": {"text": "..."}}；
• context参数：标注动作的上下文，包含以下属性：
  • annotation_id：标注（annotation）的 ID；
  • draft_id：草稿标注的 ID；
  • user_id：当前用户 ID；
  • result：当前标注结果，其中带有一个用户可修改的is_positive标志（例如在界面中按住Alt键切换）。

正是context.result中的高亮片段，构成了interactive_substring_matching后端“关键词匹配”的输入来源。这也是理解该示例后端一切行为的钥匙：它的预测逻辑本质上是接收一段高亮文本，再对任务文本执行子串查找，最后以 NER 预测结果格式返回所有命中位置。

三、开始之前：环境准备

部署该 ML 后端前，需要先准备好两件事：

1. 安装 Label Studio ML backend（SDK）：ML 后端本质上是一个将你的机器学习代码包装为 Web 服务器的 SDK，只有安装后才能把模型代码跑成可被 Label Studio 连接的 HTTP 服务。
2. 准备interactive_substring_matching示例代码：本教程基于 ML backend 仓库中的同名示例目录。

同时，一个可用的 Label Studio 实例也是必需的。如果你打算后续让 ML 后端访问 Label Studio 中的上传文件、本地存储或云存储数据，还需要为后端配置LABEL_STUDIO_URL和LABEL_STUDIO_API_KEY两个环境变量（具体见下文“连接模型与数据访问”一节）。

四、推荐的标注配置（Labeling Config）

该 ML 后端与 Label Studio 自带的默认 NER 模板完全兼容。你可以在创建/编辑项目时，通过选择预置模板Natural Language Processing > Named Entity Recognition直接获得该配置，也可以手动粘贴下面的配置示例：

<View> <Labels name="label" toName="text"> <Label value="ORG" background="orange" /> <Label value="PER" background="lightgreen" /> <Label value="LOC" background="lightblue" /> <Label value="MISC" background="lightgray" /> </Labels> <Text name="text" value="$text" /> </View>

配置要点说明：

• <Labels>定义了四类实体：ORG（组织）、PER（人名）、LOC（地点）、MISC（其他杂项），并为每类指定了不同的background颜色，便于标注员区分；
• <Text name="text" value="$text" />声明了文本数据源，字段名text对应任务数据中的data.text；
• 注意配置中没有为 Labels 标签设置smart或smartOnly属性。如需仅使用自动标注建议、完全禁止手工标注，可在<Labels>上追加smartOnly="true"；若想同时保留手动标注和自动建议，可追加smart="true"（详见 ML 集成指南中的智能工具说明）。

五、方式一：使用 Docker 运行（推荐）

这是官方推荐的部署方式，因为示例目录内置了完整的docker-compose.yml，无需手动安装 Python 依赖。

第 1 步：启动 ML 后端

进入interactive_substring_matching示例目录后执行：

docker-compose up

启动成功后，后端服务默认监听在http://localhost:9090。

第 2 步：验证后端是否存活

$ curl http://localhost:9090/ {"status":"UP"}

返回{"status":"UP"}即代表服务运行正常，可以开始连接 Label Studio。

第 3 步：在 Label Studio 中连接模型

创建项目后，进入项目设置（Project Settings）中的Model页面，点击Connect Model，填写以下字段（字段说明来自 ML 集成指南）：

⚠️ 注意：如果你把 Label Studio 也运行在 Docker 容器中，localhost在容器内指向的是容器自身而不是宿主机，此时应将 Backend URL 改为http://host.docker.internal:9090或宿主机内网 IP，否则无法连通。

启用Interactive preannotations后，回到标注界面，当你高亮选中文本中的某个实体片段时，后端会立即返回所有相同子串的匹配建议，标注员只需确认或微调即可完成标注。

六、方式二：从源码构建镜像（进阶）

如果你想修改示例代码后再构建运行，可以克隆 ML backend 仓库后，在interactive_substring_matching示例目录下执行：

docker-compose build

该命令会根据示例目录中的 Dockerfile 重新构建镜像，构建完成后同样通过docker-compose up启动。这种方式适合需要把自定义逻辑打进镜像、或需要固定镜像版本的生产化部署场景。

七、方式三：不使用 Docker 运行（进阶）

如果环境中没有 Docker，也可以直接用 Python 虚拟环境运行：

python -m venv ml-backend source ml-backend/bin/activate pip install -r requirements.txt

依赖安装完成后，通过 ML backend CLI 启动服务：

label-studio-ml start ./interactive_substring_matching

label-studio-ml start是 ML backend SDK 提供的启动命令，后面的路径指向示例目录（即包含_wsgi.py与model.py的目录）。服务同样默认运行在http://localhost:9090。

八、运行配置参数

所有运行参数都可在启动容器前于docker-compose.yml中设置。官方文档给出的通用参数如下：

在docker-compose.yml的environment段中为服务设置这些变量即可生效。需要说明的是：这些参数是 ML backend 服务器层的通用配置（影响服务的认证、日志与并发能力），与本示例后端的匹配逻辑本身无关——该示例没有任何必填的业务参数。

如果设置了 Basic Auth，记得在 Label Studio 连接模型时选择Basic Authentication并填入与BASIC_AUTH_USER/BASIC_AUTH_PASS一致的用户名密码。

九、自定义扩展

该 ML 后端本身就是“简单关键词搜索”这一逻辑的最小实现，天然适合作为自定义 NER 交互式后端的起点。你可以在./interactive_substring_matching目录内添加自己的模型与逻辑，官方明确支持这种就地扩展方式，典型做法包括：

• 修改predict()方法中的匹配逻辑：从简单子串匹配升级为正则匹配、大小写不敏感匹配、基于词典的实体识别，或接入本地/远程 NER 模型；
• 复用context参数中返回的高亮片段与is_positive标志，实现“选中即纠正”的交互（例如用户通过Alt键标记负例，后端据此调整后续匹配）；
• 返回结果的格式必须遵循 Label Studio 预测结果格式，即每个预测包含from_name、to_name、type（如labels）、value（含start/end/text/labels）等字段，Label Studio 才能正确渲染为实体标签；
• 如需基于标注数据更新后端状态，可参考 ml_create.md 中的fit方法与self.set/self.get数据存取机制，但要注意本示例本身不提供训练能力。

十、连接模型与数据访问的注意事项

在正式使用前，还有两个直接影响体验的细节需要确认：

1. 让 ML 后端能访问 Label Studio 数据

对于需要读取上传文件、本地存储或云存储（S3/GCS/Azure）数据的场景，ML 后端会通过label_studio_tools包中的get_local_path(url, task_id)函数把 URI 解析为 URL 并下载缓存到本地（该包随label-studio-ml-backend预装，详见 ML 集成指南）。此时必须在后端的environment中配置：

environment: - LABEL_STUDIO_URL=http://192.168.42.42:8080/ # 替换为你的实际 IP，容器内不可用 localhost - LABEL_STUDIO_API_KEY=<your-label-studio-api-key>

注意事项：

• LABEL_STUDIO_URL必须能被 ML 后端实例访问；
• 若 ML 后端运行在 Docker 中，LABEL_STUDIO_URL不能使用localhost或0.0.0.0，应使用完整 IP（可用ifconfig/ipconfig查询）；
• LABEL_STUDIO_URL必须以http://或https://开头；
• API Key 可在 Label Studio 用户账户页面（Access token）获取。

2. 本示例的输入输出均为纯文本

interactive_substring_matching只处理任务数据中的data.text字段，不涉及文件下载，因此对纯文本 NER 任务而言，上述存储配置并非必需——但如果你想在此基础上扩展为处理文档、PDF 等资源型任务，则必须按上述方式配置环境变量。

结语

interactive_substring_matching是理解 Label Studio 交互式 ML 后端机制的最佳入门示例：它没有外部模型依赖、无需必填参数，却能完整演示“标注动作 → 实时预测 → 界面反馈”这条交互式预标注链路。掌握它的部署方式（Docker / 源码 / 无 Docker）与运行参数后，你完全可以在此基础上替换匹配逻辑或接入真正的 NER 模型，将其升级为满足自身业务需求的交互式标注后端。更进一步地，可参阅 ML 集成指南 了解其他示例模型（如 spacy、flair、huggingface_ner 等 NER 后端）以及预测的批量获取、删除与展示策略，从而搭建完整的 ML 辅助标注流水线。

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