Azure Yapay Zeka Arama’teki sorgular için Azure Cosmos DB for Apache Gremlin verilerini dizine ekleme (önizleme)

Uyarı

Bu özellik şu anda önizleme sürümündedir. Bu önizleme, hizmet düzeyi sözleşmesi olmadan sağlanır ve üretim iş yükleri için önerilmez. Bazı özellikler desteklenmeyebilir veya kısıtlı özelliklere sahip olabilir. Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri için Ek Kullanım Koşulları.

Önemli

Bu özellikler ve işlevler, diğer Microsoft hizmetleri ve üçüncü taraf hizmetlerle bağlantıları destekler. Bu hizmetlerin kullanımı ilgili koşullara tabidir ve Azure uyumluluk sınırının dışında veri işleme veya depolamanın yanı sıra Azure uyumluluk sınırına akan verilere neden olabilir.

Verilerinizin kuruluşunuzun uyumluluk ve coğrafi sınırları dışında akıp akmayacağını ve ilgili etkileri ve uygun izinlerin, sınırların ve onayların sağlanıp sağlanmayacağını yönetmek sizin sorumluluğunuzdadır.

Özel kullanım örnekleriniz bağlamında oluşturduğunuz uygulamaları dikkatle gözden geçirmek ve test etmek ve tüm uygun kararları ve özelleştirmeleri yapmak sizin sorumluluğunuzdadır. Bu, metapromptlar, içerik filtreleri veya diğer güvenlik sistemleri gibi sorumlu yapay zeka risk azaltmalarınızı uygulamayı ve uygulamalarınızın uygun kalite, güvenilirlik, güvenlik ve güvenilirlik standartlarını karşılamasını sağlamayı içerir. Daha fazla bilgi için bkz. Azure Yapay Zeka Arama Saydamlık Notu.

Bu makalede, Apache Gremlin için Azure Cosmos DB'den içerik aktaran ve Azure Yapay Zeka Arama'te aranabilir hale getiren bir dizinleyici yapılandırmayı öğrenin.

Bu makale, Cosmos DB'ye özgü bilgilerle dizin oluşturucu oluşturma makalesini tamamlar. Rest API'lerini kullanarak tüm dizin oluşturucular için ortak olan üç parçalı bir iş akışını gösterir: veri kaynağı oluşturma, dizin oluşturma, dizin oluşturucu oluşturma. Dizin Oluşturucu Oluştur isteğini gönderdiğinizde veri ayıklama gerçekleşir.

Terminoloji kafa karıştırıcı olabileceği için Azure Cosmos DB dizin oluşturma ve Azure Yapay Zeka Arama dizin oluşturma farklı işlemler olduğunu belirtmek gerekir. Azure Yapay Zeka Arama'de dizin oluşturma, arama hizmetinizde bir arama dizini oluşturur ve yükler.

Önkoşullar

  • Senaryo geri bildirimi sağlamak için önizlemeye kaydolun. Bu özelliğe form gönderildikten sonra otomatik olarak erişebilirsiniz.

  • Azure Cosmos DB hesabı, veritabanı, kapsayıcı ve öğeler. Daha düşük gecikme süresi için hem Azure Yapay Zeka Arama hem de Azure Cosmos DB için aynı bölgeyi kullanın ve bant genişliği ücretlerinden kaçının.

  • Azure Cosmos DB koleksiyonundaki otomatik dizin oluşturma ilkesiTutarlı olarak ayarlanır. Bu varsayılan yapılandırmadır. Gecikmeli dizin oluşturma önerilmez ve eksik verilere neden olabilir.

  • Okuma izinleri. "Tam erişim" bağlantı dizesi, içeriğe erişim sağlayan bir anahtar içerir, ancak Azure rolleri kullanıyorsanız, arama hizmeti yönetilen kimliği'nin Cosmos DB Hesap Okuyucu Rolü izinlerine sahip olduğundan emin olun.

  • Veri kaynağını, dizini ve dizin oluşturucuyu oluşturmak için bir REST istemcisi .

