Query's herschrijven met een semantische rangschikking in Azure AI Zoeken (preview)

Opmerking

Azure AI Zoeken is beschikbaar via de Azure-portal, REST API's en Azure-SDK's. Het vormt ook een basis voor Foundry IQ, de beheerde kennislaag die bedrijfsinhoud transformeert in herbruikbare, machtigingsbewuste knowledge bases voor agents in de Microsoft Foundry-portal.

Important

Functies, mogelijkheden of eigenschappen die zijn gemarkeerd (preview) vallen niet onder een service level agreement, worden niet aanbevolen voor productieworkloads en kunnen worden gewijzigd of beperkt voordat ze algemeen beschikbaar worden. De Azure AI Zoeken preview-voorwaarden zijn van toepassing op alle preview-functionaliteit, ongeacht of deze zelfstandig is of deel uitmaakt van een algemeen beschikbare functie.

Het herschrijven van query's (preview) 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 search eigenschap 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.

Opmerking

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.

Voorwaarden

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.

  1. Plak de volgende aanvraag in een webclient als sjabloon.

    POST https://[search-service-name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-08-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-name de naam van uw zoekservice.

    • Vervang hotels-sample door 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 zoekopdrachten hebt aangevraagd door de eigenschap queryRewrites in te stellen, moet u de queryLanguage instellen op de zoekteksttaal. 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.

  2. 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.debug object 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 "search" de gebruiker.

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 volgt een voorbeeld van een query met een vectorquery met herschrijven van query's. 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/docs/search?api-version=2026-08-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.

Test het herschrijven van queries met foutopsporing.

U moet uw query-herschrijvingen testen om ervoor te zorgen dat ze correct functioneren zoals verwacht. Stel de "debug": "queryRewrites" eigenschap in uw queryverzoek in om de queryherwerkingen in de reactie te ontvangen. Instelling "debug" is optioneel voor testdoeleinden. Stel deze eigenschap niet in tijdens de productiefase voor betere prestaties.

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')/$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.semanticPartialResponseReason eigenschap 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.semanticQueryRewriteResultType eigenschap met de waarde OriginalQueryOnly. Dit bericht betekent dat de query-herschrijvingen 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.

Hybride query met semantische rangschikker

  • Last updated on