Integração com o Amazon S3

A integração com Amazon S3 conecta seus buckets do 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. 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 um usuário do IAM#

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. Use um usuário do IAM dedicado — nunca 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 acesso de listagem e leitura aos 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.

   Para a geração de imagens, permita também s3:PutObject:

   {
       "Effect": "Allow",
       "Action": "s3:PutObject",
       "Resource": [
           "arn:aws:s3:::my-bucket/generated/*",
           "arn:aws:s3:::my-bucket/*/generated/*",
           "arn:aws:s3:::my-bucket/.ultralytics-write-check"
       ]
   }

   O S3 não tem uma permissão exclusiva para criação, então esse escopo limita as gravações às pastas generated/ e à chave .ultralytics-write-check, que a Platform usa para testar o acesso de gravação (esse teste é sempre rejeitado, então nada é armazenado). As gravações feitas pela própria Platform nunca substituem objetos.

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 Conectar. Antes de salvar qualquer coisa, a Platform verifica se consegue listar e ler cada bucket selecionado e testa se a chave também pode gravar nele com uma solicitação que o S3 sempre rejeita, então nada é armazenado.

Cada credencial conectada tem um seletor de recursos de IA. Depois de alterar a política do IAM, conecte novamente o mesmo usuário do IAM para verificar de novo o acesso de gravação.

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.

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 Amazon S3 cujo bucket permite gravação ao usuário do IAM, 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 o mesmo usuário do IAM em Configurações > Integrações.

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 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 da AWS 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 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 conjuntos de dados baseados em S3 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 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#