Veri kaynağını tanımlama

Veri kaynağı tanımı, verilerdeki değişiklikleri tanımlamak için dizine eklenecek verileri, kimlik bilgilerini ve ilkeleri belirtir. Veri kaynağı, birden çok dizin oluşturucu tarafından kullanılabilmesi için bağımsız bir kaynak olarak tanımlanır.

Bu çağrı için Azure Cosmos DB ile Apache Gremlin'e bağlanan bir veri kaynağı oluşturmak üzere bir preview REST API sürümü belirtin. 2021-04-01-preview veya daha yenisini kullanabilirsiniz. En son önizleme API'sini öneririz.

  1. Tanımını ayarlamak için bir veri kaynağı oluşturun veya güncelleştirin:

     POST https://[service name].search.windows.net/datasources?api-version=2026-05-01-preview
 Content-Type: application/json
 api-key: [Search service admin key]
 {
   "name": "[my-cosmosdb-gremlin-ds]",
   "type": "cosmosdb",
   "credentials": {
     "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=Gremlin;"
   },
   "container": {
     "name": "[cosmos-db-collection]",
     "query": "g.V()"
   },
   "dataChangeDetectionPolicy": {
     "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
     "highWaterMarkColumnName": "_ts"
   },
   "dataDeletionDetectionPolicy": null,
   "encryptionKey": null,
   "identity": null
 }
 }

  2. "type" değerini (gerekli) olarak "cosmosdb" ayarlayın.

  3. Kimlik bilgilerini bir bağlantı dizesi olarak ayarlayın. Sonraki bölümde desteklenen biçimler açıklanmaktadır.

  4. "kapsayıcıyı koleksiyona ayarlayın." "name" özelliği gereklidir ve grafiğin kimliğini belirtir.

    "query" özelliği isteğe bağlıdır. Apache Gremlin için Azure Cosmos DB için Azure Yapay Zeka Arama dizin oluşturucusu varsayılan olarak grafiğinizdeki her köşeyi dizindeki bir belge haline getirir. Kenarlar görmezden gelinir. Sorgu varsayılanıdır g.V(). Alternatif olarak, sorguyu yalnızca kenarları dizine almak için ayarlayabilirsiniz. Kenarları dizine almak için sorguyu olarak g.E()ayarlayın.

  5. Veriler geçiciyse ve dizin oluşturucunun sonraki çalıştırmalarda yalnızca yeni ve güncelleştirilmiş öğeleri almasını istiyorsanız "dataChangeDetectionPolicy" değerini ayarlayın. Artımlı ilerleme, yüksek su işareti sütunu olarak kullanılarak _ts varsayılan olarak etkinleştirilir.

  6. Kaynak öğe silindiğinde arama belgelerini bir arama dizininden kaldırmak istiyorsanız "dataDeletionDetectionPolicy" değerini ayarlayın.

Desteklenen kimlik bilgileri ve bağlantı dizeleri

Dizin oluşturucular aşağıdaki bağlantıları kullanarak bir koleksiyona bağlanabilir. Apache Gremlin için Azure Cosmos DB hedefleyen bağlantılarda, bağlantı dizesine "ApiKind" eklediğinizden emin olun.

Uç nokta URL'sinde bağlantı noktası numaralarından kaçının. Bağlantı noktası numarasını eklerseniz bağlantı başarısız olur.

Tam erişim bağlantı dizesi
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }
Sol bölmedeki Keys öğesini seçerek Azure portalındaki Azure Cosmos DB hesap sayfasından bağlantı dizesi alabilirsiniz. Yalnızca bir anahtar değil, tam bir bağlantı dizesi seçtiğinizden emin olun.
Yönetilen kimlik bağlantı dizesi
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }
Bu bağlantı dizesi hesap anahtarı gerektirmez, ancak daha önce yönetilen kimlik kullanarak bağlanmak için bir arama hizmeti yapılandırmış ve Cosmos DB Hesap Okuyucu Rolü izinleri veren bir rol ataması oluşturmuş olmanız gerekir. Daha fazla bilgi için bkz. Yönetilen kimlik kullanarak Azure Cosmos DB veritabanına dizin oluşturucu bağlantısı kurma.

