Label Studio Enterprise 2.20.0 发版解析：Taxonomy 文本标注、音频快捷键与 Django 5 升级实践

Label Studio Enterprise 2.20.0 发版解析：Taxonomy 文本标注、音频快捷键与 Django 5 升级实践

【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio

Label Studio Enterprise 2.20.0（2025 年 1 月 28 日发布，配套 Helm Chart 1.9.0）是一次聚焦"标注效率与底层安全"的版本迭代：它让<Taxonomy>标签首次支持在文本区域上直接做 NER 式标注，为音频暂停/播放新增了ctrl/command+p快捷键，并随 Django 5 升级将 PostgreSQL 的最低版本提升至 13+。本文以官方发版说明为骨架，结合当前仓库中的标签文档、前端实现与 Django 设置源码，逐项拆解这些增强、安全加固、破坏性变更与 Bug 修复，并给出可落地的标注配置与部署建议。

版本总览

增强一：Taxonomy 作为文本标注工具（labeling="true"）

在 2.20.0 之前，<Taxonomy>标签只能用于整段/整对象的层次化分类——标注者从一棵层级树中选择一个或多个叶子节点作为该对象的分类结果。本次更新为 Taxonomy 标签引入了新的labeling参数：当设置为true时，你可以把 Taxonomy 中定义的类别直接应用到文本中的具体区域（region），使其具备 NER（命名实体识别）式标注能力，例如高亮"Virginia"并标注为Place、高亮"Opossums"并标注为Mammal。

前端源码中的参数定义

该参数在编辑器前端的 Taxonomy.jsx 中有明确定义：

const TagAttrs = types.model({ toname: types.maybeNull(types.string), labeling: types.optional(types.boolean, false), leafsonly: types.optional(types.boolean, false), showfullpath: types.optional(types.boolean, false), ... });

• labeling类型为布尔值，默认false，与文档中"默认不开启"的行为一致；
• 同一份源码中的 JSDoc 注释也明确标注："Use taxonomy to label regions in text. Only supported with<Text>and<HyperText>object tags."——labeling仅在与<Text>或<HyperText>对象标签搭配时有效。

完整可复制的标注配置

以下配置来自 docs/source/tags/taxonomy.md 与 docs/source/templates/taxonomy.md，可直接用于文本区域标注场景：

<View> <Text name="text" value="$text"/> <Taxonomy name="taxonomy" toName="text" labeling="true"> <Choice value="Animal"> <Choice value="Mammal" /> <Choice value="Reptile" /> <Choice value="Bird" /> </Choice> <Choice value="Place" /> <Choice value="Organization" /> </Taxonomy> </View>

要点说明：

• 与普通分类用法相同，<Taxonomy>必须声明name与toName，其中toName指向对象标签（这里是text）；
• 类别通过嵌套的<Choice>定义层级，标注者既可选择叶子节点，也可选择父节点类别；
• 开启labeling="true"后，标注者在文本中选中一段文字即可弹出分类树并施加标注；区域会以高亮 + 编号（如1:Place、2:Mammal）的形式呈现；
• 提示：可在<Choice>上使用color参数为不同类别着色，便于区分同一文本中的多种标注，见 docs/source/templates/taxonomy.md 中的 Tip。

发版说明中引用的官方截图也保存在仓库中：docs/themes/v2/source/images/releases/2-20-taxonomy.png，展示的正是上述"在文本段落上高亮并施加 Taxonomy 类别"的界面。

补充：Taxonomy 常用参数速查

围绕 2.20.0 的labeling新参数，<Taxonomy>还支持以下常用参数（来自 docs/source/includes/tags/taxonomy.md 与前端源码）：

其中labeling参数在前端实现（web/libs/editor/src/tags/control/Taxonomy/Taxonomy.jsx）与参数文档（docs/source/includes/tags/taxonomy.md）中均有体现，二者对"仅支持<Text>与<HyperText>"的限制保持一致。

增强二：音频标注新快捷键

2.20.0 为音频暂停/播放新增了快捷键：

• Windows / Linux：ctrl+p
• macOS：command+p

