Membuat indeks di Pencarian Azure AI

Dalam artikel ini, pelajari langkah-langkah untuk menentukan skema untuk indeks pencarian dan mendorongnya ke layanan pencarian. Membuat indeks menetapkan struktur data fisik pada layanan pencarian Anda. Setelah indeks ada, muat indeks sebagai tugas terpisah.

Prasyarat

• Sebuah langganan Azure. Buat akun gratis.

• Layanan Pencarian Azure AI, wilayah dan tingkat apa pun, tetapi harus merupakan tingkat yang dapat ditagih (Dasar atau lebih tinggi) untuk akses berbasis peran.

• Izin untuk membuat indeks: Peran Kontributor Layanan Pencarian atau kunci API admin untuk autentikasi berbasis kunci.

• Bidang unik dalam data sumber Anda yang dapat digunakan sebagai kunci dokumen dalam indeks.

• Pemahaman tentang skema data Anda. Lihat daftar periksa skema untuk panduan desain tentang membuat bidang yang dapat dicari, diambil, difilter, difaset, dan diurutkan.

Buat indeks

Saat Anda siap untuk membuat indeks, gunakan klien pencarian yang dapat mengirim permintaan. Anda dapat menggunakan API portal Azure atau REST untuk pengembangan awal dan pengujian bukti konsep, jika tidak, biasanya menggunakan Azure SDK.

Selama pengembangan, rencanakan pembangunan kembali yang sering. Karena struktur fisik dibuat dalam layanan, menghapus dan membuat ulang indeks diperlukan untuk banyak modifikasi. Anda mungkin mempertimbangkan untuk bekerja dengan subkumpulan data Anda agar rekonstruksi berjalan lebih cepat.

POST https://[servicename].search.windows.net/indexes?api-version=[api-version] 
{
  "name": "hotels",
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "retrievable": true, "searchable": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Address", "type": "Edm.ComplexType", 
      "fields": [
          { "name": "StreetAddress", "type": "Edm.String", "retrievable": true, "filterable": false, "sortable": false, "facetable": false, "searchable": true },
          { "name": "City", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "StateProvince", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": true, "sortable": true, "facetable": true }
        ]
    }
  ],
  "suggesters": [ ],
  "scoringProfiles": [ ],
  "analyzers":(optional)[ ... ]
}

using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

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

Memverifikasi pembuatan indeks

Setelah Anda membuat indeks, verifikasi bahwa indeks tersebut ada dengan mencantumkan indeks di layanan pencarian Anda.

GET https://[servicename].search.windows.net/indexes?api-version=[api-version]

// List all indexes to verify creation
var indexNames = indexClient.GetIndexNames();
foreach (var name in indexNames)
{
    Console.WriteLine(name);
}

Kunci dokumen

Pembuatan indeks pencarian memiliki dua persyaratan: indeks harus memiliki nama unik pada layanan pencarian, dan harus memiliki kunci dokumen. Atribut boolean key pada bidang dapat diatur ke true untuk menunjukkan bidang mana yang menyediakan kunci dokumen.

Kunci dokumen adalah pengidentifikasi unik dokumen pencarian, dan dokumen pencarian adalah kumpulan bidang yang sepenuhnya menjelaskan sesuatu. Misalnya, jika Anda mengindeks himpunan data film, dokumen pencarian berisi judul, genre, dan durasi satu film. Nama film unik dalam himpunan data ini, sehingga Anda dapat menggunakan nama film sebagai kunci dokumen.

Di Pencarian Azure AI, kunci dokumen adalah string, dan harus berasal dari nilai unik di sumber data yang menyediakan konten yang akan diindeks. Sebagai aturan umum, layanan pencarian tidak menghasilkan nilai kunci, tetapi dalam beberapa skenario (seperti pengindeks tabel Azure) layanan pencarian mensintesis nilai yang ada untuk membuat kunci unik untuk dokumen yang sedang diindeks. Skenario lain adalah pengindeksan satu ke banyak untuk data yang dipotong atau dipartisi, dalam hal ini kunci dokumen dihasilkan untuk setiap gugus.

