Menulis ulang kueri dengan peringkat semantik di Pencarian Azure AI (pratinjau)

Catatan

Pencarian Azure AI tersedia melalui portal Azure, REST API, dan Azure SDK. Ini juga mendukung Foundry IQ, lapisan pengetahuan terkelola yang mengubah konten perusahaan menjadi pangkalan pengetahuan yang dapat digunakan kembali dan sadar izin untuk agen di portal Microsoft Foundry.

Important

Fitur, kemampuan, atau properti yang ditandai (pratinjau) tidak tercakup dalam perjanjian tingkat layanan, tidak disarankan untuk beban kerja produksi, dan mungkin berubah atau dibatasi sebelum tersedia secara umum. Ketentuan pratinjau Pencarian Azure AI berlaku untuk semua fungsionalitas pratinjau, baik itu mandiri atau bagian dari fitur yang tersedia secara umum.

Penulisan ulang kueri (pratinjau) adalah proses mengubah kueri pengguna menjadi yang lebih efektif, menambahkan lebih banyak istilah dan menyempurnakan hasil pencarian. Layanan pencarian mengirimkan kueri pencarian (atau variasinya) ke model generatif yang menghasilkan kueri alternatif.

Penulisan ulang kueri meningkatkan hasil dari peringkat semantik dengan mengoreksi kesalahan ketik atau kesalahan ejaan dalam kueri pengguna, dan memperluas kueri dengan sinonim.

Cari dengan penulisan ulang kueri berfungsi seperti ini:

  • Kueri pengguna dikirim melalui properti search dalam permintaan.
  • Layanan pencarian mengirimkan kueri pencarian (atau variasinya) ke model generatif yang menghasilkan kueri alternatif.
  • Layanan pencarian menggunakan kueri asli dan kueri yang ditulis ulang untuk mengambil hasil pencarian.

Penulisan ulang kueri adalah fitur opsional. Tanpa penulisan ulang kueri, layanan pencarian hanya menggunakan kueri asli untuk mengambil hasil pencarian.

Catatan

Kueri yang ditulis ulang mungkin tidak berisi semua istilah yang tepat yang dimiliki kueri asli. Ini mungkin berdampak pada hasil pencarian jika kueri sangat spesifik dan diperlukan kecocokan yang tepat untuk pengidentifikasi unik atau kode produk.

Prasyarat

Tips

Konten yang mencakup penjelasan atau definisi berfungsi paling baik untuk peringkat semantik.

Membuat permintaan pencarian dengan penulisan ulang kueri

Dalam contoh REST API ini, gunakan Dokumen Pencarian (pratinjau) untuk merumuskan permintaan.

  1. Tempelkan permintaan berikut ke klien web sebagai templat.

    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
}

    • Ganti search-service-name dengan nama layanan pencarian Anda.

    • Ganti hotels-sample dengan nama indeks Anda jika berbeda.

    • Atur "cari" ke kueri pencarian teks lengkap. Properti pencarian diperlukan untuk penulisan ulang kueri, kecuali Anda menentukan kueri vektor. Jika Anda menentukan kueri vektor, maka teks "pencarian" harus cocok dengan "text" properti "vectorQueries" objek. String pencarian Anda dapat mendukung sintaksis sederhana atau sintaks Lucene penuh.

    • Atur "semanticConfiguration" ke konfigurasi semantik yang telah ditentukan sebelumnya yang disematkan dalam indeks Anda.

    • Tetapkan "queryType" menjadi "semantik". Anda perlu mengatur "queryType" ke "semantik" atau menyertakan properti "semanticQuery" yang tidak kosong dalam permintaan. Peringkat semantik diperlukan untuk penulisan ulang kueri.

    • Atur "queryRewrites" ke "generative|count-5" untuk mendapatkan hingga lima penulisan ulang kueri. Anda dapat mengatur hitungan ke nilai apa pun antara 1 dan 10.

    • Karena Anda meminta penulisan ulang kueri dengan mengatur properti "queryRewrites", Anda harus mengatur "queryLanguage" ke bahasa teks pencarian. Layanan pencarian menggunakan bahasa yang sama untuk penulisan ulang kueri. Dalam contoh ini, Anda menggunakan "en-US". Lokal yang didukung adalah: 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.

    • Atur "debug" ke "queryRewrites" untuk mendapatkan penulisan ulang kueri dalam respons.

      Tips

      Hanya tetapkan "debug": "queryRewrites" untuk tujuan pengujian. Untuk performa yang lebih baik, jangan gunakan debug dalam produksi.

    • Atur "atas" ke 1 untuk mengembalikan hanya hasil pencarian teratas.

  2. Kirim permintaan untuk menjalankan kueri dan mengembalikan hasil.

