Label Studio预标注数据导入指南：用模型预测加速人工标注

做数据标注的团队，尤其是那种模型已经跑到八九十分的团队，大概率都遇到过这样的尴尬：模型输出的结果已经能看出来了，可标注平台里等待处理的任务，还是只能靠人工从零开始画框、打标签。明明机器已经给了一遍答案，人工却要假装没看见，重新做一遍。这个问题的解法之一，就是把模型的预测结果整理成预标注数据，批量导入到 Label Studio 里，让标注员的工作从“从零标注”变成“审核修改”。

这篇文章围绕“Label Studio 导入预标注数据”这台事，讲清楚三块内容：预标注在数据模型里到底放在什么位置、常见的四条导入路径怎么选、以及我实测下来最容易翻车的几个细节。适合正在搭数据标注流水线、想用模型辅助人工标注提速的工程师和标注团队负责人参考。文章里的例子都是我自己项目里的通用场景，不绑定具体业务，你改改字段就能用。

1. 预标注导入改写了标注流程：从零画框变成审核修改

1.1 标注流程的时间账

我接手过一个文本情感分类的小项目，一万条短评要标注。当时团队里一位标注员，一天八个小时全神贯注，一个小时大概能标 200 条，一条折算下来 15 秒左右。一万条就意味着将近 50 个小时的纯人工工时，算上疲劳、返工和复核，实际要两到三周才能交付。

后来我们把一个已经训练过的分类模型先跑了一遍全部语料，准确率大概 85%，剩下的 15% 也基本集中在少数几个容易混淆的类别上。模型输出整理成预标注塞进 Label Studio，标注员打开任务看到的是已经选好的情感标签，只需要判断“这个标签对不对”，不对就改一下。同样一万条，单条耗时从 15 秒降到了 6 到 8 秒，整个交付周期压缩到一周以内。

这个账很容易算：模型哪怕只有 70% 的准确率，只要错误不是集中到没法看的程度，预标注都能显著降低人工工作量。因为“判断一个已有答案对不对”和“从空白处想出一个答案”，认知负担完全不是一个量级。

1.2 “机器打草稿、人工定稿”的定位

需要先明确一个概念：预标注不是替代人工标注，而是把模型输出当成“草稿答案”给到标注员。Label Studio 在数据模型层面严格区分了三种状态：

• 原始数据：任务里实际要标注的内容，比如一段文本、一张图片的地址。
• 预标注（predictions）：模型或者旧系统给出的预测结果，属于“候选答案”。
• 正式标注（annotations）：标注员在界面上确认、修改、提交后的结果，属于“最终答案”。

理解了这三层关系，你就不会把预标注直接塞进正式标注的位置。预标注进的是 predictions 字段，它不参与最终的标注统计，也不污染正式数据。人工确认后，系统才会把修改结果落到 annotations 里。这个设计保证了数据质量的可追溯性——哪些是机器给的，哪些是人工定稿的，一眼就能分清。

1.3 适合预标注的场景与两个反例

适合用预标注导入的场景，我总结下来有三类：

• 模型已经有一版可用结果，哪怕只有 70 分，人工修正比从零标注省力。
• 从旧标注工具迁移历史数据，旧系统里已经有手工标注结果，直接转成新系统的预标注，再走一遍确认流程。
• 多模型对比阶段，两个模型各跑一版预测，导入到同一个任务里做人工盲评。

反过来也有两个不适合硬上预标注的场景。一个是项目刚冷启动，手里没有任何模型结果和历史数据，这时候预标注无从谈起；另一个是模型输出的标签体系跟新项目的标注规范根本对不上，比如模型输出的是“积极/消极”，但新项目要的是“褒义/中性/贬义”，强行映射后错误率太高，人工修改反而比从零标注更费劲。

2. 动手写 JSON 前，先搞清 data、predictions、annotations 的分工

2.1 三个字段各管什么

Label Studio 里的一个任务，本质上就是一个 JSON 对象。最外层常见三个字段：data、predictions、annotations。

data 放的是这次要标注的原始内容。文本分类任务里就是{"text": "这句话本身"}；图像检测任务里就是{"image": "图片的URL"}。数据本身可以有很多个键，只要在标注配置里引用到了，界面就会正常渲染。

