Label Studio 数据导入全解：文件类型、JSON 任务格式、valueType 与 API 实战

Label Studio 数据导入全解：文件类型、JSON 任务格式、valueType 与 API 实战

【免费下载链接】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 官方文档 Get data into Label Studio 展开，系统讲解如何将文本、音频、图像、视频、时间序列等多类型数据导入 Label Studio 项目：包括支持的文件类型与扩展名白名单、标准 JSON 任务格式的完整字段说明、value/valueType/resolver数据解析机制、本地目录与 UI 导入操作，以及如何通过 REST API 以数据、文件、URL 三种方式批量导入。读完本文，你可以独立完成从小样本验证到大规模 URL 引用式导入的完整数据接入方案，并能对照源码验证导入限额与解析流程。

一、导入前的通用建议

官方文档给出了两条核心经验法则：

• 单项目规模建议：为保持最佳性能，建议每个项目保持约 10 万任务 / 10 万标注以内；
• 控制导入频率：每次导入都会触发较长的后台操作，建议至少每 30 秒一次，避免频繁导入造成系统过载。

对于大型项目或业务关键项目，官方强烈不建议通过 Label Studio 界面直接上传媒体文件（尤其是图像、音频、视频、时间序列等文件）。原因如下：

通过 UI 上传数据适合概念验证（PoC）项目，但不适合大规模项目。Label Studio 并非设计为大规模媒体托管服务，且不会对已导入的媒体资源做备份。

通过 UI 上传媒体后，你将在以下场景遇到麻烦：

• 导入带 predictions（预测结果）的任务；
• 导出数据；
• 将数据迁移到另一个 Label Studio 实例；
• 重新部署 Label Studio。

官方建议：改用源存储（source storage）配置，将数据存放在外部存储中，Label Studio 只保存数据引用。

如果数据在云存储桶或 Redis 数据库中，应走云/数据库存储同步流程；如果数据带有预测或预标注，参考导入预标注数据。

二、可导入的数据类型与文件扩展名

Label Studio 支持导入文本、时间序列、音频、图像等多种数据，具体支持的文件类型如下（摘自官方文档）：

* 仅云存储支持；+ 仅 Label Studio Enterprise 和 Starter Cloud 支持。

从源码看，上传文件的扩展名白名单由 SUPPORTED_EXTENSIONS 定义，包含.bmp、.csv、.flac、.gif、.htm、.html、.jpg、.jpeg、.json、.m4a、.mp3、.ogg、.png、.svg、.tsv、.txt、.wav、.xml、.mp4、.webm、.webp、.pdf等。该白名单在 check_extensions 中执行——上传或 URL 导入时，扩展名不在集合内会直接抛出ValidationError，与文档描述一致。

三、导入方式选择与 valueType 机制

3.1 推荐做法：导入 URL 引用而非媒体本体

最安全可靠的导入方式是：将数据存放在 Label Studio 外部，导入时只导入数据引用（URL）。你可以：

• 用 TXT、CSV、TSV 文件组织一份 URL 清单；
• 或在 JSON 任务格式中用字段引用 URL。

关键约束：导入音频、图像、视频数据时，必须使用 URL 引用。而使用<HyperText>、<Text>、<Paragraphs>、<TimeSeries>标签时，则既可以从 URL 加载，也可以把数据直接载入数据库，由标签的valueType决定：

• 从 URL 加载：valueType="url"；
• 直接存入数据库：HyperText/Text用valueType="text"，Paragraph/TimeSeries用valueType="json"。

注意：若从 URL 加载数据，数据本身不会被 Label Studio 保存。如果你希望导出的标注任务包含被标注的数据本体，必须不用 URL 引用、把数据导入数据库，或在导出后自行把数据与标注合并。

3.2 两种 valueType 的配置示例

以文本分类为例，valueType="text"的完整示例：

标签配置（XML）：

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

导入的 JSON 文件：

{ "text": "My awesome opossum" }

导入的 CSV 文件：

text My awesome opossum

valueType="url"的对应示例：

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

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

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

3.3value：数据取值的三种形态

Label Studio 按以下优先级和形式从任务数据中取数以渲染Object标签（该机制同样用于动态选项和标签渲染）：

1. 变量：最常见形态，value中带$前缀的变量名。例如<Audio value="$audio" ... />会在导入的 JSON 对象中查找audio字段：

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

2. 纯文本：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>

3. 其他情况：

   • value可以是包含$变量的文本片段，如<Header value="url: $image"/>；
   • 也可以引用数组和字典中的嵌套数据（$texts[2]、$audio.url），例如<Image name="image" value="$images[0]"/>。

3.4valueType参数

