Menambahkan sinonim di Pencarian Azure AI

Pada layanan pencarian, peta sinonim mengaitkan istilah yang setara, memperluas cakupan kueri tanpa pengguna harus benar-benar memberikan istilah. Misalnya, dengan asumsi anjing, canine, dan anak anjing dipetakan sebagai sinonim, kueri pada canine akan ditemukan dalam dokumen yang berisi anjing. Anda dapat membuat beberapa peta sinonim untuk berbagai bahasa, seperti versi bahasa Inggris dan Prancis, atau leksikon jika konten Anda menyertakan jargon teknis, bahasa slang, atau terminologi yang tidak jelas.

Beberapa poin penting tentang peta sinonim:

• Peta sinonim adalah sumber daya tingkat atas yang dapat dibuat sekali dan digunakan oleh banyak indeks.
• Peta sinonim berlaku untuk bidang string.
• Anda dapat membuat dan menetapkan peta sinonim kapan saja tanpa gangguan pada pengindeksan atau kueri.
• Tingkat layanan Anda menetapkan batasan jumlah peta sinonim yang dapat Anda buat.
• Layanan pencarian Anda dapat memiliki beberapa peta sinonim, tetapi dalam indeks, definisi bidang hanya dapat memiliki satu penetapan peta sinonim.

Membuat peta sinonim

Peta sinonim terdiri dari nama, format, dan aturan yang berfungsi sebagai entri peta sinonim. Satu-satunya format yang didukung adalah solr, dan solr format menentukan konstruksi aturan.

Untuk membuat peta sinonim, lakukan secara terprogram. Portal Azure tidak mendukung definisi peta sinonim.

POST /synonymmaps?api-version=2026-04-01
{
    "name": "geo-synonyms",
    "format": "solr",
    "synonyms": "
        USA, United States, United States of America\n
        Washington, Wash., WA => WA\n"
}

Menentukan aturan

Aturan pemetaan mematuhi spesifikasi filter sinonim sumber terbuka Apache Solr, yang dijelaskan dalam dokumen ini: SynonymGraphFilter. Format ini solr mendukung dua jenis aturan:

• kesetaraan (di mana istilah sama dengan pengganti dalam kueri)

• pemetaan eksplisit (di mana istilah dipetakan ke satu istilah eksplisit)

Setiap aturan dibatasi oleh karakter baris baru (\n). Anda dapat menentukan hingga 5.000 aturan per peta sinonim dalam layanan gratis dan 20.000 aturan per peta di tingkat lain. Setiap aturan dapat memiliki hingga 20 ekspansi, atau item dalam aturan. Untuk informasi selengkapnya, lihat Batas sinonim.

Parser kueri secara otomatis mengubah huruf besar atau huruf campuran menjadi huruf kecil pada istilah. Untuk mempertahankan karakter khusus dalam string, seperti koma atau tanda hubung, tambahkan karakter escape yang sesuai saat membuat peta sinonim.

Aturan kesetaraan

Aturan untuk istilah yang setara dibatasi koma dalam aturan yang sama. Dalam contoh pertama, kueri di AS diperluas ke AS ATAU "Amerika Serikat" ATAU "Amerika Serikat Amerika." Jika Anda ingin mencocokkan pada frasa, kueri itu sendiri harus menjadi kueri frasa yang diapit kutipan.

Dalam kasus kesetaraan, kueri untuk anjing memperluas kueri untuk juga menyertakan anak anjing dan anjing.

{
"format": "solr",
"synonyms": "
    USA, United States, United States of America\n
    dog, puppy, canine\n
    coffee, latte, cup of joe, java\n"
}

Pemetaan eksplisit

Aturan untuk pemetaan eksplisit ditandai dengan panah =>. Ketika ditentukan, urutan istilah dari kueri pencarian yang sesuai dengan sisi kiri => diganti dengan alternatif di sisi kanan saat pemrosesan kueri.

Dalam kasus eksplisit, kueri untuk Washington, Wash. atau WA ditulis ulang sebagai WA, dan mesin kueri hanya mencari kecocokan pada istilah WA. Pemetaan eksplisit hanya berlaku dalam arah yang ditentukan, dan tidak mengubah kueri WA menjadi Washington dalam hal ini.

{
"format": "solr",
"synonyms": "
    Washington, Wash., WA => WA\n
    California, Calif., CA => CA\n"
}

Melarikan karakter khusus

Sinonim dianalisis selama pemrosesan kueri sama seperti istilah kueri lainnya, yang berarti bahwa aturan untuk karakter khusus dan khusus berlaku untuk istilah dalam peta sinonim Anda. Daftar karakter yang memerlukan pelepasan bervariasi antara sintaks sederhana dan sintaks penuh:

• sintaks sederhana+ | " ( ) ' \
• sintaks penuh+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

Untuk melestarikan karakter yang dibuang oleh penganalisis default, ganti dengan penganalisis yang melestarikannya. Beberapa pilihan termasuk Penganalisis bahasa alami Microsoft, yang mempertahankan kata-kata yang dipenggal, atau penganalisis kustom untuk pola yang lebih kompleks. Untuk informasi selengkapnya, lihat Istilah parsial, pola, dan karakter khusus.

Contoh berikut menunjukkan contoh cara melakukan escape karakter dengan garis miring terbalik:

{
    "format": "solr",
    "synonyms": "WA\, USA, WA, Washington\n"
}

