将数据导入Label Studio

通过导入文件、引用URL或与云存储或数据库同步，将数据导入Label Studio。

• 如果您的数据存储在云存储桶中，请参阅从云或数据库存储同步数据。
• 如果您的数据存储在Redis数据库中，请参阅从云或数据库存储同步数据。
• 如果你的数据存储在互联网可访问的URL、文件或目录中，从Label Studio界面导入。
• 如果您的数据存储在本地，将其导入Label Studio。
• 如果您的数据包含预测或预标注内容，请参阅将预标注数据导入Label Studio。

数据导入通用指南

• 为获得最佳性能，建议每个项目保持约10万个任务/10万个标注。
• 避免频繁导入，因为每次新导入都需要耗时的后台操作。每30秒导入一次可避免系统过载。

可导入Label Studio的数据类型

您可以导入多种类型的数据，包括文本、时间序列、音频和图像数据。支持的文件类型取决于数据类型。

* 仅限云存储

+ 仅限Label Studio企业版和Starter云版

如果您未找到想要导入的受支持数据类型或文件类型，请通过提交问题至Label Studio Repository告知我们。

如何导入您的数据

导入数据最安全可靠的方法是将数据存储在Label Studio外部，并通过URL引用导入数据。您可以在TXT、CSV或TSV文件中导入URL列表，或在JSON任务格式中引用这些URL。

如果您要导入音频、图像或视频数据，必须使用URL来引用这些数据类型。

If you’re importing HTML, text, dialogue, or timeseries data using the , , , or tags in your labeling configuration, you can either load data directly, or load data from a URL.

• 要从URL加载数据，请在标注配置中指定valueType="url"。
• 要将数据直接加载到Label Studio数据库中，对于HyperText或Text数据需指定valueType="text"，对于Paragraph或TimeSeries数据则需指定valueType="json"。

<View> 
  <Text name="text1" value="text" valueType="text"> 
</View>

{
  "text": "My awesome opossum"
}

text
My awesome opossum

<View> 
  <Text name="text1" value="text" valueType="url"> 
</View>

{
  "text": "http://example.com/text.txt"
}

text
http://example.com/text.txt

如何检索数据

在Object标签中显示数据需要经过几个步骤。这些数据检索过程同样适用于动态选项和标签功能。请在Object标签中使用以下参数。

value (必填)

value参数表示数据来源。它可以是纯文本，也可以是复杂数据检索系统中的一个步骤。可以使用以下形式表示： value（必填）

变量

在大多数情况下，Object标签的值中包含一个变量（以$为前缀）。

例如，会在导入的JSON对象中查找"audio"字段：

{
  "data": {
    "audio": "https://host.name/myaudio.wav"
  }
}

纯文本

value参数可以是一个字符串。这对Header和Text很有用。

此外，您可以使用标签的内容作为值。这对于描述性文本标签非常有用，并且适用于Label和Choice。

例如：

<Header>Label audio:</Header>
<Header value="Label only fully visible cars" />
<Text name="instruction" value="Label only fully visible cars" />
<Label>cat</Label>

<Choice>other</Choice>

其他情况

1. value 参数可以是一个包含以$为前缀变量的文本。

   例如：

   <Header value="url: $image"/>

2. value 参数也可以引用数组和字典中的嵌套数据（$texts[2] 和 $audio.url）。

   例如：

   <Image name="image" value="$images[0]"/>

valueType (可选)

valueType参数定义了如何处理从前序步骤获取的数据。 有两种选项，分别是"url"和原始数据。目前原始数据输入可以是"text"或"json"。"text"用于HyperText和Text标签，而"json"用于TimeSeries标签。

例如：

• 使用“url”： 显示由URL加载的文本。

• 使用“text”： 显示URL但不加载文本内容。

resolver (可选)

使用此参数从S3或其他云存储的多列CSV中检索数据。Label Studio只能在运行时获取数据，因此是安全的。

如果您导入一个包含任务列表的文件，且该列表中的每个任务都是指向存储中另一个文件的链接。在这种情况下，您可以使用resolver参数从存储中检索这些文件的内容。

使用场景

这里有一个任务列表，其中每个任务的“remote”字段都指向存储中的一个CSV文件链接。每个CSV文件都包含一个待标注文本的“text”列。例如：

任务:

[
    { "remote": "s3://bucket/text1.csv" },
    { "remote": "s3://bucket/text2.csv" }
]

CSV文件：

id;text
12;The most flexible data annotation tool. Quickly installable. Build custom UIs or use pre-built labeling templates.

解决方案

要检索文件，请使用以下参数：

1. value="$remote": S3上CSV文件的URL位于任务数据的"remote"字段中。如果使用resolver参数，则value始终被视为URL，因此无需设置valueType。

2. resolver="csv|separator=;|column=text": 在运行时加载此文件，将其解析为CSV格式，并从第一行获取"text"列。

3. 显示结果。

语法

