Automatické dokončování (rozhraní REST API služby Azure AI Search)

Článek
02/28/2024

Rozhraní API pro automatické dokončování dokončí částečně zadaný vstup dotazu pomocí existujících termínů v indexu vyhledávání pro použití v sekundárním dotazu. Pokud je "medic"například vstup dotazu , vrátí rozhraní API "medicare"automatického dokončování , "medicaid""medicine" , pokud jsou tyto termíny v indexu. Vyhledávací web interně hledá odpovídající termíny v polích, která mají nakonfigurovaný modul pro návrhy .

Pro žádosti o služby se vyžaduje protokol HTTPS. Požadavek automatického dokončování lze vytvořit pomocí metod GET nebo 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]

Při volání pomocí get nesmí délka adresy URL požadavku překročit 8 kB. Tato délka je obvykle dostatečná pro většinu aplikací. Některé aplikace ale vytvářejí velmi rozsáhlé dotazy, konkrétně když se používají výrazy filtru OData. Pro tyto aplikace je http POST lepší volbou, protože umožňuje větší filtry než GET.

U funkce POST je limitačním faktorem počet klauzulí ve filtru, nikoli velikost nezpracovaného řetězce filtru, protože limit velikosti požadavku pro post je přibližně 16 MB. I když je limit velikosti požadavku POST velmi velký, výrazy filtru nemůžou být libovolně složité. Další informace o omezeních složitosti filtru najdete v tématu Syntaxe výrazů OData pro Azure AI Search.

Parametry identifikátoru URI

Parametr	Popis
[název služby]	Povinná hodnota. Nastavte ho na jedinečný, uživatelem definovaný název vaší vyhledávací služby.
[název indexu]/docs	Povinná hodnota. Určuje kolekci dokumentů pojmenovaného indexu.
verze-api	Povinná hodnota. Seznam podporovaných verzí najdete v tématu Verze rozhraní API . U dotazů se api-version vždy zadává jako parametr identifikátoru URI pro get i POST.

Doporučení ke kódování adres URL

Při přímém volání rozhraní GET REST API nezapomeňte zakódovat konkrétní parametry dotazu pomocí adresy URL. Pro automatické dokončování může být kódování adresy URL nezbytné pro následující parametry dotazu:

search
$filter
highlightPreTag
highlightPostTag

Kódování adresy URL se doporučuje pouze pro jednotlivé parametry. Pokud neúmyslně zakódujete celý řetězec dotazu pomocí adresy URL (vše za ?), požadavky se přeruší.

Kódování adresy URL je také nutné pouze při přímém volání rozhraní REST API pomocí get. Při použití post nebo klientské knihovny .NET služby Azure AI Search, která zpracovává kódování za vás, není potřeba žádné kódování adresy URL.

Hlavičky požadavku

Následující tabulka popisuje požadovanou a volitelnou hlavičku požadavku.

Pole Description

Typ obsahu Povinná hodnota. Nastavte tuto možnost na application/json

klíč rozhraní API Volitelné, pokud používáte role Azure a v požadavku je k dispozici nosný token, jinak se vyžaduje klíč. Požadavky dotazů na kolekci docs můžou jako api-keyzadat buď klíč správce, nebo klíč dotazu. Klíč dotazu se používá pro operace jen pro čtení v kolekci dokumentů indexu. Podrobnosti najdete v tématu Připojení ke službě Azure AI Search pomocí ověřování pomocí klíče .

Pole	Description
Typ obsahu	Povinná hodnota. Nastavte tuto možnost na `application/json`
klíč rozhraní API	Volitelné, pokud používáte role Azure a v požadavku je k dispozici nosný token, jinak se vyžaduje klíč. Požadavky dotazů na kolekci `docs` můžou jako `api-key`zadat buď klíč správce, nebo klíč dotazu. Klíč dotazu se používá pro operace jen pro čtení v kolekci dokumentů indexu. Podrobnosti najdete v tématu Připojení ke službě Azure AI Search pomocí ověřování pomocí klíče .

