데이터 소스
외부 저장소의 이미지와 메타데이터를 Roboflow 워크스페이스에 자동으로 동기화합니다.
데이터소스를 사용하면 클라우드 스토리지의 이미지와 메타데이터를 Roboflow 자산 라이브러리로 지속적으로 미러링할 수 있습니다. 미러링되면 이미지는 의미, 사용자 지정 메타데이터, 태그 또는 이미지 유사도로 검색할 수 있으며, 라벨링과 학습을 위해 어떤 프로젝트에도 추가할 수 있습니다.
현재 AWS S3, S3 호환 스토리지, Google Cloud Storage, Azure Blob Storage 버킷 미러링이 지원됩니다.
버킷 미러 작동 방식
데이터소스를 구성하면 Roboflow가 버킷을 크롤링하여 일치하는 모든 이미지 파일을 워크스페이스의 자산 라이브러리.
지원되는 이미지 형식: JPEG, PNG, BMP, WebP, AVIF
워크스페이스에 이미 존재하는 파일(버킷 위치와 해시가 일치하는 경우)은 다시 가져오지 않아 egress 비용을 줄입니다
만약
.json사이드카 파일이 같은 기본 이름의 이미지와 함께 존재하면 해당 메타데이터가 가져와집니다. 중첩된 키는 점 표기법을 사용해 평탄화됩니다(예:capture.temperature) - 참조: 메타데이터 사이드카버킷에서 사라진 파일은 기본적으로 유지됩니다. 대신 고아 제거를 사용 설정하면 해당 파일이 삭제됩니다(참조: 고아 파일 제거)
비디오
Roboflow는 최대 3GB까지의 MP4와 QuickTime(.mov) 비디오도 미러링합니다. 비디오는 자산 라이브러리에만 저장되며, 프로젝트에 추가되지 않고 프레임도 추출되지 않습니다. 비디오는 이미지와 마찬가지로 .json 사이드카 메타데이터를 읽습니다. 비디오를 제외하려면 이미지 파일만 일치하는 glob 패턴을 사용하세요.
버킷을 Roboflow로 미러링하기
사전 요구 사항
이미지 데이터를 포함한 클라우드 스토리지 버킷(AWS S3, Google Cloud Storage 또는 Azure Blob Storage)
해당 버킷에서 읽을 수 있는 재사용 가능한 Roboflow 자격 증명. 참조: 데이터소스 자격 증명, 그런 다음 다음을 따르세요: AWS S3 자격 증명, Google Cloud Storage 자격 증명, 또는 Azure Blob Storage 자격 증명.
Roboflow에 자격 증명 추가
Roboflow는 버킷 액세스 정보를 재사용 가능한 자격 증명으로 안전하게 암호화하여 저장합니다. 공급자별 설정 단계와 최소 권한 지침은 AWS S3 자격 증명, Google Cloud Storage 자격 증명, 또는 Azure Blob Storage 자격 증명.
로 이동하세요 자격 증명 워크스페이스 설정에서 자격 증명 추가.
버킷 미러링용 데이터소스 구성
새 데이터소스 생성 을 워크스페이스 설정에서 생성하세요. 양식에는 두 개의 탭이 있습니다:
"Connection"에는 버킷 세부 정보와 액세스 정보가 들어 있습니다: 이름, 공급자, 버킷, 리전, 자격 증명. "Credential" 드롭다운에서 저장해 둔 자격 증명을 선택하거나, 양식을 벗어나지 않고 새로 추가하려면 옆의 "+"를 사용하세요.
"Mirror Configuration"에는 가져오기 대상, 파일 필터, 미러링 동작이 들어 있습니다.
"Bucket" 필드에는 버킷 이름만 입력합니다(예: my-bucket, s3://my-bucket). 이름 뒤에 경로가 포함된 버킷 값은 거부됩니다. 버킷의 일부만 미러링하려면 "Mirror Configuration" 탭의 "File Filters" 아래에 images/**/* 와 같은 glob 패턴을 추가하세요. Azure Blob Storage의 경우에도 컨테이너 이름에 동일한 규칙이 적용됩니다.
가져오기 대상 선택
"Mirror Configuration" 아래의 "Import Destination" 섹션에서 미러링된 파일이 어디에 저장될지 제어합니다. 각 데이터소스는 하나의 대상에만 가져옵니다. 다른 곳으로 가져오려면 데이터소스를 하나 더 추가하세요.
"Workspace"는 다음 위치로 미러링됩니다 자산 라이브러리. 파일을 워크스페이스 루트에 유지하려면 "Import into" 드롭다운을 사용하거나, 프로젝트를 선택하여 해당 프로젝트에도 추가하세요.
"Folder"는 미러링된 이미지를 프로젝트 폴더로 범위를 지정하므로 그 폴더의 팀만 볼 수 있습니다. 이 옵션은 다음이 포함된 요금제에서 사용할 수 있습니다: 프로젝트 폴더 권한.
Glob 패턴으로 필터링
기본적으로 버킷의 모든 지원되는 이미지 파일이 가져와집니다. glob 패턴을 사용하여 가져올 파일을 제한할 수 있으며, 직접 지정하거나 버킷에 저장된 .txt 파일을 통해 지정할 수 있습니다.
또한 glob 패턴 대신 파일 경로의 명시적 허용 목록을 제공할 수도 있습니다.
패턴 의미
*는 다음을 제외한 모든 문자와 일치합니다/(단일 디렉터리 수준)**를 포함한 모든 문자와 일치합니다/(여러 디렉터리 수준)
예시
접두사로 일치:
일치: harvest, harvest2024, harvest/sun/file.jpg, harvest-data.png
일치하지 않음: Harvest, my-harvest
폴더 내의 모든 항목과 일치:
일치: /harvest/sun/file.txt, /harvest/sun/subfolder/image.jpg, /harvest/sun/deep/nested/path/data.png
일치하지 않음: /harvest/moon/file.txt, /other/sun/file.txt
하위 트리 내에서 접미사로 일치:
일치: /planting/wheat-crops.png, /planting/subfolder/rice-crops.png
일치하지 않음: /planting/wheat.png, /other/wheat-crops.png
특정 디렉터리 수준에서 이름 패턴으로 일치:
일치: /farm/a/field/weed-2025-10-27.png, /garden/a/plot/seaweed-data-2025-10-27.png
일치하지 않음: /farm/b/field/weed-2025-10-27.png
정확한 경로:
해당 특정 파일과만 일치합니다.
파일 이름의 리터럴 와일드카드:
패턴을 따옴표로 감싸 * 를 리터럴 문자로 처리하세요:
고아 파일 제거
고아 제거는 기본적으로 꺼져 있으므로 버킷에서 사라진 파일은 유지됩니다. removeOrphanedSourcesWhenDisappeared 가 사용 설정되면, 버킷에 더 이상 존재하지 않는 파일(또는 glob 패턴과 더 이상 일치하지 않는 파일)은 어떤 프로젝트나 다른 데이터소스 구성에서도 참조되지 않는 경우 Roboflow 워크스페이스에서 제거됩니다.
이것은 데이터소스를 삭제할 때도 적용됩니다. 고아 제거가 사용 설정되어 있고 버킷이 적어도 한 번 미러링된 경우, 다른 어떤 프로젝트에서도 사용되지 않는 해당 버킷의 이미지는 정리 작업자에 의해 제거될 수 있습니다. 삭제 확인 대화상자에서 이에 대해 경고하고, 계속하기 전에 명시적 확인을 요구합니다. 이를 방지하려면 데이터소스를 삭제하기 전에 미러 구성에서 고아 제거를 비활성화하세요.
파일 이름 지정
해당 namingStrategy 설정은 가져온 파일의 이름과 표시 방식을 Roboflow에서 제어합니다:
fullPath
전체 S3 키 경로를 파일 이름으로 사용합니다(기본값)
fileName
S3 키의 파일 이름 부분만 사용합니다
eTag
S3 객체 ETag를 사용합니다
metadata
에서 지정한 이미지 메타데이터의 값을 사용합니다 namingStrategyMetadataKey (필수)
이미지 업데이트
S3의 이미지가 수정되면 Roboflow가 워크스페이스의 복사본을 업데이트할 수 있습니다:
updateImageWhenNewer(기본값:true) - 저장된 버전보다 S3 객체가 더 최신이면 이미지를 다시 가져옵니다updateImageStrategy- 업데이트가 어떻게 적용될지 제어합니다. 현재overwrite(기존 이미지를 대체함)만 지원됩니다
메타데이터 사이드카
이미지와 같은 기본 이름을 가진 .json 사이드카 파일을 버킷에 이미지와 함께 배치하여 메타데이터를 첨부하세요:
사이드카 파일에는 key-value 쌍이 들어 있습니다:
중첩된 객체는 점 표기법으로 평탄화됩니다. 위 예시의 결과는 다음과 같습니다:
camera_id
"cam001"
location
"warehouse-3"
capture.temperature
72.5
capture.humidity
45
사이드카 파일 제약 조건:
최대 파일 크기: 256 KB
유효한 JSON이어야 합니다
null및정의되지 않음값은 필터링됩니다
메타데이터 동기화 전략
이미지의 메타데이터 사이드카 .json 파일이 S3에서 업데이트되면, 업데이트 적용 방식을 제어하는 두 가지 설정이 있습니다:
updateMetadataWhenNewer(기본값:true) - 사이드카 파일이 저장된 버전보다 더 최신이면 메타데이터를 다시 동기화합니다updateMetadataStrategy- 동기화된 메타데이터가 UI 또는 API를 통해 수동으로 설정한 메타데이터와 어떻게 상호작용할지 제어합니다:
mergeBucketWins (기본값)
두 소스를 병합합니다. 키 충돌 시 버킷 값이 우선합니다
mergeUserWins
두 소스를 병합합니다. 키 충돌 시 사용자 설정 값이 우선합니다
overwrite
버킷 메타데이터가 기존 메타데이터를 모두 완전히 대체합니다
untilFirstChange
사용자가 메타데이터 필드를 수동으로 편집할 때까지 버킷에서 동기화한 뒤, 그 후에는 중지합니다
append
버킷에서 새 키만 추가하며, 기존 키를 절대 덮어쓰지 않습니다
미러링 트리거하기
언제든지 데이터소스 목록 에서 데이터소스 옆의 재생 버튼을 클릭하여 수동으로 미러를 트리거할 수 있습니다.
수동 트리거에는 다음 보호 조건이 적용됩니다:
진행 중: 동기화가 이미 실행 중이면, 완료될 때까지 다른 동기화를 시작할 수 없습니다.
쿨다운: 동기화가 완료된 후에는 15분 동안 수동 재트리거가 차단됩니다. 버튼 툴팁에는 남은 시간이 표시됩니다. 다음 경우에는 쿨다운이 건너뛰어집니다:
이전 동기화에서 가져올 새로운 항목이 없었습니다(대기열에 들어간 파일이 0개이거나, 모든 파일이 실패함).
마지막 실행 이후 데이터소스 구성을 편집했습니다.
마지막 실행이 오류와 함께 완료되었습니다.
시간당 상한: 데이터소스는 롤링 1시간당 최대 10회까지 동기화할 수 있습니다. 이 상한은 쿨다운을 건너뛸 수 있는 경우에도 즉시 재트리거를 허용하지 않습니다.
예약된(cron) 동기화는 쿨다운과 시간당 상한을 모두 우회합니다.
일일 일정으로 실행하기
자동으로 미러링하려면 "Mirror Configuration" 탭의 "Scheduling" 섹션을 열고 "Run automatically on a daily schedule"를 선택하세요. 그러면 데이터소스가 24시간마다 동기화됩니다. 예약은 기본적으로 꺼져 있습니다.
동기화된 자산 보기
각 데이터소스 항목 에는 눈 아이콘이 있으며, 이를 통해 자산 라이브러리 해당 특정 데이터소스의 이미지와 비디오로 필터링된
모든 데이터소스에서 동기화된 모든 이미지를 보려면 데이터소스 목록 하단에서 "View Datasource Assets"를 클릭하세요. 이 링크는 최소 한 개의 데이터소스가 실행된 후에 나타납니다.
두 링크 모두 사전 입력된 태그 필터가 적용된 자산 라이브러리로 이동하므로, 워크스페이스 이미지 중 버킷 미러링된 하위 집합만 찾아보고, 검색하고, 관리할 수 있습니다.
S3 호환 스토리지
Datasources는 필요한 S3 API 작업을 구현하는 S3 호환 스토리지 공급자와 함께 작동합니다.
이러한 공급자 중 하나를 구성하려면:
데이터소스 "Connection" 탭에서
S3를 공급자로 선택하세요.평소와 같이 버킷 이름과 자격 증명을 입력하세요.
공급자의 사용자 지정
엔드포인트URL.리전은
auto또는 공급자별 리전 값으로 설정하세요.
공급자의 S3 API 엔드포인트를 엔드포인트에 사용하세요. CDN URL, 공개 버킷 URL 또는 브라우저 다운로드 URL은 사용하지 마세요.
엔드포인트는 공개 인터넷에서 접근 가능해야 합니다. Roboflow는 다음을 가리키는 엔드포인트를 거부합니다: localhost, 사설 네트워크 주소 또는 링크 로컬 주소이며, 이에 해석되는 호스트 이름도 거부합니다.
동일한 glob 패턴 필터링, 메타데이터 사이드카 동작 및 미러 설정은 이들 공급자와도 작동합니다.
경로 스타일 주소 지정
일부 공급자는 URL 경로(endpoint/bucket/key)에 버킷 이름이 들어가고, 호스트 이름(bucket.endpoint/key)에는 들어가지 않는 방식을 기대합니다. 엔드포인트를 입력하면 "Connection" 탭에 "Use path-style addressing" 체크박스가 나타납니다. Roboflow는 엔드포인트에 맞는 설정을 미리 선택하고, 변경해도 선택을 유지합니다.
MinIO 및 기타 자체 호스팅 또는 NAS 게이트웨이, Oracle Cloud 호환 엔드포인트, IP 주소나 포트로 접근하는 모든 엔드포인트, 이름에 점이 있는 버킷에는 이 옵션을 켜세요. 가상 호스팅 URL을 제공하는 공급자(예: Cloudflare R2, Backblaze B2, Wasabi, DigitalOcean Spaces, Alibaba Cloud OSS)에는 끄세요. 잘못된 설정을 사용하면 파일을 나열할 때 연결 테스트가 실패하고, 오류에 전환하라는 안내가 표시됩니다.
지원되는 S3 호환 스토리지 공급자는 다음과 같습니다:
Cloudflare R2
<account-id>.r2.cloudflarestorage.com
Backblaze B2
s3.<region>.backblazeb2.com
DigitalOcean Spaces
<region>.digitaloceanspaces.com
Akamai Linode Object Storage
<region>.linodeobjects.com
Wasabi
s3.<region>.wasabisys.com
Vultr Object Storage
<region>.vultrobjects.com
OVHcloud Object Storage
s3.<region>.io.cloud.ovh.net
Scaleway Object Storage
s3.<region>.scw.cloud
Open Telekom Cloud
obs.<region>.otc.t-systems.com
Exoscale SOS
sos-<region>.exo.io
IONOS Cloud Object Storage
s3-<region>.ionoscloud.com
IBM Cloud Object Storage
s3.<region>.cloud-object-storage.appdomain.cloud
Oracle Cloud Infrastructure Object Storage S3 호환
compat.objectstorage.<region>.oraclecloud.com
Seagate Lyve Cloud
s3.<region>.lyvecloud.seagate.com
Huawei Cloud OBS
obs.<region>.myhuaweicloud.com
Alibaba Cloud OSS
oss-<region>.aliyuncs.com
Tencent Cloud COS
cos.<region>.myqcloud.com
Yandex Object Storage
storage.yandexcloud.net
Storj Hosted S3 Gateway
gateway.storjshare.io
MCP 서버
AI 에이전트를 다음에 연결하면 MCP 서버 그리고 다음 도구를 사용해 버킷을 프로젝트에 미러링할 수 있습니다:
connect_cloud_storage
자격 증명부터 첫 실행까지, 버킷 미러를 처음부터 끝까지 설정합니다.
credentials_create
클라우드 스토리지 자격 증명을 생성합니다.
credentials_list
워크스페이스의 클라우드 스토리지 자격 증명 목록을 표시합니다.
datasource_create
버킷 경로를 프로젝트에 미러링하는 데이터소스를 생성합니다.
datasource_validate
Roboflow가 버킷에 접근할 수 있는지 확인합니다.
datasource_trigger
미러 실행을 시작합니다.
datasource_job_get
하나의 미러 실행에 대한 상태와 통계를 가져옵니다.
마지막 업데이트
도움이 되었나요?