Teljes szöveges lekérdezés létrehozása az Azure AI Keresésben

Megjegyzés:

Azure AI Keresés a Azure portálon, REST API-kon és Azure SDK-k keresztül érhető el. Emellett a Foundry IQ-t is támogatja, amely a vállalati tartalmakat újrafelhasználható, engedélytudatos tudásbázisokká alakítja át az Microsoft Foundry portálon található ügynökök számára.

Ha teljes szöveges keresésre készít lekérdezést, ez a cikk a kérés beállításának lépéseit ismerteti. Emellett egy lekérdezési struktúrát is bevezet, és elmagyarázza, hogy a mezőattribútumok és a nyelvi elemzők hogyan befolyásolhatják a lekérdezési eredményeket.

Előfeltételek

Azure AI-keresési szolgáltatás (bármilyen típusban). Szolgáltatás létrehozása vagy keressen egy meglévő szolgáltatást.
Egy keresési index, amelynek sztringmezői kereshetőként vannak megjelölve attribútumokkal. A lekérdezési kérelem végpontjaként index aliast is használhat.
Az index lekérdezéséhez szükséges engedélyek:
- Kulcsalapú hitelesítés: API lekérdezési kulcs az Ön keresési szolgáltatásához.
- Szerepköralapú hitelesítés: Keresési index adatolvasó szerepköre.
SDK-fejlesztéshez telepítse a Azure Search ügyfélkódtárat:
- Python: azure-search-documents
- .NET: Azure. Search.Documents
- JavaScript: @azure/search-documents
- Java: azure-search-documents

Jótanács

Gyors kódpélda megtekintéséhez lépjen a Teljes szöveges lekérdezési kérelem példájához.

Példa egy teljes szöveges lekérdezési kérelemre

Az Azure AI Keresés szolgáltatásban a lekérdezés egy írásvédett kérés egyetlen keresési index lekérdezhető dokumentumgyűjteményéből, olyan paraméterekkel, amelyek tájékoztatják a lekérdezés végrehajtását és alakítják a visszaadott választ.

A paraméterben search egy teljes szöveges lekérdezés van megadva, és kifejezésekből, idézőjelek közé foglalt kifejezésekből és operátorokból áll. Más paraméterek további definíciót adnak a kéréshez.

Az alábbi Search POST REST API-hívás egy lekérdezési kérést search használatával és más paraméterekkel szemléltet.

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
}

Hivatkozás:Search POST

Kulcsfontosságú pontok

search operátorokkal vagy anélkül biztosítja a megfeleltetés feltételeit, általában egész kifejezéseket vagy kifejezéseket. Az indexsémában kereshetőként tulajdonított mezők keresési művelet hatókörébe tartoznak.
queryType beállítja az elemzőt: egyszerű, teljes. Az alapértelmezett egyszerű lekérdezéselemző optimális a teljes szöveges kereséshez. A teljes Lucene lekérdezéselemző olyan speciális lekérdezésszerkezetekhez használható, mint a reguláris kifejezések, a közelségi keresés, a homályos és a helyettesítő karakterek keresése. Ez a paraméter szemantikai értékre is beállítható szemantikai rangsoroláshoz, amely lehetővé teszi a lekérdezési válaszok fejlett szemantikai modellezését.
searchModemegadja, hogy az egyezések az összes feltételen alapulnak -e (előnyben részesíti a pontosságot) vagy a kifejezésben szereplő bármely feltételen (előnyben részesíti a visszahívást). Az alapértelmezett érték bármely. Ha a nagy szöveges blokkokat (tartalommezőt vagy hosszú leírásokat) tartalmazó indexekben nagyobb valószínűséggel használ logikai operátorokat, akkor a paraméterrel tesztelje a searchMode=Any|All lekérdezéseket a beállítás logikai keresésre gyakorolt hatásának kiértékeléséhez.
searchFields korlátozza a lekérdezések végrehajtását adott kereshető mezőkre. A fejlesztés során hasznos, ha ugyanazt a mezőlistát használja a kiválasztáshoz és a kereséshez. Ellenkező esetben előfordulhat, hogy egy egyezés olyan mezőértékeken alapul, amelyeket nem lát az eredményekben, és bizonytalanságot okoz a dokumentum visszaadása miatt.

A válasz alakításához használt paraméterek:

select a válaszban visszaadandó mezőket adja meg. Csak az indexben lekérdezhetőként megjelölt mezők használhatók választó utasításban.
top A legjobban megfeleltetendő dokumentumok megadott számát adja vissza. Ebben a példában csak 10 találat kerül visszaadásra. A "top" és "skip" funkció (ami itt nem jelenik meg) használatával lapozhat az eredmények között.
count Azt jelzi, hogy a teljes index hány dokumentuma egyezik meg, ami több lehet, mint a visszaadott dokumentumok száma. Az érvényes értékek "igaz" vagy "hamis". Alapértelmezés szerint "false" (hamis). A darabszám akkor pontos, ha az index stabil, de az aktívan hozzáadott, frissített vagy törölt dokumentumok esetében előfordulhat alul- vagy túlszámlálás. Ha dokumentum nélkül szeretné csak a darabszámot lekérni, használhatja a $top=0 értéket.
orderby akkor használatos, ha az eredményeket érték, például értékelés vagy hely szerint szeretné rendezni. Ellenkező esetben az alapértelmezett érték a relevanciapont használata az eredmények rangsorolásához. A mezőnek rendezhetőnek kell lennie ahhoz, hogy a paraméter jelöltje legyen.

Ügyfél kiválasztása

A korai fejlesztéshez és a megvalósíthatósági vizsgálathoz kezdje az Azure portallal, a REST-ügyféllel vagy a Jupyter notebookkal. Ezek a megközelítések interaktívak, hasznosak a célzott teszteléshez, és segítenek felmérni a különböző tulajdonságok hatásait anélkül, hogy kódokat kellene írniuk.

Ha alkalmazáson belüli keresést szeretne meghívni, használja a Azure.Document.Search ügyfélkódtárakat a Azure SDK-kban .NET, Java, JavaScript és Python nyelven.

Az Azure portalon, amikor megnyit egy indexet, az index JSON-definíciójával együtt a Keresés Explorerrel is dolgozhat párhuzamos lapokon, így könnyen hozzáférhet a mezőattribútumokhoz. Ellenőrizze a Mezők táblát, hogy a lekérdezések tesztelése során mely elemek kereshetők, rendezhetők, szűrhetők és áttekinthetőek.

Nyissa meg a keresési szolgáltatást az Azure Portalon.
A szolgáltatásban válassza az Indexek lehetőséget, és válasszon egy indexet.
Megnyílik egy index a Kereséskezelő lapra, hogy azonnal lekérdezhető legyen. Váltson JSON nézetre a lekérdezés szintaxisának megadásához.

Íme egy teljes szöveges keresési lekérdezési kifejezés, amely a hotels-sample indexhez használható:
```
   {
       "search": "pool spa +airport",
       "queryType": "simple",
       "searchMode": "any",
       "searchFields": "Description, Tags",
       "select": "HotelName, Description, Tags",
       "top": 10,
       "count": true
   }
```
Hivatkozás:Search POST

Az alábbi képernyőkép a lekérdezést és a választ mutatja be:

GET használatával hívva a kérelem URL-címe nem haladhatja meg a 8 KB-ot. Ez a hossz a legtöbb alkalmazáshoz elegendő. Egyes alkalmazások azonban nagy lekérdezéseket hoznak létre, különösen OData-szűrőkifejezések használatakor. Ezekben az alkalmazásokban a HTTP POST jobb választás, mert nagyobb szűrőket tesz lehetővé, mint a GET.

A POST esetében a szűrőben lévő záradékok száma a korlátozó tényező, nem pedig a nyers szűrősztring mérete, mivel a POST kérelemméretének korlátja körülbelül 16 MB. Bár a POST kérelem méretkorlátja nagy, a szűrőkifejezések nem lehetnek tetszőlegesen összetettek. A szűrés összetettségi korlátaival kapcsolatos további információkért lásd az OData kifejezésszintaxisát.

Rest-ügyfél használatával állítson be egy kérést. Ha segítségre van szüksége az elindulással kapcsolatban, tekintse meg a Gyors kezdés: Teljes szöveges keresés REST használatával.

Az alábbi példa meghívja a REST API-t a teljes szöveges kereséshez:

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
}

Hivatkozás:Search POST

Részleges keresési válaszok folytatása

Néha Azure AI Keresés nem tudja egyetlen keresési válaszban visszaadni az összes kért találatot. A részleges válasz különböző okokból történhet, például ha a lekérdezés túl sok dokumentumot ad vissza úgy, hogy nem adja meg a $top, vagy ha túl nagy értéket ad meg a $top értékhez. Ilyen esetekben a Azure AI Keresés tartalmazza a válasz törzsében található @odata.nextLink megjegyzést, valamint @search.nextPageParameters, ha POST-kérés volt. Ezeknek a széljegyzeteknek az értékeivel létrehozhat egy másik keresési kérést a keresési válasz következő részének lekéréséhez. Ezt a viselkedést az eredeti keresési kérelem folytatásának nevezzük, a széljegyzeteket pedig folytatási jogkivonatoknak nevezzük. A megjegyzések szintaxisának és a válasz törzsben való megjelenésének részleteiért tekintse meg a Válasz szakaszban található példát.

