Label Studio 導出指南注解與數據的格式、API 與實操詳解【免費下載鏈接】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 支持在標注項目的任意階段導出注解annotations與數據導出結果可直接用于訓練機器學習模型或數據科學項目。本指南以官方文檔為基礎結合倉庫源碼label_studio/data_export/、label_studio/tasks/functions.py等深入講解 UI 導出、命令行導出、Easy Export API、快照Snapshot異步導出、受支持的全部導出格式、原始 JSON 結構以及圖像注解單位換算幫助讀者在社區版與企業版中選擇最合適的導出路徑并規避超時陷阱。一、導出機制概覽注解存儲在哪里Label Studio 將注解以原始 JSON 格式存儲在后端數據庫中包括 SQLite、PostgreSQL或你指定的云存儲與數據庫目標存儲。云存儲桶中每個已標注任務對應一個名為task_id.json的文件。關于目標存儲同步的更多說明參見云存儲配置。從源碼看同步導出的核心調用鏈位于 data_export/api.py 的ExportAPI.get()先按條件篩選任務并序列化為 JSON 列表再由 data_export/models.py 的DataExport.generate_export_file()交給label_studio_sdk.converter.Converter完成格式轉換。若轉換結果只有一個文件則直接返回否則會打包成 ZIP 歸檔返回。快照異步導出的核心在 data_export/mixins.py 的export_to_file()與后臺任務export_background()。有一點需要特別注意部分導出格式只導出注解而不導出任務數據本身具體見下文受支持的導出格式一節。圖像注解以 JSON 導出時邊框尺寸與位置使用相對整張圖片尺寸的百分比而非像素換算方法見圖像注解單位換算。二、注解結果在 JSON 中的保存方式每個標注生成的注解annotation都包含**區域Regions與結果Results**兩部分Regions指被選中的數據區域可能是文本片段、圖像區域、音頻片段或其他實體Results指賦予該區域的標簽。每個區域在每條注解內擁有唯一 ID由A-Za-z0-9_-字符組成的字符串每條 result 的 ID 與其對應的區域 ID 相同。當預測prediction被用來生成注解時結果 ID 會保持一致從而可以追蹤模型生成的區域并與人工創建、審核過的注解直接對比。Label Studio JSON 格式的注解任務標注完成后每個任務的原始 JSON 結構如下完整字段說明見API 文檔與任務格式{ id: 1, created_at:2021-03-09T21:52:49.513742Z, updated_at:2021-03-09T22:16:08.746926Z, project:83, data: { image: https://example.com/opensource/label-studio/1.jpg }, annotations: [ { id: 1001, result: [ { from_name: tag, id: Dx_aB91ISN, source: $image, to_name: img, type: rectanglelabels, value: { height: 10.458911419423693, rectanglelabels: [ Moonwalker ], rotation: 0, width: 12.4, x: 50.8, y: 5.869797225186766 } } ], was_cancelled: false, ground_truth: false, created_at:2021-03-09T22:16:08.728353Z, updated_at:2021-03-09T22:16:08.728378Z, lead_time:4.288, result_count:0, task:1, completed_by:10 } ], predictions: [ { created_ago: 3 hours, model_version: model 1, result: [ { from_name: tag, id: t5sp3TyXPo, source: $image, to_name: img, type: rectanglelabels, value: { height: 11.612284069097889, rectanglelabels: [ Moonwalker ], rotation: 0, width: 39.6, x: 13.2, y: 34.702495201535505 } } ] }, { created_ago: 4 hours, model_version: model 2, result: [ /* ... 結構同上 ... */ ] } ] }關鍵 JSON 字段說明JSON 屬性名說明id數據集中的標注任務標識符。data從輸入任務格式復制的原始數據參見任務格式。project該任務所屬 Label Studio 項目的標識符。annotations包含該任務標注結果的數組。annotations.id已完成任務的標識符。annotations.lead_time標注該任務所花費的秒數。annotations.result包含標注結果的數組。annotations.updated_at注解創建或修改的時間戳。annotations.completed_at注解創建或提交的時間戳。annotations.completed_by創建注解的用戶 ID與 UI 人員頁面上的用戶列表順序一致。annotations.was_cancelled布爾值表示該注解是否被跳過或取消。result.id該任務下特定標注結果的標識符可用于將不同控制標簽如Labels與Rectangle的區域關聯起來。result.parentID可選父區域 result.id 的引用用于在 Regions 面板中組織區域的層級樹。result.from_name標注該區域所用標簽的名稱參見控制標簽。result.to_name提供待標注區域的對象標簽名稱參見對象標簽。result.type用于標注該任務的標簽類型。result.value標簽相關的值包含標注結果的細節其結構取決于標簽類型參見各標簽文檔。drafts草稿注解數組結構與 annotations 類似。僅當通過UI 快照導出或快照 API導出時包含。predictions機器學習預測數組結構與 annotations 相同但額外帶一個參數。predictions.score基于概率輸出、置信度或其他指標得到的結果總體得分。task.updated_at任務或其注解/審核被創建、更新或刪除的時間戳。導入時指定標注者completed_by在導入注解時可以通過注解對象中的completed_by字段控制標注者分配// 方式 1不指定標注者使用導入者 { result: [...], completed_by: null } // 方式 2通過郵箱指定 { result: [...], completed_by: { email: annotatorexample.com } } // 方式 3通過 ID 指定 { result: [...], completed_by: 42 }系統會將該郵箱或 ID 匹配到組織內已有用戶若配置允許則回退到導入者。該規則同時適用于通過 UI、API 或 SDK 導入的場景。企業版補充字段annotations.reviews注解審核詳情數組、reviews.id審核 ID、reviews.created_by審核人的用戶 ID、郵箱、姓名等字典信息、reviews.accepted布爾值表示審核人是否接受該注解。三、社區版通過 UI 與命令行導出通過 UI 導出在社區版Community Edition中按以下步驟導出數據與注解在項目中點擊Export選擇可用的導出格式點擊Export導出數據。注意三點無論標簽頁上設置了什么過濾器導出結果始終包含已標注任務已取消cancelled的已標注任務也會包含在導出結果中若要對導出應用標簽頁過濾條件可改用 SDK 創建導出快照。社區版的導出超時問題社區版 UI 的導出是同步生成的作為請求的一部分執行。社區版為保持部署簡單默認不運行后臺導出 workerLabel Studio Enterprise 支持后臺 worker 的異步快照導出更適合大規模項目。對于大型項目社區版導出耗時可能超過反向代理或 ingress 配置的超時時間通常約90 秒導致 502/504 錯誤或導出超時。遇到該限制時可選擇以下替代方案使用 SDK 導出快照見 SDK 導出快照 API使用控制臺命令在運行 Label Studio 的機器上直接使用下面的控制臺命令導出項目在大規模場景下使用 UI 導出Label Studio Enterprise 在 UI 中提供后臺快照導出見下文導出快照。從源碼可以印證這一點同步導出 APIExportAPI.get()直接在同一請求內完成查詢、序列化、轉換與文件響應data_export/api.py而快照導出則通過ExportListAPI創建Export記錄、由后臺任務export_background()異步生成文件data_export/mixins.py。使用控制臺命令導出label-studio export project-id export-format --export-pathoutput-path啟用調試日志DEBUG1 LOG_LEVELDEBUG label-studio export project-id export-format --export-pathoutput-path該子命令由 core/argparser.py 注冊支持project_id、export_format如 JSON、JSON_MIN、CSV 等與--export-path參數--export-serializer-context可用于傳入序列化上下文默認值為{annotations__completed_by: {only_id: null}, interpolate_key_frames: true}。實際執行邏輯位于 tasks/functions.py 的export_project()先校驗格式是否受支持再按每批 1000 個任務批量序列化最終調用DataExport.generate_export_file()生成文件并寫入--export-path若為目錄則追加生成的文件名。四、Easy Export API同步導出對于小型標注項目可直接調用導出端點同步導出注解。導出包含未標注任務在內的全部任務Label Studio 開源版默認只導出已標注任務。若想輕松導出包括未標注任務在內的全部任務可在調用 Easy Export API 時帶上查詢參數download_all_taskstrue。例如curl -X GET https://localhost:8080/api/projects/{id}/export?exportTypeJSONdownload_all_taskstrue對應的同步導出接口為 data_export/urls.py 中的project-exportExportAPI。從源碼看ExportAPI.get()中only_finished not download_all_tasks當only_finished為真時會執行query.filter(annotations__isnullFalse).distinct()這正是默認只導出已標注任務的底層實現data_export/api.py。如果項目很大通常應改用快照導出以避免超時。快照默認包含所有任務包括未標注任務。五、使用快照 API 導出對于擁有數十萬任務的的大型標注項目按以下三步操作向創建新導出文件/快照發起 POST 請求響應中會包含創建文件的id使用該id作為export_pk檢查導出文件的狀態仍以該id作為export_pk向下載導出文件發起 GET 請求完成下載。對應的 REST 路由在 data_export/urls.py 中定義POST /api/projects/{id}/exports/創建快照ExportListAPIGET /api/projects/{id}/exports/{export_pk}查看狀態ExportDetailAPIGET /api/projects/{id}/exports/{export_pk}/download下載文件ExportDownloadAPI。快照模型Export維護了created / in_progress / failed / completed四種狀態并通過FileField存儲生成的文件、記錄md5與counters元數據data_export/models.py。快照文件名默認由get_default_title()生成格式為PROJECT-NAME-at-YEAR-MM-DD-HH-MMUTC 時間。六、導出快照Snapshot異步導出企業版在 Label Studio Enterprise 中可以創建數據與注解的快照按需精確導出標注項目中想要的內容。這種延遲導出方式更適合從 UI 導出大型標注項目。在項目的 Label Studio UI 中點擊Export點擊Create New SnapshotApply filters from tab ...從下拉列表中選擇Default可選Snapshot Name輸入快照名稱便于日后查找。默認快照命名為PROJECT-NAME-at-YEAR-MM-DD-HH-MM時間為 UTCInclude in the Snapshot…選擇要包含的數據類型All tasks全部任務、Only annotated僅已標注或Only reviewed僅已審核Drafts選擇導出完整草稿注解Complete drafts還是僅導出草稿注解的 IDOnly IDs僅標記存在草稿Predictions選擇導出完整預測Complete predictions還是僅導出預測 IDOnly IDs僅標記任務存在預測Annotations啟用要導出的注解類型可指定Annotations普通注解、Ground Truth與Skipped跳過的注解。默認只導出普通注解可選啟用Remove user details移除用戶詳細信息點擊Create a Snapshot開始導出在快照列表中可以看到可下載的快照以及其中包含的內容、創建時間與創建者信息點擊Download并選擇導出格式快照文件即下載到本地。從源碼看快照導出支持豐富的過濾選項_get_filtered_tasks()支持按 tab 視圖view、跳過skipped、完成finished與已標注annotated過濾任務data_export/mixins.py_get_filtered_annotations_queryset()支持按普通注解、Ground Truth、跳過的注解取并集過濾data_export/mixins.py序列化選項則控制草稿、預測、completed_by是否展開以及是否插值視頻關鍵幀、是否下載資源data_export/mixins.py。七、受支持的導出格式Label Studio 支持多種通用與標準格式導出已完成的標注任務。如果缺少你需要的格式還可以為項目貢獻一種。更多信息參見 Label Studio SDK 倉庫中的 Converter 工具。格式支持的實際判定發生在 data_export/models.py 的DataExport.get_export_formats()它基于項目解析后的標簽配置創建Converter將converter.supported_formats中不支持的格式標記為disabled在 UI 中置灰企業版啟用自定義界面時還會額外加入DOCLANG格式。ASR_MANIFEST將自動語音識別的音頻轉寫標簽導出為 NVIDIA NeMo 模型期望的 JSON manifest 格式。適用于使用Audio標簽配合TextArea標簽的音頻轉寫項目。{audio_filepath: /path/to/audio.wav, text: the transcription, offset: 301.75, duration: 0.82, utt: utterance_id, ctm_utt: en_4156, side: A}Brush labels to NumPy and PNG將畫筆遮罩標簽導出為 NumPy 二維數組與 PNG 圖片。每個標簽輸出為一張圖片。適用于使用BrushLabels標簽的畫筆標注圖像項目。COCOCOCO 數據集常用的機器學習格式用于目標檢測與圖像分割任務。適用于使用BrushLabels、RectangleLabels、KeyPointLabels見下方說明或PolygonLabels標簽的邊界框與多邊形圖像標注項目。KeyPointLabels 導出支持如果使用KeyPointLabels需要在標注配置中添加以下內容至少一個RectangleLabels選項作為關鍵點的父邊界框在KeyPointLabels內的每個Label上添加model_index該值定義輸出數組中關鍵點坐標的順序供 YOLO 使用。例如View Image nameimage value$image/ KeyPointLabels namekp toNameimage Label valuenose model_index0/ Label valueeye model_index1/ Label valuetail model_index2/ /KeyPointLabels RectangleLabels namebbox toNameimage Label valueanimal/ /RectangleLabels /View標注完成后必須在Regions面板中將每個關鍵點區域拖放到其對應的矩形區域下方從而通過parentID建立父子層級關系這是導出所必需的見上圖與下方導出示例。導出示例Keypoints in JSON[ { id: 17n06ubOJs, type: keypointlabels, value: { x: 6.675567423230974, y: 20.597014925373134, width: 0.26702269692923897, keypointlabels: [nose] }, origin: manual, to_name: image, parentID: QHG4TBXuNC, from_name: kp, image_rotation: 0, original_width: 200, original_height: 179 }, { id: QHG4TBXuNC, type: rectanglelabels, value: { x: 3.871829105473965, y: 4.029850746268656, width: 94.39252336448598, height: 92.08955223880598, rotation: 0, rectanglelabels: [animal] }, origin: manual, to_name: image, from_name: bbox, image_rotation: 0, original_width: 200, original_height: 179 } ]Keypoints in COCO[ { id: 0, image_id: 0, category_id: 0, segmentation: [], bbox: [7.74365821094793, 7.213432835820895, 188.78504672897196, 164.84029850746268], ignore: 0, iscrowd: 0, area: 31119.38345654903 }, { id: 1, image_id: 0, category_id: 0, keypoints: [13, 37, 2, 33, 33, 2, 167, 24, 2], num_keypoints: 3, bbox: [13, 24, 154, 13], iscrowd: 0 } ]Keypoints in YOLO0 0.5106809078771696 0.5007462686567165 0.9439252336448598 0.9208955223880598 0.06675567423230974 0.20597014925373133 2 0.1628838451268358 0.18507462686567164 2 0.8371161548731643 0.13134328358208955 2CoNLL2003CoNLL-2003 命名實體識別挑戰賽常用格式。適用于使用Text與Labels標簽的文本標注項目。CSV結果以逗號分隔值存儲列名由標注配置中from_name與to_name字段的值決定。支持所有項目類型。JSON以原始 JSON 格式存儲在一個 JSON 文件中的條目列表。適合同時導出數據集的數據與注解。支持所有項目類型。JSON_MIN僅導出原始 JSON 格式中from_name、to_name值的條目列表。適合導出數據集的數據與注解且不包含 Label Studio 特有字段。支持所有項目類型。例如{ image: https://htx-pub.s3.us-east-1.amazonaws.com/examples/images/nick-owuor-astro-nic-visuals-wDifg5xc9Z4-unsplash.jpg, tag: [{ height: 10.458911419423693, rectanglelabels: [Moonwalker], rotation: 0, width: 12.4, x: 50.8, y: 5.869797225186766 }] }Pascal VOC XML用于目標檢測與圖像分割任務的流行 XML 格式。適用于使用RectangleLabels標簽的邊界框圖像標注項目。spaCyLabel Studio 不支持直接導出為 spaCy 二進制格式但可以將導出的注解轉換為與 spaCy 兼容的格式。進行此轉換前必須安裝 spacy Python 包。轉換步驟先將注解導出為 CONLL2003 格式打開下載的文件在第一行添加O-DOCSTART- -X- O O在命令行運行spacy convert將 CoNLL 格式注解轉換為 spaCy 二進制格式將/path/to/filename替換為注解文件的路徑與文件名spaCy 2.xspacy convert /path/to/filename.conll -c nerspaCy 3.xspacy convert /path/to/filename.conll -c conll .更多信息參見 spaCy 文檔中關于 Converting existing corpora and annotations 運行spacy convert的說明。TSV結果存儲在制表符分隔的表格文件中列名由標注配置中的from_name與to_name值決定。支持所有項目類型。YOLO以 YOLOv3 與 YOLOv4 格式導出目標檢測注解。適用于使用RectangleLabels與KeyPointLabels標簽的目標檢測項目。如果使用 KeyPointLabels請參見 COCO 小節下的說明。八、圖像注解單位換算圖像注解中x, y, width, height的單位是占整體圖像尺寸的百分比。使用以下換算公式pixel_x x / 100.0 * original_width pixel_y y / 100.0 * original_height pixel_width width / 100.0 * original_width pixel_height height / 100.0 * original_height完整示例含雙向換算task { annotations: [{ result: [ { ...: ..., original_width: 600, original_height: 403, image_rotation: 0, value: { x: 5.33, y: 23.57, width: 29.16, height: 31.26, rotation: 0, rectanglelabels: [Airplane] } } ] }] } # 從 LS 百分比單位轉換為像素 def convert_from_ls(result): if original_width not in result or original_height not in result: return None value result[value] w, h result[original_width], result[original_height] if all([key in value for key in [x, y, width, height]]): return w * value[x] / 100.0, \ h * value[y] / 100.0, \ w * value[width] / 100.0, \ h * value[height] / 100.0 # 從像素轉換為 LS 百分比單位 def convert_to_ls(x, y, width, height, original_width, original_height): return x / original_width * 100.0, y / original_height * 100.0, \ width / original_width * 100.0, height / original_height * 100 # 從 LS 轉換 output convert_from_ls(task[annotations][0][result][0]) if output is None: raise Exception(Wrong convert) pixel_x, pixel_y, pixel_width, pixel_height output print(pixel_x, pixel_y, pixel_width, pixel_height) # 轉換回 LS x, y, width, height convert_to_ls(pixel_x, pixel_y, pixel_width, pixel_height, 600, 403) print(x, y, width, height)注意只有當 result 中包含original_width與original_height時才能完成換算因此請確保這些字段存在于導出的 JSON 中。九、手動將 JSON 注解轉換為其他格式可以通過命令行或 Python在已完成 JSON 注解的目錄或文件上運行 Label Studio converter 工具將 Label Studio JSON 格式的注解轉換為其他格式。如果使用早于 1.0.0 的 Label Studio 版本這是將 Label Studio JSON 注解轉換為其他標注格式的唯一方式。在倉庫中Converter 正是同步/快照導出鏈路里實際執行格式轉換的組件DataExport.generate_export_file()通過Converter(configproject.get_parsed_config(), ...)加載項目標簽配置在臨時目錄中調用converter.convert(input_json, tmp_dir, output_format, is_dirFalse)完成轉換data_export/models.py。十、在 Label Studio 之外訪問任務數據供 ML 后端使用機器學習后端需要使用任務中的數據生成預測因此需要在 ML 后端側下載這些資源。Label Studio 提供了下載工具位于label-studio-toolsPython 包中。如果使用官方 Label Studio Machine Learning 后端label-studio-tools會隨其他依賴自動安裝。從 Label Studio 實例訪問任務數據Label Studio 中存儲任務資源圖像、音頻、文本等的方式有以下幾種云存儲Cloud storages外部網頁鏈接External web links上傳的文件Uploaded files本地文件目錄Local files directoryLabel Studio 以上傳文件時按項目級別組織目錄結構每個項目擁有獨立的文件文件夾。可以使用label_studio_tools.core.utils.io.get_local_path獲取任務數據——它會將任務數據中的路徑或 URL 轉換為本地路徑。對于本地路徑會返回完整本地路徑使用download_resources參數時會下載資源。訪問外部資源時需要提供Hostname與access_token。在 Label Studio 實例之外訪問任務數據同樣可以使用label_studio_tools.core.utils.io.get_local_path方法從外部機器獲取外部鏈接與云存儲中的數據。重要不要忘記提供憑證credentials。如果在外部機器上掛載了相同的磁盤也可以直接使用get_local_path獲取數據。另一種訪問方式是利用任務中的鏈接與 ACCESS_TOKEN參見認證文檔拼接 Label Studio 主機名與任務數據中的鏈接然后在請求中加入訪問令牌curl -X GET http://localhost:8080/api/projects/ -H Authorization: Token {YOUR_TOKEN}十一、常見問題FAQ問題 1請求返回了以下 API 響應沒有提供任何數據No data was provided返回了 404 或 403 錯誤碼。解答首先檢查發送 API 請求時與 Label Studio 實例之間的網絡連通性。可以使用示例數據執行測試 curl 請求來驗證。問題 2訪問文件時收到FileNotFound錯誤解答確認已掛載與 Label Studio 實例相同的磁盤并先在 Label Studio 實例中確認文件存在檢查 Label Studio 實例中的LOCAL_FILES_DOCUMENT_ROOT環境變量并在訪問數據的腳本中添加該變量。問題 3如何修改 COCO 與 YOLO 導出中類別的順序標簽默認按字母順序排序。如需修改請在Label中添加category屬性來改變行為。例如Label valueabc category1 / Label valuedef category2 /十二、延伸閱讀云存儲配置目標存儲同步與云存儲桶中的task_id.json文件API 參考認證方式與導出相關端點的完整說明訪問令牌ML 后端與外部腳本訪問任務數據所需的認證任務格式輸入任務的 JSON 格式標注界面與標簽文檔各控制標簽與對象標簽的from_name/to_name語義SDK 導出快照 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創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考