Selama pengindeksan bertahap, di mana konten baru dan yang diperbarui diindeks, dokumen masuk dengan kunci baru ditambahkan, sementara dokumen masuk dengan kunci yang ada digabungkan atau ditimpa, tergantung pada apakah bidang indeks null atau diisi.

Poin penting tentang kunci dokumen meliputi:

• Panjang maksimum nilai dalam bidang kunci adalah 1.024 karakter.
• Tepat satu bidang tingkat atas di setiap indeks harus dipilih sebagai bidang kunci dan harus berjenis Edm.String.
• Nilai default atribut key adalah false untuk bidang sederhana dan null untuk bidang kompleks.

Bidang kunci dapat digunakan untuk mencari dokumen secara langsung dan memperbarui atau menghapus dokumen tertentu. Nilai dari bidang kunci ditangani secara case-sensitive saat mencari atau mengindeks dokumen. Lihat Dokumen GET (REST) dan Dokumen Indeks (REST) untuk detailnya.

Daftar periksa skema

Gunakan daftar periksa ini untuk membantu keputusan desain untuk indeks pencarian Anda.

1. Tinjau konvensi penamaan agar nama indeks dan bidang sesuai dengan aturan penamaan.

2. Tinjau jenis data yang didukung. Jenis data memengaruhi cara bidang digunakan. Misalnya, konten numerik dapat difilter tetapi tidak dapat dicari teks lengkap. Jenis data paling umum adalah Edm.String untuk teks yang dapat dicari, yang diberi token dan dikueri menggunakan mesin cari teks lengkap. Jenis data yang paling umum untuk bidang vektor adalah Edm.Single tetapi Anda juga dapat menggunakan jenis lain.

3. Berikan deskripsi indeks, maksimum 4.000 karakter. Teks yang dapat dibaca manusia ini sangat berharga ketika sistem harus mengakses beberapa indeks dan membuat keputusan berdasarkan deskripsi. Pertimbangkan server Protokol Konteks Model (MCP) yang harus memilih indeks yang benar pada waktu proses. Keputusan dapat didasarkan pada deskripsi daripada pada nama indeks saja.

4. Identifikasi kunci dokumen. Kunci dokumen merupakan syarat untuk indeks. Ini adalah bidang string tunggal yang diisi dari bidang data sumber yang berisi nilai unik. Misalnya, jika Anda mengindeks dari Blob Storage, jalur penyimpanan metadata sering digunakan sebagai kunci dokumen karena secara unik mengidentifikasi setiap blob dalam kontainer.

5. Identifikasi bidang di sumber data Anda yang berkontribusi konten yang dapat dicari dalam indeks.

   Konten nonvektor yang dapat dicari mencakup string pendek atau panjang yang dikueri menggunakan mesin pencari teks lengkap. Jika konten terlalu panjang (frasa kecil atau bagian besar), lakukan eksperimen dengan penganalisis berbeda untuk melihat bagaimana teks ditokenisasi.

   Konten vektor yang dapat dicari dapat berupa gambar atau teks (dalam bahasa apa pun) yang ada sebagai representasi matematika. Anda dapat menggunakan jenis data sempit atau kompresi vektor untuk membuat bidang vektor lebih kecil.

   Atribut yang diatur pada bidang, seperti retrievable atau filterable, menentukan perilaku pencarian dan representasi fisik indeks Anda pada layanan pencarian. Menentukan bagaimana bidang harus dikaitkan adalah proses berulang bagi banyak pengembang. Untuk mempercepat perulangan, mulai dengan contoh data agar Anda dapat menghilangkan dan membangun kembali dengan mudah.

