Azure AI 검색에서 하이브리드 쿼리를 만들기

참고

Azure AI 검색 Azure 포털, REST API 및 Azure SDK 통해 사용할 수 있습니다. 또한 엔터프라이즈 콘텐츠를 Microsoft Foundry 포털의 에이전트에 대해 재사용 가능한 사용 권한 인식 기술 자료로 변환하는 관리되는 기술 계층인 Foundry IQ를 뒷받침합니다.

Important

기능, 기능 또는 표시된 속성(미리 보기)은 서비스 수준 계약에 포함되지 않으며 프로덕션 워크로드에는 권장되지 않으며 일반적으로 사용 가능해지기 전에 변경되거나 제한될 수 있습니다. Azure AI 검색 미리 보기 용어는 독립 실행형 기능이든 일반 공급 기능의 일부이든 관계없이 모든 미리 보기 기능에 적용됩니다.

하이브리드 검색 은 단일 검색 요청에서 텍스트(키워드) 및 벡터 쿼리를 결합합니다. 두 쿼리는 모두 병렬로 실행됩니다. 결과는 RRF(상호 순위 Fusion) 를 사용하여 통합된 결과 집합을 반환하는 새 검색 점수에 의해 병합되고 순서가 변경됩니다. 대부분의 경우 벤치마크 테스트당 의미 체계 순위가 있는 하이브리드 쿼리는 가장 관련성이 높은 결과를 반환합니다.

이 문서에서는 다음 방법을 알아봅니다.

기본 하이브리드 요청 설정
매개 변수 및 필터 추가
의미 체계 순위 또는 벡터 가중치를 사용하여 관련성 향상
입력을 제어하여 쿼리 동작 최적화(maxTextRecallSize)

이 문서의 끝부분에 키워드와 벡터 검색을 선택적 의미 체계 순위와 결합하는 하이브리드 쿼리를 실행할 수 있습니다.

필수 구성 요소

Azure 구독입니다. 무료로 만듭니다.
Azure AI 검색 서비스입니다. 서비스 만들기 또는 기존 서비스 찾기.
벡터 및 비벡터 필드가 searchable 포함된 검색 인덱스입니다. 데이터 가져오기 마법사를 사용하여 인덱스 빠르게 만드는 것이 좋습니다. 그렇지 않으면 인덱스 만들기 및 검색 인덱 스로 벡터 필드 추가를 참조하세요.
사용 권한: 인덱스를 쿼리하려면 검색 인덱스 데이터 판독 기가 필요합니다. 인덱스 만들기 또는 업데이트하려면 검색 인덱스 데이터 기여자가 필요합니다. 자세한 내용은 역할을 사용하여 연결을 참조하세요.
(선택 사항) SDK 설치:
- 파이썬: pip install azure-search-documents
- C#: dotnet add package Azure.Search.Documents
(선택 사항) 쿼리 문자열의 기본 제공 텍스트-벡터 변환을 원하는 경우 검색 인덱스의 벡터 필드에 벡터라이저를 만들고 할당 합니다.

API, 도구 및 실행 가능한 패턴 선택

Azure 포털의 검색 탐색기(안정 및 미리 보기 API 검색 구문 모두 지원)에는 하이브리드 요청에 붙여넣을 수 있는 JSON 보기가 있습니다.
Azure SDK 안정적인 최신 패키지 또는 미리 보기 패키지(SDK 기능 지원에 대한 변경 로그 참조).
maxTextRecallSize 및 countAndFacetMode(미리 보기)와 같은 미리 보기 기능을 사용하는 경우 안정적인 REST API 또는 최신 미리 보기 API 버전입니다.

가독성을 위해 REST 예제를 사용하여 API의 작동 방식을 설명합니다. REST 확장과 함께 Visual Studio Code 같은 REST 클라이언트를 사용하여 하이브리드 쿼리를 빌드할 수 있습니다. Azure SDK 사용할 수도 있습니다. 자세한 내용은 빠른 시작: 벡터 검색을 참조하세요.

실행 가능한 하이브리드 패턴

하이브리드 검색을 접하는 경우 하나의 패턴을 선택하고 작은 단계로 튜닝합니다. 하나의 요청에서 최대 벡터 검색, 대량 텍스트 검색 및 의미 재순위를 동시에 시작하지 마세요.

