For the complete documentation index, see llms.txt. This page is also available as Markdown.

데이터 소스

외부 저장소의 이미지와 메타데이터를 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로 미러링하기

사전 요구 사항

  1. 이미지 데이터를 포함한 클라우드 스토리지 버킷(AWS S3, Google Cloud Storage 또는 Azure Blob Storage)

  2. 해당 버킷에서 읽을 수 있는 재사용 가능한 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 호환 스토리지 공급자와 함께 작동합니다.

이러한 공급자 중 하나를 구성하려면:

  1. 데이터소스 "Connection" 탭에서 S3 를 공급자로 선택하세요.

  2. 평소와 같이 버킷 이름과 자격 증명을 입력하세요.

  3. 공급자의 사용자 지정 엔드포인트 URL.

  4. 리전은 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

하나의 미러 실행에 대한 상태와 통계를 가져옵니다.

마지막 업데이트

도움이 되었나요?