Google Cloud Storage 集成#

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

创建只读服务账号#

平台只会从你的存储中读取数据——绝不会写入、修改或删除你的对象。创建一个仅具有读取权限的专用服务账号：

1. 在 Google Cloud 控制台中，转到 IAM & Admin > Service Accounts，然后创建服务账号。
2. 在你想要连接的存储桶上，为其授予 Storage Object Viewer（roles/storage.objectViewer）角色。
3. 打开服务账号，选择 Keys > Add key > Create new key，选择 JSON，然后下载密钥文件。

连接到平台#

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

你需要拥有工作区管理员或所有者角色才能连接云存储。一个 连接最多可包含 50 个存储桶，发现功能最多会列出服务账号可见的 300 个存储桶。

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

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

从 GCS 存储桶创建数据集#

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

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

• 图像 — .jpg、.jpeg、.png、.webp 和 .avif 对象会通过有界请求读取尺寸并建立索引。平台不会持久化源图像的第二个副本。
• 标签 — YOLO .txt 伴随文件会被解析为平台标注，并按照标准的 images/ → labels/ 布局进行匹配，或与同一文件夹中的同级文件匹配。
• 元数据 — YAML 文件提供类别名称和姿态关键点形状，处理方式与存档上传完全相同。当文件夹中有多个 YAML 文件时，优先使用 data.yaml 和 data.yml。
• 任务 — 系统会根据标签文件样本确定任务，因此会依据标签形状识别分割、姿态和 OBB 文件夹，而不是使用你在对话框中选择的任务。
• 划分 — 对象路径中的 train、val 和 test 文件夹名称会自动分配数据集划分。

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

导入失败#

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

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

训练#

托管训练通过常规训练流程运行。训练期间，平台会使用已固定图像的自有副本，你的 Google Cloud 凭据绝不会暴露给训练工作负载。

断开连接#

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

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

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 的数据集目前不支持需要平台拥有图像副本的功能：自动标注、聚类分析、数据集克隆和不可变的版本快照。

删除基于 GCS 的数据集或其中的单个图像时，只会移除平台的引用——你的对象绝不会受到影响。

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

常见问题#