Membuat indeks vektor di Pencarian Azure AI

Nota

Pencarian Azure AI tersedia melalui portal Azure, REST API, dan Azure SDK. Ini juga mendukung Foundry IQ, lapisan pengetahuan terkelola yang mengubah konten perusahaan menjadi pangkalan pengetahuan yang dapat digunakan kembali dan sadar izin untuk agen di portal Microsoft Foundry.

Di Pencarian Azure AI, Anda bisa menyimpan dan mengkueri vektor dalam indeks pencarian. Indeks vektor didefinisikan oleh skema indeks yang memiliki bidang vektor, bidang nonvektor, dan bagian konfigurasi vektor.

Membuat indeks vektor secara implisit membuat ruang penyematan yang berfungsi sebagai korpus untuk kueri vektor. Ruang penyematan terdiri dari semua bidang vektor yang diisi dengan penyematan dari model penyematan yang sama. Pada waktu kueri, sistem membandingkan kueri vektor dengan vektor terindeks dan mengembalikan hasil berdasarkan kesamaan semantik.

Artikel ini menggunakan REST untuk menjelaskan cara membuat indeks vektor, yang mencakup langkah-langkah berikut:

  • Mulai dengan definisi skema dasar
  • Menambahkan algoritma vektor dan pemadatan opsional
  • Menambahkan definisi bidang vektor
  • Muat data yang direvektorisasi sebagai langkah terpisah atau gunakan vektorisasi terintegrasi untuk memotong dan menyematkan data selama pengindeksan

Setelah Anda memahami alur kerja dasar, coba sampel Azure SDK di repositori GitHub azure-search-vector-samples untuk panduan tentang menggunakan vektor dalam kode pengujian dan produksi. Anda juga dapat menggunakan portal Microsoft Azure untuk membuat indeks vektor melalui vektorisasi terintegrasi.

Prasyarat

  • Layanan Pencarian Azure AI di wilayah mana pun dan di tingkat apa pun. Jika Anda berencana menggunakan vektorisasi terintegrasi dengan keterampilan dan vektorizer Azure Vision, Pencarian Azure AI harus berada di wilayah yang sama dengan model embedding yang dihosting di Azure Vision pada Foundry Tools.

  • Untuk autentikasi tanpa kunci yang direkomendasikan, tetapkan peran Kontributor Layanan Pencarian dan Kontributor Data Indeks Pencarian ke akun pengguna, identitas terkelola, atau perwakilan layanan Anda. Untuk autentikasi berbasis kunci yang kurang aman, dapatkan kunci API admin.

  • Dokumen sumber dengan penyematan vektor untuk diunggah ke indeks. Anda juga dapat menggunakan vektorisasi terintegrasi untuk tugas ini.

  • Batas dimensi model embedding Anda. text-embedding-ada-002 tetap pada 1536, text-embedding-3-small berkisar dari 1 hingga 1536, dan text-embedding-3-large berkisar dari 1 hingga 3072.

  • Metrik kesamaan untuk model embedding Anda. Model Azure OpenAI menggunakan cosine.

  • Keakraban dalam membuat indeks. Skema selalu menyertakan bidang untuk kunci dokumen, bidang untuk pencarian atau filter, dan konfigurasi lain untuk perilaku yang diperlukan selama pengindeksan dan kueri.

Nota

Beberapa layanan pencarian yang dibuat sebelum Januari 2019 tidak dapat membuat indeks vektor. Jika berlaku, buat layanan baru untuk menggunakan vektor.

Menyiapkan dokumen untuk pengindeksan

Sebelum mengindeks, kumpulkan payload dokumen yang mencakup bidang data vektor dan nonvektor. Struktur dokumen harus sesuai dengan kumpulan bidang skema indeks.

Pastikan dokumen sumber Anda menyediakan konten berikut:

Isi Deskripsi
Pengidentifikasi unik Bidang atau properti metadata yang secara unik mengidentifikasi setiap dokumen. Semua indeks pencarian memerlukan kunci dokumen. Untuk memenuhi persyaratan kunci dokumen, dokumen sumber harus memiliki satu bidang atau properti yang mengidentifikasinya secara unik dalam indeks. Jika Anda mengindeks blob, bisa jadi metadata_storage_path adalah yang secara unik mengidentifikasi setiap blob. Jika Anda mengindeks dari database, itu mungkin kunci utama. Bidang sumber ini harus dipetakan ke bidang indeks tipe Edm.String dan key=true dalam indeks pencarian.
Konten non-vektor Berikan bidang lain dengan konten yang dapat dibaca manusia. Konten yang dapat dibaca manusia berguna untuk respons kueri dan untuk kueri hibrid yang menyertakan pencarian teks lengkap atau peringkat semantik dalam permintaan yang sama. Jika Anda menggunakan model penyelesaian obrolan, sebagian besar model seperti ChatGPT mengharapkan teks yang dapat dibaca manusia dan tidak menerima vektor mentah sebagai input.
Konten vektor Representasi vektorisasi konten nonvektor Anda untuk digunakan pada waktu kueri. Vektor adalah array angka titik mengambang presisi tunggal yang dihasilkan oleh model penyematan. Setiap bidang vektor berisi array yang dihasilkan model. Ada satu penyematan per bidang, di mana bidang adalah bidang tingkat atas (bukan bagian dari jenis berlapis atau kompleks). Untuk integrasi sederhana, sebaiknya sematkan model di Azure OpenAI, seperti penyematan teks-3 untuk dokumen teks atau REST API Pengambilan Gambar untuk gambar dan penyematan multimodal.

Jika Anda dapat menggunakan indeksir dan skillset, pertimbangkan vektorisasi terintegrasi, yang mengodekan gambar dan teks selama pengindeksan. Definisi bidang Anda adalah untuk bidang vektor, tetapi data sumber masuk dapat berupa teks atau gambar, yang dikonversi ke array vektor selama pengindeksan.

Indeks pencarian Anda harus menyertakan bidang dan konten untuk semua skenario kueri yang ingin Anda dukung. Misalkan Anda ingin mencari atau memfilter nama produk, versi, metadata, atau alamat. Dalam hal ini, pencarian kesamaan vektor tidak terlalu membantu. Pencarian kata kunci, pencarian geografis, atau filter yang berulang melalui konten verbatim akan menjadi pilihan yang lebih baik. Indeks pencarian yang termasuk bidang vektor dan nonvektor memberikan fleksibilitas maksimum untuk konstruksi kueri dan komposisi respons.

Untuk contoh payload dokumen, lihat bagian Memuat data vektor untuk pengindeksan .

Mulai dengan indeks dasar

Mulailah dengan skema minimum sehingga Anda memiliki definisi untuk bekerja sebelum menambahkan konfigurasi vektor dan bidang vektor. Indeks sederhana mungkin terlihat seperti contoh berikut. Untuk informasi selengkapnya tentang skema indeks, lihat Membuat indeks pencarian.

Perhatikan bahwa indeks memiliki nama yang diperlukan, kunci dokumen yang diperlukan ("key": true), dan bidang untuk konten yang dapat dibaca manusia dalam teks biasa. Hal yang lazim untuk memiliki versi yang dapat dibaca manusia dari konten apa pun yang Anda maksudkan untuk vektorisasi. Misalnya, jika Anda memiliki potongan teks dari file PDF, skema indeks Anda harus memiliki bidang untuk potongan teks biasa dan bidang kedua untuk potongan vektorisasi.

Berikut adalah indeks dasar dengan "name", koleksi "fields", dan beberapa konstruksi lainnya untuk konfigurasi tambahan.

