Label Studio接入LLM预标注：零部署实现大模型自动标注

做数据标注的朋友应该都有这种体会：项目一启动，最先卡住的往往不是算法，而是“第一批标注数据从哪来”。找外包团队报价按条算钱，周期一拖就是两周；让刚上手的标注员从零开始点标签，效率和一致性都难以保证。后来我在Label Studio里尝试用大模型做预标注，发现只要把思路理顺，这个过程完全可以自动化：让LLM先跑一遍粗标，人工只需要在预标注结果上做确认和修正，整体标注成本能降一大半。这篇文章就把我实际用的这套方案完整拆开讲，基于CubeStudio内置的LLM标注后端，覆盖文本分类、NER、翻译和图片描述四类常见场景，而且不需要自己写后端服务，零部署接入Label Studio的ML Backend。

这套方案的好处在于，它把所有复杂的工程细节都封装好了。你不需要懂Flask、不用研究Docker部署，也不用去读Label Studio ML Backend的源码实现。CubeStudio做的事情很简单：把“调用大模型”这件事转换成Label Studio能够直接理解的HTTP接口，然后在标注项目里把这个接口挂上去，点一下Auto Annotation，模型返回的预测结果就自动填进标注框里。下面我按自己的实操过程，从原理到配置再到踩坑，一步步说清楚。

1. 核心思路拆解：为什么LLM预标注能省下大量标注时间

很多第一次接触的人会问：大模型标注的结果能信吗？会不会把数据搞乱？其实这里要换个角度理解。预标注的价值不是代替人工，而是把人工从“从无到有”里解放出来，变成“从有到优”。比如一个文本分类项目，标注员原本需要在五个候选标签里反复斟酌，现在模型已经给出了一个相对合理的标签，标注员只需要判断“对”还是“不对”，不对就一键切换。单条耗时可以从三十秒压缩到五秒，效率差距是数量级的。

从我跑过的几个项目来看，LLM在文本分类上的准确率通常能达到80%以上，如果领域不那么冷门，甚至能到90%。NER会稍微难一些，尤其是实体边界和特殊命名容易出错，但只要提示词设计得当，大部分常见实体类型都能正确识别。翻译类场景更是大模型的主场，在专业术语不复杂的前提下，初翻质量已经足够作为基础稿。图片描述则需要多模态模型，目前像GPT-4o或者开源的Qwen-VL都能直接吃图片URL，描述结果在图像理解这个语义层级上已经做得相当稳定。

这套方案在工程上还有一个隐形收益：数据管理和权限控制仍然完全在Label Studio里完成。预标注结果只是作为“建议”出现在界面上，真正的标签数据依然由标注平台统一存储、导出、审核。CubeStudio不会绕过Label Studio的数据模型，也不会引入额外的工作流割裂。对团队来说，这意味着几乎不需要调整现有的标注协作流程，只是每个人面前多了一份“草稿”，效率自然就上去了。

1.1 传统ML Backend的部署痛点

Label Studio的机器学习后端（ML Backend）机制其实很早就有了。官方文档里有一套标准的接入流程：写一个Python类，实现predict()方法，返回特定结构的JSON，再把这个类用Flask或Tornado包成一个HTTP服务，最后在Label Studio里添加该服务的URL。听起来不复杂，但一旦涉及多个场景、多个模型，问题就来了。文本分类一个服务，NER又一个服务，图片描述还得单独写部署脚本，每个服务都要考虑模型加载、批处理、异常退出、接口兼容性。最麻烦的是，如果标注过程中发现模型输出格式不符合预期，还得改代码重新部署一遍。

我最早接NER的时候，就在这个上面卡了一整天。虽然Label Studio的预测API结构有官方文档说明，但实际返回结果时，from_name和to_name必须和标注配置里的控制标签完全一致。模型输出的实体位置是基于原始文本的字符偏移，我需要在服务里把偏移量妥帖地换算成Label Studio需要的前后位置。一旦有特殊符号或多字节字符，偏移就容易错位，标注页面就定位不到正确的高亮区间。这种重复劳动做了几次之后就很难受，所以后来看到CubeStudio这种把接线工作内置的解决方案，我几乎没犹豫就切了过来。

1.2 CubeStudio的“零部署”到底零在哪

