Google Cloud Storage 集成

Google Cloud Storage集成可将你的 GCS 存储桶连接到 Ultralytics Platform。图像会保留在你的存储桶中——Platform 会直接为图像建立索引，因此你无需上传副本，即可浏览、标注图像并训练 YOLO 模型。开启 AI 功能后，Platform 还可使用这些图像进行智能标注、自动标注、相似图像搜索和云端训练。

创建服务账号#

读取权限涵盖所有操作，只有图像生成例外，因为图像生成也会创建对象。Platform 永远不会修改或删除你的对象。请创建专用服务账号：

1. 在 Google Cloud 控制台中，前往 IAM & Admin > Service Accounts，然后创建服务账号。
2. 为你要连接的存储桶授予 Storage Object Viewer（roles/storage.objectViewer）角色。若要使用图像生成，还需授予 Storage Object Creator（roles/storage.objectCreator）角色；该角色可以创建对象，但无法覆盖或删除对象。
3. 打开服务账号，选择 Keys > Add key > Create new key，选择 JSON，然后下载密钥文件。

连接到 Platform#

1. 前往 Settings > Integrations，然后从集成列表中选择 Google Cloud Storage。
2. 粘贴服务账号 JSON 密钥的内容。
3. 点击 Find available buckets，然后选择要连接的存储桶。如果服务账号无法列出存储桶， 请手动输入已知的存储桶名称。
4. 点击 连接。Platform 会在保存任何内容之前验证其是否可以列出和读取每个选定的存储桶，并向 Google Cloud 查询该服务账号是否也能创建对象。不会写入任何内容。

每个已连接的凭据都有一个 AI 功能开关。更改角色后，请使用同一服务账号重新连接，以重新检查写入权限。

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

浏览器会读取你粘贴的密钥文件，只发送 Platform 所需的三个字段 — client_email、private_key， 以及 project_id。JSON 中的其他内容不会离开当前页面。

稍后重新连接同一个服务账号时，新存储桶会添加到现有集成中。只有在替换凭据仍能读取你已连接的所有存储桶时，已保存的凭据才会被替换。如果任何存储桶无法读取，错误信息会指出该存储桶，包括之前使用同一服务账号连接的存储桶。

AI 功能#

每个已连接的凭据都在 Settings > Integrations 中有一个默认开启的 AI 功能开关。开启期间，Ultralytics GPU 和 AI 模型提供商可能会将该凭据中的图像用于：

• SAM 智能标注，以及单张图像和批量自动标注
• 相似图像搜索和聚类分析
• 云端训练
• 图像生成，仅限具有写入权限的存储桶

AI 模型服务商仅会参与图像生成（Google Gemini 会根据源图像规划提示词）和付费标注模型的处理（这些模型使用你工作区自己的服务商密钥运行）。Platform 不会保存你的图像副本：各项功能会按需读取图像，云端训练会在训练运行期间使用临时副本，而相似图像搜索会为每张图像保存一个嵌入，图像从 Platform 中移除时，该嵌入也会删除。

关闭开关后，图像不会发送到 Ultralytics GPU 或 AI 模型提供商。关闭开关会停止新的 AI 任务；已经运行的任务会完成。使用该凭据的数据集随后会显示 AI 功能已关闭，并提供返回这些设置的链接；每项不可用功能也会说明原因。手动标注、共享和本地训练仍可正常使用；你已创建的标签、模型和搜索结果都会保留。

你需要拥有工作区管理员或所有者角色才能更改此开关。你也可以使用 REST API进行设置，并使用 GET /api/integrations/buckets 返回的集成 ID：

curl -X PATCH \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"processing": false}' \
  https://platform.ultralytics.com/api/integrations/buckets/INTEGRATION_ID

图像生成#

只要 AI 功能已开启，且服务账号有权写入存储桶，生成相似图像就可用于 Google Cloud Storage 数据集。你添加的图像会写入数据集文件夹中的 generated/ 文件夹，然后像其他已建立索引的图像一样添加到数据集中。Platform 只会在那里创建新对象，绝不会覆盖或删除现有对象。如果操作提示需要写入权限，请按需授予权限，然后在 Settings > Integrations 中使用同一服务账号重新连接。

从 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 的存储配额。

导入失败#

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

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

训练#

开启 AI 功能后，你可以通过常规训练流程进行托管训练。训练会在运行期间使用 Platform 自己保存的已固定图像副本，你的 Google Cloud 凭据绝不会暴露给训练工作负载。关闭 AI 功能后，训练对话框会说明云端训练不可用的原因，并提供本地训练选项。

断开连接#

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

如需断开连接，请前往 Settings > Integrations，选择 Google Cloud Storage，点击凭据旁边的 Disconnect，然后确认。之后打开相关数据集时，会显示 Google Cloud Storage Disconnected，并提供返回这些设置的链接；重新连接后，数据集会自动恢复。

你也可以使用 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 持有图像副本的功能：克隆数据集、不可变的版本快照、人脸模糊处理，以及从其他数据集粘贴图像。智能标注、自动标注、相似图像搜索、聚类、云端训练和图像生成均需要开启 AI 功能。

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

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

常见问题#