Selanjutnya, Anda mengevaluasi hasil pencarian dengan penulisan ulang kueri.

Mengevaluasi tanggapan

Berikut adalah contoh respons yang menyertakan penulisan ulang kueri:

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

Berikut adalah beberapa poin penting yang perlu diperhatikan:

  • Karena Anda mengatur properti "debug" ke "queryRewrites" untuk pengujian, respons menyertakan @search.debug objek dengan kueri input teks dan penulisan ulang kueri.
  • Karena Anda mengatur properti "queryRewrites" ke "generative|count-5", respons menyertakan hingga lima penulisan ulang kueri.
  • Nilai "inputQuery" adalah kueri yang dikirimkan ke model generatif untuk penulisan ulang kueri. Kueri masukan tidak selalu identik dengan kueri pengguna "search".

Berikut adalah contoh respons tanpa penulisan ulang kueri.

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

Kueri vektor dengan penulisan ulang kueri

Anda dapat menyertakan kueri vektor dalam permintaan pencarian Anda untuk menggabungkan pencarian kata kunci dan pencarian vektor ke dalam satu permintaan dan respons terpadu.

Berikut adalah contoh kueri yang menyertakan kueri vektor dengan penulisan ulang kueri. Ubah contoh sebelumnya untuk menyertakan kueri vektor.

  • Tambahkan objek "vectorQueries" ke permintaan. Objek ini mencakup kueri vektor dengan "jenis" yang ditetapkan sebagai "teks".
  • Nilai "teks" sama dengan nilai "pencarian". Nilai-nilai ini harus identik agar penulisan ulang kueri berfungsi.
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
}

Respons mencakup penulisan ulang kueri untuk kueri teks dan kueri vektor.

Uji penulisan ulang kueri dengan debug

Anda harus menguji penulisan ulang kueri Anda untuk memastikan bahwa kueri berfungsi seperti yang diharapkan. Atur properti "debug": "queryRewrites" dalam permintaan kueri Anda untuk menerima pembaruan kueri pada respons. Pengaturan "debug" bersifat opsional untuk tujuan pengujian. Agar performa lebih baik, jangan atur properti ini di lingkungan produksi.

Alasan respons parsial

Anda mungkin mengamati bahwa respons debug (pengujian) menyertakan array kosong untuk properti text.rewrites dan 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
}

Dalam contoh sebelumnya:

  • Respons mencakup @search.semanticPartialResponseReason properti dengan nilai "Sementara". Pesan ini berarti bahwa setidaknya salah satu kueri gagal diselesaikan.
  • Respons juga mencakup @search.semanticQueryRewriteResultType properti dengan nilai "OriginalQueryOnly". Pesan ini berarti bahwa penulisan ulang kueri tidak tersedia. Hanya kueri asli yang digunakan untuk mengambil hasil pencarian.

Langkah berikutnya

Peringkat semantik dapat digunakan dalam kueri hibrid yang menggabungkan pencarian kata kunci dan pencarian vektor ke dalam satu permintaan dan respons terpadu.

Kueri hibrid dengan ranker semantik

  • Terakhir diperbarui pada