> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data/image-metadata.md).

# 이미지 메타데이터

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

## 개요

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

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

### 사용 사례

* **맥락 기록** - 카메라 ID, GPS 좌표, 날씨, 조명 조건 기록
* **품질 추적** - 신뢰도 점수, 검토 상태, 주석자 ID 첨부
* **데이터 분할** - 타겟 학습 세트를 만들기 위해 어떤 속성이든 데이터셋을 필터링
* **외부 시스템 연결** - 이미지를 내부 도구와 다시 연결해 주는 식별자 저장

## 메타데이터 추가

웹 UI, Python SDK, REST API를 통해, 또는 다음을 통해 자동으로 이미지에 메타데이터를 추가할 수 있습니다: [S3 버킷 미러](/datasets/ko/create-and-upload/adding-data/datasources.md).

{% hint style="info" %}
이미지가 AWS S3 같은 클라우드 스토리지에 있다면 [데이터 소스](/datasets/ko/create-and-upload/adding-data/datasources.md) S3 버킷 미러를 사용해 이미지 파일과 메타데이터 사이드카가 동기화 상태를 유지하도록 하세요. Signed URL이나 수동 업로드는 동일한 지속적 메타데이터 동기화 동작을 제공하지 않습니다.
{% endhint %}

### 웹 애플리케이션

{% stepper %}
{% step %}

#### 이미지 열기

프로젝트의 아무 이미지나 여세요.
{% endstep %}

{% step %}

#### 키와 값 입력

메타데이터 섹션에서 **키** 첫 번째 입력란에 **값** 두 번째 입력란에
{% endstep %}

{% step %}

#### 추가

Enter 키를 눌러 **Enter** 저장하거나 Add를 클릭하세요
{% endstep %}
{% endstepper %}

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

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

<figure><img src="/files/6fb79eee7a732f61ca1832a89bd46fbdc2995de7" alt=""><figcaption><p>주석 도구의 메타데이터 편집기</p></figcaption></figure>

### Python SDK

이미지를 업로드할 때 사전(dict)을 `metadata` 전달하세요:

```python
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 이미지 메타데이터` 기존 이미지의 메타데이터와 태그를 업데이트하는 명령어:

```bash
# 단일 이미지에 메타데이터 설정
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에 포함하세요:

```bash
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 버킷 미러

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

## 메타데이터로 검색

메타데이터는 [자산 라이브러리](https://docs.roboflow.com/platform/workspaces/asset-library)자산 라이브러리에서 인덱싱되고 검색 가능합니다. 검색창을 사용해 메타데이터 값으로 이미지를 필터링하세요:

```
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](/datasets/ko/manage/manage-datasets/add-tags-to-images.md) 이미지를 정리하는 데 도움이 되지만, 용도는 다릅니다:

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

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