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 支持导入文本、时间序列、音频、图像等多种数据具体支持的文件类型如下摘自官方文档数据类型支持的文件类型音频.flac, .m4a, .mp3, .ogg, .wavHyperText (HTML).html, .htm, .xml图像.bmp, .gif, .jpg, .png, .svg, .webpParagraphs对话.json结构化数据.csv, .tsv文本.txt, .json时间序列.csv, .tsv, .json多数据类型任务.csv, .tsv, .json, .jsonl*, .parquet*视频.mp4, .webm* 仅云存储支持 仅 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 加载valueTypeurl直接存入数据库HyperText/Text用valueTypetextParagraph/TimeSeries用valueTypejson。注意若从 URL 加载数据数据本身不会被 Label Studio 保存。如果你希望导出的标注任务包含被标注的数据本体必须不用 URL 引用、把数据导入数据库或在导出后自行把数据与标注合并。3.2 两种 valueType 的配置示例以文本分类为例valueTypetext的完整示例标签配置XMLView Text nametext1 valuetext valueTypetext /View导入的 JSON 文件{ text: My awesome opossum }导入的 CSV 文件text My awesome opossumvalueTypeurl的对应示例View Text nametext1 valuetext valueTypeurl /View{ text: http://example.com/text.txt }text http://example.com/text.txt3.3value数据取值的三种形态Label Studio 按以下优先级和形式从任务数据中取数以渲染Object标签该机制同样用于动态选项和标签渲染变量最常见形态value中带$前缀的变量名。例如Audio value$audio ... /会在导入的 JSON 对象中查找audio字段{ data: { audio: https://host.name/myaudio.wav } }纯文本value可直接是字符串适合Header与Text标签Label和Choice也可以直接用标签内容作为值HeaderLabel audio:/Header Header valueLabel only fully visible cars / Text nameinstruction valueLabel only fully visible cars / Labelcat/Label Choiceother/Choice其他情况value可以是包含$变量的文本片段如Header valueurl: $image/也可以引用数组和字典中的嵌套数据$texts[2]、$audio.url例如Image nameimage value$images[0]/。3.4valueType参数valueType定义上一步取回的数据如何被处理取值url如Text nametext1 value$text valueTypeurl/会加载 URL 指向的文本再显示text/json原始数据如Text nametext value$text valueTypetext/则直接显示 URL 字符串本身而不加载内容json用于TimeSeries等标签。3.5resolver参数运行时解析云存储中的多列 CSVresolver用于从 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.解决方案使用三个参数value$remote——CSV 的 URL 位于任务数据的remote字段。使用resolver时value恒被视为 URL因此无需再设valueTyperesolvercsv|separator;|columntext——运行期加载该文件、按 CSV 解析并取第一行的text列显示结果。resolver语法为以|分隔的选项列表第一个选项是文件类型目前仅支持 CSV其余为可选参数headlessCSV 没有表头布尔参数不接值separator;CSV 分隔符通常可自动检测column1headless模式下使用零基索引否则使用列名。完整示例resolvercsv|headless|separator;|column1。四、标准 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 encodingbase64值解释为 base64 编码的 HTML 标记Audio value$key值解释为启用 CORS 的音频文件 URLImage value$key值解释为图像文件 URLTimeSeries value$keyvalueTypeurl时解释为 CSV/TSV 文件 URLvalueTypejson时解释为列数组 JSON 字典形如value: {first_column: [...], ...}。JSON 中还可以包含两个可选键JSON 键说明annotations可选。从 Label Studio 导出的标注列表采用标注格式可导入标注结果供后续标注任务使用predictions可选。模型预测结果列表采用预测格式。导入 predictions 可实现任务自动预标注与主动学习参见导入预测标签4.1 完整示例文本分类任务标签配置View Text namemessage value$my_text/ Choices namesentiment_class toNamemessage Choice valuePositive/ Choice valueNeutral/ Choice valueNegative/ /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标签中设置valueTypeurl。从源码看TXT 每行任务的数据键为settings.DATA_UNDEFINED_NAME见 read_tasks_list_from_txt即单数据源项目的兜底键。5.3 HTMLHyperText导入 HTML 格式文件标注HyperText数据时直接导入的 HTML 内容会被压缩minify——压缩文本、去除空白等无功能数据标注应用于压缩后的版本。若不想压缩有两个办法把 HTML 文件作为 BLOB 从 Amazon S3、Google Cloud Storage 等外部云存储导入在标签配置的HyperText标签中设置valueTypeurl。六、从本地目录导入数据从本地目录导入有两条路径起一个 Web 服务器为文件生成 URL再把引用这些 URL 的文件导入 Label Studio在 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 --cors6.2 添加为本地存储Docker 部署 Label Studio 时想使用本地文件存储需要挂载文件目录并设置相应环境变量参见官方安装文档的 Run Label Studio on Docker and use Local Storage 一节。七、通过 Label Studio UI 导入同样地再次强调大型/业务关键项目请勿通过 UI 上传媒体文件风险清单同第一节。UI 导入适合 PoC 场景步骤为打开某个项目的 Data Manager 页面点击Import打开导入对话框从文件或 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}/importImportAPI一次 POST 请求最多250,000 个任务、200 MBOpenAPI 文档口径。共有三种提交方式8.1 方式一POST JSON 数据直接以 JSON 任务列表作为请求体直接 POST 文件时仅支持 JSONcurl -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 / TXTTXT 类似无表头单列 CSV仅支持单数据源项目curl -H Authorization: Token abc123 \ -X POST {host}/api/projects/1/import -F filepath/to/my_file.csv8.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参数默认说明commit_to_projecttrue是否立即把任务提交到项目return_task_idsfalse是否在响应中返回任务 IDpreannotated_from_fields无指定任务数据中哪些字段要转换为 predictions预标注preannotated_from_fields的转换逻辑在 reformat_predictions把扁平任务 JSON 中指定字段的值改写成标准 prediction 结构model_version置为preannotatedscore为 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源码检索确认此处保留原文档内容以供旧版本维护参考。启动 Label Studio 时用命令行参数指定数据路径与格式例如label-studio init --input-path my_tasks.json --input-format json打开 Label Studio UI 确认数据导入成功。--input-path可指定文件或目录--input-format指定数据格式。例如启动时从本地目录导入音频文件label-studio init my-project --input-pathmy/audios/dir --input-formataudio-dir --label-configconfig.xml --allow-serving-local-files警告--allow-serving-local-files仅适用于本地运行的 Label Studio 实例远程服务器慎用除非你清楚自己在做什么。默认情况下Label Studio 期望使用标准 JSON 任务格式的 JSON 任务。Label Studio 启动后若本地目录新增文件必须重启Label Studio 才会导入新文件中的任务。十、导入流程源码调用链速览把文档描述的导入流程对应到代码完整链路如下入口ImportAPI.create 校验项目权限后分派同步/异步解析load_tasks 按请求文件 → URL → JSON 数据的优先级读取任务执行大小/扩展名/SSRF 校验文件解析FileUpload.read_tasks 按扩展名分派 CSV/TSV/TXT/JSON/HTML 分支多文件合并时通过 load_tasks_from_uploaded_files 检查各文件数据键的一致性不一致会给出明确报错落库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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 支持导入文本、时间序列、音频、图像等多种数据具体支持的文件类型如下摘自官方文档数据类型支持的文件类型音频.flac, .m4a, .mp3, .ogg, .wavHyperText (HTML).html, .htm, .xml图像.bmp, .gif, .jpg, .png, .svg, .webpParagraphs对话.json结构化数据.csv, .tsv文本.txt, .json时间序列.csv, .tsv, .json多数据类型任务.csv, .tsv, .json, .jsonl*, .parquet*视频.mp4, .webm* 仅云存储支持 仅 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 加载valueTypeurl直接存入数据库HyperText/Text用valueTypetextParagraph/TimeSeries用valueTypejson。注意若从 URL 加载数据数据本身不会被 Label Studio 保存。如果你希望导出的标注任务包含被标注的数据本体必须不用 URL 引用、把数据导入数据库或在导出后自行把数据与标注合并。3.2 两种 valueType 的配置示例以文本分类为例valueTypetext的完整示例标签配置XMLView Text nametext1 valuetext valueTypetext /View导入的 JSON 文件{ text: My awesome opossum }导入的 CSV 文件text My awesome opossumvalueTypeurl的对应示例View Text nametext1 valuetext valueTypeurl /View{ text: http://example.com/text.txt }text http://example.com/text.txt3.3value数据取值的三种形态Label Studio 按以下优先级和形式从任务数据中取数以渲染Object标签该机制同样用于动态选项和标签渲染变量最常见形态value中带$前缀的变量名。例如Audio value$audio ... /会在导入的 JSON 对象中查找audio字段{ data: { audio: https://host.name/myaudio.wav } }纯文本value可直接是字符串适合Header与Text标签Label和Choice也可以直接用标签内容作为值HeaderLabel audio:/Header Header valueLabel only fully visible cars / Text nameinstruction valueLabel only fully visible cars / Labelcat/Label Choiceother/Choice其他情况value可以是包含$变量的文本片段如Header valueurl: $image/也可以引用数组和字典中的嵌套数据$texts[2]、$audio.url例如Image nameimage value$images[0]/。3.4valueType参数valueType定义上一步取回的数据如何被处理取值url如Text nametext1 value$text valueTypeurl/会加载 URL 指向的文本再显示text/json原始数据如Text nametext value$text valueTypetext/则直接显示 URL 字符串本身而不加载内容json用于TimeSeries等标签。3.5resolver参数运行时解析云存储中的多列 CSVresolver用于从 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.解决方案使用三个参数value$remote——CSV 的 URL 位于任务数据的remote字段。使用resolver时value恒被视为 URL因此无需再设valueTyperesolvercsv|separator;|columntext——运行期加载该文件、按 CSV 解析并取第一行的text列显示结果。resolver语法为以|分隔的选项列表第一个选项是文件类型目前仅支持 CSV其余为可选参数headlessCSV 没有表头布尔参数不接值separator;CSV 分隔符通常可自动检测column1headless模式下使用零基索引否则使用列名。完整示例resolvercsv|headless|separator;|column1。四、标准 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 encodingbase64值解释为 base64 编码的 HTML 标记Audio value$key值解释为启用 CORS 的音频文件 URLImage value$key值解释为图像文件 URLTimeSeries value$keyvalueTypeurl时解释为 CSV/TSV 文件 URLvalueTypejson时解释为列数组 JSON 字典形如value: {first_column: [...], ...}。JSON 中还可以包含两个可选键JSON 键说明annotations可选。从 Label Studio 导出的标注列表采用标注格式可导入标注结果供后续标注任务使用predictions可选。模型预测结果列表采用预测格式。导入 predictions 可实现任务自动预标注与主动学习参见导入预测标签4.1 完整示例文本分类任务标签配置View Text namemessage value$my_text/ Choices namesentiment_class toNamemessage Choice valuePositive/ Choice valueNeutral/ Choice valueNegative/ /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标签中设置valueTypeurl。从源码看TXT 每行任务的数据键为settings.DATA_UNDEFINED_NAME见 read_tasks_list_from_txt即单数据源项目的兜底键。5.3 HTMLHyperText导入 HTML 格式文件标注HyperText数据时直接导入的 HTML 内容会被压缩minify——压缩文本、去除空白等无功能数据标注应用于压缩后的版本。若不想压缩有两个办法把 HTML 文件作为 BLOB 从 Amazon S3、Google Cloud Storage 等外部云存储导入在标签配置的HyperText标签中设置valueTypeurl。六、从本地目录导入数据从本地目录导入有两条路径起一个 Web 服务器为文件生成 URL再把引用这些 URL 的文件导入 Label Studio在 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 --cors6.2 添加为本地存储Docker 部署 Label Studio 时想使用本地文件存储需要挂载文件目录并设置相应环境变量参见官方安装文档的 Run Label Studio on Docker and use Local Storage 一节。七、通过 Label Studio UI 导入同样地再次强调大型/业务关键项目请勿通过 UI 上传媒体文件风险清单同第一节。UI 导入适合 PoC 场景步骤为打开某个项目的 Data Manager 页面点击Import打开导入对话框从文件或 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}/importImportAPI一次 POST 请求最多250,000 个任务、200 MBOpenAPI 文档口径。共有三种提交方式8.1 方式一POST JSON 数据直接以 JSON 任务列表作为请求体直接 POST 文件时仅支持 JSONcurl -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 / TXTTXT 类似无表头单列 CSV仅支持单数据源项目curl -H Authorization: Token abc123 \ -X POST {host}/api/projects/1/import -F filepath/to/my_file.csv8.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参数默认说明commit_to_projecttrue是否立即把任务提交到项目return_task_idsfalse是否在响应中返回任务 IDpreannotated_from_fields无指定任务数据中哪些字段要转换为 predictions预标注preannotated_from_fields的转换逻辑在 reformat_predictions把扁平任务 JSON 中指定字段的值改写成标准 prediction 结构model_version置为preannotatedscore为 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源码检索确认此处保留原文档内容以供旧版本维护参考。启动 Label Studio 时用命令行参数指定数据路径与格式例如label-studio init --input-path my_tasks.json --input-format json打开 Label Studio UI 确认数据导入成功。--input-path可指定文件或目录--input-format指定数据格式。例如启动时从本地目录导入音频文件label-studio init my-project --input-pathmy/audios/dir --input-formataudio-dir --label-configconfig.xml --allow-serving-local-files警告--allow-serving-local-files仅适用于本地运行的 Label Studio 实例远程服务器慎用除非你清楚自己在做什么。默认情况下Label Studio 期望使用标准 JSON 任务格式的 JSON 任务。Label Studio 启动后若本地目录新增文件必须重启Label Studio 才会导入新文件中的任务。十、导入流程源码调用链速览把文档描述的导入流程对应到代码完整链路如下入口ImportAPI.create 校验项目权限后分派同步/异步解析load_tasks 按请求文件 → URL → JSON 数据的优先级读取任务执行大小/扩展名/SSRF 校验文件解析FileUpload.read_tasks 按扩展名分派 CSV/TSV/TXT/JSON/HTML 分支多文件合并时通过 load_tasks_from_uploaded_files 检查各文件数据键的一致性不一致会给出明确报错落库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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考