Ultralytics Platform 与 Azure Blob Storage 深度集成指南：原地索引容器数据、免上传构建并训练 YOLO 数据集

Ultralytics Platform（Ultralytics 平台）的 Azure Blob Storage 集成允许你把 Azure 存储账户中的容器直接接到工作区，图片原地留在你的容器内，Platform 仅以"索引"方式读取并解析，随后即可在 Web 端浏览、标注并训练 YOLO 模型，无需上传任何副本。阅读完本文，你将掌握获取连接字符串、完成容器连接、从 Blob 容器创建数据集、处理导入失败、启动托管训练以及安全断开/吊销访问的完整闭环，同时了解其访问范围、安全模型与当前功能边界。

适用前提：Pro 或 Enterprise 套餐

Azure Blob Storage 属于 Platform 的 Infrastructure（基础设施） 类集成（见 Integrations 总览），要求 Pro 或 Enterprise 套餐。

• Free 工作区可以看到该集成入口，但点击连接时会被引导升级。
• 一旦订阅结束，已有的 Azure Blob Storage 数据集仍然完全可访问——只有新建连接与新导入才需要 Pro 及以上套餐。
• 连接云存储需要工作区 admin 或 owner 角色（Editor/Viewer 无权限）；据角色矩阵，只有 Admin 与 Owner 可管理集成类资源，而 API 密钥仅 Owner 可创建与吊销。

该集成的核心设计原则是只读：Platform 从不写入、修改或删除你的 blob。

第一步：在 Azure 门户获取连接字符串

Platform 当前版本的集成要求账户访问密钥（access key）形式的连接字符串。尽管 Platform 实际只使用 list 与 read 两类操作，连接字符串本身携带的是账户级权限，因此请审慎对待它。

获取步骤：

1. 登录 Azure 门户，打开目标存储账户（storage account）；
2. 进入 Security + networking > Access keys；
3. 复制一份 connection string。

字符串必须同时满足：

• 携带 AccountName 与 AccountKey 字段；
• 协议为 HTTPS（即 DefaultEndpointsProtocol=https;AccountName=...;AccountKey=... 这种 Azure 在 Access keys 页面给出的标准形式）。

以下情况会被拒绝：

• 含 SharedAccessSignature 字段的 SAS 令牌连接字符串（因为缺少 AccountKey）；
• 指向**主权云（Azure China、Azure Government）**或自定义 blob 端点的字符串——连接使用标准 blob.core.windows.net 端点，仅支持 Public Azure cloud（公有云）。

从 Platform 的 Storage Integrations API 文档可见，Azure 提供方在 API 层的凭据结构为 {"provider": "azure", "credentials": {"connection_string": "DefaultEndpointsProtocol=https;AccountName=..."}}，与门户复制出的完整字符串一致。

安全建议（重要）：账户密钥一旦暴露在 Platform 之外，即可被用于写、删操作乃至签发 SAS 令牌。建议：

• 尽量使用专用存储账户承载待连接数据；
• 如需吊销访问，直接在 Azure 侧轮换（rotate）存储账户访问密钥。

第二步：把容器连接到 Platform

连接入口与步骤：

1. 打开 Settings > Integrations，从左侧集成列表选择 Azure Blob Storage；
2. 粘贴连接字符串；
3. 点击 Find available containers（查找可用容器） 并勾选要连接的容器；也可以手动输入容器名；
4. 点击 Connect。Platform 在保存任何信息之前，会先验证它能对每个选中的容器执行 list 与 read 操作，验证不通过则不会保存。

需要注意的边界：

• 一次连接最多携带 50 个容器；
• 自动发现（discovery）最多在存储账户中列出 300 个容器；
• 之后再次连接同一存储账户，会把新增容器追加到既有集成上，而不是另建一个集成；
• 保存的凭据只有在"替换凭据仍能读取你已连接的所有容器"的前提下才会被覆盖，避免误伤既有数据集。

凭据安全模型（Platform 官方说明）：

• 凭据在静态存储时以 AES-256-GCM 加密；
• 凭据永远不会回传给浏览器（即前端展示不了已保存的密钥原文）；
• 凭据永远不会暴露给训练任务——训练只使用 Platform 自身对已索引图片的副本；
• 吊销方式为在 Azure 中轮换存储账户访问密钥。

第三步：从 Blob 容器创建数据集

连接完成后，创建数据集只需几步：

1. 点击 New Dataset，切换到 Cloud（云） 标签页；
2. 选择一个已连接的容器，浏览定位到存放数据的文件夹；
3. 确认文件夹、调整数据集名称，然后创建数据集。

Platform 会只列出该文件夹一次，并对发现的内容建立索引：

• 图片：.jpg、.jpeg、.png、.webp、.avif 五种 blob 会被索引，图片尺寸通过**有界请求（bounded requests）**读取；Platform 不会持久化源图片的第二份副本（源图按需流式读取）。
• 标签：YOLO .txt 侧车文件（sidecar）会被解析为 Platform 标注，匹配方式为标准的 images/ → labels/ 目录布局，或同文件夹兄弟文件。
• 元数据：目录下的 YAML 文件提供类别名与姿态关键点形状（kpt_shape），机制与归档上传完全一致；若文件夹内有多个 YAML，优先使用 data.yaml 与 data.yml。
• 任务类型：通过对标签文件抽样自动判定任务，因此 segment、pose、OBB 文件夹是从标签形状识别的，而非对话框中你手动选择的任务。
• 划分（Splits）：blob 路径中的 train、val、test 文件夹名会自动把图片归入对应划分。