CubeStudio在设计上把ML Backend的工程细节全部隐藏了。它用一个统一的配置入口接收LLM的API密钥、模型名称和任务提示词，然后在本地启动一个兼容ML Backend协议的HTTP服务。原本需要手写的Controller层、数据格式转换层、错误处理层，现在都变成了配置项。启动这个服务不需要额外安装Torch、TensorFlow或者加载本地权重，所有推理都通过调用云端LLM的API完成，因此资源占用极低，一台2核4GB的轻量服务器就能跑。和传统ML Backend相比，“零部署”体现在三个层面：不用写后端代码、不用维护模型服务进程、不用为不同标注任务分别起服务。

当然，这个“零”是针对服务端来说的。你仍然需要有个地方运行CubeStudio进程，也需要有可用的LLM API。但前者只是一个常驻脚本，后者你本来就要用大模型，这些成本都非常可控。更重要的是，CubeStudio把LLM的请求模板抽象成了几个内置类型，文本分类、NER、翻译、图片描述都对应了一套预设的提示词和输出解析逻辑。你要做的只是往里填业务字段，然后就能在Label Studio里看到结构化结果。

2. CubeStudio与LLM标注后端的架构关系

要灵活使用这套方案，脑内必须有一个清晰的架构图。我习惯把整个过程拆成四层：数据层是Label Studio里的标注项目，展示层是标注前端页面，服务层是CubeStudio启动的ML Backend兼容接口，模型层则是各类LLM API。四者的调用顺序是：标注员在页面上点击“Auto Annotation”按钮，Label Studio把当前任务的文本或图片信息发送给服务层（即CubeStudio地址），服务层根据配置的任务类型组装提示词，再请求模型层的大模型API，等模型返回后解析成预测结果，填回Label Studio界面。

理解这个链路很重要，因为后续所有问题基本都出在这几层的衔接上。比如报错“Prediction result is invalid”，说明服务层返回的JSON结构不符合Label Studio的预期；又比如翻译任务的输出在页面上不显示，多半是字段映射没配好。只要脑内清楚每一层的职责，排查起来就能直接定位到是配置问题还是API问题。

2.1 ML Backend接口协议与Label Studio的预测格式

Label Studio的ML Backend要求predict()方法返回一个列表，每个元素对应一个任务的预测结果。以下是文本分类最简结构的示意：

[ { "result": [ { "from_name": "label", "to_name": "text", "value": { "choices": [ [ "Positive" ] ] } } ], "score": 0.93 } ]

这里的from_name是标注配置里控制标签的名称，to_name是被标注对象的名称，value按不同任务类型装载结果。比如NER的value里会有start和end表示实体范围，图片描述的value里则是text数组。CubeStudio内部维护了一套映射表，根据你在配置里选择的“任务类型”自动生成对应格式，这正是它比我手写服务稳定得多的地方。

2.2 为什么CubeStudio不需要加载模型权重

我一开始以为CubeStudio会在本地跑模型，实际上它只是一个“转换网关”。它在启动时并不初始化任何神经网络模型，只是持有LLM API的配置信息和构造请求的模板。收到Label Studio的预测请求后，它把任务文本嵌入到预设的提示词中，以特定格式请求远程LLM，再把回复文本解析成JSON。所以这个服务可以保持很轻量，即使在同一台机器上运行Label Studio也几乎不占用什么内存。很多做label的同事看到它只占不到200MB内存，都觉得很意外，其实原理就是它压根没加载模型。

这种设计带来的好处是：模型迭代非常方便。如果你觉得某个模型在中文数据上分得好，或者另一个模型在翻译上的语气更自然，你只需要修改配置文件里的model字段，然后重启服务。标注项目本身完全不用动，预标注逻辑就切换了新模型。相比传统ML Backend的“每次换模型都要重新下载权重、准备环境、兼容CUDA”，这个体验要友好得多。

3. 零部署接入ML Backend的完整实操步骤

现在进入正题。我用一个实际项目来演示接入流程。我的环境是Ubuntu 22.04，Python 3.10以上，Label Studio是Docker方式部署在服务器上，CubeStudio直接装在宿主机，通过局域网IP让Label Studio访问。如果你是用本地或者云服务器，思路完全一致。

3.1 安装CubeStudio并初始化配置

CubeStudio的安装很直接，用pip安装即可。注意它依赖了requests、pydantic、fastapi和uvicorn，如果环境里有高版本冲突，建议用虚拟环境隔离。

python3 -m venv cubestudio-env source cubestudio-env/bin/activate pip install cubestudio

装完后先初始化一份配置文件。CubeStudio提供了预设模板，里面已经包含所有内置任务类型的配置占位。

cubestudio init --output config.yaml

