클라이언트 앱에 자동 완성 및 검색 제안 추가
입력과 동시에 검색은 쿼리 생산성을 개선하기 위한 일반적인 기술입니다. Azure AI Search에서 이 환경은 부분 입력을 기반으로 용어 또는 구를 완료하는 자동 완성을 통해 지원됩니다(예: 마이크로칩, 현미경, Microsoft 및 기타 마이크로 일치를 사용하여 마이크로 일치 완료). 두 번째 사용자 환경은 일치하는 문서의 짧은 목록을 생성하는 제안입니다(예: 해당 책에 대한 세부 정보 페이지에 연결할 수 있도록 ID가 있는 책 제목 반환). 자동 완성과 제안 모두 인덱스의 일치 항목에 기반합니다. 서비스는 0개의 결과를 반환하는 자동 완성된 쿼리 또는 제안을 제공하지 않습니다.
Azure AI 검색에서 이러한 환경을 구현하려면 다음을 수행합니다.
- 인덱스 스키마에
suggester를 추가합니다. - 요청에서 자동 완성 API 또는 제안 API를 호출하는 쿼리를 빌드합니다.
- 클라이언트 앱에서 입력과 동시에 검색 상호 작용을 처리하는 UI 컨트롤. 기존 JavaScript 라이브러리를 이 용도로 사용하는 것이 좋습니다.
Azure AI 검색에서는 자동 완성된 쿼리와 제안 결과가 쿼리 인덱스, 제안기에 등록한 선택된 필드에서 쿼리됩니다. 제안기는 인덱스의 일부이며, 쿼리를 완료하거나 결과를 제안하거나 둘 다 수행하는 내용을 제공할 필드를 지정합니다. 인덱스가 만들어지고 로드되면 부분 쿼리에서 일치에 사용되는 접두사를 저장하는 제안기 데이터 구조가 내부에서 만들어집니다. 제안의 경우 고유하거나 적어도 반복적이지 않은 적절한 필드를 선택하는 것이 환경에 필수적입니다. 자세한 내용은 제안기 구성을 참조 하세요.
이 문서의 나머지 부분에서는 쿼리와 클라이언트 코드에 대해 집중적으로 설명합니다. 핵심 사항을 설명하기 위해 JavaScript와 C#을 사용합니다. 각 작업을 간결하게 표시하기 위해 REST API 예제가 사용됩니다. 엔드투엔드 코드 샘플은 .NET을 사용하여 웹 사이트에 검색 추가를 참조하세요.
요청 설정
요청 요소에는 입력과 동시에 검색 API, 부분 쿼리, 제안기 중 하나가 포함됩니다. 다음 스크립트는 자동 완성 REST API를 예제로 사용하여 요청의 구성 요소를 보여 줍니다.
POST /indexes/myxboxgames/docs/autocomplete?search&api-version=2024-07-01
{
"search": "minecraf",
"suggesterName": "sg"
}
매개 변수는 suggesterName 용어 또는 제안을 완료하는 데 사용되는 제안기 인식 필드를 제공합니다. 특히 제안의 경우 필드 목록은 일치하는 결과 중에서 명확한 선택을 제공하는 제안으로 구성되어야 합니다. 컴퓨터 게임을 판매하는 사이트에서 이 필드는 게임 타이틀이 될 수 있습니다.
매개 변수는 search jQuery 자동 완성 컨트롤을 통해 문자가 쿼리 요청에 공급되는 부분 쿼리를 제공합니다. 이전 예제 에서 minecraf 는 컨트롤이 전달할 수 있는 내용에 대한 정적 그림입니다.
API는 부분 쿼리에 최소 길이 요구 사항을 적용하지 않습니다. 문자 하나여도 됩니다. 그러나 jQuery 자동 완성은 최소 길이를 제공합니다. 최소 2~3자가 일반적입니다.
일치 항목은 입력 문자열에서 용어의 시작 부분에 있습니다. 빠른 갈색 여우를 감안할 때, 자동 완성과 제안은 모두 빠른, 갈색 또는 여우의 부분 버전에서 일치하지만 rown 또는 ox와 같은 부분 접두사 용어에는 일치하지 않습니다. 또한 각 일치 항목은 다운스트림 확장의 범위를 설정합니다. 빠른 br의 부분 쿼리는 빠른 갈색 또는 빠른 빵에 일치하지만, 빠른 * 앞에하지 않는 한 그 자체로 갈색이나 빵은 일치하지 않을 것입니다.
입력과 동시에 검색을 위한 API
REST 및 .NET SDK 참조 페이지에 대한 다음 링크를 따라가세요.
응답 구성
자동 완성 및 제안에 대한 응답은 패턴을 통해 예상할 수 있습니다. 자동 완성은 용어 목록을 반환하고, 제안은 용어 외에도 문서를 가져올 수 있도록 문서 ID도 반환합니다(특정 문서의 상세 페이지를 가져오려면 문서 조회 API를 사용하세요).
응답은 요청에서의 매개 변수에 따라 다음과 같이 구성됩니다.
자동 완성의 경우 autocompleteMode 를 설정하여 텍스트 완성이 하나 또는 두 개의 용어로 수행되는지 여부를 결정합니다.
제안의 경우 이름 및 설명과 같이 고유하거나 차별화된 값이 포함된 필드를 반환하도록 $select 설정합니다. 중복 값(예: 범주 또는 도시)을 포함하는 필드는 사용하지 않는 것이 좋습니다.
다음 매개 변수는 자동 완성과 제안 모두에 적용되지만 특히 제안에 여러 필드가 포함된 경우 제안에 더 적합합니다.
| 매개 변수 | 사용 |
|---|---|
| searchFields | 쿼리를 특정 필드로 제한합니다. |
| $filter | 결과 집합에서 일치 조건을 적용합니다($filter=Category eq 'ActionAdventure'). |
| $top | 결과를 특정 숫자로 제한합니다($top=5). |
사용자 상호 작용 코드 추가
쿼리 용어를 자동으로 채우거나 일치하는 링크 목록을 드롭다운하려면 사용자 상호 작용 코드(일반적으로 JavaScript)가 필요합니다. 이 코드는 Azure Search Cognitive 인덱스에 대한 자동 완성 또는 제안 쿼리와 같은 외부 원본의 요청을 사용할 수 있습니다.
이 코드를 고유하게 작성할 수도 있지만 다음 중 하나와 같은 기존 JavaScript 라이브러리의 함수를 사용하는 것이 쉽습니다.
제안 코드 조각에 자동 완성 위젯(jQuery UI) 이 나타납니다. 검색 상자를 만든 다음 자동 완성 위젯을 사용하는 JavaScript 함수에서 참조할 수 있습니다. 위젯의 속성은 원본(자동 완성 또는 제안 함수), 작업을 수행하기 전의 최소 입력 문자 길이, 위치 지정을 설정합니다.
XDSoft 자동 완성 플러그 인 이 자동 완성 코드 조각에 나타납니다.
웹 사이트에 검색 추가 자습서 및 코드 샘플에 제안이 표시됩니다.
클라이언트에서 이러한 라이브러리를 사용하여 제안 및 자동 완성을 모두 지원하는 검색 상자를 만듭니다. 검색 상자에 수집된 입력은 검색 서비스에서의 제안 및 자동 완성 작업에 쌍으로 연결할 수 있습니다.
제안
이 섹션에서는 검색 상자 정의부터 시작하여 제안된 결과를 구현하는 과정을 안내합니다. 또한 이 문서에서 참조하는 첫 번째 JavaScript 자동 완성 라이브러리를 호출하는 스크립트를 작성하는 방법을 보여 줍니다.
검색 상자 만들기
jQuery UI 자동 완성 라이브러리 및 C#의 MVC 프로젝트가 있다면 Index. cshtml 파일에서 JavaScript를 사용하여 검색 상자를 정의할 수 있습니다. 이 라이브러리는 제안을 검색하는 MVC 컨트롤러를 비동기 방식으로 호출하여 입력과 동시에 검색 상호 작용을 검색 상자에 추가합니다.
\Views\Home 폴더 내의 Index.cshtml에서 검색 상자를 만드는 줄은 다음과 같습니다.
<input class="searchBox" type="text" id="searchbox1" placeholder="search">
이 예제는 스타일 지정에 대한 클래스, JavaScript에서 참조할 ID 및 자리 표시자 텍스트가 있는 간단한 입력 텍스트 상자입니다.
동일한 파일 내에서 검색 상자를 참조하는 JavaScript를 포함합니다. 다음 함수는 부분 용어 입력을 기반으로 제안된 일치 문서를 요청하는 제안 API를 호출합니다.
$(function () {
$("#searchbox1").autocomplete({
source: "/home/suggest?highlights=false&fuzzy=false&",
minLength: 3,
position: {
my: "left top",
at: "left-23 bottom+10"
}
});
});
source는 검색 상자 아래에 표시할 항목 목록을 가져올 위치를 jQuery UI Autocomplete 함수에 알려 줍니다. 이 프로젝트는 MVC 프로젝트이므로 쿼리 제안을 반환하는 논리가 포함된 HomeController.cs 함수를 호출 Suggest 합니다. 또한 이 함수는 강조 표시, 유사 일치, 용어를 제어하는 몇 가지 매개 변수도 전달합니다. 자동 완성 JavaScript API는 용어 매개 변수를 추가합니다.
minLength: 3 검색 상자에 세 개 이상의 문자가 있는 경우에만 권장 사항이 표시됩니다.
유사 일치 사용
유사 항목 검색을 사용하면 사용자가 검색 상자에 단어 철자를 틀리게 입력하더라도 가까운 일치를 기준으로 결과를 가져올 수 있습니다. 편집 거리는 1입니다. 즉, 사용자 입력과 일치 사이에는 최대한 문자의 불일치가 있을 수 있습니다.
source: "/home/suggest?highlights=false&fuzzy=true&",
강조 표시 사용
강조 표시는 결과에서 입력과 일치하는 문자에 글꼴 스타일을 적용합니다. 예를 들어 부분 입력이 마이크로인 경우 결과는 마이크로 소프트, 마이크로범위 등으로 표시됩니다. 강조 표시는 함수와 HighlightPreTag 인라인으로 정의된 매개 변수 및 HighlightPostTag 매개 변수를 기반으로 합니다 Suggest .
source: "/home/suggest?highlights=true&fuzzy=true&",
Suggest 함수
C# 및 MVC 애플리케이션을 사용하는 경우 Controllers 디렉터리의 HomeController.cs 파일에서 제안된 결과에 대한 클래스를 만들 수 있습니다. .NET Suggest 에서 함수는 SuggestAsync 메서드를 기반으로 합니다. .NET SDK에 대한 자세한 내용은 .NET 애플리케이션에서 Azure AI 검색을 사용하는 방법을 참조하세요.
InitSearch 메서드는 Azure AI 검색 서비스에 인증된 HTTP 인덱스 클라이언트를 만듭니다. SuggestOptions 클래스의 속성은 결과에서 검색되고 반환되는 필드, 일치 항목 수, 유사 일치가 사용되는지 여부를 결정합니다.
자동 완성의 경우 유사 일치는 1 편집 거리(생략되거나 잘못된 문자 하나)로 제한됩니다. 자동 완성 쿼리의 유사 일치는 인덱스 크기 및 분할된 방식에 따라 예기치 않은 결과를 생성하는 경우도 있습니다.
public async Task<ActionResult> SuggestAsync(bool highlights, bool fuzzy, string term)
{
InitSearch();
var options = new SuggestOptions()
{
UseFuzzyMatching = fuzzy,
Size = 8,
};
if (highlights)
{
options.HighlightPreTag = "<b>";
options.HighlightPostTag = "</b>";
}
// Only one suggester can be specified per index.
// The suggester for the Hotels index enables autocomplete/suggestions on the HotelName field only.
// During indexing, HotelNames are indexed in patterns that support autocomplete and suggested results.
var suggestResult = await _searchClient.SuggestAsync<Hotel>(term, "sg", options).ConfigureAwait(false);
// Convert the suggest query results to a list that can be displayed in the client.
List<string> suggestions = suggestResult.Value.Results.Select(x => x.Text).ToList();
// Return the list of suggestions.
return new JsonResult(suggestions);
}
이 함수는 SuggestAsync 검색 용어 입력 외에도 적중 강조 표시가 반환되는지 또는 유사 항목 일치가 사용되는지 여부를 결정하는 두 개의 매개 변수를 사용합니다. 제안된 결과에는 최대 8개의 일치 항목이 포함될 수 있습니다. 이 메서드는 SuggestOptions 개체를 만든 다음 Suggest API로 전달합니다. 그러면 클라이언트에 표시될 수 있게 결과가 JSON으로 변환됩니다.
자동 완성
지금까지 검색 UX 코드는 제안에 중점을 두었습니다. 다음 코드 블록에서는 XDSoft jQuery UI Autocomplete 함수를 사용하여 Azure AI 검색 자동 완성 요청을 전달하는 자동 완성을 보여 줍니다. 제안과 마찬가지로 C# 애플리케이션에서는 사용자 상호 작용을 지원하는 코드가 index.cshtml에 들어갑니다.
$(function () {
// using modified jQuery Autocomplete plugin v1.2.8 https://xdsoft.net/jqplugins/autocomplete/
// $.autocomplete -> $.autocompleteInline
$("#searchbox1").autocompleteInline({
appendMethod: "replace",
source: [
function (text, add) {
if (!text) {
return;
}
$.getJSON("/home/autocomplete?term=" + text, function (data) {
if (data && data.length > 0) {
currentSuggestion2 = data[0];
add(data);
}
});
}
]
});
// complete on TAB and clear on ESC
$("#searchbox1").keydown(function (evt) {
if (evt.keyCode === 9 /* TAB */ && currentSuggestion2) {
$("#searchbox1").val(currentSuggestion2);
return false;
} else if (evt.keyCode === 27 /* ESC */) {
currentSuggestion2 = "";
$("#searchbox1").val("");
}
});
});
Autocomplete 함수
자동 완성은 AutocompleteAsync 메서드를 기반으로 합니다. 제안과 마찬가지로 이 코드 블록은 HomeController.cs 파일에 들어갑니다.
public async Task<ActionResult> AutoCompleteAsync(string term)
{
InitSearch();
// Setup the autocomplete parameters.
var ap = new AutocompleteOptions()
{
Mode = AutocompleteMode.OneTermWithContext,
Size = 6
};
var autocompleteResult = await _searchClient.AutocompleteAsync(term, "sg", ap).ConfigureAwait(false);
// Convert the autocompleteResult results to a list that can be displayed in the client.
List<string> autocomplete = autocompleteResult.Value.Results.Select(x => x.Text).ToList();
return new JsonResult(autocomplete);
}
Autocomplete 함수는 검색 용어 입력을 사용합니다. 이 메서드는 AutoCompleteParameters 개체를 만듭니다. 그러면 클라이언트에 표시될 수 있게 결과가 JSON으로 변환됩니다.
다음 단계
다음 자습서에서는 유형별 검색 환경을 보여 줍니다.