创建完成后，该数据集与普通上传数据集行为一致：可浏览与标注、设为公开/私有、与团队共享，并可通过托管训练在其上训练。源图按需流式传输，已索引的图片不消耗工作区的存储配额。

索引硬性限制

• 单次导入最多索引 50,000 个 blob，更大容器应拆分为多个数据集；
• 单个标签或 YAML 文件上限 1 MB。

保持已索引 blob 不可变（重要警告）

每个被索引的图片都会钉（pin）到其 blob 的 ETag；一旦 blob 在 Platform 下方发生变化，Platform 会fail closed（保守失败）——即宁可让读取失败，也不去使用被篡改的内容。因此正确的数据更新姿势是新增新 blob，而不是覆盖已有 blob。

导入失败怎么办：Retry import 语义

导入失败的可能原因：空文件夹、路径拼写错误、权限被吊销。此时数据集页面会显示具体错误。Editor 及以上角色可点击 Retry import，使用已保存的容器与文件夹重新启动导入；也可以新建一个指向修正后路径的数据集。

重试的关键语义：它是"重新列出"，而非"断点续传"：

• 第一次尝试之后新增的 blob 会被纳入；
• 已不存在的 blob 会被从数据集中移除。

在 Azure 数据集上训练

托管训练走的是常规训练流程即可（见云端训练与使用 Platform 数据集训练）：

• 训练期间，Platform 使用自己对已钉图片的副本，仅持续于本次运行期间；
• 你的 Azure 凭据永远不会暴露给训练负载；
• 训练数据引用也支持通过 ul://username/datasets/dataset-slug 这类 URI 在任意环境（本地、Google Colab、远程服务器）下发训练命令，Platform 会自动处理数据拉取（此机制同样适用于云端连接数据集）。

若希望在导入前先在本地校验 YOLO 数据集配置的完整性，还可以借助开源仓库 ultralytics 中 check_det_dataset 之类的工具函数先行检查 data.yaml，再确保云端文件夹结构与之匹配。

断开连接：UI 与 API 两种方式

断开连接只删除 Platform 侧保存的连接字符串，不会触碰 Azure 中的任何数据。断连后，基于这些容器构建的数据集仍留在工作区中（类别、标签、标注都在），但由于图片无法加载、预览或训练，实际处于"冻结"状态——直到同一存储账户被再次连接才会恢复可用。

除了 UI 断开按钮，官方文档提供了 REST API 方式，需要先用 GET /api/integrations/buckets 取得 integration ID：

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/integrations/buckets/INTEGRATION_ID

对应 Python SDK（读取环境变量 ULTRALYTICS_API_KEY）：

from ultralytics_platform import Platform

client = Platform()  # reads ULTRALYTICS_API_KEY
integrations = client.storage_integrations.list()
client.storage_integrations.delete("INTEGRATION_ID")

如需在源头吊销访问，则在 Azure 中轮换存储账户的访问密钥。

底层 API 补充

Storage Integrations API 还暴露了其余操作，均可通过 client.storage_integrations.* 调用：

操作	HTTP	Python SDK
列出集成	GET /api/integrations/buckets	client.storage_integrations.list()
发现容器（不保存凭据）	POST /api/integrations/buckets/discover	client.storage_integrations.discover(body=...)
连接存储	POST /api/integrations/buckets（targets 数组 1–50 个容器名）	client.storage_integrations.create(body=...)
浏览对象	GET /api/integrations/buckets/{id}/objects?target=...&prefix=...&cursor=...	client.storage_integrations.objects(id, target=...)
断开存储	DELETE /api/integrations/buckets/{id}	client.storage_integrations.delete(id)

其中 discover 的 Azure 请求体为 {"provider": "azure", "credentials": {"connection_string": "..."}}，响应返回可读容器列表 {"targets": [...]}。API 级别的断开同样只删除保存凭据，不删除提供方数据；已连接数据集保持可见但其文件不可用，且操作要求工作区 admin 权限。

当前功能边界与数据删除语义

由于 Azure 数据集的原图归你所有（Platform 不保存像素副本），以下需要 Platform 持有图片副本的功能对 Azure 数据集不可用：

• 自动标注（auto-annotation）
• 聚类分析（clustering analysis）（见数据集聚类，需至少 20 张非错误图片的普通数据集才可用）
• 数据集克隆（dataset cloning）
• 不可变版本快照（immutable version snapshots）（见数据集 Versions 页签）

删除一个 Azure 数据集、或删除其中的单张图片，只会移除 Platform 的引用记录——你的 blob 永远不会被触碰。这一点与上传型数据集形成鲜明对比：上传型数据删除即删除 Platform 持有的字节。

结语与同族集成

Azure Blob Storage 集成解决了"数据集体量很大、不想二次复制"的核心痛点，让 YOLO 训练数据既留在你自己的存储中，又能享受 Platform 的浏览、标注与托管训练能力。相似的"原地索引"能力还覆盖 Google Cloud Storage（基于服务账号 JSON 密钥）与 Amazon S3（基于 IAM 长时访问密钥，单连接单区域），三个集成共享相同的连接角色、50 桶/容器上限、50,000 对象索引上限、ETag/generation 钉扎与凭据安全模型——选定一家云厂商后，其余心智模型可无缝平移。