6. Identifikasi bidang sumber mana yang dapat digunakan sebagai filter. Konten numerik dan bidang teks pendek, terutama yang memiliki nilai berulang, adalah pilihan yang baik. Saat bekerja dengan filter, ingatlah:

   • Filter dapat digunakan dalam kueri vektor dan nonvektor, tetapi filter itu sendiri diterapkan ke bidang yang dapat dibaca manusia (nonvektor) dalam indeks Anda.

   • Bidang yang dapat difilter dapat digunakan secara opsional dalam navigasi tersaring.

   • Bidang yang dapat difilter dikembalikan dalam urutan semena-mena dan tidak menjalani penilaian relevansi, jadi pertimbangkan untuk membuatnya dapat diurutkan juga.

7. Untuk bidang vektor, tentukan konfigurasi pencarian vektor dan algoritma yang digunakan untuk membuat jalur navigasi dan mengisi ruang penyematan. Untuk informasi selengkapnya, lihat Menambahkan bidang vektor.

   Bidang vektor memiliki properti tambahan yang tidak dimiliki bidang nonvektor, seperti algoritma mana yang akan digunakan dan kompresi vektor.

   Bidang vektor menghilangkan atribut yang tidak berguna pada data vektor, seperti pengurutan, pemfilteran, dan faset.

8. Untuk bidang nonvektor, tentukan apakah akan menggunakan penganalisis default ("analyzer": null) atau penganalisis yang berbeda. Penganalisis digunakan untuk tokenisasi bidang teks selama pengindeksan dan eksekusi kueri.

   Untuk string multibahasa, pertimbangkan penganalisis bahasa.

   Untuk string berhubung atau karakter khusus, pertimbangkan penganalisis khusus. Salah satu contohnya adalah kata kunci yang memperlakukan seluruh konten bidang sebagai token tunggal. Perilaku ini berguna untuk data seperti kode pos, ID, dan beberapa nama produk. Untuk informasi selengkapnya, lihat Pencarian dan pola istilah parsial dengan karakter khusus.

Mengonfigurasi definisi bidang

Kumpulan bidang menentukan struktur dokumen pencarian. Semua bidang memiliki nama, jenis data, dan atribut.

Mengatur bidang sebagai dapat dicari, dapat difilter, dapat diurutkan, atau dapat difaset memiliki efek pada ukuran indeks dan performa kueri. Jangan atur atribut tersebut pada bidang yang tidak dimaksudkan untuk direferensikan dalam ekspresi kueri.

Jika bidang tidak diatur agar dapat dicari, dapat difilter, dapat diurutkan, atau dapat difaset, bidang tidak dapat direferensikan dalam ekspresi kueri apa pun. Ini diinginkan untuk bidang yang tidak digunakan dalam kueri, tetapi diperlukan dalam hasil pencarian.

REST API memiliki atribusi default berdasarkan jenis data, yang juga digunakan oleh wizard Impor data di portal Microsoft Azure. Azure SDK tidak memiliki default, tetapi memiliki subkelas bidang yang menggabungkan properti dan perilaku, seperti SearchableField untuk string dan SimpleField untuk primitif.

Atribusi bidang default untuk REST API dirangkum dalam tabel berikut.

Bidang string juga dapat dikaitkan secara opsional dengan penganalisis dan peta sinonim. Bidang jenis Edm.String yang dapat difilter, dapat diurutkan, atau dapat difaset dapat memiliki panjang paling banyak 32 kilobyte. Ini karena nilai bidang tersebut diperlakukan sebagai istilah pencarian tunggal, dan panjang maksimum istilah di Pencarian Azure AI adalah 32 kilobyte. Jika Anda perlu menyimpan lebih banyak teks daripada ini dalam satu bidang string, Anda harus secara eksplisit mengatur dapat difilter, dapat diurutkan, dan dapat difaset ke false dalam definisi indeks Anda.

Bidang vektor harus dikaitkan dengan dimensi dan profil vektor. Jika Anda menambahkan bidang vektor menggunakan wizard Impor data di portal Azure, "Retrievable" berarti "true" (benar) sebagai default. Jika Anda menggunakan REST API, itu salah.

