Azure Yapay Zeka Arama'te REST kullanarak tümleşik vektörleştirme kurma

Bu makalede, desteklenen bir veri kaynağından içeriği öbekleyip vektörleştirmek için beceri kümesini kullanmayı öğreneceksiniz. Beceri kümesi öbekleme için Metin Bölme becerisini veya Belge Düzeni becerisini ve öbek vektörleştirmesi için desteklenen bir ekleme modeline eklenmiş bir ekleme becerisini çağırır. Ayrıca öbeklenmiş ve vektörleştirilmiş içeriği bir vektör dizininde depolamayı da öğrenirsiniz.

Bu makalede REST kullanarak tümleşik vektörleştirme için uçtan uca iş akışı açıklanmaktadır. Portal tabanlı yönergeler için bkz. Quickstart: Azure portalında metin ve görüntüleri vektörleştirme.

Önkoşullar

• Etkin aboneliği olan bir Azure hesabı. Ücretsiz bir hesap oluşturun.

• Azure Yapay Zeka Arama hizmeti. Temel katmanı veya üzerini öneririz.

• Desteklenen bir veri kaynağı.

• Desteklenen bir ekleme modeli.

• Hızlı Başlangıcın Tamamlanması: Anahtarlar olmadan bağlanma ve Sistem tarafından atanan yönetilen kimliği yapılandırma. Veri düzlemi işlemleri için anahtar tabanlı kimlik doğrulaması kullanabilseniz de, bu makalede rollerin ve yönetilen kimliklerin daha güvenli olduğu varsayılır.

• REST İstemci uzantısı ile Visual Studio Code.

Desteklenen veri kaynakları

Tümleşik vektörleştirme , desteklenen tüm veri kaynaklarıyla çalışır. Ancak, bu makale aşağıdaki tabloda açıklanan en yaygın kullanılan veri kaynaklarına odaklanır.

Veri kaynağı	Açıklama
Azure Blob Depolama	Bu veri kaynağı bloblar ve tablolarla çalışır. Standart performans (genel amaçlı v2) hesabı kullanmanız gerekir. Erişim katmanları sıcak, orta veya soğuk olabilir.
Azure Data Lake Storage (ADLS) Gen2	Bu, hiyerarşik ad alanı etkinleştirilmiş bir Azure Depolama hesabıdır. Data Lake Storage sahip olduğunuzu onaylamak için Overview sayfasındaki Properties sekmesini denetleyin.
Microsoft OneLake	Bu veri kaynağı OneLake dosyalarına ve kısayollarına bağlanır.

Desteklenen ekleme modelleri

Tümleşik vektörleştirme için aşağıdaki ekleme modellerinden birini kullanın. Dağıtım yönergeleri sonraki bir bölümde sağlanmıştır.

¹ Azure OpenAI kaynağınızın uç noktasının, özel bir alt etki alanı olan https://my-unique-name.openai.azure.com gibi, olması gerekir. Kaynağınızı Azure portalında oluşturduysanız, bu alt etki alanı kaynak kurulumu sırasında otomatik olarak oluşturulur.

^{Microsoft Foundry portalında} oluşturulan 2 Azure OpenAI kaynakları (ekleme modellerine erişimle) desteklenmez. Azure portalında bir Azure OpenAI kaynağı oluşturmanız gerekir.

3 Faturalama amacıyla Microsoft Foundry kaynağınızı Azure Yapay Zeka Arama beceri kümesine eklemelisiniz. Beceri kümesini oluşturmak için anahtarsız bağlantı kullanmadığınız sürece her iki kaynak da aynı bölgede olmalıdır.

⁴ Azure Vision çok modüllü ekleme modeli, seçin bölgeleri içinde kullanılabilir.

Rol tabanlı erişim

Microsoft Entra ID rol atamalarıyla veya tam erişim bağlantı dizeleriyle anahtar tabanlı kimlik doğrulamasıyla kullanabilirsiniz. Diğer kaynaklarla Azure Yapay Zeka Arama'in bağlantıları için rol atamalarını tavsiye ediyoruz.

Tümleşik vektörleştirme için rol tabanlı erişimi yapılandırmak için:

1. Arama hizmetinizde rolleri etkinleştirin ve sistem tarafından atanan yönetilen kimliği yapılandırın.