resolver 参数的语法由一系列选项组成，各选项之间用 | 符号分隔。

第一个选项是文件类型。

其余选项是带有可选值的指定文件类型的参数。CSV文件的参数包括：

• headless: CSV文件没有表头（该参数为布尔类型且不能赋值）。
• separator=;: CSV分隔符，通常可以自动检测。
• column=1: 在headless模式下使用从零开始的索引，否则使用列名。

例如，resolver="csv|headless|separator=;|column=1"

如何格式化数据以便导入

Label Studio 对不同文件类型采取不同的处理方式。

如果您想同时导入多种类型的数据进行标注，例如带有说明文字的图片或带有转录文本的音频录音，您必须使用Label Studio基础JSON格式。

您也可以使用CSV文件或JSON任务列表来指向包含数据的URL，当需要导入数千个文件时，这比直接导入数据更高效。您可以将最多包含250,000个任务或最大50MB的文件导入Label Studio。

如果您在云存储桶或容器中指定数据，并且不想同步云存储，可以在JSON、CSV、TSV或TXT文件中创建并指定Amazon S3存储的预签名URL、Google云存储的签名URL或Microsoft Azure的共享访问签名。

Label Studio 基础 JSON 格式

将数据导入Label Studio的最佳方式是使用JSON格式的任务列表。JSON文件的data键将每个任务引用为JSON字典中的一个条目。如果没有data键，Label Studio会将整个JSON文件解释为一个任务。

在data JSON字典中，使用与项目设置的标签配置中对象标签期望的源键相对应的键值对。

根据对象标签的类型，Label Studio 对字段值的解析方式有所不同：

• : value 被解析为纯文本。
• : value is interpreted as HTML markup.
• : value is interpreted as a base64 encoded HTML markup.
• : value 被解释为服务器端启用了CORS策略的音频文件的有效URL。
• : value被解析为图像文件的有效URL
• : 当valueType="url"时，value会被解析为CSV/TSV文件的URL地址；当valueType="json"时，则会被解析为包含列数组的JSON字典："value": {"first_column": [...], ...}。更多详情请参阅如何使用valueType。

您可以向JSON文件添加其他可选键。

有关导出任务JSON格式的更多详情，请参阅导出文档中的相关JSON属性描述。

JSON格式示例

对于一个文本分类项目的示例，您可以设置如下的标签配置：

<View>
  <Text name="message" value="$my_text"/>
  <Choices name="sentiment_class" toName="message">
    <Choice value="Positive"/>
    <Choice value="Neutral"/>
    <Choice value="Negative"/>
  </Choices>
</View>

然后您可以导入符合以下JSON格式的文本任务进行标注：

[{
  # "data" must contain the "my_text" field defined in the text labeling config as the value and can optionally include other fields
  "data": {
    "my_text": "Opossums are great",
    "ref_id": 456,
    "meta_info": {
      "timestamp": "2020-03-09 18:15:28.212882",
      "location": "North Pole"
    } 
  },

  # annotations are not required and are the list of annotation results matching the labeling config schema
  "annotations": [{
    "result": [{
      "from_name": "sentiment_class",
      "to_name": "message",
      "type": "choices",
      "readonly": false,
      "hidden": false,
      "value": {
        "choices": ["Positive"]
      }
    }]
  }],

  # "predictions" are pretty similar to "annotations" 
  # except that they also include some ML-related fields like a prediction "score"
  "predictions": [{
    "result": [{
      "from_name": "sentiment_class",
      "to_name": "message",
      "type": "choices",
      "readonly": false,
      "hidden": false,
      "value": {
        "choices": ["Neutral"]
      }
    }],
  # score is used for active learning sampling mode
    "score": 0.95
  }]
}]

包含多个任务的JSON示例

如果您仅通过Label Studio导入对话框（数据管理器 => 导入按钮）上传JSON文件，或从云存储导入时，可以在一个JSON文件中放置多个任务。使用云存储时，必须确保文件中的每个任务都采用相同的格式。

如果您使用的是Source云存储，您还可以将多个任务放置在一个以换行符分隔的JSON文件（JSONL/NDJSON）中。

[
   {
      "id":1,
      "data":{
         "my_text":"Opossums like to be aloft in trees."
      }
   },
   {
      "id":2,
      "data":{
         "my_text":"Opossums are opportunistic."
      }
   },
   {
      "id":3,
      "data":{
         "my_text":"Opossums like to forage for food."
      }
   }
]

[
   {
      "my_text":"Opossums like to be aloft in trees."
   },
   {
      "my_text":"Opossums are opportunistic."
   },
   {
      "my_text":"Opossums like to forage for food."
   }
]

旧版Label Studio的JSON示例

如果您仍在使用Label Studio 1.0.0之前的版本，请参考此示例JSON格式。