Atribut bidang dijelaskan dalam tabel berikut.

Pembaruan yang diizinkan pada indeks yang ada

Buat Indeks membuat struktur data fisik (file dan indeks terbalik) pada layanan pencarian Anda. Setelah indeks dibuat, kemampuan Anda untuk memengaruhi perubahan menggunakan Buat atau Perbarui Indeks adalah kontingen pada apakah modifikasi Anda membatalkan struktur fisik tersebut. Sebagian besar atribut bidang tidak dapat diubah setelah bidang dibuat dalam indeks Anda.

Untuk meminimalkan churn dalam kode aplikasi, Anda dapat membuat alias indeks yang berfungsi sebagai referensi stabil ke indeks pencarian. Alih-alih memperbarui kode Anda dengan nama indeks, Anda dapat memperbarui alias indeks untuk menunjuk ke versi indeks yang lebih baru.

Untuk meminimalkan churn dalam proses desain, tabel berikut menjelaskan elemen mana yang tetap dan fleksibel dalam skema. Mengubah elemen tetap memerlukan pembangunan kembali indeks, sedangkan elemen fleksibel dapat diubah kapan saja tanpa memengaruhi implementasi fisik. Untuk informasi selengkapnya, lihat Memperbarui atau membangun ulang indeks.

Pengaturan corsOptions untuk kueri lintas-asal

Skema indeks menyertakan bagian untuk pengaturan corsOptions. Secara default, JavaScript sisi klien tidak dapat memanggil API apa pun karena browser mencegah semua permintaan lintas asal. Untuk mengizinkan kueri lintas sumber ke indeks Anda, aktifkan CORS (Berbagi Sumber Daya Lintas Asal) dengan mengatur atribut corsOptions. Untuk alasan keamanan, hanya API kueri yang mendukung CORS.

"corsOptions": {
  "allowedOrigins": [
    "*"
  ],
  "maxAgeInSeconds": 300

Properti berikut dapat diatur untuk CORS:

• allowedOrigins (diperlukan): Ini adalah daftar asal yang diizinkan mengakses indeks Anda. Kode JavaScript yang dilayani dari asal ini diizinkan untuk mengkueri indeks Anda (dengan asumsi pemanggil menyediakan kunci yang valid atau memiliki izin). Setiap asal biasanya dari bentuk protocol://<fully-qualified-domain-name>:<port> meskipun <port> sering kali dihilangkan. Untuk informasi selengkapnya, lihat Berbagi sumber daya lintas asal (Wikipedia).

  Jika Anda ingin mengizinkan akses ke semua asal, sertakan * sebagai item tunggal dalam array allowedOrigins. Ini bukan praktik yang direkomendasikan untuk layanan pencarian produksi tetapi sering kali berguna untuk pengembangan dan penelusuran kesalahan.

• maxAgeInSeconds (opsional): Browser menggunakan nilai ini untuk menentukan durasi (dalam detik) untuk membuat cache respons preflight CORS. Nilai harus bilangan bulat non-negatif. Periode cache yang lebih lama memberikan performa yang lebih baik, tetapi memperpanjang jumlah waktu yang perlu diterapkan oleh kebijakan CORS. Jika nilai ini tidak diatur, durasi default lima menit akan digunakan.

Langkah berikutnya

Gunakan tautan berikut untuk mempelajari tentang fitur khusus yang dapat ditambahkan ke indeks:

• Menambahkan bidang vektor dan profil vektor
• Menambahkan profil penilaian
• Menambahkan peringkat semantik
• Menambahkan pemberi saran
• Menambahkan peta sinonim
• Menambahkan penganalisis
• Menambahkan enkripsi

Gunakan tautan ini untuk memuat atau memperbarui indeks:

• Ikhtisar Impor Data
• Muat dokumen
• Memperbarui atau membangun ulang indeks