균형 잡힌 하이브리드(기본값): 대부분의 워크로드에 먼저 사용합니다. k 30~50 범위에서 시작하고 top 10~20 범위에서 시작하며, 측정된 관련성을 향상시킬 때에만 의미 체계 순위를 사용하도록 설정합니다.
리콜 우선 하이브리드: 적용 범위가 목표인 어려운 쿼리에 사용합니다. 점진적으로 늘리고 maxTextRecallSize 벡터 설정을 보통으로 유지합니다. 더 높은 병합 비용을 예상하십시오.
정밀도 우선 하이브리드: 짧은 대기 시간에 대규모로 사용합니다. k 및 top을 온건하게 유지하고, 선택적 필터를 적용하며, 가치를 추가하지 않는 의미 기능을 피하십시오.

과부하된 쿼리가 제한되는 이유

하이브리드 쿼리는 텍스트 및 벡터 검색을 병렬로 실행한 다음 결과를 RRF와 병합합니다. 어휘 기여도를 늘리는 경우(예: BM25를 위해 하이브리드 가중치를 변경하여) 벡터 후보와 병합해야 하는 텍스트 후보 수를 늘립니다. 이 설정을 고가의 벡터 설정 및 의미 체계 다시 표시와 결합하면 CPU 및 메모리 압력이 빠르게 증가합니다.

용량이 적은 구성에서는, 추가 병합 및 순위 재조정 작업으로 인해 다음이 발생할 수 있습니다.

지연 시간 및 p95/p99 급등
429 제한 응답
다시 시도 동작이 구성되지 않은 경우 클라이언트에서 관찰한 삭제 또는 시간 초과 요청

스케일 아웃하기 전에 순서 조정

복제본을 추가하기 전에 쿼리 및 벡터 설정을 조정합니다.

먼저 비용이 많이 드는 벡터 검색 설정을 줄입니다. 예를 들어 efSearch과 maxConnections이(가) 적극적으로 설정된 경우, 확장하기 전에 이들을 낮추세요(예: efSearch를 약 800에서 128에서 192로 줄이고, maxConnections를 64에서 32로 줄입니다).
의미 재순위를 이점이 있는 사례로 제한합니다.
대표 부하에서 대기 시간 및 429 속도를 다시 테스트합니다.
조정 후 제한이 지속되는 경우에만 복제본 크기를 조정합니다.

크기를 조정하기 전에 먼저 안정성을 개선하고 비용을 제어하려면 이 시퀀스를 사용합니다.

하이브리드 쿼리 설정

이 섹션에서는 하이브리드 쿼리의 기본 구조와 검색 탐색기에서 또는 REST 클라이언트에서 실행을 설정하는 방법을 설명합니다.

결과는 벡터가 포함된 필드를 비롯하여 일반 텍스트로 retrievable 반환됩니다. 숫자 벡터는 검색 결과에 유용하지 않으므로 인덱스의 다른 필드를 벡터 일치의 프록시로 선택합니다. 예를 들어 인덱스의 "descriptionVector" 및 "descriptionText" 필드가 있는 경우 쿼리는 "descriptionVector"에서 일치할 수 있지만 검색 결과에는 "descriptionText"가 표시될 수 있습니다. 매개 변수를 select 사용하여 결과에서 사람이 읽을 수 있는 필드만 지정합니다.

Azure 포털 검색 서비스로 이동합니다.
검색 관리>인덱스 아래에서 벡터 및 비벡터 콘텐츠가 있는 인덱스를 선택합니다. 검색 탐색기가 첫 번째 탭입니다.
보기에서 벡터 쿼리에 붙여넣을 수 있도록 JSON 보기로 전환합니다.
기본 쿼리 템플릿을 하이브리드 쿼리로 바꿉다. 기본 하이브리드 쿼리에는 텍스트 쿼리가 지정되고 search아래에 지정된 벡터 쿼리가 있습니다 vectorQueries.vector. 텍스트 쿼리와 벡터 쿼리는 동일하거나 서로 다를 수 있지만 동일한 의도를 공유하는 것이 일반적입니다.

