빠른 시작: 검색 탐색기를 사용하여 Azure Portal에서 쿼리 실행

2025-05-27

이 빠른 시작에서는 Azure AI Search 인덱스에 대해 쿼리를 실행하기 위해 Azure Portal의 기본 제공 쿼리 도구인 Search 탐색기를 사용하는 방법을 알아봅니다. 쿼리 또는 필터 식을 테스트하거나 인덱스에 콘텐츠가 있는지 확인하는 데 사용합니다.

이 빠른 시작에서는 기존 인덱스를 사용하여 검색 탐색기를 보여줍니다.

필수 조건

활성 구독이 있는 Azure 계정. 체험 계정을 만듭니다.
Azure AI 검색 서비스. 현재 구독에서 서비스를 만들거나 기존 서비스를 찾습니다. 이 빠른 시작에서는 무료 서비스를 사용할 수 있습니다.
이 퀵스타트에서는 realestate-us-sample 인덱스를 사용합니다. 인덱을 만들려면 데이터 가져오기 마법사를 실행하고 기본 제공 샘플 데이터를 선택한 다음 모든 기본값을 사용하여 마법사를 단계별로 실행합니다.

검색 탐색기 시작

Azure Portal에서 검색 서비스를 찾고 개요 페이지를 엽니다.
명령 모음에서 검색 탐색기를 선택합니다.

또는 열려 있는 인덱스에서 검색 탐색기 탭을 선택합니다.

세 가지 방법으로 쿼리하기

검색 탐색기에서 쿼리하는 방법에는 다음 세 가지가 있습니다.

쿼리 뷰는 기본 검색 창을 제공합니다. 빈 쿼리나 부울 연산자가 포함된 자유 텍스트 쿼리를 예시로 seattle condo + parking를 수용합니다.
이미지 보기는 PNG, JPG 또는 JPEG 파일을 찾아보거나 끌어서 놓을 수 있는 창을 제공합니다. 인덱스가 이미지 벡터라이저와 동등한 기술을 가지고 있지 않으면 이 보기를 사용할 수 없습니다.
JSON 뷰는 매개 변수화된 쿼리를 지원합니다. 필터, orderby, select, count, searchFields 및 기타 모든 매개 변수는 JSON 보기에서 설정해야 합니다.

예: 이미지 쿼리

검색 탐색기는 이미지 보기를 통해 이미지를 쿼리 입력으로 허용하므로 지원되는 벡터라이저 기술 쌍을 사용해야 합니다. 자세한 내용은 검색 인덱스에서 벡터라이저 구성을 참조하세요.

realestate-us-sample 인덱스가 이미지 벡터화를 위해 구성되지 않았습니다. 이미지 쿼리를 실행하려면 Azure Portal에서 빠른 시작: 벡터 검색에 설명된 대로 인덱스를 만듭니다. 빠른 시작에서는 텍스트 기반 샘플 데이터를 사용하므로 이미지가 포함된 문서를 사용해야 합니다.

이미지 쿼리를 실행하려면 이미지를 선택하거나 검색 영역으로 끌어서 검색을 선택합니다. 검색 탐색기는 이미지를 벡터화하고 쿼리 실행을 위해 검색 엔진에 벡터를 보냅니다. 검색 엔진은 지정된 k 결과 수까지 입력 이미지와 충분히 유사한 문서를 반환합니다.

예: JSON 쿼리

다음은 검색 탐색기를 사용하여 실행할 수 있는 JSON 쿼리의 예입니다. 이러한 예제를 수행하려면 JSON 보기로 전환합니다. 각 JSON 예제를 텍스트 영역에 붙여넣을 수 있습니다.

팁

JSON 뷰는 매개 변수 이름 완성을 위한 intellisense를 제공합니다. JSON 뷰 내에 커서를 놓고 공백 문자를 입력하여 모든 쿼리 매개 변수를 확인합니다. "s"와 같은 문자를 입력하여 해당 문자로 시작하는 쿼리 매개 변수만 볼 수도 있습니다. Intellisense는 잘못된 매개 변수를 제외하지 않으므로 최선의 판단을 사용합니다.

지정되지 않은 쿼리 실행

검색 탐색기에서 POST 요청은 검색 POST REST API를 사용하여 내부적으로 공식화되며 응답은 자세한 JSON 문서로 반환됩니다.

콘텐츠를 처음 살펴보려면 용어가 제공되지 않은 검색을 선택하여 빈 검색 을 실행합니다. 빈 검색은 전체 문서를 반환하여 문서 컴퍼지션을 검토할 수 있도록 하므로 첫 번째 쿼리로서 유용합니다. 빈 검색에서는 검색 점수가 없으며 문서가 임의 순서로 반환됩니다(모든 문서에 대한"@search.score": 1). 기본적으로 하나의 검색 요청에서 50개의 문서가 반환됩니다.

빈 검색에 해당하는 구문은 * 또는 "search": "*"입니다.

{
   "search": "*",
   "count": true
}

결과

자유 텍스트 쿼리 실행

연산자가 있거나 없는 자유 형식 검색은 사용자 지정 앱에서 Azure AI Search로 전송된 사용자 정의 쿼리를 시뮬레이션하는 데 유용합니다. 인덱스 정의에서 "검색 가능"으로 특성이 지정된 필드만 일치 항목에 대해 검색됩니다.

무료 텍스트 쿼리에는 JSON 보기가 필요하지 않지만 이 문서에서는 다른 예제와의 일관성을 위해 JSON으로 제공합니다.

쿼리 용어나 식 같은 검색 조건을 입력하면 검색 순위가 매겨집니다. 다음 예제에서는 자유 텍스트 검색을 보여 줍니다. "@search.score"는 기본 점수 알고리즘을 사용하여 일치에 대해 계산된 관련성 점수입니다.

