Google Cloud Storage 통합

Google Cloud Storage 통합을 사용하면 GCS 버킷을 Ultralytics Platform에 연결할 수 있습니다. 이미지는 버킷에 그대로 보관됩니다. Platform은 이미지를 제자리에서 인덱싱하므로 사본을 업로드하지 않고도 YOLO 모델을 탐색하고 어노테이션하며 학습할 수 있습니다. AI 기능이 켜져 있으면 Platform은 스마트 어노테이션, 자동 어노테이션, 유사 이미지 검색 및 클라우드 학습에도 이미지를 사용할 수 있습니다.

서비스 계정 만들기#

읽기 권한으로 이미지 생성을 제외한 모든 작업을 수행할 수 있으며, 이미지 생성에는 객체 생성 권한도 필요합니다. Platform은 객체를 수정하거나 삭제하지 않습니다. 전용 서비스 계정을 만드세요.

1. Google Cloud 콘솔에서 IAM 및 관리자 > 서비스 계정으로 이동해 서비스 계정을 만듭니다.
2. 연결하려는 버킷에 Storage Object Viewer (roles/storage.objectViewer) 역할을 부여합니다. 이미지 생성을 사용하려면 객체를 만들 수 있지만 덮어쓰거나 삭제할 수는 없는 Storage Object Creator (roles/storage.objectCreator) 역할도 부여하세요.
3. 서비스 계정을 열고 키 > 키 추가 > 새 키 만들기를 선택한 다음, JSON을 선택하고 키 파일을 다운로드합니다.

Platform에 연결하기#

1. 설정 > 통합으로 이동한 다음 통합 목록에서 Google Cloud Storage를 선택합니다.
2. 서비스 계정 JSON 키의 내용을 붙여 넣습니다.
3. 사용 가능한 버킷 찾기를 클릭한 다음 연결할 버킷을 선택합니다. 서비스 계정에서 버킷 목록을 조회할 수 없다면 알려진 버킷 이름을 직접 입력하세요.
4. Connect를 클릭합니다. Platform은 저장하기 전에 선택한 각 버킷을 나열하고 읽을 수 있는지 확인하며, 서비스 계정으로 객체도 만들 수 있는지 Google Cloud에 확인합니다. 아무것도 기록되지 않습니다.

연결된 각 자격 증명에는 AI 기능 스위치가 있습니다. 역할을 변경한 후에는 동일한 서비스 계정을 다시 연결해 쓰기 권한을 재확인하세요.

클라우드 스토리지를 연결하려면 작업 공간 관리자 또는 소유자 역할이 필요합니다. 한 번에 최대 50개의 버킷을 추가할 수 있으며, 검색 결과에는 서비스 계정에서 액세스할 수 있는 버킷 중 최대 300개가 표시됩니다.

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

나중에 동일한 서비스 계정을 다시 연결하면 기존 통합에 새 버킷이 추가됩니다. 저장된 자격 증명은 교체용 자격 증명으로 이미 연결된 모든 버킷을 계속 읽을 수 있는 경우에만 교체됩니다. 버킷을 하나라도 읽을 수 없으면 같은 서비스 계정으로 이전에 연결한 버킷을 포함해 해당 버킷의 이름이 오류에 표시됩니다.

AI 기능#

연결된 각 자격 증명에는 기본적으로 켜져 있는 Settings > Integrations의 AI 기능 스위치가 있습니다. 스위치가 켜져 있으면 Ultralytics GPU와 AI 모델 제공업체가 해당 자격 증명의 이미지를 다음 용도로 사용할 수 있습니다.

• SAM 스마트 어노테이션 및 단일 이미지·배치 자동 어노테이션
• 유사 이미지 검색 및 클러스터링 분석
• 클라우드 학습
• 쓰기 권한이 있는 버킷에서 이미지 생성

AI 모델 제공업체는 Google Gemini가 원본 이미지의 프롬프트를 계획하는 이미지 생성과, 워크스페이스 자체 제공업체 키로 실행되는 유료 어노테이션 모델에만 관여합니다. Platform은 이미지 사본을 보관하지 않습니다. 기능은 필요할 때 이미지를 읽고, 클라우드 학습은 실행 시간 동안 임시 사본을 사용하며, 유사 이미지 검색은 각 이미지의 임베딩을 보관하다가 이미지가 Platform에서 제거되면 삭제합니다.

