Erneutes Schreiben von Abfragen mit semantischer Rangfolge in Azure KI-Suche (Vorschau)

Das Umschreiben von Abfragen (Vorschau) ist der Prozess der Transformation der Abfrage eines Benutzers in eine effektivere Abfrage, das Hinzufügen weiterer Ausdrücke und das Verfeinern von Suchergebnissen. Der Suchdienst sendet die Suchabfrage (oder eine Variation davon) an ein generatives Modell, das alternative Abfragen generiert.

Das Umschreiben von Abfragen verbessert Ergebnisse aus der semantischen Rangfolge, indem Tippfehler oder Rechtschreibfehler in Benutzerabfragen korrigiert und Abfragen mit Synonymen ergänzt werden.

Die Suche mit Umschreiben von Abfragen funktioniert wie folgt:

• Die Benutzerabfrage wird über die search Eigenschaft in der Anforderung gesendet.
• Der Suchdienst sendet die Suchabfrage (oder eine Variation davon) an ein generatives Modell, das alternative Abfragen generiert.
• Der Suchdienst verwendet die ursprüngliche Abfrage und die umgeschriebenen Abfragen, um Suchergebnisse abzurufen.

Die Umformulierung von Abfragen ist eine optionale Funktion. Ohne Abfrageumschreibung verwendet der Suchdienst nur die ursprüngliche Abfrage, um Suchergebnisse abzurufen.

Voraussetzungen

• Azure KI-Suche in einer beliebigen Region, die Abfrageumschreibung bereitstellt.

• Ein vorhandener Suchindex mit semantischer Konfiguration und Rich-Text-Inhalt. In den Beispielen in diesem Leitfaden wird der Hotels-Beispielindex verwendet, um das Query-Rewriting zu veranschaulichen.

• Um den Anweisungen in diesem Artikel zu folgen, benötigen Sie einen Webclient, der REST-API-Anforderungen unterstützt. Die Beispiele in diesem Artikel wurden mit Visual Studio Code und der erweiterung REST Client getestet.

Eine Suchanfrage stellen mit Abfrageumformulierungen

Verwenden Sie in diesem REST-API-Beispiel Suchdokumente (Vorschau), um die Anforderung zu formulieren.

1. Fügen Sie die folgende Anforderung als Vorlage in einen Webclient ein.

   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
   }
   

   • Ersetzen Sie search-service-name durch den Namen Ihres Suchdienstes.

   • Ersetzen Sie hotels-sample durch Ihren Indexnamen, wenn dieser anders ist.

   • Legen Sie "Suche" auf eine Volltextsuchabfrage fest. Die Sucheigenschaft ist für die Abfrageumschreibung erforderlich, es sei denn, Sie geben Vektorabfragen an. Wenn Sie Vektorabfragen angeben, muss der Text "search" mit der "text" Eigenschaft des "vectorQueries" Objekts übereinstimmen. Ihre Suchzeichenfolge kann entweder die einfache Syntax oder die vollständige Lucene-Syntax unterstützen.

   • Legen Sie "semanticConfiguration" auf eine vordefinierte semantische Konfiguration fest, die in Ihrem Index eingebettet ist.

   • Legen Sie "queryType" auf "semantisch" fest. Sie müssen entweder "queryType" auf "semantisch" festlegen oder eine nicht benötigte "semanticQuery"-Eigenschaft in die Anforderung einschließen. Die semantische Rangfolge ist für die Abfrageumschreibung erforderlich.

   • Legen Sie "queryRewrites" auf "generative|count-5" fest, um bis zu fünf Abfrageumschreibungen abzurufen. Sie können die Anzahl auf einen beliebigen Wert zwischen 1 und 10 festlegen.

   • Da Sie Abfrageumschreibungen anfordern, indem Sie die queryRewrites-Eigenschaft festlegen, müssen Sie „queryLanguage“ auf die Suchtextsprache festlegen. Der Suchdienst verwendet dieselbe Sprache für die Abfrageumschreibungen. In diesem Beispiel verwenden Sie "en-US". Die unterstützten Gebietsschemas sind: 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 und zh-TW.

   • Setzen Sie "debug" auf "queryRewrites", um die Abfrageumschreibungen in der Antwort zu erhalten.

     Tipp

     Legen Sie "debug": "queryRewrites" nur für Testzwecke fest. Verwenden Sie für eine bessere Leistung das Debuggen in der Produktion nicht.

   • Legen Sie "top" auf 1 fest, um nur das oberste Suchergebnis zurückzugeben.