이 예제는 벡터 및 비벡터 콘텐츠가 있는 vector 빠른 시작 및 여러 쿼리 예제에서 가져옵니다. 간단히 하기 위해 이 문서에서는 벡터가 잘립니다.
```
{
    "search": "historic hotel walk to restaurants and shopping",
    "vectorQueries": [
        {
            "vector": [0.01944167, 0.0040178085, -0.007816401 ... <remaining values omitted> ], 
            "k": 7,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}
```
검색을 선택합니다.

팁

벡터를 숨기면 검색 결과를 더 쉽게 읽을 수 있습니다. 쿼리 옵션에서 검색 결과에서 벡터 값 숨기기를 켭니다.

쿼리의 다른 버전은 다음과 같습니다. 일치하는 항목 수를 계산하기 위한 count를 추가하고, 특정 필드를 선택하기 위한 select 매개변수를 추가하며, 상위 7개 결과를 반환하기 위한 top 매개변수를 추가합니다.

 {
     "count": true,
     "search": "historic hotel walk to restaurants and shopping",
     "select": "HotelId, HotelName, Category, Tags, Description",
     "top": 7,
     "vectorQueries": [
         {
             "vector": [0.01944167, 0.0040178085, -0.007816401 ... <remaining values omitted> ], 
             "k": 7,
             "fields": "DescriptionVector",
             "kind": "vector",
             "exhaustive": true
         }
     ]
 }

다음 예제에서는 REST API를 사용하는 하이브리드 쿼리 요청을 보여 줍니다.

이 예제는 벡터 및 비벡터 콘텐츠가 있는 vector 빠른 시작 및 여러 쿼리 예제에서 가져옵니다. 간단히 하기 위해 이 문서에서는 벡터가 잘립니다.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2026-04-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "vectorQueries": [
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true,
            "k": 10
        },
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true,
            "k": 10
        }
    ],
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelName, Description, Address/City",
    "top": 10
}

핵심 사항:

벡터 쿼리 문자열은 속성을 통해 vectorQueries.vector 지정됩니다. 쿼리는 "DescriptionVector" 필드에 대해 실행됩니다. 쿼리 유형을 나타내려면 "vector"로 설정합니다 kind . 필요에 따라 exhaustive을(를) true로 설정하여 벡터 필드의 전체 내용을 쿼리합니다.
키워드 검색은 속성을 통해 search 지정됩니다. 벡터 쿼리와 병렬로 실행됩니다.

참조: 문서 검색(REST) | vectorQueries

k 는 벡터 쿼리에서 반환되고 RRF 순위에 제공되는 가장 가까운 인접 일치 항목 수를 결정합니다.
top 는 응답 올업에서 반환되는 일치 항목 수를 결정합니다. 이 예제에서 응답에는 병합된 결과에 10개 이상의 일치 항목이 있다고 가정하여 10개의 결과가 포함됩니다.

다음 예제에서는 Python Azure SDK 사용하는 하이브리드 쿼리를 보여 있습니다.

import os
from azure.identity import DefaultAzureCredential
from azure.search.documents import SearchClient
from azure.search.documents.models import VectorizedQuery

# Set up the client
endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
index_name = "hotels-sample"
credential = DefaultAzureCredential()

client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

# Define your vector (typically from an embedding model)
query_vector = [-0.009154141, 0.018708462, ...]  # Your embedding values

# Create the vector query
vector_query = VectorizedQuery(
    vector=query_vector,
    k_nearest_neighbors=10,
    fields="DescriptionVector",
    exhaustive=True
)

# Execute hybrid search
results = client.search(
    search_text="historic hotel walk to restaurants and shopping",
    vector_queries=[vector_query],
    select=["HotelName", "Description", "Address/City"],
    top=10
)

for result in results:
    print(f"{result['HotelName']}: {result['Description']}")

참조: SearchClient | VectorizedQuery

다음 예제에서는 .NET Azure SDK 사용하는 하이브리드 쿼리를 보여줍니다.

using Azure;
using Azure.Identity;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;

// Set up the client
string endpoint = Environment.GetEnvironmentVariable("AZURE_SEARCH_ENDPOINT");
string indexName = "hotels-sample";

SearchClient client = new SearchClient(
    new Uri(endpoint),
    indexName,
    new DefaultAzureCredential());

// Define your vector (typically from an embedding model)
float[] queryVector = new float[] { -0.009154141f, 0.018708462f, /* ... */ };

