Pelengkapan otomatis (Azure AI Search REST API)

Artikel
03/05/2024

API Pelengkapan Otomatis menyelesaikan input kueri yang ditik sebagian menggunakan istilah yang ada dalam indeks pencarian untuk digunakan dalam kueri sekunder. Misalnya, jika input kueri adalah "medic", API Lengkapi Otomatis mengembalikan "medicare", , "medicaid""medicine" jika istilah tersebut ada dalam indeks. Secara internal, mesin pencari mencari istilah yang cocok dalam bidang yang memiliki Saran yang dikonfigurasi.

HTTPS diperlukan untuk permintaan layanan. Permintaan Pelengkapan Otomatis dapat dibuat menggunakan metode GET atau POST.

GET https://[service name].search.windows.net/indexes/[index name]/docs/autocomplete?[query parameters]
  Content-Type: application/json   
  api-key: [admin or query key]

POST https://[service name].search.windows.net/indexes/[index name]/docs/autocomplete?api-version=[api-version]
  Content-Type: application/json   
  api-key: [admin or query key]

Ketika dipanggil dengan GET, panjang URL permintaan tidak boleh melebihi 8 KB. Panjang ini biasanya cukup untuk sebagian besar aplikasi. Namun, beberapa aplikasi menghasilkan kueri yang sangat besar, khususnya ketika ekspresi filter OData digunakan. Untuk aplikasi ini, HTTP POST adalah pilihan yang lebih baik karena memungkinkan filter yang lebih besar daripada GET.

Dengan POST, jumlah klausul dalam filter adalah faktor pembatas, bukan ukuran string filter mentah karena batas ukuran permintaan untuk POST adalah sekitar 16 MB. Meskipun batas ukuran permintaan POST sangat besar, ekspresi filter tidak bisa sangat kompleks. Untuk informasi selengkapnya tentang batasan kompleksitas filter, lihat Sintaks Ekspresi OData untuk Pencarian Azure AI.

Parameter URI

Parameter	Deskripsi
[nama layanan]	Wajib diisi. Atur ini ke nama unik yang ditentukan pengguna dari layanan pencarian Anda.
[nama indeks]/dokumen	Wajib diisi. Menentukan kumpulan dokumen dari indeks bernama.
versi-api	Wajib diisi. Lihat versi API untuk daftar versi yang didukung. Untuk kueri, versi api selalu ditentukan sebagai parameter URI untuk GET dan POST.

Rekomendasi pengodean URL

Ingatlah untuk mengodekan URL parameter kueri tertentu saat memanggil GET REST API secara langsung. Untuk Pelengkapan otomatis, pengodean URL mungkin diperlukan untuk parameter kueri berikut:

pencarian
$filter
highlightPreTag
highlightPostTag

Pengodean URL hanya direkomendasikan untuk parameter individual. Jika Anda secara tidak sengaja mengodekan URL seluruh string kueri (semuanya setelah ?), permintaan akan rusak.

Selain itu, pengodean URL hanya diperlukan saat memanggil REST API secara langsung menggunakan GET. Tidak ada pengodean URL yang diperlukan saat menggunakan POST, atau saat menggunakan pustaka klien Azure AI Search .NET, yang menangani pengodean untuk Anda.

Judul Permintaan

Tabel berikut ini menjelaskan header permintaan yang diperlukan dan opsional.

Bidang	Deskripsi
Jenis-Konten	Wajib diisi. Atur titik akhir ini ke `application/json`
api-key	Opsional jika Anda menggunakan peran Azure dan token pembawa disediakan berdasarkan permintaan, jika tidak, kunci diperlukan. Permintaan kueri terhadap `docs` koleksi dapat menentukan kunci admin atau kunci kueri sebagai `api-key`. Kunci kueri digunakan untuk operasi baca-saja pada kumpulan dokumen indeks. Lihat Menyambungkan ke Azure AI Search menggunakan autentikasi kunci untuk detailnya.

Isi Permintaan

Untuk GET: None.

Untuk POST:

{  
  "autocompleteMode": "oneTerm" (default) | "twoTerms" | "oneTermWithContext",
  "filter": "odata_filter_expression",
  "fuzzy": true | false (default),  
  "highlightPreTag": "pre_tag",  
  "highlightPostTag": "post_tag",  
  "minimumCoverage": # (% of index that must be covered to declare query successful; default 80),
  "search": "partial_search_input",  
  "searchFields": "field_name_1, field_name_2, ...",
  "suggesterName": "suggester_name",  
  "top": # (default 5)  
}