在此之前，音频播放/暂停已有空格键（space）快捷键。新增组合键的价值在于：当标注者在音频任务中同时填写文本框（如转写内容）时，空格键会被文本输入框吞掉，无法触发播放控制；此时ctrl/command+p提供了一条不干扰输入的播放控制路径。

增强三：视频帧分类模板内置

视频帧分类（Video Frame Classification）模板此前只存在于文档中，2.20.0 起直接在 Label Studio 应用内可用。该模板用于对视频中的每一帧单独打标，适合检测动作、状态或随时间变化的事件，而不是对整段视频做单一分类。其核心配置（见 docs/source/templates/video_frame_classification.md）：

<View> <TimelineLabels name="videoLabels" toName="video"> <Label value="Movement" background="#c813ec"/> <Label value="Still" background="#1d81cd"/> <Label value="Slow Motion" background="#54d651"/> </TimelineLabels> <Video name="video" value="$video" frameRate="25.0" timelineHeight="120" /> </View>

关键参数说明：

• <Video>的frameRate必须与视频实际帧率一致；若视频存在缺陷或可变帧率（VFR），可能导致帧与时间轴错位，建议先转码为恒定帧率再上传；
• timelineHeight控制时间轴高度；
• <TimelineLabels>内的<Label>定义可施加到具体帧上的标签。

增强四：前端性能优化

2.20.0 优化了前端发出的 API 调用：

• **成员管理页（members management）**与Data Manager 用户列表：减少了冗余请求，用户量较大时列表加载更流畅；
• Projects 页面：优化加载时间。

这类优化属于前端行为层面的改进，不影响标注配置或后端 API 契约。

安全加固

2.20.0 包含两项安全相关变更：

1. 升级 pyarrow：修复旧版本包中存在的安全漏洞；
2. CSRF Cookie 默认设置加固：更新了 CSRF Cookie 的默认配置，并新增环境变量以控制 Cookie 有效期。

关于第 2 点的实现，可参见 label_studio/core/settings/base.py：

# Sessions and CSRF SESSION_COOKIE_SECURE = bool(int(get_env('SESSION_COOKIE_SECURE', False))) SESSION_COOKIE_SAMESITE = get_env('SESSION_COOKIE_SAMESITE', 'Lax') CSRF_COOKIE_SECURE = bool(int(get_env('CSRF_COOKIE_SECURE', SESSION_COOKIE_SECURE))) CSRF_COOKIE_HTTPONLY = bool(int(get_env('CSRF_COOKIE_HTTPONLY', SESSION_COOKIE_SECURE))) CSRF_COOKIE_SAMESITE = get_env('CSRF_COOKIE_SAMESITE', 'Lax') # default value is from django docs: https://docs.djangoproject.com/en/5.1/ref/settings/#csrf-cookie-age # approximately 1 year CSRF_COOKIE_AGE = int(get_env('CSRF_COOKIE_AGE', 31449600))

由此可知，本次加固涉及的可用环境变量包括：

生产部署建议：在启用 HTTPS 的环境中将CSRF_COOKIE_SECURE显式设为true，并根据安全合规要求通过CSRF_COOKIE_AGE收紧 Cookie 有效期。

破坏性变更：Django 5 与 PostgreSQL 13+

2.20.0 将底层 Django 框架升级到Django 5，由此带来一个必须提前评估的运维前提：

Label Studio Enterprise 2.20.0 起要求 PostgreSQL 13+。

在升级前请确认：

• 数据库版本是否 ≥ 13（SELECT version();可查看 PostgreSQL 版本）；
• 若仍在运行 PostgreSQL 12 或更早版本，需先完成数据库升级；
• 升级过程建议先在预发布环境验证，再对生产实例执行迁移。

作为佐证，当前仓库主分支的依赖清单（pyproject.toml）已锁定 Django 5.2 系列（Django (>=5.2.16,<5.3.0)），并搭配djangorestframework 3.17.2、django-cors-headers 4.7.0等 Django 5 兼容生态，说明 Django 5 已成为项目当前的技术基线。

Bug 修复清单

2.20.0 修复的问题覆盖 UI、API、任务统计与基础设施四个层面：

