Azure Yapay Zeka Arama'te vektör dizini oluşturma

Azure Yapay Zeka Arama'te vektörleri bir arama dizininde depolayabilir ve sorgulayabilirsiniz. Vektör dizini, vektör alanları, görsel olmayan alanlar ve vektör yapılandırma bölümü içeren bir dizin şeması tarafından tanımlanır.

Vektör dizini oluşturmak, örtük olarak vektör sorguları için corpus görevi görecek bir ekleme alanı oluşturur. Ekleme alanı, aynı ekleme modelinden eklemelerle doldurulmuş tüm vektör alanlarından oluşur. Sorgu zamanında sistem, vektör sorgusunu dizine alınan vektörlerle karşılaştırır ve anlamsal benzerlik temelinde sonuçlar döndürür.

Bu makalede, aşağıdaki adımları içeren bir vektör dizininin nasıl oluşturulacağını açıklamak için REST kullanılır:

Temel iş akışını anladıktan sonra test ve üretim kodunda vektörleri kullanma konusunda rehberlik için azure-search-vector-samples GitHub deposundaki Azure SDK örneklerini deneyin. Tümleşik vektörleştirme aracılığıyla vektör dizini oluşturmak için Azure portalını da kullanabilirsiniz.

Önkoşullar

• Herhangi bir bölgede ve herhangi bir katmanda bir Azure AI Arama hizmeti . Azure Görüntü İşleme becerisi ve vektörleştiricisi ile tümleşik vektörleştirme kullanmayı planlıyorsanız, Azure Yapay Zeka Arama'in Döküm Araçları'nda Azure Vision'da barındırılan ekleme modelleriyle aynı bölgede olması gerekir.

• Önerilen anahtarsız kimlik doğrulaması için Kullanıcı hesabınıza, yönetilen kimliğinize veya hizmet sorumlunuza Arama Hizmeti Katkıda Bulunanı ve Arama Dizini Veri Katkıda Bulunanı rollerini atayın. Daha az güvenli anahtar tabanlı kimlik doğrulaması için bir yönetici API anahtarı alın.

• Dizine yüklenecek vektör eklemeleri içeren kaynak belgeler. Bu görev için tümleşik vektörleştirmeyi de kullanabilirsiniz.

• Ekleme modelinizin boyut sınırı. text-embedding-ada-002 1536'da, text-embedding-3-small 1 ile 1536 arasında ve text-embedding-3-large 1 ile 3072 arasında sabittir.

• Ekleme modelinizin benzerlik ölçümü. Azure OpenAI modelleri kullanır cosine.

• Dizin oluşturma hakkında bilgi. Şema her zaman belge anahtarı için bir alan, arama veya filtreler için alanlar ve dizin oluşturma ve sorgular sırasında gereken davranışlara yönelik diğer yapılandırmaları içerir.

Belgeleri dizin oluşturma için hazırlama

Dizin oluşturmadan önce vektör ve seçici olmayan veri alanlarını içeren bir belge yükü oluşturun. Belge yapısı dizin şemasının alan koleksiyonuna uygun olmalıdır.

Kaynak belgelerinizin aşağıdaki içeriği sağladığından emin olun:

Arama dizininiz, desteklemek istediğiniz tüm sorgu senaryoları için alanlar ve içerik içermelidir. Ürün adlarını, sürümlerini, meta verilerini veya adreslerini aramak veya filtrelemek istediğinizi varsayalım. Bu durumda vektör benzerlik araması özellikle yararlı değildir. Ayrıntılı içeriği yineleyen anahtar sözcük araması, coğrafi arama veya filtreler daha iyi bir seçim olabilir. Hem vektör hem de nonvector alanlarını kapsayan bir arama dizini, sorgu oluşturma ve yanıt oluşturma için maksimum esneklik sağlar.

Belge yükü örneği için Dizin oluşturma için vektör verilerini yükleme bölümüne bakın.

Temel bir dizinle başlayın