// Execute hybrid search
SearchResults<SearchDocument> results = client.Search<SearchDocument>(
    "historic hotel walk to restaurants and shopping",
    new SearchOptions
    {
        VectorSearch = new()
        {
            Queries = {
                new VectorizedQuery(queryVector)
                {
                    KNearestNeighborsCount = 10,
                    Fields = { "DescriptionVector" },
                    Exhaustive = true
                }
            }
        },
        Select = { "HotelName", "Description", "Address/City" },
        Size = 10
    });

await foreach (SearchResult<SearchDocument> result in results.GetResultsAsync())
{
    Console.WriteLine($"{result.Document["HotelName"]}: {result.Document["Description"]}");
}

참조: SearchClient | VectorizedQuery

maxTextRecallSize 및 countAndFacetMode 설정하기(미리 보기)

하이브리드 쿼리를 조정하여 결합된 결과에 기여하는 각 하위 쿼리의 양을 제어할 수 있습니다. maxTextRecallSize 매개 변수(미리 보기)를 설정하면 하이브리드 순위 모델에 전달되는 BM25 순위 결과의 수를 지정합니다.

요청에 패싯이 포함된 경우 인덱스에 표시된 facetable 비벡터 필드를 사용합니다. 벡터 필드는 패싯할 수 없습니다.

패싯 수는 쿼리 유형에 따라 달라집니다.

텍스트 전용 쿼리에서 패싯은 텍스트 쿼리와 일치하는 문서의 개수를 계산합니다.
벡터 전용 쿼리에서 패싯은 벡터 쿼리에서 k 반환된 문서 수를 계산합니다.
하이브리드 쿼리에서 패싯은 벡터 및 텍스트 결과를 모두 고려합니다. 벡터 측은 k 가장 가까운 문서를 제공합니다. 텍스트 쪽은 BM25 순위 문서를 제공합니다. 매개 변수(미리 보기)는 countAndFacetMode 개수 및 패싯 계산에서 모든 텍스트 일치를 사용하는지 또는 순위에 대해 검색된 텍스트 일치만 사용하는지 여부를 결정합니다.

maxTextRecallSize를 사용하면 countAndFacetMode를 설정할 수도 있습니다. 이 매개 변수는 count 및 facets에 텍스트 쿼리와 일치하는 모든 문서를 포함할지, 아니면 maxTextRecallSize 창 내에서 검색된 문서만 포함할지를 결정합니다. 기본값은 countAllResults입니다.

기본 countAllResults 모드에서는 카운트 및 패싯에 maxTextRecallSize 창 범위를 벗어나 RRF 순위 산정 시 검색되지 않는 텍스트 기반 문서가 포함될 수 있습니다. maxTextRecallSize를 늘리면 순위 지정에 사용할 수 있는 BM25 순위 문서 수는 증가하지만, 벡터 기여도는 k를 초과하여 증가하지 않습니다. 하이브리드 순위를 위해 검색된 문서에 한해 카운트 및 패싯 계산을 수행하려면 countRetrievableResults를 사용하십시오.

이러한 옵션을 설정하려면 최신 미리 보기 REST API 를 사용하는 것이 좋습니다.

팁

하이브리드 쿼리 튜닝의 또 다른 방법은 요청에서 벡터 쿼리의 중요성을 높이는 데 사용되는 벡터 가중치입니다.

Search - POST(미리 보기) 또는 검색 - GET(미리 보기)을 사용하여 미리 보기 매개 변수를 지정합니다.
쿼리 매개 변수 개체를 hybridSearch 추가하여 하이브리드 쿼리의 BM25 순위 결과를 통해 회수된 최대 문서 수를 설정합니다. 다음과 같은 두 가지 속성이 있습니다.
- maxTextRecallSize 는 하이브리드 쿼리에 사용되는 Reciprocal Rank Fusion(RRF) 랭커에 제공할 BM25 랭킹 결과의 수를 지정합니다. 기본값은 1,000입니다. 최대값은 10,000입니다.
- countAndFacetMode 는 하이브리드 쿼리의 개수 및 패싯 범위를 보고합니다. 기본값인 countAllResults는 maxTextRecallSize 범위를 벗어나 RRF 순위 매김을 위해 검색되지 않는 일부 텍스트 일치 항목이 있더라도, 텍스트 쿼리와 일치하는 모든 문서를 포함하는 전체 하이브리드 결과 집합을 사용합니다. 순위 매기기를 위해 검색된 문서( countRetrievableResults BM25 순위 문서와 maxTextRecallSize 벡터 일치 항목 포함)에 대해 개수와 패싯의 범위를 한정하려면 k를 사용합니다.
설정 maxTextRecallSize:
- 벡터 유사성 검색이 대개 하이브리드 쿼리의 텍스트 쪽을 능가하는 경우 maxTextRecallSize을 줄입니다.
- 인덱스가 크고 기본값이 충분한 수의 결과를 캡처하지 않는 경우 maxTextRecallSize를 증가시키세요. 더 큰 BM25 순위 결과 집합을 사용할 때 top, skip, next를 설정하여 결과의 일부를 검색할 수도 있습니다.

