> 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).

# 이미지 메타데이터

Metadata를 사용하면 Roboflow workspace의 이미지에 사용자 정의 key-value 쌍을 첨부할 수 있습니다. metadata를 사용해 캡처 조건, 디바이스 식별자, 품질 점수 또는 도메인별 속성과 같은 구조화된 정보를 이미지와 함께 저장한 다음, 해당 속성을 기준으로 데이터를 검색, 필터링, 정리할 수 있습니다.

## 개요

각 이미지는 원하는 만큼의 metadata 항목을 포함할 수 있습니다. 각 항목은 **키** (예: 다음과 같은 이름 `camera_id`)과 함께 짝을 이루는 **값** (문자열, 숫자 또는 불리언).

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

### 사용 사례

* **캡처 컨텍스트** — camera ID, GPS 좌표, 날씨, 조명 조건을 기록
* **품질 추적** — 신뢰도 점수, 검토 상태, 주석자 ID를 추가
* **데이터 분할** — 어떤 속성으로든 데이터셋을 필터링해 타깃 학습 세트를 구성
* **외부 시스템 연결** — 이미지를 내부 도구와 연결하는 식별자를 저장

## Metadata 추가

웹 UI, Python SDK, REST API를 통해 또는 다음을 통해 자동으로 이미지에 metadata를 추가할 수 있습니다: [S3 Bucket Mirror](broken://pages/9b39be0f1f38c481a6fbce2748e49f77d55fc690).

### 웹 애플리케이션

{% stepper %}
{% step %}

#### 이미지를 엽니다

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

{% step %}

#### 키와 값을 입력

metadata 섹션에서 다음을 입력하세요: **키** 첫 번째 입력란에 a **값** 두 번째 입력란에.
{% endstep %}

{% step %}

#### 추가

누르세요 **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의 metadata 편집기</p></figcaption></figure>

### Python SDK

다음을 전달하세요: `metadata` 이미지를 업로드할 때 dictionary를:

```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 image metadata` 기존 이미지의 metadata와 tags를 업데이트하는 명령:

```bash
# 단일 이미지에 metadata 설정
roboflow image metadata <image_id> -m '{"camera_id": "cam001", "location": "warehouse-3"}'

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

# metadata 키 제거
roboflow image metadata <image_id> --remove-metadata "old_key,deprecated_field"

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

# 결합: 한 번의 호출로 metadata 설정, tags 추가, tags 제거
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개)는 batch 비동기 endpoint를 사용합니다. 다음을 추가하세요: `--poll` batch가 완료될 때까지 기다리기 위해; 이를 지정하지 않으면 명령은 다음을 반환합니다: `taskId` 나중에 다음으로 확인할 수 있습니다: `roboflow asynctasks get <task-id>`.

| 플래그                    | 설명                          |
| ---------------------- | --------------------------- |
| `-m`, `--metadata`     | 설정할 key-value 쌍의 JSON 문자열   |
| `--remove-metadata`    | 제거할 metadata 키를 쉼표로 구분한 목록  |
| `--tags`               | 추가할 tags를 쉼표로 구분한 목록        |
| `--remove-tags`        | 제거할 tags를 쉼표로 구분한 목록        |
| `--poll` / `--no-poll` | batch 완료를 기다림 (batch 모드에서만) |
| `--timeout`            | 폴링 타임아웃(초 단위) (기본값: 1800)   |

### REST API

#### 업로드 중 metadata 추가

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

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

### S3 Bucket Mirror

사용할 때 [Datasources](broken://pages/9b39be0f1f38c481a6fbce2748e49f77d55fc690) S3 bucket에서 이미지를 동기화할 때 metadata는 각 이미지 옆에 배치된 JSON sidecar 파일을 통해 가져옵니다. 다음을 참조하세요: [Datasources](broken://pages/9b39be0f1f38c481a6fbce2748e49f77d55fc690) sidecar 파일 형식, 제약, 업데이트 전략은 다음을 참조하세요.

## Metadata로 검색

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

```
metadata.camera_id:"cam001"
metadata.quality_score>80
metadata.reviewed:true
```

metadata 필터를 다른 검색 필터와 결합할 수 있습니다:

```
metadata.location:"warehouse-3" AND class:forklift
```

Asset Library는 workspace에 موجود한 내용을 기반으로 metadata 키와 값에 대한 자동완성도 제공합니다.

## 키 명명 규칙

metadata 키는 다음 규칙을 따라야 합니다:

| 규칙      | 세부 정보                                        |
| ------- | -------------------------------------------- |
| 허용되는 문자 | 문자(`a-z`, `A-Z`), 숫자(`0-9`언더스코어(`_`), 점(`.`) |
| 첫 번째 문자 | 문자, 숫자 또는 언더스코어여야 합니다                        |
| 금지된 문자  | 슬래시(`/`)는 허용되지 않습니다                          |

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

유효하지 않은 키: `camera/id` (포함 `/`), `.starts_with_dot` (로 시작함 `.`), `공백 포함` (공백 포함)

## Metadata vs. Tags

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

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

동일한 이미지에 둘 다 사용할 수 있습니다. 예를 들어, 이미지를 다음과 같은 tag로 지정하고 `reviewed` 또한 다음을 저장할 수 있습니다: `reviewer: "alice"` 및 `confidence: 0.95` metadata로 저장합니다.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.roboflow.com/roboflow/roboflow-ko/datasets/adding-data/image-metadata.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.