Karena tanda garis miring terbalik itu sendiri adalah karakter khusus dalam bahasa lain seperti JSON dan C#, Anda mungkin perlu menggandakan pelarian. Berikut adalah contoh di JSON:

{
    "format":"solr",
    "synonyms": "WA\\, USA, WA, Washington"
}

Mengelola peta sinonim

Anda dapat memperbarui peta sinonim tanpa mengganggu beban kerja kueri dan pengindeksan. Namun, setelah Anda menambahkan peta sinonim ke bidang, jika Anda kemudian menghapus peta sinonim, kueri apa pun yang menyertakan bidang yang dimaksud gagal dengan kesalahan 404.

Membuat, memperbarui, dan menghapus peta sinonim selalu merupakan operasi seluruh dokumen. Anda tidak dapat memperbarui atau menghapus bagian peta sinonim secara bertahap. Hanya memperbarui satu aturan pun memerlukan pemuatan ulang.

Menetapkan sinonim pada kolom data

Setelah Anda membuat peta sinonim, tetapkan ke bidang di indeks Anda. Untuk menetapkan peta sinonim, lakukan secara terprogram. Portal Azure tidak mendukung asosiasi bidang peta sinonim.

• Bidang harus berjenis Edm.String atau Collection(Edm.String)
• Bidang harus memiliki "searchable":true
• Bidang hanya dapat memiliki satu peta sinonim

Jika peta sinonim ada di layanan pencarian, peta tersebut digunakan pada kueri berikutnya, tanpa perlu mengindeks ulang atau membangun ulang.

PUT /indexes?api-version=2026-04-01
{
    "name":"hotels-sample",
    "fields":[
        {
            "name":"description",
            "type":"Edm.String",
            "searchable":true,
            "synonymMaps":[
            "en-synonyms"
            ]
        },
        {
            "name":"description_fr",
            "type":"Edm.String",
            "searchable":true,
            "analyzer":"fr.microsoft",
            "synonymMaps":[
            "fr-synonyms"
            ]
        }
    ]
}

// Update an index
string indexName = "hotels";
SearchIndex index = new SearchIndex(indexName)
{
    Fields =
    {
        new SimpleField("hotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true },
        new SearchableField("hotelName") { IsFilterable = true, IsSortable = true },
        new SearchableField("description") { AnalyzerName = LexicalAnalyzerName.EnLucene },
        new SearchableField("descriptionFr") { AnalyzerName = LexicalAnalyzerName.FrLucene }
        new ComplexField("address")
        {
            Fields =
            {
                new SearchableField("streetAddress"),
                new SearchableField("city") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("stateProvince") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("country") { SynonymMapNames = new[] { synonymMapName }, IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("postalCode") { IsFilterable = true, IsSortable = true, IsFacetable = true }
            }
        }
    }
};

await indexClient.CreateIndexAsync(index);

Melakukan kueri pada bidang yang setara atau dipetakan

Penetapan bidang sinonim tidak mengubah cara Anda menulis kueri. Setelah penetapan peta sinonim, satu-satunya perbedaan adalah bahwa jika istilah kueri ada di peta sinonim, mesin pencari memperluas atau menulis ulang istilah atau frasa, tergantung pada aturan.

Bagaimana sinonim digunakan selama eksekusi kueri

Sinonim adalah teknik perluasan kueri yang melengkapi konten indeks dengan istilah yang setara, tetapi hanya untuk bidang yang memiliki penetapan sinonim. Jika kueri berskala bidang mengecualikan bidang yang mendukung sinonim, Anda tidak melihat kecocokan dari peta sinonim.

Untuk bidang yang diaktifkan sinonim, sinonim tunduk pada analisis teks yang sama dengan bidang terkait. Misalnya, jika bidang dianalisis menggunakan penganalisis Lucene standar, istilah sinonim juga tunduk pada penganalisis Lucene standar pada waktu kueri. Jika Anda ingin mempertahankan tanda baca, seperti titik atau tanda hubung, dalam istilah sinonim, terapkan pengolah konten pada bidang tersebut.

Secara internal, fitur sinonim menulis ulang kueri asli dengan sinonim dengan menggunakan operator OR. Untuk alasan ini, penyorotan hasil pencarian dan profil penilaian skor memperlakukan istilah asli dan sinonim sebagai setara.

Sinonim hanya berlaku untuk kueri teks bentuk bebas dan tidak didukung untuk filter, bidang, pelengkapan otomatis, atau rekomendasi. Pelengkapan otomatis dan saran hanya didasarkan pada istilah asli; kecocokan sinonim tidak muncul dalam respons.

Jika Anda memiliki indeks yang ada di lingkungan pengembangan (nonproduksi), bereksperimenlah dengan kamus kecil untuk melihat bagaimana penambahan sinonim mengubah pengalaman pencarian, termasuk dampak pada profil penilaian, penyorotan hit, dan saran.

Pencarian kartubebas

Ekspansi sinonim tidak berlaku untuk istilah pencarian wildcard; istilah prefix, fuzzy, dan regex tidak diperluas.

Jika Anda perlu melakukan satu query yang menerapkan ekspansi sinonim dan pencarian wildcard, regex, atau fuzzy, Anda dapat menggabungkan query menggunakan sintaksis OR. Misalnya, untuk menggabungkan sinonim dengan wildcard untuk sintaksis kueri sederhana, istilahnya adalah <query> | <query>*.

Langkah selanjutnya