다음 REST 예제에서는 설정 maxTextRecallSize에 대한 두 가지 사용 사례를 보여 줍니다.

첫 번째 예제에서는 maxTextRecallSize 100으로 줄여 하이브리드 쿼리의 텍스트 쪽을 100개의 문서로 제한합니다. 또한 개수 및 패싯 계산에 검색 가능한 문서만 포함하도록 설정합니다 countAndFacetMode .

POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2026-08-01-preview

    { 
      "vectorQueries": [ 
        { 
          "kind": "vector", 
          "vector": [1.0, 2.0, 3.0], 
          "fields": "my_vector_field", 
          "k": 10 
        } 
      ], 
      "search": "hello world", 
      "hybridSearch": { 
        "maxTextRecallSize": 100, 
        "countAndFacetMode": "countRetrievableResults" 
      } 
    }

두 번째 예제는 maxTextRecallSize를 5,000으로 증가시킵니다. 또한 큰 결과 집합에서 결과를 끌어오기 위해 상위, 건너뛰기 및 다음을 사용합니다. 이 경우 요청은 RRF 복합 결과 집합에 대한 텍스트 쿼리 기여로 위치 1,500에서 2,000까지의 BM25 순위 결과를 가져옵니다.

POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2026-08-01-preview

    { 
      "vectorQueries": [ 
        { 
          "kind": "vector", 
          "vector": [1.0, 2.0, 3.0], 
          "fields": "my_vector_field", 
          "k": 10 
        } 
      ], 
      "search": "hello world",
      "top": 500,
      "skip": 1500,
      "next": 500,
      "hybridSearch": { 
        "maxTextRecallSize": 5000, 
        "countAndFacetMode": "countRetrievableResults" 
      } 
    }

참조: hybridSearch | maxTextRecallSize | countAndFacetMode

하이브리드 쿼리의 예

이 섹션에는 하이브리드 쿼리 패턴을 보여 주는 여러 쿼리 예제가 있습니다.

예: 필터를 사용하는 하이브리드 검색

다음은 검색 인덱스의 비벡터 필드에 적용되는 filterable 필터를 추가하는 예제입니다.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2026-04-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "vectorQueries": [
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "k": 10
        }
    ],
    "search": "historic hotel walk to restaurants and shopping",
    "vectorFilterMode": "preFilter",
    "filter": "ParkingIncluded",
    "top": "10"
}

핵심 사항:

필터는 필터링 가능한 필드의 콘텐츠에 적용됩니다. 이 예제에서 ParkingIncluded 필드는 부울이며 인덱스 스키마에서는 filterable로 나타납니다.
하이브리드 쿼리에서는 쿼리 실행 전에 필터를 적용하여 쿼리 표면을 줄이거나 쿼리 실행 후에 결과를 트리밍할 수 있습니다. "preFilter" 가 기본값입니다. 사용하려면 postFilter 또는 strictPostFilter (미리 보기 기능)을, 이 예제와 같이 필터 처리 모드로 설정하십시오.
쿼리 결과를 사후 필터링하면 결과 수가 top-n보다 작을 수 있습니다.

참조: 필터 | vectorFilterMode

예: 벡터 하위 쿼리를 대상으로 하는 필터가 있는 하이브리드 검색(미리 보기)

최신 미리 보기 REST API를 사용하여 하이브리드 요청의 벡터 하위 쿼리만 대상으로 하는 보조 필터를 적용하여 검색 요청에 대한 전역 필터를 재정의할 수 있습니다.