Dizine arama alanları ekleme

Arama dizininde, kaynak JSON belgelerini veya özel sorgu projeksiyonunuzun çıkışını kabul etmek için alanlar ekleyin. Arama dizini şemasının grafiğinizle uyumlu olduğundan emin olun. Azure Cosmos DB içeriğindeki arama dizini şemanız, veri kaynağınızdaki Azure Cosmos DB öğeleri ile uyumlu olmalıdır.

  1. Verileri depolayacak arama alanlarını tanımlamak için bir dizin oluşturun veya güncelleştirin:

     POST https://[service name].search.windows.net/indexes?api-version=2026-05-01-preview
 Content-Type: application/json
 api-key: [Search service admin key]
 {
    "name": "mysearchindex",
    "fields": [
     {
         "name": "rid",
         "type": "Edm.String",
         "facetable": false,
         "filterable": false,
         "key": true,
         "retrievable": true,
         "searchable": true,
         "sortable": false,
         "analyzer": "standard.lucene",
         "indexAnalyzer": null,
         "searchAnalyzer": null,
         "synonymMaps": [],
         "fields": []
     },{
     }, {
         "name": "label",
         "type": "Edm.String",
         "searchable": true,
         "filterable": false,
         "retrievable": true,
         "sortable": false,
         "facetable": false,
         "key": false,
         "indexAnalyzer": null,
         "searchAnalyzer": null,
         "analyzer": "standard.lucene",
         "synonymMaps": []
    }]
  }

  2. Belge anahtar alan oluştur ("key": true). Bölümlenmiş koleksiyonlar için varsayılan belge anahtarı, Azure Cosmos DB _rid özelliğidir. Alan adları alt çizgi karakteriyle başlayamayacağından, Azure Yapay Zeka Arama bu özelliği otomatik olarak rid olarak yeniden adlandırır. Ayrıca, Azure Cosmos DB _rid değerleri Azure Yapay Zeka Arama anahtarlarda geçersiz karakterler içerir. Bu nedenle değerler _rid Base64 ile kodlanmıştır.

  3. Daha fazla aranabilir içerik için ek alanlar oluşturun. Ayrıntılar için bkz. Dizin oluşturma .

Veri türlerini eşleme

JSON veri türü Azure Yapay Zeka Arama alan türleri
Bool Edm.Boolean, Edm.String
Tamsayı gibi görünen sayılar Edm.Int32, Edm.Int64, Edm.String
Kayan noktalar gibi görünen sayılar Edm.Double, Edm.String
Dize Edm.String
["a", "b", "c"] gibi ilkel tür dizileri Collection(Edm.String)
Tarih gibi görünen dizeler Edm.DateTimeOffset, Edm.String
{ "type": "Point", "coordinates": [long, lat] } gibi GeoJSON nesneleri Edm.GeographyPoint
Diğer JSON nesneleri YOK

Azure Cosmos DB dizin oluşturucusunu yapılandırma ve çalıştırma

Dizin ve veri kaynağı oluşturulduktan sonra dizin oluşturucuyu oluşturmaya hazır olursunuz. Dizin oluşturucu yapılandırması, çalışma zamanı davranışlarını denetleen girişleri, parametreleri ve özellikleri belirtir.

  1. Dizin oluşturucuya bir ad verip veri kaynağına ve hedef dizine başvurarak dizin oluşturucu oluşturun veya güncelleştirin:

    POST https://[service name].search.windows.net/indexers?api-version=2026-05-01-preview
