数据标注实战:用 Open Marker 跑通从原始文本到审核交付的完整流程

上一篇讨论了 数据标注的原理与价值。这一篇不再停留在概念上,而是结合 Open Marker,走一遍从项目搭建到标注结果交付的实际流程。

一个标注系统是否可用,不能只看有没有项目列表和几个按钮。至少要回答:空项目能不能正常进入?数据能不能导入?标注保存后能不能回读?审核状态是否生效?导出文件里是不是只有应该交付的数据?

本文以 2026 年 11 月 19 日的本地实现与验收为基线,不代表公网已经部署相同版本。

一、先说清楚这次要做什么

这次使用的技术结构是 React 19 + Vite 8 前端,配套 Node.js/Koa 后端与 MongoDB。前后端分别维护,登录和注册复用现有账号服务,标注业务作为独立模块接入。

当前可以完成三类任务:

  • 文本多标签分类,例如用户反馈归类。
  • 图片矩形框标注,例如目标检测数据制作。
  • 文本实体标注,例如标出人名和地点。

它还包括数据导入、任务分配、自动保存、审核返工、抽检、审计记录和标准格式导出。

这里先划清边界:标注平台负责生产和交付数据,不负责自动训练模型。 当前也没有实现视频、音频、3D、像素级分割或完整训练流水线。AI 部分只有接口适配,尚未接入真实模型。

另外,前端工程不包含完整后端。下面的启动步骤面向已经拿到配套后端服务的项目环境;只有前端源码或一个 Vite 模板,并不能独立运行本文全部业务。

二、从脚手架开始,而不是从空文件夹开始

如果是新建一个学习工程,可以先用官方脚手架准备 React 模板:

1
2
3
4
npm create vite@latest open-marker-lab -- --template react
cd open-marker-lab
npm install
npm run dev

这是“另起一个学习目录”的示例,不要在已有 Open Marker 目录中重新初始化。它只会生成基础模板,不会自动生成标注业务。命令形式和 React 模板可参考 Vite 官方指南。

如果使用的是已经实现业务的项目,则进入现有前端仓库根目录,执行:

1
npm ci

现有项目应以锁文件恢复依赖,而不是在实战过程中顺手把全部依赖升级到最新版本。本文本地验证使用 Node.js 24;选择其他版本前,要确认满足项目和 Vite 的要求。

脚手架解决的是开发服务器、模块构建和基础工程组织。真正的业务,需要继续拆成可以独立理解的部分。目前前端主要模块如下,路径均相对仓库根目录:

1
2
3
4
5
6
7
8
9
src/
├── App.jsx 项目、数据集、任务与审核页面
├── Auth.jsx 登录、注册及本地体验入口
├── Editor.jsx 标注编辑、保存与草稿管理
├── ImageCanvas.jsx 图片绘框与画布交互
├── TextEntities.jsx 文本实体选区
├── ExportPanel.jsx 导出快照与下载
├── annotationData.js 项目和样本响应校验
└── ErrorBoundary.jsx 渲染异常兜底

这并不是说每个功能必须对应一个文件,而是应避免让“画框”“导出”“权限”“保存状态”都挤进同一段逻辑里。

三、前后端分别负责什么

前端负责把工作过程呈现出来:展示数据、接受选择、编辑标注、提醒保存状态。后端负责验证这次操作是否允许,以及怎样可靠地保存结果。

1
2
3
4
5
React 工作台
→ /api 请求
→ 后端身份验证、项目权限、输入校验
├── MongoDB:项目、数据集、样本、记录与任务元数据
└── 受控文件目录:托管图片、导出文件

例如,“隐藏审核按钮”只是界面行为;标注员直接调用审核接口时,后端仍要检查角色。类似地,前端对图片格式的提示,也不能替代服务端校验。

为什么项目和样本要分开

当前项目详情提供名称、标签、成员、统计等信息,样本则通过分页接口单独读取:

1
2
GET /api/annotation/projects/:id
GET /api/annotation/projects/:id/samples?page=1

