标注数据是 AI 项目里最能熬人的环节。我之前做一个实体识别项目，三千条样本标了两周，全程盯着屏幕拖鼠标，眼睛快瞎掉不说，中间还因为标准不统一返工了两轮。后来尝试让大模型在 Label Studio 里做预标注，配合 CubeStudio 内置的 LLM 标注后端接入 ML Backend，流程直接变了样：模型先标一遍，人只负责校对，原本两周的活压缩到三天。这篇就把整个实操过程拆开讲清楚，覆盖文本分类、NER、翻译和图片描述四类任务，重点聊零部署接入 ML Backend 到底怎么落地，以及我踩过哪些坑。
1. 为什么预标注是刚需：先想清楚再动手
1.1 标注成本的真相
很多人低估了数据标注的时间成本。拿 NER 来说，一个熟练标注员标注一千条文本，如果实体密度高，平均每条要花 30 到 60 秒，算下来两三千条样本就是一整天起步。更麻烦的是标注标准的一致性，两个人标同样的内容，边界切法可能完全不同，回头还得花时间对齐口径。
预标注解决的就是这个“从零到一”的问题。让大模型先基于你写好的规则和示例输出一轮结果，标注员看到的是带高亮、带标签的候选结果，只需要判断“对”或“错”，错了就拖一下边界。这个模式在 Label Studio 里叫 prediction，工程师叫它 pre-labeling，本质上就是在任务打开之前，把模型推理结果填进标注界面里。
成本下降的幅度很直观：纯手工标注一条 NER 可能要 40 秒，预标注后校对普遍能压到 15 秒以内，熟练之后更快。而且模型输出的标签风格是稳定的，只要 prompt 写得好，两个人校对的口径差异也会小很多。
1.2 ML Backend 到底在 Label Studio 里怎么工作
Label Studio 本身不做推理。它通过 ML Backend 机制连接外部模型服务，官方实现方式是自己写一个 HTTP 服务，暴露几个特定端点，然后把这个服务注册进项目里。
整个请求链路大致是这样：标注界面里点击“自动标注”（Auto Label）按钮，Label Studio 会把当前任务的数据打包成一个 HTTP 请求，推送到你配置好的 ML Backend 地址；后端收到请求后调用推理逻辑，把结果按照 Label Studio 规定的 JSON 结构返回；前端拿到结果后渲染成高亮标签、下拉选项或者文本框内容。
这个 JSON 结构就是关键。Label Studio 要求返回的格式大体上是：
{ "predictions": [ { "result": [ { "from_name": "label", "to_name": "text", "type": "choices", "value": {"choices": ["正样本"]} } ], "score": 0.98 } ] }其中from_name和to_name必须跟你标注配置里的命名完全一致，否则前端找不到对应的控件，结果就渲染不出来。很多人第一次接入就死在这里，后面我会单独讲。
1.3 为什么选 CubeStudio 而不是自己写 FastAPI 后端
自己写 ML Backend 不是不行，我最早就是这么干的。FastAPI 写两个端点，把 OpenAI SDK 或国产模型 SDK 接进来，处理完模型输出再组装 JSON，总共两百多行代码。听起来不复杂，但实际上非常烦。
烦在哪儿？第一，模型输出并不是每次都规规矩矩给 JSON，你得做容错和重试；第二，不同任务类型要写不同的推理函数，文本分类一套逻辑，NER 一套逻辑，图片描述又要处理多模态，代码会越来越臃肿；第三，部署环境要照顾，有些模型服务需要配置代理或者特殊环境变量；第四，Label Studio 升级后接口可能有细微变化，你得跟着调。
CubeStudio 内置的 LLM 标注后端，就是把这一层封装好了。它以应用模板的形式提供，你在 CubeStudio 里填模型配置、写 prompt、定义输出格式，它直接把 ML Backend 的地址给你，Label Studio 侧只管注册这个地址。零部署的意思是：你不需要自己起服务、写代码、管运维，配置完就能用。
这对我这种“能少写一行代码就少写一行”的人来说，属于刚需。
2. 零部署接入：把 CubeStudio 的 LLM 标注后端接到 Label Studio
2.1 环境准备：Label Studio 最小化部署
接入 CubeStudio 之前，先保证 Label Studio 自己能跑起来。有两个常见方式，我推荐 Docker 方式，干净且不污染本机环境。
docker run -it -p 8080:80 \ -v $(pwd)/label-studio-data:/label-studio/data \ -e LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT=/label-studio/data \ -e LABEL_STUDIO_LOCAL_FILES_SERVING_ENABLED=true \ heartexlabs/label-studio:latest如果用本地图片做图片描述任务，后面两个环境变量必须配，否则 Label Studio 往外部传图片路径时可能带不上。不想用 Docker 的话，pip 安装也可以：
pip install label-studio label-studio start默认会在 localhost:8080 启动，注册管理员账号后先创建项目，标注配置先随便填一个，后面会替换。
2.2 CubeStudio 侧配置：模型、Prompt、输出格式三要素
进入 CubeStudio 控制台，找到 LLM 标注后端这个应用模板，创建后会进入一个配置界面，核心就三块：模型配置、Prompt 模板、输出格式约定。
模型配置就是填服务商相关的参数。以 OpenAI 兼容协议为例，一般要填四个东西：API Base、API Key、模型名称、Token 上限。比如用 DeepSeek，API Base 填https://api.deepseek.com/v1，模型填deepseek-chat；用通义千问，Base 填对应的 dashscope 网关地址，模型填qwen-plus。如果做图片描述，这里需要选带视觉能力的多模态模型，比如qwen-vl-plus或者支持图像输入的 GPT-4o 系列。
Prompt 模板是决定标注质量的核心。CubeStudio 里会有一个变量占位符，通常标注任务的原始内容会以{{text}}或{{image_url}}的形式注入。我的经验是，prompt 里必须包含三部分：角色设定、输出格式约束、示例（可选）。其中输出格式约束必须用“只输出 JSON”这样的强措辞，并且明确字段结构。
输出格式约定也很重要。CubeStudio 通常提供一个 JSON Schema 编辑框，你定义好字段名和类型，比如：
{ "label": "string", "confidence": "number" }这之后 CubeStudio 会把模型输出往这个结构上靠，并且做一定的容错处理。凡是模型输出了多余的话，或者 JSON 外面包了 markdown 代码块标记，这个内置解析层会自动清洗。这一点比我自写的代码稳定得多。
配置完保存，CubeStudio 会生成一个 ML Backend URL，形如https://xxx.cubestudio.app/ml-backend/predict。记下它。
2.3 在 Label Studio 项目里注册 ML Backend 的注意事项
打开 Label Studio 项目，进入 Settings，选 Machine Learning，点击 Add Model。
在这里填入刚才那个 URL。Label Studio 会自动探测一些信息，比如模型名称和支持的类型。几个容易看漏的地方：
一是 URL 端口问题。如果 CubeStudio 给的地址是 https 的，就直接用，不要在本地再包一层反代，除非你明确知道自己在做什么。
二是认证。有些 CubeStudio 实例会在 ML Backend URL 后面附加一个 access token 查询参数，Label Studio 能识别 Query String 里的 token，直接整段粘贴即可。
三是测试时机。建议先创建任务再注册后端，然后用一个与真实数据格式相同的任务点“预标注”测试，别拿空项目测，容易误判配置失败。
注册成功后，打开任意一个任务，点击右上角的“Auto-Label”图标，等待几秒，就能看到预标注结果被填进界面。
3. 四大场景实操：从文本分类到图片描述
3.1 文本分类：最简单的预标注
文本分类属于最容易接通的任务，因为标签结果是离散的，不需要处理位置偏移，LLM 的输出解析也不容易出错。
标注界面的配置可以选 Choices 控件：
<View> <Text name="text" value="$text"/> <Choices name="label" toName="text" choice="single"> <Choice value="正样本"/> <Choice value="负样本"/> </Choices> </View>在 CubeStudio 的 prompt 模板里，需要把候选标签穷举清楚。这里有个方法论级别的细节：不要只给标签名，还要给标签定义。以“正样本”为例，如果只写“正样本/负样本”，模型很容易把模糊样本分错；写了定义之后，准确率会明显提升。
你是文本分类助手。请判断下面文本的类别，只输出 JSON。 候选类别及定义： - 正样本：包含明确购买意向的咨询或询价信息 - 负样本：不含购买意向的闲聊、广告或无关内容 文本内容： {{text}} 输出格式：{"label": "正样本或负样本"}保存后回到 Label Studio，在任务列表选中几条文本，点 Auto-Label。成功的话，Choices 控件会自动选中对应的选项，并且标注区域会有高亮提示。
文本分类最容易翻车的地方有两个。一个是在 label 字段里输出了一个未被定义的类别，比如把“正样本”写成“正向样本”，这在 CubeStudio 侧默认情况下会原样返回，Label Studio 里 Choices 没有这个值就会忽略它，看起来就是“没有预标注”。遇到这种情况，建议在 CubeStudio 的配置里开启“标签值映射”或者在后端做一次字符串匹配，把模型输出映射到最接近的已定义标签。另一个是模型对多标签任务不够敏感，如果建模时定义的是 single 选择，但模型输出数组，这时 Label Studio 只会取第一个值，需要把 prompt 明确写成“只能选一个”。
我自己的经验是：文本分类任务用带温度 0 的模型配置，在 CubeStudio 里把采样温度调到最低，分类结果的稳定性会好非常多，因为这类任务要的是确定性而不是创造力。
3.2 NER 实体识别：位置偏移是最大的坑
NER 的预标注比文本分类复杂一个量级，核心难点在于实体起止位置的定位。LLM 读的是 token，它返回的 start 和 end 是以字符为单位的偏移量，这个偏移量经常出错，差一个标点或者空格就会把高亮位置渲染错。
Label Studio 的 Span 控件标准配置大概是这样：
<View> <Text name="text" value="$text"/> <Labels name="entity" toName="text"> <Label value="人名"/> <Label value="组织"/> <Label value="地点"/> </Labels> </View>CubeStudio 侧的 prompt 模板，我建议这样写：
你是命名实体识别助手。从文本中抽取指定类型的实体。 实体类型：人名、组织、地点 要求： 1. 实体必须完整出现在原文中 2. 返回 JSON 数组，不要返回偏移量，由系统自行定位 输出格式： {"entities": [{"text": "实体原文", "label": "人名"}]}注意这里的思路：明确要求模型不要返回 start 和 end，只返回实体文本片段。CubeStudio 的 NER 模板会在拿到text字段后，在当前输入文本里做精确匹配，从而计算偏移量。只要文本片段没有歧义，这种方式基本不会定位错。
为什么我强烈建议这样干？因为模型算偏移量本质上靠“数数”，一旦文本前面有换行、特殊符号，它数的位置就会偏一位两位。而文本匹配是朴素字符串搜索，语言模型再差，给出的实体片段通常是原文里的正确子串。真实场景里，实体片段歧义的概率远小于偏移量出错概率。
一旦涉及多实体类型，配一个 few-shot 示例能显著提升效果。在 prompt 模板里加两三条样例，告诉模型“人名指的是具体人的姓名，‘张三’算，‘人员’不算”。没有示例时，模型对“地点”的边界把握很模糊，可能把“位于杭州的公司”整个抽成地点。
3.3 翻译：让 LLM 输出多语言对照
翻译预标注的界面跟上面两类任务都不一样。翻译场景通常需要同时展示原文和目标译文，最直接的做法是在同一个 View 里放一个原文只读区和一个译文编辑区：
<View> <Text name="source" value="$source_text"/> <TextArea name="translation" toName="source" editable="true"/> </View>CubeStudio 里的 prompt 设定为翻译任务，让模型把{{source_text}}翻译成目标语言，输出 JSON：
{"translation": "译文"}拿到结果后，CubeStudio 的翻译标注模板会把translation的值填到TextArea类型的 result 里。标注员打开任务能看到模型给出的整段译文，直接校对修改即可。
翻译任务这个场景，预标注最大的价值不在于省去打字，而在于统一术语。如果同时有一批文本里反复出现产品名、地名、人名，你可以在 prompt 里加一个术语表：
术语表： - OpenBayes -> 开放贝斯 - AugNet -> 增强网络 翻译时必须使用术语表中的译法。加上术语表之后，模型输出的译文在关键术语上是稳定的，校对员工不需要反复跟规则较劲。
有个需要注意的点：翻译任务不要用文本分类那种极低温度。翻译本身有多种合法表达，温度极低时译文可能过于直译，反而增加校对工作量。我把温度设置在 0.3 左右，译文的自然度和稳定性比较平衡。
3.4 图片描述：多模态模型的接入要点
图片描述这个场景依赖多模态模型，也是 CubeStudio LLM 标注后端模板里相对特殊的一种。
Label Studio 侧，图片展示用的是 Image 控件，描述输出用 TextArea：
<View> <Image name="image" value="$image"/> <TextArea name="caption" toName="image" editable="true"/> </View>图片数据本身有两种存在形式。一种是 URL 外链，CubeStudio 直接把 URL 传给多模态模型的 image 参数；另一种是本地文件，需要 Label Studio 开启本地文件服务（就是你前面配的那两个环境变量），并且任务里的图片要引用本地文件路径。
这里有一个我在项目里踩过的暗坑：Label Studio 默认把本地文件路径映射成/data/upload/...这样的内部路径。如果 CubeStudio 拿这个路径去请求图片，会得到一个访问不到资源的错误。解决方式有二：一是在创建任务时，直接把图片字段写成绝对路径；二是在 Label Studio 设置里开启本地文件服务，并确认 CubeStudio 模板支持从上传目录读取图片。我建议第一种，简单粗暴但可靠。
prompt 模板长这样：
你是图片描述专家。描述图片中的核心内容。 要求：用 1-2 句中文描述，突出主体、动作、场景。 输出格式：{"description": "对图片的描述"}多模态模型偶尔会返回“图片无法访问”之类的内容而不是真实描述，遇到这种情况要查一下图片 URL 的可达性，而不是急着改 prompt。另外，图片描述对模型的视觉能力要求比较高，用纯文本模型去接这个任务肯定是不可行的，选型时注意选带视觉输入的模型。
4. 常见问题与排查技巧实录
4.1 LLM 返回格式不对，解析器“翻车”
这是接入 LLM 标注后端后最常遇到的问题。模型在生成 JSON 时，经常会在前后加一些解释性文字，比如“以下是识别结果：”或者把 JSON 包在 ```json 代码块里。CubeStudio 内置解析层通常能自动清理，但如果遇到清理不掉的情况，多半是模型输出的 JSON 本身就坏了，字段缺失、括号不匹配、字符串没转义。
排查路径很清楚：先在 CubeStudio 的后端日志或运行记录里找到原始模型输出，确认格式是不是合法的 JSON。如果是没包好 markdown 代码块，就在 prompt 里强制指定“不要输出任何解释，不要 markdown 标记”；如果是字段缺失，检查你对齐的 JSON Schema 和 prompt 里给出的格式是否一致。一个我自己常用的技巧是在 prompt 末尾加一句话：“只输出一个 JSON 对象，不要输出其他任何内容。”很多时候就靠这句话救回来。
4.2 请求超时与 token 限制
LLM 推理速度比传统模型慢不少，短文本分类可能只要一两秒，长文本 NER 或者图片描述可能要五到十秒。Label Studio 默认的 ML Backend 超时时间是 10 秒左右，如果超时，界面会提示“Request to ML Backend failed”。
解决方案有三个。第一，在 Label Studio 的 ML Backend 设置里调整超时参数，如果是 Docker 部署，有的版本支持在环境变量里配置超时时间；第二，把长文本切成更短的片段，分批请求；第三，选择推理速度更快的模型。文本分类用轻量模型足够，没必要上大参数模型。
Token 限制是另一道坎。输入文本一旦超过模型上下文长度，请求直接报错。这种问题大概率出现在 NER 长文档和翻译长段落场景。CubeStudio 模板里通常有“文本截断”或者“自动切片”选项，按需要开启。如果不想切片，也可以让 prompt 输出时用流式方式，但 ML Backend 请求一般是同步的，流式支持有限，所以切片是最稳的办法。
4.3 标签不匹配、实体错位、API 报错速查表
把实操中遇到的高频问题整理成一个速查表，对应现象、原因和解决方案，方便直接对照排查。
| 现象 | 可能原因 | 解决方式 |
|---|---|---|
| 预标注结果没有渲染到界面上 | from_name/to_name与标注配置不一致 | 检查 result 里的名称，和 XML 配置中的 name 对齐 |
| 分类结果消失但日志里正常 | 模型输出了未定义的标签值 | 开启 CubeStudio 标签映射，或 prompt 里更严格约束候选集合 |
| NER 实体高亮位置明显偏移 | 模型返回的 start/end 有误 | 改用实体文本回填匹配，不信任模型计算的偏移量 |
| 翻译结果没有填充到编辑器 | TextArea 的 value 类型传成了数组 | 让模型输出字符串类型，后端再透传 |
| 图片描述返回“无法访问图片” | 本地图片路径未开启映射 | 使用绝对路径，或确认本地文件服务已开启 |
| LLM 请求被拒绝，提示 schema 或 tool payload 异常 | 传给模型的工具定义与模型服务不兼容 | 换用 OpenAPI 兼容的模型网关，或关闭工具调用模式 |
这里重点说下最后一种情况。如果你用的模型 API 对 tool call 的 JSON Schema 要求特别严格，而 CubeStudio 默认开启了结构化输出，会出现类似provider rejected the request schema or tool payload的报错。我的经验是，遇到这种报错先看 CubeStudio 是不是把输出格式定义直接作为 tool 传给了模型。如果是，可以把这个模型切换到另一个兼容性更好的服务商，或者关闭强制 schema 模式，靠 prompt 约束输出格式。
4.4 关于“稳定”这件事的长期心得
预标注的稳定性从来不是由单一环节决定的，而是由模型、prompt、解析层、Label Studio 配置四个环节共同决定的。我见过很多人只调 prompt，忽略了模型选型，效果始终不稳定。以我的观察，中文文本分类和 NER 任务，国产模型和 OpenAI 系列模型的表现差距已经很小，优先选延迟低的即可；翻译任务则要看目标语言对，多尝试几个模型再定。
另外两个操作细节：一是 pre-annotation 不是一锤子买卖。第一批任务预标注完成后，建议用“预标注结果 + 人工修正”的方式形成一批高质量数据，再把这批数据作为 few-shot 示例反哺给 prompt，第二轮的效果会明显提升。二是定期检查标注员对预标注结果的修改，如果某类标签经常被人工改掉，说明模型在这个类别上的表现不行，及时在 prompt 里加该类的正反例。
我自己现在的固定工作流是：CubeStudio 里配好任务模板，Label Studio 底部队列批量跑预标注，标注员只负责校对和边缘情况处理。遇到模型明显兜不住的类别，就把它从自动标注范围里摘出来，改人工标注。这种混合模式在多个项目里跑下来，整体效率比全人工标注能提升 60% 到 80%，而且标注标准更统一，质检成本也降下来了。
最后分享一个算不上技巧但很实用的习惯：每次修改 prompt 后，先在 CubeStudio 里用三条真实样本做自测，确认输出格式没问题，再去 Label Studio 里跑批量预标注。这十几秒的检查能避免一整个批次的返工。预标注只有真正融进生产流程，和人工校对、质检、模型迭代连成一条线，才能发挥出它最大的价值。
