如何在Doccano中通过自定义REST API请求配置自动标注功能

这套配置我在文本分类、NER两个生产级标注项目里都跑通过，照着配置基本不会出问题。

• 前置准备：先确认两个前提，一是你已经在Doccano里建好了对应类型的标注项目，提前把要用到的标签都在项目标签库录入完成；二是你自己的NLP推理服务已经部署完成，有可正常调用的REST接口，明确接口的请求方法、参数格式、返回结构。

1. 进入配置入口 #

打开目标标注项目，在左侧边栏找「设置」-「自动标注」，点「创建」按钮，模板选择自定义REST API，不要选自带的第三方服务模板。

2. 配置请求规则 #

这部分全部填写你自己的推理接口信息：

• 请求方法：按接口实际情况选GET或者POST，绝大多数模型推理接口用POST
• 接口地址：填推理服务的完整可访问地址，比如http://192.168.1.100:8080/ner/predict，如果是容器化部署的Doccano，别填127.0.0.1，要填服务所在的内网IP或者域名，不然会出现网络不通的问题
• 请求头：按接口要求添加，比如传JSON格式就加Content-Type: application/json，接口有token鉴权就加对应的Authorization字段
• 请求模板：用{{ text }}作为待标注文本的占位符，POST请求就把占位符放到请求体里，示例：

{
  "content": "{{ text }}",
  "return_offsets": "char"
}

如果是GET请求，直接把占位符拼到URL查询参数里就行，格式类似http://your-service-addr/predict?text={{ text }}

3. 配置返回结果映射 #

这一步是核心，要把你接口返回的字段和Doccano要求的标注字段一一对应，不同项目类型映射要求不一样：

• 文本分类项目：把接口返回的标签值映射到label字段，置信度值映射到score字段即可
• 序列标注（NER）项目：需要先指定实体列表在返回结果里的层级路径，再把列表里的实体起始位置、结束位置、实体类型三个字段，分别映射到start_offset、end_offset、label
• 序列到序列（摘要、翻译类）项目：直接把接口返回的生成结果映射到text字段就行

举个NER场景的映射例子，假设你的接口返回格式如下：

{
  "status": 0,
  "result": [
    {"start_pos": 0, "end_pos": 2, "entity_type": "PER", "prob": 0.97}
  ]
}

那映射配置就填：

• 实体列表路径：result
• 起始偏移对应字段：start_pos
• 结束偏移对应字段：end_pos
• 标签对应字段：entity_type

4. 测试启用 #

配置填完后，在页面底部的测试框输入一段样例文本，点测试按钮，看预览区能不能正常显示自动打出来的标签。如果标签位置、内容都对，直接保存配置，打开启用开关就可以用了。之后打开未标注的文档时，Doccano会自动调用你配的接口拉取预标注结果，人工只需要校对调整就行，能省至少60%的标注时间。

常见踩坑点 #

• 序列标注一定要确认偏移量是字符级的，Doccano不认token级偏移，如果你模型返回的是token偏移，记得在推理接口里先转成字符偏移，不然标出来的实体位置全错
• 接口返回的标签文本必须和你在Doccano标签库里提前录入的标签完全一致，差一个空格都识别不出来
• 如果测试的时候报连接错误，先登到Doccano部署的机器上curl一下你的推理接口，先排查网络连通性问题，再查参数格式问题

内容的提问来源于stack exchange，提问作者Anand Shrivastava