POST https://[servicename].search.windows.net/indexes?api-version=[api-version] 
{
  "name": "example-index",
  "description": "This is an example index."
  "fields": [
    { "name": "documentId", "type": "Edm.String", "key": true, "retrievable": true, "searchable": true, "filterable": true },
    { "name": "myHumanReadableNameField", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "myHumanReadableContentField", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
  ],
  "analyzers": [ ],
  "scoringProfiles": [ ],
  "suggesters": [ ],
  "vectorSearch": [ ]
}

Menambahkan konfigurasi pencarian vektor

Selanjutnya, tambahkan "vectorSearch" konfigurasi ke skema Anda. Sangat berguna untuk menentukan konfigurasi sebelum definisi bidang, karena profil yang Anda tentukan di sini menjadi bagian dari definisi bidang vektor. Dalam skema, konfigurasi vektor biasanya dimasukkan setelah koleksi bidang, mungkin setelah "analyzers", "scoringProfiles", dan "suggesters". Namun, urutan tidak penting.

Konfigurasi vektor meliputi:

  • vectorSearch.algorithms digunakan selama pengindeksan untuk membuat informasi "tetangga terdekat" di antara simpul vektor.
  • vectorSearch.compressions untuk kuantisasi skalar atau biner, pengambilan sampel berlebih, dan reranking dengan vektor asli.
  • vectorSearch.profiles untuk menentukan beberapa kombinasi konfigurasi algoritma dan kompresi.

Berikut langkah-langkahnya:

  1. Gunakan REST API Buat atau Perbarui Indeks untuk membuat indeks.

  2. vectorSearch Tambahkan bagian dalam indeks yang menentukan algoritma pencarian yang digunakan untuk membuat ruang penyematan.

     "vectorSearch": {
     "compressions": [
         {
             "name": "scalar-quantization",
             "kind": "scalarQuantization",
             "scalarQuantizationParameters": {
                 "quantizedDataType": "int8"
                 },
             "rescoringOptions": {
                 "enableRescoring": true,
                 "defaultOversampling": 10,
                 "rescoreStorageMethod": "preserveOriginals"
             }
         },
         {
             "name": "binary-quantization",
             "kind": "binaryQuantization",
             "rescoringOptions": {
                 "enableRescoring": true,
                 "defaultOversampling": 10,
                 "rescoreStorageMethod": "discardOriginals"
         }
         }
     ],
     "algorithms": [
         {
             "name": "hnsw-1",
             "kind": "hnsw",
             "hnswParameters": {
                 "m": 4,
                 "efConstruction": 400,
                 "efSearch": 500,
                 "metric": "cosine"
             }
         },
         {
             "name": "hnsw-2",
             "kind": "hnsw",
             "hnswParameters": {
                 "m": 8,
                 "efConstruction": 800,
                 "efSearch": 800,
                 "metric": "hamming"
             }
         },
         {
             "name": "eknn",
             "kind": "exhaustiveKnn",
             "exhaustiveKnnParameters": {
                 "metric": "euclidean"
             }
         }

     ],
     "profiles": [
       {
         "name": "vector-profile-hnsw-scalar",
         "compression": "scalar-quantization",
         "algorithm": "hnsw-1"
       }
     ]
 }

    Poin utama:

    • Nama untuk setiap konfigurasi kompresi, algoritma, dan profil harus unik untuk jenisnya dalam indeks.

    • vectorSearch.compressions dapat berupa scalarQuantization atau binaryQuantization. Kuantisasi skalar mengompresi nilai float ke dalam jenis data yang lebih sempit. Kuantisasi biner mengonversi float menjadi nilai biner 1-bit.

    • vectorSearch.compressions.rescoringOptions menggunakan vektor asli yang tidak dikompresi untuk menghitung ulang kesamaan dan mererank hasil teratas yang dikembalikan oleh kueri pencarian awal. Vektor yang tidak dikompresi ada di indeks pencarian meskipun stored salah. Properti ini bersifat opsional. Pengaturan awal adalah benar.

    • vectorSearch.compressions.rescoringOptions.defaultOversampling mempertimbangkan serangkaian hasil potensial yang lebih luas untuk mengimbangi pengurangan informasi dari kuantisasi. Rumus untuk hasil potensial terdiri dari k dalam kueri, dengan pengali sampel berlebih. Misalnya, jika kueri menentukan k 5, dan oversampling adalah 20, kueri secara efektif meminta 100 dokumen untuk digunakan dalam reranking, menggunakan vektor asli yang tidak dikompresi untuk tujuan tersebut. Hanya hasil yang telah diurutkan ulang k teratas yang diberikan kembali. Properti ini bersifat opsional. Nilai awal adalah 4.

    • vectorSearch.compressions.scalarQuantizationParameters.quantizedDataType harus diatur ke int8. Ini adalah satu-satunya jenis data primitif yang didukung saat ini. Properti ini bersifat opsional. Defaultnya adalah int8.

    • vectorSearch.algorithms adalah baik hnsw maupun exhaustiveKnn. Ini adalah algoritma Perkiraan Tetangga Terdekat (ANN) yang digunakan untuk mengatur konten vektor selama pengindeksan.

    • vectorSearch.algorithms.m adalah jumlah tautan dua arah. Nilai awal adalah 4. Rentangnya adalah 4 hingga 10. Nilai yang lebih rendah seharusnya menghasilkan kebisingan yang lebih sedikit dalam hasil.

    • vectorSearch.algorithms.efConstruction adalah jumlah tetangga terdekat yang digunakan selama pengindeksan. Defaultnya adalah 400. Rentangnya adalah 100 hingga 1.000.

    • "vectorSearch.algorithms.efSearch adalah jumlah tetangga terdekat yang digunakan selama pencarian. Nilai baku adalah 500. Rentangnya adalah 100 hingga 1.000.

    • vectorSearch.algorithms.metric seharusnya cosine jika Anda menggunakan Azure OpenAI, jika tidak, gunakan metrik kesamaan yang terkait dengan model penyematan yang Anda gunakan. Nilai yang didukung adalah cosine, dotProduct, euclidean, dan hamming (digunakan untuk mengindeks data biner).

    • vectorSearch.profiles tambahkan lapisan abstraksi untuk mengakomodasi definisi yang lebih kaya. Profil didefinisikan dalam vectorSearch dan dirujuk berdasarkan nama di setiap bidang vektor. Ini adalah kombinasi konfigurasi kompresi dan algoritma. Anda menetapkan properti ini ke bidang vektor, dan menentukan algoritma dan kompresi bidang.

Menambahkan bidang vektor ke kumpulan bidang

Setelah memiliki konfigurasi vektor, Anda dapat menambahkan bidang vektor ke koleksi bidang. Ingat bahwa koleksi bidang harus menyertakan bidang untuk kunci dokumen, bidang vektor, dan bidang nonvektor lainnya yang Anda butuhkan untuk skenario pencarian hibrid atau penyelesaian model obrolan dalam beban kerja RAG.

Bidang vektor ditandai oleh jenis datanya, dimensions properti berdasarkan model penyematan yang digunakan untuk menghasilkan vektor, dan profil vektor yang Anda buat di langkah sebelumnya.

  1. Gunakan REST API Buat atau Perbarui Indeks untuk membuat indeks dan menambahkan bidang vektor ke koleksi bidang.

    {
  "name": "example-index",
  "fields": [
    {
        "name": "contentVector",
        "type": "Collection(Edm.Single)",
        "searchable": true,
        "retrievable": false,
        "stored": false,
        "dimensions": 1536,
        "vectorSearchProfile": "vector-profile-1"
    }
  ]
}

  2. Tentukan bidang vektor dengan atribut berikut. Anda dapat menyimpan satu penyematan yang dihasilkan per bidang. Untuk setiap bidang vektor:

    • type harus berupa jenis data vektor. Collection(Edm.Single) adalah yang paling umum untuk menyematkan model.
    • dimensions adalah jumlah dimensi yang dihasilkan oleh model penyematan. Untuk text-embedding-ada-002, tetap sebesar 1536. Untuk seri model text-embedding-3, terdapat berbagai macam nilai. Jika Anda menggunakan vektorisasi terintegrasi dan keterampilan penyematan untuk menghasilkan vektor, pastikan properti ini diatur ke nilai dimensi yang sama yang digunakan oleh keterampilan penyematan.
    • vectorSearchProfile adalah nama profil yang ditentukan di tempat lain dalam indeks.
    • searchable harus benar.
    • retrievable bisa benar atau salah. True mengembalikan vektor mentah (1.536 di antaranya) sebagai teks biasa dan mengonsumsi ruang penyimpanan. Atur ke true jika Anda meneruskan hasil vektor ke aplikasi hilir.
    • stored bisa benar atau salah. Ini menentukan apakah salinan vektor tambahan disimpan untuk pengambilan. Untuk informasi selengkapnya, lihat Mengurangi ukuran vektor.
    • filterable, facetable, dan sortable harus salah.

  3. Tambahkan bidang non-vektor yang dapat difilter ke koleksi, seperti title dengan filterable diatur ke true, jika Anda ingin mengaktifkan prafiltering, pasca-penyaringan, atau penyaringan pasca ketat (pratinjau) pada kueri vektor.

  4. Tambahkan bidang lain yang menentukan substansi dan struktur konten tekstual yang Anda indeks. Minimal, Anda memerlukan kunci dokumen.

    Anda juga harus menambahkan bidang yang berguna dalam kueri atau dalam responsnya. Contoh berikut menunjukkan bidang vektor untuk judul dan konten (titleVector dan contentVector) yang setara dengan vektor. Ini juga menyediakan bidang untuk konten tekstual yang setara (title dan content) yang berguna untuk mengurutkan, memfilter, dan membaca dalam hasil pencarian.

    Contoh berikut menunjukkan kumpulan bidang:

    PUT https://my-search-service.search.windows.net/indexes/my-index?api-version=2026-04-01&allowIndexDowntime=true
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "name": "{{index-name}}",
    "fields": [
        {
            "name": "id",
            "type": "Edm.String",
            "key": true,
            "filterable": true
        },
        {
            "name": "title",
            "type": "Edm.String",
            "searchable": true,
            "filterable": true,
            "sortable": true,
            "retrievable": true
        },
        {
            "name": "titleVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": true,
            "stored": true,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-1"
        },
        {
            "name": "content",
            "type": "Edm.String",
            "searchable": true,
            "retrievable": true
        },
        {
            "name": "contentVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": false,
            "stored": false,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-1"
        }
    ],
    "vectorSearch": {
        "algorithms": [
            {
                "name": "hnsw-1",
                "kind": "hnsw",
                "hnswParameters": {
                    "m": 4,
                    "efConstruction": 400,
                    "efSearch": 500,
                    "metric": "cosine"
                }
            }
        ],
        "profiles": [
            {
                "name": "vector-profile-1",
                "algorithm": "hnsw-1"
            }
        ]
    }
}