生成的config.yaml长这样（我只保留关键字段）：

server: host: "0.0.0.0" port: 9090 llm: provider: "openai" # 也可以是 compatible_qwen / ollama 等 api_key: "sk-xxxx" model: "gpt-4o-mini" base_url: "https://api.openai.com/v1" temperature: 0.1 backend: project_name: "Demo Project" # 显示在Label Studio里的名称 task_type: "text_classification" # 可选: text_classification, ner, translation, image_caption label_config: | <View> <Text name="text" value="$text"/> <Choices name="label" toName="text" choice="single"> <Choice value="Positive"/> <Choice value="Negative"/> </Choices> </View> prompt_template: | Classify the sentiment of the text. Output only label. Text: {{text}} Label:

几处关键配置要特别说明。server.host如果设置成0.0.0.0，表示CubeStudio会监听所有网卡，这样Label Studio在别的机器上也能访问。backend.project_name这个字段会被Label Studio用来标识模型名称，建议和标注项目名保持一致。label_config是一段XML配置，用来让ML Backend知道前端的标签控件结构，这个和Label Studio项目里的配置保持一致即可。

3.2 启动LLM标注后端并接入Label Studio

配置文件准备好后，一条命令就能启动服务：

cubestudio backend --config config.yaml

看到日志输出Uvicorn running on http://0.0.0.0:9090，就表示接口已经就绪。可以用curl简单验证一下健康状态：

curl http://localhost:9090/health

如果返回{"status":"ok"}，就可以去Label Studio接入了。在Label Studio项目的Settings里找到Machine Learning，点击Add Model，填入以下内容：

• Model Name：随便取，比如LLM Auto Label
• Model URL：http://<你的服务器IP>:9090
• 是否需要认证：一般不需要

添加完成后，Label Studio会向CubeStudio发送一个GET /api/models请求，拿到模型信息。看到状态变为“Connected”，说明接入成功。之后在标注界面右侧可以选择“Model”，并点击“Auto Annotation”按钮，Label Studio会把当前任务发给CubeStudio，返回的预测结果会直接填到标签控件上。

3.3 手动验证预测结果与真实标注的一致性

接入成功不代表万事大吉。我强烈建议第一次使用的时候，手动挑三五个任务，先不点Auto Annotation，而是用“Predict”按钮逐条看返回结果。因为你可能遇到一种情况：接口通了，页面也显示通了，但是返回的预测结果没有出现在任何控件上。这通常是label_config里的控件name和from_name不一致导致的。CubeStudio默认使用label_config中第一个Choices控件的name作为from_name，如果你的前端标注配置里把控件叫sentiment，而这里写的是label，Label Studio就会拒绝填充。

这类问题排查起来不算难，但初次接触时很容易绕进去。根据我个人经验，最稳妥的方法是：把CubeStudio的label_config直接从Label Studio项目的Labeling Interface前端代码里复制过来，保证完全一致。不要自己手动重写，因为少了某个标签或者改了一个name字段，都可能让预标注静默失败。

4. 四大标注场景的LLM提示词设计与效果

不同标注任务对提示词和输出解析的要求很不一样。CubeStudio把这些差异封装成了几个“任务类型”，但提示词这块依然需要你自己根据业务场景去打磨。我分别说说四类任务的配置要点和实际效果。

4.1 文本分类：给LLM一个明确的标签枚举

文本分类的关键是让模型输出“有限集合中的某一个标签”，而不是自由发挥。提示词里必须把可用标签全部列出来，并且只允许输出枚举之一。CubeStudio针对文本分类会要求prompt_template里有一个{{text}}占位符，同时建议把标签枚举写在提示词里。

我用的一个简单模板：

You are a sentiment classifier. The labels are: Positive, Negative, Neutral. Read the text and output exactly one label. Do not output extra words. Text: {{text}} Output:

温度参数设低一点，比如0.1，让模型输出更稳定。CubeStudio解析时会去掉首尾空白，然后和label_config里的Choice值做匹配。如果模型偶尔输出了“positive”（小写）或者“Positive.”，CubeStudio会做大小写和标点的容错，但为了保险起见，我还是建议在提示词里强调“Do not output extra words”。

实测下来，英文社交文本的情感标签准确率在85%～95%之间。中文文本也很不错，只是偶尔在“中性”和“消极”的边界上拿不准，人工修正成本很低。

4.2 NER：用偏移量对齐原文