Parameter kueri

Kueri menerima beberapa parameter pada URL saat dipanggil dengan GET, dan sebagai properti JSON di isi permintaan saat dipanggil dengan POST. Sintaks untuk beberapa parameter sedikit berbeda antara GET dan POST. Perbedaan ini dicatat sebagaimana berlaku di bawah ini.

Nama	Jenis	Deskripsi
versi-api	string	Wajib diisi. Versi REST API yang digunakan untuk permintaan tersebut. Untuk daftar versi yang didukung, lihat Penerapan versi API. Untuk operasi ini, versi api ditentukan sebagai parameter URI terlepas dari apakah Anda memanggil Lengkapi Otomatis dengan GET atau POST.
autocompleteMode	string	Opsional. Default ke oneTerm. Nilai yang valid adalah oneTerm, twoTerms, oneTermWithContext. oneTerm mengembalikan satu istilah. Jika kueri memiliki dua istilah, hanya istilah terakhir yang selesai. Misalnya, mengingat `"washington medic"`, responsnya mungkin salah satu dari istilah tunggal ini: `"medicaid"`, , `"medicare""medicine"`. twoTerms cocok pada frasa dua istilah dalam indeks. Misalnya, diberikan `"medic"`, responsnya mungkin `"medicare coverage"`, atau `"medical assistant"`. Dalam banyak kasus, istilah `"medicare"` tunggal atau `"medical"` tidak akan dikembalikan karena preferensi diberikan ke frasa dua istilah yang cocok. oneTermWithContext menyelesaikan istilah terakhir dalam kueri dengan dua istilah atau lebih, di mana dua istilah terakhir adalah frasa yang ada dalam indeks. Misalnya, diberikan `"washington medic"`, responsnya mungkin `"washington medicaid"`, `"washington medical"`.
$filter	string	Opsional. Ekspresi pencarian terstruktur dalam sintaks OData standar yang memfilter dokumen yang dipertimbangkan untuk menghasilkan saran istilah lengkap. Ekspresi filter "search.ismatch" dan "search.ismatchscoring*" tidak didukung di API Lengkapi Otomatis. Hanya bidang yang dapat difilter yang dapat digunakan dalam filter. Ketika dipanggil dengan POST, parameter ini diberi nama filter alih-alih $filter. Lihat Sintaks Ekspresi OData untuk Pencarian Azure AI untuk detail tentang subset tata bahasa ekspresi OData yang didukung Azure AI Search.
Fuzzy	boolean	Opsional. Default ke false. Ketika diatur ke true, API ini menemukan saran meskipun ada karakter yang diganti atau hilang dalam teks pencarian ⁽¹⁾. Ini memberikan pengalaman yang lebih baik dalam beberapa skenario tetapi datang dengan biaya performa karena pencarian saran fuzzy lebih lambat dan mengonsumsi lebih banyak sumber daya.
highlightPostTag	string	Opsional. Default ke string kosong. Tag string yang ditambahkan ke istilah yang disorot. Harus diatur dengan highlightPreTag. Karakter yang dicadangkan dalam URL harus dikodekan persen (misalnya, %23, bukan #). Ketika dipanggil menggunakan GET, karakter yang dipesan dalam URL harus dikodekan persen (misalnya, %23 alih-alih #).
highlightPreTag	string	Opsional. Default ke string kosong. Tag string yang ditambahkan ke istilah yang disorot. Harus diatur dengan highlightPostTag. Ketika dipanggil menggunakan GET, karakter yang dipesan dalam URL harus dikodekan persen (misalnya, %23 alih-alih #).
minimumCoverage	bilangan bulat	Opsional. Default ke 80. Angka antara 0 dan 100 menunjukkan persentase indeks yang harus tersedia untuk melayani kueri sebelum dapat dilaporkan sebagai keberhasilan. Default mencerminkan bias terhadap kecepatan dan efisiensi atas cakupan penuh. Mengurangi cakupan membatasi ekspansi kueri, memungkinkan hasil untuk kembali lebih cepat. Ini juga memungkinkan kueri untuk berhasil pada ketersediaan indeks parsial, bahkan jika satu pecahan lambat merespons atau tidak tersedia karena masalah kesehatan layanan atau pemeliharaan indeks. Apa pun nilai minimumCoverage, persentase indeks tersebut harus tersedia atau Lengkapi Otomatis mengembalikan kode status HTTP 503. Jika Pelengkapan Otomatis berhasil pada tingkat minimumCoverage, ini mengembalikan HTTP 200 dan menyertakan @search.coverage nilai dalam respons yang menunjukkan persentase indeks yang tersedia saat melayani kueri. Menurunkan nilai ini mungkin berguna jika terjadi kesalahan 503. Jika tidak, Anda mungkin mempertimbangkan untuk menaikkan nilai jika respons memberikan kecocokan yang tidak mencukupi.
pencarian	string	Wajib diisi. Teks yang akan dicari. Teks pencarian untuk diselesaikan. Harus minimal 1 karakter, dan tidak lebih dari 100 karakter. Ini tidak boleh berisi operator, sintaks kueri, atau frasa yang dikutip.
searchFields	string	Opsional. Daftar nama bidang yang dipisahkan koma untuk mencari teks pencarian yang ditentukan. Bidang target harus tercantum dalam definisi Pemberi Saran dalam indeks.
suggesterName	string	Wajib diisi. Nama pemberi saran seperti yang ditentukan dalam koleksi Pemberi Saran yang menjadi bagian dari definisi indeks. Pemberi saran menentukan bidang mana yang dipindai untuk istilah kueri yang disarankan.
$top	bilangan bulat	Pilihan. Default ke 5. Jumlah saran yang diselesaikan secara otomatis untuk diambil. Nilai harus berupa angka antara 1 dan 100. Ketika dipanggil dengan POST, parameter ini dinamai teratas alih-alih $top.

(1) Batasan fuzzy dalam Pelengkapan Otomatis:

Pertama, jarak edit terbatas hanya pada satu perbedaan karakter per token tidak seperti parameter fuzzy dalam pencarian. Membatasi jarak edit ke satu karakter berarti tidak semua kecocokan kandidat akan ditemukan, tetapi batasnya diperlukan untuk memastikan tingkat performa yang dapat diterima.

Kedua, langkah fuzzy terjadi setelah ekspansi token parsial dan hanya istilah dari shard indeks yang sama yang dipertimbangkan untuk kecocokan fuzzy. Kendala ini meningkatkan performa API Lengkapi Otomatis dengan menghilangkan agregasi kecocokan fuzzy di semua pecahan. Batasan ini menjadi kurang terlihat karena lebih banyak istilah ditambahkan ke indeks, menghasilkan distribusi istilah yang sama untuk setiap shard. Karena istilah didistribusikan secara merata, kecocokan fuzzy dalam pecahan adalah perkiraan yang baik dari kecocokan fuzzy di seluruh indeks. Namun, hasilnya bisa lebih rendah jika indeks memiliki lebih sedikit istilah, seperti dalam indeks pengujian atau prototipe, yang menghasilkan representasi yang tidak merata di seluruh pecahan. Untuk informasi selengkapnya tentang bagaimana indeks dibagi menjadi pecahan, lihat kombinasi partisi dan replika.

Respons

Kode Status: "200 OK" dikembalikan untuk respons yang berhasil.

Payload respons memiliki dua properti.

Properti	Deskripsi
"teks"	Istilah atau frasa yang telah selesai
"queryPlusText"	Input kueri awal ditambah istilah atau frasa yang telah selesai

{  
  "@search.coverage": # (if minimumCoverage was provided in the query),  
  "value": [
    {
      "text": "...",
      "queryPlusText": "..."
    },
    ...  
  ]
}

Contoh

Contoh 1: Ambil tiga saran lengkapi otomatis di mana input pencarian parsial adalah 'washington medic' dengan mode default (oneTerm):

GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&api-version=2020-06-30

POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{  
  "search": "washington medic",
  "filter": "search.in(roleId, 'admin,manager')",
  "top": 3,
  "suggesterName": "sg"  
}

Respons:

{    
  "value": [
    {
      "text": "medicaid",
      "queryPlusText": "washington medicaid"
    },
    {
      "text": "medicare",
      "queryPlusText": "washington medicare"
    },
    {
      "text": "medicine",
      "queryPlusText": "washington medicine"
    }
  ]
}

Contoh 2: Ambil tiga saran lengkapi otomatis di mana input pencarian parsial adalah 'washington medic' dan autocompleteMode=twoTerms:

GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&autocompleteMode=twoTerms&api-version=2020-06-30

POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{  
  "search": "washington medic",  
  "autocompleteMode": "twoTerms",
  "filter": "planDuration ge 1",
  "top": 3,  
  "suggesterName": "sg"  
}