这样,打开一个项目不必把全部样本都拉进浏览器。保存一条标注,也不需要重新提交整个项目。

样本有独立的 revision。保存时带上自己读取的版本,后端用样本标识与版本共同匹配更新:如果别人已经修改过同一条数据,就返回冲突,提示用户重新核对,而不是静默覆盖。不同样本之间则不必因为共享一个项目版本而相互冲突。

四、在本地启动配套服务

本地体验采用独立演示数据库,只监听回环地址,不连接业务数据库,也不连接真实模型。前提是本机 MongoDB 已按演示要求运行;不要为了体验而关闭现有业务数据库的认证。

以下命令分别在对应仓库根目录执行,不需要把前端放进后端仓库。

1. 启动配套后端

在提供了演示启动脚本的后端工程中执行:

1
2
npm ci --legacy-peer-deps
npm run annotation:demo

这里的 --legacy-peer-deps 是该配套工程的依赖安装方式,不是所有 Node.js 项目都应照搬的默认参数。

后端演示服务监听 127.0.0.1:3110。首次启动准备示例账号和合成项目;后续启动保留已有数据,不重置用户修改。

2. 启动前端体验环境

在现有前端工程中执行:

1
2
npm ci
npm run demo

打开 本地体验入口,可以一键进入,也可以用普通登录表单登录:

1
2
负责人账号:13900001234
密码:MarkerDemo123!

另有标注员 13900001235 和审核员 13900001236,演示密码相同。这些是专用的本地演示账号,不是公网通用账号。不要把演示服务开放到公网,也不要往其中上传敏感数据。

3. 再验证生产构建

开发模式能运行,不等于构建产物也没有问题。保留演示后端,在前端目录执行以下 PowerShell 命令:

1
2
3
npm run build
$env:API_PROXY_TARGET = 'http://127.0.0.1:3110'
npm run preview -- --host 127.0.0.1 --port 5190 --strictPort

打开 本地构建预览,使用上面的账号手动登录。生产构建不会包含一键体验入口和演示账号信息。

preview 这里只用于本地验收,不应当作公网生产服务器。真正发布时,还要处理静态资源、API 代理、持久化存储、访问控制与备份。

五、实战:做一个用户反馈分类项目

先用很少的数据验证流程,不急着导入几万条。下面的样例用于功能验收,不能据此训练出可靠的情感模型。

第一步:创建项目,先写标注规则

点击“新建项目”,填写:

1
2
3
项目名称:用户反馈分类实战
项目类型:文本分类
标签集:正向,负向

在“项目设置”中补充标注规范。例如,本练习只处理有明确态度的简单评论:表达满意的标为正向,表达不满的标为负向;遇到混合或无法判断的内容,不强行提交,先由负责人明确规则。

当前文本编辑器支持多标签。“本练习每条只选一个标签”是这次练习的规范,不是平台已经实现了单选约束。 如果实际业务要求严格单选,需要另外补充对应的前后端规则。

项目创建后默认进入数据集页面。切换到“标注任务”,此时应该保留导航并显示“项目还没有数据”和“前往导入数据”。数据为空是一种正常业务状态,不应该导致整页空白。

第二步:导入两条文本

点击“前往导入数据”,再点“导入数据”。数据集名称填写“实战数据”,文本格式选择 TXT,粘贴:

1
2
这款产品很好用。
上传一直失败,体验不好。

当前导入规则是一行一条数据。若使用 JSONL,等价输入如下:

1
2
{"content":"这款产品很好用。"}
{"content":"上传一直失败,体验不好。"}

确认导入前检查预览中的可导入数量、重复记录和错误行。当前每批最多 500 条,这不是整个项目只能存 500 条。导入去重也不等于识别所有语义近似句子;近重复数据仍需要额外检查。

导入成功后切换到“标注任务”,应该能看到两条待标注数据。

第三步:标注第一条,并验证保存

选择“这款产品很好用。”,勾选“正向”。可以等待自动保存,也可以点击“保存草稿”。