Memuat data vektor untuk pengindeksan

Konten yang Anda berikan untuk pengindeksan harus sesuai dengan skema indeks dan menyertakan nilai string unik untuk kunci dokumen. Data yang diprovektorisasi dimuat ke dalam satu atau beberapa bidang vektor, yang dapat berdampingan dengan bidang lain yang berisi konten nonvektor.

Untuk penyerapan data, Anda dapat menggunakan metodologi pendorongan atau penarikan.

Gunakan Dokumen - Indeks untuk memuat data vektor dan nonvektor ke dalam indeks. API pendorongan untuk pengindeksan identik di semua versi stabil dan pratinjau. Gunakan salah satu API berikut untuk memuat dokumen:

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/index?api-version=2026-04-01

{
    "value": [
        {
            "id": "1",
            "title": "Azure App Service",
            "content": "Azure App Service is a fully managed platform for building, deploying, and scaling web apps. You can host web apps, mobile app backends, and RESTful APIs. It supports a variety of programming languages and frameworks, such as .NET, Java, Node.js, Python, and PHP. The service offers built-in auto-scaling and load balancing capabilities. It also provides integration with other Azure services, such as Azure DevOps, GitHub, and Bitbucket.",
            "category": "Web",
            "titleVector": [
                -0.02250031754374504,
                 . . . 
                        ],
            "contentVector": [
                -0.024740582332015038,
                 . . .
            ],
            "@search.action": "upload"
        },
        {
            "id": "2",
            "title": "Azure Functions",
            "content": "Azure Functions is a serverless compute service that enables you to run code on-demand without having to manage infrastructure. It allows you to build and deploy event-driven applications that automatically scale with your workload. Functions support various languages, including C#, F#, Node.js, Python, and Java. It offers a variety of triggers and bindings to integrate with other Azure services and external services. You only pay for the compute time you consume.",
            "category": "Compute",
            "titleVector": [
                -0.020159931853413582,
                . . .
            ],
            "contentVector": [
                -0.02780858241021633,
                 . . .
            ],
            "@search.action": "upload"
        }
        . . .
    ]
}