[{
  # "data" must contain the "my_text" field defined by labeling config,
  # and can optionally include other fields
  "data": {
    "my_text": "Opossums are great",
    "ref_id": 456,
    "meta_info": {
      "timestamp": "2020-03-09 18:15:28.212882",
      "location": "North Pole"
    } 
  },

  # completions are the list of annotation results matching the labeling config schema
  "completions": [{
    "result": [{
      "from_name": "sentiment_class",
      "to_name": "message",
      "type": "choices",
      "value": {
        "choices": ["Positive"]
      }
    }]
  }],

  # "predictions" are pretty similar to "completions" 
  # except that they also include some ML-related fields like a prediction "score"
  "predictions": [{
    "result": [{
      "from_name": "sentiment_class",
      "to_name": "message",
      "type": "choices",
      "value": {
        "choices": ["Neutral"]
      }
    }],
  # score is used for active learning sampling mode
    "score": 0.95
  }]
}]

导入CSV或TSV数据

当你导入CSV/TSV格式的文本文件时，Label Studio会将列名解析为任务数据键，这些键对应于你设置的标注配置：

my_text,optional_field
this is a first task,123
this is a second task,456

纯文本

将数据导入为纯文本格式。Label Studio会将纯文本文件中的每一行解析为独立的数据标注任务。

如果您的标注任务只有单一数据流输入，且标签配置中仅指定了一个object标签，那么可以使用纯文本格式进行标注。

this is a first task
this is a second task

如果您希望导入整个纯文本文件，而不是每行都成为一个新的标注任务，可以自定义标注配置，在Text标签中指定valueType="url"。请参阅Text标签文档。了解更多关于如何使用valueType字段的信息。

Import HTML data

You can import HyperText data in HTML-formatted files and annotate them in Label Studio. When you directly import HTML files, the content is minified by compressing the text, removing whitespace and other nonfunctional data in the HTML code. Annotations that you create are applied to the minified version of the HTML.

If you want to label HTML files without minifying the data, you can do one of the following:

• Import the HTML files as BLOB storage from external cloud storage such as Amazon S3 or Google Cloud Storage.
• 在你的标注配置中更新HyperText标签，按照本页如何导入数据中所述指定valueType="url"。

从本地目录导入数据

要从本地目录导入数据，您有两种选择：

• 运行一个网络服务器来生成文件的URL，然后上传一个引用这些URL的文件到Label Studio。
• 在Label Studio界面中将文件目录添加为源或目标本地存储连接。

运行网络服务器以生成本地文件的URL

要运行一个网络服务器来生成文件的URL，你可以参考Label Studio仓库中提供的辅助shell脚本或编写自己的脚本。使用该脚本执行以下操作：

1. 在包含您希望Label Studio导入的文件目录的机器上，调用辅助脚本并指定正则表达式模式以匹配要导入的文件。在此示例中，脚本识别具有JPG文件扩展名的文件：

   ./script/serve_local_files.sh  *.jpg

   该脚本收集由该HTTP服务器提供的文件链接，并将它们保存到files.txt文件中，每行一个URL。
2. 使用Label Studio界面将包含URL的文件导入Label Studio。

如果您的标注配置支持超文本或多数据类型，请使用Label Studio JSON格式来指定本地文件位置，而非txt文件。查看此格式示例。

如果您通过如下方式创建的HTTP服务器提供数据：python -m http.server 8081 -d，可能需要为该服务器设置CORS，以便Label Studio能够成功访问数据文件。如有需要，请从命令行运行以下命令：

npm install http-server -g
http-server -p 3000 --cors

在Label Studio界面中将文件目录添加为源存储

如果您在Docker上运行Label Studio并希望添加本地文件存储，需要挂载文件目录并设置环境变量。请参阅Run Label Studio on Docker and use local storage。

从Label Studio界面导入数据

要通过Label Studio界面导入数据，请执行以下操作：

1. 在Label Studio用户界面中，打开特定项目的数据管理页面。
2. 点击导入打开导入对话框。
3. 从文件或URL导入您的数据。

您导入的数据是项目特定的。

通过API导入数据

通过Label Studio API导入您的数据。请参阅导入任务的API文档。

从命令行导入数据

在Label Studio 1.0.0之前的版本中，您可以通过命令行从本地目录导入数据。

要从命令行导入数据，请执行以下操作：

1. 启动Label Studio并使用命令行参数指定数据路径和数据格式。
   例如：
   label-studio init --input-path my_tasks.json --input-format json
2. 打开Label Studio界面，确认您的数据已正确导入。

您可以使用--input-path参数指定要标注数据的文件或目录。通过--input-format参数可以指定其他数据格式。例如运行以下命令启动Label Studio并从本地目录导入音频文件：

label-studio init my-project --input-path=my/audios/dir --input-format=audio-dir --label-config=config.xml --allow-serving-local-files

默认情况下，Label Studio 期望使用 基本 Label Studio JSON 格式 的 JSON 格式化任务。

如果在Label Studio启动后向本地目录添加更多文件，必须重新启动Label Studio才能导入新增文件中的任务。