Vytvoření fulltextového dotazu ve službě Azure AI Vyhledávač

Pokud vytváříte dotaz pro fulltextové vyhledávání, najdete v tomto článku postup nastavení požadavku. Představuje také strukturu dotazů a vysvětluje, jak můžou atributy polí a lingvistické analyzátory ovlivnit výsledky dotazů.

Požadavky

• Azure AI Vyhledávač service (libovolná úroveň). Vytvořte službu nebo najděte existující.

• Index vyhledávání obsahující řetězcová pole, která jsou označena jako prohledávatelná. Jako koncový bod požadavku dotazu můžete použít také alias indexu .

• Oprávnění k dotazování indexu:

  • Klíčové ověřování: Dotazovací klíč rozhraní API pro vaši vyhledávací službu.
  • Ověřování na základě role: Role Čtenář dat indexu vyhledávání

• Pro vývoj sady SDK nainstalujte klientskou knihovnu Azure Search:

  • Python: azure-search-documents
  • .NET: Azure. Search.Documents
  • JavaScript: @azure/search-documents
  • Java: azure-search-documents

Příklad požadavku na fulltextový dotaz

V Azure AI Vyhledávač je dotaz požadavkem jen pro čtení pro kolekci dokumentů jednoho indexu vyhledávání s parametry, které informují o spuštění dotazu a tvarují návrat odpovědi.

Fulltextový dotaz se zadává v parametru search a skládá se z termínů, uvozovek uzavřených frází a operátorů. Další parametry přidávají do požadavku další definici.

Následující volání rozhraní REST API služby Search POST znázorňuje požadavek dotazu s použitím search a dalšími parametry.

POST https://[service name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-04-01
{
    "search": "NY +view",
    "queryType": "simple",
    "searchMode": "all",
    "searchFields": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "select": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "top": 10,
    "count": true
}

Reference:Search POST

Klíčové body

• search poskytuje kritéria shody, obvykle celé termíny nebo fráze, s nebo bez operátorů. Jakékoli pole, které je atributem prohledávatelné ve schématu indexu, je v rozsahu pro operaci vyhledávání.

• queryType nastaví analyzátor: jednoduchý, plný. Výchozí jednoduchý analyzátor dotazů je optimální pro fulltextové vyhledávání. Úplný analyzátor dotazů Lucene je určený pro pokročilé konstruktory dotazů, jako jsou regulární výrazy, vyhledávání dle blízkosti, přibližné vyhledávání a vyhledávání zástupných znaků. Tento parametr lze také nastavit na sémantickou pro sémantické řazení pro pokročilé sémantické modelování v odpovědi dotazu.

• searchMode určuje, zda jsou shody založeny na všech kritériích (upřednostňují přesnost) nebo kterémkoli kritériu (upřednostňuje vyhledání) ve výrazu. Výchozí hodnota je libovolný. Pokud očekáváte vysoké využití logických operátorů, což je pravděpodobnější v indexech, které obsahují velké textové bloky (pole obsahu nebo dlouhé popisy), nezapomeňte otestovat dotazy s parametrem searchMode=Any|All a vyhodnotit dopad tohoto nastavení na logické vyhledávání.

• searchFields omezuje provádění dotazu na konkrétní prohledávatelná pole. Během vývoje je užitečné použít stejný seznam polí pro výběr a vyhledávání. V opačném případě může být shoda založená na hodnotách polí, které ve výsledcích nevidíte, což vede k nejistotě, proč byl dokument vrácen.

Parametry použité k tvarování odpovědi:

• select určuje, která pole se mají v odpovědi vrátit. V příkazu select lze použít pouze pole označená jako načítaná v indexu.

• top vrátí zadaný počet nejlépe odpovídajících dokumentů. V tomto příkladu se vrátí pouze 10 zásahů. K stránkování výsledků můžete použít možnosti "nahoru" a "přeskočit" (není zobrazeno).

• count vám řekne, kolik dokumentů v celém indexu odpovídá celkově, což může být větší, než kolik se vrátí. Platné hodnoty jsou true nebo false. Výchozí hodnota je "false". Počet je přesný, pokud je index stabilní, ale při aktivním přidávání, aktualizaci nebo mazání dokumentů vždy buď podhodnocuje nebo nadhodnocuje. Pokud chcete získat pouze počet bez jakýchkoli dokumentů, můžete použít $top=0.

• orderby se používá, pokud chcete výsledky seřadit podle hodnoty, jako je hodnocení nebo umístění. V opačném případě je výchozí použít skóre relevance k řazení výsledků. Pole musí být označeno jako sortable, aby bylo kandidátem pro tento parametr.

Volba klienta

V případě počátečního vývoje a testování konceptu začněte s Azure portal nebo klientem REST nebo Jupyter notebook. Tyto přístupy jsou interaktivní, užitečné pro cílené testování a pomáhají vyhodnotit účinky různých vlastností, aniž byste museli psát jakýkoli kód.

Pokud chcete volat vyhledávání z aplikace, použijte klientské knihovny Azure.Document.Search v sadách Azure SDK pro .NET, Java, JavaScript a Python.

POST https://[service name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-04-01
{
    "search": "NY +view",
    "queryType": "simple",
    "searchMode": "all",
    "searchFields": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "select": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "count": true
}

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

# Set up the client
service_name = "<your-search-service-name>"
index_name = "hotels-sample"
api_key = "<your-query-api-key>"