이미지가 Ultralytics GPU와 AI 모델 제공업체에 전달되지 않도록 스위치를 끄세요. 스위치를 끄면 새로운 AI 작업이 중단되지만, 이미 실행 중인 작업은 완료됩니다. 해당 자격 증명을 사용하는 데이터셋에는 AI features off가 표시되고 이 설정으로 돌아가는 링크가 제공되며, 사용할 수 없는 각 기능에는 그 이유가 안내됩니다. 수동 어노테이션, 공유 및 로컬 학습은 계속 사용할 수 있으며, 이미 생성한 라벨, 모델 및 검색 결과도 유지됩니다.

스위치를 변경하려면 워크스페이스 관리자 또는 소유자 역할이 필요합니다. REST API를 사용해 설정할 수도 있으며, GET /api/integrations/buckets에서 반환된 통합 ID를 사용합니다.

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

이미지 생성#

유사 이미지 생성은 서비스 계정에 쓰기 권한이 있는 버킷을 사용하는 Google Cloud Storage 데이터셋에서 AI 기능이 켜져 있을 때 작동합니다. 추가한 이미지는 데이터셋 폴더 안의 generated/ 폴더에 기록된 다음, 다른 인덱싱된 이미지와 마찬가지로 데이터셋에 추가됩니다. Platform은 해당 위치에 새 객체만 생성하며 기존 객체를 덮어쓰거나 삭제하지 않습니다. 작업에 쓰기 권한이 필요하다는 메시지가 표시되면 필요한 경우 권한을 부여한 후 Settings > Integrations에서 동일한 서비스 계정을 다시 연결하세요.

GCS 버킷에서 데이터셋 만들기#

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 스토리지 할당량을 차지하지 않습니다.

가져오기 실패#

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

재시도는 이어서 진행하는 대신 폴더를 다시 나열합니다. 첫 시도 이후 추가된 객체는 가져오고, 더 이상 존재하지 않는 객체는 데이터셋에서 제거합니다.

학습#

AI 기능이 켜져 있으면 일반 학습 흐름을 통해 관리형 학습을 사용할 수 있습니다. 학습은 실행 중에 고정된 이미지의 Platform 자체 사본을 사용하며, Google Cloud 자격 증명은 학습 워크로드에 노출되지 않습니다. AI 기능이 꺼져 있으면 학습 대화상자에 클라우드 학습을 사용할 수 없는 이유가 표시되고 대신 로컬 학습이 안내됩니다.

연결 해제#

연결을 해제하면 Google Cloud의 어떤 항목도 건드리지 않고 저장된 자격 증명만 삭제됩니다. 해당 버킷으로 만든 데이터셋은 클래스, 라벨, 어노테이션과 함께 워크스페이스에 유지되지만, 동일한 서비스 계정을 다시 연결할 때까지 이미지를 불러오거나 미리 보거나 학습에 사용할 수 없습니다. 연결이 해제된 상태에서도 데이터셋 이름 변경, 라벨 편집, 삭제는 가능합니다.

연결을 해제하려면 Settings > Integrations로 이동해 Google Cloud Storage를 선택하고, 자격 증명 옆의 Disconnect를 클릭한 다음 확인하세요. 해당 데이터셋을 열면 이 설정으로 돌아가는 링크와 함께 Google Cloud Storage Disconnected가 표시되며, 다시 연결하면 데이터셋이 자동으로 복원됩니다.

REST API를 사용하여 연결을 해제할 수도 있습니다. GET /api/integrations/buckets에서 반환된 통합 ID를 사용하세요.

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 소유 사본이 필요한 기능을 사용할 수 없습니다. 여기에는 데이터셋 복제, 변경 불가 버전 스냅샷, 얼굴 흐림 처리, 다른 데이터셋의 이미지 붙여넣기가 포함됩니다. 스마트 어노테이션, 자동 어노테이션, 유사 이미지 검색, 클러스터링, 클라우드 학습 및 이미지 생성에는 AI 기능이 켜져 있어야 합니다.

GCS 기반 데이터셋이나 그 안의 개별 이미지를 삭제해도 Platform의 참조만 제거되며, 사용자의 객체에는 아무런 영향을 주지 않습니다.

Amazon S3 및 Azure Blob Storage 통합도 참조하세요.

자주 묻는 질문#