데이터셋 검색

텍스트 기반 검색 쿼리와 필터를 사용해 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 이는 최소 너비 필터와 최대 어노테이션 수 필터를 사용합니다

다음의 전체 목록을 보세요 검색 필터및 아래 예시도 함께

이 모든 검색 필터와 쿼리는 서로 조합할 수 있습니다

의미 검색

이미지를 설명하는 방식으로 검색할 수 있습니다. 이러한 쿼리는 검색어와 가장 관련성이 높은 이미지를 찾아주며, 객체에 아직 레이블이 없어도 이미지를 찾는 데 도움이 됩니다.

의미 검색은 어떤 필터 선택자도 없이 텍스트 쿼리를 입력할 때 발생합니다(예: filename:)

파일 이름으로 검색

다음 필터를 사용해 파일 이름을 검색할 수 있습니다 filename: 또는 파일 이름 텍스트 상자를 사용하면 쿼리가 자동으로 만들어집니다.

데이터셋 분할로 검색

데이터셋 분할(train, valid, test)로 이미지를 검색합니다

이미지를 다른 분할로 다시 할당하려면, 이미지를 선택한 뒤(또는 검색 결과에서 "모두 선택"을 선택한 뒤) 대량 작업 메뉴에서 "데이터셋 분할 변경"을 클릭하세요. 큰 선택 항목은 백그라운드에서 처리됩니다.

업로드 날짜로 검색

다음을 사용하여 Roboflow에 처음 업로드된 날짜 기준으로 이미지를 필터링합니다 date: 필터. 업로드 날짜는 변경 불가능하며, 이미지가 편집되거나, 다시 어노테이션되거나, 분할 간 이동해도 바뀌지 않습니다.

사용하세요 date:YYYY-MM-DD 는 특정 날짜를 지정할 때 사용하거나, 비교 연산자를 조합해 범위를 검색할 수 있습니다:

date>=2026-01-01 date<2026-02-01

검색 필터

사용 가능한 필터는 다음과 같습니다:

• like-image:<IMAGE_ID>: 이미지 콘텐츠를 기반으로 한 의미 검색

• tag : 사용자가 제공한 태그로 필터링합니다.

• filename : 제공된 파일 이름과 일치하는 파일 이름을 검색합니다. 부분 일치를 실행하려면 쿼리의 앞뒤에 *를 사용하세요.

• split : 분할(train, test, valid)로 필터링합니다.

• job:<JOB_ID> : 제공된 작업 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

REST API를 사용하여 Roboflow에 호스팅된 이미지를 검색할 수 있습니다. 엔드포인트는 두 가지가 있습니다. 프로젝트 범위의 /:workspace/:project/search 엔드포인트와 워크스페이스 전체의 /:workspace/search/v1 엔드포인트가 있으며, 이는 다음을 그대로 반영합니다 웹 앱 데이터셋 검색.

프로젝트에서 이미지 검색

Roboflow에 호스팅된 이미지를 검색하려면 다음 API 엔드포인트로 POST 요청을 보내세요:

https://api.roboflow.com/:workspace/:project/search

다음은 API 요청 예시입니다:

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 본문에서 다음 값을 허용합니다:

{
     // 제공되면 의미 유사도 순으로 정렬된 결과를 제공합니다
     "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는 다음 구조의 응답을 반환합니다. 사용 가능한 값은 추가로 지정한 필드 에 따라 달라집니다:

{
    "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 웹 애플리케이션의 이미지 검색 기능.

엔드포인트

API에 요청하려면 다음 엔드포인트로 POST 요청을 보내세요:

https://api.roboflow.com/{WORKSPACE}/search/v1?api_key=API_KEY

여기서 WORKSPACE 는 워크스페이스 ID이고, API_KEY 는 API 키입니다.

워크스페이스 ID를 찾는 방법 알아보기.

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

• 필드: 응답에 포함할 필드 목록입니다. 가능한 값은 "tags", "width", "height", "filename", "aspectRatio", "split", "projects", "annotations", "labels", "owner", "url".

요청 예시

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: 페이지네이션용 토큰.

이미지 객체 필드

다음에 요청한 필드에 따라 필드 매개변수:

• id: 이미지의 고유 식별자.

• projectData: 프로젝트 URL을 키로 하는 객체로, 프로젝트별 데이터를 포함합니다:

  • split: 데이터셋 분할을 나타냅니다(예: "test"). 다음일 때 반환됩니다 "split" 가 필드.

  • inDataset: 이미지가 데이터셋에 있는지 여부를 나타내는 불리언 값입니다. 다음일 때 반환됩니다 "projects" 가 필드.

  • annotations: 이 프로젝트의 이미지에 대한 어노테이션 데이터입니다. 여기에는 annotationGroup, classes및 classCounts. 다음일 때 반환됩니다 "annotations" 가 필드.

  • labels: 이 프로젝트의 이미지에 대한 레이블 데이터입니다. 다음일 때 반환됩니다 "labels" 가 필드.

• tags: 이미지와 연결된 태그 배열.

• width: 이미지의 픽셀 너비.

• height: 이미지의 픽셀 높이.

• filename: 이미지 파일 이름.

• aspectRatio: 이미지의 종횡비.

• owner: 이미지의 소유자 식별자.

• url: 원본 이미지 파일로의 직접 URL.

페이지네이션 및 continuationToken

해당 continuationToken 응답에 반환된 는 검색 결과와 일치하는 페이지 사이를 이동할 수 있게 해줍니다. 다음 요청에 continuationToken 가 포함되면 다음 결과 집합을 가져옵니다.

사용하려면 continuationToken를 다음 API 호출의 요청 본문에 포함하세요. 이렇게 하면 원래 쿼리를 기반으로 다음 결과 페이지를 가져옵니다.

오류 응답

• 400 - 다음일 때 반환됩니다 query 가 누락되었거나 비어 있거나, 또는 project: 필터가 워크스페이스에 속하지 않는 프로젝트를 참조하는 경우.

• 500 - 내부 서버 오류.

프로젝트 및 데이터셋 필터

다음에서 사용 가능한 모든 필터 외에도 앱 내 데이터셋 검색, 워크스페이스 전체 검색은 다음에 대한 필터도 지원합니다 프로젝트 및 데이터셋 . 예를 들어 다음과 같은 쿼리를 사용할 수 있습니다 project:foo project:bar 두 프로젝트 모두에 있는 모든 이미지를 찾기 위해 foo 및 bar. 다음과 같은 쿼리는 dataset:foo프로젝트의 이미지를 반환합니다 foo 레이블이 지정되었고 프로젝트의 데이터셋에 추가된 이미지입니다.

Python SDK

Project.search_all() 프로젝트의 이미지 전반에서 검색 결과를 페이지 단위로 반환하는 반복자를 돌려줍니다. 검색 모드는 조합할 수 있습니다: 클래스에 의해 범위가 좁혀진 텍스트 프롬프트, 단일 배치로 필터링된 기존 이미지 유사도 검색 등.

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, optional) - 자연어 검색 프롬프트(CLIP 임베딩을 통한 의미 검색).

• like_image (str, optional) - 텍스트 대신 시각적 유사도로 검색할 이미지 ID.

• tag (str, optional) - 이 태그가 있는 이미지만.

• class_name (str, optional) - 이 클래스의 어노테이션이 있는 이미지만.

• in_dataset (str, optional) - 이미지가 속해야 하는 데이터셋의 이름(해당 데이터셋의 이미지로 제한되며, 배치/어노테이션 작업 스테이징 영역은 제외).

• batch (bool, optional) 및 batch_id (str, optional) - 특정 업로드 배치로 제한합니다.

• annotation_job (bool, 키워드 전용) 및 annotation_job_id (str, 키워드 전용) - 특정 어노테이션 작업으로 제한합니다.

• offset (int, 기본값 0) - 페이지네이션 오프셋.

• limit (int, 기본값 100) - 페이지 크기.

• 필드 (list[str], optional) - 응답 크기를 줄이기 위해 결과당 나열된 필드만 요청합니다.

search_all() 는 제너레이터입니다. 각 반복은 최대 limit 개의 결과가 있는 한 페이지를 반환하고, offset을 자동으로 증가시킵니다. 한 번만 실행하는 단일 페이지 호출의 경우 project.search(...) 를 동일한 인자로 사용하세요.

워크스페이스 전체 검색

워크스페이스의 모든 프로젝트를 대상으로 검색하려면 Workspace.search() / Workspace.search_all()를 사용하세요. 프로젝트별 메서드와 달리, 이들은 단일 RoboQL query 문자열(예: "class:forklift", "tag:review"또는 의미 CLIP 검색을 위한 자유 텍스트)과 선택적 page_size 및 필드. 각 반환된 페이지는 결과 행의 목록이며, 행에는 소스 프로젝트가 하나의 프로젝트 필드 아래에 포함됩니다.

records = []
for page in rf.workspace().search_all(query="class:forklift"):
    records.extend(page)

검색 결과를 다운로드 가능한 데이터셋으로 내보내기

Workspace.search_export() 검색을 실행하고 결과를 다운로드 가능한 데이터셋(COCO / YOLO / VOC 등)으로 패키징합니다. 자세한 내용은 데이터 내보내기(REST) 해당 기반 엔드포인트를 참조하세요.

path = rf.workspace().search_export(
    query="forklift",
    format="coco",
    location="./forklift-search",
)
print(path)

CLI

워크스페이스 전체에서 다음을 사용해 이미지를 검색할 수 있습니다 RoboQL 원하는 경우 일치하는 결과를 다운로드 가능한 데이터셋으로 내보낼 수 있습니다.

검색

roboflow search "<query>"

옵션

플래그	설명
--limit	반환할 최대 결과 수(기본값: 50)
--cursor	페이지네이션용 연속 토큰
--fields	포함할 필드의 쉼표로 구분된 목록

예시

특정 태그가 있는 이미지를 검색:

roboflow search "tag:reviewed"

특정 클래스를 포함한 이미지를 검색:

roboflow search "class:person" --limit 100

검색 결과 내보내기

추가 --export 일치하는 이미지를 데이터셋으로 다운로드하려면:

roboflow search "<query>" --export -f <format> -l <location>

내보내기 옵션

플래그	설명
--export	내보내기 모드 활성화
-f, --format	주석 형식(기본값: coco)
-l, --location	내보내기를 저장할 로컬 디렉터리
-d, --dataset	특정 프로젝트로 제한
-g, --annotation-group	특정 주석 그룹으로 제한
--name	내보내기용 선택적 이름
--no-extract	ZIP 파일을 유지하고 압축 해제는 건너뜀

예시

검토된 모든 이미지를 COCO 형식으로 내보내기:

roboflow search "tag:reviewed" --export -f coco -l ./reviewed-export

특정 프로젝트의 이미지를 YOLOv8 형식으로 내보내기:

roboflow search "class:car" --export -d my-project -f yolov8 -l ./cars

JSON 출력

roboflow search "tag:reviewed" --json

{
  "results": [...],
  "total": 42,
  "cursor": "next-page-token"
}

다음을 사용하세요 커서 페이지네이션 값:

roboflow search "tag:reviewed" --cursor "next-page-token" --json