endpoint = f"https://{service_name}.search.windows.net"
credential = AzureKeyCredential(api_key)
client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

# Run a full-text search query
results = client.search(
    search_text="NY +view",
    search_mode="all",
    search_fields=["HotelName", "Description", "Address/City", "Tags"],
    select=["HotelName", "Description", "Address/City", "Tags"],
    top=10,
    include_total_count=True
)

print(f"Total documents matching query: {results.get_count()}")
for result in results:
    print(f"Hotel: {result['HotelName']}")

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

// Set up the client
string serviceName = "<your-search-service-name>";
string indexName = "hotels-sample";
string apiKey = "<your-query-api-key>";

Uri endpoint = new Uri($"https://{serviceName}.search.windows.net");
AzureKeyCredential credential = new AzureKeyCredential(apiKey);
SearchClient searchClient = new SearchClient(endpoint, indexName, credential);

// Run a full-text search query
SearchOptions options = new SearchOptions
{
    SearchMode = SearchMode.All,
    IncludeTotalCount = true,
    Size = 10
};
options.SearchFields.Add("HotelName");
options.SearchFields.Add("Description");
options.Select.Add("HotelName");
options.Select.Add("Description");

SearchResults<SearchDocument> response = await searchClient.SearchAsync<SearchDocument>("NY +view", options);

Console.WriteLine($"Total documents matching query: {response.TotalCount}");
await foreach (SearchResult<SearchDocument> result in response.GetResultsAsync())
{
    Console.WriteLine($"Hotel: {result.Document["HotelName"]}");
}

Volba typu dotazu: simple | plný

Pokud je dotaz fulltextové vyhledávání, použije se analyzátor dotazů ke zpracování libovolného textu, který se předává jako hledané termíny a fráze. Azure AI Vyhledávač nabízí dva analyzátory dotazů.

• Jednoduchý analyzátor rozumí syntaxi jednoduchého dotazu. Tento analyzátor byl vybrán jako výchozí pro jeho rychlost a účinnost ve volných textových dotazech. Syntaxe podporuje běžné vyhledávací operátory (AND, OR, NOT) pro hledání termínů a frází a vyhledávání předpon (*jako v sea* seattlu a přímořském pobřeží). Obecně doporučujeme nejprve vyzkoušet jednoduchý analyzátor a poté přejít na plnohodnotný analyzátor, pokud požadavky aplikace vyžadují výkonnější dotazy.

• Úplná syntaxe dotazů Lucene, která je povolená při přidání queryType=full do požadavku, je založená na Apache Lucene Parseru.

Úplná syntaxe a jednoduchá syntaxe se překrývají v rozsahu, který podporuje stejnou předponu i logické operace, ale úplná syntaxe poskytuje více operátorů. Existuje celá řada operátorů pro logické výrazy a další operátory pro pokročilé dotazy, jako je vyhledávání přibližných shod, vyhledávání zástupných znaků, vyhledávání podle blízkosti a regulární výrazy.

Volba metod dotazu

Vyhledávání je v podstatě cvičení řízené uživatelem, kde se termíny nebo fráze shromažďují z vyhledávacího pole nebo z kliknutí na události na stránce. Následující tabulka shrnuje mechanismy, podle kterých můžete shromažďovat vstupy uživatelů spolu s očekávaným vyhledávacím prostředím.

Vliv atributů pole na dotazy

Pokud znáte typy a složení dotazů, možná si pamatujete, že parametry požadavku na dotaz závisí na atributech polí v indexu. Například v dotazech a výsledcích hledání se dají použít jenom pole označená jako prohledávatelná a zobrazitelná . Při nastavování searchfilterparametrů a orderby parametrů v požadavku byste měli zkontrolovat atributy, abyste se vyhnuli neočekávaným výsledkům.

Na následujícím snímku obrazovky indexu hotels-sample jsou pouze poslední dvě pole LastRenovationDate a Ratingsortovatelná, což je požadavek pro použití v "$orderby" samotné klauzuli.

Definice atributů polí najdete v tématu Vytvoření indexu (REST API).

Účinek tokenů na dotazy

Během indexování používá vyhledávací web textový analyzátor řetězců k maximalizaci potenciálu hledání shody v době dotazu. Řetězce jsou minimálně převedeny na malá písmena, ale v závislosti na analyzátoru mohou také projít lematizací a odstraněním stop slov. Větší řetězce nebo složená slova se obvykle rozdělí pomocí prázdných znaků, spojovníků nebo pomlček a indexují se jako samostatné tokeny.

Klíčovým bodem je, že to, co si myslíte, že index obsahuje a co je ve skutečnosti v něm, se může lišit. Pokud dotazy nevrací očekávané výsledky, můžete zkontrolovat tokeny vytvořené analyzátorem prostřednictvím rozhraní REST API (Analyze Text). Další informace o tokenizaci a vlivu na dotazy naleznete v části Částečné hledání termínů a vzorů se speciálními znaky.

Odstraňování problémů s dotazy

Následující tabulka uvádí běžné problémy s dotazy a jejich řešení.

Související obsah

Teď, když máte lepší přehled o tom, jak žádosti o dotazy fungují, vyzkoušejte následující rychlé starty pro praktické zkušenosti.

• Vyhledávací průzkumník
• Rychlý průvodce: Fulltextové vyhledávání
• Jednoduchá syntaxe dotazů
• Úplná syntaxe dotazů Lucene
• Syntaxe filtru OData