이 기능은 필터가 벡터 검색 결과에만 영향을 주도록 하여 키워드 기반 검색 결과에 영향을 미치지 않도록 하여 세분화된 제어를 제공합니다.

대상 필터는 보안 트리밍 또는 지리 공간 검색에 사용되는 필터를 포함하여 전역 필터를 완전히 재정의합니다. 보안 트리밍과 같은 전역 필터가 필요한 경우 보안 및 기타 제약 조건이 일관되게 적용되도록 최상위 필터와 각 벡터 수준 필터에 이러한 필터를 명시적으로 포함해야 합니다.

대상 벡터 필터를 적용하려면 다음을 수행합니다.

최신 미리 보기 검색 문서 REST API 또는 기능을 제공하는 Azure SDK 베타 패키지를 사용합니다.
쿼리 요청을 수정하고 vectorQueries.filterOverride에 새 매개 변수 집합을 추가합니다.

다음은 필터 재정의를 추가하는 하이브리드 쿼리의 예입니다. 전역 필터 "Rating gt 3"은 런타임 중에 filterOverride로 바뀝니다.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2026-08-01-preview

{
    "vectorQueries": [
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true,
            "filterOverride": "Address/City eq 'Seattle'",
            "k": 10
        }
    ],
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelName, Description, Address/City, Rating",
    "filter": "Rating gt 3",
    "debug": "vector",
    "top": 10
}

예: 의미 체계 하이브리드 검색

인덱스 정의에 의미 체계 구성이 포함되어 있다고 가정하면 병합된 결과 집합에 대한 의미 체계 순위를 사용하여 벡터 검색 및 키워드 검색을 포함하는 쿼리를 작성할 수 있습니다. 필요에 따라 캡션과 답변을 추가할 수 있습니다.

벡터와 함께 의미 체계 순위를 사용할 때마다 k가 50으로 설정되어 있는지 확인하십시오. 의미 체계 순위는 최대 50개 일치 항목을 입력으로 사용합니다. 50 미만으로 지정하면 의미 순위 모델에 필요한 입력이 부족하게 됩니다.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2026-04-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "vectorQueries": [
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "k": 50
        }
    ],
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelName, Description, Tags",
    "queryType": "semantic",
    "semanticConfiguration": "my-semantic-config",
    "captions": "extractive",
    "answers": "extractive",
    "top": "50"
}

핵심 사항:

의미 체계 순위는 병합된 응답에서 최대 50개의 결과를 허용합니다.
"queryType" 및 "semanticConfiguration"이 필요합니다.
"캡션" 및 "답변"은 선택 사항입니다. 값은 결과의 축자 텍스트에서 추출됩니다. 응답은 결과에 쿼리에 대한 답변의 특징이 있는 콘텐츠가 포함된 경우에만 반환됩니다.

참조: queryType | semanticConfiguration | 캡션 | 답변

예: 필터를 사용하는 의미 체계 하이브리드 검색

이 예제에서는 ParkingIncluded 의미 체계 하이브리드 쿼리에 필터를 추가합니다.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2026-04-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "vectorQueries": [
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "k": 50
        }
    ],
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelName, Description, Tags",
    "queryType": "semantic",
    "semanticConfiguration": "my-semantic-config",
    "captions": "extractive",
    "answers": "extractive",
    "filter": "ParkingIncluded",
    "vectorFilterMode": "preFilter",
    "top": "50"
}

핵심 사항:

필터 모드는 의미 체계 순위에 사용할 수 있는 결과 수에 영향을 줄 수 있습니다. 의미 체계 순위에 최대 문서 수(50)를 지정하는 것이 가장 좋습니다. 프리필터 또는 포스트필터가 지나치게 엄격하면 시맨틱 순위 지정기가 활용할 수 있는 문서가 50개 미만으로 줄어들어, 시맨틱 순위 지정기에 충분한 입력을 제공하지 못할 수 있습니다.
preFilter 는 쿼리 실행 전에 적용됩니다. 미리 필터가 검색 영역을 100개의 문서로 줄이면 벡터 쿼리가 해당 100개 문서에 대한 필드를 통해 DescriptionVector 실행되어 k=50이 가장 일치하는 항목을 반환합니다. 이러한 50개의 일치하는 문서는 통합된 결과를 위해 RRF에 전달된 후, 의미 체계 랭커에 전달됩니다.
postFilter 는 쿼리 실행 후에 적용됩니다. k=50이 벡터 쿼리 쪽에서 50개의 일치 항목을 반환한 다음 50개의 일치 항목에 적용된 후 필터를 반환하는 경우 필터 조건을 충족하는 문서 수만큼 결과가 줄어듭니다. 따라서 의미 체계 순위에 전달할 문서가 50개 미만입니다. 의미 체계 순위를 사용하는 경우 이 점을 염두에 두어야 합니다. 의미 체계 순위는 입력으로 문서가 50개 있는 경우에 가장 적합합니다.
strictPostFilter (미리 보기)는 쿼리 실행 후 필터링되지 않은 상위k 결과에 적용됩니다. 항상 문서보다 작거나 같은 값을 반환합니다 k . 필터링되지 않은 k=50이 필터링되지 않은 50개의 결과를 반환하고 필터가 30개의 문서와 일치하는 경우 인덱스가 필터와 일치하는 문서가 30개 이상인 경우에도 결과 집합에 30개의 문서만 반환됩니다. 이 모드는 검색 회수가 가장 크게 감소하기 때문에 시맨틱 랭커와 함께 사용하는 것을 권장하지 않습니다.

쿼리 응답 구성

하이브리드 쿼리를 설정할 때 응답 구조를 생각해 보세요. 검색 엔진은 일치하는 문서의 순위를 지정하고 가장 관련성이 높은 결과를 반환합니다. 응답은 평면화된 행 집합입니다. 쿼리의 매개 변수는 각 행에 있는 필드와 응답에 있는 행 수를 결정합니다.

응답의 필드

검색 결과는 검색 인덱스의 retrievable 필드로 구성됩니다. 결과는 다음과 같습니다.

모든 retrievable 필드(REST API 기본값).
쿼리의 매개 변수에 select 명시적으로 나열된 필드입니다.

이 문서의 예제에서는 문을 사용하여 select 응답에서 텍스트(비벡터) 필드를 지정했습니다.

참고

벡터는 사람이 읽을 수 있는 텍스트로 리버스 엔지니어링되지 않으므로 응답에서 반환하지 마세요. 대신 검색 문서를 나타내는 비벡터 필드를 선택합니다. 예를 들어 쿼리가 "DescriptionVector" 필드를 대상으로 하는 경우 응답에 하나("설명")가 있는 경우 해당하는 텍스트 필드를 반환합니다.

결과 수

검색 조건이 약한 경우(예: null 쿼리의 경우 "search=*") 쿼리는 모든 문서 수와 일치할 수 있습니다. 바인딩되지 않은 결과를 반환하는 것은 거의 실용적이지 않으므로 전체 응답의 최대값을 지정해야 합니다.

"top": n 키워드 전용 쿼리에 대한 결과(벡터 없음)
"k": n 벡터 전용 쿼리에 대한 결과
"top": n "search" 매개 변수를 포함하는 하이브리드 쿼리(의미 체계 포함 또는 제외)에 대한 결과

둘 다 k와 top는 선택 사항입니다. 지정되지 않은 응답의 기본 결과 수는 50입니다. 기본값을 변경하거나 더 많은 결과를 페이지로 넘길 수 있도록 top 및 skip을 설정할 수 있습니다.

참고

2024-05-01-preview API에서 하이브리드 검색을 사용하는 경우 maxTextRecallSize를 사용하여 키워드 쿼리의 결과 수를 제어할 수 있습니다. 각 검색 하위 시스템(키워드 및 벡터)의 표현을 제어하기 위한 k 설정과 결합합니다.

시맨틱 랭커 결과

참고

시맨틱 랭커는 최대 50개의 결과를 포함할 수 있습니다.

2024-05-01-preview 이상에서 의미 체계 순위 매기기를 사용하는 경우, k와 maxTextRecallSize의 합계를 총 50 이상으로 설정하는 것이 가장 좋습니다. 그런 다음 매개 변수를 사용하여 사용자에게 top 반환된 결과를 제한할 수 있습니다.

2024-05-01-preview 이전 API 버전에서 의미 체계 순위 관리자를 사용하는 경우 다음 단계를 수행합니다.

키워드 전용 검색(벡터 없음)이 50으로 설정된 top 경우
하이브리드 검색의 설정 k을 50으로 설정하여 의미 체계 순위자가 최소한 50개의 결과를 얻도록 합니다.