Content-Type: application/json
api-key: [search service admin key]
{
    "name" : "[my-cosmosdb-indexer]",
    "dataSourceName" : "[my-cosmosdb-gremlin-ds]",
    "targetIndexName" : "[my-search-index]",
    "disabled": null,
    "schedule": null,
    "parameters": {
        "batchSize": null,
        "maxFailedItems": 0,
        "maxFailedItemsPerBatch": 0,
        "base64EncodeKeys": false,
        "configuration": {}
        },
    "fieldMappings": [],
    "encryptionKey": null
}

  2. Alan adında veya türünde farklılıklar varsa veya arama dizininde bir kaynak alanın birden çok sürümüne ihtiyacınız varsa alan eşlemelerini belirtin.

  3. Diğer özellikler hakkında daha fazla bilgi için bkz. Dizin oluşturucu oluşturma .

Dizin oluşturucu oluşturulduğunda otomatik olarak çalışır. "disabled" ayarını true olarak ayarlayarak bunu önleyebilirsiniz. Dizin oluşturucu yürütmesini denetlemek için isteğe bağlı olarak bir dizin oluşturucu çalıştırın veya zamanlamaya yerleştirin.

Dizin oluşturucu durumunu kontrol etme

Dizin oluşturucu durumunu ve yürütme geçmişini izlemek için Dizin Oluşturucu Durumunu Al isteği gönderin:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2026-05-01-preview
  Content-Type: application/json  
  api-key: [admin key]

Yanıt, durumu ve işlenen öğe sayısını içerir. Aşağıdaki örneğe benzer görünmelidir:

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

Yürütme geçmişi, en son tamamlanan yürütmelerin en son 50'sini içerir ve en son yürütme önce gelecek şekilde ters kronolojik sırada sıralanır.

Yeni ve değiştirilmiş belgelerin dizinini oluşturma

Dizin oluşturucu bir arama dizinini tam olarak doldurduktan sonra, sonraki dizin oluşturucu çalıştırmalarının veritabanınızdaki yalnızca yeni ve değiştirilmiş belgeleri artımlı olarak dizinlemesini isteyebilirsiniz.

Artımlı dizin oluşturmayı etkinleştirmek için veri kaynağı tanımınızda "dataChangeDetectionPolicy" özelliğini ayarlayın. Bu özellik, dizin oluşturucuya verilerinizde hangi değişiklik izleme mekanizmasının kullanıldığını bildirir.

Azure Cosmos DB dizin oluşturucular için desteklenen tek ilke, Azure Cosmos DB tarafından sağlanan HighWaterMarkChangeDetectionPolicy (zaman damgası) özelliğini kullanan _ts ilkesidir.

Aşağıdaki örnekte, değişiklik algılama ilkesine sahip bir veri kaynağı tanımı gösterilmektedir:

"dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
"  highWaterMarkColumnName": "_ts"
},

Silinen belgelerin dizinini oluşturma

Grafik verileri silindiğinde, ilgili belgeyi arama dizininden de silmek isteyebilirsiniz. Veri silme algılama ilkesinin amacı, silinen veri öğelerini verimli bir şekilde tanımlamak ve belgenin tamamını dizinden silmektir. Veri silme algılama ilkesi, kısmi belge bilgilerini silmek için tasarlanmamıştır. Şu anda desteklenen tek ilke Soft Delete , veri kaynağı tanımında aşağıdaki gibi belirtilen ilkedir (silme işlemi bir tür bayrakla işaretlenir):

"dataDeletionDetectionPolicy"": {
    "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
    "softDeleteColumnName" : "the property that specifies whether a document was deleted",
    "softDeleteMarkerValue" : "the value that identifies a document as deleted"
}

Aşağıdaki örnek geçici silme ilkesine sahip bir veri kaynağı oluşturur:

POST https://[service name].search.windows.net/datasources?api-version=2026-05-01-preview
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "[my-cosmosdb-gremlin-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=Gremlin"
    },
    "container": { "name": "[my-cosmos-collection]" },
    "dataChangeDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "`_ts`"
    },
    "dataDeletionDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName": "isDeleted",
        "softDeleteMarkerValue": "true"
    }
}