• 侧边菜单版本号显示异常：Label Studio 版本号在侧边菜单中的格式不正确，已修复；
• contextlog 缺少content_type：contextlog未上报content_type字段的问题已修复；
• 高亮时重叠关系（relations）显示异常：标注界面上高亮区域时，重叠的 relation 显示异常，已修复；
• API 批量导入任务 ID 重复：通过 API 大批量导入任务时出现任务 ID 重复，已修复；
• 登录后跳转页面错误：用户登录后未跳转到正确页面，已修复；
• 无法编辑标注框（bbox）区域的元信息：用户无法修改之前为 bounding box 区域添加的元信息，已修复；
• Poetry / Poetry-core 2 兼容问题：修复了多个因 Poetry/Poetry-core 2 发布导致的构建/依赖问题；
• django-rq 管理页面不可访问：修复了 django-rq admin 页面无法访问的问题；
• Data Manager / 编辑器动态加载竞态条件：修复了动态加载 Data Manager 或编辑器时可能出现的竞态条件（race condition），该问题曾导致二者均无法加载；
• Skip Queue 设置为 Ignore Skipped 时跳过任务未计入完成：当项目 Skip Queue 设置为Ignore Skipped时，被跳过的任务未被计算为已完成，已修复。

Skip Queue 修复的源码佐证

最后一项修复可以在当前仓库的任务统计逻辑中找到对应实现。项目级配置在 label_studio/projects/models.py 中定义：

IGNORE_SKIPPED = 'IGNORE_SKIPPED', 'Ignore skipped'

任务完成度的聚合计算位于 label_studio/tasks/models.py：

with transaction.atomic(): use_overlap = project._can_use_overlap() if use_overlap: # following definition of `completed_annotations` above, count cancelled annotations # as completed if project is in IGNORE_SKIPPED mode completed_annotations_f_expr = F('total_annotations') if project.skip_queue == project.SkipQueue.IGNORE_SKIPPED: completed_annotations_f_expr += F('cancelled_annotations') finished_q = Q(GreaterThanOrEqual(completed_annotations_f_expr, F('overlap'))) finished_tasks = tasks.filter(finished_q) tasks.update(is_labeled=Q(id__in=finished_tasks_ids))

注释与代码均明确：当skip_queue == IGNORE_SKIPPED时，被取消（跳过）的标注计入completed_annotations表达式，从而让跳过任务被正确算作已完成——这正是发版说明中所描述的修复行为。相关行为也有测试覆盖，见 label_studio/tests/next_task_skip_queue.tavern.yml（测试名skip_queue_ignore_skipped，配置skip_queue: IGNORE_SKIPPED）。

升级建议与验证清单

综合以上变更，从 2.20.0 之前版本升级时建议按以下顺序检查：

1. 数据库：确认 PostgreSQL ≥ 13（硬性要求），必要时先升级数据库实例；
2. 依赖构建：若使用 Poetry 管理依赖，确认 Poetry/Poetry-core 版本与 2.20.0 兼容（本次修复了 Poetry-core 2 的兼容问题）；
3. 安全配置：按需设置CSRF_COOKIE_SECURE、CSRF_COOKIE_AGE等环境变量；
4. 新功能验证：在测试项目中尝试labeling="true"的 Taxonomy 文本标注、ctrl/command+p音频快捷键，以及视频帧分类模板；
5. 任务统计回归：为设置了Ignore Skipped的项目导入数据并跳过部分任务，确认其被正确计为已完成；
6. 批量导入回归：通过 API 批量导入大量任务，确认任务 ID 无重复。

相关资源

• Taxonomy 标签完整参数文档：docs/source/tags/taxonomy.md、docs/source/includes/tags/taxonomy.md
• Taxonomy 模板与外部分类树（apiUrl、JSON 扁平文件、API taxonomy 规范）：docs/source/templates/taxonomy.md
• 视频帧分类模板：docs/source/templates/video_frame_classification.md
• Taxonomy 前端实现：web/libs/editor/src/tags/control/Taxonomy/Taxonomy.jsx
• CSRF Cookie 设置源码：label_studio/core/settings/base.py
• Skip Queue 状态定义与任务统计实现：label_studio/projects/models.py、label_studio/tasks/models.py
• 依赖版本（Django 5.2 系列）：pyproject.toml

【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio