Membuat kueri vektor di Pencarian Azure AI

Jika Anda memiliki indeks vector di Pencarian Azure AI, artikel ini menjelaskan cara:

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

Anda juga dapat menggunakan Search Explorer di portal Azure.

Prasyarat

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 bagaimana menghasilkan penyematan dalam repositori azure-search-vector-samples.

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

Berikut adalah contoh REST API dari string kueri yang dikirimkan ke penyebaran model embedding 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 untuk panggilan yang berhasil ke model yang sudah disebarkan adalah 202.

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.

Versi stabil mendukung:

  • vectorQueries adalah konstruksi untuk pencarian vektor.
  • vectorQueries.kind diatur ke vector untuk array vektor atau text jika input adalah string dan jika 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 pencocokan 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 sesungguhnya memiliki 1.536 embedding, yang dipangkas untuk memudahkan pembacaan dalam contoh ini.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2026-04-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
        }
    ]
}

Respons kueri vektor

Dalam Pencarian Azure AI, respons kueri terdiri dari semua bidang retrievable 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 penyematan, yang dipangkas dalam contoh ini untuk 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-poin penting:

  • k menentukan berapa banyak hasil tetangga terdekat yang dikembalikan, dalam hal ini, tiga. Kueri vektor selalu mengembalikan k hasil, dengan asumsi bahwa ada setidaknya k dokumen, walaupun beberapa dokumen memiliki kesamaan yang buruk. Ini karena algoritma menemukan k tetangga terdekat dari 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 untuk 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=2026-04-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 pencarian 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 dalam keduanya myImageVector dan myTextVector, tapi mengirim dua penyematan kueri yang berbeda, yang masing-masing dijalankan secara paralel. Hasil kueri ini dinilai menggunakan fusi peringkat timbal balik (RRF).

  • vectorQueries menyediakan berbagai kueri vektor.
  • vector berisi vektor gambar dan vektor teks dalam indeks pencarian. Setiap instance 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 2026-04-01 yang stabil REST API, Search Explorer, atau paket Azure SDK yang lebih baru untuk fitur ini.

Prasyarat adalah indeks pencarian yang memiliki vektorizer yang sudah dikonfigurasi dan ditetapkan ke bidang vektor. Pemvektor menyediakan informasi koneksi ke model embedding yang digunakan saat kueri.

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.

  1. Buka layanan pencarian Anda di portal Azure.

  2. Dari menu sebelah kiri, pilihIndeks> pencarian, lalu pilih indeks Anda.

  3. Pilih tab Profil vektor untuk mengonfirmasi bahwa Anda memiliki vektorizer.

    Cuplikan layar pengaturan vektorizer dalam indeks pencarian.

  4. 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.

Jumlah hasil terperingkat 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 dari kueri yang tidak masuk akal atau di luar topik, terutama jika Anda tidak menggunakan petunjuk untuk mengatur 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 kondusif untuk ambang minimum karena rentang RRF jauh lebih kecil dan lebih volatil.

Parameter kueri yang memengaruhi jumlah hasil meliputi:

  • "k": n hasil untuk kueri yang hanya berbasis vektor.
  • "top": n hasil untuk kueri hibrid yang menyertakan search parameter.

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

Algoritma peringkat yang digunakan dalam kueri vektor

Peringkat hasil dihitung dengan:

  • Metrik kemiripan.
  • RRF jika ada lebih dari satu set hasil pencarian.

Metrik kemiripan

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

Azure model penyematan OpenAI menggunakan kesamaan kosinus, jadi jika Anda menggunakan model penyematan OpenAI Azure, 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. Output adalah sekumpulan hasil berperingkat untuk setiap kueri, yang dikombinasikan menggunakan RRF. Untuk informasi selengkapnya, lihat Penilaian relevansi menggunakan Reciprocal Rank Fusion.

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 merupakan pengali dari nilai weight terhadap skor peringkat dokumen dalam set hasil masing-masing.

Contoh berikut adalah kueri hibrid dengan dua string kueri vektor dan satu string teks. Bobot dialokasikan ke kueri vektor. Kueri pertama memiliki bobot 0,5 atau setengah, yang 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=2026-04-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 k, dimungkinkan untuk mendapatkan beberapa kecocokan dengan penilaian rendah sebagai bagian dari memenuhi persyaratan jumlah k 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 pratinjau terbaru Dokumen - Pencarian Pos (REST API).

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=2025-11-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 
          } 
        }
      ]
    }

Langkah berikutnya

Sebagai langkah berikutnya, tinjau contoh kode kueri vektor di Python, C# atau JavaScript.

  • Last updated on