Az Azure AI Keresés folytatási tokenek visszaadásának okai implementáció-specifikusak, és változhatnak idővel. Az erős klienseknek mindig készen kell állniuk az olyan esetek kezelésére, amikor a vártnál kevesebb dokumentumot adnak vissza, és egy folytatási tokent tartalmaz a dokumentumok további lekéréséhez. Azt is vegye figyelembe, hogy a folytatáshoz ugyanazt a HTTP-metódust kell használnia, mint az eredeti kérelem. Ha például GET kérést küldött, az elküldött folytatási kérelmeknek a GET (és hasonlóképpen a POST) parancsot is használniuk kell.

Megjegyzés:

@odata.nextLink és @search.nextPageParameters célja, hogy megvédje a szolgáltatást a túl sok eredményt kérő lekérdezésektől, nem pedig az, hogy általános mechanizmust biztosítson a lapozáshoz. Ha az eredményeket szeretné áttekinteni, használja $top és $skip együtt. Ha például 10-es méretű oldalakat szeretne, az első kérésnek $top=10 és $skip=0, a második kérésnek $top=10 és $skip=10, a harmadik kérésnek $top=10 és $skip=20 stb.

Az alábbi példák bemutatják, hogyan futtathat teljes szöveges lekérdezést a Azure SDK-k használatával.

Python

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']}")

Hivatkozás:SearchClient, keresés

C#

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"]}");
}

Referencia:SearchClient, SearchAsync, SearchOptions

További SDK-erőforrások

Azure SDK	Ügyfél	Példák
.NET	SearchClient	DotNetHowTo
Java	SearchClient	SearchForDynamicDocumentsExample.java
JavaScript	SearchClient	SDK-példák
Python	SearchClient	sample_simple_query.py

Válasszon egy lekérdezéstípust: egyszerű | tele

Ha a lekérdezés teljes szöveges keresés, a lekérdezéselemző a keresési kifejezésként és kifejezésként átadott szövegek feldolgozására szolgál. Azure AI Keresés két lekérdezéselemzőt kínál.

Az egyszerű elemző megérti az egyszerű lekérdezés szintaxisát. Ez az elemző lett kiválasztva alapértelmezettként az ingyenes formátumú szöveges lekérdezések sebességéhez és hatékonyságához. A szintaxis támogatja a gyakori keresési operátorokat (AND, OR, NOT) a kifejezés- és kifejezéskeresésekhez, valamint az előtagok (*) keresését (például sea* Seattle és Seaside esetében). Általános javaslat, hogy először próbálja ki az egyszerű elemzőt, majd lépjen tovább a teljes elemzőre, ha az alkalmazás követelményeinek nagyobb teljesítményű lekérdezésekre van szükség.
A Lucene teljes lekérdezési szintaxisa, amely akkor engedélyezett, ha hozzád queryType=full a kéréshez, az Apache Lucene Parser-en alapul.

A teljes szintaxis és az egyszerű szintaxis olyan mértékben fedi egymást, hogy mindkettő ugyanazt az előtagot és logikai műveletet támogatja, de a teljes szintaxis több operátort biztosít. Teljes egészében több operátor áll rendelkezésre a logikai kifejezésekhez, és további operátorok a speciális lekérdezésekhez, például a homályos kereséshez, a helyettesítő karakterek kereséséhez, a közelségi kereséshez és a reguláris kifejezésekhez.

Lekérdezési módszerek kiválasztása

A keresés alapvetően egy felhasználóvezérelt tevékenység, ahol a kifejezéseket egy keresőmezőből vagy egy weboldalon történt kattintásokból gyűjtik össze. Az alábbi táblázat összefoglalja azokat a mechanizmusokat, amelyekkel összegyűjtheti a felhasználói bemenetet, valamint a várt keresési élményt.