2. Veri kaynağı platformunuzda ve ekleme modeli sağlayıcınızda, arama hizmetinizin verilere ve modellere erişmesine olanak sağlayan rol atamaları oluşturun. Bkz . Verilerinizi hazırlama ve Ekleme modelinizi hazırlama.

Azure Yapay Zeka Arama için bağlantı bilgilerini alma

Bu bölümde, Azure Yapay Zeka Arama hizmetiniz için uç noktayı ve Microsoft Entra belirtecini alırsınız. REST isteklerinde bağlantı kurmak için her iki değer de gereklidir.

1. Azure portalında arama hizmetinize gidin.

2. Arama uç noktanızı almak için Genel Bakış sayfasındaki URL'yi kopyalayın. Örnek arama uç noktası: https://my-service.search.windows.net.

3. Microsoft Entra belirtecinizi almak için yerel sisteminizde aşağıdaki komutu çalıştırın. Bu adım , Hızlı Başlangıç: Anahtar olmadan bağlanma'nın tamamlanmasını gerektirir.

   az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
   

Verilerinizi hazırlama

Bu bölümde, desteklenen bir veri kaynağına dosya yükleyerek, roller atayarak ve bağlantı bilgilerini alarak verilerinizi tümleşik vektörleştirme için hazırlarsınız.

Ekleme modelinizi hazırlama

Bu bölümde roller atayarak, uç nokta edinerek ve supported embedding model dağıtarak Azure yapay zeka kaynağınızı tümleşik vektörleştirme için hazırlarsınız.

Değişkenleri ayarlama

Bu bölümde, Azure Yapay Zeka Arama hizmetiniz, desteklenen veri kaynağınız ve desteklenen gömme modeli bağlantı bilgilerini belirtirsiniz.

1. Visual Studio Code üzerinde, aşağıdaki yer tutucuları .rest veya .http dosyanıza yapıştırın.

   @baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
   @token = PUT-YOUR-MICROSOFT-ENTRA-TOKEN-HERE
   

2. @baseUrl öğesini arama uç noktası ve @token değerini Azure Yapay Zeka Arama için bağlantı bilgilerini al bölümünde elde ettiğiniz Microsoft Entra belirteci ile değiştirin.

3. Veri kaynağınıza bağlı olarak aşağıdaki değişkenleri ekleyin.

   Veri kaynağı	Değişken	Bu bilgileri girin
   Azure Blob Depolama	@storageConnectionString Ve @blobContainer	Verilerinizi Hazırlayın bölümünde oluşturduğunuz kapsayıcının bağlantı dizesi ve adı.
   ADLS Gen2	@storageConnectionString Ve @blobContainer	Verilerinizi Hazırlayın bölümünde oluşturduğunuz kapsayıcının bağlantı dizesi ve adı.
   OneLake	@workspaceId Ve @lakehouseId	Verilerinizi hazırlama bölümünde elde ettiğiniz çalışma alanı ve göl evi kimlikleri.

4. Ekleme modeli sağlayıcınıza bağlı olarak aşağıdaki değişkenleri ekleyin.

   Ekleme modeli sağlayıcısı	Değişken	Bu bilgileri girin
   Azure OpenAI	@aoaiEndpoint, @aoaiDeploymentName ve @aoaiModelName	Ekleme modelinizi hazırlama bölümünde elde ettiğiniz uç nokta, dağıtım adı ve model adı.
   Azure Vision	@AiFoundryEndpoint	Ekleme modelinizi hazırlama bölümünde edindiğiniz uç nokta.

5. Değişkenleri doğrulamak için aşağıdaki isteği gönderin.

   ### List existing indexes by name
   GET {{baseUrl}}/indexes?api-version=2026-04-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   

   Bir yanıt bitişik bir bölmede görünmelidir. Mevcut dizinleriniz varsa, bunlar listelenir. Aksi takdirde, liste boş olur. HTTP kodu ise 200 OKdevam etmeye hazırsınız demektir.

Verilerinize bağlanma

Bu bölümde, dizin oluşturucu tabanlı dizin oluşturma için desteklenen bir veri kaynağına bağlanacaksınız. Azure Yapay Zeka Arama'teki bir indexer, türü, kimlik bilgileri ve kapsayıcıyı belirten bir veri kaynağına ihtiyaç duyar.