valueType定义上一步取回的数据如何被处理，取值：

• url：如<Text name="text1" value="$text" valueType="url"/>会加载 URL 指向的文本再显示；
• text/json（原始数据）：如<Text name="text" value="$text" valueType="text"/>则直接显示 URL 字符串本身而不加载内容；json用于TimeSeries等标签。

3.5resolver参数：运行时解析云存储中的多列 CSV

resolver用于从 S3 等云存储上的多列 CSV 中按需取列，且只在运行期读取，安全性更好。典型场景：任务列表中的每个任务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"——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"。

四、标准 JSON 任务格式

官方推荐用JSON 任务列表导入数据。JSON 文件中的data键把每个任务组织为 JSON 字典条目；若没有data键，Label Studio 会把整个 JSON 解释为一个任务（源码中read_tasks_list_from_json对此有对应处理，见 FileUpload.read_tasks_list_from_json：缺少data的条目会被自动包成{"data": task}）。

data字典的键值对应你在标签配置中对象标签所期望的源键。不同对象标签对字段值的解释方式不同：

• <Text value="$key">：值解释为纯文本；
• <HyperText value="$key">：值解释为 HTML 标记；
• <HyperText value="$key" encoding="base64">：值解释为 base64 编码的 HTML 标记；
• <Audio value="$key">：值解释为启用 CORS 的音频文件 URL；
• <Image value="$key">：值解释为图像文件 URL；
• <TimeSeries value="$key">：valueType="url"时解释为 CSV/TSV 文件 URL；valueType="json"时解释为列数组 JSON 字典，形如"value": {"first_column": [...], ...}。

JSON 中还可以包含两个可选键：

4.1 完整示例：文本分类任务

标签配置：

<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" 必须包含标签配置中定义的 "my_text" 字段，可另含其他字段 "data": { "my_text": "Opossums are great", "ref_id": 456, "meta_info": { "timestamp": "2020-03-09 18:15:28.212882", "location": "North Pole" } }, # annotations 非必填，是符合标签配置 schema 的标注结果列表 "annotations": [{ "result": [{ "from_name": "sentiment_class", "to_name": "message", "type": "choices", "readonly": false, "hidden": false, "value": { "choices": ["Positive"] } }] }], # "predictions" 与 "annotations" 类似， # 但还包含 score 等 ML 相关字段 "predictions": [{ "result": [{ "from_name": "sentiment_class", "to_name": "message", "type": "choices", "readonly": false, "hidden": false, "value": { "choices": ["Neutral"] } }], # score 用于主动学习采样模式 "score": 0.95 }] }]

4.2 单文件多任务

通过 UI 的 Import 对话框上传或从云存储导入时，可以在一个 JSON 文件中放置多个任务（使用云存储时须保证文件内每个任务格式一致；源云存储还支持换行分隔的 JSONL/NDJSON 文件）。示例（不含标注/预测的多文本分类任务，id参数非必填）：

[ { "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." } } ]

在没有 annotations/predictions 时，也可直接使用data字段内容的裸列表：

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

4.3 旧版本（1.0.0 之前）的 JSON 格式

1.0.0 之前的版本使用completions键代替annotations：

