Arama dizininde vektörleştirici yapılandırma

Azure Yapay Zeka Arama'te vektörleştirici , sorgu yürütme sırasında metinleri veya görüntüleri vektörlere dönüştürerek, eklemeleri kendiniz hesaplamadan vektör alanlarına düz metin sorguları göndermenize olanak sağlar.

Vektörleştirici bir arama dizininde tanımlanır ve vektör profili aracılığıyla vektör alanlarına atanır. Sorgu zamanında vektörleştirici, sorgu girişinizden bir vektör oluşturmak için bir ekleme modeli çağırır. Daha fazla bilgi için bkz. Sorgularda tümleşik vektörleştirmeyi kullanma.

Dizine vektörleştirici eklemek için Azure portalında içeri aktarma sihirbazını veya dizin tasarımcısını, Dizinler - Oluşturma veya Güncelleştirme 'yi (REST API) veya bir Azure SDK paketini kullanın. Bu makalede çizim için REST kullanılır.

Önkoşullar

• Arama hizmetinizde aranabilir vektör alanları olan bir dizin .

• (İsteğe bağlı) Vektör sorgu yürütmesini onaylamak için arama hizmetinizde tanılama günlüğü etkinleştirildi .

• Vektörleştiriciniz için desteklenen bir ekleme modeli dağıtımı.

• Dizini güncelleştirme ve sorgulama izinleri. Bu makalede önerilen anahtarsız kimlik doğrulaması kullanılır. Arama Hizmeti Katkıda Bulunanı ve Arama Dizini Veri Okuyucusu rollerini kullanıcı hesabınıza atayın, Azure'da oturum açın ve erişim belirteci alın. Bunun yerine API anahtarları kullanıyorsanız, güncelleştirme işlemleri için bir yönetici anahtarı ve arama işlemleri için bir sorgu anahtarı alın.

• Ekleme modelini kullanma izinleri. Örneğin, Azure OpenAI ile çağıranın Bilişsel Hizmetler OpenAI Kullanıcı izinlerine sahip olması gerekir. Api anahtarı da kullanabilirsiniz.

• REST İstemci uzantısıylaVisual Studio Code. Bu makaledeki her REST isteğini doğrudan düzenleyiciden göndermek için bir .rest veya .http dosyası oluşturun.

Desteklenen ekleme modelleri

Azure Yapay Zeka Arama, her biri ilgili beceriyle eşleştirilmiş çeşitli vektörleştirici türleri sunar. Beceri, dizin oluşturma sırasında eklemeler oluştururken vektörleştirici sorgu zamanında eklemeler oluşturur. Her ikisi için de aynı ekleme modelini kullanmanız gerekir, bu nedenle aynı model dağıtımına işaret eden bir vektörleştirici-beceri çifti seçin.

Aşağıdaki tabloda vektörleştiriciler, desteklenen modeller ve ilişkili beceriler listelenmektedir.

¹ Program aracılığıyla yalnızca embed-v-4-0 veya Microsoft Foundry model kataloğu vektörleştiricisi aracılığıyla belirtebilirsiniz, Azure portalı üzerinden belirtemezsiniz. Ancak, daha sonra beceri kümesini veya vektörleştiriciyi yönetmek için portalı kullanabilirsiniz.

Sihirbaz kullanarak vektörleştirici tanımlama

Azure portalındaki Verileri içeri aktarma sihirbazı Azure Blob Depolama'dan dosyaları okuyabilir, öbeklenmiş ve vektörleştirilmiş alanlarla bir dizin oluşturabilir ve vektörleştirici ekleyebilir. Tasarım gereği, sihirbaz tarafından oluşturulan vektörleştirici, blob içeriğini dizine almak için kullanılan ekleme modeline ayarlanır.

Sihirbazı kullanarak vektörleştirici ile örnek dizin oluşturmak için:

1. Azure Depolama'da bir kapsayıcıya dosya yükleme. Bu yönergeleri ücretsiz bir arama hizmetinde test etmek için NASA'nın Dünya'daki Gece e-kitabındaki küçük metin dosyalarını kullandık.

