Ultralytics YOLO27：

Google Cloud Storage 集成#

Google Cloud Storage 集成可将你的 GCS 存储桶连接到 Ultralytics Platform。你的图像会保留在存储桶中，Platform 会直接在原位置为图像建立索引，因此你可以浏览、标注并训练 YOLO 模型，无需上传副本。

Pro 功能

Google Cloud Storage 数据集需要Pro 或 Enterprise 套餐。免费工作区可以看到此集成，但在连接时会收到升级提示。订阅到期后，现有 Google Cloud Storage 数据集仍可正常访问；只有新建连接和导入才需要 Pro。

创建只读服务账号#

Platform 只会读取你的存储内容，不会写入、修改或删除任何对象。请创建一个只有读取权限的专用服务账号：

  1. 在 Google Cloud 控制台中，前往 IAM & Admin > Service Accounts，然后创建一个服务账号。
  2. 为该账号授予你要连接的存储桶上的 Storage Object Viewer (roles/storage.objectViewer) 角色。
  3. 打开该服务账号，选择 Keys > Add key > Create new key，选择 JSON，然后下载密钥文件。
存储桶发现还需要一项权限

roles/storage.objectViewer 涵盖 Platform 对你的数据执行的所有操作，但不允许列出项目中的存储桶。如果你希望 Platform 自动查找存储桶，请添加包含 storage.buckets.list 的角色；否则，连接时请手动输入每个存储桶名称。

连接到 Platform#

  1. 前往 Settings > Integrations，然后从集成列表中选择 Google Cloud Storage。
  2. 粘贴服务账号 JSON 密钥的内容。
  3. 点击 Find available buckets，然后选择要连接的存储桶。如果服务账号无法列出存储桶，请手动输入已知的存储桶名称。
  4. 点击 Connect。Platform 会先验证其能否列出并读取每个所选存储桶，然后才保存任何内容。

Ultralytics Platform Google Cloud Storage 集成设置

你需要具有工作区管理员或所有者角色，才能连接云存储。一个连接最多可关联 50 个存储桶，发现功能最多可列出服务账号能够访问的 300 个存储桶。

你的浏览器会读取粘贴的密钥文件，并且只发送 Platform 所需的三个字段——client_email、private_key 和 project_id。JSON 的其余内容不会离开此页面。

之后重新连接同一个服务账号时，新存储桶会添加到现有集成中。只有在替换凭据仍能读取你已连接的所有存储桶时，已保存的凭据才会被替换。

凭据安全

凭据在静态存储时使用 AES-256-GCM 加密，不会返回给浏览器，也不会暴露给训练工作负载。若要撤销访问权限，请在 Google Cloud 中删除服务账号密钥。

根据 GCS 存储桶创建数据集#

  1. 点击 New Dataset，然后打开 Cloud 标签页。
  2. 选择一个已连接的存储桶，并浏览到包含数据的文件夹。
  3. 确认文件夹，调整数据集名称，然后创建数据集。

Platform 会列出该文件夹一次，并为找到的内容建立索引：

  • 图像 — .jpg、.jpeg、.png、.webp 和 .avif 对象会通过有大小限制的请求读取尺寸并建立索引。Platform 不会额外保存源图像的副本。
  • 标签 — YOLO .txt 附属文件会解析为 Platform 标注，并按照标准的 images/ → labels/ 目录结构进行匹配，或与同一文件夹中的文件进行匹配。
  • 元数据 — YAML 文件会提供类别名称和姿态关键点形状，与压缩包上传的处理方式完全相同。如果文件夹中有多个文件，则优先使用 data.yaml 和 data.yml。
  • 任务 — 系统会根据部分标签文件判断任务，因此会依据标签形状识别分割、姿态和 OBB 文件夹，而不是依据你在对话框中选择的任务。
  • 数据集划分 — 对象路径中的 train、val 和 test 文件夹名称会自动分配数据集划分。

此后，该数据集的使用方式与其他数据集相同：你可以浏览并标注，将其设为公开或私有，与团队共享，并通过托管训练在其上训练。原始图像会按需流式传输，已建立索引的图像不会占用 Platform 的存储配额。

限制

单次导入最多为 500,000 个对象建立索引；标签或 YAML 文件的大小上限为 1 MB。对于更大的存储桶，应将内容拆分到多个数据集中。

确保已建立索引的对象保持不变

每张已建立索引的图像都会绑定到其 GCS 对象的版本代次；如果对象在此期间发生变化，Platform 会采取关闭失败（fail-closed）措施。请添加新对象，而不要覆盖现有对象。

导入失败#

如果导入失败（例如文件夹为空、路径拼写错误或权限被撤销），数据集页面会显示错误。编辑者可以点击 Retry import，使用已保存的存储桶和文件夹重新启动导入，也可以创建一个指向正确路径的新数据集。

重试时会重新列出文件夹，而不是从中断处继续：首次尝试后添加的对象会被纳入，已不存在的对象则会从数据集中移除。

训练#

托管训练通过常规训练流程运行。在训练期间，训练使用 Platform 自己保存的、已绑定版本的图像副本；你的 Google Cloud 凭据绝不会暴露给训练工作负载。

断开连接#

断开连接会删除已保存的凭据，但不会更改 Google Cloud 中的任何内容。根据这些存储桶创建的数据集仍会保留在你的工作区中，包括类别、标签和标注；但在重新连接同一个服务账号之前，无法加载、预览或训练这些数据集中的图像。

使用 REST API 和 GET /api/integrations/buckets 返回的集成 ID：

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

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

如果要直接在源端撤销访问权限，请在 Google Cloud 中删除服务账号密钥。

当前限制#

目前，基于 GCS 的数据集不支持需要 Platform 自行保存图像副本的功能：自动标注、聚类分析、数据集克隆和不可变的版本快照。

删除基于 GCS 的数据集或其中的单张图像，只会移除 Platform 保存的引用，不会触及你的对象。

另请参阅 Amazon S3 和 Azure Blob Storage 集成。

常见问题#

  • 不会。Platform 会列出存储桶一次，并为找到的图像尺寸和标签建立索引。浏览和标注时，原始图像会按需流式传输；托管训练仅在训练运行期间使用 Platform 自己保存的、已绑定版本的图像副本。已建立索引的图像不会计入你的存储配额。

  • 数据集在创建时只建立一次索引。只有创建新数据集或重试失败的导入，才能纳入新对象；每张已建立索引的图像都会绑定到其版本，因此覆盖对象会导致 Platform 对该图像采取关闭失败措施。请添加新对象，而不要替换现有对象。

  • 已连接的数据集不支持需要 Platform 自行保存图像副本的功能：自动标注、聚类分析、数据集克隆和不可变的版本快照。手动标注、共享和训练均可正常使用。

  • 在 Settings > Integrations 中断开该集成以删除已保存的凭据，或者在 Google Cloud 中删除服务账号密钥。这两种操作都不会触及存储桶中的数据。

贡献者
GLglenn-jocher7RAraimbekovm2PDpderrenger1

评论