Vektör yapılandırması ve vektör alanları eklemeden önce birlikte çalışabileceğiniz bir tanımın olması için en düşük şemayla başlayın. Basit bir dizin aşağıdaki örneğe bakabilir. Dizin şeması hakkında daha fazla bilgi için bkz. Arama dizini oluşturma.

Dizinin gerekli bir ada, gerekli bir belge anahtarına ("key": true) ve düz metin olarak insan tarafından okunabilen içerik alanlarına sahip olduğuna dikkat edin. Vektörleştirmek istediğiniz içeriğin insan tarafından okunabilen bir sürümüne sahip olmak yaygındır. Örneğin, PDF dosyasından bir metin öbekleriniz varsa, dizin şemanızda düz metin öbekleri için bir alan ve vektörleştirilmiş öbekler için ikinci bir alan olmalıdır.

Temel bir dizin, bir "name" koleksiyonu ve ek yapılandırma için bazı diğer yapılar aşağıdadır:

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

Vektör arama yapılandırması ekleme

Ardından şemanıza bir "vectorSearch" yapılandırma ekleyin. Burada tanımladığınız profiller vektör alanının tanımının bir parçası haline geldiği için, alan tanımlarından önce bir yapılandırma belirtmek yararlı olur. Şemada, vektör yapılandırması genellikle alanlar koleksiyonundan sonra (belki de , "analyzers"ve "scoringProfiles"' nin ardından"suggesters") eklenir. Ancak, düzen önemli değildir.

Vektör yapılandırması şunları içerir:

• vectorSearch.algorithms , vektör düğümleri arasında "en yakın komşu" bilgilerini oluşturmak için dizin oluşturma sırasında kullanılır.
• vectorSearch.compressions skaler veya ikili niceleme, fazla örnekleme ve özgün vektörlerle yeniden sıralama için.
• vectorSearch.profiles algoritma ve sıkıştırma yapılandırmalarının birden çok bileşimini belirtmek için.

Adımlar aşağıdaki gibidir:

1. Dizini oluşturmak için Dizin Oluştur veya Güncelleştir REST API'sini kullanın.

2. Dizinde, ekleme alanını oluşturmak için kullanılan arama algoritmalarını belirten bir vectorSearch bölüm ekleyin.

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

   Önemli noktalar:

   • Sıkıştırma, algoritma ve profil yapılandırmalarının adları dizin içindeki türü için benzersiz olmalıdır.

   • vectorSearch.compressionsveya scalarQuantizationolabilirbinaryQuantization. Skaler niceleme, kayan değerleri daha dar veri türlerine sıkıştırır. İkili niceleme, float'ları ikili 1 bit değerlere dönüştürür.

   • vectorSearch.compressions.rescoringOptions özgün, sıkıştırılmamış vektörleri kullanarak benzerliği yeniden hesaplar ve ilk arama sorgusu tarafından döndürülen en iyi sonuçları yeniden hesaplar. Sıkıştırılmamış vektörler, false olsa stored bile arama dizininde bulunur. Bu özellik isteğe bağlıdır. Varsayılan değer doğrudur.

   • vectorSearch.compressions.rescoringOptions.defaultOversampling , bilgilerdeki azalmayı nicelemeden dengelemek için daha geniş bir olası sonuç kümesini dikkate alır. Olası sonuçlara yönelik formül, sorgudaki formülden ve bir fazla örnekleme çarpanından oluşur k . Örneğin, sorgu k 5 olarak belirtiliyorsa ve fazla örnekleme oranı 20 ise, bu amaç için özgün sıkıştırılmamış vektörü kullanarak yeniden sıralama yapmak üzere etkin bir biçimde 100 belge talep etmektedir. Yalnızca en yüksek k yeniden sıralanan sonuçlar döndürülür. Bu özellik isteğe bağlıdır. Varsayılan değer 4'dür.

   • vectorSearch.compressions.scalarQuantizationParameters.quantizedDataType olarak ayarlanmalıdır int8. Şu anda desteklenen tek temel veri türü budur. Bu özellik isteğe bağlıdır. Varsayılan int8 değeridir.

   • vectorSearch.algorithms hnsw veya exhaustiveKnnşeklindedir. Bunlar, dizin oluşturma sırasında vektör içeriğini düzenlemek için kullanılan En Yakın Yaklaşık Komşular (ANN) algoritmalarıdır.

   • vectorSearch.algorithms.m çift yönlü bağlantı sayısıdır. Varsayılan değer 4'dür. Değer aralığı 4 ile 10 arasındadır. Düşük değerler sonuçlarda daha az gürültü vermelidir.

   • vectorSearch.algorithms.efConstruction dizin oluşturma sırasında kullanılan en yakın komşu sayısıdır. Varsayılan değer 400'dür. 100 ila 1.000 arası bir aralıktır.

   • "vectorSearch.algorithms.efSearch arama sırasında kullanılan en yakın komşu sayısıdır. Varsayılan değer 500'dür. 100 ila 1.000 arası bir aralıktır.

   • vectorSearch.algorithms.metric , Azure OpenAI kullanıyorsanız olmalıdır cosine ; aksi takdirde kullandığınız ekleme modeliyle ilişkili benzerlik ölçümünü kullanın. Desteklenen değerler , cosinedotProduct, euclideanve hamming (ikili verilerin dizinini oluşturmak için kullanılır).

   • vectorSearch.profiles daha zengin tanımları kabul etmek için bir soyutlama katmanı ekleyin. Bir profil vectorSearch içinde tanımlanır ve her vektör alanında adı ile referans verilir. Sıkıştırma ve algoritma yapılandırmalarının bir birleşimidir. Bu özelliği bir vektör alanına atarsınız ve alanların algoritmasını ve sıkıştırmasını belirler.

Alanlar koleksiyonuna vektör alanı ekleme

Vektör yapılandırmasına sahip olduktan sonra, alanlar koleksiyonuna bir vektör alanı ekleyebilirsiniz. Alan koleksiyonunun belge anahtarı için bir alan, vektör alanları ve RAG iş yüklerindekarma arama senaryoları veya sohbet modeli tamamlama için ihtiyacınız olan diğer tüm görsel olmayan alanları içermesi gerektiğini unutmayın.

Vektör alanları , veri türleri, vektörlerin çıkışını almak için kullanılan ekleme modelini temel alan bir dimensions özellik ve önceki adımda oluşturduğunuz bir vektör profili ile karakterize edilir.

1. Dizini oluşturmak ve alanlar koleksiyonuna bir vektör alanı eklemek için Dizin Oluştur veya Güncelleştir REST API'sini kullanın.

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

2. Aşağıdaki özniteliklere sahip bir vektör alanı belirtin. Alan başına oluşturulan bir ekleme depolayabilirsiniz. Her vektör alanı için:

   • type bir vektör veri türü olmalıdır. Collection(Edm.Single) , modelleri eklemek için en yaygın olanıdır.
   • dimensions ekleme modeli tarafından oluşturulan boyut sayısıdır. Text-embedding-ada-002 için 1536 olarak düzeltildi. Metin ekleme-3 model serisi için bir değer aralığı vardır. Vektör oluşturmak için tümleşik vektörleştirme ve ekleme becerisi kullanıyorsanız, bu özelliğin ekleme becerisi tarafından kullanılan boyut değerine ayarlandığından emin olun.
   • vectorSearchProfile , dizinin başka bir yerinde tanımlanan bir profilin adıdır.
   • searchable doğru olmalıdır.
   • retrievable true veya false olabilir. True, ham vektörleri (bunların 1.536'sı) düz metin olarak döndürür ve depolama alanı kullanır. Sonraki uygulamaya vektör sonucunu geçiriyorsanız, true olarak ayarlayın.
   • stored true veya false olabilir. Vektörlerin ek bir kopyasının alma için depolanıp depolanmadığını belirler. Daha fazla bilgi için bkz . Vektör boyutunu küçültme.
   • filterable, facetableve sortable yanlış olmalıdır.

3. title ve filterable'i true olarak ayarlayarak koleksiyona filtrelenebilir non-vektör alanlar ekleyin. Bu, ön filtreleme, son filtreleme veya sıkı son filtreleme (önizleme) işlemlerini vektör sorgusu üzerinde çağırmak istediğinizde gereklidir.

4. Dizine eklediğiniz metin içeriğinin maddesini ve yapısını tanımlayan diğer alanları ekleyin. En azından bir belge anahtarına ihtiyacınız vardır.

   Sorguda veya yanıtında yararlı olan alanlar da eklemeniz gerekir. Aşağıdaki örnekte, başlık ve içerik (titleVector ve contentVector) için vektörlere eşdeğer vektör alanları gösterilmektedir. Ayrıca, bir arama sonucunda sıralama, filtreleme ve okuma için yararlı olan eşdeğer metin içeriği alanları (title ve content) da sağlar.

   Aşağıdaki örnekte alanlar koleksiyonu gösterilmektedir:

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

Dizin oluşturma için vektör verilerini yükleme

Dizin oluşturma için sağladığınız içerik dizin şemasına uygun olmalı ve belge anahtarı için benzersiz bir dize değeri içermelidir. Prevektörleştirilmiş veriler, bir veya daha fazla vektör alanına yüklenir ve bu alan, seçici olmayan içerik içeren diğer alanlarla birlikte bulunabilir.

Veri alımı için gönderme veya çekme yöntemleri kullanabilirsiniz.

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

Vektör içeriği için dizin sorgulama

Doğrulama amacıyla, Azure portalında Arama Gezgini'ni veya REST API çağrısını kullanarak dizini sorgulayabilirsiniz. Azure Yapay Zeka Arama vektörleri insan tarafından okunabilen metne dönüştüremediğinden, aynı belgedeki eşleşmenin kanıtını sağlayan alanları döndürmeyi deneyin. Örneğin, vektör sorgusu titleVector alanını hedefliyorsa, arama sonuçları için title alanını seçebilirsiniz.

Alanlar, sonuçlara dahil edilmek için retrievable olarak ilişkilendirilmelidir.

POST https://my-search-service.search.windows.net/indexes/my-index/docs/search?api-version=2026-04-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "vector": {
        "value": [
            -0.009154141,
            0.018708462,
            . . . 
            -0.02178128,
            -0.00086512347
        ],
        "fields": "contentVector",
        "k": 5
    },
    "select": "title, content, category"
}

