Membuat kueri vektor di Azure AI Search

2025-06-20

Di Pencarian Azure AI, jika Anda memiliki indeks vektor, artikel ini menjelaskan cara:

Bidang vektor pencarian.
Kueri beberapa bidang vektor sekaligus.
Atur bobot vektor.
Kueri dengan vektorisasi terintegrasi.
Atur ambang batas untuk mengecualikan hasil penilaian rendah (pratinjau).

Artikel ini menggunakan REST untuk ilustrasi. Setelah Anda memahami alur kerja dasar, lanjutkan dengan sampel kode Azure SDK di repositori azure-search-vector-samples , yang menyediakan solusi end-to-end yang menyertakan kueri vektor.

Anda juga dapat menggunakan Search Explorer di portal Azure.

Prasyarat

Layanan Pencarian Azure AI di wilayah mana pun dan di tingkat apa pun.
Indeks vektor. Periksa apakah ada bagian vectorSearch di dalam indeks Anda untuk mengonfirmasi keberadaannya.
Secara opsional, tambahkan vektorizer ke indeks Anda untuk konversi teks ke vektor atau gambar ke vektor bawaan selama kueri.
Visual Studio Code dengan klien REST dan data sampel jika Anda ingin menjalankan contoh ini sendiri. Untuk mulai menggunakan klien REST, lihat Mulai Cepat: Pencarian teks lengkap menggunakan REST.

Mengonversi input string kueri menjadi vektor

Untuk mengkueri bidang vektor, kueri itu sendiri harus menjadi vektor.

Salah satu pendekatan untuk mengonversi string kueri teks pengguna menjadi representasi vektornya adalah memanggil pustaka penyematan atau API dalam kode aplikasi Anda. Sebagai praktik terbaik, selalu gunakan model penyematan yang sama yang digunakan untuk menghasilkan penyematan dalam dokumen sumber. Anda dapat menemukan sampel kode yang menunjukkan cara membuat penyematan di repositori azure-search-vector-samples .

Pendekatan kedua adalah menggunakan vektorisasi terintegrasi, sekarang tersedia secara umum, agar Azure AI Search menangani input dan output vektorisasi kueri Anda.

Berikut adalah contoh REST API dari string kueri yang dikirimkan ke penyebaran model penyematan Azure OpenAI:

POST https://{{openai-service-name}}.openai.azure.com/openai/deployments/{{openai-deployment-name}}/embeddings?api-version={{openai-api-version}}
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "input": "what azure services support generative AI'"
}

Respons yang diharapkan adalah 202 untuk panggilan yang berhasil ke model yang disebarkan.

Bidang embedding dalam isi respons adalah representasi vektor dari string inputkueri . Untuk tujuan pengujian, Anda akan menyalin nilai embedding array ke dalam vectorQueries.vector permintaan kueri, menggunakan sintaks yang diperlihatkan di beberapa bagian berikutnya.

Respons aktual terhadap panggilan POST ini ke model yang disebarkan mencakup 1.536 penyematan. Untuk keterbacaan, contoh ini hanya menunjukkan beberapa vektor pertama.

{
    "object": "list",
    "data": [
        {
            "object": "embedding",
            "index": 0,
            "embedding": [
                -0.009171937,
                0.018715322,
                ...
                -0.0016804502
            ]
        }
    ],
    "model": "ada",
    "usage": {
        "prompt_tokens": 7,
        "total_tokens": 7
    }
}

Dalam pendekatan ini, kode aplikasi Anda bertanggung jawab untuk terhubung ke model, menghasilkan penyematan, dan menangani respons.

Permintaan kueri vektor

Bagian ini memperlihatkan struktur dasar kueri vektor. Anda dapat menggunakan portal Azure, REST API, atau Azure SDK untuk merumuskan kueri vektor.

Jika Anda bermigrasi dari Pratinjau 2023-07-01, ada perubahan yang melanggar. Untuk informasi selengkapnya, lihat Meningkatkan ke REST API terbaru.

