Google Cloud Storage 통합#

Google Cloud Storage 통합은 GCS 버킷을 Ultralytics Platform에 연결합니다. 이미지는 버킷에 그대로 유지되며, Platform은 이미지를 제자리에서 인덱싱하므로 복사본을 업로드하지 않고도 YOLO 모델을 탐색하고, 주석을 추가하고, 학습할 수 있습니다.

읽기 전용 서비스 계정 생성#

Platform은 스토리지에서 읽기만 수행하며 객체를 쓰거나 수정하거나 삭제하지 않습니다. 읽기 권한만 있는 전용 서비스 계정을 생성합니다:

1. Google Cloud 콘솔에서 IAM & Admin > Service Accounts로 이동하여 서비스 계정을 생성합니다.
2. 연결하려는 버킷에 Storage Object Viewer (roles/storage.objectViewer) 역할을 부여합니다.
3. 서비스 계정을 열고 Keys > Add key > Create new key를 선택한 다음 JSON을 선택하고 키 파일을 다운로드합니다.

Platform에 연결#

1. **Settings > Integrations**로 이동하고 통합 목록에서 Google Cloud Storage를 선택합니다.
2. 서비스 계정 JSON 키의 내용을 붙여넣습니다.
3. Find available buckets를 클릭한 다음 연결할 버킷을 선택합니다. 서비스 계정이 버킷을 나열할 수 없으면 알고 있는 버킷 이름을 직접 입력합니다.
4. Connect를 클릭합니다. Platform은 저장하기 전에 선택한 각 버킷을 나열하고 읽을 수 있는지 확인합니다.

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

브라우저는 붙여넣은 키 파일을 읽고 Platform에 필요한 세 필드인 client_email, private_key, project_id만 전송합니다. 나머지 JSON은 페이지 밖으로 전송되지 않습니다.

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

GCS 버킷에서 데이터셋 생성#

1. New Dataset을 클릭하고 Cloud 탭을 엽니다.
2. 연결된 버킷을 선택하고 데이터가 포함된 폴더로 이동합니다.
3. 폴더를 확인하고 데이터셋 이름을 조정한 다음 데이터셋을 생성합니다.

Platform은 폴더를 한 번 나열한 후 검색된 항목을 인덱싱합니다:

• Images — .jpg, .jpeg, .png, .webp, .avif 객체는 제한된 요청을 통해 읽은 크기 정보와 함께 인덱싱됩니다. Platform은 원본 이미지의 두 번째 복사본을 저장하지 않습니다.
• Labels — YOLO .txt 사이드카는 Platform 주석으로 파싱되며, 표준 images/ → labels/ 레이아웃 또는 동일 폴더의 형제 파일 구조를 기준으로 매칭됩니다.
• Metadata — YAML 파일은 아카이브 업로드와 동일하게 클래스 이름과 pose keypoint 형상을 제공합니다. 폴더에 여러 파일이 있는 경우 data.yaml 및 data.yml가 우선 사용됩니다.
• Task — 레이블 파일 샘플을 통해 task가 결정되므로, 대화 상자에서 선택한 task가 아니라 레이블 형상에 따라 segment, pose 및 OBB 폴더가 인식됩니다.
• Splits — 객체 경로의 train, val, test 폴더 이름에 따라 split이 자동으로 할당됩니다.

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

가져오기 실패#

빈 폴더, 경로 오타 또는 취소된 권한으로 인해 가져오기가 실패하면 데이터셋 페이지에 오류가 표시됩니다. 편집자는 Retry import를 클릭하여 저장된 버킷과 폴더로 가져오기를 다시 시작하거나, 수정된 경로를 가리키는 새 데이터셋을 생성할 수 있습니다.

다시 시도하면 이어서 진행하지 않고 폴더를 다시 나열합니다. 첫 번째 시도 이후 추가된 객체는 포함되고, 더 이상 존재하지 않는 객체는 데이터셋에서 제거됩니다.

학습#

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

연결 해제#

연결을 해제하면 Google Cloud의 어떤 항목도 변경하지 않고 저장된 자격 증명만 삭제합니다. 해당 버킷에서 생성된 데이터셋은 클래스, 레이블 및 주석과 함께 워크스페이스에 유지되지만, 동일한 서비스 계정을 다시 연결할 때까지 이미지를 로드하거나 미리 보거나 학습에 사용할 수 없습니다.

GET /api/integrations/buckets에서 반환된 통합 ID를 사용하여 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")

대신 소스에서 액세스 권한을 취소하려면 Google Cloud에서 서비스 계정 키를 삭제합니다.

현재 제한 사항#

현재 GCS 기반 데이터셋에서는 이미지의 Platform 소유 복사본이 필요한 기능인 자동 주석, 클러스터링 분석, 데이터셋 복제 및 변경 불가능한 버전 스냅샷을 사용할 수 없습니다.

GCS 기반 데이터셋 또는 해당 데이터셋의 개별 이미지를 삭제하면 Platform의 참조만 제거되며, 객체에는 어떠한 작업도 수행되지 않습니다.

Amazon S3 및 Azure Blob Storage 통합도 참조하십시오.

FAQ#