NER比文本分类复杂在两部分：一是模型要输出实体文本和实体类型，二是要在原始文本里找到准确的字符位置。CubeStudio内置的NER解析器是这样工作的：LLM接收到原文和实体类型枚举后，输出一个JSON数组，每个元素包含text和type。CubeStudio拿到这个数组后，去原文中搜索实体的出现位置，计算出start和end偏移量，再组装成Label Studio需要的高亮片段。

提示词模板大致如下：

You are an NER system. Extract entities of types: PERSON, ORG, LOC, TIME. Return JSON list of {"text": "...", "type": "..."}. Text: {{text}} Entities:

使用这个方案时，一个容易踩的坑是：当实体在原文中出现多次时，CubeStudio默认返回第一个匹配位置。如果你的标注需求是标注所有出现位置，那就需要在提示词里让模型输出具体的序号，或者接受只标记第一处。对于大多数预标注场景，标记第一处已经够用了，人工在页面上补充其他位置也不费多少事。

我还在一个法律文书数据集上跑过中文人名和机构名识别。启用大模型后，长尾实体（比如少见的律师姓名）识别效果比我从spaCy训练的小模型好很多，尤其是一些多字人名和复杂机构全称。但代价是API调用延迟，每条约1到3秒，所以不建议一次性让整个批次自动跑完，最好等人点再请求。

4.3 翻译：把原文替换成目标语言

翻译在预标注里有点特别，它本质上不是“标注”，而是“改写”。Label Studio的Translation控件支持把原文和译文平行展示，ML Backend需要预测的结果是一个文本字段，替换或追加在目标语言框里。CubeStudio的translation任务类型会要求你在提示词里指定源语言和目标语言。

Translate the following text from English to Chinese. Output only the translated text. Text: {{text}} Translation:

在Label Studio的标注配置中，会有两个Text控件，一个name="text"，一个name="translation"，toName指向原文。CubeStudio返回的结果会在value.text这个字段里。你需要在Label Studio界面里选择“Pre-annotated Text”或者手动确认。翻译质量方面，通用文本的常规翻译很稳定，但是专业术语（比如法律、医疗）需要你在提示词里加上术语表，否则大模型很可能直译。

4.4 图片描述：多模态模型的接入配置

图片描述需要多模态模型，并且CubeStudio要从Label Studio拿到图片的访问方式。Label Studio的图片标注通常是Image控件，其值是图片URL或本地路径。CubeStudio在收到预测请求时，会从任务数据里提取图片URL字段，然后将其作为消息内容的一部分发送给支持视觉的模型。

配置task_type为image_caption，提示词模板如下：

Describe the image in detail, focusing on the main objects and their actions. Output only the description text.

调用时，CubeStudio会把图片URL放进请求体的image_url字段，GPT-4o和Qwen-VL都支持这种标准方式。返回的描述文本会被放到一个Text控件的value.text里。当然，如果用的是Ollama部署本地多模态模型，base_url和model相应改成Ollama的地址即可。

这里的要点是：图片URL必须是Label Studio能够访问到的地址。如果你用Docker部署Label Studio，图片存在Docker卷里，CubeStudio在宿主机上可能没法直接访问容器内部路径。最简单的办法是让图片存储在对象存储或公网可访问的URL下，或者在CubeStudio的配置里设置它与Label Studio共享同一个宿主机路径，并做相应的路径映射。

5. 常见问题与排查技巧实录

这套方案虽然省事，但实际跑起来还是会遇到不少问题。我把自己踩过比较典型的几个整理成速查表，方便你对照排查。

5.1 预测格式不符合Label Studio预期的快速定位

我在前面反复强调格式问题是有原因的。只要Label Studio返回了预测结果但界面上不显示，九成都是格式问题。有一个通用排查方法：用curl直接向后端发送一个模拟任务数据，看返回的JSON结构。

curl -X POST http://localhost:9090/predict \ -H "Content-Type: application/json" \ -d '{"tasks":[{"data":{"text":"I love this product!"}}]}'

返回的JSON里，检查result下的from_name、to_name和value。只要这三个字段和你在Label Studio里预标注配置匹配，就一定能显示出来。官方文档里的ML Backend示例使用的是from_name和to_name，但很多自写服务容易漏掉，导致前端没有任何反馈。

5.2 错误提示“Provider rejected request schema or tool payload”的应对

如果你用的是兼容OpenAI的API，有时会遇到类似Provider rejected request schema or tool payload的报错。这个提示通常说明请求中携带了工具调用（function calling）参数，但目标模型或网关不支持。CubeStudio在某些版本里为了增强NER结构化输出，会默认带出tools配置。如果你的模型不支持，最简单的解决办法是在配置里关闭工具调用：