[{ # "data" 必须包含标签配置定义的 "my_text" 字段，可另含其他字段 "data": { "my_text": "Opossums are great", "ref_id": 456, "meta_info": { "timestamp": "2020-03-09 18:15:28.212882", "location": "North Pole" } }, # completions 是符合标签配置 schema 的标注结果列表 "completions": [{ "result": [{ "from_name": "sentiment_class", "to_name": "message", "type": "choices", "value": { "choices": ["Positive"] } }] }], # "predictions" 与 "completions" 类似， # 但还包含 score 等 ML 相关字段 "predictions": [{ "result": [{ "from_name": "sentiment_class", "to_name": "message", "type": "choices", "value": { "choices": ["Neutral"] } }], # score 用于主动学习采样模式 "score": 0.95 }] }]

五、CSV / TSV、纯文本与 HTML 导入

5.1 CSV / TSV

导入 CSV/TSV 文本文件时，Label Studio 把列名解释为任务数据键，与标签配置对应：

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

注意：若标签配置中包含TimeSeries标签，CSV/TSV 会被解释为时间序列数据——该文件被托管为资源文件，Label Studio 自动创建一条指向所上传 CSV/TSV 的任务链接。

从源码看，CSV 解析由 FileUpload.read_tasks_list_from_csv 完成，它先用 _detect_csv_separator 自动检测分隔符：分析文件首行中分号与逗号的频次，分号更多则用;，否则默认,。TSV 则固定按\t分隔。解析结果统一包装为[{"data": {...}}, ...]的任务列表。

5.2 纯文本（TXT）

纯文本文件按行解析：每一行成为一个独立的标注任务。适合只有一条输入数据流、标签配置中只有一个对象标签的场景：

this is a first task this is a second task

若希望整个纯文本文件作为单条数据（而不是每行一个任务），请在Text标签中设置valueType="url"。从源码看，TXT 每行任务的数据键为settings.DATA_UNDEFINED_NAME（见 read_tasks_list_from_txt），即单数据源项目的兜底键。

5.3 HTML（HyperText）

导入 HTML 格式文件标注HyperText数据时，直接导入的 HTML 内容会被压缩（minify）——压缩文本、去除空白等无功能数据，标注应用于压缩后的版本。若不想压缩，有两个办法：

• 把 HTML 文件作为 BLOB 从 Amazon S3、Google Cloud Storage 等外部云存储导入；
• 在标签配置的HyperText标签中设置valueType="url"。

六、从本地目录导入数据

从本地目录导入有两条路径：

1. 起一个 Web 服务器为文件生成 URL，再把引用这些 URL 的文件导入 Label Studio；
2. 在 Label Studio UI 中把该文件目录添加为源/目标本地存储连接。

6.1 用 Web 服务器生成本地文件 URL

仓库自带了辅助脚本，用法为：

./script/serve_local_files.sh <directory/with/files> *.jpg

脚本行为（可对照 serve_local_files.sh 源码确认）：

• 接收 4 个位置参数：INPUT_DIR（目录）、WILDCARD（文件通配符，默认全部文件）、OUTPUT_FILE（默认files.txt）、PORT（默认 8081）；
• 用find扫描目录匹配文件，把目录前缀替换为http://localhost:PORT后写入files.txt（每行一个 URL）；
• 最后cd到目标目录并启动python3 -m http.server $PORT。

之后在 UI 中导入该 URL 清单文件即可。注意：标注期间必须保持 Web 服务器运行，否则 URL 会失效。

如果你的标签配置支持 HyperText 或多数据类型，建议改用 JSON 任务格式指代本地文件位置（而非txt文件），参见本地存储文件引用的示例。

若用python -m http.server 8081 -d自建 HTTP 服务器，可能需要为该服务器配置 CORS 才能让 Label Studio 正常访问数据文件，可改用：

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

6.2 添加为本地存储

Docker 部署 Label Studio 时想使用本地文件存储，需要挂载文件目录并设置相应环境变量（参见官方安装文档的 "Run Label Studio on Docker and use Local Storage" 一节）。

七、通过 Label Studio UI 导入

同样地，再次强调：大型/业务关键项目请勿通过 UI 上传媒体文件（风险清单同第一节）。UI 导入适合 PoC 场景，步骤为：

1. 打开某个项目的 Data Manager 页面；
2. 点击Import打开导入对话框；
3. 从文件或 URL 导入数据。

导入的数据是项目专属的（project-specific）。从源码看，UI 的 Import 对话框与 API 的POST /api/projects/<id>/import走同一套解析逻辑；多文件上传前会先执行 check_request_files_size 与扩展名校验，上传文件落盘路径由 upload_name_generator 生成（upload/<project_id>/<uuid8>-<文件名>），每个任务会记录file_upload_id以便后续重导入（reimport）时按文件粒度删除重建。

八、通过 API 导入数据

API 导入入口为POST /api/projects/{project_id}/import（ImportAPI），一次 POST 请求最多250,000 个任务、200 MB（OpenAPI 文档口径）。共有三种提交方式：

8.1 方式一：POST JSON 数据

直接以 JSON 任务列表作为请求体（直接 POST 文件时仅支持 JSON）：

curl -H 'Content-Type: application/json' -H 'Authorization: Token abc123' \ -X POST '{host}/api/projects/1/import' --data '[{"text": "Some text 1"}, {"text": "Some text 2"}]'

8.2 方式二：POST 上传文件

可挂载多个不同名称的文件，支持 JSON / CSV / TSV / TXT（TXT 类似无表头单列 CSV，仅支持单数据源项目）：

curl -H 'Authorization: Token abc123' \ -X POST '{host}/api/projects/1/import' -F 'file=@path/to/my_file.csv'

8.3 方式三：POST URL

提供包含标注任务文件的 URL，支持格式与方式二相同：

curl -H 'Content-Type: application/json' -H 'Authorization: Token abc123' \ -X POST '{host}/api/projects/1/import' \ --data '[{"url": "http://example.com/test1.csv"}, {"url": "http://example.com/test2.csv"}]'

从源码看，URL 导入由 tasks_from_url 实现：先用ssrf_safe_get下载（开启 SSRF 防护，见 SSRF_PROTECTION_ENABLED），解析重定向后的文件名并校验扩展名，下载前先用content-length头做体积预检，最后落为FileUpload记录走统一解析。

8.4 同步与异步导入行为

create 方法 根据版本分派：

• Community 版：同步导入，立即返回task_count、annotation_count、prediction_count、duration、found_formats、data_columns等详情；
• 非 Community 版：异步导入，先创建ProjectImport记录并投递后台任务（async_import_background，队列high），响应{"import": <import_id>}，需用返回的 ID 轮询GET /api/projects/{project_id}/imports/{import_id}获取状态与数据级错误。

请求支持三个查询参数（见 OpenAPI 参数定义 api.py）：

preannotated_from_fields的转换逻辑在 reformat_predictions：把扁平任务 JSON 中指定字段的值改写成标准 prediction 结构（model_version置为preannotated，score为 1.0），并依据项目label_config推断to_name与type。此外，当项目使用了非默认标签配置时，导入的 predictions 会经LabelInterface.validate_prediction逐条校验（见 sync_import），校验失败会汇总为带任务/预测索引的错误信息。

8.5 导入限额

文档口径：单次导入文件最多250,000 个任务或 50MB。而源码中的默认值为 TASKS_MAX_NUMBER = 1,000,000、TASKS_MAX_FILE_SIZE = DATA_UPLOAD_MAX_MEMORY_SIZE（默认 250MB，可用环境变量覆盖），实际触发点分别是 check_max_task_number 与 check_tasks_max_file_size。API OpenAPI 文档则以"单次 POST 250K 任务、200MB"为限。请以你所部署版本的实际配置为准；工程上仍建议遵循文档的 250k/50MB 保守阈值分批导入。

8.6 流式导入（大规模 JSON）

从源码结构看，后台导入支持按批流式处理以降低内存占用：load_tasks_for_async_import_streaming 按settings.IMPORT_BATCH_SIZE分批产出任务；JSON 文件的流式解析基于ijson增量解析器（见 read_tasks_list_from_json_streaming），逐条产出数组元素而无需整文件载入内存。

九、命令行导入（1.0.0 之前的版本）

以下仅适用于1.0.0 之前的 Label Studio；当前仓库的导入入口为 UI 与 REST API，代码库中已不包含该initCLI（源码检索确认），此处保留原文档内容以供旧版本维护参考。

1. 启动 Label Studio 时用命令行参数指定数据路径与格式，例如：

   label-studio init --input-path my_tasks.json --input-format json

2. 打开 Label Studio UI 确认数据导入成功。

--input-path可指定文件或目录，--input-format指定数据格式。例如启动时从本地目录导入音频文件：

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

警告：--allow-serving-local-files仅适用于本地运行的 Label Studio 实例；远程服务器慎用，除非你清楚自己在做什么。

默认情况下，Label Studio 期望使用标准 JSON 任务格式的 JSON 任务。Label Studio 启动后若本地目录新增文件，必须重启Label Studio 才会导入新文件中的任务。

十、导入流程源码调用链速览

把文档描述的导入流程对应到代码，完整链路如下：

1. 入口：ImportAPI.create 校验项目权限后分派同步/异步；
2. 解析：load_tasks 按"请求文件 → URL → JSON 数据"的优先级读取任务，执行大小/扩展名/SSRF 校验；
3. 文件解析：FileUpload.read_tasks 按扩展名分派 CSV/TSV/TXT/JSON/HTML 分支，多文件合并时通过 load_tasks_from_uploaded_files 检查各文件数据键的一致性（不一致会给出明确报错）；
4. 落库：ImportApiSerializer创建Task及内嵌的annotations/predictions，随后project.update_tasks_counters_and_task_states更新项目计数与任务状态，并通过 webhook 发出TASKS_CREATED事件（见 async_import_background）。

相关测试用例可参考 label_studio/tests/data_import/ 与 data_import.tavern.yml，覆盖了 CSV、TXT、JSON 多格式与 URL 导入的端到端行为。

小结

Label Studio 的数据导入遵循一个清晰的工程原则：数据本体尽量外置，导入只存引用。文档给出的类型表、valueType三态、resolverCSV 语法与标准 JSON 任务格式，覆盖了从 PoC 到生产的数据接入路径；对照 label_studio/data_import/ 下的 api.py、uploader.py、models.py、functions.py，可以进一步验证扩展名白名单、导入限额、SSRF 防护与异步/流式导入的实现细节，确保大规模导入方案与当前版本能力严格对齐。

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