2. Verileri içeri aktarma sihirbazını çalıştırın. Veri kaynağı için blob kapsayıcısını seçin.

   

3. Bir vektörleştirici türü ve varsa bir model dağıtımı seçin. Bu örnekte Azure OpenAI ve text-embedding-ada-002 dağıtımı kullanılır.

   

4. Sihirbaz tamamlandıktan ve tüm dizin oluşturucu işlemleri tamamlandıktan sonra aranabilir vektör alanına sahip bir dizininiz olmalıdır. Alanın JSON tanımı şöyle görünür:

    {
      "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": []
    }
   

   Ayrıca bir vektör profiline, vektör arama algoritmasına ve vektörleştiriciye sahip olmanız gerekir. JSON tanımları şöyle görünür:

    "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",
        },
      }
    ]
   

Vektörleştiriciyi program aracılığıyla tanımlama

Portal sihirbazını kullanmadıysanız veya var olan bir dizine vektörleştirici eklemek istiyorsanız, vektörleştirici ve vektör profilini program aracılığıyla tanımlayabilirsiniz. Vektör profili bir vektörleştiriciyi bir veya daha fazla vektör alanına bağlar ve gezinti yapıları için kullanılan vektör arama algoritmasını belirtir.

Var olan bir dizinde vektörleştirici ve vektör profili tanımlamak için:

1. Dizinler - Get (REST API) kullanarak dizin tanımını alın. Hizmet adını, dizin adını ve erişim belirtecini kendi değerlerinizle değiştirin.

   ### 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

   Alınan Özel Web API vektörleştiricisi, her httpHeaders değeri için <redacted> içerir. Aynı vektörleştiriciyi name, kind veya uri öğelerini değiştirmeden güncellediğinizde, mevcut üst bilgi adlarıyla eşleştirmek için <redacted> öğesini yeniden gönderebilirsiniz. uri öğesini değiştirirseniz, her httpHeaders girdisi için gerçek değerler gönderin. Diğer güncelleştirme kuralları için bkz . Özel Web API vektörleştiricisi.

2. Dizin tanımını güncelleştirmek için Dizinler - Oluştur veya Güncelleştir (REST API) kullanın. tam dizin tanımını istek gövdesine yapıştırın.

   ### 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. vectorizers bölümünü vectorSearch nesneye ekleyin. Bu bölüm, dağıtılan bir ekleme modeline bağlantı bilgilerini belirtir. Aşağıdaki örnek, karşılaştırma için hem Azure OpenAI hem de Özel Web API'sini içerir.

   "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. algorithms bir bölümünü vectorSearch bölümüne ekleyin. Bu bölümde, gezinti yapıları için kullanılan bir vektör arama algoritması tanımlanmıştır.

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

5. profiles, vectorSearch bölümüne ekleyin. Bu bölüm, önceki adımlarda tanımlanan vektörleştirici ve vektör arama algoritmasına başvurur.

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

6. fields dizisinde, vectorSearchProfile özelliğini belirterek, vektör profilini bir veya daha fazla vektör alanına atayın.

   "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. Dizin tanımını güncelleştirmek için PUT isteğini gönderin. İstek başarılı olursa bir 204 No Content yanıt almanız gerekir.

8. Vektörleştiriciyi ve vektör profilini doğrulamak için ilk adımda GET isteğini yeniden çalıştırın. Şunları onaylayın:

   • vectorSearch.vectorizers dizisi, doğru kind ve bağlantı parametreleri ile vektörleştirici tanımınızı içerir.

   • Dizi, vectorSearch.profiles vektörleştiricinize adına referans veren bir profil içerir.

   • Dizi, profilinizde referans verilen vektör arama algoritmasını içerir.

   • vectorSearchProfile Dizideki vektör alanlarınızın fields üzerindeki özellik profil adıyla eşleşir.

Vektörleştiriciyi test edin