2024-07-01 adalah versi REST API yang stabil dari Search POST. Versi ini mendukung:

vectorQueries adalah konstruksi untuk pencarian vektor.
vectorQueries.kind diatur ke vector untuk array vektor atau text jika input adalah string dan Anda memiliki vektorizer.
vectorQueries.vector adalah kueri (representasi vektor teks atau gambar).
vectorQueries.exhaustive (opsional) memanggil KNN lengkap pada waktu kueri, bahkan jika bidang diindeks untuk HNSW.
vectorQueries.fields (opsional) menargetkan bidang tertentu untuk eksekusi kueri (hingga 10 per kueri).
vectorQueries.weight (opsional) menentukan bobot relatif setiap kueri vektor yang disertakan dalam operasi pencarian. Untuk informasi selengkapnya, lihat Pembobotan vektor.
vectorQueries.k adalah jumlah kecocokan yang akan dikembalikan.

Dalam contoh berikut, vektor adalah representasi dari string ini: "what Azure services support full text search". Kueri menargetkan contentVector bidang dan mengembalikan k hasil. Vektor aktual memiliki 1.536 penyematan, yang dipangkas dalam contoh ini untuk keterbacaan.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2024-07-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "count": true,
    "select": "title, content, category",
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "exhaustive": true,
            "fields": "contentVector",
            "weight": 0.5,
            "k": 5
        }
    ]
}

Pratinjau 2024-05-01 adalah versi API pratinjau terbaru dari Search - POST. Ini mendukung sintaks kueri vektor yang sama dengan 2024-07-01, tetapi memiliki parameter tambahan untuk pencarian hibrid dan ambang minimum untuk tidak termasuk hasil yang lebih lemah.

Pratinjau ini menambahkan:

threshold untuk tidak menyertakan hasil dengan skor rendah.
Hybridsearch.MaxTextRecallSize untuk kontrol lebih besar atas input ke kueri hibrid.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2024-05-01-preview
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "count": true,
    "select": "title, content, category",
    "hybridSearch": {
        "maxTextRecallSize": 100,
        "countAndFacetMode": "countAllResults"
        }
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "contentVector",
            "k": 5,
            "exhaustive": true,
            "weight": 2,
            "threshold": {
                "kind": "vectorSimilarity",
                "value": 0.8
            },

        }
    ]

Respons kueri vektor

Di Azure AI Search, respons kueri terdiri dari semua retrievable bidang secara default. Namun, umum untuk membatasi hasil pencarian ke subset retrievable bidang dengan mencantumkannya dalam select pernyataan.

Dalam kueri vektor, pertimbangkan dengan cermat apakah Anda perlu mem-vektor bidang dalam respons. Bidang vektor tidak dapat dibaca manusia, jadi jika Anda mendorong respons ke halaman web, Anda harus memilih bidang nonvektor yang mewakili hasilnya. Misalnya, jika kueri dijalankan terhadap contentVector, Anda dapat kembali content sebagai gantinya.

Jika Anda menginginkan bidang vektor dalam hasilnya, berikut adalah contoh struktur respons. contentVector adalah array string dari embedding, yang dipotong dalam contoh ini demi keterbacaan. Skor pencarian menunjukkan relevansi. Bidang nonvektor lainnya disertakan untuk konteks.

{
    "@odata.count": 3,
    "value": [
        {
            "@search.score": 0.80025613,
            "title": "Azure Search",
            "category": "AI + Machine Learning",
            "contentVector": [
                -0.0018343845,
                0.017952163,
                0.0025753193,
                ...
            ]
        },
        {
            "@search.score": 0.78856903,
            "title": "Azure Application Insights",
            "category": "Management + Governance",
            "contentVector": [
                -0.016821077,
                0.0037742127,
                0.016136652,
                ...
            ]
        },
        {
            "@search.score": 0.78650564,
            "title": "Azure Media Services",
            "category": "Media",
            "contentVector": [
                -0.025449317,
                0.0038463024,
                -0.02488436,
                ...
            ]
        }
    ]
}

