> 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/manage/manage-datasets/dataset-search.md). # 데이터셋 검색 ## 정보 데이터셋 검색을 사용하면 파일 이름 조회, 구조화된 필터(태그, 분할, 클래스, 크기, 주석 수), 불리언 논리, 자연어 의미 검색을 통해 프로젝트 전반에서 특정 이미지를 찾을 수 있습니다. 이를 사용해 데이터를 감사하고, 잘못 레이블링되었거나 누락된 주석을 찾아내며, 검토 또는 내보내기를 위한 대상 하위 집합을 만들 수 있습니다. 동일한 쿼리를 웹 앱과 검색 REST API에서 모두 사용할 수 있습니다. ## 웹 앱 Roboflow에서 파일 이름, 검색 쿼리로 이미지 파일을 검색하고, 쿼리와 필터를 조합하여 특정 이미지를 찾고 데이터를 더 잘 이해할 수 있습니다. * **특정 태그가 있는 분할의 이미지:**\ `tag:factory split:train`\ 이것은 태그 필터와 분할 필터를 사용합니다 * **의미 검색과 클래스 필터를 사용하여 누락된 레이블 찾기**:\ `person -class:helmet`\ 이것은 의미 검색과 클래스 필터에 대한 반전 필터를 사용합니다 * **모든 이미지에 특정 클래스가 있으면 특정 필터가 필요한 경우:**\ `class:helmet AND NOT (tag:v1 OR tag:v2)`\ 이것은 클래스 필터, 불리언 논리, 태그 필터를 사용합니다 * **주석 수가 적은 넓은 이미지 찾기:**\ `min-width:1000 max-annotations:1`\ 이것은 최소 너비 필터와 최대 주석 수 필터를 사용합니다 전체 목록은 다음을 참조하세요. [검색 필터](#search-filters)와 아래 예시 {% hint style="info" %} 이 모든 검색 필터와 쿼리를 함께 조합할 수 있습니다 {% endhint %} ### 의미 검색 이미지를 설명해서 검색할 수 있습니다. 이러한 쿼리는 검색어와 가장 밀접하게 관련된 이미지를 찾고, 객체가 아직 레이블링되지 않았더라도 이미지를 찾는 데 도움이 됩니다. 의미 검색은 어떤 필터 선택자도 없이 텍스트 쿼리를 입력할 때 발생합니다(예: `filename:`)
### 파일 이름으로 검색 다음을 사용하여 파일 이름을 검색할 수 있습니다. `filename:` 필터 또는 파일 이름 텍스트 상자를 사용하면 쿼리가 자동으로 생성됩니다.
### 데이터셋 분할로 검색 데이터셋 분할(train, valid, test)별로 이미지를 검색합니다
이미지를 다른 분할로 다시 할당하려면 이미지를 선택한 뒤(또는 검색에서 "모두 일치하는 항목 선택"을 선택한 뒤) 대량 작업 메뉴에서 "데이터셋 분할 변경"을 클릭하세요. 큰 선택 항목은 백그라운드에서 처리됩니다. ### 업로드 날짜로 검색 다음을 사용하여 Roboflow에 처음 업로드된 날짜별로 이미지를 필터링합니다. `date:` 필터. 업로드 날짜는 변경할 수 없으며, 이미지가 편집되거나 다시 주석 처리되거나 분할 간에 이동해도 변경되지 않습니다. 사용 `date:YYYY-MM-DD` 는 특정 날짜에 사용하고, 비교 연산자를 조합하여 범위를 검색할 수 있습니다: `date>=2026-01-01 date<2026-02-01` ### 검색 필터 사용 가능한 필터는 다음과 같습니다: * `like-image:`: 이미지 콘텐츠를 기반으로 한 의미 검색 * `태그` : 사용자가 제공한 태그로 필터링합니다. * `파일 이름` : 제공된 파일 이름과 일치하는 파일 이름을 검색합니다. 부분 일치를 실행하려면 쿼리의 시작과 끝에 \*를 사용하세요. * `분할` : 분할(train, test, valid)별로 필터링합니다. * `job:` : 제공된 작업 ID가 있는 이미지를 표시합니다. * `min-width:X` : 너비가 X보다 큰 이미지를 표시합니다. * `max-width:X` : 너비가 X보다 작은 이미지를 표시합니다. * `min-height:X` : 높이가 X보다 큰 이미지를 표시합니다. * `max-height:X` : 높이가 X보다 작은 이미지를 표시합니다. * `min-annotations:X` : 지정된 주석 수보다 많은 이미지를 필터링합니다. * `max-annotations:X` : 지정된 주석 수보다 적은 이미지를 표시합니다. * `class:CLASS`: 제공된 레이블로 최소 1개의 주석이 있는 이미지를 표시합니다. * `date:YYYY-MM-DD` : 이미지가 업로드된 변경 불가능한 날짜로 필터링합니다. 비교 연산자를 지원합니다(예: `date>=2026-01-01 date<2026-02-01`). #### 불리언 논리 AND, OR, NOT 및 괄호를 사용하여 여러 필터를 결합해 복잡한 쿼리를 만드세요. `class:helmet AND NOT (tag:v1 OR tag:v2)` #### 반전 필터 필터와 일치하는 이미지를 제외하려면 필터 앞에 빼기 기호를 추가하세요. `class:helmet -class:vest` #### 숫자 클래스 필터 이미지에 레이블이 지정된 항목 수로 필터링합니다. `class:helmet=3 class:vest>=4` ### API 다음을 통해 Roboflow에서 데이터셋과 이미지를 검색할 수도 있습니다. [검색 API](#http-api). ## HTTP API REST API를 사용하여 Roboflow에 호스팅된 이미지를 검색할 수 있습니다. 두 개의 엔드포인트가 있습니다. 프로젝트 범위의 `/:workspace/:project/search` 엔드포인트와 워크스페이스 전체 `/:workspace/search/v1` 엔드포인트가 있으며, 이는 다음과 동일합니다. [웹 앱 데이터셋 검색](#web-app). ### 프로젝트에서 이미지 검색 Roboflow에 호스팅된 이미지를 검색하려면 다음 API 엔드포인트로 POST 요청을 보내세요: ```url https://api.roboflow.com/:workspace/:project/search ``` 다음은 API 요청 예시입니다: ```bash curl -X POST "https://api.roboflow.com/my-workspace/my-project-name/search?api_key=$ROBOFLOW_API_KEY" \ -H 'Content-Type: application/json' \ --data \ '{ "like_image": "image_id", "in_dataset": true, "limit": 125 }' ``` 이 엔드포인트는 POST 본문에서 다음 값을 허용합니다: ```json { // 제공되면, 의미 유사도 기준으로 정렬된 결과를 제공합니다 "like_image": string, // 제공되면, 의미 유사도 기준으로 정렬된 결과를 제공합니다 "prompt": string, // 기본값은 0 "offset": int, // 기본값은 50(최대: 250) "limit": int, // 제공되면, 지정된 태그가 있는 이미지를 필터링합니다 "tag": string, // 제공되면, 지정된 클래스 이름이 있는 이미지를 필터링합니다 "class_name": string, // 제공되면, 지정된 프로젝트에 있는 이미지를 필터링합니다 "in_dataset": string, // 제공되면, 어떤 배치에든 있는 이미지만 반환합니다 "batch": boolean, // 제공되면, 지정된 배치에 있는 이미지만 반환합니다 "batch_id": string, // 제공되면, 어떤 주석 작업에든 있는 이미지만 반환합니다 "annotation_job": boolean, // 제공되면, 지정된 주석 작업에 있는 이미지만 반환합니다 "annotation_job_id": string, // 반환할 필드를 지정합니다. 기본값은 ["id", "created"]입니다 // 옵션은 ["id", "name", "annotations", "labels", "split", "tags", "owner", "url", "embedding", "created"]입니다 "fields": string[] } ``` 검색 API는 다음 구조의 응답을 반환합니다. 사용할 수 있는 값은 추가로 지정한 `fields` 에 따라 달라집니다: ```json { "offset": 0, "total": 292, "results": [ { "id": "image123", "name": "humpbackwhale.jpg", "owner": "owner123", "url": "https://source.roboflow.com/owner123/image123/original.jpg", "annotations": { "count": 5, "classes": { "whale": 1, "fish": 4 } }, "labels": [], "tags": [ "cam_x13" ] } // ... 등 ] } ``` ### 워크스페이스 전체에서 이미지 검색 워크스페이스 이미지 검색 API를 사용하면 워크스페이스 내에서 이미지를 나열하고 검색할 수 있습니다. 이 API를 사용하면, 다음과 유사한 쿼리 문자열을 사용하여 필터링, 정렬, 의미 검색을 수행할 수 있습니다. [Roboflow 웹 애플리케이션의 이미지 검색 기능](#web-app). #### 엔드포인트 API에 요청하려면 `POST` 요청을 다음 엔드포인트로 보내세요: ``` https://api.roboflow.com/{WORKSPACE}/search/v1?api_key=API_KEY ``` 여기서 `WORKSPACE` 는 워크스페이스 ID이고, `API_KEY` 는 API 키입니다. [워크스페이스 ID를 찾는 방법 알아보기](https://docs.roboflow.com/reference/authentication/authentication/workspace-and-project-ids). [API 키를 찾는 방법 알아보기.](https://docs.roboflow.com/reference/platform/rest-api/authenticate-with-the-rest-api) #### 인증 API에 접근하려면 요청에 API 키를 포함해야 합니다. API 키는 쿼리 매개변수로 전달해야 합니다. 예시: `?api_key={YOUR_API_KEY}` #### 요청 형식 **헤더** * `Content-Type: application/json` **본문 매개변수** * `query` **(필수)**: 필터링, 정렬 또는 의미 검색을 수행하기 위한 비어 있지 않은 문자열입니다. 예를 들면: `"nighttime project:{my-project-url}"` 는 다음의 이미지에 대해 필터링합니다. `my-project-url` 프로젝트와 일치하는 이미지에 대해 의미 정렬을 적용합니다. `nighttime`가 없거나 비어 있으면 400 오류를 반환합니다. * `pageSize`: 페이지당 반환할 결과 수(기본값: 50). * `fields`: 응답에 포함할 필드 목록입니다. 가능한 값은 `"tags"`, `"width"`, `"height"`, `"filename"`, `"aspectRatio"`, `"split"`, `"projects"`, `"annotations"`, `"labels"`, `"owner"`, `"url"`. **요청 예시** ```bash curl --location 'https://api.roboflow.com/{WORKSPACE}/search/v1?api_key={API_KEY}' \ --header 'Content-Type: application/json' \ --data '{ "query": "project:foo nightime", "pageSize": 10, "fields": ["tags", "width", "height", "filename", "aspectRatio", "split"] }' ``` #### 응답 형식 응답은 다음 필드를 포함하는 JSON 객체입니다: * `results`: 이미지 객체 배열입니다. * `total`: 찾은 총 이미지 수입니다. * `continuationToken`: 페이지 매김용 토큰입니다. **이미지 객체 필드** 요청한 필드에 따라 `fields` 매개변수: * `id`: 이미지의 고유 식별자입니다. * `projectData`: 프로젝트 URL을 키로 하는 객체이며, 프로젝트별 데이터를 포함합니다: * `분할`: 이미지의 데이터셋 분할을 나타냅니다(예: "test"). 다음일 때 반환됩니다. `"split"` 가 `fields`. * `inDataset`: 이미지가 데이터셋에 있는지 나타내는 불리언입니다. 다음일 때 반환됩니다. `"projects"` 가 `fields`. * `annotations`: 이 프로젝트의 이미지에 대한 주석 데이터로, 다음을 포함합니다. `annotationGroup`, `classes` 및 `classCounts`. 다음일 때 반환됩니다. `"annotations"` 가 `fields`. * `labels`: 이 프로젝트의 이미지에 대한 레이블 데이터입니다. 다음일 때 반환됩니다. `"labels"` 가 `fields`. * `tags`: 이미지와 연결된 태그 배열입니다. * `width`: 이미지의 픽셀 단위 너비입니다. * `height`: 이미지의 픽셀 단위 높이입니다. * `파일 이름`: 이미지 파일의 이름입니다. * `aspectRatio`: 이미지의 종횡비입니다. * `owner`: 이미지의 소유자 식별자입니다. * `url`: 원본 이미지 파일의 직접 URL입니다. **페이지 매김 및 `continuationToken`** 다음 `continuationToken` 는 검색 결과와 일치하는 페이지 사이를 이동할 수 있게 해줍니다. 다음 `continuationToken` 이 후속 요청에 포함되면 다음 결과 집합을 가져옵니다. 다음을 사용하려면 `continuationToken`, 다음 API 호출의 요청 본문에 포함하세요. 그러면 원래 쿼리를 기반으로 결과의 다음 페이지를 가져옵니다. **오류 응답** * `400` - 다음일 때 반환됩니다. `query` 가 없거나 비어 있거나, `project:` 필터가 워크스페이스에 속하지 않는 프로젝트를 참조하는 경우. * `500` - 내부 서버 오류. **프로젝트 및 데이터셋 필터** 에서 사용할 수 있는 모든 필터 외에도 [앱 내 데이터셋 검색](#web-app), 워크스페이스 전체 검색은 다음에 대한 필터도 지원합니다. `프로젝트` 와 `데이터셋` . 예를 들어 다음과 같은 쿼리를 사용할 수 있습니다. `project:foo project:bar` 를 사용하면 두 프로젝트 모두에 있는 모든 이미지를 찾을 수 있습니다 `foo` 와 `bar`.\ \ 다음과 같은 쿼리는 `dataset:foo`는 프로젝트 내의 이미지를 반환합니다 `foo` 에서 레이블링되었고 프로젝트의 데이터셋에 추가된 이미지입니다. ## Python SDK `Project.search_all()` 는 프로젝트의 이미지 전반에 걸친 검색 결과의 페이지 매김 이터레이터를 반환합니다. 검색 모드는 조합할 수 있습니다. 예를 들어 클래스에 의해 좁혀진 텍스트 프롬프트, 단일 배치로 필터링된 기존 이미지 유사도 검색 등이 가능합니다. ```python import roboflow rf = roboflow.Roboflow(api_key="YOUR_API_KEY") project = rf.workspace().project("my-detector") records = [] for page in project.search_all( prompt="mug on a desk", class_name="mug", in_dataset="my-detector", limit=100, fields=["id", "created", "name", "labels"], ): records.extend(page) print(len(records)) ``` ### 매개변수 * `prompt` (str, 선택 사항) - 자연어 검색 프롬프트(CLIP 임베딩을 통한 의미 검색). * `like_image` (str, 선택 사항) - 텍스트 대신 시각적 유사도로 검색할 이미지 ID. * `태그` (str, 선택 사항) - 이 태그가 있는 이미지만. * `class_name` (str, 선택 사항) - 이 클래스에 대한 주석이 있는 이미지만. * `in_dataset` (str, 선택 사항) - 이미지가 속해야 하는 데이터셋 이름(해당 데이터셋의 이미지로만 제한하며 배치 / 주석 작업 스테이징 영역은 제외). * `batch` (bool, 선택 사항) 및 `batch_id` (str, 선택 사항) - 특정 업로드 배치로 제한. * `annotation_job` (bool, 키워드 전용) 및 `annotation_job_id` (str, 키워드 전용) - 특정 주석 작업으로 제한. * `offset` (int, 기본값 `0`) - 페이지 매김 오프셋. * `limit` (int, 기본값 `100`) - 페이지 크기. * `fields` (list\[str], 선택 사항) - 응답 크기를 줄이기 위해 각 결과에 대해 나열된 필드만 요청합니다. `search_all()` 는 생성기입니다 - 각 반복은 최대 `limit` 개의 결과를 반환하며, 오프셋을 자동으로 진행합니다. 한 번만 호출하는 단일 페이지 요청의 경우 `project.search(...)` 를 동일한 인수와 함께 사용하세요. ### 워크스페이스 전체 검색 워크스페이스의 모든 프로젝트를 검색하려면 `Workspace.search()` / `Workspace.search_all()`을 사용하세요. 프로젝트별 메서드와 달리, 이들은 단일 RoboQL `query` 문자열(예: `"class:forklift"`, `"tag:review"`또는 의미론적 CLIP 검색을 위한 자유 텍스트)과 선택적 `page_size` 와 `fields`를 받습니다. 반환되는 각 페이지는 결과 행의 목록이며, 행에는 `projects` 필드 아래에 소스 프로젝트가 포함됩니다. ```python records = [] for page in rf.workspace().search_all(query="class:forklift"): records.extend(page) ``` ### 검색 결과를 다운로드 가능한 데이터셋으로 내보내기 `Workspace.search_export()` 는 검색을 실행하고 결과를 다운로드 가능한 데이터셋(COCO / YOLO / VOC 등)으로 패키징합니다. 다음을 참조하세요. [데이터 내보내기(REST)](/datasets/ko/versions/dataset-versions/exporting-data.md#http-api) 에서 기본 엔드포인트를 확인하세요. ```python path = rf.workspace().search_export( query="forklift", format="coco", location="./forklift-search", ) print(path) ``` ## CLI 워크스페이스 전반에서 이미지를 검색하려면 [RoboQL](/datasets/ko/manage/manage-datasets/dataset-search.md) 을 사용하고, 일치하는 결과를 다운로드 가능한 데이터셋으로 선택적으로 내보낼 수 있습니다. ### 검색 ```bash roboflow search "" ``` #### 옵션 | 플래그 | 설명 | | ---------- | -------------------- | | `--limit` | 반환할 최대 결과 수(기본값: 50) | | `--cursor` | 페이지 매김을 위한 계속 토큰 | | `--fields` | 포함할 필드의 쉼표로 구분된 목록 | #### 예시 특정 태그가 있는 이미지를 검색: ```bash roboflow search "tag:reviewed" ``` 특정 클래스를 포함한 이미지를 검색: ```bash roboflow search "class:person" --limit 100 ``` ### 검색 결과 내보내기 추가 `--export` 를 사용해 일치하는 이미지를 데이터셋으로 다운로드: ```bash roboflow search "" --export -f -l ``` #### 내보내기 옵션 | 플래그 | 설명 | | -------------------------- | ----------------------- | | `--export` | 내보내기 모드 활성화 | | `-f`, `--format` | 주석 형식(기본값: coco) | | `-l`, `--location` | 내보내기를 저장할 로컬 디렉터리 | | `-d`, `--dataset` | 특정 프로젝트로 제한 | | `-g`, `--annotation-group` | 특정 주석 그룹으로 제한 | | `--name` | 내보내기용 선택적 이름 | | `--no-extract` | zip 파일을 유지하고 압축 해제는 건너뜀 | #### 예시 검토된 모든 이미지를 COCO 형식으로 내보내기: ```bash roboflow search "tag:reviewed" --export -f coco -l ./reviewed-export ``` 특정 프로젝트의 이미지를 YOLOv8 형식으로 내보내기: ```bash roboflow search "class:car" --export -d my-project -f yolov8 -l ./cars ``` ### JSON 출력 ```bash roboflow search "tag:reviewed" --json ``` ```json { "results": [...], "total": 42, "cursor": "next-page-token" } ``` 다음을 사용하세요. `cursor` 값을 페이지 매김에 사용: ```bash roboflow search "tag:reviewed" --cursor "next-page-token" --json ``` ## MCP 서버 AI 에이전트를 [MCP 서버](https://docs.roboflow.com/agents/mcp-server) 에 연결하면 다음 도구로 이미지를 찾을 수 있습니다:
도구설명
images_search프로젝트 내부에서 이미지를 검색합니다.
images_workspace_searchRoboQL을 사용해 전체 워크스페이스에서 이미지를 검색합니다.