不要只看按钮有没有响应,至少检查三件事:

  1. 页面状态是否从“未保存”变成“已保存”。
  2. 刷新页面、重新打开同一条数据后,标签是否仍然存在。
  3. 保存失败时,是否保留当前修改,并提供重试或草稿备份入口。

本项目支持会话草稿恢复,但它不是无限期、跨浏览器的备份。重要数据仍应以服务端确认保存为准。

完成核对后点击“提交审核”。此时样本进入待审核状态,标注内容转为只读;审核驳回后可以继续修改。

第四步:审核通过,保留一条未审核数据作对照

进入“审核质检”,选择第一条数据并点击“审核通过”。第二条暂时不处理,用它验证导出是否正确过滤未完成的数据。

快速体验时,负责人默认可以审核自己的结果。这只是为了方便单人跑通流程,不意味着真实团队应该省略独立审核。

若要体验多人协作,可在“项目成员”中添加已注册的标注员和审核员,再把任务分配给标注员。在项目设置开启“禁止标注者审核自己的结果”后,应由另一位有审核权限的成员审核。

这里还有一个权限边界:标注员只能修改分配给自己的任务,但当前项目成员可以查看项目数据。任务分配并不是数据可见性隔离;对敏感数据有更细要求时,需要继续设计权限。

第五步:生成快照,检查真正下载到的文件

进入“数据导出”,选择 JSONL,点击“生成导出快照”,再点击“下载快照”。

此时应只导出第一条已通过的数据,不应包含第二条未审核数据。实际文件还包含样本标识、标签定义和版本等字段。下面只展示其中的核心字段,不是完整格式模板:

1
2
3
4
5
6
7
8
{
"dataset": "实战数据",
"content": "这款产品很好用。",
"type": "text",
"annotation": {
"labels": ["正向"]
}
}

还要注意,导出行中的顶层 labels 是项目标签定义,真正属于该条样本的标签在 annotation.labels 中。编写后续训练转换脚本时,不要把二者混为一谈。

快照用于重复下载同一份交付结果,不等于可以回滚整个数据集。也不要直接把平台导出文件当成所有模型都能使用的训练输入:不同训练程序还需要各自的字段转换、数据划分和校验。

到这里,完成的是一条真实的标注交付流程,而不是一次模型训练实验。

六、把同一套流程扩展到图片和实体标注

图片:不仅要有类别,还要有位置

创建图片项目后,可以上传 PNG/JPEG,再绘制矩形框、选择类别、调整位置与大小,最后走提交和审核流程。当前单张图片上限为 5 MB,并校验图片尺寸。

内部框坐标采用相对图片宽高的比例。假设一张图片宽 1000、高 500,目标框左上角是 (100, 50),框宽 200、高 100,则内部表示为:

1
{"label":"车辆","x":0.1,"y":0.1,"width":0.2,"height":0.2}

导出时,COCO 使用像素框 [100, 50, 200, 100];YOLO 使用归一化中心点与宽高 (0.2, 0.2, 0.2, 0.2),并配上类别编号。这也是为什么必须保存原图尺寸,而不能拿浏览器里缩放后的显示尺寸当作依据。

当前实现会在 COCO/YOLO 的 ZIP 中打包托管原图;外链图片不会由服务端自动抓取,需要按导出清单自行准备。即使生成了 ZIP,训练前仍要自行检查图片是否齐全、类别映射是否正确,并完成合理的数据划分。

实体:不仅要有类别,还要有文本范围

创建实体标注项目,标签设为“人物、地点”。对于“张三在北京工作。”,可以标记:

1
2
3
4
5
6
7
{
"entities": [
{"start":0,"end":2,"text":"张三","label":"人物"},
{"start":3,"end":5,"text":"北京","label":"地点"}
],
"empty": false
}

这里采用左闭右开的区间:start 包含,end 不包含。当前项目按 JavaScript 的 UTF-16 下标记录,遇到 emoji 时,不一定能把一个视觉字符当作一个下标单位。导入其他语言的训练程序时,要确认它期待的是 UTF-16 偏移、Unicode 码点位置,还是分词后的 token 位置。