Poin utama:

k menentukan berapa banyak hasil tetangga terdekat yang dikembalikan, dalam hal ini, tiga. Kueri vektor selalu mengembalikan k hasil, dengan asumsi terdapat setidaknya k dokumen, bahkan jika beberapa dokumen memiliki tingkat kesamaan yang rendah. Ini karena algoritma menemukan tetangga terdekat apapun untuk vektor kueri.
Algoritma pencarian vektor menentukan @search.score.
Bidang dalam hasil pencarian adalah semua retrievable bidang atau bidang dalam select klausa. Selama eksekusi kueri vektor, pencocokan dilakukan pada data vektor saja. Namun, respons dapat menyertakan bidang apa pun retrievable dalam indeks. Karena tidak ada fasilitas untuk mendekode hasil bidang vektor, penyertaan bidang teks nonvektor sangat membantu untuk nilai yang dapat dibaca manusia.

Beberapa bidang vektor

Anda dapat mengatur properti vectorQueries.fields pada beberapa bidang vektor. Kueri vektor dijalankan terhadap setiap bidang vektor yang Anda sediakan fields dalam daftar. Anda dapat menentukan hingga 10 bidang.

Saat mengkueri beberapa bidang vektor, pastikan masing-masing berisi penyematan dari model penyematan yang sama. Kueri juga harus dihasilkan dari model penyematan yang sama.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2024-07-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "count": true,
    "select": "title, content, category",
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "exhaustive": true,
            "fields": "contentVector, titleVector",
            "k": 5
        }
    ]
}

Beberapa kueri vektor

Pencarian vektor multi-kueri mengirimkan beberapa kueri di beberapa bidang vektor dalam indeks pencarian Anda. Jenis kueri ini umumnya digunakan dengan model seperti CLIP untuk pencarian multimodal, di mana model yang sama dapat mem-vektorisasi teks dan gambar.

Contoh kueri berikut mencari kesamaan antara myImageVector dan myTextVector, tetapi mengirimkan dua penyematan kueri yang masing-masing dieksekusi secara paralel. Hasil kueri ini dinilai menggunakan fusi peringkat timbal balik (RRF).

vectorQueries menyediakan array kueri vektor.
vector berisi vektor gambar dan vektor teks dalam indeks pencarian. Setiap instans adalah kueri terpisah.
fields menentukan bidang vektor mana yang akan ditargetkan.
k adalah jumlah kecocokan tetangga terdekat untuk disertakan dalam hasil.

{
    "count": true,
    "select": "title, content, category",
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "myimagevector",
            "k": 5
        },
        {
            "kind": "vector"
            "vector": [
                -0.002222222,
                0.018708462,
                -0.013770515,
            . . .
            ],
            "fields": "mytextvector",
            "k": 5
        }
    ]
}

Indeks pencarian tidak dapat menyimpan gambar. Dengan asumsi bahwa indeks Anda menyertakan bidang untuk file gambar, hasil pencarian akan menyertakan kombinasi teks dan gambar.

Kueri dengan vektorisasi terintegrasi

Bagian ini memperlihatkan kueri vektor yang memanggil vektorisasi terintegrasi untuk mengonversi kueri teks atau gambar menjadi vektor. Kami merekomendasikan paket REST API 2024-07-01 yang stabil, Search Explorer, atau Azure SDK yang lebih baru untuk fitur ini.

Prasyaratnya adalah adanya indeks pencarian yang memiliki vektorizer yang telah dikonfigurasi dan ditugaskan ke bidang vektor. Vektorizer menyediakan informasi koneksi ke model penyematan yang digunakan pada waktu kueri.

Portal Azure
REST API

Search Explorer mendukung vektorisasi terintegrasi pada waktu kueri. Jika indeks Anda berisi bidang vektor dan memiliki vektorizer, Anda dapat menggunakan konversi teks ke vektor bawaan.