Vektör dizinini güncelleştirme

Vektör dizinini güncelleştirmek için şemayı değiştirin ve belgeleri yeni alanları dolduracak şekilde yeniden yükleyin. Şema güncelleştirmeleri için API'ler arasında Oluşturma veya Güncelleştirme Dizini (REST), .NET için Azure SDK'da CreateOrUpdateIndex , Python için Azure SDK'da create_or_update_index ve diğer Azure SDK'larında benzer yöntemler bulunur.

Dizini güncelleştirmeyle ilgili standart yönergeler için bkz. Dizini güncelleştirme veya yeniden derleme.

Önemli noktalar şunlardır:

• Var olan alanların güncellenmesi ve silinmesi için genellikle bırakma ve tam dizin yeniden oluşturulması gerekir.

• Yeniden derleme gereksinimi olmadan aşağıdaki değişiklikleri yapabilirsiniz:

  • Alan koleksiyonuna yeni alanlar ekleyin.
  • Yeni alanlara atanan ancak zaten vektörleştirilmiş olan mevcut alanlara atanmamış yeni vektör yapılandırmaları ekleyin.
  • Var olan bir alandaki değeri değiştir (değerler doğru veya yanlış olabilir). Vektör alanları aranabilir ve alınabilir olmalıdır, ancak bırakma ve yeniden oluşturmanın mümkün olmadığı durumlarda vektör alanına erişimi devre dışı bırakmak istiyorsanız, alınabilir değerini false olarak ayarlayabilirsiniz.

Sonraki adımlar

Sonraki adım olarak Vektör sorgusu oluşturmanızı öneririz.

azure-search-vector-samples deposundaki kod örnekleri şema tanımı, vektörleştirme, dizin oluşturma ve sorgular içeren uçtan uca iş akışlarını gösterir.

Python, C# ve JavaScript için tanıtım kodu vardır.