Vektörleştiricinin çalıştığını onaylamak için, vektör yerine metin dizesi geçiren bir vektör sorgusu gönderin. Aşağıdaki örnek, Sihirbaz kullanarak vektörleştirici tanımlama'dan örnek dizini hedefler, ancak alan adlarını ve sorgu parametrelerini ayarlayarak kendi dizininizi test edebilirsiniz.

İsteği göndermek için Belgeler - Arama Gönderisi 'ni (REST API) kullanın. Hizmet adını, dizin adını ve erişim belirtecini kendi değerlerinizle değiştirin.

### 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
        }
    ]
}

Önemli noktalar:

• "kind": "text" arama altyapısına girişin bir metin dizesi olduğunu ve arama alanıyla ilişkili vektörleştiriciyi kullanmasını söyler.

• "text" vektörleştirecek düz dil dizesidir.

• "fields": "text_vector" , sorgunun yapılacağı alanın adıdır. Sihirbaz tarafından oluşturulan örnek dizini kullanırsanız, oluşturulan vektör alanı olarak adlandırılır text_vector.

• "exhaustive": true HNSW grafiğini devre dışı bırakır ve tüm vektörler üzerinde kaba kuvvet araması yapar. Bu ayar doğruluğu test etmede kullanışlıdır ancak varsayılan yaklaşık aramadan daha yavaştır. Daha iyi performans için üretim sorgularında bu parametreyi kaldırın.

• Sorgu hiçbir vektörleştirici özelliği ayarlamaz. Arama altyapısı bunları alana atanan vektör profilinden otomatik olarak okur.

Vektörleştirici doğru yapılandırıldıysa, yanıt benzerliğe göre derecelendirilen eşleşen belgeleri döndürür. Üç sonuç (k: 3) almalısınız, bunlardan ilki en ilgili olanıdır.

{
    "@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
    ]
}

Sorun giderme

Vektörleştiriciniz beklendiği gibi çalışmıyorsa yaygın hatalar tablosuyla başlayın ve daha fazla ayrıntı için tanılama günlüklerinizi denetleyin.

Sık karşılaşılan hatalar

Aşağıdaki tabloda yaygın vektörleştirici hataları ve bunların nasıl çözüleceğini listeledik.

Günlükleri denetleme

Arama hizmetiniz için tanılama günlüğünü etkinleştirdiyseniz, vektör alanınızda sorgu yürütmeyi onaylamak için aşağıdaki Kusto sorgusunu çalıştırın.

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

En iyi yöntemler

• Üretimde API anahtarları yerine yönetilen kimlik kullanın. Yönetilen kimlikler daha güvenlidir ve anahtar döndürme ek yükünü önler. Daha fazla bilgi için, Yönetilen kimlik kullanarak bağlanmak için bir arama hizmetini yapılandırma bölümüne bakın.

• Ekleme modelini arama hizmetinizle aynı bölgeye dağıtın. Birlikte bulundurma, gecikme süresini azaltır ve hizmetler arasında veri aktarımının hızını artırır. Vektörleştiriciler, Azure Yapay Zeka Arama'in kullanılabildiği tüm bölgelerde kullanılabilir, ancak model kullanılabilirliği sağlayıcıya göre değişir.

• Dizin oluşturma ve sorgular için aynı ekleme modelinin ayrı dağıtımlarını kullanın. Ayrılmış dağıtımlar, her iş yükü için TPM kotasını bağımsız olarak ayırmanıza ve trafik kaynaklarını tanımlamanızı kolaylaştırmanıza olanak sağlar.

• Azure OpenAI TPM kotanızı izleyin. TPM sınırınıza ulaştıysanız kota sınırlarını gözden geçirin ve destek talebi aracılığıyla daha yüksek bir sınır istemeyi göz önünde bulundurun.

• Azure OpenAI ekleme becerisi için en iyi yöntemleri gözden geçirin. Aynı kılavuz Azure OpenAI vektörleştiricisi için de geçerlidir.

İlgili içerik

• Azure AI Arama'da vektör araması
• Tümleşik vektör ekleme
• Vektör sorgusu oluşturma