1. Dizin oluşturma sırasında bağlantı bilgileri sağlayan bir veri kaynağı tanımlamak için Veri Kaynağı Oluştur'u kullanın.

   ### Create a data source
   POST {{baseUrl}}/datasources?api-version=2026-04-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-data-source",
       "type": "azureblob",
       "subtype": null,
       "credentials": {
           "connectionString": "{{storageConnectionString}}"
       },
       "container": {
           "name": "{{blobContainer}}",
           "query": null
       },
       "dataChangeDetectionPolicy": null,
       "dataDeletionDetectionPolicy": null
     }
   

2. Veri kaynağınıza ayarlayın type : azureblob veya adlsgen2.

3. Veri kaynağını oluşturmak için İstek gönder'i seçin.

4. OneLake kullanıyorsanız, credentials.connectionString öğesini ResourceId={{workspaceId}} olarak ve container.name öğesini {{lakehouseId}} olarak ayarlayın.

Beceri kümesi oluşturma

Bu bölümde, içeriğinizi bölümlere ayıran yerleşik bir beceriyi çağıran bir beceri kümesi ve bu bölümler için vektör temsilleri oluşturmak amacıyla bir gömme becerisi oluşturacaksınız. Beceri kümesi sonraki bir bölümde dizin oluşturma sırasında yürütülür.

İçeriğinizi öbeklemek için yerleşik bir beceri çağırma

İçeriğinizi öbekler halinde bölümleme, ekleme modelinizin gereksinimlerini karşılamanıza yardımcı olur ve kesme nedeniyle veri kaybını önler. Öbekleme hakkında daha fazla bilgi almak için Vektör arama çözümleri için büyük belgeleri öbekleme belgesine bakın.

Yerleşik veri parçalama için Azure Yapay Zeka Arama, Text Split becerisini ve Azure Content Understanding becerisini sunar. Metin Bölme becerisi metni cümlelere veya belirli bir uzunluktaki sayfalara bölerken, Azure Content Understanding becerisi paragraf sınırlarına uyan anlamsal, düzeni dikkate alan parçalara ayırma işlemi gerçekleştirir.

1. Beceri kümesi tanımlamak için Beceri Kümesi Oluştur'u kullanın.

   ### Create a skillset
   POST {{baseUrl}}/skillsets?api-version=2026-04-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-skillset",
       "skills": []
     }
   

