Integração com o Google Cloud Storage#

A integração com o Google Cloud Storage liga os teus buckets GCS à Ultralytics Platform. As tuas imagens permanecem nos teus buckets — a Platform indexa-as no local, para que possas explorá-las, anotá-las e treinar modelos YOLO sem carregar uma cópia.

Criar uma conta de serviço apenas de leitura#

A Platform apenas lê o teu armazenamento — nunca grava, modifica ou elimina os teus objetos. Cria uma conta de serviço dedicada com acesso apenas de leitura:

1. Na consola do Google Cloud, acede a IAM & Admin > Service Accounts e cria uma conta de serviço.
2. Atribui-lhe a função Storage Object Viewer (roles/storage.objectViewer) nos buckets que queres ligar.
3. Abre a conta de serviço, escolhe Keys > Add key > Create new key, seleciona JSON e transfere o ficheiro de chave.

Ligar à Platform#

1. Acede a Settings > Integrations e seleciona Google Cloud Storage na lista de integrações.
2. Cola o conteúdo da chave JSON da conta de serviço.
3. Clica em Find available buckets e seleciona os buckets a ligar. Se a conta de serviço não conseguir listar buckets, introduz manualmente um nome de bucket conhecido.
4. Clica em Connect. A Platform verifica se consegue listar e ler cada bucket selecionado antes de guardar qualquer informação.

Precisas da função de administrador ou proprietário do espaço de trabalho para ligar o armazenamento na nuvem. Uma ligação suporta até 50 buckets, e a descoberta lista até 300 dos buckets que a conta de serviço consegue ver.

O teu navegador lê o ficheiro de chave colado e envia apenas os três campos de que a Platform precisa — client_email, private_key, e project_id. O restante JSON nunca sai da página.

Voltar a ligar a mesma conta de serviço mais tarde adiciona novos buckets à integração existente. Uma credencial guardada só é substituída depois de se verificar que a sua substituta continua a conseguir ler todos os buckets que já ligaste.

Criar um dataset a partir de um bucket GCS#

1. Clica em New Dataset e abre o separador Cloud.
2. Seleciona um bucket ligado e navega até à pasta que contém os teus dados.
3. Confirma a pasta, ajusta o nome do dataset e cria o dataset.

A Platform lista a pasta uma vez e indexa o que encontra:

• Imagens — os objetos .jpg, .jpeg, .png, .webp e .avif são indexados com dimensões lidas através de pedidos limitados. A Platform não guarda uma segunda cópia da imagem de origem.
• Etiquetas — os ficheiros associados .txt do YOLO são analisados em anotações da Platform, correspondidos pelo esquema padrão images/ → labels/ ou como elementos irmãos na mesma pasta.
• Metadados — um ficheiro YAML fornece os nomes das classes e a estrutura dos pontos-chave de pose, exatamente como num carregamento de arquivo. Dá-se preferência a data.yaml e data.yml quando a pasta contém vários ficheiros.
• Tarefa — uma amostra dos ficheiros de etiquetas determina a tarefa, pelo que as pastas de segmentação, pose e OBB são reconhecidas pela estrutura das respetivas etiquetas, e não pela tarefa escolhida na caixa de diálogo.
• Divisões — os nomes de pastas train, val e test no caminho do objeto atribuem automaticamente as divisões.

O dataset passa então a comportar-se como qualquer outro: explora-o e anota-o, define-o como público ou privado, partilha-o com a tua equipa e treina com ele através do treino gerido. Os originais são transmitidos conforme necessário, e as imagens indexadas não consomem a tua quota de armazenamento da Platform.

Importações falhadas#

Se uma importação falhar — devido a uma pasta vazia, a um erro no caminho ou a permissões revogadas — o dataset apresenta o erro na sua página. Os editores podem clicar em Retry import para a reiniciar com o bucket e a pasta guardados, ou criar um novo dataset que aponte para o caminho corrigido.

Uma nova tentativa volta a listar a pasta em vez de retomar a operação: os objetos adicionados desde a primeira tentativa são incluídos, e os objetos que já não existem são removidos do dataset.

Treino#

O treino gerido funciona através do fluxo de treino normal. Durante a execução, o treino utiliza as próprias cópias da Platform das imagens associadas, e as tuas credenciais do Google Cloud nunca são expostas a cargas de trabalho de treino.

Desligar uma ligação#

Desligar elimina as credenciais guardadas sem tocar em nada no Google Cloud. Os datasets criados a partir desses buckets permanecem no teu espaço de trabalho com as respetivas classes, etiquetas e anotações, mas as suas imagens não podem ser carregadas, pré-visualizadas ou utilizadas no treino até que a mesma conta de serviço seja ligada novamente.

Utiliza a REST API com o ID da integração devolvido por GET /api/integrations/buckets:

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")

Para revogar o acesso diretamente na origem, elimina a chave da conta de serviço no Google Cloud.

Limitações atuais#

Os datasets baseados em GCS excluem atualmente funcionalidades que requerem cópias das imagens pertencentes à Platform: anotação automática, análise de clustering, clonagem de datasets e snapshots de versões imutáveis.

Eliminar um dataset baseado em GCS, ou imagens individuais do mesmo, remove apenas as referências da Platform — os teus objetos nunca são alterados.

Consulta também as integrações com Amazon S3 e Azure Blob Storage.

Perguntas frequentes#