Label Studio 接入 Microsoft Azure Blob Storage源存储、目标存储与 Service Principal 完整配置指南【免费下载链接】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 开源仓库中的 Azure Blob 存储集成storage_azure.md展开讲解如何将 Azure Blob Storage 容器同时配置为 Label Studio 的源存储Source Storage用于导入标注任务与目标存储Target Storage用于导出标注结果并覆盖 CORS 配置、存储账户密钥认证、本地部署环境变量以及 Enterprise 版的 Service Principal 认证方式。读完本文你将能够从零完成 Azure Blob 与 Label Studio 的对接、校验连接、配置同步策略并通过源码理解其底层数据流转机制。前置概念Label Studio 云存储的工作方式在动手配置之前先明确两个基础概念。Label Studio 中的云存储分为两类详见 io_storages/README.md导入存储Source / Import Storage从云存储容器中把数据文件或任务定义同步进项目对应源码中的ImportStorage抽象基类导出存储Target / Export Storage把标注结果写回云存储容器对应ExportStorage抽象基类。Azure Blob 在源码中由label_studio/io_storages/azure_blob/目录实现其中 models.py 定义了AzureBlobImportStorage导入与AzureBlobExportStorage导出两个模型URL scheme 为azure-blob。预签名 URL 与平台代理两种数据加载方式原文档特别强调了一个关键选择Use pre-signed URLs预签名 URL与Proxy through the platform平台代理两种模式这决定了标注媒体文件如何从 Azure 流向标注者的浏览器预签名 URL 模式Label Studio 后端为容器对象生成带 SAS token 的临时 HTTPS 链接浏览器直接向https://account.blob.core.windows.net/container/blob?sas发起请求HTTP 303 重定向。媒体流量不经过 Label Studio 服务器速度更快、扩展性更好但要求容器正确配置 CORS且存储账户需要具备预签名SAS 生成权限。平台代理模式后端从 Azure 下载文件后再以流式方式转发给浏览器所有媒体流量都经过 Label Studio 服务器。数据始终停留在 Label Studio / 网络边界内每次请求都会执行任务级访问权限检查也无需配置 CORS但会消耗更多 worker 资源速度略慢。从源码看两种模式分别对应 models.py 中的generate_http_url()生成 SAS 预签名 URL与get_bytes_stream()AZURE.download_stream_response()流式下载。UI 中的开关映射到模型的presign字段默认True预签名 URL 的有效期由presign_ttl字段控制默认 1 分钟UI 默认值 15 分钟最小 1 分钟见 form_layout.yml。第一步为 Azure Blob 配置 CORS如果你计划使用平台代理模式可以跳过本节。只要使用预签名 URL就必须配置 CORS。登录 Azure 门户进入存储账户Storage account页面从左侧菜单滚动到设置 资源共享CORSSettings Resource sharing (CORS)在Blob service下添加如下规则配置项取值Allowed originshttps://app.humansignal.com或你实际使用的 Label Studio 域名Allowed methodsGET, HEAD, OPTIONSAllowed headers*Exposed headers*Max age3600点击保存。配置完成后浏览器才能通过预签名 URL 跨域读取容器中的媒体对象。若使用 Service Principal 认证且同样启用预签名 URL也必须在存储账户的 Blob service 上完成上述 CORS 配置。第二步使用存储账户密钥连接 Azure Blob Storage这是 Label Studio 开源版OSS的标准接入方式。开始前请先在 Azure 门户的存储账户资源页面收集以下三项信息容器名称Container Name位于存储账户资源页数据存储 容器Data storage Containers下存储账户名称Account Name存储账户资源页顶部访问密钥Access Key位于安全 网络 访问密钥Security networking Access keys下。创建源存储连接导入数据在 Label Studio 中打开项目进入Settings Cloud Storage Add Source Storage选择Azure Blob Storage并点击Next。配置连接Configure Connection填写以下字段后点击Test connection验证连通性字段说明Storage Title为该存储连接起一个用于标识的名称。Container Name输入 Azure 存储容器名称即上文在 Azure 控制台数据存储 容器下找到的名称。Account Name输入 Azure 存储账户名称。Account Key输入存储账户的访问密钥位于安全 网络 访问密钥下。Use pre-signed URLs (On) / Proxy through the platform (Off)决定容器数据如何加载预签名 URL 模式生成指向 Azure 对象的临时 HTTPS 链接浏览器直连需正确 CORS 与预签名权限平台代理模式由后端下载并流式转发数据不离开 Label Studio 边界每次请求都做任务级访问检查但更耗 worker 资源。Expire pre-signed URLs (minutes)控制预签名 URL 的剩余有效分钟数。导入设置与预览Import Settings Preview点击Load preview确认正在同步的数据符合预期字段说明Bucket Prefix可选。填写容器内要使用的目录名例如data-set-1或data-set-1/subfolder-2。Import Method选择“为容器中每个文件创建一个任务”或使用 JSON/JSONL/Parquet 文件来定义每个任务的数据。File Name Filter填写正则表达式过滤容器对象使用.*收集所有对象。Scan all sub-folders开启后对容器内子文件夹执行递归扫描。复核与确认Review Confirm确认无误后点击Save Sync立即同步或点击Save保存设置、稍后再同步。创建目标存储连接导出标注在 Label Studio 中打开项目进入Settings Cloud Storage Add Target Storage选择Azure Blob Storage并点击Next填写以下字段字段说明Storage Title输入用于标识该存储连接的名称。Container Name输入 Azure 存储容器名称。Container Prefix可选。填写容器内要使用的目录名例如data-set-1或data-set-1/subfolder-2。Account Name输入 Azure 存储账户名称。Account Key输入存储账户访问密钥。Can delete objects from storage开启后当标注在 Label Studio 中被删除时容器中对应的标注文件也会被删除。添加完成后点击Sync推送导出数据。本地部署使用环境变量代替 UI 输入如果你运行的是本地/自托管on-prem部署可以不把密钥手动填进 UI而是通过环境变量注入export AZURE_BLOB_ACCOUNT_NAMEyour-storage-account-name export AZURE_BLOB_ACCOUNT_KEYyour-storage-account-key源码中AzureBlobStorageMixin.get_account_name()与get_account_key()models.py的逻辑是优先使用模型字段account_name/account_key字段为空时回退到环境变量。若两者都未提供连接校验会抛出明确错误提示。底层连接使用 Azure Python SDK 的BlobServiceClient.from_connection_string()构造的字符串格式为DefaultEndpointsProtocolhttps;AccountName...;AccountKey...;EndpointSuffixcore.windows.net见 utils.py。同时要注意AzureBlobImportStorageSerializer将account_name、account_key标记为secure_fieldsserializers.py序列化返回时会主动移除这两个字段避免密钥通过 API 响应泄露。第三步Enterprise使用 Service Principal 认证连接 Azure BlobLabel Studio Enterprise 支持通过 Azure Service Principal 认证连接 Azure Blob Storage无需使用存储账户访问密钥。该方式基于 Entra ID原 Azure Active Directory身份与访问管理可授予细粒度权限并支持审计且权限可随时撤销或轮换——相比拥有存储账户完全访问权的账户密钥安全性更高。注本节为 Enterprise 专属能力开源版OSS不支持。前置条件一个 Azure 订阅和一个存储账户有权限创建应用注册App Registration并在存储账户上分配角色一个私有的数据容器如无则先创建。在 Entra 中创建 Service Principal1. 在 Entra 注册应用打开 Microsoft Entra 管理中心右侧选择应用注册点击新注册。填写名称、选择适当的账户类型重定向 URI 可留空在“概述”页复制应用程序客户端ID和目录租户ID进入证书和机密添加一个新的客户端机密并复制值Value字段。2. 在 Azure 中授予主体存储访问权限返回 Azure 门户并进入你的存储账户从存储账户左侧选择访问控制 (IAM)选择添加 添加角色分配使用搜索框定位Storage Blob Data Contributor角色并点击选中选择上方成员标签页选择用户、组或服务主体然后点击选择成员在搜索框中找到之前创建的应用名称并点击选择点击审阅 分配。3. 创建容器仍在存储账户页面点击左侧数据存储选择容器如没有容器创建一个私有访问级别的新容器。警告如果计划使用预签名 URL必须在存储账户 Blob service 上配置 CORS详见上文“为 Azure Blob 配置 CORS”一节。4. 所需权限清单源存储Source Storage需要Microsoft.Storage/storageAccounts/blobServices/containers/read.../containers/blobs/read目标存储Target Storage需要.../containers/blobs/read.../containers/blobs/write.../containers/read.../containers/blobs/delete可选以上权限均包含在内置的Storage Blob Data Contributor角色中。创建源存储连接Service Principal进入Settings Cloud Storage Add Source Storage选择Azure Blob Storage with Service Principal并点击Next。配置连接填写后点击Test connection字段说明Storage Title输入该存储连接在 Label Studio 中显示的名称。Storage Name输入 Azure 存储账户名称。Container Name输入 Azure 存储账户内的容器名称。Tenant ID填写应用注册中的目录租户ID。Client ID填写应用注册中的应用程序客户端ID。Client Secret填写之前复制的客户端机密值。Use pre-signed URLs / Proxy through the platform启用或禁用预签名 URL。Expiration minutes调整预签名 URL 的有效分钟数。导入设置与预览、复核与确认步骤与存储账户密钥方式完全一致填写 Bucket Prefix、Import Method、File Name Filter、Scan all sub-folders 后点击Load preview校验最后Save Sync立即同步或Save稍后同步。创建目标存储连接Service Principal进入Settings Cloud Storage Add Target Storage选择Azure Blob Storage with Service Principal并点击Next填写字段说明Storage Title输入该存储连接在 Label Studio 中显示的名称。Storage Name输入 Azure 存储账户名称。Container Name输入 Azure 存储账户内的容器名称。Container Prefix可选填写容器内要使用的目录名例如data-set-1或data-set-1/subfolder-2。Tenant ID填写应用注册中的目录租户ID。Client ID填写应用注册中的应用程序客户端ID。Client Secret填写客户端机密值。Can delete objects from storage开启后标注在 Label Studio 中被删除时容器中对应对象也会被删除凭据需具备删除容器对象的权限。添加后点击Sync推送导出。验证与排错添加存储后连接会被自动检查若失败请依次核实Tenant ID / Client ID / Client Secret值是否正确无多余空格、机密未过期存储账户名与容器名区分大小写需严格匹配角色分配应用注册是否在存储账户上拥有Storage Blob Data Contributor角色CORS使用预签名 URL 时必须配置排查阶段可先切换到代理模式测试。第四步通过 Label Studio API 创建与同步存储除了 UI你还可以完全通过 REST API 以编程方式管理 Azure 存储连接。仓库中 api.py 与 urls.py 定义了完整的端点端点方法用途api/storages/azure/GET / POST列出 / 创建 Azure 导入存储api/storages/azure/idGET / PATCH / DELETE读取 / 更新 / 删除指定导入存储api/storages/azure/id/syncPOST同步导入存储拉取任务api/storages/azure/validatePOST校验导入存储连接api/storages/azure/filesGET列出容器内文件api/storages/export/azure/GET / POST列出 / 创建 Azure 导出存储api/storages/export/azure/idGET / PATCH / DELETE读取 / 更新 / 删除指定导出存储api/storages/export/azure/id/syncPOST同步导出存储推送标注api/storages/export/azure/validatePOST校验导出存储连接创建时使用type: azure标识 Azure 类型由序列化器StorageTypeField(defaultazure)保证。例如创建一个 Azure 导入存储的请求体大致为{ type: azure, title: my-azure-source, container: my-container, prefix: data-set-1, account_name: account-name, account_key: account-key, presign: true, presign_ttl: 15, regex_filter: .*, use_blob_urls: false, recursive_scan: true, project: 1 }创建后调用对应端点的sync接口即可触发同步校验接口则复用序列化器中的validate_connection()逻辑serializers.py异常会被提取为人类可读的错误信息返回。源码视角Azure 同步与数据流原理理解底层实现有助于你在实际项目中排错与调优。连接校验validate_connection()models.py会尝试读取容器属性容器不存在时抛出KeyError(Container not found: ...)对于导入存储还会校验prefix前缀下是否存在 bloblist_blob_names(name_starts_withprefix)找不到则报告azure-blob://container/prefix not found。对象枚举与导入AzureBlobImportStorageBase.iter_objects()支持两种扫描模式——recursive_scanTrue时用list_blobs全量递归recursive_scanFalse时用walk_blobs(delimiter/)按层级遍历并跳过目录占位符。两种模式下都会应用regex_filter正则过滤跳过不匹配的对象见日志is skipped by regex filter。get_data()则根据use_blob_urls决定导入方式开启时把每个文件包装成azure-blob://container/key形式的任务数据即“每个文件一个任务”关闭时把 JSON/JSONL/Parquet 文件内容解析成任务定义load_tasks_json。预签名 URL 生成generate_http_url()使用generate_blob_sas()生成带BlobSasPermissions(readTrue)权限、有效期presign_ttl分钟的 SAS token最终 URL 形如https://account.blob.core.windows.net/container/blob?sas。标注导出AzureBlobExportStorage.save_annotation()将标注序列化为 JSON上传到prefix/key对应的 blobupload_blob(..., overwriteTrue)并创建AzureBlobExportStorageLink建立映射。标注保存后通过 Djangopost_save信号触发异步导出start_job_async_or_sync删除标注时若开启了can_delete_objects会同步删除容器中对应对象pre_delete信号 delete_blob()。同步状态机每次同步都会驱动StorageInfo状态流转queued → in_progress → completed / completed_with_errors / failed同步失败时的 traceback、已同步任务数、耗时等元数据都会记录在存储连接的last_sync/last_sync_count/traceback/meta字段中base_models.py可在存储详情页或通过 API 查看。流式媒体代理代理模式下get_bytes_stream()解析azure-blob://URI通过AZURE.download_stream_response()统一处理 HTTP Range 请求支持bytesstart-end包含Content-Range、ETag、Last-Modified等响应头并以分块迭代器方式流式输出避免大文件音视频、高分图整块加载占用内存。常见问题速查Test connection 报 “Container not found”容器名拼写错误或大小写不匹配检查 Azure 控制台中的准确名称。报 “prefix not found”prefix下没有对象确认目录名正确且存在文件。预签名 URL 打开后浏览器报 CORS 错误确认 Blob service CORS 规则中 Allowed origins 包含你的 Label Studio 域名且方法包含GET, HEAD, OPTIONS。导入时报 “JSONDecodeError / UnicodeDecodeError”容器内混入了非 JSON 文件而导入方式仍为 “Tasks”此时应在 Import Method 中开启 “Files” 模式use_blob_urlsTrue让每个文件成为一个任务。导出后容器中没有文件确认目标存储已点击Sync且prefix没有写错导出由后台 RQ 任务异步执行可在存储状态中查看last_sync与traceback。Service Principal 连接校验失败按“验证与排错”清单逐项核对 Tenant/Client/Secret、账户容器名大小写、角色分配与 CORS。通过以上步骤你已完成 Label Studio 与 Azure Blob Storage 的完整对接既能从容器批量导入任务也能把标注结果实时写回容器实现数据标注流程与 Azure 云生态的无缝集成。【免费下载链接】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 接入 Microsoft Azure Blob Storage：源存储、目标存储与 Service Principal 完整配置指南
Label Studio 接入 Microsoft Azure Blob Storage源存储、目标存储与 Service Principal 完整配置指南【免费下载链接】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 开源仓库中的 Azure Blob 存储集成storage_azure.md展开讲解如何将 Azure Blob Storage 容器同时配置为 Label Studio 的源存储Source Storage用于导入标注任务与目标存储Target Storage用于导出标注结果并覆盖 CORS 配置、存储账户密钥认证、本地部署环境变量以及 Enterprise 版的 Service Principal 认证方式。读完本文你将能够从零完成 Azure Blob 与 Label Studio 的对接、校验连接、配置同步策略并通过源码理解其底层数据流转机制。前置概念Label Studio 云存储的工作方式在动手配置之前先明确两个基础概念。Label Studio 中的云存储分为两类详见 io_storages/README.md导入存储Source / Import Storage从云存储容器中把数据文件或任务定义同步进项目对应源码中的ImportStorage抽象基类导出存储Target / Export Storage把标注结果写回云存储容器对应ExportStorage抽象基类。Azure Blob 在源码中由label_studio/io_storages/azure_blob/目录实现其中 models.py 定义了AzureBlobImportStorage导入与AzureBlobExportStorage导出两个模型URL scheme 为azure-blob。预签名 URL 与平台代理两种数据加载方式原文档特别强调了一个关键选择Use pre-signed URLs预签名 URL与Proxy through the platform平台代理两种模式这决定了标注媒体文件如何从 Azure 流向标注者的浏览器预签名 URL 模式Label Studio 后端为容器对象生成带 SAS token 的临时 HTTPS 链接浏览器直接向https://account.blob.core.windows.net/container/blob?sas发起请求HTTP 303 重定向。媒体流量不经过 Label Studio 服务器速度更快、扩展性更好但要求容器正确配置 CORS且存储账户需要具备预签名SAS 生成权限。平台代理模式后端从 Azure 下载文件后再以流式方式转发给浏览器所有媒体流量都经过 Label Studio 服务器。数据始终停留在 Label Studio / 网络边界内每次请求都会执行任务级访问权限检查也无需配置 CORS但会消耗更多 worker 资源速度略慢。从源码看两种模式分别对应 models.py 中的generate_http_url()生成 SAS 预签名 URL与get_bytes_stream()AZURE.download_stream_response()流式下载。UI 中的开关映射到模型的presign字段默认True预签名 URL 的有效期由presign_ttl字段控制默认 1 分钟UI 默认值 15 分钟最小 1 分钟见 form_layout.yml。第一步为 Azure Blob 配置 CORS如果你计划使用平台代理模式可以跳过本节。只要使用预签名 URL就必须配置 CORS。登录 Azure 门户进入存储账户Storage account页面从左侧菜单滚动到设置 资源共享CORSSettings Resource sharing (CORS)在Blob service下添加如下规则配置项取值Allowed originshttps://app.humansignal.com或你实际使用的 Label Studio 域名Allowed methodsGET, HEAD, OPTIONSAllowed headers*Exposed headers*Max age3600点击保存。配置完成后浏览器才能通过预签名 URL 跨域读取容器中的媒体对象。若使用 Service Principal 认证且同样启用预签名 URL也必须在存储账户的 Blob service 上完成上述 CORS 配置。第二步使用存储账户密钥连接 Azure Blob Storage这是 Label Studio 开源版OSS的标准接入方式。开始前请先在 Azure 门户的存储账户资源页面收集以下三项信息容器名称Container Name位于存储账户资源页数据存储 容器Data storage Containers下存储账户名称Account Name存储账户资源页顶部访问密钥Access Key位于安全 网络 访问密钥Security networking Access keys下。创建源存储连接导入数据在 Label Studio 中打开项目进入Settings Cloud Storage Add Source Storage选择Azure Blob Storage并点击Next。配置连接Configure Connection填写以下字段后点击Test connection验证连通性字段说明Storage Title为该存储连接起一个用于标识的名称。Container Name输入 Azure 存储容器名称即上文在 Azure 控制台数据存储 容器下找到的名称。Account Name输入 Azure 存储账户名称。Account Key输入存储账户的访问密钥位于安全 网络 访问密钥下。Use pre-signed URLs (On) / Proxy through the platform (Off)决定容器数据如何加载预签名 URL 模式生成指向 Azure 对象的临时 HTTPS 链接浏览器直连需正确 CORS 与预签名权限平台代理模式由后端下载并流式转发数据不离开 Label Studio 边界每次请求都做任务级访问检查但更耗 worker 资源。Expire pre-signed URLs (minutes)控制预签名 URL 的剩余有效分钟数。导入设置与预览Import Settings Preview点击Load preview确认正在同步的数据符合预期字段说明Bucket Prefix可选。填写容器内要使用的目录名例如data-set-1或data-set-1/subfolder-2。Import Method选择“为容器中每个文件创建一个任务”或使用 JSON/JSONL/Parquet 文件来定义每个任务的数据。File Name Filter填写正则表达式过滤容器对象使用.*收集所有对象。Scan all sub-folders开启后对容器内子文件夹执行递归扫描。复核与确认Review Confirm确认无误后点击Save Sync立即同步或点击Save保存设置、稍后再同步。创建目标存储连接导出标注在 Label Studio 中打开项目进入Settings Cloud Storage Add Target Storage选择Azure Blob Storage并点击Next填写以下字段字段说明Storage Title输入用于标识该存储连接的名称。Container Name输入 Azure 存储容器名称。Container Prefix可选。填写容器内要使用的目录名例如data-set-1或data-set-1/subfolder-2。Account Name输入 Azure 存储账户名称。Account Key输入存储账户访问密钥。Can delete objects from storage开启后当标注在 Label Studio 中被删除时容器中对应的标注文件也会被删除。添加完成后点击Sync推送导出数据。本地部署使用环境变量代替 UI 输入如果你运行的是本地/自托管on-prem部署可以不把密钥手动填进 UI而是通过环境变量注入export AZURE_BLOB_ACCOUNT_NAMEyour-storage-account-name export AZURE_BLOB_ACCOUNT_KEYyour-storage-account-key源码中AzureBlobStorageMixin.get_account_name()与get_account_key()models.py的逻辑是优先使用模型字段account_name/account_key字段为空时回退到环境变量。若两者都未提供连接校验会抛出明确错误提示。底层连接使用 Azure Python SDK 的BlobServiceClient.from_connection_string()构造的字符串格式为DefaultEndpointsProtocolhttps;AccountName...;AccountKey...;EndpointSuffixcore.windows.net见 utils.py。同时要注意AzureBlobImportStorageSerializer将account_name、account_key标记为secure_fieldsserializers.py序列化返回时会主动移除这两个字段避免密钥通过 API 响应泄露。第三步Enterprise使用 Service Principal 认证连接 Azure BlobLabel Studio Enterprise 支持通过 Azure Service Principal 认证连接 Azure Blob Storage无需使用存储账户访问密钥。该方式基于 Entra ID原 Azure Active Directory身份与访问管理可授予细粒度权限并支持审计且权限可随时撤销或轮换——相比拥有存储账户完全访问权的账户密钥安全性更高。注本节为 Enterprise 专属能力开源版OSS不支持。前置条件一个 Azure 订阅和一个存储账户有权限创建应用注册App Registration并在存储账户上分配角色一个私有的数据容器如无则先创建。在 Entra 中创建 Service Principal1. 在 Entra 注册应用打开 Microsoft Entra 管理中心右侧选择应用注册点击新注册。填写名称、选择适当的账户类型重定向 URI 可留空在“概述”页复制应用程序客户端ID和目录租户ID进入证书和机密添加一个新的客户端机密并复制值Value字段。2. 在 Azure 中授予主体存储访问权限返回 Azure 门户并进入你的存储账户从存储账户左侧选择访问控制 (IAM)选择添加 添加角色分配使用搜索框定位Storage Blob Data Contributor角色并点击选中选择上方成员标签页选择用户、组或服务主体然后点击选择成员在搜索框中找到之前创建的应用名称并点击选择点击审阅 分配。3. 创建容器仍在存储账户页面点击左侧数据存储选择容器如没有容器创建一个私有访问级别的新容器。警告如果计划使用预签名 URL必须在存储账户 Blob service 上配置 CORS详见上文“为 Azure Blob 配置 CORS”一节。4. 所需权限清单源存储Source Storage需要Microsoft.Storage/storageAccounts/blobServices/containers/read.../containers/blobs/read目标存储Target Storage需要.../containers/blobs/read.../containers/blobs/write.../containers/read.../containers/blobs/delete可选以上权限均包含在内置的Storage Blob Data Contributor角色中。创建源存储连接Service Principal进入Settings Cloud Storage Add Source Storage选择Azure Blob Storage with Service Principal并点击Next。配置连接填写后点击Test connection字段说明Storage Title输入该存储连接在 Label Studio 中显示的名称。Storage Name输入 Azure 存储账户名称。Container Name输入 Azure 存储账户内的容器名称。Tenant ID填写应用注册中的目录租户ID。Client ID填写应用注册中的应用程序客户端ID。Client Secret填写之前复制的客户端机密值。Use pre-signed URLs / Proxy through the platform启用或禁用预签名 URL。Expiration minutes调整预签名 URL 的有效分钟数。导入设置与预览、复核与确认步骤与存储账户密钥方式完全一致填写 Bucket Prefix、Import Method、File Name Filter、Scan all sub-folders 后点击Load preview校验最后Save Sync立即同步或Save稍后同步。创建目标存储连接Service Principal进入Settings Cloud Storage Add Target Storage选择Azure Blob Storage with Service Principal并点击Next填写字段说明Storage Title输入该存储连接在 Label Studio 中显示的名称。Storage Name输入 Azure 存储账户名称。Container Name输入 Azure 存储账户内的容器名称。Container Prefix可选填写容器内要使用的目录名例如data-set-1或data-set-1/subfolder-2。Tenant ID填写应用注册中的目录租户ID。Client ID填写应用注册中的应用程序客户端ID。Client Secret填写客户端机密值。Can delete objects from storage开启后标注在 Label Studio 中被删除时容器中对应对象也会被删除凭据需具备删除容器对象的权限。添加后点击Sync推送导出。验证与排错添加存储后连接会被自动检查若失败请依次核实Tenant ID / Client ID / Client Secret值是否正确无多余空格、机密未过期存储账户名与容器名区分大小写需严格匹配角色分配应用注册是否在存储账户上拥有Storage Blob Data Contributor角色CORS使用预签名 URL 时必须配置排查阶段可先切换到代理模式测试。第四步通过 Label Studio API 创建与同步存储除了 UI你还可以完全通过 REST API 以编程方式管理 Azure 存储连接。仓库中 api.py 与 urls.py 定义了完整的端点端点方法用途api/storages/azure/GET / POST列出 / 创建 Azure 导入存储api/storages/azure/idGET / PATCH / DELETE读取 / 更新 / 删除指定导入存储api/storages/azure/id/syncPOST同步导入存储拉取任务api/storages/azure/validatePOST校验导入存储连接api/storages/azure/filesGET列出容器内文件api/storages/export/azure/GET / POST列出 / 创建 Azure 导出存储api/storages/export/azure/idGET / PATCH / DELETE读取 / 更新 / 删除指定导出存储api/storages/export/azure/id/syncPOST同步导出存储推送标注api/storages/export/azure/validatePOST校验导出存储连接创建时使用type: azure标识 Azure 类型由序列化器StorageTypeField(defaultazure)保证。例如创建一个 Azure 导入存储的请求体大致为{ type: azure, title: my-azure-source, container: my-container, prefix: data-set-1, account_name: account-name, account_key: account-key, presign: true, presign_ttl: 15, regex_filter: .*, use_blob_urls: false, recursive_scan: true, project: 1 }创建后调用对应端点的sync接口即可触发同步校验接口则复用序列化器中的validate_connection()逻辑serializers.py异常会被提取为人类可读的错误信息返回。源码视角Azure 同步与数据流原理理解底层实现有助于你在实际项目中排错与调优。连接校验validate_connection()models.py会尝试读取容器属性容器不存在时抛出KeyError(Container not found: ...)对于导入存储还会校验prefix前缀下是否存在 bloblist_blob_names(name_starts_withprefix)找不到则报告azure-blob://container/prefix not found。对象枚举与导入AzureBlobImportStorageBase.iter_objects()支持两种扫描模式——recursive_scanTrue时用list_blobs全量递归recursive_scanFalse时用walk_blobs(delimiter/)按层级遍历并跳过目录占位符。两种模式下都会应用regex_filter正则过滤跳过不匹配的对象见日志is skipped by regex filter。get_data()则根据use_blob_urls决定导入方式开启时把每个文件包装成azure-blob://container/key形式的任务数据即“每个文件一个任务”关闭时把 JSON/JSONL/Parquet 文件内容解析成任务定义load_tasks_json。预签名 URL 生成generate_http_url()使用generate_blob_sas()生成带BlobSasPermissions(readTrue)权限、有效期presign_ttl分钟的 SAS token最终 URL 形如https://account.blob.core.windows.net/container/blob?sas。标注导出AzureBlobExportStorage.save_annotation()将标注序列化为 JSON上传到prefix/key对应的 blobupload_blob(..., overwriteTrue)并创建AzureBlobExportStorageLink建立映射。标注保存后通过 Djangopost_save信号触发异步导出start_job_async_or_sync删除标注时若开启了can_delete_objects会同步删除容器中对应对象pre_delete信号 delete_blob()。同步状态机每次同步都会驱动StorageInfo状态流转queued → in_progress → completed / completed_with_errors / failed同步失败时的 traceback、已同步任务数、耗时等元数据都会记录在存储连接的last_sync/last_sync_count/traceback/meta字段中base_models.py可在存储详情页或通过 API 查看。流式媒体代理代理模式下get_bytes_stream()解析azure-blob://URI通过AZURE.download_stream_response()统一处理 HTTP Range 请求支持bytesstart-end包含Content-Range、ETag、Last-Modified等响应头并以分块迭代器方式流式输出避免大文件音视频、高分图整块加载占用内存。常见问题速查Test connection 报 “Container not found”容器名拼写错误或大小写不匹配检查 Azure 控制台中的准确名称。报 “prefix not found”prefix下没有对象确认目录名正确且存在文件。预签名 URL 打开后浏览器报 CORS 错误确认 Blob service CORS 规则中 Allowed origins 包含你的 Label Studio 域名且方法包含GET, HEAD, OPTIONS。导入时报 “JSONDecodeError / UnicodeDecodeError”容器内混入了非 JSON 文件而导入方式仍为 “Tasks”此时应在 Import Method 中开启 “Files” 模式use_blob_urlsTrue让每个文件成为一个任务。导出后容器中没有文件确认目标存储已点击Sync且prefix没有写错导出由后台 RQ 任务异步执行可在存储状态中查看last_sync与traceback。Service Principal 连接校验失败按“验证与排错”清单逐项核对 Tenant/Client/Secret、账户容器名大小写、角色分配与 CORS。通过以上步骤你已完成 Label Studio 与 Azure Blob Storage 的完整对接既能从容器批量导入任务也能把标注结果实时写回容器实现数据标注流程与 Azure 云生态的无缝集成。【免费下载链接】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），仅供参考