当前实体标注不支持重叠或嵌套实体。需要“一个机构名里再标地点”这样的规则时,不能直接假设现有编辑器已经支持。

七、一次白屏问题带来的工程教训

这个项目曾出现过一个很典型的问题:总览页能打开,一进入项目,整个页面却变成空白。

最容易产生的误解是“没有数据,所以没显示东西”。实际原因不是业务上的空数据,而是旧前端仍在读取:

1
project.samples.find((sample) => sample.id === selected)

新版后端已经把项目详情与样本列表拆开,详情里不再包含 samples。旧代码拿到项目对象后访问了不存在的数组,触发渲染异常。

这个问题提醒我们,至少要同时解决三层问题。

第一层是配套部署。 新后端和旧静态页面不能因为“都能启动”就被视为兼容。发布后要确认实际加载的构建版本,并复验真实接口。

第二层是数据边界。 项目详情省略 samples 是合法协议,前端应从分页接口取数据;分页接口缺失必需的 items,却是异常。不能把所有错误都写成 value || [],否则“服务坏了”会被伪装成“项目没有数据”。当前的响应校验模块 src/annotationData.js 就是在进入页面状态前区分这两类情况。

第三层是渲染兜底。 局部组件出错时,尽量保留导航和恢复入口;根组件出错时,也应该有能重新打开工作区的页面。本项目通过错误边界组件 src/ErrorBoundary.jsx 处理这类失败。错误边界主要处理子组件的渲染错误,不能代替异步请求和事件处理中的异常捕获,具体边界见 React 官方说明。

修复后,真正的空项目显示导入引导;任务请求失败显示重试;组件渲染失败显示恢复页。三种状态有不同的处理方式,不再统一变成一块空白。

八、怎样证明平台真的能用

“页面看起来正常”只是检查的一部分。对于标注平台,至少需要验证数据最终是否落到了正确的位置,并且经过了正确的流程。

这次本地闭环验收检查了:

环节 检查内容
空项目 保留导航,显示暂无数据和导入入口
导入 数据真实写入,任务页能读取
保存 刷新后标注仍然存在
并发 旧版本保存被拒绝,当前草稿保留
审核 提交、通过、驳回对应的权限与状态生效
导出 只包含已通过样本,内容和标签正确
重复下载 同一快照的文件内容一致
故障恢复 异常数据、断网、过期登录和渲染错误不再直接白屏

在前端仓库可以先运行:

1
2
3
npm test
npm run lint
npm run build

浏览器验收使用 Python Playwright,包含文本闭环、图片、协作、实体和 AI 接口适配等测试。运行它们之前,还需要启动隔离测试后端并配置测试环境,具体命令见 项目 README。不要把测试脚本的地址改成真实业务环境来“顺便验收”。

本次本地记录中,5 组前端单测、7 组浏览器测试及配套后端验证通过;随后又在生产构建预览中复验了文本闭环和异常响应恢复。这证明的是所覆盖的本地行为,不等于已经完成公网发布、容量压测或真实模型效果评估。

写在最后

搭建数据标注平台,最值得先完成的不是菜单数量,而是一条从原始数据到审核交付的可靠路径。

Open Marker 的实践顺序是:用标准脚手架建立前端基础,接入现有账号体系,拆分项目与样本,逐步补上编辑、保存、审核和导出,再用真实数据读写和故障测试验证它们。

平台跑通之后,下一阶段才是围绕具体业务完善标注规范、补充代表性样本、接入可信模型,并在独立评测中验证效果。数据标注系统负责把这些工作组织好,但不能替代对数据质量的判断。

数据标注实战:用 Open Marker 跑通从原始文本到审核交付的完整流程

https://hjb.leheavengame.com/2026/11/10/数据标注实战:用-Open-Marker-跑通从原始文本到审核交付的完整流程/

作者

hujinbin

发布于

2026-11-10

更新于

2026-11-21

许可协议

评论