predictions 放模型预测结果，是一个数组，因为同一份数据可以有多条候选预测。数组里每个元素至少包含一个 result 字段，存放具体的标签或框；还可以带 score 和 model_version，用来表示置信度和模型来源。

annotations 放人工标注结果，结构跟 predictions 的 result 很像，但它是由标注员在界面上提交后生成的。你通过导入接口传任务时，通常只需要给 data 和 predictions，annotations 留给人工环节去填。

2.2 为什么预标注只能放 predictions，不能直接写进 annotations

有的同事问过我：既然预标注已经大概率是对的，为什么不直接把模型结果写成 annotations，这样人工打开任务就是已经标注好的状态，不是更省事吗？

这个做法短期看省了一步，长期看坑很大。第一，你失去了“机器结果”和“人工结果”的边界，后续统计标注质量、分析模型错误都说不清数据来源。第二，如果模型预测被当成正式标注直接落库，标注员审核时改了一个标签，你没法对比“模型原判”和“人工修正”。

所以 Label Studio 才设计了 predictions 这个独立通道。模型结果永远是建议，人工确认后才成为标注。这个原则我建议你在团队里定成铁律。

2.3 一个任务 JSON 的骨架

看一个最简骨架：

{ "data": { "text": "这里是要标注的文本" }, "predictions": [ { "result": [ { "from_name": "sentiment", "to_name": "text", "type": "choices", "value": { "choices": ["正面"] } } ], "score": 0.96, "model_version": "sentiment_model_v1" } ] }

一个导入文件里可以包含多条这样的任务，组成一个数组。Label Studio 也支持 JSONL 格式，每一行放一个任务对象。实际使用中我习惯用 JSONL，因为逐行处理方便，出错了也知道具体是哪一条的问题。

3. 四种导入路径怎么选：UI、REST API、Python SDK、Storage 同步

3.1 界面导入：第一次验证格式最快

如果你只是想知道自己构造的 JSON 对不对，最快的方式是打开 Label Studio 项目页面，点右上角的 Import 按钮，选一个 JSON 或 JSONL 文件上传。

界面导入适合小批量验证，几十条、上百条都没问题。第一次接触预标注格式的人，建议先手工构造几条数据，从界面导入看看效果。界面还有个好处：上传完立刻能看到任务列表里每条任务是否带着预测标记，点进任务还能直接看到预测结果渲染得对不对。

3.2 REST API：定时脚本和流水线的首选

一旦进入工程化阶段，就不能天天手动上传文件了。Label Studio 提供了 REST API，导入接口是POST /api/projects/{project_id}/import。用 Python 的 requests 直接调用：

import json import requests API_URL = "http://localhost:8080" API_KEY = "你的APIKey" project_id = 1 tasks = [ { "data": {"text": "这款耳机的降噪效果超出预期"}, "predictions": [ { "result": [ { "from_name": "sentiment", "to_name": "text", "type": "choices", "value": {"choices": ["正面"]} } ], "score": 0.97, "model_version": "sentiment_model_v3" } ] } ] headers = { "Authorization": f"Token {API_KEY}" } resp = requests.post( f"{API_URL}/api/projects/{project_id}/import", headers=headers, json=tasks ) print(resp.status_code)

API Key 在 Label Studio 的 Account & Settings 页面里可以找到。接口调用成功后，返回的任务列表里能看到新创建的任务 ID。

用 REST API 的好处是方便放进定时脚本、模型训练流水线，或者跟 CI/CD 流程集成。模型每跑完一批预测，脚本自动把结果导入标注平台，标注团队第二天打开就能看到带预标注的新任务。

3.3 Python SDK：在预处理脚本里一条龙完成

如果你已经在写 Python 预处理脚本，直接引入官方的 label-studio-sdk 更顺手。SDK 把 API 封装成了更自然的方法调用：

from label_studio_sdk import Client API_URL = "http://localhost:8080" API_KEY = "你的APIKey" ls = Client(url=API_URL, api_key=API_KEY) project = ls.get_project(id=1) tasks = [ { "data": {"text": "这个手机电池续航不错"}, "predictions": [ { "result": [ { "from_name": "sentiment", "to_name": "text", "type": "choices", "value": {"choices": ["正面"]} } ], "score": 0.94, "model_version": "sentiment_model_v3" } ] } ] project.import_tasks(tasks)