순위

선택적인 의미 재정렬 포함 여부에 관계없이 하이브리드 쿼리를 위해 여러 집합이 만들어집니다. 결과의 순위는 상호 순위 Fusion(RRF)에 의해 계산됩니다.

이 섹션에서는 단일 벡터 검색과 상위 결과에 대한 간단한 하이브리드 검색 간의 응답을 비교합니다. 다른 순위 알고리즘, HNSW의 유사성 메트릭 및 RRF는 이 경우 크기가 다른 점수를 생성합니다. 이 동작은 의도적으로 수행됩니다. 유사성 일치가 높더라도 RRF 점수는 매우 낮게 나타날 수 있습니다. 낮은 점수는 RRF 알고리즘의 특징입니다. RRF를 사용하는 하이브리드 쿼리에서는 순수 벡터 검색과 달리 RRF 순위가 지정된 문서의 점수가 상대적으로 작기 때문에 순위가 지정된 문서의 더 많은 상호가 결과에 포함됩니다.

단일 벡터 검색: @search.score 코사인 유사성(기본 벡터 유사성 거리 함수)에 따라 정렬된 결과입니다.

{
    "@search.score": 0.8399121,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center.",
    "Category": "Luxury",
    "Address": {
    "City": "Arlington"
    }
}

하이브리드 검색: Reciprocal Rank Fusion을 사용하여 순위가 매겨진 하이브리드 결과

{
    "@search.score": 0.032786883413791656,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center.",
    "Category": "Luxury",
    "Address": {
    "City": "Arlington"
    }
}

하이브리드 쿼리 문제 해결

다음 표를 사용하여 하이브리드 쿼리의 일반적인 문제를 진단합니다.

문제	가능한 원인	해상도
빈 결과	벡터 필드 이름 불일치 또는 누락된 인덱스 데이터	`fields`가 인덱스 스키마의 벡터 필드와 일치하는지 `vectorQueries` 확인하세요. 문서에 벡터 데이터가 포함되어 있는지 확인합니다.
낮은 RRF 점수	일반적인 RRF 동작	RRF 점수는 본질적으로 유사성 점수보다 낮습니다. 점수가 0.03이어도 여전히 강한 일치를 나타낼 수 있습니다.
벡터 결과가 지배합니다.	텍스트 쿼리의 성능이 저하되었습니다.	BM25 결과를 더 많이 포함하도록 `maxTextRecallSize`를 증가시키거나 벡터 가중치를 조정합니다.
텍스트 결과가 지배합니다.	벡터 유사성이 너무 낮음	임베딩 품질을 확인합니다. 쿼리 벡터가 문서 벡터와 동일한 모델을 사용하는지 확인합니다.
의미 체계 순위는 더 적은 결과를 반환합니다.	입력 문서가 부족합니다.	의미 체계 순위를 사용하는 경우 50개 이상으로 설정합니다 `k` . 필터가 너무 제한적이지 않은지 확인합니다.
필터가 벡터에 적용되지 않음	전역 필터만 사용	벡터별 필터링의 경우 벡터 쿼리(미리 보기)에서 사용합니다 `filterOverride` .
결과의 예기치 않은 필드	`select` 매개 변수가 없습니다.	반환할 필드를 지정하려면 추가 `select` 합니다. 가독성을 위해 벡터 필드를 제외합니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-08-06

Azure AI 검색에서 하이브리드 쿼리를 만들기

필수 구성 요소

API, 도구 및 실행 가능한 패턴 선택

실행 가능한 하이브리드 패턴

과부하된 쿼리가 제한되는 이유

스케일 아웃하기 전에 순서 조정

하이브리드 쿼리 설정

maxTextRecallSize 및 countAndFacetMode 설정하기(미리 보기)

하이브리드 쿼리의 예

예: 필터를 사용하는 하이브리드 검색

예: 벡터 하위 쿼리를 대상으로 하는 필터가 있는 하이브리드 검색(미리 보기)

예: 의미 체계 하이브리드 검색

예: 필터를 사용하는 의미 체계 하이브리드 검색

쿼리 응답 구성

응답의 필드

결과 수

시맨틱 랭커 결과

순위

하이브리드 쿼리 문제 해결

관련 콘텐츠

피드백

추가 리소스