Text požadavku

Pro GET: Žádné.

Pro 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)  
}

Parametry dotazů

Dotaz při volání pomocí get přijímá několik parametrů na adrese URL a jako vlastnosti JSON v textu požadavku při volání pomocí POST. Syntaxe některých parametrů se mezi get a POST mírně liší. Tyto rozdíly jsou uvedeny jako použitelné níže.

Název	Typ	Description
verze-api	řetězec	Povinná hodnota. Verze rozhraní REST API, která se používá pro požadavek. Seznam podporovaných verzí najdete v tématu Správa verzí rozhraní API. Pro tuto operaci je api-version určena jako parametr identifikátoru URI bez ohledu na to, jestli voláte automatické dokončování pomocí get nebo POST.
Autocompletemode	řetězec	Nepovinný parametr. Výchozí hodnota je oneTerm. Platné hodnoty jsou oneTerm, twoTerms, oneTermWithContext. funkce oneTerm vrátí jeden termín. Pokud dotaz obsahuje dva termíny, dokončí se jenom poslední termín. Například v případě `"washington medic"`odpovědi může být některý z těchto jednotlivých termínů: `"medicaid"`, `"medicare"`, . `"medicine"` twoTerms se shoduje se dvěma frázemi v indexu. Například v případě `"medic"`, může být `"medicare coverage"`odpověď , nebo `"medical assistant"`. V mnoha případech by se jedno termíny `"medicare"` nebo `"medical"` nevrátily, protože se dává přednost dvěma frázím, které odpovídají. OneTermWithContext dokončí poslední termín v dotazu se dvěma nebo více termíny, kde poslední dva termíny jsou fráze, která existuje v indexu. Například v případě `"washington medic"`, může být `"washington medicaid"`odpověď , . `"washington medical"`
$filter	řetězec	Nepovinný parametr. Strukturovaný vyhledávací výraz ve standardní syntaxi OData, který filtruje dokumenty zvažované pro vytváření dokončených návrhů termínů. Rozhraní API pro automatické dokončování nepodporuje výrazy filtru search.ismatchscoring a search.ismatchscoring.* Ve filtru lze použít pouze filtrovatelná pole. Při zavolání s post má tento parametr název filter místo $filter. Podrobnosti o podmnožině gramatiky výrazů OData podporované službou Azure AI Search najdete v tématu Syntaxe výrazů OData pro Azure AI Search.
Fuzzy	boolean	Nepovinný parametr. Výchozí hodnota je false. Pokud je nastavená hodnota true, toto rozhraní API vyhledá návrhy i v případě, že hledaný text obsahuje nahrazený nebo chybějící znak ^(1). V některých scénářích to poskytuje lepší prostředí, ale má to náklady na výkon, protože vyhledávání přibližných návrhů je pomalejší a spotřebovává více prostředků.
highlightPostTag	řetězec	Nepovinný parametr. Výchozí hodnota je prázdný řetězec. Značka řetězce, která připojí zvýrazněný termín. Musí být nastaven pomocí highlightPreTag. Rezervované znaky v adrese URL musí být zakódované procenty (například %23 místo #). Při volání pomocí funkce GET musí být rezervované znaky v adrese URL zakódované v procentech (například %23 místo #).
highlightPreTag	řetězec	Nepovinný parametr. Výchozí hodnota je prázdný řetězec. Značka řetězce, která se předeznamuje zvýrazněným termínem. Musí být nastaven pomocí highlightPostTag. Při volání pomocí funkce GET musí být rezervované znaky v adrese URL zakódované v procentech (například %23 místo #).
minimumCoverage	integer	Nepovinný parametr. Výchozí hodnota je 80. Číslo mezi 0 a 100 označující procento indexu, které musí být k dispozici pro obsluhu dotazu, aby bylo možné hlásit úspěch. Výchozí hodnota odráží sklon k rychlosti a efektivitě oproti plnému pokrytí. Omezení pokrytí omezuje rozšíření dotazů, což umožňuje rychlejší vrácení výsledků. Umožňuje také úspěšně provést dotaz při částečné dostupnosti indexu, a to i v případě, že jeden horizontální oddíl reaguje pomalu nebo není k dispozici kvůli problémům se stavem služby nebo údržbě indexu. Bez ohledu na hodnotu minimumCoverage musí být toto procento indexu k dispozici nebo automatické dokončování vrátí stavový kód HTTP 503. Pokud automatické dokončování proběhne úspěšně na úrovni minimumCoverage, vrátí http 200 a do odpovědi zahrne @search.coverage hodnotu označující procento indexu, které bylo k dispozici při údržbě dotazu. Snížení této hodnoty může být užitečné, pokud dochází k chybám 503. V opačném případě můžete zvážit zvýšení hodnoty, pokud odpověď neposkytuje dostatečné shody.
search	řetězec	Povinná hodnota. Text, který chcete vyhledat. Hledaný text, který se má dokončit. Musí mít alespoň 1 znak a nesmí být delší než 100 znaků. Nemůže obsahovat operátory, syntaxi dotazu ani uvozované fráze.
searchFields	řetězec	Nepovinný parametr. Seznam názvů polí oddělených čárkami pro vyhledání zadaného hledaného textu. Cílová pole musí být uvedená v definici Návrhy v indexu.
suggesterName	řetězec	Povinná hodnota. Název návrhu zadaný v kolekci Návrhy, která je součástí definice indexu. Předpona určuje, která pole se kontrolují pro navrhované termíny dotazu.
$top	integer	Nepovinný parametr. Výchozí hodnota je 5. Počet automaticky dokončovaných návrhů, které se mají načíst. Hodnota musí být číslo mezi 1 a 100. Při zavolání pomocí POST má tento parametr název top místo $top.

(1) Omezení fuzzy v automatickém dokončování:

Za prvé, vzdálenost úprav je omezena pouze na jeden znak rozdíl na token na rozdíl od parametru fuzzy při hledání. Omezení vzdálenosti úprav na jeden znak znamená, že nebudou nalezeny všechny kandidátské shody, ale limit je nezbytný pro zajištění přijatelné úrovně výkonu.

Za druhé, krok fuzzy nastane po částečném rozšíření tokenu a pro přibližné shody se zvažují pouze termíny ze stejného horizontálního oddílu indexu. Toto omezení zvyšuje výkon rozhraní API automatického dokončování tím, že eliminuje agregaci přibližných shod pro všechny horizontální oddíly. Toto omezení se stává méně patrným s tím, jak se do indexu přidá více termínů, což má za následek podobné rozdělení termínů pro každý horizontální oddíl. Vzhledem k tomu, že se termíny distribuují rovnoměrně, přibližné shody v rámci horizontálního oddílu představují dobrou aproximaci přibližných shod v celém indexu. Výsledky však můžou být nižší, pokud index obsahuje méně termínů, například v testovacím nebo prototypovém indexu, což vede k nerovnoměrné reprezentaci napříč horizontálními oddíly. Další informace o rozdělení indexů na horizontální oddíly najdete v tématu Kombinace oddílů a replik.

Odpověď

Pro úspěšnou odpověď se vrátí stavový kód 200 OK.

Datová část odpovědi má dvě vlastnosti.

Vlastnost	Popis
"text"	Dokončený termín nebo fráze
"queryPlusText"	Vstupní počáteční dotaz plus dokončený termín nebo frázi

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

Příklady

Příklad 1: Načtení tří návrhů automatického dokončování, kde je 'washington medic' částečný vstup hledání s výchozím režimem (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"  
}

Odpověď:

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

Příklad 2: Načtení tří návrhů automatického dokončování, kde je 'washington medic' vstup částečného hledání a 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"  
}