Bevitel	Élmény
Keresési módszer	A felhasználó egy keresőmezőbe írja be a kifejezéseket vagy kifejezéseket operátorokkal vagy anélkül, és a Keresés gombra kattintva elküldi a kérést. A keresés szűrőkkel is használható ugyanazon a kérelemen, de automatikus kiegészítéssel vagy javaslatokkal nem.
Automatikus kiegészítési módszer	A felhasználók néhány karaktert írnak be, és a lekérdezések az egyes új karakterek beírása után indulnak el. A válasz egy befejezett karaktersor az indexből. Ha a megadott sztring érvényes, a felhasználó a Keresés lehetőséget választva elküldi a lekérdezést a szolgáltatásnak.
Javaslatok módszere	Az automatikus kiegészítéshez hasonlóan a felhasználó beír néhány karaktert, és közben fokozatos lekérdezések jönnek létre. A válasz az egyező dokumentumok legördülő listája, amelyet általában néhány egyedi vagy leíró mező jelöl. Ha bármelyik kijelölés érvényes, a felhasználó kiválaszt egyet, és visszaadja a megfelelő dokumentumot.
Jellemzőalapú navigáció	Egy oldalon kattintható navigációs hivatkozások vagy a keresés hatókörét szűkítő morzsák láthatók. Az összetett navigációs struktúra egy kezdeti lekérdezés alapján dinamikusan áll össze. Például `search=*` egy minden lehetséges kategóriából álló, összetett navigációs fa kitöltéséhez. A rendszer egy aspektusalapú navigációs struktúrát hoz létre egy lekérdezési válaszból, de a következő lekérdezés kifejezésére is használható mechanizmus. n A REST API-referencia `facets` egy Keresési dokumentumok művelet lekérdezési paramétereként van dokumentálva, de a `search` paraméter nélkül is használható.
Szűrési módszer	A szűrők az eredmények szűkítéséhez használnak aspektusokat. A lap mögött szűrőt is implementálhat, például nyelvspecifikus mezőkkel inicializálhatja a lapot. A REST API-referencia `$filter` egy Keresési dokumentumok művelet lekérdezési paramétereként van dokumentálva, de a `search` paraméter nélkül is használható.

A mezőattribútumok hatása a lekérdezésekre

Ha ismeri a lekérdezéstípusokat és -összetételt, előfordulhat, hogy a lekérdezési kérelem paraméterei az index mezőattribútumaitól függnek. A lekérdezésekben és a keresési eredményekben például csak kereshetőként és lekérdezhetőként megjelölt mezők használhatók. Ha a kérelemben beállítja a search, filterés orderby a paramétereket, a váratlan eredmények elkerülése érdekében ellenőrizze az attribútumokat.

A hotelek mintaindexének alábbi képernyőképén csak az utolsó két mező, a LastRenovationDate és az Értékelésrendezhető, ami egy "$orderby" egyetlen záradékban való használat követelménye.

A mezőattribútum-definíciókért lásd az Index létrehozása (REST API) című témakört.

Tokenek hatása a lekérdezésekre

Az indexelés során a keresőmotor sztringeken lévő szövegelemzővel maximalizálja az egyezés keresésének lehetőségét a lekérdezési időpontban. A sztringeket minimálisan kisbetűsre alakítják át, de az elemzőtől függően lemmatizáláson mehetnek keresztül, és a stop szavak eltávolítását is elvégezhetik. A nagyobb sztringeket vagy összetett szavakat általában szóköz, kötőjel vagy gondolatjel szerint osztják fel, és külön szóelemként indexelik.

A lényeg az, hogy az index tartalma és a benne lévő tartalom eltérhet. Ha a lekérdezések nem adnak vissza várt eredményeket, az elemző által létrehozott jogkivonatokat az Elemzési szöveg (REST API) segítségével vizsgálhatja meg. A tokenizálásról és a lekérdezésekre gyakorolt hatásról további információt a részleges kifejezéskeresés és a speciális karaktereket tartalmazó minták című témakörben talál.

Lekérdezések hibaelhárítása

Az alábbi táblázat a gyakori lekérdezési problémákat és azok megoldását sorolja fel.

Probléma	Oka	Rezolúció
Üres találatok	Egyetlen dokumentum sem egyezik a lekérdezési feltételekkel.	Ellenőrizze, hogy a mező kereshető-e a sémában. A tokenizálás ellenőrzéséhez használja az Analyze Text API-t .
Váratlan eredmények	A lekérdezés megfelel a nem kívánt mezőknek.	A keresési mezők korlátozására használható `searchFields` .
Túl sok eredmény	A lekérdezés túlságosan általános.	Adjon hozzá szűrőket, használjon `searchMode=all`vagy adjon hozzá szükséges feltételeket az operátorral `+` .
Az eredmények nem a várt sorrendben jelennek meg	A relevanciapontozás nem felel meg az elvárásoknak.	Fontolja meg a pontozási profilokat vagy a szemantikai rangsorolást.
Hiányzó részleges egyezések	Az elemző a várttól eltérően tokenizál.	Használjon helyettesítő (`*`) utótagot, vagy ellenőrizze az elemző viselkedését az Analyze Text API-val.
A szűrő nem működik	A mező nincs szűrhetőként megjelölve.	Az index séma frissítése, hogy beállítsa a(z) `filterable: true` mezőt.

Most, hogy jobban megismerte a lekérdezési kérelmek működését, próbálkozzon az alábbi gyorsútmutatókkal a gyakorlati élmény érdekében.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Utolsó frissítés időpontja: 2026-03-05