Silme algılama ilkesini etkinleştirseniz bile, karmaşık (Edm.ComplexType) alanların dizinden silinmesi desteklenmez. Bu ilke, Gremlin veritabanındaki 'etkin' sütunun tamsayı, dize veya boole türünde olmasını gerektirir.

Grafik verilerini arama dizinindeki alanlarla eşleme

Apache Gremlin dizin oluşturucusunun Azure Cosmos DB birkaç grafik verisini otomatik olarak eşler:

  1. Dizin oluşturucu, dizinde mevcutsa _rid öğesini bir rid alanına eşleyecek ve Base64 ile kodlayacaktır.

  2. Dizin oluşturucu, varsa _id öğesini dizindeki bir id alanına eşler.

  3. Apache Gremlin için Azure Cosmos DB kullanarak Azure Cosmos DB veritabanınızı sorgularken, her özelliğin JSON çıkışında id ve value olduğunu fark edebilirsiniz. Dizinleyici, özellikleri value, arama dizininde mevcutsa, özellik ile aynı ada sahip bir alana otomatik olarak eşler. Aşağıdaki örnekte 450, arama dizinindeki bir pages alana eşlenir.

    {
        "id": "Cookbook",
        "label": "book",
        "type": "vertex",
        "properties": {
          "pages": [
            {
              "id": "48cf6285-a145-42c8-a0aa-d39079277b71",
              "value": "450"
            }
          ]
        }
    }

Sorgu çıkışınızı dizininizdeki alanlarla eşlemek için Çıkış Alanı Eşlemeleri'ni kullanmanız gerektiğini fark edebilirsiniz. Özel sorguda büyük olasılıkla karmaşık veriler olacağından Alan Eşlemeleri yerine Çıkış Alanı Eşlemeleri'ni kullanmak istersiniz.

Örneğin, sorgunuzun şu çıkışı ürettiğini düşünelim:

    [
      {
        "vertex": {
          "id": "Cookbook",
          "label": "book",
          "type": "vertex",
          "properties": {
            "pages": [
              {
                "id": "48cf6085-a211-42d8-a8ea-d38642987a71",
                "value": "450"
              }
            ],
          }
        },
        "written_by": [
          {
            "yearStarted": "2017"
          }
        ]
      }
    ]

Yukarıdaki JSON değerini dizininizdeki bir pages alanla eşlemek totalpages isterseniz, dizin oluşturucu tanımınıza aşağıdaki Çıkış Alanı Eşlemesi'ni ekleyebilirsiniz:

    ... // rest of indexer definition 
    "outputFieldMappings": [
        {
          "sourceFieldName": "/document/vertex/pages",
          "targetFieldName": "totalpages"
        }
    ]

Çıkış Alanı Eşlemesi'nin "/document" ile başladığını ve JSON'daki properties anahtarına bir referans içermediğini fark edin. Bunun nedeni, dizin oluşturucunun grafik verilerini alırken her belgeyi /document düğümünün altına yerleştirmesi ve ayrıca dizin oluşturucunun, pages dizisinin ilk nesnesine başvurmanız gerekmeden, basit bir şekilde pages kullanarak pages değerine otomatik olarak başvurmanıza olanak sağlamasıdır.

Sonraki adımlar

  • Apache Gremlin için Azure Cosmos DB hakkında daha fazla bilgi edinmek için Azure Cosmos DB'ye Giriş: Apache Gremlin için Azure Cosmos DB bölümüne bakın.

  • Azure Yapay Zeka Arama senaryoları ve fiyatlandırma hakkında daha fazla bilgi için azure.microsoft.com üzerindeki Arama hizmeti sayfasına bakın.

  • Ağ yapılandırması hakkında bilgi edinmek için, Azure ağ güvenlik özellikleriyle korunan içeriğe dizin oluşturucuların erişimi konusuna bakın.

  • Last updated on