从原始文本到训练数据集：doccano 文本标注实战指南

【免费下载链接】doccanoOpen source annotation tool for machine learning practitioners.项目地址: https://gitcode.com/gh_mirrors/do/doccano

手里有一批原始文本，要人工标注成命名实体识别（NER）或情感分析的训练数据，手动改 JSON 文件既慢又容易出错？doccano 是一款面向机器学习从业者的开源文本标注工具，把"建项目、导数据、划标签、导格式"整条链路搬进浏览器，支持多人协作、自动标注和 RESTful API 集成，几个小时就能攒出一个可训练的数据集。

先想清楚：你的任务属于哪种标注类型

标注效率的第一道分水岭不在工具，而在任务定义。doccano 的项目类型直接决定了标注界面长什么样、数据能导出成什么格式，所以这一步要在建项目之前定下来：

选错类型的代价是数据得重标一遍，所以可以先用文档里的示例数据（backend/data_import/pipeline/examples/）跑一个最小项目感受一下界面。

五分钟把 doccano 跑起来

安装方式按环境复杂度三选一，多数个人场景用 pip 就够了。

pip（Python 3.8+），默认用 SQLite 存储，零依赖：

pip install doccano doccano init # 初始化数据库 doccano createuser --username admin --password pass # 创建超级用户 doccano webserver --port 8000 # 启动 Web 服务

再开一个终端跑doccano task，它是负责文件导入导出等长任务的队列进程，缺了它数据集上传会卡住。然后访问http://127.0.0.1:8000/即可。

Docker，团队部署推荐，数据持久化在命名卷里，重启不丢：

docker pull doccano/doccano docker container create --name doccano \ -e "ADMIN_USERNAME=admin" -e "ADMIN_EMAIL=admin@example.com" \ -e "ADMIN_PASSWORD=password" \ -v doccano-db:/data -p 8000:8000 doccano/doccano docker container start doccano

Docker Compose，需要 nginx + PostgreSQL + RabbitMQ 完整生产栈时使用，先拉源码：

git clone https://gitcode.com/gh_mirrors/do/doccano cd doccano

再按 docs/install_and_upgrade_doccano.md 配置.env后启动docker/docker-compose.prod.yml。生产部署的容器拓扑长这样：

建项目、定标签：标注前的两个关键决策

登录后进入项目列表，点Create，填好名称、描述并选定任务类型，一个标注项目就建好了：

紧接着是标签设计，它直接决定标注速度和数据一致性：

• 数量克制：标签太多会让标注者在边界案例上反复犹豫，先收敛到 5~10 个高频标签
• 配好快捷键与颜色：每个标签设一个键位和区分度高的背景色，长文本标注时双手不离键盘
• 留一个兜底标签：如Other，容纳无法归类的片段，避免标注者弃标

团队协作还要把成员拉进来。项目左侧菜单的Members面板里可以按用户名添加成员并指定角色——administrator、annotator、approver三级权限分别对应管理、标注与审核。新用户要先在管理后台创建，具体路径见 docs/faq.md：

数据导入避坑：格式、编码与文件细节

项目建好后，在Dataset页点Actions > Import Dataset，选择文件格式再上传即可。doccano 支持纯文本、CSV、JSON、JSONL、Excel、CoNLL、FastText 等多种格式，解析逻辑集中在 backend/data_import/，已标注数据也能直接导入，省去从零开始。

上传失败十有八九栽在下面几个细节上，导入前自查一遍能省不少时间：

• 编码必须是UTF-8
• 文件名用纯字母命名最稳妥
• 数据里不能有空白行和空白字段
• JSON/JSONL 要先保证语法合法——挑一小段脱敏数据校验就够，不必拿完整文件冒险

标注工作台：划词、快捷键与自动保存

数据就绪后点导航栏的Start annotation进入标注界面。以序列标注为例：鼠标划选文字片段，按对应快捷键（或点选标签）完成一次标注，然后继续往下推进。文档间可以前后翻页跳转，标注结果自动保存，中途关页面也不会丢。

标注过程中你还能顺手做两件事：给有歧义的片段加 comment，把疑问留给approver角色的审核者；以及通过项目 metrics 页面查看每个人的进度和标签分布，哪个成员卡住了、哪个标签占比异常，一目了然，实现逻辑在 backend/metrics/。

自动标注：让 API 先标一版，人来复核

大批量数据如果全靠人工，成本会成倍上涨。doccano 的自动标注功能可以挂接一个 Web API（预训练模型服务也好，云端服务也好），打开新文档时自动先标一遍，标注者只做修正。

配置入口在项目的Settings > Auto Labeling，先选一个模板——内置模板覆盖 Amazon Comprehend 等云服务，也支持 Custom REST Request 对接自己的模型服务：

模板选定后按"请求参数 → 响应映射 → 标签映射 → 启用"四步走：用样本数据逐步测试，确认 API 返回能正确转换成 doccano 内部标签，再到标注页打开开关。整个模块实现在 backend/auto_labeling/，详细步骤见 docs/advanced/auto_labelling_config.md。

值得一提的是，doccano 本身是 RESTful API 架构，如果你不想走界面自动标注，也可以直接写脚本调用 API 批量打标，把模型推理和标注数据管理完全自动化。

导出训练数据：格式按训练框架选

标注完成后回到Dataset页，点Actions > Export Dataset，选择目标格式即可生成训练数据。doccano 支持 CSV、JSON、JSONL、FastText 等格式，导出管线在 backend/data_export/，不同任务类型会生成对应的字段结构。以序列标注导出的 JSONL 为例，每条记录包含文本、标签区间和标注者：

{"doc_id": 33, "text": "The Hitchhiker's Guide to the Galaxy ...", "labels": [[0, 36, "Title"], [89, 111, "Genre"], [130, 143, "Person"]], "username": "admin"}

导出前最后过一遍质量：approver复核过的文档可信度最高，标签分布明显偏斜的类别往往意味着标签定义或标注说明出了问题，这时候回改标签体系比硬着头皮训练模型更划算。

下一步

到这里，从原始文本到可训练数据集的完整闭环就跑通了。想继续深入，docs/index.md 里有安装升级、多语言界面（中/英/法/德）、暗色主题、端口与 HTTPS 配置等细节；团队使用时的常见问题都收在 docs/faq.md，比如改端口、处理 CSRF 报错这类操作都有现成方案。

【免费下载链接】doccanoOpen source annotation tool for machine learning practitioners.项目地址: https://gitcode.com/gh_mirrors/do/doccano