Mengonfigurasi vektorisasi dalam indeks pencarian

Di Pencarian Azure AI, vektorizer mengonversi teks atau gambar menjadi vektor selama eksekusi kueri, memungkinkan Anda mengirimkan kueri teks biasa terhadap bidang vektor tanpa menghitung penyematan sendiri.

Vektorizer didefinisikan dalam indeks pencarian dan ditetapkan ke bidang vektor melalui profil vektor. Pada saat kueri, vektorizer memanggil model penyematan untuk menghasilkan vektor dari input kueri Anda. Untuk informasi selengkapnya, lihat Menggunakan vektorisasi terintegrasi dalam kueri.

Untuk menambahkan vektorizer ke indeks, gunakan wizard impor atau perancang indeks di portal Microsoft Azure, Indeks - Buat Atau Perbarui (REST API), atau paket Azure SDK. Artikel ini menggunakan REST untuk ilustrasi.

Prasyarat

• Indeks dengan bidang vektor yang dapat dicari di layanan pencarian Anda.

• (Opsional) Pembuatan log diagnostik diaktifkan pada layanan pencarian Anda untuk mengonfirmasi eksekusi kueri vektor.

• Penyebaran model penyematan yang didukung untuk vektorizer Anda.

• Izin untuk memperbarui dan mengkueri indeks. Artikel ini menggunakan autentikasi tanpa kunci yang direkomendasikan. Tetapkan peran Kontributor Layanan Pencarian dan Pembaca Data Indeks Pencarian ke akun pengguna Anda, masuk ke Azure, dan dapatkan token akses. Jika Anda menggunakan kunci API sebagai gantinya, dapatkan kunci admin untuk operasi pembaruan dan kunci kueri untuk operasi pencarian.

• Izin untuk menggunakan model embedding. Misalnya, dengan Azure OpenAI, pemanggil harus memiliki izin Pengguna OpenAI Cognitive Services . Anda juga dapat menggunakan kunci API.

• Visual Studio Code dengan ekstensi Klien REST. Buat .rest file atau .http untuk mengirim setiap permintaan REST dalam artikel ini langsung dari editor.

Model embedding yang didukung

Pencarian Azure AI menawarkan beberapa jenis vektorizer, yang masing-masing dipasangkan dengan kemampuan yang sesuai. Keterampilan ini menghasilkan penyematan selama pengindeksan, sementara vektorizer menghasilkan penyematan pada waktu kueri. Anda harus menggunakan model pembenaman yang sama untuk keduanya, jadi pilih pasangan vektorizer–kemampuan yang menunjuk ke penerapan model yang sama.

Tabel berikut mencantumkan vektorizer dan model yang didukung serta keterampilan terkait.

¹ Anda hanya dapat menentukan embed-v-4-0 secara terprogram melalui keterampilan AML atau vektorizer katalog model Microsoft Foundry, bukan melalui portal Microsoft Azure. Namun, Anda dapat menggunakan portal untuk mengelola keterampilan atau pemvektor sesudahnya.

Menentukan vektorizer menggunakan wizard

Wizard Impor data di portal Microsoft Azure dapat membaca file dari Azure Blob Storage, membuat indeks dengan bidang yang dipotong dan di-vektorisasi, dan menambahkan vektorizer. Dari rancangan, penvektor yang dihasilkan oleh wizard diatur untuk menggunakan model penyematan yang sama yang digunakan untuk mengindeks konten blob.

Untuk membuat indeks sampel dengan vektorizer menggunakan wizard:

1. Unggah file ke kontainer di Azure Storage. Kami menggunakan file teks kecil dari e-book Bumi di Malam Hari NASA untuk menguji instruksi ini pada layanan pencarian gratis.

2. Jalankan Impor data wizard. Pilih kontainer blob untuk sumber data.

   

3. Pilih jenis vektorizer dan, jika diperlukan, penggunaan model. Contoh ini menggunakan Azure OpenAI dan deploymen text-embedding-ada-002.

   

4. Setelah wizard selesai dan semua pemrosesan pengindeks selesai, Anda harus memiliki indeks dengan bidang vektor yang dapat dicari. Definisi JSON bidang terlihat seperti ini:

    {
      "name": "text_vector",
      "type": "Collection(Edm.Single)",
      "searchable": true,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false,
      "key": false,
      "dimensions": 1536,
      "vectorSearchProfile": "vector-nasa-ebook-text-profile",
      "synonymMaps": []
    }
   

   Anda juga harus memiliki profil vektor, algoritma pencarian vektor, dan vektorizer. Definisi JSON mereka terlihat seperti ini:

    "algorithms": [
      {
        "name": "vector-nasa-ebook-text-algorithm",
        "kind": "hnsw",
        "hnswParameters": {
          "metric": "cosine",
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500
        }
      }
    ],
   "profiles": [
      {
        "name": "vector-nasa-ebook-text-profile",
        "algorithm": "vector-nasa-ebook-text-algorithm",
        "vectorizer": "vector-nasa-ebook-text-vectorizer"
      }
    ],
    "vectorizers": [
      {
        "name": "vector-nasa-ebook-text-vectorizer",
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "https://my-azure-openai-resource.openai.azure.com",
          "deploymentId": "text-embedding-ada-002",
          "modelName": "text-embedding-ada-002",
        },
      }
    ]
   