Masuk ke portal Azure dan temukan layanan pencarian Anda.
Dari menu sebelah kiri, pilihIndeks> pencarian, lalu pilih indeks Anda.
Pilih tab Profil vektor untuk mengonfirmasi bahwa Anda memiliki vektorizer.
Pilih tab Penjelajah pencarian . Dengan menggunakan tampilan kueri default, Anda bisa memasukkan string teks ke bilah pencarian. Vektorizer bawaan mengonversi string Anda menjadi vektor, melakukan pencarian, dan mengembalikan hasil.

Atau, Anda dapat memilih Tampilkan>tampilan JSON untuk menampilkan atau mengubah kueri. Jika vektor ada, Search Explorer menyiapkan kueri vektor secara otomatis. Anda dapat menggunakan tampilan JSON untuk memilih bidang yang akan digunakan dalam pencarian dan respons, menambahkan filter, dan membuat kueri yang lebih canggih, seperti kueri hibrid. Untuk melihat contoh JSON, pilih tab REST API di bagian ini.

Gunakan Indeks - GET untuk mengembalikan definisi indeks dan memeriksa keberadaan konfigurasi vektorizer. Cari vectorizers dalam definisi indeks Anda. Ini harus menentukan model penyematan yang disebarkan.
Gunakan Search - POST untuk permintaan kueri.
- kind harus diatur ke text.
- text harus memiliki string teks. Ini diteruskan ke vektorizer yang ditetapkan ke bidang vektor.
- fields adalah bidang vektor untuk dicari.
- k adalah jumlah kecocokan vektor yang akan dikembalikan.

Berikut adalah contoh sederhana kueri yang di-vektorisasi pada waktu kueri. String teks di-vektorisasi lalu digunakan untuk mengkueri descriptionVector bidang.

POST https://{{search-service}}.search.windows.net/indexes/{{index}}/docs/search?api-version=2024-07-01
{
    "select": "title, genre, description",
    "vectorQueries": [
        {
            "kind": "text",
            "text": "mystery novel set in London",
            "fields": "descriptionVector",
            "k": 5
        }
    ]
}

Berikut adalah kueri hibrid yang menggunakan vektorisasi terintegrasi untuk kueri teks. Kueri ini mencakup beberapa bidang vektor kueri, beberapa bidang nonvektor, filter, dan peringkat semantik. Sekali lagi, perbedaannya adalah kind kueri vektor dan text string alih-alih vector.

Dalam contoh ini, mesin pencari melakukan tiga panggilan vektorisasi ke vektorizer yang ditetapkan ke descriptionVector, synopsisVector, dan authorBioVector dalam indeks. Vektor yang dihasilkan digunakan untuk mengambil dokumen terhadap bidang masing-masing. Mesin pencari juga menjalankan pencarian kata kunci pada search kueri, yaitu "mystery novel set in London".

POST https://{{search-service}}.search.windows.net/indexes/{{index}}/docs/search?api-version=2024-07-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "search":"mystery novel set in London", 
    "searchFields":"description, synopsis", 
    "semanticConfiguration":"my-semantic-config", 
    "queryType":"semantic",
    "select": "title, author, synopsis",
    "filter": "genre eq 'mystery'",
    "vectorFilterMode": "postFilter",
    "vectorQueries": [
        {
            "kind": "text",
            "text": "mystery novel set in London",
            "fields": "descriptionVector, synopsisVector",
            "k": 50
        },
        {
            "kind": "text"
            "text": "living english author",
            "fields": "authorBioVector",
            "k": 50
        }
    ]
}

Setiap kali Anda menggunakan peringkat semantik dengan vektor, atur k ke 50. Ranker semantik menggunakan hingga 50 kecocokan sebagai input. Menentukan kurang dari 50 mengurangi model peringkat semantik dari input yang diperlukan.

