Integração com o Amazon S3#

A integração com o Amazon S3 conecta seus buckets S3 à 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.

Criar um usuário IAM somente leitura#

A Platform apenas lê seus dados — nunca grava, modifica ou exclui seus objetos. Use um usuário IAM dedicado, com acesso somente para listar e ler — nunca use credenciais root:

1. No console da AWS, acesse IAM > Usuários e crie um usuário sem acesso ao console.

2. Anexe uma política que conceda apenas acesso para listar e ler os buckets que você quer conectar:

   {
       "Version": "2012-10-17",
       "Statement": [
           { "Effect": "Allow", "Action": "s3:ListAllMyBuckets", "Resource": "*" },
           {
               "Effect": "Allow",
               "Action": ["s3:ListBucket", "s3:GetObject"],
               "Resource": ["arn:aws:s3:::my-bucket", "arn:aws:s3:::my-bucket/*"]
           }
       ]
   }

   s3:ListAllMyBuckets é opcional — permite que a Platform descubra seus buckets para que você não precise digitar os nomes.

3. Abra a guia Credenciais de segurança do usuário, crie uma chave de acesso e copie o ID da chave de acesso e a chave de acesso secreta.

Conecte à Platform#

1. Acesse Configurações > Integrações e selecione Amazon S3 na lista de integrações.
2. Insira o ID da chave de acesso, a chave de acesso secreta e a região do bucket (por exemplo, us-east-1).
3. Clique em Localizar buckets disponíveis e selecione os buckets que deseja conectar. Se a política não permitir a descoberta, insira manualmente o nome de um bucket conhecido.
4. Clique em Connect. A Platform verifica se consegue listar e ler cada bucket selecionado antes de salvar qualquer dado.

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

Se você reconectar o mesmo usuário IAM posteriormente, novos buckets serão adicionados à integração existente. Uma credencial salva só será substituída quando a nova credencial ainda puder ler todos os buckets já conectados. Se não for possível ler algum bucket, o erro identificará esse bucket, incluindo os conectados anteriormente com o mesmo usuário IAM.

Criar um dataset a partir de um bucket S3#

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 — Os nomes de pasta train, val e test na chave 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 de treinamento normal. Durante a execução, o treinamento usa as próprias cópias da Platform das imagens vinculadas, e suas credenciais da AWS nunca são expostas às cargas de trabalho de treinamento.

Desconectar uma conexão#

Desconectar exclui as credenciais armazenadas sem alterar nada na AWS. 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 o mesmo usuário IAM seja conectado novamente. Mesmo desconectados, você ainda pode renomear os datasets, editar os rótulos ou excluí-los.

Para desconectar, acesse Configurações > Integrações, selecione Amazon S3, clique em Desconectar ao lado da credencial e confirme. Ao abrir um dos datasets, será exibida a mensagem Amazon S3 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, desative ou exclua a chave de acesso no AWS IAM.

Limitações atuais#

Os datasets vinculados ao S3 atualmente não incluem recursos que exigem cópias das imagens mantidas pela Platform: anotação automática, análise de agrupamento, clonagem de datasets e instantâneos imutáveis de versões.

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

Veja também as integrações do Google Cloud Storage e do Azure Blob Storage.

Perguntas frequentes#