Menentukan vektorizer secara terprogram

Jika Anda tidak menggunakan wizard portal atau ingin menambahkan vektorizer ke indeks yang ada, Anda dapat menentukan vektorizer dan profil vektor secara terprogram. Profil vektor menautkan vektorizer ke satu atau beberapa bidang vektor dan menentukan algoritma pencarian vektor yang digunakan untuk struktur navigasi.

Untuk menentukan vektorisasi dan profil vektor dalam indeks yang ada:

1. Ambil definisi indeks menggunakan Indeks - Dapatkan (REST API). Ganti nama layanan, nama indeks, dan token akses dengan nilai Anda sendiri.

   ### Get index definition
   GET https://my-search-service.search.windows.net/indexes/my-index?api-version=2026-04-01 HTTP/1.1
   Authorization: Bearer <your-access-token> // For API keys, replace this line with api-key: <your-admin-api-key>
   

   Warning

   Vectorizer Web API kustom yang diambil berisi <redacted> untuk setiap nilai httpHeaders. Ketika Anda memperbarui vektorizer yang sama tanpa mengubah name, , kindatau uri, Anda dapat mengirim <redacted> ulang untuk mencocokkan nama header yang ada. Jika Anda mengubah uri, kirimkan nilai aktual untuk setiap httpHeaders entri. Untuk aturan pembaruan lainnya, lihat Vektorizer API Web Kustom.

2. Gunakan Indeks - Buat Atau Perbarui (REST API) untuk memperbarui definisi indeks. Tempelkan definisi indeks lengkap di isi permintaan.

   ### Update index definition
   PUT https://my-search-service.search.windows.net/indexes/my-index?api-version=2026-04-01 HTTP/1.1
   Content-Type: application/json
   Authorization: Bearer <your-access-token> // For API keys, replace this line with api-key: <your-admin-api-key>
   
   // Paste your index definition here
   

3. Tambahkan vectorizers bagian ke objek vectorSearch. Bagian ini menentukan informasi koneksi ke model embedding yang tersebar. Contoh berikut mencakup Azure OpenAI dan Custom Web API untuk perbandingan.

   "vectorSearch": {
       "vectorizers": [
         {
           "name": "my_azure_open_ai_vectorizer",
           "kind": "azureOpenAI",
           "azureOpenAIParameters": {
             "resourceUri": "https://url.openai.azure.com",
             "deploymentId": "text-embedding-ada-002",
             "modelName": "text-embedding-ada-002",
             "apiKey": "<your-azure-openai-api-key>"
           }
         },
         {
           "name": "my_custom_vectorizer",
           "kind": "customWebApi",
           "customWebApiParameters": {
             "uri": "https://contoso.embeddings.com",
             "httpMethod": "POST",
             "authResourceId": null,
             "authIdentity": null
           }
         }
       ]
     }
   

4. Tambahkan bagian algorithms ke vectorSearch. Bagian ini menentukan algoritma pencarian vektor yang digunakan untuk struktur navigasi.

   "algorithms": [
     {
       "name": "my_hnsw_algorithm",
       "kind": "hnsw",
       "hnswParameters": {
         "m": 4,
         "efConstruction": 400,
         "efSearch": 500,
         "metric": "cosine"
       }
     }
   ]
   

5. profiles Tambahkan bagian ke vectorSearch. Bagian ini merujuk pada penvektor dan algoritma pencarian berbasis vektor yang ditentukan dalam langkah-langkah sebelumnya.

   "profiles": [ 
     { 
       "name": "my_vector_profile", 
       "algorithm": "my_hnsw_algorithm", 
       "vectorizer": "my_azure_open_ai_vectorizer" 
     }
   ]
   

6. Dalam array fields, tetapkan profil vektor ke satu atau beberapa bidang vektor dengan menentukan properti vectorSearchProfile.

   "fields": [
       ... // Trimmed for brevity
       {
         "name": "vector",
         "type": "Collection(Edm.Single)",
         "dimensions": 1536,
         "vectorSearchProfile": "my_vector_profile",
         "searchable": true,
         "retrievable": true
       },
       {
         "name": "my_second_vector",
         "type": "Collection(Edm.Single)",
         "dimensions": 1536,
         "vectorSearchProfile": "my_vector_profile",
         "searchable": true,
         "retrievable": true
       }
   ]
   

7. Kirim permintaan PUT untuk memperbarui definisi indeks. Jika permintaan berhasil, Anda harus menerima 204 No Content respons.