Hasil yang dinilai dari keempat kueri menyatu menggunakan peringkat RRF. Peringkat semantik sekunder diterapkan hanya pada hasil pencarian yang sudah disatukan, meningkatkan hasil yang paling semantik selaras dengan searchFields.

Catatan

Vektorisasi terjadi selama pengindeksan dan kueri. Jika Anda tidak memerlukan pemotongan dan vektorisasi data dalam indeks, Anda dapat melewati langkah-langkah seperti membuat pengindeks, set keterampilan, dan sumber data. Dalam alur kerja ini, vektorisasi hanya digunakan pada waktu kueri untuk mengonversi string teks atau gambar menjadi penyematan. Anda dapat menentukan vektorizer dalam indeks pencarian untuk langkah ini.

Jumlah hasil berpangkat dalam respons kueri vektor

Kueri vektor menentukan k parameter, yang menentukan berapa banyak kecocokan yang dikembalikan dalam hasil. Mesin pencari selalu mengembalikan k jumlah kecocokan. Jika k lebih besar dari jumlah dokumen dalam indeks, jumlah dokumen menentukan batas atas apa yang dapat dikembalikan.

Jika Anda terbiasa dengan pencarian teks lengkap, Anda tahu untuk mengharapkan hasil nol jika indeks tidak berisi istilah atau frasa. Namun, dalam pencarian vektor, operasi pencarian mengidentifikasi tetangga terdekat dan selalu mengembalikan k hasil, bahkan jika tetangga terdekat tidak sejenis itu. Dimungkinkan untuk mendapatkan hasil untuk kueri yang tidak masuk akal atau di luar topik, terutama jika Anda tidak menggunakan petunjuk untuk menetapkan batasan. Hasil yang kurang relevan memiliki skor kesamaan yang lebih buruk, tetapi masih vektor "terdekat" jika tidak ada yang lebih dekat. Oleh karena itu, respons tanpa hasil yang bermakna masih dapat mengembalikan k hasil, tetapi skor kesamaan setiap hasil akan rendah.

Pendekatan hibrid yang menyertakan pencarian teks lengkap dapat mengurangi masalah ini. Solusi lain adalah mengatur ambang minimum pada skor pencarian, tetapi hanya jika kueri adalah kueri vektor tunggal murni. Kueri hibrid tidak sesuai untuk ambang minimum karena rentang RRF jauh lebih kecil dan lebih mudah berubah.

Parameter kueri yang memengaruhi jumlah hasil meliputi:

"k": n hasil untuk kueri yang hanya menggunakan vektor.
"top": n adalah hasil dari kueri hibrida yang menyertakan parameter search.

Keduanya k dan top bersifat opsional. Ketika tidak ditentukan, jumlah default hasil dalam respons adalah 50. Anda dapat mengatur top dan skip untuk menelusuri lebih banyak hasil atau mengubah pengaturan default.

Algoritma peringkat yang digunakan dalam kueri vektor

Peringkat hasil dihitung dengan:

Metrik kesamaan.
RRF jika terdapat beberapa kumpulan hasil pencarian.

Metrik kesamaan

Metrik kesamaan yang ditentukan di bagian indeks vectorSearch untuk kueri khusus vektor. Nilai yang valid adalah cosine, euclidean, dan dotProduct.

Model penyematan Azure OpenAI menggunakan kesamaan kosinus, jadi jika Anda menggunakan model penyematan Azure OpenAI, cosine adalah metrik yang direkomendasikan. Metrik peringkat lain yang didukung termasuk euclidean dan dotProduct.

RRF

Beberapa set dibuat jika kueri menargetkan beberapa bidang vektor, menjalankan beberapa kueri vektor secara paralel, atau merupakan hibrida pencarian vektor dan teks lengkap, dengan atau tanpa peringkat semantik.

Selama eksekusi kueri, kueri vektor hanya dapat menargetkan satu indeks vektor internal. Untuk beberapa bidang vektor dan beberapa kueri vektor, mesin pencari menghasilkan beberapa kueri yang menargetkan indeks vektor masing-masing dari setiap bidang. Hasilnya adalah sekumpulan hasil berperingkat untuk setiap kueri, yang digabungkan dengan menggunakan RRF. Untuk informasi selengkapnya, lihat Penilaian Relevansi menggunakan Fusi Peringkat Timbal Balik.

