Menambahkan sinonim di Azure AI Search

Pada layanan pencarian, peta sinonim mengaitkan istilah yang setara, memperluas cakupan kueri tanpa pengguna harus benar-benar memberikan istilah. Misalnya, dengan asumsi anjing, anjing, dan anak anjing dipetakan sinonim, kueri tentang kecocokan anjing pada 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 tidak mendukung definisi peta sinonim.

REST

Gunakan Buat Peta Sinonim (REST API) untuk membuat peta sinonim.

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

.NET

Gunakan kelas SynonymMap (.NET) dan Buat peta sinonim (sampel Azure SDK) untuk membuat peta.

Python

Gunakan kelas SynonymMap (Python) untuk membuat peta.

Java

Gunakan kelas SynonymMap (Java) untuk membuat peta.

JavaScript

Gunakan antarmuka SynonymMap (JavaScript) untuk membuat peta.

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.

Pengurai kueri secara otomatis menurunkan huruf besar atau campuran 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." Perhatikan bahwa jika Anda ingin mencocokkan pada frasa, kueri itu sendiri harus berupa 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 =>. Saat ditentukan, urutan istilah kueri pencarian yang cocok dengan sisi => kiri diganti dengan alternatif di sisi kanan pada waktu 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 menulis ulang wa kueri ke Washington dalam hal ini.

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

Pelepasan 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 mempertahankan karakter yang dibuang penganalisis default, ganti penganalisis yang mempertahankannya. 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 garis miring terbelakang itu sendiri adalah karakter khusus dalam bahasa lain seperti JSON dan C#, Anda mungkin perlu melepaskannya kembali. 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 ke bidang

Setelah Anda membuat peta sinonim, tetapkan ke bidang di indeks Anda. Untuk menetapkan peta sinonim, lakukan secara terprogram. Portal 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.

REST

Gunakan Buat atau Perbarui Indeks (REST API) untuk mengubah definisi bidang.

PUT /indexes?api-version=2024-07-01
{
    "name":"hotels-sample-index",
    "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"
            ]
        }
    ]
}

.NET SDK

Gunakan SearchIndexClient untuk memperbarui indeks. Berikan seluruh definisi indeks dan sertakan parameter baru untuk penetapan peta sinonim.

Dalam contoh ini, country bidang memiliki synonymMapName properti .

// 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);

Untuk contoh selengkapnya, lihat mulai cepat/v11 di GitHub.

SDK Lainnya

Anda dapat menggunakan SDK yang didukung untuk memperbarui indeks pencarian. Semuanya menyediakan SearchIndexClient yang memiliki metode untuk memperbarui indeks.

Azure SDK	Klien	Contoh
Java	SearchIndexClient	CreateIndexExample.java
JavaScript	SearchIndexClient	Sampel JavaScript
Python	SearchIndexClient	sample_index_crud_operations.py

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 yang dilingkup bidang mengecualikan bidang berkemampuan 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 penganalisis yang mempertahankan konten di bidang.

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

Sinonim hanya berlaku untuk kueri teks bentuk bebas dan tidak didukung untuk filter, faset, lengkapi otomatis, atau saran. 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 kartubebas; awalan, fuzzy, dan istilah regex tidak diperluas.

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

Langkah selanjutnya

Membuat peta sinonim (REST API)