这样的好处是，你可以在同一个脚本里完成“读取数据 → 模型推理 → 结果格式化成预标注 → 导入 Label Studio”全流程。SDK 适合那些已经把数据处理逻辑写在 Python 里的团队，复用成本最低。

3.4 Storage 同步的误区

Label Studio 支持本地文件系统、云存储桶的同步，配置之后，新的数据文件会自动变成标注任务。这个功能对原始数据入库很友好，但我要提醒一句：预标注批量导入这件事，不建议依赖 Storage 同步来跑。

原因有两方面。Storage 同步更适合存放“纯原始数据”的目录，比如图片文件、文本文件，Label Studio 读取后会按字段映射生成任务；但如果你让模型输出直接写到同步目录，文件格式、命名、更新时机都得额外控制，一旦目录出现半成品文件，任务会被不完整地导入。另外，预标注数据通常是从模型产线生成、带明确版本信息的，这类数据走 API 或 SDK 导入，你能拿到导入结果的响应，方便排查问题。Storage 同步适合的，是数据源在持续增长、且不需要带复杂预标注的场景。

3.5 选型对照表

如果让我给一个默认建议：验证格式用 UI，正式导入用 REST API 或 Python SDK，规模再大就写成脚本定时跑。

4. 预标注 JSON 三种模板：文本分类、文本NER、图像检测

4.1 文本分类：choices 类型的最小完整示例

先看标注配置。假设你的项目里拖了一个 Choices 控件：

<View> <Text name="text" value="$text"/> <Choices name="sentiment" toName="text" choice="single"> <Choice value="正面"/> <Choice value="负面"/> <Choice value="中性"/> </Choices> </View>

对应的预标注 result 就得这么写：

{ "data": { "text": "这款耳机的降噪效果超出预期" }, "predictions": [ { "result": [ { "from_name": "sentiment", "to_name": "text", "type": "choices", "value": { "choices": ["正面"] } } ], "score": 0.97, "model_version": "sentiment_model_v3" } ] }

注意 choices 里的值是数组，哪怕单选也是数组形式。这是 Label Studio 的约定，写错容易导入后不渲染。

4.2 文本NER：字符偏移量 start/end 的算法

文本命名实体识别是另一个高频场景。标注配置里一般是一个 Text 控件配一个 Labels 控件：

<View> <Text name="text" value="$text"/> <Labels name="ner" toName="text"> <Label value="人物" background="#ff0000"/> <Label value="地点" background="#00ff00"/> </Labels> </View>

预标注实体通过字符偏移量定位。比如原始文本是“张三住在北京。”，字符串下标从 0 开始：张是 0，三是 1，住是 2，在是 3，北是 4，京是 5，句号是 6。“张三”占下标 0 到 1，“北京”占下标 4 到 5。

在 result 里，start 是实体起点，end 是终点，end 不包含实体最后一个字符的下一位，也就是左闭右开区间：

{ "data": { "text": "张三住在北京。" }, "predictions": [ { "result": [ { "from_name": "ner", "to_name": "text", "type": "labels", "value": { "start": 0, "end": 2, "text": "张三", "labels": ["人物"] } }, { "from_name": "ner", "to_name": "text", "type": "labels", "value": { "start": 4, "end": 6, "text": "北京", "labels": ["地点"] } } ], "score": 0.88, "model_version": "ner_model_v2" } ] }

这里最容易踩的坑是 end 值多算一位或少算一位。多算一位，界面会把相邻字符一并标进去；少算一位，最后一个字会漏掉。我的习惯是：在脚本里生成偏移量之后，强制校验一下text[start:end]是否等于预标注里写的 text 字段，不相等就跳过这条候选预测，宁可少一条预测，也不要一条虚假的。

中文按字符计数，不需要按字节数，这一点跟英文场景一样，放心用。

4.3 图像检测：bbox 百分比坐标的换算

图像检测的标注配置通常长这样：

<View> <Image name="image" value="$image"/> <RectangleLabels name="label" toName="image"> <Label value="车辆" background="#ff0000"/> <Label value="行人" background="#00ff00"/> </RectangleLabels> </View>