Pembobotan vektor

weight Tambahkan parameter kueri untuk menentukan bobot relatif setiap kueri vektor yang disertakan dalam operasi pencarian. Nilai ini digunakan saat menggabungkan hasil beberapa daftar peringkat yang dihasilkan oleh dua kueri vektor atau lebih dalam permintaan yang sama, atau dari bagian vektor kueri hibrid.

Defaultnya adalah 1,0, dan nilainya harus berupa angka positif yang lebih besar dari nol.

Bobot digunakan saat menghitung skor RRF dari setiap dokumen. Perhitungan adalah perkalian nilai weight terhadap skor peringkat dari dokumen dalam set hasilnya masing-masing.

Contoh berikut adalah kueri hibrid dengan dua string kueri vektor dan satu string teks. Bobot ditetapkan ke kueri vektor. Kueri pertama adalah 0,5 atau setengah berat, mengurangi kepentingannya dalam permintaan. Kueri vektor kedua dua kali lebih penting.

POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2024-07-01

    { 
      "vectorQueries": [ 
        { 
          "kind": "vector", 
          "vector": [1.0, 2.0, 3.0], 
          "fields": "my_first_vector_field", 
          "k": 10, 
          "weight": 0.5 
        },
        { 
          "kind": "vector", 
          "vector": [4.0, 5.0, 6.0], 
          "fields": "my_second_vector_field", 
          "k": 10, 
          "weight": 2.0
        } 
      ], 
      "search": "hello world" 
    }

Pembobotan vektor hanya berlaku untuk vektor. Kueri teks dalam contoh ini, "hello world", memiliki berat netral implisit 1,0. Namun, dalam kueri hibrid, Anda dapat menambah atau mengurangi pentingnya bidang teks dengan mengatur maxTextRecallSize.

Atur ambang batas untuk mengecualikan hasil penilaian rendah (pratinjau)

Karena pencarian tetangga terdekat selalu mengembalikan tetangga yang diminta, memungkinkan k mendapatkan beberapa kecocokan dengan nilai rendah sebagai bagian dari memenuhi k persyaratan jumlah pada hasil pencarian. Untuk mengecualikan hasil pencarian penilaian rendah, Anda dapat menambahkan threshold parameter kueri yang memfilter hasil berdasarkan skor minimum. Pemfilteran terjadi sebelum menggabungkan hasil dari set pengenalan yang berbeda.

Parameter ini sedang dalam tahap pratinjau. Kami merekomendasikan versi REST API pratinjau 2024-05-01 .

Dalam contoh ini, semua kecocokan yang skor di bawah 0,8 dikecualikan dari hasil pencarian vektor, bahkan jika jumlah hasilnya berada di bawah .k

POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2024-05-01-preview 
    Content-Type: application/json 
    api-key: [admin key] 

    { 
      "vectorQueries": [ 
        { 
          "kind": "vector", 
          "vector": [1.0, 2.0, 3.0], 
          "fields": "my-cosine-field", 
          "threshold": { 
            "kind": "vectorSimilarity", 
            "value": 0.8 
          } 
        }
      ]
    }

MaxTextSizeRecall untuk pencarian hibrid (pratinjau)

Kueri vektor sering digunakan dalam konstruksi hibrid yang menyertakan bidang nonvektor. Jika Anda menemukan bahwa hasil berperingkat BM25 lebih atau kurang diwakili dalam hasil kueri hibrid, Anda dapat mengatur maxTextRecallSize untuk menambah atau mengurangi hasil berperingkat BM25 yang disediakan untuk peringkat hibrid.

Anda hanya dapat mengatur properti ini dalam permintaan hibrid yang menyertakan komponen search dan vectorQueries .