2. Senden Sie die Anforderung, um die Abfrage auszuführen und Ergebnisse zurückzugeben.

Anschließend werten Sie die Suchergebnisse mit den Abfrageumformulierungen aus.

Auswerten der Antwort

Hier ist ein Beispiel für eine Antwort, die Abfrageumschreibungen enthält:

"@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 sind einige wichtige Punkte zu beachten:

• Da Sie die Eigenschaft "debug" zum Testen auf "queryRewrites" festlegen, enthält die Antwort ein @search.debug Objekt mit der Texteingabeabfrage und Abfrageumschreibungen.
• Da Sie die Eigenschaft "queryRewrites" auf "generative|count-5" festlegen, enthält die Antwort bis zu fünf Abfrageumschreibungen.
• Der "inputQuery" Wert ist die Abfrage, die an das generative Modell für die Abfrageumschreibung gesendet wird. Die Eingabeabfrage ist nicht immer mit der Abfrage des "search" Benutzers identisch.

Hier ist ein Beispiel für eine Antwort ohne Abfrageumschreibungen.

"@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
  }
]

Vektorabfragen mit Abfrageumschreibung

Sie können Vektorabfragen in Ihre Suchanforderung einschließen, um die Stichwortsuche und die Vektorsuche in eine einzelne Anforderung und eine einheitliche Antwort zu kombinieren.

Im Folgenden finden Sie ein Beispiel für eine Abfrage, die eine Vektorabfrage mit Abfrageumschreibungen enthält. Ändern Sie ein vorheriges Beispiel , um eine Vektorabfrage einzuschließen.

• Fügen Sie der Anforderung ein "vectorQueries"-Objekt hinzu. Dieses Objekt enthält eine Vektorabfrage, deren "Art" auf "Text" festgelegt ist.
• Der Wert "text" ist identisch mit dem Wert "search". Damit die Abfrageumschreibung funktioniert, müssen diese Werte identisch sein.

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
}

Die Antwort enthält Abfrageumschreibungen sowohl für die Textabfrage als auch für die Vektorabfrage.

Testen von Abfrageumschreibungen mit Debug

** Sie sollten Ihre Abfrageumschreibungen testen, um sicherzustellen, dass sie wie erwartet funktionieren. Legen Sie die "debug": "queryRewrites" Eigenschaft in Ihrer Abfrageanforderung fest, um die Abfrageumschreibungen in der Antwort abzurufen. Die Einstellung "debug" ist für Testzwecke optional. Um eine bessere Leistung zu erzielen, legen Sie diese Eigenschaft nicht in der Produktion fest.

Teilweise Antwortgründe

Möglicherweise stellen Sie fest, dass die Debug-(Test-)Antwort ein leeres Array für die Eigenschaften text.rewrites und vectors enthält.

{
  "@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
}

Im vorherigen Beispiel:

• Die Antwort enthält eine @search.semanticPartialResponseReason Eigenschaft mit dem Wert "Transient". Diese Meldung bedeutet, dass mindestens eine der Abfragen nicht abgeschlossen werden konnte.
• Die Antwort enthält auch eine @search.semanticQueryRewriteResultType Eigenschaft mit dem Wert "OriginalQueryOnly". Diese Meldung bedeutet, dass die Abfrageumschreibungen nicht verfügbar sind. Nur die ursprüngliche Abfrage wird zum Abrufen von Suchergebnissen verwendet.

Nächste Schritte

Die semantische Rangfolge kann in Hybridabfragen verwendet werden, die die Schlüsselwortsuche und die Vektorsuche in einer einzigen Anforderung und einer einheitlichen Antwort kombinieren.