이미지 메타데이터

메타데이터를 사용하면 Roboflow workspace의 이미지에 사용자 지정 키-값 쌍을 추가할 수 있습니다. 메타데이터를 사용해 촬영 조건, 장치 식별자, 품질 점수 또는 도메인별 속성과 같은 구조화된 정보를 이미지와 함께 저장한 다음, 이러한 속성을 기준으로 데이터를 검색, 필터링, 정리할 수 있습니다.

개요

각 이미지는 원하는 수의 메타데이터 항목을 저장할 수 있습니다. 한 항목은 키 (예를 들어 camera_id)와 연결된 값 (문자열, 숫자, 또는 불리언).

값 유형	예시
문자열	location: "warehouse-3", shift: "night"
숫자	temperature: 72.5, quality_score: 95
불리언	reviewed: true, is_night: false

사용 사례

• 촬영 맥락 — 카메라 ID, GPS 좌표, 날씨, 조명 조건 기록

• 품질 추적 — 신뢰도 점수, 검토 상태, 주석 작성자 ID 추가

• 데이터 분할 — 어떤 속성으로든 데이터셋을 필터링하여 타겟 학습 세트 구성

• 외부 시스템 연결 — 이미지를 내부 도구와 연결하는 식별자 저장

메타데이터 추가

웹 UI, Python SDK, REST API를 통해 또는 다음을 통해 자동으로 이미지에 메타데이터를 추가할 수 있습니다. S3 Bucket Mirror.

이미지가 AWS S3 같은 클라우드 스토리지에 있다면 다음을 사용하세요 Datasources 및 Bucket Mirror를 사용하면 이미지 파일과 메타데이터 사이드카가 동기화 상태를 유지합니다. Signed URL이나 수동 업로드는 동일한 지속적 메타데이터 동기화 동작을 제공하지 않습니다.

웹 애플리케이션

1

이미지 열기

프로젝트의 아무 이미지나 여세요.

2

키와 값 입력

메타데이터 섹션에서 다음을 입력하세요. 키 첫 번째 입력란에 키를 값 두 번째 입력란에 값을.

3

추가

누르고 Enter 를 눌러 저장하거나 Add를 클릭하세요

값은 유형에 따라 자동으로 파싱됩니다:

입력한 값	저장 형식
front	"front" (문자열)
95	95 (숫자)
3.14	3.14 (숫자)
true / false	true / false (불리언)

Annotation Tool의 메타데이터 편집기

Python SDK

다음과 같은 metadata 딕셔너리를 이미지 업로드 시 전달하세요:

import roboflow

rf = roboflow.Roboflow(api_key="YOUR_API_KEY")
project = rf.workspace("your-workspace").project("your-project")

project.upload(
    image_path="image.jpg",
    metadata={
        "camera_id": "cam001",
        "location": "warehouse-3",
        "temperature": 72.5,
        "is_night": False
    }
)

CLI

다음을 사용하세요 roboflow image metadata 명령으로 기존 이미지의 메타데이터와 태그를 업데이트하세요:

# 단일 이미지의 메타데이터 설정
roboflow image metadata <image_id> -m '{"camera_id": "cam001", "location": "warehouse-3"}'

# 이미지에 태그 추가
roboflow image metadata <image_id> --tags "reviewed,v2"

# 메타데이터 키 제거
roboflow image metadata <image_id> --remove-metadata "old_key,deprecated_field"

# 태그 제거
roboflow image metadata <image_id> --remove-tags "draft"

# 결합: 한 번의 호출로 메타데이터 설정, 태그 추가, 태그 제거
roboflow image metadata <image_id> -m '{"quality_score": 95}' --tags "reviewed" --remove-tags "pending"

# 여러 이미지를 일괄 업데이트(비동기)
roboflow image metadata img1,img2,img3 -m '{"batch": "june-2026"}' --tags "processed" --poll

단일 이미지 ID는 동기적으로 업데이트됩니다. 쉼표로 구분된 여러 ID(최대 1,000개)는 배치 비동기 엔드포인트를 사용합니다. 다음을 추가하세요 --poll 배치가 완료될 때까지 기다리려면; 이 옵션이 없으면 명령은 다음을 반환합니다 taskId 나중에 다음 명령으로 확인할 수 있습니다 roboflow asynctasks get <task-id>.

플래그	설명
-m, --metadata	설정할 키-값 쌍의 JSON 문자열
--remove-metadata	제거할 메타데이터 키를 쉼표로 구분
--tags	추가할 태그를 쉼표로 구분
--remove-tags	제거할 태그를 쉼표로 구분
--poll / --no-poll	배치 완료를 기다립니다(배치 모드에서만)
--timeout	폴링 타임아웃(초)(기본값: 1800)

REST API

업로드 중 메타데이터 추가

다음을 포함하세요 metadata 이미지를 업로드할 때 multipart form data에 JSON 문자열화된 field를 포함하세요:

curl -X POST "https://api.roboflow.com/dataset/your-dataset/upload?api_key=YOUR_API_KEY" \\
  -F "name=image.jpg" \\
  -F "split=train" \\
  -F "file=@image.jpg" \\
  -F 'metadata={"camera_id":"cam001","temperature":72.5}'

S3 Bucket Mirror

사용할 때 Datasources S3 버킷에서 이미지를 동기화하려면, 메타데이터는 각 이미지 옆에 배치된 JSON 사이드카 파일을 통해 가져옵니다. 다음을 참조하세요 Datasources 사이드카 파일 형식, 제약 조건, 업데이트 전략에 대해.

메타데이터로 검색

메타데이터는 다음에서 인덱싱되고 검색 가능합니다: Asset Library. 검색창을 사용해 메타데이터 값으로 이미지를 필터링하세요:

metadata:camera_id="cam001"
metadata:quality_score>80
metadata:reviewed=true

메타데이터 필터를 다른 검색 필터와 함께 사용할 수 있습니다:

metadata:location="warehouse-3" AND class:forklift

Asset Library는 workspace에 있는 내용을 기반으로 메타데이터 키와 값에 대한 자동 완성도 제공합니다.

키 이름 지정 규칙

메타데이터 키는 다음 규칙을 따라야 합니다:

규칙	세부 사항
허용되는 문자	문자(a-z, A-Z), 숫자(0-9), 밑줄(_), 점(.)
첫 글자	문자, 숫자, 또는 밑줄이어야 합니다
금지된 문자	슬래시(/)는 허용되지 않습니다

유효한 키: camera_id, capture.temperature, _internal_ref, v2_score

잘못된 키: camera/id (포함 /), .starts_with_dot (다음으로 시작 .), 공백 포함 (공백 포함)

메타데이터 vs. 태그

메타데이터와 태그는 이미지를 정리하는 데 도움이 되지만, 용도는 다릅니다:

	태그	메타데이터
구조	간단한 레이블	키-값 쌍
값	값 없이 이름만	문자열, 숫자, 또는 불리언
적합한 용도	분류, 워크플로 상태	구조화된 속성, 측정값
예시	reviewed, v2, needs-annotation	temperature: 72.5, camera_id: "cam001"

둘 다 같은 이미지에 사용할 수 있습니다. 예를 들어 이미지를 다음과 같이 태그하고 reviewed 그리고 다음도 저장할 수 있습니다 reviewer: "alice" 및 confidence: 0.95 를 메타데이터로 저장할 수 있습니다.