Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
Notitie
Deze functie is momenteel beschikbaar als openbare preview-versie. Deze preview wordt geleverd zonder service level agreement en wordt niet aanbevolen voor productieworkloads. Misschien worden bepaalde functies niet ondersteund of zijn de mogelijkheden ervan beperkt. Zie Aanvullende gebruiksvoorwaarden voor Microsoft Azure-previews voor meer informatie.
Het herschrijven van query's is het proces van het transformeren van de query van een gebruiker in een effectievere query, het toevoegen van meer termen en het verfijnen van zoekresultaten. De zoekservice verzendt de zoekquery (of een variatie ervan) naar een generatief model waarmee alternatieve query's worden gegenereerd.
Het herschrijven van query's verbetert de resultaten van semantische classificatie door typfouten of spelfouten in gebruikersquery's te corrigeren en query's uit te breiden met synoniemen.
Zoeken met het herschrijven van query's werkt als volgt:
- De gebruikersquery wordt verzonden via de
searcheigenschap in de aanvraag. - De zoekservice verzendt de zoekquery (of een variatie ervan) naar een generatief model waarmee alternatieve query's worden gegenereerd.
- De zoekservice maakt gebruik van de oorspronkelijke query en de herschreven query's om zoekresultaten op te halen.
Het herschrijven van query's is een optionele functie. Zonder query's opnieuw te schrijven, gebruikt de zoekservice alleen de oorspronkelijke query om zoekresultaten op te halen.
Notitie
De herschreven query's bevatten mogelijk niet alle exacte termen die de oorspronkelijke query had. Dit kan van invloed zijn op zoekresultaten als de query zeer specifiek was en exacte overeenkomsten vereist voor unieke id's of productcodes.
Vereisten
Azure AI Search in elke regio die het herschrijven van query's biedt, waarbij semantische rangschikking is ingeschakeld.
Een bestaande zoekindex met een semantische configuratie en opgemaakte tekst. In de voorbeelden in deze handleiding worden de voorbeeldgegevens van hotels-sample-index gebruikt om het herschrijven van query's te demonstreren.
Als u de instructies in dit artikel wilt volgen, hebt u een webclient nodig die REST API-aanvragen ondersteunt. De voorbeelden in dit artikel zijn getest met Visual Studio Code en de REST Client-extensie .
Tip
Inhoud met uitleg of definities werkt het beste voor semantische rangschikking.
Een zoekaanvraag maken met herschrijfbewerkingen voor query's
In dit REST API-voorbeeld gebruikt u Zoekdocumenten (preview) om de aanvraag te formuleren.
Plak de volgende aanvraag in een webclient als sjabloon.
POST https://[search-service-name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2025-11-01-preview { "search": "newer hotel near the water with a great restaurant", "semanticConfiguration":"en-semantic-config", "queryType":"semantic", "queryRewrites":"generative|count-5", "queryLanguage":"en-US", "debug":"queryRewrites", "top": 1 }Vervang door
search-service-namede naam van uw zoekservice.Vervang
hotels-sample-indexdoor uw indexnaam als deze anders is.Stel 'zoeken' in op een zoekopdracht in volledige tekst. De zoekeigenschap is vereist voor het herschrijven van query's, tenzij u vectorquery's opgeeft. Als u vectorquery's opgeeft, moet de zoektekst overeenkomen met de
"text"eigenschap van het"vectorQueries"object. Uw zoekreeks kan de eenvoudige syntaxis of volledige Lucene-syntaxis ondersteunen.Stel 'semanticConfiguration' in op een vooraf gedefinieerde semantische configuratie die is ingesloten in uw index.
Stel 'queryType' in op 'semantisch'. U moet 'queryType' instellen op 'semantisch' of een nonempty 'semanticQuery'-eigenschap opnemen in de aanvraag. Semantische classificatie is vereist voor het herschrijven van query's.
Stel 'queryRewrites' in op 'generatief|count-5' om maximaal vijf herschrijven van query's op te halen. U kunt het aantal instellen op elke waarde tussen 1 en 10.
Omdat u hebt gevraagd om query herschrijvingen door de eigenschap "queryRewrites" in te stellen, moet u "queryLanguage" instellen op de taal van de zoektekst. De zoekservice gebruikt dezelfde taal voor het herschrijven van de query. In dit voorbeeld gebruikt u 'en-US'. De ondersteunde landinstellingen zijn:
en-AU,en-CA,en-GB,en-IN,en-US,ar-EG,ar-JO,ar-KW,ar-MA,ar-SA,bg-BG,bn-IN,ca-ES,cs-CZ,da-DK,de-DE,el-GR,es-ES,es-MX,et-EE,eu-ES,fa-AE,fi-FI,fr-CA,fr-FR,ga-IE,gl-ES,gu-IN,he-IL,hi-IN,hr-BA,hr-HR,hu-HU,hy-AM,id-ID,is-IS,it-IT,ja-JP,kn-IN,ko-KR,lt-LT,lv-LV,ml-IN,mr-IN,ms-BN,ms-MY,nb-NO,nl-BE,nl-NL,no-NO,pa-IN,pl-PL,pt-BR,pt-PT,ro-RO,ru-RU,sk-SK,sl-SL,sr-BA,sr-ME,sr-RS,sv-SE,ta-IN,te-IN,th-TH,tr-TR,uk-UA,ur-PK,vi-VN,zh-CN,zh-TW.Stel 'debug' in op 'queryRewrites' om de query opnieuw te schrijven in het antwoord.
Tip
Stel
"debug": "queryRewrites"alleen in voor testdoeleinden. Gebruik voor betere prestaties geen foutopsporing in productie.Stel 'top' in op 1 om alleen het bovenste zoekresultaat te retourneren.
Verzend de aanvraag om de query uit te voeren en retourneer resultaten.
Vervolgens evalueert u de zoekresultaten met het herschrijven van de query.
Het antwoord evalueren
Hier volgt een voorbeeld van een antwoord dat query's herschrijft:
"@search.debug": {
"semantic": null,
"queryRewrites": {
"text": {
"inputQuery": "newer hotel near the water with a great restaurant",
"rewrites": [
"new waterfront hotels with top-rated eateries",
"new waterfront hotels with top-rated restaurants",
"new waterfront hotels with excellent dining",
"new waterfront hotels with top-rated dining",
"new water-side hotels with top-rated restaurants"
]
},
"vectors": []
}
},
"value": [
{
"@search.score": 58.992092,
"@search.rerankerScore": 2.815633535385132,
"HotelId": "18",
"HotelName": "Ocean Water Resort & Spa",
"Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
"Description_fr": "Nouvel h\u00f4tel de luxe pour des vacances inoubliables. Vue sur la baie depuis chaque chambre, emplacement pr\u00e8s de la jet\u00e9e, piscine sur le toit, restaurant au bord de l'eau et plus encore.",
"Category": "Luxury",
"Tags": [
"view",
"pool",
"restaurant"
],
"ParkingIncluded": true,
"LastRenovationDate": "2020-11-14T00:00:00Z",
"Rating": 4.2,
"Location": {
"type": "Point",
"coordinates": [
-82.537735,
27.943701
],
"crs": {
"type": "name",
"properties": {
"name": "EPSG:4326"
}
}
},
//... more properties redacted for brevity
}
]
Hier volgen enkele belangrijke punten die u moet noteren:
- Omdat u de eigenschap 'debug' instelt op 'queryRewrites' voor testen, bevat het antwoord een
@search.debugobject met de tekstinvoerquery en herschrijven van query's. - Omdat u de eigenschap 'queryRewrites' instelt op 'generatief|count-5', bevat het antwoord maximaal vijf herschrijven van query's.
- De
"inputQuery"waarde is de query die wordt verzonden naar het generatieve model voor het herschrijven van query's. De invoerquery is niet altijd hetzelfde als de query van de gebruiker"search".
Hier volgt een voorbeeld van een antwoord zonder query opnieuw te schrijven.
"@search.debug": {
"semantic": null,
"queryRewrites": {
"text": {
"inputQuery": "",
"rewrites": []
},
"vectors": []
}
},
"value": [
{
"@search.score": 7.774868,
"@search.rerankerScore": 2.815633535385132,
"HotelId": "18",
"HotelName": "Ocean Water Resort & Spa",
"Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
"Description_fr": "Nouvel h\u00f4tel de luxe pour des vacances inoubliables. Vue sur la baie depuis chaque chambre, emplacement pr\u00e8s de la jet\u00e9e, piscine sur le toit, restaurant au bord de l'eau et plus encore.",
"Category": "Luxury",
"Tags": [
"view",
"pool",
"restaurant"
],
"ParkingIncluded": true,
"LastRenovationDate": "2020-11-14T00:00:00Z",
"Rating": 4.2,
"Location": {
"type": "Point",
"coordinates": [
-82.537735,
27.943701
],
"crs": {
"type": "name",
"properties": {
"name": "EPSG:4326"
}
}
},
//... more properties redacted for brevity
}
]
Vectorquery's met het herschrijven van query's
U kunt vectorquery's opnemen in uw zoekaanvraag om trefwoordzoekopdrachten en vectorzoekopdrachten te combineren in één aanvraag en een uniform antwoord.
Hier is een voorbeeld van een query die een vectorquery met herschrijven van query's bevat. Wijzig een vorig voorbeeld om een vectorquery op te nemen.
- Voeg een vectorQueries-object toe aan de aanvraag. Dit object bevat een vectorquery met de 'soort' ingesteld op 'tekst'.
- De waarde 'tekst' is hetzelfde als de zoekwaarde. Deze waarden moeten identiek zijn voor het herschrijven van query's.
POST https://[search-service-name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2025-11-01-preview
{
"search": "newer hotel near the water with a great restaurant",
"vectorQueries": [
{
"kind": "text",
"text": "newer hotel near the water with a great restaurant",
"k": 50,
"fields": "Description",
"queryRewrites": "generative|count-3"
}
],
"semanticConfiguration":"en-semantic-config",
"queryType":"semantic",
"queryRewrites":"generative|count-5",
"queryLanguage":"en-US",
"top": 1
}
Het antwoord bevat queryherschrijvingen voor zowel de tekstquery als de vectorquery.
Query's opnieuw schrijven met foutopsporing
U moet uw query-herschrijvingen testen om ervoor te zorgen dat ze werken zoals verwacht. Stel de "debug": "queryRewrites" eigenschap in uw queryaanvraag in om de query opnieuw te schrijven in het antwoord. Instelling "debug" is optioneel voor testdoeleinden. Voor betere prestaties moet u deze eigenschap niet instellen in de productieomgeving.
Redenen voor gedeeltelijke reacties
U ziet mogelijk dat het antwoord voor foutopsporing (test) een lege matrix bevat voor de text.rewrites en vectors eigenschappen.
{
"@odata.context": "https://demo-search-svc.search.windows.net/indexes('hotels-sample-index')/$metadata#docs(*)",
"@search.debug": {
"semantic": null,
"queryRewrites": {
"text": {
"rewrites": []
},
"vectors": []
}
},
"@search.semanticPartialResponseReason": "Transient",
"@search.semanticQueryRewriteResultType": "OriginalQueryOnly",
//... more properties redacted for brevity
}
In het voorgaande voorbeeld:
- Het antwoord bevat een
@search.semanticPartialResponseReasoneigenschap met de waarde 'Tijdelijk'. Dit bericht betekent dat ten minste één van de query's niet kan worden voltooid. - Het antwoord bevat ook een
@search.semanticQueryRewriteResultTypeeigenschap met de waarde OriginalQueryOnly. Dit bericht betekent dat de herschrijvingen van de query niet beschikbaar zijn. Alleen de oorspronkelijke query wordt gebruikt om zoekresultaten op te halen.
Volgende stappen
Semantische classificatie kan worden gebruikt in hybride query's die trefwoordzoekopdrachten en vectorzoekopdrachten combineren in één aanvraag en een uniform antwoord.