Riscrivere le query usando il ranker semantico in Azure AI Search (anteprima)

La riscrittura delle query (anteprima) è il processo di trasformazione della query di un utente in uno più efficace, aggiungendo altri termini e affinando i risultati della ricerca. Il servizio di ricerca invia la query di ricerca (o una variante di essa) a un modello generativo che genera query alternative.

La riscrittura delle query migliora i risultati dalla classificazione semantica correggendo errori di digitazione o ortografia nelle query utente ed espandendo le query con sinonimi.

La ricerca con riscrittura delle query funziona come segue:

• La query dell'utente viene inviata nella richiesta tramite la proprietà search.
• Il servizio di ricerca invia la query di ricerca (o una variante di essa) a un modello generativo che genera query alternative.
• Il servizio di ricerca usa la query originale e le query riscritte per recuperare i risultati della ricerca.

La riscrittura delle query è una funzionalità facoltativa. Senza riscrittura delle query, il servizio di ricerca usa solo la query originale per recuperare i risultati della ricerca.

Prerequisiti

• Ricerca di Azure AI in qualsiasi area che fornisce riscrittura della query.

• Indice di ricerca esistente con una configurazione semantica e contenuto di testo ricco. Gli esempi in questa guida usano l'indice hotels-sample per illustrare la riscrittura delle query.

• Per seguire le istruzioni in questo articolo, è necessario un client Web che supporta le richieste api REST. Gli esempi in questo articolo sono stati testati con Visual Studio Code e l'estensione REST Client.

Effettuare una richiesta di ricerca con riscrittura della query

In questo esempio di API REST usare Cerca documenti (anteprima) per formulare la richiesta.

1. Incollare la richiesta seguente in un client Web come modello.

   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
   }
   

   • Sostituire search-service-name con il nome del servizio di ricerca.

   • Sostituire hotels-sample con il nome dell'indice, se questo dovesse essere diverso.

   • Impostare "search" su una query di ricerca testo completo. La proprietà di ricerca è necessaria per la riscrittura delle query, a meno che non si specifichino query vettoriali. Se si specificano query vettoriali, il testo "search" deve corrispondere alla "text" proprietà dell'oggetto "vectorQueries" . La stringa di ricerca può supportare la sintassi semplice o la sintassi Lucene completa.

   • Impostare "semanticConfiguration" su una configurazione semantica predefinita incorporata nell'indice.

   • Impostare "queryType" su "semantic". È necessario impostare "queryType" su "semantico" o includere una proprietà "semanticQuery" non vuota nella richiesta. La classificazione semantica è necessaria per la riscrittura delle query.

   • Impostare "queryRewrites" su "generative|count-5" per ottenere fino a cinque riscritture di query. È possibile impostare il conteggio su qualsiasi valore compreso tra 1 e 10.

   • Poiché è stata richiesta la riscrittura della query impostando la proprietà "queryRewrites", è necessario impostare "queryLanguage" sulla lingua del testo di ricerca. Il servizio di ricerca usa la stessa lingua per la riscrittura della query. In questo esempio si usa "en-US". Le impostazioni locali supportate sono: 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.

   • Imposta "debug" su "queryRewrites" per ottenere le riscritture della query nella risposta.

     Suggerimento

     Imposta "debug": "queryRewrites" solo per test. Per prestazioni migliori, non usare il debug nell'ambiente di produzione.

   • Impostare "top" su 1 per restituire solo il risultato della ricerca principale.

2. Inviare la richiesta per eseguire la query e restituire i risultati.

Successivamente, si valutano i risultati della ricerca con la riscrittura della query.

Valutare la risposta

Di seguito è riportato un esempio di risposta che include riscrittura delle query:

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

Ecco alcuni punti chiave da notare:

• Poiché si imposta la proprietà "debug" su "queryRewrites" per il test, la risposta include un oggetto @search.debug con la query di input testuale e le riscritture delle query.
• Poiché si imposta la proprietà "queryRewrites" su "generative|count-5", la risposta include fino a cinque riscritture di query.
• Il valore di "inputQuery" è la query inviata al modello generativo per la riscrittura delle query. La query di input non coincide sempre con quella dell'utente "search".

Di seguito è riportato un esempio di risposta senza riscrittura della query.

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

Query vettoriali con riscrittura delle query

È possibile includere query vettoriali nella richiesta di ricerca per combinare la ricerca di parole chiave e la ricerca vettoriale in una singola richiesta e una risposta unificata.

Di seguito è riportato un esempio di query che include una query vettoriale con riscrittura della query. Modificare un esempio precedente per includere una query vettoriale.

• Aggiungere un oggetto "vectorQueries" alla richiesta. Questo oggetto include una query vettoriale con il campo "kind" impostato su "text".
• Il valore "text" corrisponde al valore "search". Questi valori devono essere identici per il funzionamento della riscrittura delle query.

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
}

La risposta include riscritture di query sia per la query di testo che per la query vettoriale.

Verificare le riscritture delle query in debug

È consigliabile testare le riscritture della query per assicurarsi che funzionino come previsto. Impostare la proprietà "debug": "queryRewrites" nella richiesta di query per ottenere le riscritture della query nella risposta. L'impostazione "debug" è facoltativa a scopo di test. Per prestazioni migliori, non impostare questa proprietà nell'ambiente di produzione.

Motivi di risposta parziali

È possibile osservare che la risposta di debug (test) include una matrice vuota per le text.rewrites proprietà e vectors .

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

Nell'esempio precedente:

• La risposta include una @search.semanticPartialResponseReason proprietà con valore "Transient". Questo messaggio indica che almeno una delle query non è riuscita a completare.
• La risposta include anche una @search.semanticQueryRewriteResultType proprietà con valore "OriginalQueryOnly". Questo messaggio indica che le riscritture della query non sono disponibili. Solo la query originale viene usata per recuperare i risultati della ricerca.

Passaggi successivi

La classificazione semantica può essere usata nelle query ibride che combinano la ricerca di parole chiave e la ricerca vettoriale in una singola richiesta e in una risposta unificata.