Label Studio Python 库

Label Studio Python 库方便了从 Python 应用程序中调用 Label Studio API。

文档

点击此处浏览 Label Studio API 文档。

安装

pip install --upgrade label-studio-sdk
# 或使用 poetry
poetry add label-studio-sdk

用法

from label_studio_sdk import LabelStudio

client = LabelStudio(
    base_url='YOUR_LABEL_STUDIO_URL',  
    api_key="YOUR_API_KEY",
)

命令行工具

SDK 还附带一个命令行入口，映射了 SDK 中的资源和方法的用法。

在叶子命令（例如 projects create）上，使用 -h 可查看简洁帮助（一行摘要、SDK 签名和选项），使用 --help 可查看完整生成的文档（参数、示例、返回结构和选项）。顶层组只支持 --help。

export LABEL_STUDIO_API_KEY="YOUR_API_KEY"
export LABEL_STUDIO_URL="YOUR_BASE_URL"

# 单个命令的简洁帮助
label-studio-sdk projects create -h

# 完整帮助（较长）
label-studio-sdk projects create --help

# 顶层帮助
label-studio-sdk --help

# 列出项目
label-studio-sdk projects list

# 创建项目（通用 key=value 参数）
label-studio-sdk projects create \
  --param title="CLI 示例" \
  --param 'label_config=<View><Text name="text" value="$text"/></View>'

通过 uv 运行命令行

# 从 PyPI
uv run --with label_studio_sdk label-studio-sdk --help

# 从 GitHub
uv run --with git+https://github.com/HumanSignal/label-studio-sdk.git label-studio-sdk --help

# 从本地
uv run --with-editable . label-studio-sdk --help

界面命令行

使用 label-studio-sdk interface 可以从本地界面 JSX 文件中搭建、验证、预览、同步和启动项目。详见界面命令行指南。

版本

SDK 2.0.0

我们于 2025 年 8 月发布了 SDK 2.0.0 版本。

此版本在文档和功能上相比 SDK 1 有若干改进。

增强功能

仅企业版

• 新增 projects.stats.iaa 端点，用于返回注释者间一致性矩阵的统计信息。
• 现在可以更新带有评论的任务。
• 为 S3s（使用 IAM 角色的 S3）导出增加了 sync 支持。

企业版和开源版

• 扩展支持所有项目设置，其中许多在 SDK 1 中缺失。例如在企业环境中，现在可以配置 assignment_settings、review_settings、annotator_evaluation 等。
• 修复了 actions.list() 中传递 project 参数的问题（SDK 1 中存在错误）。
• 请求/响应验证机制更加宽松，减少了 SDK 2 中的 pydantic 错误。

破坏性变更

仅企业版

• comments.create 不再接受 project 参数。
• 在 prompts.indicators 中，pk 参数更名为 id。
• 在 prompts.runs 和 prompts.versions 中，id 参数更名为 prompt_id。
• workspaces.members.list 的响应返回对象而非字典。

企业版和开源版

• 在 projects.exports 调用中，项目 ID 现在作为 id 传递，导出 ID 作为 export_pk 传递。
• 任务响应中返回的预测结果现在是对象而非字典。

SDK 1.0+

SDK 1 于 2024 年 6 月发布。

如果在任何自动化流程中使用 Label Studio SDK 1 包，强烈建议在解决破坏性变更之前，将 SDK 版本锁定在 <2.0.0。

旧版 SDK（<1）

label-studio-sdk<1 版本已弃用且不再支持。建议更新到最新版本。

git clone https://github.com/HumanSignal/label-studio-sdk.git
cd label-studio-sdk
git fetch origin
git checkout release/0.0.34

from label_studio_sdk import Client
from label_studio_sdk.data_manager import Filters, Column, Operator, Type
from label_studio_sdk._legacy import Project

示例：创建一个新项目并添加任务

# 导入 SDK 和客户端模块
from label_studio_sdk import LabelStudio

client = LabelStudio(
    base_url="http://localhost:8080",   # 替换为你的 LS URL
    api_key="YOUR_API_KEY",             # 替换为你的 API 密钥
)

label_config = """
<View>
  <Header value="选择文本情感："/>
  <Text name="text" value="$text"/>
  <Choices name="sentiment" toName="text" choice="single">
    <Choice value="正面"/>
    <Choice value="负面"/>
    <Choice value="中性"/>
  </Choices>
</View>
"""

# 创建项目
project = client.projects.create(
    title="情感分类",
    label_config=label_config
)

# （可选）验证配置以尽早发现错误
client.projects.validate_label_config(id=project.id, label_config=label_config)

# 创建一个任务
task = client.tasks.create(
    project=project.id,
    data={"text": "Label Studio 是最好的！"}  # 'text' 与 value="$text" 对应
)
print(f"创建的任务 ID: {task.id}")

# 或批量创建多个任务
client.projects.import_tasks(
    id=project.id,
    request=[
        {"text": "我喜欢 Label Studio"},
        {"text": "Label Studio 帮我更快发布产品"},
    ]
)

更多示例，请参阅我们的 API 参考文档。

贡献

请按照此指南参与 SDK 的贡献

虽然我们重视对该 SDK 的开源贡献，但本库是以程序化方式生成的。直接对本库的修改需要迁移到我们的生成代码中，否则将在下一次生成发布时被覆盖。欢迎提交 PR 作为概念验证，但我们无法按原样合并。建议先提一个 issue 与我们讨论！

另一方面，对 README 的贡献始终非常欢迎！