Label Studio Python SDK 集成指南将数据标注无缝接入机器学习流水线【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studioLabel Studio 是一个支持多类型数据标注与注释的开源工具而Label Studio Python SDK是为其 HTTP API 提供的官方 Python 客户端封装。本文围绕 SDK 官方指南 展开结合本仓库中 SDK 测试套件的真实用法系统讲解如何在数据科学和机器学习流水线中通过 Python 脚本管理项目、导入任务、操作标注、批量预测与数据导出。读完本文你将掌握 SDK 的安装、认证、核心对象模型与端到端实战模式能够把 Label Studio 的标注能力直接嵌入你自己的数据处理工作流。SDK 是什么面向数据流水线的 API 封装层Label Studio Python SDK 提供了一组预定义的类与方法用于直接在你的 Python 脚本中与 Label Studio API 交互使管理项目、导入任务、处理标注等操作不再依赖手工 curl 或浏览器操作。从仓库的测试代码可以清晰看到它的核心入口形态from label_studio_sdk.client import LabelStudio ls LabelStudio(base_urldjango_live_url, api_keybusiness_client.api_key)这一行代码即完成了全部初始化后续所有操作都通过ls客户端的资源命名空间如ls.projects、ls.tasks、ls.annotations、ls.predictions、ls.views、ls.actions、ls.ml、ls.import_storage、ls.users展开。以 label_studio/tests/sdk/test_projects.py 为例创建项目、查询项目、更新标题等操作在 SDK 下只需要几个方法调用。使用 SDK 的核心收益原文档 sdk.md 总结了五大收益每一项都能在仓库测试代码中找到对应的落地实现简化的 API 交互SDK 把 HTTP 请求、序列化、错误处理封装成用户友好的 Python 方法与类。测试中ls.projects.create(...)返回可直接访问属性的对象如project.id、project.title无需手动解析 JSON。流水线集成SDK 可以嵌入任何已有的数据科学工作流。测试代码如 test_tasks.py展示了建项目 → 导任务 → 标注 → 导出这一完整链路在纯 Python 中的编排方式。自动化项目创建、任务导入、数据导出等重复性操作均可脚本化。例如 test_export.py 中用ls.projects.exports.as_pandas(project.id)一步完成标注数据 → pandas DataFrame的转换。增强的数据准备SDK 提供过滤器Filters与自定义配置label config能力。 test_annotations.py 中通过Filters.create结合Column、Operator、Type枚举构建查询筛选出未标注任务保证高质量标注。异步操作SDK 同时提供AsyncLabelStudio异步客户端用于处理大数据量下的并发请求提升性能详见下文异步操作一节。快速开始安装、认证与连接第一步安装 SDKpip install label-studio-sdk在本仓库中SDK 被作为开发与测试依赖使用声明于 pyproject.toml通过 git 引用固定版本这保证了仓库自带 SDK 集成测试始终针对某个确定的 SDK 版本运行也说明 SDK 与 Label Studio 服务端是同源演进、配套验证的。第二步准备访问令牌与服务器地址SDK 需要两个信息Label Studio 服务地址与API 密钥访问令牌。API 密钥在 Label Studio 界面右上角用户图标 →Account Settings中生成相关操作详见 访问令牌指南。Label Studio 提供两类令牌对 SDK 而言用法完全相同详见 access_tokens.md特性个人访问令牌PAT传统令牌Legacy Token有效期可在组织级设置 TTLEnterprise不自动过期可见性仅创建时可见一次始终列在账号设置中类型JWT 刷新令牌静态令牌吊销可手动吊销可手动吊销与 HTTP API 配合需先用POST /api/token/refresh换取短期 access token携带Authorization: Bearer token直接携带Authorization: Token token与 SDK 配合直接传入或设置环境变量只需配置一次直接传入或设置环境变量只需配置一次关于令牌的安全建议传统令牌因为必须手动吊销安全性弱于 PAT使用 HTTP API 时 PAT 换取的短期 access token 约 5 分钟过期过期后需重新换取返回 401这构成额外的安全层。第三步在脚本中建立连接原文档给出的最小连接代码# 定义 Label Studio 可访问的地址 LABEL_STUDIO_URL YOUR_BASE_URL # API key 可以是个人访问令牌或传统访问令牌 LABEL_STUDIO_API_KEY YOUR_API_KEY # 导入 SDK 与客户端模块 from label_studio_sdk import LabelStudio client LabelStudio(base_urlLABEL_STUDIO_URL, api_keyLABEL_STUDIO_API_KEY)同时令牌也支持通过环境变量注入。根据 access_tokens.md个人访问令牌可以直接写在脚本中或设置为LABEL_STUDIO_API_KEY环境变量SDK 会自动读取。推荐在 CI/CD 与共享脚本中使用环境变量方式避免把密钥写进代码库。深入客户端对象模型以测试套件为教材本仓库的 label_studio/tests/sdk 目录是 SDK 用法的权威活教材。下面按资源维度逐一展开每个示例均直接取自仓库测试代码。项目Projects创建、查询、更新、删除test_projects.py 展示了项目生命周期管理ls LabelStudio(base_urldjango_live_url, api_keybusiness_client.api_key) # 创建项目title 必填label_config 为标注界面 XML 配置 p ls.projects.create(titleNew Project, label_configLABEL_CONFIG_AND_TASKS[label_config]) # 按 id 获取项目 project ls.projects.get(idp.id) # 更新项目属性 ls.projects.update(idproject.id, titleUpdated Project) # 删除项目 ls.projects.delete(idproject.id) # 列出项目支持过滤与字段裁剪 projects list(ls.projects.list(filterpinned_only)) projects list(ls.projects.list(includeid,title,pinned_at,created_at,created_by))其中include参数用于按需裁剪返回字段减少传输数据量filter支持如pinned_only之类的服务端过滤。测试还验证了返回对象的字段可访问性例如project.created_by.email。任务Tasks创建、导入、批量操作与导出任务管理是 SDK 最常用的能力test_tasks.py 覆盖了完整 CRUD# 单条创建任务 task_data [{data: {my_text: Test task}}] for task in task_data: ls.tasks.create(projectp.id, datatask[data]) # 列出项目下所有任务 tasks [task for task in ls.tasks.list(projectp.id)] # 更新任务数据 ls.tasks.update(idtask_id, data{my_text: Updated task}) # 删除单条任务 ls.tasks.delete(idtask_id) # 批量导入任务推荐用于大批量场景 ls.projects.import_tasks(idp.id, requesttask_data) # 通过 actions 批量删除选中特定任务 ls.actions.create(projectp.id, iddelete_tasks, selected_items{all: False, included: tasks_ids_to_delete}) # 通过 actions 删除除某任务外的全部任务 ls.actions.create(projectp.id, iddelete_tasks, selected_items{all: True, excluded: [tasks[5].id]}) # 清空项目全部任务 ls.tasks.delete_all_tasks(idp.id)ls.projects.import_tasks是批量导入任务的标准入口它支持两种请求体形态参见 test_predictions.py简化形态只传字段映射如{my_text: Hello world, sentiment_class: Positive}配合preannotated_from_fields[sentiment_class]可从数据字段自动生成预测扩展形态传包含data、annotations、predictions的完整任务结构例如仓库 common.py 中定义的tasks_for_import——一个任务可同时携带标注结果annotations[].result[].value和模型预测predictions[].result与score用于一次性还原完整的标注项目。标注Annotations结构化创建与 CRUD标注是 SDK 最值得展开的能力因为它引入了类型安全的结构化 API。 test_annotations.py 展示了完整流程from label_studio_sdk.label_interface import LabelInterface from label_studio_sdk.label_interface.objects import AnnotationValue, TaskValue # 用 XML 配置构建 LabelInterface获得类型化的标注构建器 li LabelInterface(LABEL_CONFIG_AND_TASKS[label_config]) # 用 TaskValue 构造任务值对象model_dump() 转成可导入的字典 task_data TaskValue(data{my_text: Test task}) ls.projects.import_tasks(idp.id, request[task_data.model_dump()]) # 通过 li.get_control(tag_name).label(...) 构造符合标签配置的结果 annotation_data AnnotationValue( result[li.get_control(sentiment_class).label([Positive])], completed_bybusiness_client.user.id, ).model_dump() new_annotation ls.annotations.create(task_id, resultannotation_data[result]) # 更新标注结果值被替换为 Negative ls.annotations.update(idannotation_id, result[li.get_control(sentiment_class).label([Negative])]) # 按任务列出标注 annotations ls.annotations.list(task_id) # 删除标注 ls.annotations.delete(idannotation_id)对于视觉标注如目标检测label(...)支持坐标参数。测试中构造了一个矩形框标注annotation_data AnnotationValue( result[li.get_control(bbox).label([Car], x10, y20, width100, height100)], completed_bybusiness_client.user.id, ).model_dump()生成的result[0][value]为{rectanglelabels: [Car], x: 10, y: 20, width: 100, height: 100, rotation: 0}与编辑器内部存储格式完全一致。此外LabelInterface.create(...)还可以用 Python 字典以编程方式生成标签配置test_annotations.py例如from label_studio_sdk.label_interface.create import labels label_config LabelInterface.create({ image1: Image, bbox: labels([Car, Truck, Van], tag_typeRectangleLabels), })测试还验证了标注与任务完成状态的联动使用Column.completed_at为空的过滤器查询时未标注任务不会出现在结果中一旦写入标注该任务立即可被过滤器捕获详见 test_annotations.py。数据过滤与视图Filters ViewsSDK 提供了一套面向数据管理器的类型化过滤 API用于精准筛选任务子集。构建过滤器的要素包括Column数据列如Column.id、Column.completed_atOperator操作符如Operator.EMPTY、Operator.EQUAL、Operator.GREATER_OR_EQUAL、Operator.LESS_OR_EQUALType字段类型如Type.Datetime、Type.NumberFilters过滤器组合容器支持Filters.AND/Filters.OR逻辑示例test_annotations.pyfrom label_studio_sdk.data_manager import Column, Filters, Operator, Type import json filters Filters.create( Filters.OR, [Filters.item(Column.completed_at, Operator.EMPTY, Type.Datetime, Filters.value(False))], ) query json.dumps({filters: filters}) # 将 query 传给 tasks.list 进行服务端过滤 labeled_tasks [task for task in ls.tasks.list(projectp.id, queryquery, fieldsall)]过滤器还可以持久化为视图View之后可按视图拉取任务test_views.pyfilters Filters.create( Filters.AND, [ Filters.item(Column.id, Operator.GREATER_OR_EQUAL, Type.Number, Filters.value(1)), Filters.item(Column.id, Operator.LESS_OR_EQUAL, Type.Number, Filters.value(100)), ], ) view ls.views.create(projectproject.id, datadict(titleTest View, filtersfilters)) # 列出项目全部视图 views ls.views.list(projectproject.id) # 按视图 id 获取任务返回过滤后的任务子集支持排序字段 tasks [task for task in ls.tasks.list(viewview.id)]视图数据支持ordering字段如- Column.id表示按 id 降序详见 fixtures.py。预测Predictions写入、导入与版本管理SDK 对模型预测提供了完整支持test_predictions.pyfrom label_studio_sdk.label_interface.objects import PredictionValue # 为指定任务创建预测 pv PredictionValue( result[li.get_control(sentiment_class).label([Positive])], score0.9, model_version1.0.0, ) prediction ls.predictions.create(tasktask.id, **pv.model_dump()) # 读取 / 列出 / 删除 prediction ls.predictions.get(idprediction.id) predictions ls.predictions.list(tasktask.id) ls.predictions.delete(idprediction.id) # 批量导入预测一次请求创建多条 response ls.projects.import_predictions(idproject.id, requestpredictions_payload) assert response.created 3两点值得注意的实现细节同样来自测试断言model_version强校验项目存在已登记的模型版本时用未登记的model_version更新项目会抛出label_studio_sdk.core.api_error.ApiErrorHTTP 状态码 400响应体包含validation_errorstest_predictions.py。因此引入新模型时应先通过ls.projects.update(idp.id, model_versionx.y.z)登记版本。简化导入自动预标注import_tasks传入preannotated_from_fields[sentiment_class]时SDK 会把任务数据中的该字段转换为预测省去手工构造 result 的步骤。ML 后端集成与批量动作SDK 可以注册 ML 后端并对任务批量触发预测整个流程在 test_ml.py 中有端到端验证# 注册 ML 后端 ls.ml.create(urlhttp://test.ml.backend.for.sdk.com:9092, projectp.id, titleModelSingle) # 确认 ML 后端已创建 ml_backend ls.ml.list(projectp.id) # 通过 actions 对指定任务批量触发预测排除 tasks[1] ls.actions.create( idretrieve_tasks_predictions, projectp.id, selected_items{all: True, excluded: [tasks[1].id]}, ) # 通过 actions 将预测转成标注 ls.actions.create( idpredictions_to_annotations, projectp.id, selected_items{all: False, included: [predictions[0].task, predictions[1].task]}, )actions.create的selected_items支持{all: True, excluded: [...]}排除法与{all: False, included: [...]}选择法两种模式。批量预测返回的预测记录会带上 ML 后端的model_version即注册时的title与score随后可一键转换为正式标注——这是模型预标注 → 人工确认流水线的核心闭环。外部存储连接Import Storages对于 S3、GCS、Azure Blob、本地目录等外部存储SDK 提供了import_storage/export_storage命名空间。 test_storages.py 以 S3 为例验证了建连接 → 配置 → 同步三步# 创建 S3 导入存储连接 storage_resp ls.import_storage.s3.create( projectp.id, bucketpytest-s3-images, regex_filter.*, # 文件名匹配规则 use_blob_urlsFalse, # 是否使用 blob URL recursive_scanTrue, # 是否递归扫描子目录 ) # 读取与更新连接配置 storage ls.import_storage.s3.get(idstorage_id) ls.import_storage.s3.update(idstorage_id, use_blob_urlsTrue) # 触发一次同步把存储中的文件作为任务拉入项目 resp ls.import_storage.s3.sync(idstorage_id)测试特别验证了recursive_scan的行为差异为False时只导入根目录文件如image1.jpg为True时连子目录文件如subdir/another/image2.jpg一并导入导入后每个任务可通过storage_filename属性追溯到源文件。用户管理test_users.py 展示了如何通过 SDK 邀请/创建组织成员u ls.users.create(**{ email: test_memberexample.com, username: test_memberexample.com, first_name: Test, last_name: Member, }) assert u.id in [u.id for u in ls.users.list()]数据导出JSON、pandas 与流式下载导出是 SDK 的高频能力test_export.py 给出了三种形态# 1) 查询项目支持的导出格式 formats ls.projects.exports.list_formats(project.id) # 2) 直接导出为 JSON 列表 json_data ls.projects.exports.as_json(project.id) # 3) 直接导出为 pandas DataFrame适合直接进入模型训练/分析 df ls.projects.exports.as_pandas(project.id) # 4) 底层同步下载字节流可控制是否包含全部任务 data ls.projects.exports.download_sync(project.id, download_all_tasksTrue)其中as_pandas还可透传创建参数如{task_filter_options: {finished: only}}只导出已标注完成的任务。从测试断言看download_sync返回字节流需自行组装为 JSON 解析测试中通过BytesIO累积分块后json.load完成反序列化。异步操作AsyncLabelStudio原文档特别强调了 SDK 的异步能力。SDK 提供AsyncLabelStudio客户端接口与同步客户端一一对应适用于大批量任务的并发导入、导出与预测。仓库测试中的使用形态test_export.pyfrom label_studio_sdk import AsyncLabelStudio ls AsyncLabelStudio(base_urldjango_live_url, api_keybusiness_client.api_key) project await ls.projects.create(titleExport Test Project, label_configLABEL_CONFIG_AND_TASKS[label_config]) await ls.projects.import_tasks(idproject.id, requestLABEL_CONFIG_AND_TASKS[tasks_for_import]) json_data await ls.projects.exports.as_json(project.id) df await ls.projects.exports.as_pandas(project.id)说明上述异步测试用例在当前仓库环境中因pytest-asyncio未启用而被跳过测试文件中有pytest.mark.skip标注但这只是仓库测试运行条件的限制AsyncLabelStudio类本身由 SDK 提供。在数据量较大、需要并发吞吐的场景下应优先使用异步客户端。测试即文档如何验证你的 SDK 集成本仓库在 label_studio/tests/sdk 下提供了完整、可运行的 SDK 集成测试基于 Django 测试框架与真实的内存数据库覆盖项目、任务、标注、预测、视图、存储、ML 后端、用户与导出等全部资源。这些测试既是对 SDK 的回归保障也是学习 SDK 用法的第一手样例——当你需要确认某个 SDK 方法的确切参数与返回结构时直接查阅对应测试文件即可例如项目生命周期test_projects.py任务批量操作与删除test_tasks.py标注结构化创建与过滤器联动test_annotations.py预测 CRUD 与批量导入test_predictions.py视图持久化与按视图取数test_views.py、fixtures.py外部存储同步test_storages.pyML 后端批量预测与预测转标注test_ml.py多种导出形态与异步客户端test_export.py测试中反复出现的 common.py 定义了一套标准的文本分类标签配置TextChoices含 Positive/Neutral/Negative与任务 标注 预测完整样例数据可作为自行编写 SDK 脚本时构造测试数据的模板。常见注意事项令牌安全优先使用个人访问令牌PAT并通过LABEL_STUDIO_API_KEY环境变量注入PAT 与 HTTP API 配合时需要先调用POST /api/token/refresh换取短期 access token详见 access_tokens.md而 SDK 中两者用法一致仅需配置一次。model_version一致性写入预测或更新项目时模型版本必须已在项目中登记否则 SDK 会抛出ApiError400。批量操作优先使用 actions删除大量任务、批量触发预测、预测转标注等场景统一通过ls.actions.create(id..., selected_items...)实现支持选择法与排除法两种任务子集表达避免逐条循环调用 API。大数据量场景使用异步客户端需要并发处理海量任务时改用AsyncLabelStudio与await语法充分利用异步 I/O 提升吞吐。类型化对象先行构造标注/预测/任务时优先使用LabelInterface、TaskValue、AnnotationValue、PredictionValue等类型化对象通过model_dump()输出字典能显著降低手写嵌套字典出错的概率。【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Label Studio Python SDK 集成指南：将数据标注无缝接入机器学习流水线
Label Studio Python SDK 集成指南将数据标注无缝接入机器学习流水线【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studioLabel Studio 是一个支持多类型数据标注与注释的开源工具而Label Studio Python SDK是为其 HTTP API 提供的官方 Python 客户端封装。本文围绕 SDK 官方指南 展开结合本仓库中 SDK 测试套件的真实用法系统讲解如何在数据科学和机器学习流水线中通过 Python 脚本管理项目、导入任务、操作标注、批量预测与数据导出。读完本文你将掌握 SDK 的安装、认证、核心对象模型与端到端实战模式能够把 Label Studio 的标注能力直接嵌入你自己的数据处理工作流。SDK 是什么面向数据流水线的 API 封装层Label Studio Python SDK 提供了一组预定义的类与方法用于直接在你的 Python 脚本中与 Label Studio API 交互使管理项目、导入任务、处理标注等操作不再依赖手工 curl 或浏览器操作。从仓库的测试代码可以清晰看到它的核心入口形态from label_studio_sdk.client import LabelStudio ls LabelStudio(base_urldjango_live_url, api_keybusiness_client.api_key)这一行代码即完成了全部初始化后续所有操作都通过ls客户端的资源命名空间如ls.projects、ls.tasks、ls.annotations、ls.predictions、ls.views、ls.actions、ls.ml、ls.import_storage、ls.users展开。以 label_studio/tests/sdk/test_projects.py 为例创建项目、查询项目、更新标题等操作在 SDK 下只需要几个方法调用。使用 SDK 的核心收益原文档 sdk.md 总结了五大收益每一项都能在仓库测试代码中找到对应的落地实现简化的 API 交互SDK 把 HTTP 请求、序列化、错误处理封装成用户友好的 Python 方法与类。测试中ls.projects.create(...)返回可直接访问属性的对象如project.id、project.title无需手动解析 JSON。流水线集成SDK 可以嵌入任何已有的数据科学工作流。测试代码如 test_tasks.py展示了建项目 → 导任务 → 标注 → 导出这一完整链路在纯 Python 中的编排方式。自动化项目创建、任务导入、数据导出等重复性操作均可脚本化。例如 test_export.py 中用ls.projects.exports.as_pandas(project.id)一步完成标注数据 → pandas DataFrame的转换。增强的数据准备SDK 提供过滤器Filters与自定义配置label config能力。 test_annotations.py 中通过Filters.create结合Column、Operator、Type枚举构建查询筛选出未标注任务保证高质量标注。异步操作SDK 同时提供AsyncLabelStudio异步客户端用于处理大数据量下的并发请求提升性能详见下文异步操作一节。快速开始安装、认证与连接第一步安装 SDKpip install label-studio-sdk在本仓库中SDK 被作为开发与测试依赖使用声明于 pyproject.toml通过 git 引用固定版本这保证了仓库自带 SDK 集成测试始终针对某个确定的 SDK 版本运行也说明 SDK 与 Label Studio 服务端是同源演进、配套验证的。第二步准备访问令牌与服务器地址SDK 需要两个信息Label Studio 服务地址与API 密钥访问令牌。API 密钥在 Label Studio 界面右上角用户图标 →Account Settings中生成相关操作详见 访问令牌指南。Label Studio 提供两类令牌对 SDK 而言用法完全相同详见 access_tokens.md特性个人访问令牌PAT传统令牌Legacy Token有效期可在组织级设置 TTLEnterprise不自动过期可见性仅创建时可见一次始终列在账号设置中类型JWT 刷新令牌静态令牌吊销可手动吊销可手动吊销与 HTTP API 配合需先用POST /api/token/refresh换取短期 access token携带Authorization: Bearer token直接携带Authorization: Token token与 SDK 配合直接传入或设置环境变量只需配置一次直接传入或设置环境变量只需配置一次关于令牌的安全建议传统令牌因为必须手动吊销安全性弱于 PAT使用 HTTP API 时 PAT 换取的短期 access token 约 5 分钟过期过期后需重新换取返回 401这构成额外的安全层。第三步在脚本中建立连接原文档给出的最小连接代码# 定义 Label Studio 可访问的地址 LABEL_STUDIO_URL YOUR_BASE_URL # API key 可以是个人访问令牌或传统访问令牌 LABEL_STUDIO_API_KEY YOUR_API_KEY # 导入 SDK 与客户端模块 from label_studio_sdk import LabelStudio client LabelStudio(base_urlLABEL_STUDIO_URL, api_keyLABEL_STUDIO_API_KEY)同时令牌也支持通过环境变量注入。根据 access_tokens.md个人访问令牌可以直接写在脚本中或设置为LABEL_STUDIO_API_KEY环境变量SDK 会自动读取。推荐在 CI/CD 与共享脚本中使用环境变量方式避免把密钥写进代码库。深入客户端对象模型以测试套件为教材本仓库的 label_studio/tests/sdk 目录是 SDK 用法的权威活教材。下面按资源维度逐一展开每个示例均直接取自仓库测试代码。项目Projects创建、查询、更新、删除test_projects.py 展示了项目生命周期管理ls LabelStudio(base_urldjango_live_url, api_keybusiness_client.api_key) # 创建项目title 必填label_config 为标注界面 XML 配置 p ls.projects.create(titleNew Project, label_configLABEL_CONFIG_AND_TASKS[label_config]) # 按 id 获取项目 project ls.projects.get(idp.id) # 更新项目属性 ls.projects.update(idproject.id, titleUpdated Project) # 删除项目 ls.projects.delete(idproject.id) # 列出项目支持过滤与字段裁剪 projects list(ls.projects.list(filterpinned_only)) projects list(ls.projects.list(includeid,title,pinned_at,created_at,created_by))其中include参数用于按需裁剪返回字段减少传输数据量filter支持如pinned_only之类的服务端过滤。测试还验证了返回对象的字段可访问性例如project.created_by.email。任务Tasks创建、导入、批量操作与导出任务管理是 SDK 最常用的能力test_tasks.py 覆盖了完整 CRUD# 单条创建任务 task_data [{data: {my_text: Test task}}] for task in task_data: ls.tasks.create(projectp.id, datatask[data]) # 列出项目下所有任务 tasks [task for task in ls.tasks.list(projectp.id)] # 更新任务数据 ls.tasks.update(idtask_id, data{my_text: Updated task}) # 删除单条任务 ls.tasks.delete(idtask_id) # 批量导入任务推荐用于大批量场景 ls.projects.import_tasks(idp.id, requesttask_data) # 通过 actions 批量删除选中特定任务 ls.actions.create(projectp.id, iddelete_tasks, selected_items{all: False, included: tasks_ids_to_delete}) # 通过 actions 删除除某任务外的全部任务 ls.actions.create(projectp.id, iddelete_tasks, selected_items{all: True, excluded: [tasks[5].id]}) # 清空项目全部任务 ls.tasks.delete_all_tasks(idp.id)ls.projects.import_tasks是批量导入任务的标准入口它支持两种请求体形态参见 test_predictions.py简化形态只传字段映射如{my_text: Hello world, sentiment_class: Positive}配合preannotated_from_fields[sentiment_class]可从数据字段自动生成预测扩展形态传包含data、annotations、predictions的完整任务结构例如仓库 common.py 中定义的tasks_for_import——一个任务可同时携带标注结果annotations[].result[].value和模型预测predictions[].result与score用于一次性还原完整的标注项目。标注Annotations结构化创建与 CRUD标注是 SDK 最值得展开的能力因为它引入了类型安全的结构化 API。 test_annotations.py 展示了完整流程from label_studio_sdk.label_interface import LabelInterface from label_studio_sdk.label_interface.objects import AnnotationValue, TaskValue # 用 XML 配置构建 LabelInterface获得类型化的标注构建器 li LabelInterface(LABEL_CONFIG_AND_TASKS[label_config]) # 用 TaskValue 构造任务值对象model_dump() 转成可导入的字典 task_data TaskValue(data{my_text: Test task}) ls.projects.import_tasks(idp.id, request[task_data.model_dump()]) # 通过 li.get_control(tag_name).label(...) 构造符合标签配置的结果 annotation_data AnnotationValue( result[li.get_control(sentiment_class).label([Positive])], completed_bybusiness_client.user.id, ).model_dump() new_annotation ls.annotations.create(task_id, resultannotation_data[result]) # 更新标注结果值被替换为 Negative ls.annotations.update(idannotation_id, result[li.get_control(sentiment_class).label([Negative])]) # 按任务列出标注 annotations ls.annotations.list(task_id) # 删除标注 ls.annotations.delete(idannotation_id)对于视觉标注如目标检测label(...)支持坐标参数。测试中构造了一个矩形框标注annotation_data AnnotationValue( result[li.get_control(bbox).label([Car], x10, y20, width100, height100)], completed_bybusiness_client.user.id, ).model_dump()生成的result[0][value]为{rectanglelabels: [Car], x: 10, y: 20, width: 100, height: 100, rotation: 0}与编辑器内部存储格式完全一致。此外LabelInterface.create(...)还可以用 Python 字典以编程方式生成标签配置test_annotations.py例如from label_studio_sdk.label_interface.create import labels label_config LabelInterface.create({ image1: Image, bbox: labels([Car, Truck, Van], tag_typeRectangleLabels), })测试还验证了标注与任务完成状态的联动使用Column.completed_at为空的过滤器查询时未标注任务不会出现在结果中一旦写入标注该任务立即可被过滤器捕获详见 test_annotations.py。数据过滤与视图Filters ViewsSDK 提供了一套面向数据管理器的类型化过滤 API用于精准筛选任务子集。构建过滤器的要素包括Column数据列如Column.id、Column.completed_atOperator操作符如Operator.EMPTY、Operator.EQUAL、Operator.GREATER_OR_EQUAL、Operator.LESS_OR_EQUALType字段类型如Type.Datetime、Type.NumberFilters过滤器组合容器支持Filters.AND/Filters.OR逻辑示例test_annotations.pyfrom label_studio_sdk.data_manager import Column, Filters, Operator, Type import json filters Filters.create( Filters.OR, [Filters.item(Column.completed_at, Operator.EMPTY, Type.Datetime, Filters.value(False))], ) query json.dumps({filters: filters}) # 将 query 传给 tasks.list 进行服务端过滤 labeled_tasks [task for task in ls.tasks.list(projectp.id, queryquery, fieldsall)]过滤器还可以持久化为视图View之后可按视图拉取任务test_views.pyfilters Filters.create( Filters.AND, [ Filters.item(Column.id, Operator.GREATER_OR_EQUAL, Type.Number, Filters.value(1)), Filters.item(Column.id, Operator.LESS_OR_EQUAL, Type.Number, Filters.value(100)), ], ) view ls.views.create(projectproject.id, datadict(titleTest View, filtersfilters)) # 列出项目全部视图 views ls.views.list(projectproject.id) # 按视图 id 获取任务返回过滤后的任务子集支持排序字段 tasks [task for task in ls.tasks.list(viewview.id)]视图数据支持ordering字段如- Column.id表示按 id 降序详见 fixtures.py。预测Predictions写入、导入与版本管理SDK 对模型预测提供了完整支持test_predictions.pyfrom label_studio_sdk.label_interface.objects import PredictionValue # 为指定任务创建预测 pv PredictionValue( result[li.get_control(sentiment_class).label([Positive])], score0.9, model_version1.0.0, ) prediction ls.predictions.create(tasktask.id, **pv.model_dump()) # 读取 / 列出 / 删除 prediction ls.predictions.get(idprediction.id) predictions ls.predictions.list(tasktask.id) ls.predictions.delete(idprediction.id) # 批量导入预测一次请求创建多条 response ls.projects.import_predictions(idproject.id, requestpredictions_payload) assert response.created 3两点值得注意的实现细节同样来自测试断言model_version强校验项目存在已登记的模型版本时用未登记的model_version更新项目会抛出label_studio_sdk.core.api_error.ApiErrorHTTP 状态码 400响应体包含validation_errorstest_predictions.py。因此引入新模型时应先通过ls.projects.update(idp.id, model_versionx.y.z)登记版本。简化导入自动预标注import_tasks传入preannotated_from_fields[sentiment_class]时SDK 会把任务数据中的该字段转换为预测省去手工构造 result 的步骤。ML 后端集成与批量动作SDK 可以注册 ML 后端并对任务批量触发预测整个流程在 test_ml.py 中有端到端验证# 注册 ML 后端 ls.ml.create(urlhttp://test.ml.backend.for.sdk.com:9092, projectp.id, titleModelSingle) # 确认 ML 后端已创建 ml_backend ls.ml.list(projectp.id) # 通过 actions 对指定任务批量触发预测排除 tasks[1] ls.actions.create( idretrieve_tasks_predictions, projectp.id, selected_items{all: True, excluded: [tasks[1].id]}, ) # 通过 actions 将预测转成标注 ls.actions.create( idpredictions_to_annotations, projectp.id, selected_items{all: False, included: [predictions[0].task, predictions[1].task]}, )actions.create的selected_items支持{all: True, excluded: [...]}排除法与{all: False, included: [...]}选择法两种模式。批量预测返回的预测记录会带上 ML 后端的model_version即注册时的title与score随后可一键转换为正式标注——这是模型预标注 → 人工确认流水线的核心闭环。外部存储连接Import Storages对于 S3、GCS、Azure Blob、本地目录等外部存储SDK 提供了import_storage/export_storage命名空间。 test_storages.py 以 S3 为例验证了建连接 → 配置 → 同步三步# 创建 S3 导入存储连接 storage_resp ls.import_storage.s3.create( projectp.id, bucketpytest-s3-images, regex_filter.*, # 文件名匹配规则 use_blob_urlsFalse, # 是否使用 blob URL recursive_scanTrue, # 是否递归扫描子目录 ) # 读取与更新连接配置 storage ls.import_storage.s3.get(idstorage_id) ls.import_storage.s3.update(idstorage_id, use_blob_urlsTrue) # 触发一次同步把存储中的文件作为任务拉入项目 resp ls.import_storage.s3.sync(idstorage_id)测试特别验证了recursive_scan的行为差异为False时只导入根目录文件如image1.jpg为True时连子目录文件如subdir/another/image2.jpg一并导入导入后每个任务可通过storage_filename属性追溯到源文件。用户管理test_users.py 展示了如何通过 SDK 邀请/创建组织成员u ls.users.create(**{ email: test_memberexample.com, username: test_memberexample.com, first_name: Test, last_name: Member, }) assert u.id in [u.id for u in ls.users.list()]数据导出JSON、pandas 与流式下载导出是 SDK 的高频能力test_export.py 给出了三种形态# 1) 查询项目支持的导出格式 formats ls.projects.exports.list_formats(project.id) # 2) 直接导出为 JSON 列表 json_data ls.projects.exports.as_json(project.id) # 3) 直接导出为 pandas DataFrame适合直接进入模型训练/分析 df ls.projects.exports.as_pandas(project.id) # 4) 底层同步下载字节流可控制是否包含全部任务 data ls.projects.exports.download_sync(project.id, download_all_tasksTrue)其中as_pandas还可透传创建参数如{task_filter_options: {finished: only}}只导出已标注完成的任务。从测试断言看download_sync返回字节流需自行组装为 JSON 解析测试中通过BytesIO累积分块后json.load完成反序列化。异步操作AsyncLabelStudio原文档特别强调了 SDK 的异步能力。SDK 提供AsyncLabelStudio客户端接口与同步客户端一一对应适用于大批量任务的并发导入、导出与预测。仓库测试中的使用形态test_export.pyfrom label_studio_sdk import AsyncLabelStudio ls AsyncLabelStudio(base_urldjango_live_url, api_keybusiness_client.api_key) project await ls.projects.create(titleExport Test Project, label_configLABEL_CONFIG_AND_TASKS[label_config]) await ls.projects.import_tasks(idproject.id, requestLABEL_CONFIG_AND_TASKS[tasks_for_import]) json_data await ls.projects.exports.as_json(project.id) df await ls.projects.exports.as_pandas(project.id)说明上述异步测试用例在当前仓库环境中因pytest-asyncio未启用而被跳过测试文件中有pytest.mark.skip标注但这只是仓库测试运行条件的限制AsyncLabelStudio类本身由 SDK 提供。在数据量较大、需要并发吞吐的场景下应优先使用异步客户端。测试即文档如何验证你的 SDK 集成本仓库在 label_studio/tests/sdk 下提供了完整、可运行的 SDK 集成测试基于 Django 测试框架与真实的内存数据库覆盖项目、任务、标注、预测、视图、存储、ML 后端、用户与导出等全部资源。这些测试既是对 SDK 的回归保障也是学习 SDK 用法的第一手样例——当你需要确认某个 SDK 方法的确切参数与返回结构时直接查阅对应测试文件即可例如项目生命周期test_projects.py任务批量操作与删除test_tasks.py标注结构化创建与过滤器联动test_annotations.py预测 CRUD 与批量导入test_predictions.py视图持久化与按视图取数test_views.py、fixtures.py外部存储同步test_storages.pyML 后端批量预测与预测转标注test_ml.py多种导出形态与异步客户端test_export.py测试中反复出现的 common.py 定义了一套标准的文本分类标签配置TextChoices含 Positive/Neutral/Negative与任务 标注 预测完整样例数据可作为自行编写 SDK 脚本时构造测试数据的模板。常见注意事项令牌安全优先使用个人访问令牌PAT并通过LABEL_STUDIO_API_KEY环境变量注入PAT 与 HTTP API 配合时需要先调用POST /api/token/refresh换取短期 access token详见 access_tokens.md而 SDK 中两者用法一致仅需配置一次。model_version一致性写入预测或更新项目时模型版本必须已在项目中登记否则 SDK 会抛出ApiError400。批量操作优先使用 actions删除大量任务、批量触发预测、预测转标注等场景统一通过ls.actions.create(id..., selected_items...)实现支持选择法与排除法两种任务子集表达避免逐条循环调用 API。大数据量场景使用异步客户端需要并发处理海量任务时改用AsyncLabelStudio与await语法充分利用异步 I/O 提升吞吐。类型化对象先行构造标注/预测/任务时优先使用LabelInterface、TaskValue、AnnotationValue、PredictionValue等类型化对象通过model_dump()输出字典能显著降低手写嵌套字典出错的概率。【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考