> 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/roboflow/roboflow-ko/datasets/adding-data/image-metadata.md).

# 이미지 메타데이터

메타데이터를 사용하면 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](/roboflow/roboflow-ko/datasets/adding-data/datasources.md).

{% hint style="info" %}
이미지가 AWS S3 같은 클라우드 스토리지에 있다면 다음을 사용하세요: [Datasources](/roboflow/roboflow-ko/datasets/adding-data/datasources.md) 그리고 Bucket Mirror를 사용하면 이미지 파일과 메타데이터 사이드카가 동기화 상태로 유지됩니다. Signed URL 또는 수동 업로드는 동일한 지속적인 메타데이터 동기화 동작을 제공하지 않습니다.
{% endhint %}

### 웹 애플리케이션

{% stepper %}
{% step %}

#### 이미지를 열기

프로젝트의 아무 이미지나 엽니다.
{% endstep %}

{% step %}

#### 키와 값을 입력

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

{% step %}

#### Add

누르세요 **Enter** 저장하려면 Add를 클릭하세요
{% endstep %}
{% endstepper %}

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

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

<figure><img src="/files/869ff44bf69b5b78ddff4570c48984fb07f6df24" alt=""><figcaption><p>Annotation Tool의 메타데이터 편집기</p></figcaption></figure>

### Python SDK

다음을 전달하세요: `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
    }
)
```

이미 업로드된 이미지의 메타데이터를 업데이트하려면 다음을 사용하세요: `rfapi` 어댑터를 직접 사용합니다. 전달된 값은 `metadata` 업서트됩니다: 새 키는 추가되고 기존 키는 덮어써집니다.

```python
from roboflow.adapters import rfapi

rfapi.update_image_metadata(
    api_key="YOUR_API_KEY",
    workspace_url="your-workspace",
    image_id="IMAGE_ID",
    metadata={"quality_score": 95, "reviewed": True},
    remove_metadata=["old_key"],
    add_tags=["reviewed"],
    remove_tags=["pending"]
)
```

한 번의 호출로 최대 1,000개의 이미지를 업데이트하려면 다음을 사용하세요: `batch_update_image_metadata`. 반환값은 `taskId` 비동기 작업 엔드포인트를 통해 폴링할 수 있습니다:

```python
from roboflow.adapters import rfapi

result = rfapi.batch_update_image_metadata(
    api_key="YOUR_API_KEY",
    workspace_url="your-workspace",
    updates=[
        {"imageId": "img1", "metadata": {"batch": "june-2026"}, "addTags": ["processed"]},
        {"imageId": "img2", "metadata": {"batch": "june-2026"}, "addTags": ["processed"]}
    ]
)
print(result["taskId"])

```

### CLI

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

```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
```

단일 image 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를 포함하세요:

```bash
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}'
```

#### 기존 이미지의 메타데이터 업데이트

단일 이미지 엔드포인트를 사용해 이미 workspace에 있는 이미지의 메타데이터를 설정하거나 덮어쓰고, 메타데이터 키를 삭제하고, 태그를 추가/제거하세요. 전달된 값은 `metadata` 업서트됩니다(새 키는 추가되고 기존 키는 덮어써집니다); 다음에 나열된 키는 `removeMetadata` 삭제됩니다.

```bash
curl -X POST "https://api.roboflow.com/your-workspace/images/IMAGE_ID/metadata?api_key=YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "metadata": {"quality_score": 95, "reviewed": true},
    "removeMetadata": ["old_key"],
    "addTags": ["reviewed"],
    "removeTags": ["pending"]
  }'
```

| 필드               | 유형        | 설명                                                                    |
| ---------------- | --------- | --------------------------------------------------------------------- |
| `metadata`       | 객체        | 설정할 키-값 쌍입니다. 새 키를 추가하고 기존 키를 덮어씁니다.                                  |
| `removeMetadata` | string\[] | 삭제할 메타데이터 키입니다. 한 키는 둘 다에 포함될 수 없습니다 `metadata` 그리고 `removeMetadata`. |
| `addTags`        | string\[] | 추가할 태그입니다.                                                            |
| `removeTags`     | string\[] | 삭제할 태그입니다. 한 태그는 둘 다에 포함될 수 없습니다 `addTags` 그리고 `removeTags`.          |

모든 필드는 선택 사항이지만, 적어도 하나는 있어야 합니다. 반환: `200 { "success": true }`.

#### 메타데이터 일괄 업데이트(비동기)

한 번의 호출로 최대 1,000개의 이미지를 업데이트하려면, `POST` workspace 수준 엔드포인트에 업데이트 배열을 전달합니다:

```bash
curl -X POST "https://api.roboflow.com/your-workspace/images/metadata?api_key=YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "updates": [
      {"imageId": "img1", "metadata": {"batch": "june-2026"}, "addTags": ["processed"]},
      {"imageId": "img2", "metadata": {"batch": "june-2026"}, "addTags": ["processed"]}
    ]
  }'
```

반환값 `202 { "taskId": "...", "url": "..." }`. 반환된 URL을 동일한 `api_key` 를 사용해 상태를 확인하고 항목별 결과를 가져오세요:

```bash
curl "https://api.roboflow.com/your-workspace/asynctasks/TASK_ID?api_key=YOUR_API_KEY"
```

### S3 Bucket Mirror

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

## 메타데이터로 검색

메타데이터는 색인화되어 있으며 다음에서 검색 가능합니다: [Asset Library](/roboflow/roboflow-ko/workspaces/asset-library.md). 검색창을 사용해 메타데이터 값으로 이미지를 필터링하세요:

```
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. 태그

메타데이터와 [태그](/roboflow/roboflow-ko/datasets/manage-datasets/add-tags-to-images.md) 모두 이미지를 정리하는 데 도움이 되지만, 용도는 다릅니다:

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

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