2. skills dizisinde Metin Bölme becerisini veya Azure Content Understanding becerisini çağırın. Aşağıdaki tanımlardan birini yapıştırabilirsiniz.

       "skills": [
        {
          "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
          "name": "my-text-split-skill",
          "textSplitMode": "pages",
          "maximumPageLength": 2000,
          "pageOverlapLength": 500,
          "maximumPagesToTake": 0,
          "unit": "characters",
          "defaultLanguageCode": "en",
          "inputs": [
           {
             "name": "text",
             "source": "/document/text",
             "inputs": []
           }
          ],
          "outputs": [
           {
             "name": "textItems"
           }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Util.ContentUnderstandingSkill",
          "name": "my-content-understanding-skill",
          "context": "/document",
          "chunkingProperties": {
            "method": "semantic",
            "unit": "tokens",
            "maximumLength": 500
          },
          "inputs": [
           {
             "name": "file_data",
             "source": "/document/file_data"
           }
          ],
          "outputs": [
           {
             "name": "text_sections",
             "targetName": "text_sections"
           }
          ]
        }
       ]
   

Parçaları vektörleştirmek için gömme becerisini çağırın

Öbeklenmiş içeriğinizi vektörleştirmek için beceri kümesinin desteklenen bir ekleme modeline işaret eden bir ekleme becerisine ihtiyacı vardır.

1. skills dizisindeki yerleşik parçalama becerisinden sonra Azure OpenAI Gömme becerisini veya Azure Vision çok modlu gömme becerisini (önizleme) çağırın. Aşağıdaki tanımlardan birini yapıştırabilirsiniz.

        {
          "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
          "resourceUri": "{{aoaiEndpoint}}",
          "deploymentId": "{{aoaiDeploymentName}}",
          "modelName": "{{aoaiModelName}}",
          "dimensions": 1536,
          "inputs": [
            {
              "name": "text",
              "source": "/document/text"
            }
          ],
          "outputs": [
            {
              "name": "embedding"
            }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Vision.VectorizeSkill",
          "context": "/document",
          "modelVersion": "2023-04-15",
          "inputs": [
            {
              "name": "url",
              "source": "/document/metadata_storage_path"
            },
            {
              "name": "queryString",
              "source": "/document/metadata_storage_sas_token"
            }
          ],
          "outputs": [
            {
              "name": "vector"
            }
          ]
        }
   

   Not

   Azure Vision çok modüllü ekleme becerisi önizleme aşamasındadır. Bu beceriyi çağırmak istiyorsanız en son önizleme API'sini kullanın.

2. Azure OpenAI Ekleme becerisini kullanıyorsanız değerini ekleme modeliniz tarafından oluşturulan sayısına ayarlayın.

3. Azure Vision çok modüllü eklemeler becerisini kullanıyorsanız Microsoft Foundry kaynağınızıskills dizininden sonra ekleyin. Bu ek faturalama amaçlıdır.

       "skills": [ ... ],
       "cognitiveServices": {
         "@odata.type": "#Microsoft.Azure.Search.AIServicesByIdentity",
         "subdomainUrl": "{{AiFoundryEndpoint}}"
        }
   

4. Beceri kümesini oluşturmak için İstek gönder'i seçin.

Vektör dizini oluşturma

Bu bölümde, vector dizini oluşturarak Azure Yapay Zeka Arama hizmetinizde fiziksel veri yapıları ayarlarsınız. Vektör dizini şeması aşağıdakileri gerektirir:

• Adı
• Anahtar alanı (dize)
• Bir veya daha fazla vektör alanı
• Vektör yapılandırması

Vektör alanları öbeklenmiş verilerinizin sayısal gösterimlerini depolar. Aranabilir ve alınabilir olmaları gerekir, ancak filtrelenebilir, modellenebilir veya sıralanabilir olamazlar. Ayrıca çözümleyiciler, normalleştiriciler veya eş anlamlı eşleme atamaları da olamaz.

Vektör alanlarına ek olarak, aşağıdaki adımlarda yer alan örnek dizin, insan tarafından okunabilen içerikler için görsel olmayan alanlar içerir. Vektörleştirmek istediğiniz içeriğin düz metin eşdeğerlerini eklemek yaygın bir durum. Daha fazla bilgi için bkz. Vektör dizini oluşturma.

1. Vektör dizininin şemasını tanımlamak için Dizin Oluştur'u kullanın.

   ### Create a vector index
   POST {{baseUrl}}/indexes?api-version=2026-04-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-vector-index",
       "fields": [],
       "vectorSearch": []
     }
   

2. Bölümüne bir vektör arama yapılandırmasıvectorSearch ekleyin.

       "vectorSearch": {
         "algorithms": [
           {
             "name": "hnsw-algorithm",
             "kind": "hnsw",
             "hnswParameters": {
               "m": 4,
               "efConstruction": 400,
               "efSearch": 100,
               "metric": "cosine"
             }
           }
         ],
         "profiles": [
           {
             "name": "vector-profile-hnsw",
             "algorithm": "hnsw-algorithm",
           }
         ]
       }
   

   vectorSearch.algorithms , vektör alanlarını dizine almak ve sorgulamak için kullanılan algoritmayı belirtirken vectorSearch.profiles , algoritma yapılandırmasını vektör alanlarına atayabileceğiniz bir profile bağlar.

3. Gömme modelinize bağlı olarak vectorSearch.algorithms.metric güncelleyin. Uzaklık ölçümleri için geçerli değerler : cosine, dotproduct, euclideanve hamming.

4. Dizilere fields alanlar ekleyin. Belge tanımlama için anahtar bir alan ve insan tarafından okunabilir içerik için vektör olmayan alanlar ile gömüler için vektör alanları ekleyin.

       "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": false,
            "stored": true,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-hnsw"
         },
         {
           "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-hnsw"
         }
       ]
   

5. Ekleme becerinize bağlı olarak, her vektör alanı için aşağıdaki değere ayarlayın dimensions .

   Ekleme becerisi	Bu değeri girin
   Azure OpenAI	Ekleme modeliniz tarafından oluşturulan ekleme sayısı.
   Azure Vision	1024

Dizine vektörleştirici ekleme

Bu bölümde, dizininizde bir vektörleştirici tanımlayarak sorgu zamanında vektörleştirmeyi etkinleştirebilirsiniz. Vektörleştirici, verilerinizi dizine ekleyen gömme modeli kullanarak bir arama dizesini veya görüntüyü vektör araması için bir vektöre dönüştürür.

