Integração com o Google Cloud Storage

A integração com Google Cloud Storage conecta seus buckets do GCS à Ultralytics Platform. Suas imagens permanecem nos seus buckets — a Platform as indexa no local, para que você possa navegar, anotar e treinar modelos YOLO sem enviar uma cópia. Com os recursos de IA ativados, a Platform também pode usá-las para anotação inteligente, anotação automática, busca por imagens semelhantes e treinamento na nuvem.

Criar uma conta de serviço#

O acesso de leitura cobre tudo, exceto a geração de imagens, que também cria objetos. A Platform nunca modifica nem exclui seus objetos. Crie uma conta de serviço dedicada:

1. No console do Google Cloud, acesse IAM & Admin > Service Accounts e crie uma conta de serviço.
2. Atribua a ela a função Storage Object Viewer (roles/storage.objectViewer) nos buckets que você quer conectar. Para a geração de imagens, atribua também a função Storage Object Creator (roles/storage.objectCreator), que cria objetos, mas não pode substituí-los nem excluí-los.
3. Abra a conta de serviço, escolha Keys > Add key > Create new key, selecione JSON e baixe o arquivo de chave.

Conecte à Platform#

1. Acesse Settings > Integrations e selecione Google Cloud Storage na lista de integrações.
2. Cole o conteúdo do arquivo de chave JSON da conta de serviço.
3. Clique em Find available buckets e selecione os buckets que deseja conectar. Se a conta de serviço não puder listar buckets, digite manualmente o nome de um bucket conhecido.
4. Clique em Conectar. Antes de salvar qualquer coisa, a Platform verifica se consegue listar e ler cada bucket selecionado e pergunta ao Google Cloud se a conta de serviço também pode criar objetos. Nada é gravado.

Cada credencial conectada tem um seletor de recursos de IA. Depois de alterar as funções, conecte novamente a mesma conta de serviço para verificar de novo o acesso de gravação.

Você precisa da função de administrador ou proprietário do espaço de trabalho para conectar o armazenamento na nuvem. Você pode adicionar até 50 buckets por vez, e a descoberta lista até 300 dos buckets que a conta de serviço consegue acessar.

Seu navegador lê o arquivo de chave colado e envia apenas os três campos necessários para a Platform — client_email, private_key e project_id. O restante do JSON nunca sai da página.

Conectar novamente a mesma conta de serviço depois adiciona novos buckets à integração existente. Uma credencial salva só é substituída quando a credencial substituta ainda consegue ler todos os buckets já conectados. Se não for possível ler algum bucket, o erro informa o nome dele, inclusive se ele tiver sido conectado antes usando a mesma conta de serviço.

Recursos de IA#

Cada credencial conectada tem um seletor de recursos de IA em Configurações > Integrações, ativado por padrão. Enquanto estiver ativado, as GPUs da Ultralytics e os provedores de modelos de IA poderão usar as imagens dessa credencial para:

• Anotação inteligente com SAM e anotação automática de imagem única e em lote
• Busca por imagens semelhantes e análise de agrupamento
• Treinamento na nuvem
• Geração de imagens, em buckets com permissão de gravação

Os fornecedores de modelos de IA só participam na geração de imagens, cujos prompts são planeados pelo Google Gemini com base na imagem de origem, e nos modelos de anotação pagos, que funcionam com a chave do fornecedor do teu próprio espaço de trabalho. A Platform não guarda cópias das tuas imagens: as funcionalidades leem-nas quando necessário, o treino na cloud usa cópias temporárias durante a execução e a pesquisa de imagens semelhantes guarda um embedding de cada imagem, que é eliminado quando a imagem sai da Platform.

Desative o seletor para impedir que as imagens sejam usadas nas GPUs da Ultralytics e pelos provedores de modelos de IA. Desativá-lo interrompe novos trabalhos de IA; os trabalhos já em andamento são concluídos. Os conjuntos de dados que usam essa credencial passam a mostrar recursos de IA desativados, com um link para estas configurações, e cada recurso indisponível explica o motivo. A anotação manual, o compartilhamento e o treinamento local continuam funcionando, e os rótulos, modelos e resultados de busca que você já criou são mantidos.

Você precisa da função de administrador ou proprietário da área de trabalho para alterar o seletor. Você também pode configurá-lo com a REST API, usando o ID da integração retornado por GET /api/integrations/buckets:

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

Geração de imagens#