Mengkueri indeks untuk konten vektor

Untuk tujuan validasi, Anda dapat mengkueri indeks menggunakan Search Explorer di panggilan portal Azure atau REST API. Karena Pencarian Azure AI tidak dapat mengonversi vektor ke teks yang dapat dibaca manusia, coba kembalikan bidang dari dokumen yang sama yang memberikan bukti kecocokan. Misalnya, jika kueri vektor menargetkan titleVector bidang , Anda dapat memilih title untuk hasil pencarian.

Bidang harus diberi atribut retrievable agar dapat disertakan dalam hasil.

  • Tinjau indeks di manajemen pencarian>Indeks untuk melihat ukuran indeks keseluruhan dan ukuran indeks vektor. Ukuran indeks vektor positif menunjukkan adanya vektor.

  • Gunakan Search Explorer untuk mengkueri indeks. Search Explorer memiliki dua tampilan: Tampilan kueri (default) dan tampilan JSON.

    • Atur Opsi Kueri>Sembunyikan nilai vektor dalam hasil penelusuran untuk hasil yang lebih mudah dibaca.

    • Gunakan tampilan JSON untuk kueri vektor. Anda dapat menempelkan definisi JSON dari kueri vektor yang ingin Anda jalankan. Jika indeks Anda memiliki penetapan vektorizer, Anda juga dapat menggunakan konversi teks ke vektor atau gambar ke vektor bawaan. Untuk informasi selengkapnya tentang pencarian gambar, lihat Panduan Cepat: Pencarian Gambar di Penjelajah Pencarian.

    • Gunakan tampilan Kueri default untuk konfirmasi cepat bahwa indeks berisi vektor. Tampilan kueri adalah untuk pencarian teks lengkap. Meskipun Anda tidak dapat menggunakannya untuk kueri vektor, Anda dapat mengirim pencarian kosong (search=*) untuk memeriksa konten. Konten semua bidang, termasuk bidang vektor, dikembalikan sebagai teks biasa.

