> 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). # 데이터셋 검색 텍스트 기반 검색 쿼리와 필터를 사용해 Roboflow의 데이터셋을 더 잘 이해합니다. ## 정보 데이터셋 검색을 사용하면 파일 이름 조회, 구조화된 필터(태그, 분할, 클래스, 크기, 주석 수), 불리언 논리, 자연어 시맨틱 검색을 통해 프로젝트 전반에서 특정 이미지를 찾을 수 있습니다. 이를 사용해 데이터를 감사하고, 잘못 레이블되었거나 누락된 주석을 찾아내며, 검토나 내보내기를 위한 대상 하위 집합을 만들 수 있습니다. 동일한 쿼리를 웹 앱과 검색 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:`: 이미지 콘텐츠를 기반으로 한 시맨틱 검색 * `tag` : 사용자가 제공한 태그로 필터링합니다. * `filename` : 제공된 파일 이름과 일치하는 파일 이름을 검색합니다. 부분 일치를 실행하려면 쿼리의 앞뒤에 \*를 사용하세요. * `split` : 분할(train, test, valid)로 필터링합니다. * `job:` : 제공된 작업 ID가 있는 이미지를 표시합니다. * `min-width:X` : 너비가 최소 X픽셀인 이미지를 표시합니다. * `max-width:X` : 너비가 최대 X픽셀인 이미지를 표시합니다. * `min-height:X` : 높이가 최소 X픽셀인 이미지를 표시합니다. * `max-height:X` : 높이가 최대 X픽셀인 이미지를 표시합니다. * `min-annotations:X` : 주석이 최소 X개 있는 이미지를 표시합니다. * `max-annotations:X` : 주석이 최대 X개인 이미지를 표시합니다. 다음을 사용하세요: `max-annotations:0` 주석이 없는 이미지를 찾으려면. * `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, // true이면 URL의 프로젝트에 포함된 이미지만 필터링합니다 "in_dataset": boolean, // 제공되면 어떤 배치에든 포함된 이미지만 반환합니다 "batch": boolean, // 제공되면 지정된 배치에 포함된 이미지만 반환합니다 "batch_id": string, // 제공되면 어떤 주석 작업에든 포함된 이미지만 반환합니다 "annotation_job": boolean, // 제공되면 지정된 주석 작업에 포함된 이미지만 반환합니다 "annotation_job_id": string, // 반환할 미디어: "image", "video", 또는 둘 다. 기본값: ["image"] "mediaTypes": string[], // 반환할 필드를 지정합니다. 기본값은 ["id", "created"] // 옵션은 ["id", "name", "annotations", "labels", "split", "tags", "owner", "url", "embedding", "created"] "fields": string[] } ``` 모든 결과에는 `mediaType` 의 `image` 또는 `video`. 다음을 요청하면 `url`, 비디오 결과의 포스터 이미지는 다음에 있고 `url` 짧은 수명의 다운로드 링크는 다음에 있습니다: `videoUrl`. 검색 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" ] } // ... 등 ] } ``` ### 작업공간 전체에서 이미지 검색 Workspace Image Search API를 사용하면 작업공간 내의 이미지를 나열하고 검색할 수 있습니다. 이 API를 사용하면 다음과 유사한 쿼리 문자열로 필터링, 정렬, 시맨틱 검색을 수행할 수 있습니다: [Roboflow 웹 애플리케이션의 이미지 검색 기능](#web-app). #### 엔드포인트 API에 요청하려면 다음을 보내세요: `POST` 다음 엔드포인트로 요청: ``` https://api.roboflow.com/{WORKSPACE}/search/v1?api_key=API_KEY ``` 여기서 `WORKSPACE` 는 작업공간 ID이며 `API_KEY` 는 API 키입니다. [Workspace 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"`. * `mediaTypes`: 반환할 미디어: `"image"`, `"video"`, 또는 둘 다(기본값: `["image"]`). 결과에는 `mediaType` 및 `videoUrl` 프로젝트 검색처럼 [프로젝트 검색](#search-images-in-a-project). **예시 요청** ```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을 키로 하는 객체로, 프로젝트별 데이터를 포함합니다: * `split`: 데이터셋 분할(예: "test")을 나타냅니다. 다음일 때 반환됩니다 `"split"` 다음에 포함될 때 `fields`. * `inDataset`: 이미지가 데이터셋에 포함되어 있는지 나타내는 불리언 값입니다. 다음일 때 반환됩니다 `"projects"` 다음에 포함될 때 `fields`. * `annotations`: 이 프로젝트의 이미지에 대한 주석 데이터로, 다음을 포함합니다: `annotationGroup`, `classes`및 `classCounts`. 다음일 때 반환됩니다 `"annotations"` 다음에 포함될 때 `fields`. * `labels`: 이 프로젝트의 이미지에 대한 레이블 데이터입니다. 다음일 때 반환됩니다 `"labels"` 다음에 포함될 때 `fields`. * `tags`: 이미지와 연결된 태그 배열입니다. * `width`: 이미지의 너비(픽셀)입니다. * `height`: 이미지의 높이(픽셀)입니다. * `filename`: 이미지 파일 이름입니다. * `aspectRatio`: 이미지의 가로세로비입니다. * `owner`: 이미지 소유자 식별자입니다. * `url`: 원본 이미지 파일의 직접 URL입니다. **페이지네이션 및 `continuationToken`** 이 `continuationToken` 응답에 반환된 항목은 검색 결과와 일치하는 페이지 사이를 이동할 수 있게 해줍니다. 다음 `continuationToken` 가 후속 요청에 포함되면 다음 결과 집합을 가져옵니다. 다음을 사용하려면 `continuationToken`, 다음 API 호출의 요청 본문에 포함하세요. 그러면 원래 쿼리를 기준으로 다음 결과 페이지를 가져옵니다. **오류 응답** * `400` - 다음 경우 반환됩니다 `query` 가 누락되었거나 비어 있거나, 다음 경우 `project:` 필터가 작업공간에 속하지 않는 프로젝트를 참조할 때. * `500` - 내부 서버 오류. **프로젝트 및 데이터셋 필터** 다음에서 사용할 수 있는 모든 필터 외에도 [앱 내 데이터셋 검색](#web-app), 작업공간 전체 검색은 다음에 대한 필터도 지원합니다: `project` 및 `dataset` . 예를 들어 다음과 같은 쿼리를 사용할 수 있습니다: `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=True, limit=100, fields=["id", "created", "name", "labels"], ): records.extend(page) print(len(records)) ``` ### 매개변수 * `prompt` (str, optional) - 자연어 검색 프롬프트(CLIP 임베딩을 통한 의미 검색). * `like_image` (str, optional) - 텍스트 대신 시각적 유사성으로 검색할 이미지 ID. * `tag` (str, optional) - 이 태그가 있는 이미지만. * `class_name` (str, optional) - 이 클래스에 대한 주석이 있는 이미지만. * `in_dataset` (bool, optional) - 배치 / 주석 작업 스테이징 영역을 제외하고 프로젝트의 데이터셋에 있는 이미지로 결과를 제한할지 여부입니다. * `batch` (bool, optional) 그리고 `batch_id` (str, optional) - 특정 업로드 배치로 제한합니다. * `annotation_job` (bool, kw-only) 그리고 `annotation_job_id` (str, kw-only) - 특정 주석 작업으로 제한합니다. * `offset` (int, 기본값 `0`) - 페이지네이션 오프셋입니다. * `limit` (int, 기본값 `100`) - 페이지 크기입니다. * `fields` (list\[str], optional) - 응답 크기를 줄이기 위해 각 결과에서 나열된 필드만 요청합니다. `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 등)으로 패키징합니다. 자세한 내용은 [Export Data (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을 사용하여 전체 워크스페이스의 이미지를 검색합니다.