8. Untuk memverifikasi vectorizer dan profil vektor, jalankan ulang permintaan GET dari langkah pertama. Konfirmasikan bahwa:

   • Array vectorSearch.vectorizers berisi definisi vektorizer Anda dengan parameter kind dan koneksi yang benar.

   • Array vectorSearch.profiles menyertakan profil yang mereferensikan vektorizer Anda berdasarkan nama.

   • Array vectorSearch.algorithms menyertakan algoritma pencarian vektor yang dirujuk oleh profil Anda.

   • Properti vectorSearchProfile pada bidang vektor Anda dalam fields array cocok dengan nama profil.

Menguji vektorizer

Untuk mengonfirmasi vektorizer berfungsi, kirim kueri vektor yang meneruskan string teks alih-alih vektor. Contoh berikut menargetkan indeks sampel dari Tentukan vektorizer menggunakan wizard, tetapi Anda dapat menguji indeks Anda sendiri dengan menyesuaikan nama bidang dan parameter kueri.

Gunakan Dokumen - Cari Posting (REST API) untuk mengajukan permintaan. Ganti nama layanan, nama indeks, dan token akses dengan nilai Anda sendiri.

### Test a vectorizer with a vector query
POST https://my-search-service.search.windows.net/indexes/vector-nasa-ebook-txt/docs/search?api-version=2026-04-01 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <your-access-token> // For API keys, replace this line with api-key: <your-query-api-key>

{
    "count": true,
    "select": "title, chunk",
    "vectorQueries": [
        {
            "kind": "text",
            "text": "what cloud formations exist in the troposphere",
            "fields": "text_vector",
            "k": 3,
            "exhaustive": true
        }
    ]
}

Poin-poin penting:

• "kind": "text" memberi tahu mesin pencari bahwa input adalah string teks dan untuk menggunakan vektorizer yang terkait dengan bidang pencarian.

• "text" adalah string bahasa biasa untuk vektorisasi.

• "fields": "text_vector" adalah nama bidang yang akan dikueri. Jika Anda menggunakan indeks sampel yang dihasilkan oleh wizard, bidang vektor yang dihasilkan diberi nama text_vector.

• "exhaustive": true mengabaikan grafik HNSW dan melakukan pencarian brute-force di semua vektor. Pengaturan ini berguna untuk menguji akurasi tetapi lebih lambat dari perkiraan default pencarian. Hapus parameter ini dalam kueri produksi untuk performa yang lebih baik.

• Kueri tidak mengatur properti vektorizer apa pun. Mesin pencari membacanya secara otomatis dari profil vektor yang ditugaskan ke bidang tersebut.

Jika vektorizer dikonfigurasi dengan benar, respons mengembalikan dokumen yang cocok yang diberi peringkat oleh kesamaan. Anda harus mendapatkan tiga hasil (k: 3), yang pertama adalah yang paling relevan.

{
    "@odata.count": 3,
    "value": [
        {
            "@search.score": 0.66195244,
            "chunk": "Cloud Shadow\tGermany\nIn November 2012, the Earth Observing...",
            "title": "page-25.txt"
        },
        ... // Trimmed for brevity
    ]
}

Troubleshooting

Jika vektorizer Anda tidak berfungsi seperti yang diharapkan, mulailah dengan tabel kesalahan umum lalu periksa log diagnostik Anda untuk detail selengkapnya.

Kesalahan umum

Tabel berikut ini mencantumkan kesalahan vektorizer umum dan cara mengatasinya.

Periksa log

Jika Anda mengaktifkan pembuatan log diagnostik untuk layanan pencarian Anda, jalankan kueri Kusto berikut untuk mengonfirmasi eksekusi kueri di bidang vektor Anda.

OperationEvent
| where TIMESTAMP > ago(30m)
| where Name == "Query.Search" and AdditionalInfo["QueryMetadata"]["Vectors"] has "TextLength"

Praktik terbaik

• Gunakan identitas terkelola alih-alih kunci API dalam produksi. Identitas terkelola lebih aman dan menghindari beban lebih pada perputaran kunci. Untuk informasi selengkapnya, lihat Mengonfigurasi layanan pencarian untuk menyambungkan menggunakan identitas terkelola.

• Sebarkan model penyematan di wilayah yang sama dengan layanan pencarian Anda. Kolokasi mengurangi latensi dan meningkatkan kecepatan transfer data antar layanan. Vektorizer tersedia di semua wilayah tempat Pencarian Azure AI tersedia, tetapi ketersediaan model bervariasi menurut penyedia.

• Gunakan implementasi terpisah dari model embedding yang sama untuk pengindeksan dan kueri. Penyebaran khusus memungkinkan Anda mengalokasikan kuota TPM secara independen untuk setiap beban kerja dan mempermudah mengidentifikasi sumber lalu lintas.

• Pantau kuota TPM Azure OpenAI Anda. Jika Anda mencapai batas TPM, tinjau batas kuota dan pertimbangkan untuk meminta batas yang lebih tinggi melalui kasus dukungan.

• Tinjau praktik terbaik untuk keterampilan penyematan Azure OpenAI. Panduan yang sama berlaku untuk vektorizer Azure OpenAI.

Konten terkait

• Pencarian vektor di Pencarian Azure AI
• Penyematan vektor terintegrasi
• Membuat kueri vektor