预标注里每个框对应一个 result：

{ "data": { "image": "http://localhost:8080/data/upload/1/sample.jpg" }, "predictions": [ { "result": [ { "from_name": "label", "to_name": "image", "type": "rectanglelabels", "value": { "x": 15.2, "y": 30.1, "width": 20.5, "height": 10.8, "rotation": 0, "rectanglelabels": ["车辆"] } } ], "score": 0.91, "model_version": "det_model_v1" } ] }

x、y、width、height 这四个值一律是百分比，范围 0 到 100，坐标原点在图像左上角。x 是框左上角的横坐标百分比，y 是左上角的纵坐标百分比，width 是框宽度占图像宽度的百分比，height 是框高度占图像高度的百分比。

模型输出的检测框坐标一般是像素，转换时用百分比 =（像素 / 图像宽或高）× 100。比如一张宽 1200 像素、高 800 像素的图，框的左上角在像素坐标（180，240），那么 x = 180 / 1200 × 100 = 15，y = 240 / 800 × 100 = 30。

这个换算逻辑务必写在脚本里，不要手工算。

4.4 from_name、to_name、type 必须和标注配置对齐

前面几个例子里反复出现的 from_name、to_name、type，是 Label Studio 渲染预测结果的核心映射关系：

• from_name：对应标注配置里控件的 name 属性。比如 Choices 控件的 name="sentiment"，那么 result 里的 from_name 就必须是 sentiment。
• to_name：对应被标注的数据控件名称。比如 Text 控件的 name="text"，to_name 就是 text。
• type：指明这个 result 是什么类型的标注区域。choices 对应分类，labels 对应文本实体，rectanglelabels 对应图像框。

这三项组合成 Label Studio 的“标注配置指纹”。任何一个写错，预测结果都无法渲染到界面上。更麻烦的是，这种错误往往不会在导入时爆出提示，而是成为一个“看不见预测”的隐形问题，留到下一章详细说。

5. 实测最容易翻车的五个细节：坐标单位、字段名、排序、去重、图片路径

5.1 像素坐标直接写进 bbox 导致框爆掉

我第一次给图像检测项目导预标注，就是从模型输出里直接拿像素坐标塞进了 value，然后打开任务发现框的尺寸大得离谱，有的框直接把整张图盖住了。

原因就是上一章说的：Label Studio 的矩形框字段是百分比制，不是像素制。一张 1200 像素宽的图，如果框实际宽度是 300 像素，直接写 width=300，系统会把它解释成宽度占图像的 300%，不爆才怪。

解决办法是在模型推理脚本后面加个换算函数，把所有 pixel 坐标统一转成百分比，再做一次越界检查，保证 x、y、width、height 都在 0 到 100 之间。

5.2 from_name 写错：导入成功但界面上看不到预测

这个坑我踩过不止一次。典型表现是：导入接口返回 200，任务列表里也能看到“已有预测”的标记，但点开任务，预测结果就是不出来，标注区域一片空白。

排查下来，跑不了是 result 里的 from_name 跟标注配置不一致。比如标注配置里控件叫 tag，你写成了 label，Label Studio 拿着这个 result 找不到对应的控件去渲染，于是静默忽略掉了。

这种“无声失败”最容易消耗排查时间。我的做法是，每次写预标注生成脚本之前，先把标注配置导出来看一眼控件 name，然后把这段映射关系配置到脚本里，不让任何人手工填写 from_name。另一个习惯是导入前先造 5 条样例数据，从界面点进去确认预测渲染正常，再跑全量。

5.3 score 与 model_version 缺失打乱排序和追溯

score 和 model_version 不是必填字段，但强烈建议每次都带。因为一条任务的 predictions 是数组，里面可以有多个预测候选，界面经常会按 score 排序，好的排前面。缺了 score，候选预测的顺序就很混乱。

model_version 更重要，它解决的是“这条预测是哪一版模型给的”。模型迭代之后，标注团队看到的结果可能是 v1 也可能是 v3，没有版本标记，后续导出分析时根本没法按版本分组，模型对比也无从谈起。

5.4 重复导入不会自动去重

定时脚本跑起来之后，很容易出现一个我没预料到的情况：同一个模型结果文件被导入两次，Label Studio 里就出现了两份相同的任务。