Untuk informasi selengkapnya, lihat Membuat kueri vektor.

Memperbarui indeks vektor

Untuk memperbarui indeks vektor, ubah skema dan muat ulang dokumen untuk mengisi bidang baru. API untuk pembaruan skema termasuk Buat atau Perbarui Indeks (REST), CreateOrUpdateIndex di Azure SDK untuk .NET, create_or_update_index di Azure SDK for Python, dan metode serupa di Azure SDK lainnya.

Untuk panduan standar tentang memperbarui indeks, lihat Memperbarui atau membangun ulang indeks.

Poin-poin penting meliputi:

  • Penghapusan dan pembangunan ulang indeks secara penuh sering diperlukan untuk pembaruan dan penghapusan bidang yang ada.

  • Anda dapat melakukan modifikasi berikut tanpa persyaratan pembangunan ulang:

    • Tambahkan bidang baru ke kumpulan bidang.
    • Tambahkan konfigurasi vektor baru, ditetapkan ke bidang baru tetapi bukan bidang yang sudah ada yang sudah di-vektorisasi.
    • Ubah retrievable (nilai-nilai adalah 'benar' atau 'salah') pada bidang yang ada. Bidang vektor harus dapat dicari dan diakses, tetapi jika Anda ingin menonaktifkan akses ke bidang vektor dalam situasi di mana menghapus dan membuat ulang tidak layak dilakukan, Anda dapat mengatur retrievable menjadi tidak aktif.

Langkah berikutnya

Sebagai langkah berikutnya, sebaiknya Buat kueri vektor.

Sampel kode di repositori azure-search-vector-samples menunjukkan alur kerja end-to-end yang mencakup definisi skema, vektorisasi, pengindeksan, dan kueri.

Ada kode demo untuk Python, C#, dan JavaScript.

  • Last updated on