자동 완성(Azure AI Search REST API)

아티클
03/05/2024

자동 완성 API는 보조 쿼리에 사용하기 위해 검색 인덱스의 기존 용어를 사용하여 부분적으로 형식화된 쿼리 입력을 완료합니다. 예를 들어 쿼리 입력이 인 경우 자동 완성 API는 "medic"해당 용어가 인덱스에 있는 경우 , "medicaid""medicine" 를 반환"medicare"합니다. 내부적으로 검색 엔진은 Suggester 가 구성된 필드에서 일치하는 용어를 찾습니다.

서비스 요청에는 HTTPS를 사용해야 합니다. 자동 완성 요청은 GET 또는 POST 메서드를 사용하여 생성할 수 있습니다.

GET https://[service name].search.windows.net/indexes/[index name]/docs/autocomplete?[query parameters]
  Content-Type: application/json   
  api-key: [admin or query key]

POST https://[service name].search.windows.net/indexes/[index name]/docs/autocomplete?api-version=[api-version]
  Content-Type: application/json   
  api-key: [admin or query key]

GET을 사용하여 호출하면 요청 URL의 길이가 8KB를 초과할 수 없습니다. 이 길이는 일반적으로 대부분의 애플리케이션에 충분합니다. 그러나 일부 애플리케이션은 특히 OData 필터 식을 사용하는 경우 매우 큰 쿼리를 생성합니다. 이러한 애플리케이션의 경우 HTTP POST는 GET보다 더 큰 필터를 허용하므로 더 나은 선택입니다.

POST를 사용하면 필터의 절 수는 제한되지만 POST의 요청 크기 제한이 약 16MB이므로 원시 필터 문자열의 크기는 제한되지 않습니다. POST 요청 크기 제한이 매우 크더라도 필터 식은 임의로 복잡할 수 없습니다. 필터 복잡성 제한 사항에 대한 자세한 내용은 Azure AI Search용 OData 식 구문을 참조하세요.

URI 매개 변수

매개 변수	Description
[서비스 이름]	필수 사항입니다. 검색 서비스의 고유한 사용자 정의 이름으로 설정합니다.
[인덱스 이름]/docs	필수 사항입니다. 명명된 인덱스의 문서 컬렉션을 지정합니다.
api-version	필수 사항입니다. 지원되는 버전 목록은 API 버전을 참조하세요. 쿼리의 경우 api-version은 항상 GET 및 POST 모두에 대한 URI 매개 변수로 지정됩니다.

URL 인코딩 권장 사항

GET REST API를 직접 호출할 때 특정 쿼리 매개 변수를 URL로 인코딩 해야 합니다. 자동 완성의 경우 다음 쿼리 매개 변수에 URL 인코딩이 필요할 수 있습니다.

search
$filter
highlightPreTag
highlightPostTag

URL 인코딩은 개별 매개 변수에만 권장됩니다. 실수로 ? 뒤에 있는 전체 쿼리 문자열을 URL로 인코딩한 경우 요청이 중단됩니다.

또한 URL 인코딩은 GET을 사용하여 REST API를 직접 호출할 때만 필요합니다. POST를 사용하거나 인코딩을 처리하는 Azure AI Search .NET 클라이언트 라이브러리를 사용하는 경우 URL 인코딩이 필요하지 않습니다.

요청 헤더

다음 표에서는 필수 요청 헤더와 선택적 요청 헤더에 대해 설명합니다.

필드 Description

콘텐츠 형식 필수 사항입니다. application/json

api-key Azure 역할을 사용하고 요청에 전달자 토큰이 제공된 경우 선택 사항이며, 그렇지 않으면 키가 필요합니다. 컬렉션에 대한 쿼리 요청은 docs admin-key 또는 query-key를 로 api-key지정할 수 있습니다. 쿼리 키는 인덱스 문서 컬렉션에서 읽기 전용 작업에 사용됩니다. 자세한 내용은 키 인증을 사용하여 Azure AI Search에 연결을 참조하세요.

필드	Description
콘텐츠 형식	필수 사항입니다. `application/json`
api-key	Azure 역할을 사용하고 요청에 전달자 토큰이 제공된 경우 선택 사항이며, 그렇지 않으면 키가 필요합니다. 컬렉션에 대한 쿼리 요청은 `docs` admin-key 또는 query-key를 로 `api-key`지정할 수 있습니다. 쿼리 키는 인덱스 문서 컬렉션에서 읽기 전용 작업에 사용됩니다. 자세한 내용은 키 인증을 사용하여 Azure AI Search에 연결을 참조하세요.

요청 본문

GET의 경우: 없음.

POST의 경우:

{  
  "autocompleteMode": "oneTerm" (default) | "twoTerms" | "oneTermWithContext",
  "filter": "odata_filter_expression",
  "fuzzy": true | false (default),  
  "highlightPreTag": "pre_tag",  
  "highlightPostTag": "post_tag",  
  "minimumCoverage": # (% of index that must be covered to declare query successful; default 80),
  "search": "partial_search_input",  
  "searchFields": "field_name_1, field_name_2, ...",
  "suggesterName": "suggester_name",  
  "top": # (default 5)  
}