llm: use_tools: false

另外，如果你在base_url里填的是OpenAI兼容网关（比如OneAPI或New API），也要确认网关后端是否透传了tools参数。很多网关在默认配置下不会把tools传给上游模型，导致请求被拒。关闭工具调用后，结构化的实体抽取改由提示词要求模型输出JSON，CubeStudio也能正常解析。

5.3 中文文本偏离和多字节编码对NER的影响

中文NER的偏移问题尤其常见。英文按空格分词，偏移简单；中文每个字占一个字符，但Python字符串默认的索引是按Unicode码点计算的，和Label Studio前端JavaScript的偏移也是按Unicode码点计算，理论上是一致的。问题往往出在换行符或特殊字符上，比如原文里有\r\n，在JSON序列化后变成\\r\\n，实际字符数变了，偏移就会差一两个。排查时可以打印出模型返回的实体文本和原文的索引范围，手动比对一下。CubeStudio内部有一套对齐逻辑，但遇到模型输出实体文本与原文存在细微差异（比如多了个空格）时，它可能找不到匹配位置，这时后处理逻辑就会尝试模糊匹配。如果频繁出现找不到实体的情况，建议在提示词里强调“实体文本必须与原文完全一致，禁止追加描述或空格”。

5.4 多任务同时使用的配置隔离技巧

实际项目中很少只用一种模型处理所有数据。CubeStudio允许你在配置中定义多个backend段，每个段有不同的task_type、prompt_template和模型参数。你可以在一个进程里启动多个端口，然后在Label Studio中为不同项目添加不同的模型URL。比如：

backend: - project_name: "News Classifier" task_type: "text_classification" port: 9091 prompt_template: "..." - project_name: "Legal NER" task_type: "ner" port: 9092 prompt_template: "..."

不过要注意，同一个llm配置的api_key可以复用，但不同任务之间如果要使用不同模型，需要在backend段内覆盖model字段。这样设计的好处是：标注团队切换到不同项目时，不用像以前那样各起各的服务，只要在项目里选对应模型即可。

6. 一些使用心得与优化建议

如果你准备在实际项目中采用这套方案，有几点建议值得参考。

第一，不要把预标注结果当成无需审查的最终数据。LLM幻觉在边界场景一定存在，比如文本分类中不常见的情感表达、NER中的长尾实体、图片描述中的小目标遗漏。人工修正的回流数据建议保存下来，后续可以作为微调或评估数据积累。从这个角度说，预标注不是一个“代替标注员”的方案，而是一个“让标注员更高效”的工具。

第二，合理控制模型请求频率。如果一群标注员同时点击Auto Annotation，CubeStudio默认是并发请求LLM的。免费或配额有限的API很容易在短时间内被打爆，导致大量请求返回429。建议在CubeStudio配置里加上rate_limit和max_concurrent参数，比如每秒最多两次，最大并发3，避免影响团队使用。

server: rate_limit_per_second: 2 max_concurrent_requests: 3

第三，提示词要不断根据反馈迭代。我通常每跑完30条预标注数据，会随机抽查10条，把模型做错的样本收集起来，针对性地修改提示词。比如在NER中，经常会把公司名称识别成“WHERE”类型，我就会在提示词里增加一句“If the entity is an organization, choose ORG instead of LOC”。这比换模型更直接有效。

最后再分享一个我很早踩过的小坑：不要把CubeStudio和Label Studio部署在同一台机器的不同容器里还指望网络自动互通。容器服务的IP是隔离的，你填的URL如果写localhost，只会在当前容器里打转。最稳妥的做法是统一使用宿主机IP，并把CubeStudio的host设为0.0.0.0。如果涉及HTTPS或代理，还要注意Label Studio和CubeStudio的端口必须都能从外部访问。我在迁移到内网环境时，就是因为防火墙只开了Label Studio的端口，CubeStudio一直连不上，后来检查防火墙才解决。

当然，这套方案也不是万能的。如果你要标注的数据流非常大，每秒几十上百条，那LLM API的延迟和成本会成为一个瓶颈，效率不一定比人工标注快。但绝大多数中小团队的数据集规模都没到那一步，LLM预标注完全能撑起标注流程的“草稿”角色。在动手之前，建议先拿50条数据测一下效果，确认输出质量和人工修正成本都能接受，再全面铺开。