이미지 메타데이터

이미지에 사용자 지정 키-값 메타데이터를 추가하여 데이터셋을 검색, 필터링, 정리할 수 있습니다.

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

개요

각 이미지는 원하는 수만큼 메타데이터 항목을 담을 수 있습니다. 항목은 키 (예: camera_id)와 짝을 이루는 값 (문자열, 숫자 또는 불리언).

값 유형	예시
문자열	위치: "warehouse-3", 교대: "night"
숫자	온도: 72.5, 품질 점수: 95
불리언	검토됨: true, 야간 여부: false

사용 사례

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

• 품질 추적 - 신뢰도 점수, 검토 상태, 주석자 ID 첨부

• 데이터 분할 - 타겟 학습 세트를 만들기 위해 어떤 속성이든 데이터셋을 필터링

• 외부 시스템 연결 - 이미지를 내부 도구와 다시 연결해 주는 식별자 저장

메타데이터 추가

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

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

웹 애플리케이션

1

이미지 열기

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

2

키와 값 입력

메타데이터 섹션에서 키 첫 번째 입력란에 값 두 번째 입력란에

3

추가

Enter 키를 눌러 Enter 저장하거나 Add를 클릭하세요

값은 유형별로 자동으로 파싱됩니다:

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

주석 도구의 메타데이터 편집기

Python SDK

이미지를 업로드할 때 사전(dict)을 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 이미지 메타데이터 기존 이미지의 메타데이터와 태그를 업데이트하는 명령어:

# 단일 이미지에 메타데이터 설정
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 필드(JSON 문자열화)를 multipart form data에 포함하세요:

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

S3 버킷 미러

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

메타데이터로 검색

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

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

메타데이터 필터를 다른 검색 필터와 결합할 수 있습니다:

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

자산 라이브러리는 워크스페이스에 존재하는 항목을 기반으로 메타데이터 키와 값에 대한 자동 완성도 제공합니다.

키 이름 지정 규칙

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

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

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

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

메타데이터와 태그

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

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

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