使用 Hugging Face LLM 构建 Label Studio 文本生成 ML 后端：部署、配置与自定义实战

使用 Hugging Face LLM 构建 Label Studio 文本生成 ML 后端部署、配置与自定义实战【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studioLabel Studio 通过ML 后端Machine Learning Backend机制将大语言模型无缝接入数据标注工作流模型以独立的 Web 服务形式运行Label Studio 在标注时自动向该服务请求预测结果并在标注界面中展示。本文以官方示例后端huggingface_llm为蓝本完整讲解如何基于 Hugging Facetransformers预训练模型搭建文本生成后端覆盖 Docker / 源码 / 纯 Python 三种启动方式、全部配置参数、与 Label Studio 的对接认证以及在其基础上扩展自定义模型的方法让你能直接照做跑通提示词 → LLM 生成文本 → 人工标注的完整链路。一、这个 ML 后端能做什么huggingface_llm是一个专为 Label Studio 设计的机器学习后端ML backend核心职责是文本生成text generation。它基于 Hugging Face 的transformers库加载一个预训练的语言模型接收标注任务中的文本输入通常是一段带指令的提示词例如Summarize the following text: ...生成对应的输出文本并作为预测结果prediction回传给 Label Studio 展示给标注人员。在 Label Studio 的 ML 后端体系中该示例属于预标注/自动标注pre-annotation类型的后端模型先行产出结果人工再核对、修改或确认。根据官方示例模型清单见 docs/source/guide/ml.md 中的 Example models 表格huggingface_llm的能力标注为支持预标注Pre-annotation ✅不支持交互式标注与训练且无必填参数——这意味着拿到示例仓库后不做任何额外配置即可启动。其预测链路可以概括为参照 ml.md 中对 ML 后端工作方式的描述标注人员打开一个任务Label Studio 将任务数据发送给 ML 后端ML 后端调用模型推理并返回预测结果预测结果被加载进标注界面展示给标注人员审阅。二、前置条件安装 Label Studio ML backend在动手之前需要先安装Label Studio ML backendSDK 与示例合集所在的仓库。该 SDK 的作用是把机器学习代码包装成一个标准 Web 服务器服务器端使用 uWSGI 与 supervisord 管理进程后台训练任务由 RQ 队列处理参见 docs/source/guide/ml_create.md。安装后即可获得本文所需的huggingface_llm示例目录以及label-studio-ml命令行工具。本教程使用的huggingface_llm示例位于 label-studio-ml-backend 仓库的label_studio_ml/examples/huggingface_llm目录下克隆并安装该仓库即可获得。具体安装方式以该仓库 README 的 quickstart 为准。另外还需要准备一套可用的Label Studio实例用于创建项目并连接模型安装方式见 docs/source/guide/install.mdDocker Compose若采用推荐的后端启动方式。三、Label Studio XML 标注配置huggingface_llm后端与使用TextArea标签的标注配置兼容。下面是一份可直接使用的标注配置示例View Text nameinput_text value$text/ TextArea namegenerated_text toNameinput_text/ /View配置要点说明Text nameinput_text value$text/从任务数据中读取$text字段作为提示词输入。要获得有意义的结果提示词中应包含明确指令例如Summarize the following text: ...这样模型才能理解任务意图并产出对应文本。TextArea namegenerated_text toNameinput_text/toName将文本区域关联到输入文本标注界面中的文本框会展示后端生成的文本。TextArea标签本身支持转录、转述、字幕等场景详见 docs/source/tags/textarea.md此处用于承接模型输出标注人员可以在生成结果基础上直接编辑确认。当你在 Label Studio 中打开任务时后端会基于Text中定义的提示词生成文本并填入文本框人工只需审阅、修正并提交即可完成标注。四、启动 ML 后端三种方式方式一Docker 启动推荐进入huggingface_llm示例目录后使用 Docker Compose 一键启动docker-compose up启动完成后后端默认运行在http://localhost:9090。用 curl 验证服务是否健康$ curl http://localhost:9090/ {status:UP}返回{status:UP}即表示后端已就绪可以连接到 Label Studio 了。方式二从源码构建 Docker 镜像进阶如果你想基于当前源码重新构建镜像例如修改了模型逻辑或依赖后执行docker-compose build构建完成后再通过docker-compose up启动即可。适合需要定制镜像内容或离线交付的场景。方式三不使用 Docker 直接运行进阶若本机环境没有 Docker可以克隆 label-studio-ml-backend 仓库后用 Python 虚拟环境安装依赖python -m venv ml-backend source ml-backend/bin/activate pip install -r requirements.txt然后启动 ML 后端./huggingface_llm指向示例模型目录label-studio-ml start ./huggingface_llmlabel-studio-ml start是 ML backend SDK 提供的标准启动命令它会读取模型目录下的_wsgi.py与模型类定义把推理逻辑包装为可被 Label Studio 调用的 HTTP 服务uWSGI supervisord 架构。五、配置参数详解所有参数都可以在运行容器前通过docker-compose.yml的环境变量environment段进行设置。常用参数如下参数默认值说明MODEL_NAMEfacebook/opt-125m用于文本生成的预训练模型名称Hugging Face 模型 IDMAX_LENGTH50生成文本的最大长度BASIC_AUTH_USER—模型服务器的 Basic Auth 用户名BASIC_AUTH_PASS—模型服务器的 Basic Auth 密码LOG_LEVEL—模型服务器的日志级别WORKERS—模型服务器的工作进程worker数THREADS—模型服务器的线程数将这些参数补充进docker-compose.yml的environment段即可例如services: ml-backend: environment: - MODEL_NAMEfacebook/opt-125m - MAX_LENGTH50 - LOG_LEVELINFO - WORKERS2 - THREADS4源码层面的佐证Basic Auth 参数并非装饰性配置。Label Studio 侧在 label_studio/ml/models.py 中定义了 ML 后端的认证模型MLBackendAuth枚举包含NONE与BASIC_AUTH两种方式同时模型字段basic_auth_user、basic_auth_pass与这里的BASIC_AUTH_USER、BASIC_AUTH_PASS一一对应当选择 Basic Auth 认证后Label Studio 在发起预测请求时会把凭据通过 HTTP Basic Auth 注入请求头参见 label_studio/ml/api_connector.py 中_prepare_kwargs对HTTPBasicAuth的使用。因此如果你在生产环境给模型服务器加了 Basic Auth 保护务必在 Label Studio 连接模型时填写相同的用户名与密码。另外WORKERS/THREADS/LOG_LEVEL对应 ML backend SDK 启动服务器时的进程、线程与日志配置属于服务运行层面的调优参数。六、将模型连接到 Label Studio后端跑起来后需要在 Label Studio 中完成对接在 Label Studio 中创建一个项目进入项目设置的Model页面参见 docs/source/guide/project_settings.md 中 Model 一节点击Connect Model按以下字段填写详细字段说明见 ml.md 的 Connect the model to Label Studio 一节字段填写内容Name为模型取一个名字例如HuggingFace LLMBackend URL模型服务地址默认http://localhost:9090Select authentication method若模型服务器启用了 Basic Auth选择Basic Authentication并填写用户名密码Extra params传递给模型的附加参数可选Interactive preannotations是否开启交互式预标注本示例后端不支持交互模式保持关闭即可对接成功后打开任务即可看到模型基于提示词生成的文本预测。几个容易踩坑的注意点localhost 语义localhost会回环到发出请求的机器本身。如果 Label Studio 运行在 Docker 容器中localhost指向的是容器自身而非宿主机。此时应改用host.docker.internal例如http://host.docker.internal:9090或宿主机内网 IP 来访问 ML 后端。后端访问 Label Studio 数据若任务数据来自上传文件、本地存储或云存储S3/GCS/AzureML 后端需要借助get_local_path()工具函数来自label_studio_tools包把资源 URI 解析并下载为本地文件。使用该函数前必须在 ML 后端的environment段配置两个环境变量LABEL_STUDIO_URLLabel Studio 实例地址必须以http://或https://开头容器内运行时不能写localhost/0.0.0.0应使用宿主机真实 IPifconfig/ipconfig可查LABEL_STUDIO_API_KEYLabel Studio 访问令牌可在个人账户页面获取见 docs/source/guide/user_account.md 中 Access token 一节。由于huggingface_llm处理的是纯文本字段而非文件资源常规文本生成场景无需这两项配置但如果你把任务来源换成需要解析文件的存储类型就需要补上。七、自定义模型与推理逻辑ML 后端天然支持定制你可以在./huggingface_llm目录中添加自己的模型和逻辑。该目录即模型后端的主目录包含model.py、docker-compose.yml、_wsgi.py、requirements.txt等文件目录结构可参考label-studio-ml create生成的模板见 docs/source/guide/ml_create.md。自定义的核心是修改model.py中继承自LabelStudioMLBase的模型类重写predict方法实现自己的推理逻辑def predict(self, tasks, context, **kwargs): Make predictions for the tasks. # tasks: Label Studio 任务 JSON 数组例如 [{data: {text: ...}}] # 在此处加载你的模型并生成文本 return predictions # 符合 Label Studio 预测格式的结果数组predict方法各参数含义如下见 ml_create.mdtasksLabel Studio 任务数据JSON 格式结构参见 docs/source/guide/task_format.mdcontext交互式标注场景下的上下文信息含annotation_id、draft_id、user_id、result等字段返回值predictions预测结果数组需符合 Label Studio 预测格式。对huggingface_llm来说替换MODEL_NAME即可切换为任意 Hugging Face 文本生成模型如 OPT、GPT-2、Llama 系列等你也可以在model.py中改造成支持批量提示词、加入 prompt 模板或接入本地微调模型。修改后重新docker-compose build docker-compose up即可生效。八、底层调用链从界面点击到预测结果从源码看Label Studio 与 ML 后端之间通过一组固定的 HTTP 端点协作定义于 label_studio/ml/api_connector.pyhealth健康检查返回{status:UP}即对应本文第一节的 curl 验证setup连接模型时调用用于交换项目与模型信息predict核心推理端点接收任务数据并返回{results: [...]}versions/job_status/webhook等用于版本同步与训练任务跟踪。Label Studio 侧在 label_studio/ml/models.py 中维护 ML 后端的生命周期状态机DISCONNECTED未连接→CONNECTED已连接→ERROR出错/TRAINING训练中/PREDICTING预测中。连接模型时会先执行健康检查与setup通过后状态置为CONNECTED预测时predict_tasks会把任务批量序列化后 POST 到predict端点并对返回的results做校验要求为列表、且每个预测项必须包含result字段最终以 Prediction 形式持久化并展示给标注人员。这套协议对所有 ML 后端统一生效huggingface_llm只是其中一种实现。理解调用链后你排查模型连不上预测不显示等问题时就能有的放矢先curl健康检查再看setup是否成功最后检查predict的返回格式是否符合协议要求。九、小结与延伸阅读本文完整覆盖了huggingface_llm后端的定位、标注配置、三种启动方式、环境变量参数、与 Label Studio 的连接认证以及自定义模型的方法。核心要点回顾该后端解决的是LLM 文本生成 人工标注的预标注场景基于 Hugging Facetransformers预训练模型推荐 Docker 方式启动默认地址http://localhost:9090健康检查返回{status:UP}通过MODEL_NAME/MAX_LENGTH等环境变量即可调整模型与生成行为BASIC_AUTH_USER/BASIC_AUTH_PASS与 Label Studio 侧的 Basic Auth 认证严格对应自定义能力集中在./huggingface_llm目录内的model.py重写predict方法即可接入自己的模型。若想深入了解 ML 后端的通用机制推荐继续阅读ML 后端集成总览预测工作流、连接模型、训练、交互式预标注编写自己的 ML 后端predict/fit方法与self.set/self.get存储机制ML 后端示例合集GPT、Hugging Face NER、Llama 交互式标注等其他大模型相关后端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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考