数据标注实战:用 Open Marker 跑通从原始文本到审核交付的完整流程
上一篇讨论了 数据标注的原理与价值。这一篇不再停留在概念上,而是结合 Open Marker,走一遍从项目搭建到标注结果交付的实际流程。
一个标注系统是否可用,不能只看有没有项目列表和几个按钮。至少要回答:空项目能不能正常进入?数据能不能导入?标注保存后能不能回读?审核状态是否生效?导出文件里是不是只有应该交付的数据?
本文以 2026 年 11 月 19 日的本地实现与验收为基线,不代表公网已经部署相同版本。
一、先说清楚这次要做什么
这次使用的技术结构是 React 19 + Vite 8 前端,配套 Node.js/Koa 后端与 MongoDB。前后端分别维护,登录和注册复用现有账号服务,标注业务作为独立模块接入。
当前可以完成三类任务:
- 文本多标签分类,例如用户反馈归类。
- 图片矩形框标注,例如目标检测数据制作。
- 文本实体标注,例如标出人名和地点。
它还包括数据导入、任务分配、自动保存、审核返工、抽检、审计记录和标准格式导出。
这里先划清边界:标注平台负责生产和交付数据,不负责自动训练模型。 当前也没有实现视频、音频、3D、像素级分割或完整训练流水线。AI 部分只有接口适配,尚未接入真实模型。
另外,前端工程不包含完整后端。下面的启动步骤面向已经拿到配套后端服务的项目环境;只有前端源码或一个 Vite 模板,并不能独立运行本文全部业务。
二、从脚手架开始,而不是从空文件夹开始
如果是新建一个学习工程,可以先用官方脚手架准备 React 模板:
1 | npm create vite@latest open-marker-lab -- --template react |
这是“另起一个学习目录”的示例,不要在已有 Open Marker 目录中重新初始化。它只会生成基础模板,不会自动生成标注业务。命令形式和 React 模板可参考 Vite 官方指南。
如果使用的是已经实现业务的项目,则进入现有前端仓库根目录,执行:
1 | npm ci |
现有项目应以锁文件恢复依赖,而不是在实战过程中顺手把全部依赖升级到最新版本。本文本地验证使用 Node.js 24;选择其他版本前,要确认满足项目和 Vite 的要求。
脚手架解决的是开发服务器、模块构建和基础工程组织。真正的业务,需要继续拆成可以独立理解的部分。目前前端主要模块如下,路径均相对仓库根目录:
1 | src/ |
这并不是说每个功能必须对应一个文件,而是应避免让“画框”“导出”“权限”“保存状态”都挤进同一段逻辑里。
三、前后端分别负责什么
前端负责把工作过程呈现出来:展示数据、接受选择、编辑标注、提醒保存状态。后端负责验证这次操作是否允许,以及怎样可靠地保存结果。
1 | React 工作台 |
例如,“隐藏审核按钮”只是界面行为;标注员直接调用审核接口时,后端仍要检查角色。类似地,前端对图片格式的提示,也不能替代服务端校验。
为什么项目和样本要分开
当前项目详情提供名称、标签、成员、统计等信息,样本则通过分页接口单独读取:
1 | GET /api/annotation/projects/:id |
这样,打开一个项目不必把全部样本都拉进浏览器。保存一条标注,也不需要重新提交整个项目。
样本有独立的 revision。保存时带上自己读取的版本,后端用样本标识与版本共同匹配更新:如果别人已经修改过同一条数据,就返回冲突,提示用户重新核对,而不是静默覆盖。不同样本之间则不必因为共享一个项目版本而相互冲突。
四、在本地启动配套服务
本地体验采用独立演示数据库,只监听回环地址,不连接业务数据库,也不连接真实模型。前提是本机 MongoDB 已按演示要求运行;不要为了体验而关闭现有业务数据库的认证。
以下命令分别在对应仓库根目录执行,不需要把前端放进后端仓库。
1. 启动配套后端
在提供了演示启动脚本的后端工程中执行:
1 | npm ci --legacy-peer-deps |
这里的 --legacy-peer-deps 是该配套工程的依赖安装方式,不是所有 Node.js 项目都应照搬的默认参数。
后端演示服务监听 127.0.0.1:3110。首次启动准备示例账号和合成项目;后续启动保留已有数据,不重置用户修改。
2. 启动前端体验环境
在现有前端工程中执行:
1 | npm ci |
打开 本地体验入口,可以一键进入,也可以用普通登录表单登录:
1 | 负责人账号:13900001234 |
另有标注员 13900001235 和审核员 13900001236,演示密码相同。这些是专用的本地演示账号,不是公网通用账号。不要把演示服务开放到公网,也不要往其中上传敏感数据。
3. 再验证生产构建
开发模式能运行,不等于构建产物也没有问题。保留演示后端,在前端目录执行以下 PowerShell 命令:
1 | npm run build |
打开 本地构建预览,使用上面的账号手动登录。生产构建不会包含一键体验入口和演示账号信息。
preview 这里只用于本地验收,不应当作公网生产服务器。真正发布时,还要处理静态资源、API 代理、持久化存储、访问控制与备份。
五、实战:做一个用户反馈分类项目
先用很少的数据验证流程,不急着导入几万条。下面的样例用于功能验收,不能据此训练出可靠的情感模型。
第一步:创建项目,先写标注规则
点击“新建项目”,填写:
1 | 项目名称:用户反馈分类实战 |
在“项目设置”中补充标注规范。例如,本练习只处理有明确态度的简单评论:表达满意的标为正向,表达不满的标为负向;遇到混合或无法判断的内容,不强行提交,先由负责人明确规则。
当前文本编辑器支持多标签。“本练习每条只选一个标签”是这次练习的规范,不是平台已经实现了单选约束。 如果实际业务要求严格单选,需要另外补充对应的前后端规则。
项目创建后默认进入数据集页面。切换到“标注任务”,此时应该保留导航并显示“项目还没有数据”和“前往导入数据”。数据为空是一种正常业务状态,不应该导致整页空白。
第二步:导入两条文本
点击“前往导入数据”,再点“导入数据”。数据集名称填写“实战数据”,文本格式选择 TXT,粘贴:
1 | 这款产品很好用。 |
当前导入规则是一行一条数据。若使用 JSONL,等价输入如下:
1 | {"content":"这款产品很好用。"} |
确认导入前检查预览中的可导入数量、重复记录和错误行。当前每批最多 500 条,这不是整个项目只能存 500 条。导入去重也不等于识别所有语义近似句子;近重复数据仍需要额外检查。
导入成功后切换到“标注任务”,应该能看到两条待标注数据。
第三步:标注第一条,并验证保存
选择“这款产品很好用。”,勾选“正向”。可以等待自动保存,也可以点击“保存草稿”。
不要只看按钮有没有响应,至少检查三件事:
- 页面状态是否从“未保存”变成“已保存”。
- 刷新页面、重新打开同一条数据后,标签是否仍然存在。
- 保存失败时,是否保留当前修改,并提供重试或草稿备份入口。
本项目支持会话草稿恢复,但它不是无限期、跨浏览器的备份。重要数据仍应以服务端确认保存为准。
完成核对后点击“提交审核”。此时样本进入待审核状态,标注内容转为只读;审核驳回后可以继续修改。
第四步:审核通过,保留一条未审核数据作对照
进入“审核质检”,选择第一条数据并点击“审核通过”。第二条暂时不处理,用它验证导出是否正确过滤未完成的数据。
快速体验时,负责人默认可以审核自己的结果。这只是为了方便单人跑通流程,不意味着真实团队应该省略独立审核。
若要体验多人协作,可在“项目成员”中添加已注册的标注员和审核员,再把任务分配给标注员。在项目设置开启“禁止标注者审核自己的结果”后,应由另一位有审核权限的成员审核。
这里还有一个权限边界:标注员只能修改分配给自己的任务,但当前项目成员可以查看项目数据。任务分配并不是数据可见性隔离;对敏感数据有更细要求时,需要继续设计权限。
第五步:生成快照,检查真正下载到的文件
进入“数据导出”,选择 JSONL,点击“生成导出快照”,再点击“下载快照”。
此时应只导出第一条已通过的数据,不应包含第二条未审核数据。实际文件还包含样本标识、标签定义和版本等字段。下面只展示其中的核心字段,不是完整格式模板:
1 | { |
还要注意,导出行中的顶层 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 | { |
这里采用左闭右开的区间: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 | npm test |
浏览器验收使用 Python Playwright,包含文本闭环、图片、协作、实体和 AI 接口适配等测试。运行它们之前,还需要启动隔离测试后端并配置测试环境,具体命令见 项目 README。不要把测试脚本的地址改成真实业务环境来“顺便验收”。
本次本地记录中,5 组前端单测、7 组浏览器测试及配套后端验证通过;随后又在生产构建预览中复验了文本闭环和异常响应恢复。这证明的是所覆盖的本地行为,不等于已经完成公网发布、容量压测或真实模型效果评估。
写在最后
搭建数据标注平台,最值得先完成的不是菜单数量,而是一条从原始数据到审核交付的可靠路径。
Open Marker 的实践顺序是:用标准脚手架建立前端基础,接入现有账号体系,拆分项目与样本,逐步补上编辑、保存、审核和导出,再用真实数据读写和故障测试验证它们。
平台跑通之后,下一阶段才是围绕具体业务完善标注规范、补充代表性样本、接入可信模型,并在独立评测中验证效果。数据标注系统负责把这些工作组织好,但不能替代对数据质量的判断。
数据标注实战:用 Open Marker 跑通从原始文本到审核交付的完整流程
https://hjb.leheavengame.com/2026/11/10/数据标注实战:用-Open-Marker-跑通从原始文本到审核交付的完整流程/