Label Studio 的导入接口不是幂等的。传两次同样的 JSON，它就创建两次任务，不会自动识别重复。想控制这一点，得自己在脚本里做差集：导入前把任务列表查出来，用 data 里的业务唯一键，比如文本内容、文件名，去掉已存在的再导入。

或者更简单的方式：确认上一次导入完全成功且不需要保留旧任务时，先清空项目再导入。清空操作要谨慎，生产环境我一般只在测试环境这么干。

5.5 本地图片路径标注员打不开

图像任务的预标注，data.image 字段经常是相对路径或本机文件路径，比如/data/images/a.jpg。这种路径开发机自测没问题，但标注员在其他电脑上打开任务时，图片加载不出来，就没办法审核。

原因很简单：浏览器加载图片，请求的是 Label Studio 后端的地址，后端必须能访问到这个路径。本机文件对后端不可见，自然 404。

解决方案有两条路：一是先把图片文件传到 Label Studio 管理的上传目录里，用平台提供的 URL；二是走 Storage 同步，把图片放到配置好的存储目录中。总之，data 里的图片地址必须是后端服务能访问、浏览器能直接加载的合法 URL。

5.6 导入前五连查清单

我把日常检查项固定在生成脚本的末尾，每次导入前自动打印一份检查结果：

• 标注配置里的 from_name、to_name 是否与 result 一一对应
• 坐标类字段是否已转成 0 到 100 的百分比
• 每一条预测是否都带了 score 和 model_version
• 导入前是否做过任务去重
• 先导入 5 条样例数据并打开界面核对渲染结果

这个清单看着简单，执行到位之后，我几乎没有再因为“预测不见”这类问题返过工。

6. 导入只是起点：预标注如何变成正式标注并回流模型

6.1 标注员打开任务后的实际操作

预标注导入后，标注员的界面跟普通任务不太一样。任务列表里，带预测的任务会显示一个预测标记；点开任务后，预测结果会以“建议”的形式出现，标注员可以一键采用，也可以直接拖拽、修改、删除局部结果。

对文本分类任务，就是看一眼已经选中的标签，不对就换一个；对图像检测任务，就是检查每个框的位置和类别，拖一拖、改一改。整个过程比从零标注轻松得多，这就是预标注的最终目的。

6.2 开启自动采用预测，省掉加载那一步

想再进一步提速，可以在项目设置的 Labeling Interface 里开启 Auto accept annotation suggestions。开启之后，标注员打开任务时，预测结果会自动变成标注草案，省去手动点击“采用预测”这一步。

这个功能适合预测准确率已经很高、标注员主要做微调的场景。如果模型质量不够稳定，或者标注规范有较大调整，我建议先不开这个开关，让标注员自己选择是否采用预测，避免错误预测被不小心提交成正式标注。

6.3 人工提交后的数据归属：predictions 与 annotations 隔离

标注员提交之后，界面上的结果会写入 annotations，与原任务里的 predictions 分开存放。两者互不影响，最终标注数据以 annotations 为准。

这个隔离非常有用：导出数据做模型训练时，你可以只导出 annotations；做模型诊断时，可以同时导出 predictions 和 annotations 做对比。如果当初偷懒把模型结果直接塞进 annotations，现在就没有这份对照数据了。

6.4 从修改记录里找模型短板

我习惯在两批预标注任务完成之后，跑一个简单的差异统计：把每条任务的预测标签和人工最终标签做对比，找出人工修改频率最高的类别。

比如文本情感分类项目，预测是“正面”而人工改成“负面”的样本特别多，那大概率是模型在“讽刺”或“隐喻”表达上存在系统性偏差。把这类样本导出来，挑出有代表性的几百条补充进训练集，下一版模型的线上表现会好很多。

后续再做预标注时，记得更新 model_version，比如从 sentiment_model_v3 改成 sentiment_model_v4。这样两周后再看数据，你还能按版本查历史，对比每一版模型给标注团队节省了多少工作量。

最后说一点我自己的习惯：不管预标注多准，我永远会留着人工审核这个环节，不会让模型预测直接变成正式标注。审核过程虽然要花时间，但它是数据质量的最后一道保险。效率可以靠预标注提上去，质量底线还是得靠流程来守。