Membuat indeks di Azure AI Search

Artikel
02/02/2024

Di Pencarian Azure AI, permintaan kueri menargetkan teks yang dapat dicari dalam indeks pencarian.

Dalam artikel ini, pelajari langkah-langkah untuk menentukan dan menerbitkan indeks pencarian. Membuat indeks menetapkan struktur data fisik pada layanan pencarian Anda. Setelah definisi indeks ada, memuat indeks mengikuti sebagai tugas terpisah.

Prasyarat

Izin tulis. Izin dapat diberikan melalui kunci API admin pada permintaan. Atau, jika Anda menggunakan kontrol akses berbasis peran, kirim permintaan sebagai anggota peran Kontributor Pencarian.
Pemahaman tentang data yang ingin Anda indeks. Membuat indeks adalah latihan definisi skema, jadi Anda harus memiliki gambaran yang jelas tentang bidang sumber mana yang ingin Anda buat dapat dicari, dapat diambil, dapat difilter, dapat difaset, dan dapat diurutkan (lihat daftar periksa skema untuk panduan).

Anda juga harus memiliki bidang unik dalam data sumber yang dapat digunakan sebagai kunci dokumen (atau ID) dalam indeks.
Lokasi indeks yang stabil. Memindahkan indeks yang ada ke layanan pencarian lain tidak didukung secara langsung. Kunjungi kembali persyaratan aplikasi dan pastikan bahwa layanan pencarian Anda yang ada, kapasitas dan lokasinya, cukup untuk kebutuhan Anda.
Terakhir, semua tingkat layanan memiliki limit indeks pada jumlah objek yang dapat Anda buat. Misalnya, jika Anda bereksperimen pada tingkat Gratis, Anda hanya dapat memiliki tiga indeks pada waktu tertentu. Dalam indeks itu sendiri, ada batasan jumlah bidang dan kumpulan yang kompleks.

Kunci dokumen

Indeks pencarian memiliki satu bidang yang diperlukan: kunci dokumen. Kunci dokumen adalah pengidentifikasi unik dokumen pencarian. Di Azure AI Search, string harus berupa string, dan harus berasal dari nilai unik di sumber data yang menyediakan konten yang akan diindeks. 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.

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.

Daftar periksa skema

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

Tinjau konvensi penamaan agar nama indeks dan bidang sesuai dengan aturan penamaan.
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.
Identifikasi kunci dokumen. Kunci dokumen adalah persyaratan indeks. Ini adalah bidang string tunggal dan 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.
Identifikasi bidang di sumber data Anda yang berkontribusi konten yang dapat dicari dalam indeks. Konten yang dapat dicari mencakup string pendek atau panjang yang dikueri menggunakan mesin cari teks lengkap. Jika konten verbose (frasa kecil atau gugus yang lebih besar), lakukan eksperimen dengan penganalisis yang berbeda untuk melihat bagaimana teks ditokenisasi.

Penetapan atribut bidang menentukan perilaku pencarian dan representasi fisik indeks Anda pada layanan pencarian. Bagi kebanyakan pelanggan, penentuan cara bidang harus ditetapkan adalah proses berulang. Untuk mempercepat perulangan, mulai dengan contoh data agar Anda dapat menghilangkan dan membangun kembali dengan mudah.
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:
- Bidang yang dapat difilter dapat digunakan secara opsional dalam navigasi tersaring.
- Bidang yang dapat difilter dikembalikan dalam urutan arbitrer, jadi pertimbangkan untuk membuatnya dapat diurutkan juga.
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 yang dipending 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.

Catatan

Pencarian teks lengkap dilakukan melalui istilah yang ditokenisasi selama pengindeksan. Jika kueri Anda gagal mengembalikan hasil yang Anda harapkan, uji tokenisasi untuk memverifikasi string benar-benar ada. Anda dapat mencoba penganalisis yang berbeda pada string untuk melihat bagaimana token diproduksi untuk berbagai penganalisis.

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.

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 subnet data Anda untuk membuat pembangunan kembali berjalan lebih cepat.

Desain indeks melalui portal menerapkan persyaratan dan aturan skema untuk jenis data tertentu, seperti melarang kemampuan pencarian teks penuh pada bidang numerik.

Masuk ke portal Azure.
Di halaman Gambaran Umum layanan pencarian, pilih salah satu opsi untuk membuat indeks pencarian:
- Menambahkan indeks, editor yang disematkan untuk menentukan skema indeks
- Wizard impor data
Wizard adalah alur kerja end-to-end yang membuat pengindeks, sumber data, dan indeks yang sudah selesai. Ini juga memuat data. Jika ini lebih dari yang Anda inginkan, gunakan Tambahkan indeks sebagai gantinya.

Cuplikan layar berikut menyoroti tempat Tambahkan indeks dan Impor data muncul di bilah perintah. Setelah indeks dibuat, Anda dapat menemukannya lagi di tab Indeks.

Tip

Setelah membuat indeks di portal, Anda dapat menyalin representasi JSON dan menambahkannya ke kode aplikasi Anda.

Buat Indeks (REST API) digunakan untuk membuat indeks. Anda memerlukan klien REST untuk terhubung ke layanan pencarian Anda dan mengirim permintaan. Lihat Mulai Cepat: Pencarian teks menggunakan REST untuk memulai.

REST API menyediakan default untuk atribusi bidang. Misalnya, semua Edm.String bidang dapat dicari secara default. Atribut ditampilkan secara lengkap di bawah ini untuk tujuan ilustrasi, tetapi Anda dapat menghilangkan atribusi dalam kasus jika nilai default berlaku.

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)[ ... ]
}

Azure SDK untuk .NET memiliki SearchIndexClient dengan metode untuk membuat dan memperbarui indeks.

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

Untuk contoh lainnya, lihatazure-search-dotnet-samples/quickstart/v11/.

Untuk Azure AI Search, Azure SDK menerapkan fitur yang tersedia secara umum. Dengan demikian, Anda dapat menggunakan salah satu SDK untuk membuat indeks pencarian. Semuanya menyediakan SearchIndexClient yang memiliki metode untuk membuat dan memperbarui indeks.

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

Mengatur `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 asal 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.

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 Perbarui Indeks bergantung pada apakah perubahan Anda membatalkan validitas struktur fisik tersebut. Sebagian besar atribut bidang tidak dapat diubah setelah bidang dibuat dalam indeks Anda.

Atau, Anda dapat membuat alias indeks yang berfungsi sebagai referensi stabil dalam kode aplikasi Anda. Alih-alih memperbarui kode, 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.

Elemen	Dapat diperbarui?
Nama	No
Kunci	No
Nama dan jenis bidang	No
Atribut bidang (dapat dicari, dapat difilter, dapat difaset, dapat diurutkan)	No
Atribut bidang (dapat diambil)	Ya
Penganalisis	Anda dapat menambahkan dan memodifikasi penganalisis kustom dalam indeks. Mengenai penugasan penganalisis pada bidang string, Anda hanya dapat memodifikasi `searchAnalyzer`. Semua penugasan dan modifikasi lainnya memerlukan pembangunan kembali.
Profil Penilaian	Ya
Pemberi saran	No
berbagi sumber daya lintas asal (CORS)	Ya
Enkripsi	Ya

Langkah berikutnya

Gunakan tautan berikut untuk membiasakan dengan memuat indeks dengan data, atau memperluas indeks dengan peta sinonim.