쿼리 매개 변수

쿼리는 GET을 사용하여 호출할 때 URL에 대한 여러 매개 변수를 허용하고 POST를 사용하여 호출할 때 요청 본문의 JSON 속성으로 허용합니다. 일부 매개 변수에 대한 구문은 GET 및 POST 간에 약간 다릅니다. 이러한 차이점은 아래와 같이 설명됩니다.

Name	형식	Description
api-version	문자열	필수 사항입니다. 요청에 사용되는 REST API의 버전입니다. 지원되는 버전 목록은 API 버전 관리를 참조하세요. 이 작업의 경우 api-version은 GET 또는 POST를 사용하여 자동 완성 을 호출하는지 여부에 관계없이 URI 매개 변수로 지정됩니다.
autocompleteMode	문자열	(선택 사항) 기본값은 oneTerm입니다. 유효한 값은 oneTerm, twoTerms, oneTermWithContext입니다. oneTerm은 단일 용어를 반환합니다. 쿼리에 두 개의 용어가 있는 경우 마지막 용어만 완료됩니다. 예를 들어 가 지정된 경우 `"washington medic"`응답은 , , `"medicare""medicine"`등의 단일 용어 `"medicaid"`중 하나일 수 있습니다. twoTerms는 인덱스의 2개 용어 구와 일치합니다. 예를 들어 가 지정된 경우 `"medic"`응답은 또는 일 `"medical assistant"`수 있습니다`"medicare coverage"`. 대부분의 경우 일치하는 2개 용어 구에 `"medicare"` 기본 설정이 지정되기 때문에 단일 용어 또는 `"medical"` 가 반환되지 않습니다. oneTermWithContext는 두 개 이상의 용어를 사용하여 쿼리에서 마지막 용어를 완료합니다. 여기서 마지막 두 용어는 인덱스에 있는 구입니다. 예를 들어 가 지정된 경우 `"washington medic"`응답은 , 일 `"washington medicaid""washington medical"`수 있습니다.
$filter	문자열	(선택 사항) 완성된 용어 제안을 생성하는 것으로 간주되는 문서를 필터링하는 표준 OData 구문의 구조화된 검색 식입니다. 필터 식 "search.ismatch" 및 "search.ismatchscoring*"은 자동 완성 API에서 지원되지 않습니다. 필터에 필터링 가능한 필드만 사용할 수 있습니다. POST를 사용하여 호출하면 이 매개 변수는 $filter 대신 필터로 명명됩니다. Azure AI Search에서 지원하는 OData 식 문법의 하위 집합에 대한 자세한 내용은 Azure AI Search용 OData 식 구문을 참조하세요.
유사	boolean	선택 사항입니다. 기본값은 false입니다. true로 설정하면 이 API는 검색 텍스트 ⁽¹⁾에 대체되거나 누락된 문자가 있더라도 제안을 찾습니다. 이는 일부 시나리오에서 더 나은 환경을 제공하지만 유사 항목 제안 검색이 느리고 더 많은 리소스를 사용함에 따라 성능 비용이 발생합니다.
highlightPostTag	문자열	(선택 사항) 기본값은 빈 문자열입니다. 강조 표시된 용어에 추가되는 문자열 태그입니다. highlightPreTag를 사용하여 설정해야 합니다. URL의 예약된 문자는 %로 인코딩해야 합니다. 예를 들어 # 대신 %23을 사용해야 합니다. GET을 사용하여 호출할 때 URL의 예약 문자는 백분율로 인코딩되어야 합니다(예: #대신 %23).
highlightPreTag	문자열	(선택 사항) 기본값은 빈 문자열입니다. 강조 표시된 용어 앞에 추가되는 문자열 태그입니다. highlightPostTag를 사용하여 설정해야 합니다. GET을 사용하여 호출할 때 URL의 예약 문자는 백분율로 인코딩되어야 합니다(예: #대신 %23).
minimumCoverage	integer	선택 사항입니다. 기본값은 80입니다. 쿼리를 성공으로 보고하기 전에 쿼리를 서비스하는 데 사용할 수 있어야 하는 인덱스의 백분율을 나타내는 0에서 100 사이의 숫자입니다. 기본값은 전체 검사에 대한 속도와 효율성에 대한 편견을 반영합니다. 범위를 줄이면 쿼리 확장이 제한되므로 결과가 더 빠르게 돌아올 수 있습니다. 또한 서비스 상태 문제 또는 인덱스 유지 관리로 인해 하나의 분할된 데이터베이스가 응답 속도가 느리거나 사용할 수 없는 경우에도 부분 인덱스 가용성에서 쿼리가 성공할 수 있습니다. minimumCoverage 값이 무엇이든 간에 인덱스의 백분율을 사용할 수 있어야 하며 자동 완성은 HTTP 상태 코드 503을 반환해야 합니다. 자동 완성이 minimumCoverage 수준에서 성공하면 HTTP 200을 반환하고 쿼리를 서비스할 때 사용할 수 있었던 인덱스의 백분율을 나타내는 값을 응답에 포함합니다 @search.coverage . 503 오류가 발생하는 경우 이 값을 낮추면 도움이 될 수 있습니다. 그렇지 않으면 응답에서 일치하는 항목이 부족한 경우 값을 높이는 것이 좋습니다.
search	문자열	필수 사항입니다. 검색할 텍스트입니다. 완료할 검색 텍스트입니다. 최소 1자가 되어야 하며 100자를 넘지 않아야 합니다. 연산자, 쿼리 구문 또는 따옴표 붙은 구를 포함할 수 없습니다.
searchFields	문자열	(선택 사항) 지정된 검색 텍스트를 검색하기 위한 쉼표로 구분된 필드 이름 목록입니다. 대상 필드는 인덱 스 내 제안기 정의에 나열되어야 합니다.
suggesterName	문자열	필수 사항입니다. 인덱스 정의의 일부인 Suggesters 컬렉션에 지정된 제안기의 이름입니다. 제안기는 제안된 쿼리 용어를 검사할 필드를 결정합니다.
$top	integer	선택 사항입니다. 기본값은 5입니다. 검색할 자동 완성 제안 수입니다. 값은 1~100 사이의 숫자여야 합니다. POST를 사용하여 호출할 때 이 매개 변수의 이름은 $top 대신 top으로 지정됩니다.

(1) 자동 완성의 유사 항목 제한 사항:

먼저 편집 거리는 검색의 유사 항목 매개 변수와 달리 토큰당 하나의 문자 차이로 제한됩니다. 편집 거리를 한 문자로 제한하면 모든 후보 일치 항목이 발견되지는 않지만 허용 가능한 수준의 성능을 보장하기 위해 상한이 필요합니다.

둘째, 유사 항목 단계는 부분 토큰 확장 후에 발생하며 동일한 인덱스 분할된 데이터베이스의 용어만 유사 항목 일치로 간주됩니다. 이 제약 조건은 모든 분할된 데이터베이스에 대한 유사 항목 일치 집계를 제거하여 자동 완성 API의 성능을 향상합니다. 이 제약 조건은 인덱스에 더 많은 용어가 추가되어 각 분할된 데이터베이스에 대해 유사한 용어 분포가 발생하므로 눈에 띄지 않습니다. 용어가 균등하게 분산되기 때문에 분할된 데이터베이스 내의 유사 항목 일치는 전체 인덱스에서 유사 항목 일치의 근사치입니다. 그러나 인덱스에 테스트 또는 프로토타입 인덱스와 같은 용어가 적으면 결과가 열등할 수 있으므로 분할된 데이터베이스 전체에서 고르지 않은 표현이 발생할 수 있습니다. 인덱스를 분할된 데이터베이스로 나누는 방법에 대한 자세한 내용은 파티션 및 복제본(replica) 조합을 참조하세요.

응답

상태 코드: 성공적인 응답을 위해 "200 OK"가 반환됩니다.

응답 페이로드에는 두 가지 속성이 있습니다.

속성	Description
"text"	완성된 용어 또는 구
"queryPlusText"	초기 쿼리 입력과 완성된 용어 또는 구

{  
  "@search.coverage": # (if minimumCoverage was provided in the query),  
  "value": [
    {
      "text": "...",
      "queryPlusText": "..."
    },
    ...  
  ]
}

예제

예제 1: 부분 검색 입력 'washington medic' 이 기본 모드(oneTerm)인 세 가지 자동 완성 제안을 검색합니다.

GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&api-version=2020-06-30

POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{  
  "search": "washington medic",
  "filter": "search.in(roleId, 'admin,manager')",
  "top": 3,
  "suggesterName": "sg"  
}

응답:

{    
  "value": [
    {
      "text": "medicaid",
      "queryPlusText": "washington medicaid"
    },
    {
      "text": "medicare",
      "queryPlusText": "washington medicare"
    },
    {
      "text": "medicine",
      "queryPlusText": "washington medicine"
    }
  ]
}

예제 2: 부분 검색 입력 'washington medic' 이 및 autocompleteMode=twoTerms인 세 가지 자동 완성 제안을 검색합니다.

GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&autocompleteMode=twoTerms&api-version=2020-06-30

POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{  
  "search": "washington medic",  
  "autocompleteMode": "twoTerms",
  "filter": "planDuration ge 1",
  "top": 3,  
  "suggesterName": "sg"  
}

응답:

{    
  "value": [
    {
      "text": "medicaid insurance",
      "queryPlusText": "washington medicaid insurance"
    },
    {
      "text": "medicare plan",
      "queryPlusText": "washington medicare plan"
    },
    {
      "text": "medicine book",
      "queryPlusText": "washington medicine book"
    }
  ]
}

자동 완성 작업에 suggesterName 이 필요합니다.