O recurso Gerar imagens semelhantes funciona em conjuntos de dados do Google Cloud Storage cujo bucket permite gravação à conta de serviço, enquanto os recursos de IA estão ativados. As imagens que você adiciona são gravadas em uma pasta generated/ dentro da pasta do conjunto de dados e, em seguida, adicionadas ao conjunto de dados como qualquer outra imagem indexada. A Platform só cria novos objetos nessa pasta e nunca substitui nem exclui os existentes. Se a ação indicar que precisa de acesso de gravação, conceda-o, se necessário, e conecte novamente a mesma conta de serviço em Configurações > Integrações.

Crie um conjunto de dados a partir de um bucket do GCS#

1. Clique em New Dataset e abra a aba Cloud.
2. Escolha um bucket conectado e navegue até a pasta que contém seus dados.
3. Confirme a pasta, ajuste o nome do conjunto de dados e crie-o.

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

• Imagens — os objetos .jpg, .jpeg, .png, .webp e .avif são indexados, e suas dimensões são lidas por meio de solicitações com limites. A Platform não armazena uma segunda cópia da imagem de origem.
• Rótulos — os arquivos auxiliares YOLO .txt são analisados como anotações da Platform, correspondendo ao layout padrão images/ → labels/ ou a arquivos irmãos na mesma pasta.
• Metadados — um arquivo YAML fornece os nomes das classes e o formato dos pontos-chave de pose, exatamente como um envio de arquivo compactado. data.yaml e data.yml têm preferência quando a pasta contém vários arquivos.
• Tarefa — uma amostra dos arquivos de rótulos determina a tarefa, portanto, pastas de segmentação, pose e OBB são reconhecidas pelo formato dos rótulos, não pela tarefa escolhida na caixa de diálogo.
• Divisões — nomes de pastas train, val e test no caminho do objeto atribuem divisões automaticamente.

O conjunto de dados funciona como qualquer outro: navegue por ele e anote-o, defina-o como público ou privado, compartilhe-o com sua equipe e treine com ele usando o treinamento gerenciado. Os originais são transmitidos sob demanda, e as imagens indexadas não consomem sua cota de armazenamento da Platform.

Importações com falha#

Se uma importação falhar — por causa de uma pasta vazia, um erro de digitação no caminho ou permissões revogadas —, o dataset exibe o erro na página. Os editores podem clicar em Tentar importação novamente para reiniciá-la usando o bucket e a pasta armazenados, ou criar um novo dataset apontando para o caminho corrigido.

Uma nova tentativa lista a pasta novamente, em vez de continuar de onde parou: os objetos adicionados desde a primeira tentativa são incluídos, e os objetos que não estão mais lá são removidos do dataset.

Treinamento#

O treinamento gerenciado funciona pelo fluxo normal de treinamento enquanto os recursos de IA estão ativados. Durante a execução, o treinamento usa as próprias cópias da Platform das imagens fixadas, e suas credenciais do Google Cloud nunca são expostas às cargas de trabalho de treinamento. Com os recursos de IA desativados, a caixa de diálogo de treinamento explica por que o treinamento na nuvem não está disponível e oferece o treinamento local.

Desconectar uma conexão#

Desconectar exclui as credenciais armazenadas sem alterar nada no Google Cloud. Os datasets criados com esses buckets continuam no seu workspace com suas classes, rótulos e anotações, mas não é possível carregar, visualizar ou treinar com as imagens até que a mesma conta de serviço seja conectada novamente. Mesmo desconectados, você ainda pode renomear os datasets, editar os rótulos ou excluí-los.

Para desconectar, acesse Configurações > Integrações, selecione Google Cloud Storage, clique em Desconectar ao lado da credencial e confirme. Ao abrir um dos datasets, será exibida a mensagem Google Cloud Storage desconectado, com um link para estas configurações. O dataset ficará disponível automaticamente quando você se conectar novamente.

Você também pode desconectar usando a REST API, com o ID da integração retornado 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 na origem, exclua a chave da conta de serviço no Google Cloud.

Limitações atuais#

Os conjuntos de dados baseados em GCS não incluem recursos que precisam de cópias das imagens sob controle da Platform: clonagem de conjuntos de dados, instantâneos de versões imutáveis, desfoque de rostos e colagem de imagens de outros conjuntos de dados. A anotação inteligente, a anotação automática, a busca por imagens semelhantes, o agrupamento, o treinamento na nuvem e a geração de imagens requerem que os recursos de IA estejam ativados.

Excluir um dataset vinculado ao GCS ou imagens individuais dele remove apenas as referências da Platform — os objetos nunca são alterados.

Veja também as integrações do Amazon S3 e do Azure Blob Storage.

Perguntas frequentes#