{
    "search": "Seattle townhouse `Lake Washington` miele OR thermador appliance"
}

결과

특정 관심 용어의 경우 Ctrl+F를 사용하여 결과 내에서 검색을 수행할 수 있습니다.

일치하는 문서 개수 계산

인덱스에서 찾은 일치 항목 수를 가져오려면 "count": true(을)를 추가합니다. 빈 검색에서 count는 인덱스의 총 문서 수입니다. 정규화된 검색에서는 쿼리 입력과 일치하는 문서의 수입니다. 서비스는 기본적으로 상위 50개의 일치 항목을 반환하므로 결과에 반환된 항목보다 인덱스에서 더 많은 일치 항목이 표시될 수 있습니다.

{
    "search": "Seattle townhouse `Lake Washington` miele OR thermador appliance",
    "count": true
}

결과

검색 결과의 필드 제한

검색 탐색기에서 더 읽기 쉬운 출력을 위해 명시적으로 이름이 지정된 필드로 결과를 제한하려면 "select"를 추가합니다. 검색 인덱스에서 "검색 가능"으로 표시된 필드만 결과에 표시될 수 있습니다.

{
   "search": "seattle condo",
   "count": true,
   "select": "listingId, beds, baths, description, street, city, price"
}

결과

결과의 다음 일괄 처리 반환

Azure AI 검색은 검색 순위에 따라 상위 50개 일치 항목을 반환합니다. 일치하는 다음 문서 집합을 가져오려면 "top": 100 및 "skip": 50(을)를 추가하여 결과 집합을 100개 문서(기본값은 50개, 최댓값은 1000개)로 늘리고 처음 50개 문서는 건너뜁니다. 문서 키(listingID)를 확인하여 문서를 식별할 수 있습니다.

순위가 지정된 결과를 얻으려면 쿼리 용어 또는 식과 같은 검색 조건을 제공해야 합니다. 검색 결과에 더 깊게 도달할수록 검색 점수가 줄어듭니다.

{
   "search": "seattle condo",
   "count": true,
   "select": "listingId, beds, baths, description, street, city, price",
   "top": 100,
   "skip": 50
}

결과

필터 식(보다 큼, 보다 작음, 같음)

filter 매개 변수를 사용하여 포함 또는 제외 조건을 지정합니다. 필드는 인덱스에서 "필터링 가능"으로 특성이 지정되어야 합니다. 이 예제에서는 침실 개수가 4개 이상인 항목을 검색합니다.

{
    "search": "seattle condo",
    "count": true,
    "select": "listingId, beds, baths, description",
    "filter": "beds gt 3"
}

결과

결과 정렬

검색 점수 외에 다른 필드를 기준으로 결과를 정렬하려면 orderby(을)를 추가합니다. 필드는 인덱스에서 "정렬 가능"으로 특성이 지정되어야 합니다. 필터링된 값이 동일한 경우(예: 동일한 가격) 순서는 임의적이지만 더 심층적인 정렬을 위해 더 많은 조건을 추가할 수 있습니다. 다음은 이 출력을 테스트하는 데 사용할 수 있는 예제 식입니다.

{
    "search": "seattle condo",
    "count": true,
    "select": "listingId, price, beds, baths, description",
    "filter": "beds gt 3",
    "orderby": "price asc"
}

결과

핵심 내용

이 빠른 시작에서는 검색 탐색기에서 REST API를 사용하여 인덱스를 쿼리했습니다.

결과는 자세한 JSON 문서로 반환되므로 문서 생성 및 콘텐츠를 완전히 볼 수 있습니다. 쿼리 식의 select 매개 변수는 반환되는 필드를 제한할 수 있습니다.
검색 결과는 인덱스에서 "검색 가능"으로 표시된 모든 필드로 구성됩니다. 특성을 검토하려면 인접한 필드 탭을 선택합니다.
상용 웹 브라우저에 입력하는 것과 유사한 키워드 검색은 최종 사용자 환경을 테스트하는 데 유용합니다. 예를 들어 기본 제공 부동산 샘플 인덱스를 가정하면 "시애틀 아파트 레이크 워싱턴"을 입력한 다음 Ctrl-F 사용하여 검색 결과 내에서 용어를 찾을 수 있습니다.
쿼리 및 필터 식은 Azure AI 검색에서 구현되는 구문으로 표현됩니다. 기본 구문은 간단한 구문이지만 필요에 따라 보다 강력한 쿼리를 위해 전체 Lucene을 사용할 수 있습니다. 필터 식은 OData 구문으로 표현됩니다.

리소스 정리

자체 구독으로 작업하는 경우 프로젝트가 끝날 때 만든 리소스가 여전히 필요한지 여부를 결정하는 것이 좋습니다. 계속 실행되는 리소스에는 요금이 부과될 수 있습니다. 리소스를 개별적으로 삭제하거나 리소스 그룹을 삭제하여 전체 리소스 세트를 삭제할 수 있습니다.

왼쪽 탐색 창의 모든 리소스 또는 리소스 그룹 링크를 사용하여 Azure Portal에서 리소스를 찾고 관리할 수 있습니다.

무료 서비스를 사용하는 경우 인덱스, 인덱서, 데이터 원본 3개로 제한됩니다. Azure Portal에서 개별 항목을 삭제하여 제한 이하로 유지할 수 있습니다.

다음 단계

쿼리 구조 및 구문에 대해 자세히 알아보려면 REST 클라이언트를 사용하여 API의 더 많은 파트를 사용하는 쿼리 식을 만드세요. 검색 POST REST API는 학습 및 탐색에 특히 유용합니다.

빠른 시작: REST를 사용한 전체 텍스트 검색