Amazon S3 통합#

Amazon S3 통합을 사용하면 S3 버킷을 Ultralytics Platform에 연결할 수 있습니다. 이미지는 버킷에 그대로 유지되며, Platform은 이미지를 복사하지 않고 원래 위치에서 인덱싱하므로 YOLO 모델을 탐색하고, 어노테이션을 추가하고, 학습시킬 수 있습니다.

읽기 전용 IAM 사용자 생성#

Platform은 스토리지에서 데이터를 읽기만 하며, 객체를 쓰거나 수정하거나 삭제하지 않습니다. 루트 자격 증명은 사용하지 말고, 목록 조회 및 읽기 권한만 있는 전용 IAM 사용자를 사용하세요.

1. AWS 콘솔에서 IAM > Users로 이동하고 콘솔 액세스 권한이 없는 사용자를 생성합니다.

2. 연결할 버킷에 대해서만 목록 조회 및 읽기 권한을 부여하는 정책을 연결합니다.

   {
       "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은 선택 사항입니다. 이 옵션을 사용하면 Platform에서 버킷을 검색하므로 버킷 이름을 직접 입력하지 않아도 됩니다.

3. 사용자의 Security credentials 탭을 열고 access key를 생성한 다음, 액세스 키 ID와 비밀 액세스 키를 복사합니다.

Platform에 연결#

1. **Settings > Integrations**로 이동한 다음 통합 목록에서 Amazon S3를 선택합니다.
2. 액세스 키 ID, 비밀 액세스 키, 버킷 리전을 입력합니다(예: us-east-1).
3. Find available buckets를 클릭한 다음 연결할 버킷을 선택합니다. 정책에서 버킷 검색을 허용하지 않는 경우 알려진 버킷 이름을 직접 입력하세요.
4. 연결을 클릭합니다. Platform은 저장하기 전에 선택한 각 버킷의 목록을 조회하고 내용을 읽을 수 있는지 확인합니다.

클라우드 스토리지를 연결하려면 워크스페이스 관리자 또는 소유자 역할이 필요합니다. 연결 하나당 최대 50개의 버킷을 사용할 수 있으며, 검색 결과에는 키로 액세스할 수 있는 버킷 중 최대 300개가 표시됩니다.

나중에 동일한 IAM 사용자로 다시 연결하면 기존 통합에 새 버킷이 추가됩니다. 저장된 자격 증명은 새 자격 증명으로 연결된 모든 기존 버킷에 계속 읽기 액세스할 수 있는 경우에만 교체됩니다.

S3 버킷에서 데이터 세트 생성#

1. 새 데이터 세트를 클릭하고 클라우드 탭을 엽니다.
2. 연결된 버킷을 선택하고 데이터가 포함된 폴더를 찾습니다.
3. 폴더를 확인하고 데이터 세트 이름을 조정한 다음 데이터 세트를 만듭니다.

Platform은 폴더 목록을 한 번 조회하고 찾은 항목을 색인합니다.

• 이미지 — .jpg, .jpeg, .png, .webp, .avif 객체는 제한된 요청을 통해 크기를 읽어 색인합니다. Platform은 원본 이미지의 사본을 별도로 저장하지 않습니다.
• 레이블 — YOLO .txt 사이드카 파일을 파싱해 Platform 주석으로 변환합니다. 표준 images/ → labels/ 구조 또는 동일 폴더 내 형제 파일 구조를 기준으로 일치시킵니다.
• 메타데이터 — YAML 파일은 아카이브 업로드와 마찬가지로 클래스 이름과 포즈 키포인트 형태를 제공합니다. 폴더에 여러 파일이 있는 경우 data.yaml과 data.yml를 우선 사용합니다.
• 작업 — 레이블 파일 샘플을 바탕으로 작업을 결정하므로 대화상자에서 선택한 작업이 아니라 레이블 형태를 기준으로 세그먼테이션, 포즈, OBB 폴더를 인식합니다.
• 분할 — 객체 키의 train, val, test 폴더 이름에 따라 분할이 자동으로 지정됩니다.

이후 데이터 세트는 다른 데이터 세트와 동일하게 작동합니다. 데이터 세트를 탐색하고 주석을 달고, 공개 또는 비공개로 설정하고, 팀과 공유하며, 관리형 학습을 통해 학습할 수 있습니다. 원본은 요청 시 스트리밍되며, 색인된 이미지는 Platform 스토리지 할당량을 사용하지 않습니다.

가져오기 실패#

폴더가 비어 있거나 경로에 오타가 있거나 권한이 취소되어 가져오기에 실패하면 데이터 세트 페이지에 오류가 표시됩니다. 편집자는 가져오기 재시도를 클릭해 저장된 버킷과 폴더를 사용하여 다시 시작하거나, 올바른 경로를 가리키는 새 데이터 세트를 만들 수 있습니다.

재시도는 가져오기를 이어서 진행하는 대신 폴더 목록을 다시 조회합니다. 따라서 첫 번째 시도 이후 추가된 객체는 가져오고 더 이상 존재하지 않는 객체는 데이터 세트에서 제외합니다.

학습#

관리형 학습은 일반 학습 흐름을 통해 실행됩니다. 학습이 진행되는 동안 고정된 이미지의 Platform 자체 사본을 사용하며, AWS 자격 증명은 학습 워크로드에 노출되지 않습니다.

연결 해제#

연결을 해제하면 AWS의 항목에는 영향을 주지 않고 저장된 자격 증명만 삭제됩니다. 해당 버킷에서 생성한 데이터 세트와 클래스, 레이블, 어노테이션은 워크스페이스에 그대로 남지만, 동일한 IAM 사용자를 다시 연결할 때까지 이미지를 불러오거나 미리 보거나 학습에 사용할 수 없습니다.

통합 ID와 GET /api/integrations/buckets이 반환한 값을 사용해 REST API를 호출합니다.

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

대신 원본에서 액세스 권한을 취소하려면 AWS IAM에서 액세스 키를 비활성화하거나 삭제하세요.

현재 제한 사항#

S3 기반 데이터 세트에서는 이미지의 Platform 소유 사본이 필요한 기능(자동 어노테이션, 클러스터링 분석, 데이터 세트 복제, 변경 불가능한 버전 스냅샷)을 현재 사용할 수 없습니다.

S3 기반 데이터 세트 또는 그 안의 개별 이미지를 삭제해도 Platform의 참조만 제거되며, 객체에는 영향을 주지 않습니다.

Google Cloud Storage 및 Azure Blob Storage 통합도 참조하세요.

자주 묻는 질문#