1. Azure OpenAI vektörleştiricisini veya Azure Görüntü vektörleştiricisini (önizleme) sonra vectorSearch.profilesekleyin. Aşağıdaki tanımlardan birini yapıştırabilirsiniz.

         "profiles": [ ... ],
         "vectorizers": [
           {
             "name": "my-openai-vectorizer",
             "kind": "azureOpenAI",
             "azureOpenAIParameters": {
               "resourceUri": "{{aoaiEndpoint}}",
               "deploymentId": "{{aoaiDeploymentName}}",
               "modelName": "{{aoaiModelName}}"
             }
           },
           {
             "name": "my-ai-services-vision-vectorizer",
             "kind": "aiServicesVision",
             "aiServicesVisionParameters": {
               "resourceUri": "{{AiFoundryEndpoint}}",
               "modelVersion": "2023-04-15"
             }
           }
         ]
   

   Not

   Azure Görüntü İşleme vektörleştiricisi önizleme aşamasındadır. Bu vektörleştiriciyi çağırmak istiyorsanız en son önizleme API sürümünü kullanın.

2. içinde vectorSearch.profilesvektörleştiricinizi belirtin.

         "profiles": [
           {
             "name": "vector-profile-hnsw",
             "algorithm": "hnsw-algorithm",
             "vectorizer": "my-openai-vectorizer"
           }
         ]
   

3. Vektör dizinini oluşturmak için İstek gönder'i seçin.

Dizin oluşturucu oluşturma

Bu bölümde, veri alımından beceri kümesi yürütmeye ve dizin oluşturmaya kadar vektörleştirme işlem hattının tamamını yönlendirmek için bir dizin oluşturucu oluşturacaksınız. Azaltma nedeniyle kaçırılan değişiklikleri veya belgeleri işlemek için dizin oluşturucuyu bir zamanlamaya göre çalıştırmanızı öneririz.

1. Vektörleştirme işlem hattını yürüten bir dizin oluşturucu tanımlamak için Dizin Oluşturucu Oluştur'u kullanın.

   ### Create an indexer
   POST {{baseUrl}}/indexers?api-version=2026-04-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-indexer",
       "dataSourceName": "my-data-source",
       "targetIndexName": "my-vector-index",
       "skillsetName": "my-skillset",
       "schedule": {
         "interval": "PT2H"
       },
       "parameters": {
         "batchSize": null,
         "maxFailedItems": null,
         "maxFailedItemsPerBatch": null
       }
     }
   

2. Dizin oluşturucuyu oluşturmak için İstek gönder'i seçin.

Dizin oluşturmayı onaylamak için vektör sorgusu çalıştırma

Bu bölümde, bir vektör sorgusu oluşturarak içeriğinizin başarıyla dizine alındığı doğrulanır. Önceki bir bölümde vektörleştirici yapılandırdığınız için, arama altyapısı düz metnin veya görüntünün kodunu sorgu yürütme için bir vektöre dönüştürebilir.

1. Sorgu zamanında vektörleştirilmiş bir sorgu tanımlamak için Belgeler - Arama Gönderisi'ni kullanın.

   ### Run a vector query
   POST {{baseUrl}}/indexes('my-vector-index')/docs/search.post.search?api-version=2026-04-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "count": true,
       "select": "title, content",
       "vectorQueries": [
           {
             "kind": "text",
             "text": "a sample text string for integrated vectorization",
             "fields": "titleVector, contentVector",
             "k": "3"
           }
       ]
     }
   

   Not

   Azure Görüntü İşleme vektörleştiricisi önizleme aşamasındadır. Bu vektörleştiriciyi çağırmak istiyorsanız en son önizleme API sürümünü kullanın.

   Tümleşik vektörleştirmeyi çağıran sorgular için kindolarak text ayarlanmalıdır ve text bir metin dizesi belirtmelidir. Bu dize, vektör alanına atanan vektörleştiriciye geçirilir. Daha fazla bilgi için bkz. Tümleşik vektörleştirme ile sorgulama.

2. Vektör sorgusunu çalıştırmak için İstek gönder'i seçin.

İlgili içerik

• Azure Yapay Zeka Arama'te tümleşik vektör yerleştirme
• Hızlı Başlangıç: Azure portalında vektör araması
• Tümleşik vektörleştirme için Python örneği