Zenginleştirilmiş çıkışı Azure AI Search'teki arama dizinindeki alanlarla eşleme

Bu makalede, çıktı alanı eşlemelerinin nasıl ayarlanacağı, beceri kümesi işleme sırasında oluşturulan bellek içi veriler ile arama dizinindeki hedef alanlar arasında veri yolu tanımlama işlemleri açıklanmaktadır. Dizin oluşturucu yürütme sırasında, beceri tarafından oluşturulan bilgiler yalnızca bellekte bulunur. Bu bilgileri bir arama dizininde kalıcı hale getirmek için dizin oluşturucuya verilerin nereye gönderileceği bildirmelisiniz.

Çıkış alanı eşlemesi bir dizin oluşturucuda tanımlanır ve aşağıdaki öğelere sahiptir:

"outputFieldMappings": [
  {
    "sourceFieldName": "document/path-to-a-node-in-an-enriched-document",
    "targetFieldName": "some-search-field-in-an-index",
    "mappingFunction": null
  }
],

Ayrıntılı kaynak alanları ile fieldMappings dizin alanları arasındaki yolu eşleyen tanımın aksine, outputFieldMappings tanım bellek içi zenginleştirmeleri arama dizinindeki alanlarla eşler.

Önkoşullar

• Dizin oluşturucu, dizin, veri kaynağı ve beceri kümesi.

• Dizin alanları basit veya en üst düzey alanlar olmalıdır. Karmaşık bir türe çıkış yapamazsınız. Ancak, karmaşık bir türünüz varsa, karmaşık türün bölümlerini düzleştirmek ve bunları arama dizinindeki bir koleksiyona göndermek için bir çıkış alanı tanımı kullanabilirsiniz.

Çıkış alanı eşlemesi ne zaman kullanılır?

Dizin oluşturucunuz, dizininizde istediğiniz yeni bilgileri oluşturan ekli bir beceri kümesine sahipse çıkış alanı eşlemeleri gereklidir. Örnekler şunları içerir:

• Ekleme becerilerinden vektörler
• Görüntü becerilerinden optik karakter tanıma (OCR) metni
• Varlık tanıma becerilerinden konumlar, kuruluşlar veya kişiler

Çıkış alanı eşlemeleri şunları yapmak için de kullanılabilir:

• Oluşturulan içeriğinizin birden çok kopyasını oluşturun (bire çok çıkış alanı eşlemeleri).

• Kaynak belgenin karmaşık türünü düzleştirme. Örneğin, kaynak belgelerin çok parçalı adres gibi karmaşık bir türü olduğunu ve yalnızca şehri istediğinizi varsayalım. İç içe veri yapısını düzleştirmeye yönelik bir çıkış alanı eşlemesi kullanabilir ve ardından çıktıyı arama dizininizdeki bir dize koleksiyonuna göndermek için bir çıkış alanı eşlemesi kullanabilirsiniz.

Çıkış alanı eşlemeleri yalnızca arama dizinlerine uygulanır. Bilgi deposu dolduruyorsanız veri yolu yapılandırması için projeksiyonları kullanın.

Çıkış alanı eşlemesi tanımlama

Çıkış alanı eşlemeleri dizin oluşturucu tanımında diziye outputFieldMappings eklenir ve genellikle dizinin arkasına fieldMappings yerleştirilir. Çıkış alanı eşlemesi üç bölümden oluşur.

Çıktı alanı eşlemelerini tanımlamak için REST API veya Azure SDK'sını kullanabilirsiniz.

İpucu

Verileri içeri aktarma sihirbazı tarafından oluşturulan dizin oluşturucular, sihirbaz tarafından oluşturulan çıkış alanı eşlemelerini içerir. Örneklere ihtiyacınız varsa, dizin oluşturucuda çıkış alanı eşlemelerini görmek için sihirbazı veri kaynağınız üzerinden çalıştırın.

REST API'leri

1. Azure SDK'da Dizin Oluşturucu Oluştur veya Dizin Oluşturucu Oluştur veya Güncelleştir ya da eşdeğer bir yöntem kullanın. Aşağıda dizin oluşturucu tanımının bir örneği verilmiştir.

   {
      "name": "myindexer",
      "description": null,
      "dataSourceName": "mydatasource",
      "targetIndexName": "myindex",
      "schedule": { },
      "parameters": { },
      "fieldMappings": [],
      "outputFieldMappings": [],
      "disabled": false,
      "encryptionKey": { }
    }
   

2. Eşlemeleri outputFieldMappings belirtmek için diziyi doldurun. Alan eşlemesi üç bölümden oluşur.

   "outputFieldMappings": [
     {
       "sourceFieldName": "/document/path-to-a-node-in-an-enriched-document",
       "targetFieldName": "some-search-field-in-an-index",
       "mappingFunction": null
     }
   ]
   

   Özellik	Açıklama
   sourceFieldName	Gerekli. Zenginleştirilmiş içeriğin yolunu belirtir. Örnek olarak /document/content yer alabilir. Yol söz dizimi ve örnekler için bkz . Azure AI Search beceri kümesinde başvuru zenginleştirmeleri.
   targetFieldName	isteğe bağlı. Zenginleştirilmiş içeriği alan arama alanını belirtir. Hedef alanlar üst düzey basit alanlar veya koleksiyonlar olmalıdır. Karmaşık türde bir alt alan yolu olamaz. Karmaşık bir yapıda belirli düğümleri almak istiyorsanız, tek tek düğümleri bellekte düzleştirebilir ve ardından çıktıyı dizininizdeki bir dize koleksiyonuna gönderebilirsiniz.
   mappingFunction	isteğe bağlı. Dizin oluşturucular tarafından desteklenen eşleme işlevleri tarafından sağlanan ek işleme ekler. Zenginleştirme düğümleri için kodlama ve kod çözme en yaygın kullanılan işlevlerdir.

3. targetFieldName her zaman arama dizinindeki alanın adıdır.

4. sourceFieldName, zenginleştirilmiş belgedeki bir düğümün yoludur. Bu bir becerinin çıktısı. Yol her zaman /document ile başlar ve bir blobdan dizin oluştururken yolun ikinci öğesi /content olur. Üçüncü öğe, beceri tarafından üretilen değerdir. Daha fazla bilgi ve örnek için bkz . Azure AI Search beceri kümesinde zenginleştirmelere başvurma.

   Bu örnek, bir blob'un içerik özelliğinden ayıklanan varlıkları ve yaklaşım etiketlerini arama dizinindeki alanlara ekler.

   {
       "name": "myIndexer",
       "dataSourceName": "myDataSource",
       "targetIndexName": "myIndex",
       "skillsetName": "myFirstSkillSet",
       "fieldMappings": [],
       "outputFieldMappings": [
           {
               "sourceFieldName": "/document/content/organizations/*/description",
               "targetFieldName": "descriptions",
               "mappingFunction": {
                   "name": "base64Decode"
               }
           },
           {
               "sourceFieldName": "/document/content/organizations",
               "targetFieldName": "orgNames"
           },
           {
               "sourceFieldName": "/document/content/sentiment",
               "targetFieldName": "sentiment"
           }
       ]
   }
   

5. Bir alanın içeriğini dizinde depolanmadan önce dönüştürmek için gereken eşleme işlevlerini atayın. Zenginleştirme düğümleri için kodlama ve kod çözme en yaygın kullanılan işlevlerdir.

.NET SDK (C#)

.NET için Azure SDK'da, ve TargetFieldName özellikleri ve isteğe bağlı MappingFunction başvuru sağlayan Name OutputFieldMappingEntry sınıfını kullanın.

Dizin oluşturucuyu oluştururken çıkış alanı eşlemelerini belirtin veya doğrudan SearchIndexer.OutputFieldMappings'i ayarlayarak daha sonra belirtin. Aşağıdaki C# örneği, dizin oluşturucu oluşturulurken çıkış alanı eşlemelerini ayarlar.

string indexerName = "cog-search-demo";
SearchIndexer indexer = new SearchIndexer(
    indexerName,
    dataSourceConnectionName,
    indexName)
{
    // Field mappings omitted for this example (assume default mappings)
    OutputFieldMappings =
    {
        new FieldMapping("/document/content/organizations") { TargetFieldName = "orgNames" },
        new FieldMapping("/document/content/sentiment") { TargetFieldName = "sentiment" }
    },
    SkillsetName = skillsetName
};

await indexerClient.CreateIndexerAsync(indexer);

Bire çok çıkış alanı eşlemesi

Tek bir kaynak alanı arama dizinindeki birden çok alana yönlendirmek için çıkış alanı eşlemesi kullanabilirsiniz. Bunu karşılaştırma testi için veya farklı özniteliklere sahip alanlar istiyorsanız yapabilirsiniz.

Bir vektör alanı için eklemeler oluşturan bir beceri kümesinin ve algoritma ve sıkıştırma ayarlarına göre değişen birden çok vektör alanı olan bir dizinin olduğunu varsayalım. Dizin oluşturucunun içinde, ekleme becerisinin çıkışını arama dizinindeki birden çok vektör alanının her birine eşleyin.

"outputFieldMappings": [
    { "sourceFieldName" : "/document/content/text_vector", "targetFieldName" : "vector_hnsw" }, 
    { "sourceFieldName" : "/document/content/text_vector", "targetFieldName" : "vector_eknn" },
    { "sourceFieldName" : "/document/content/text_vector", "targetFieldName" : "vector_narrow" }, 
    { "sourceFieldName" : "/document/content/text_vector", "targetFieldName" : "vector_no_stored" },
    { "sourceFieldName" : "/document/content/text_vector", "targetFieldName" : "vector_scalar" }       
  ]

Kaynak alan yolu beceri çıkışıdır. Bu örnekte çıkış text_vector. Hedef adı isteğe bağlı bir özelliktir. Çıkış eşlemesine bir hedef ad vermezseniz, yol ekleme veya daha kesin olarak /document/content/embedding olur.

{
  "name": "test-vector-size-ss",  
  "description": "Generate embeddings using AOAI",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
      "name": "#1",
      "description": null,
      "context": "/document/content",
      "resourceUri": "https://my-demo-eastus.openai.azure.com",
      "apiKey": null,
      "deploymentId": "text-embedding-ada-002",
      "dimensions": 1536,
      "modelName": "text-embedding-ada-002",
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "embedding",
          "targetName": "text_vector"
        }
      ],
      "authIdentity": null
    }
  ]
}

Karmaşık yapıları dize koleksiyonuna düzleştirme

Kaynak verileriniz iç içe veya hiyerarşik JSON'lardan oluşuyorsa, veri yollarını ayarlamak için alan eşlemelerini kullanamazsınız. Bunun yerine, arama dizininizin tam içeri aktarma için her düzeyde için kaynak veri yapısını yansıtması gerekir.

Bu bölümde, karmaşık bir belgenin hem kaynak hem de hedef tarafında bire bir yansımasını oluşturan içeri aktarma işleminde size yol gösterilir. Ardından, tek tek düğümlerin dize koleksiyonlarına alınmasını ve düzleştirmesini göstermek için aynı kaynak belgeyi kullanır.

Azure Cosmos DB'de iç içe JSON içeren bir belge örneği aşağıda verilmiştir:

{
   "palette":"primary colors",
   "colors":[
      {
         "name":"blue",
         "medium":[
            "acrylic",
            "oil",
            "pastel"
         ]
      },
      {
         "name":"red",
         "medium":[
            "acrylic",
            "pastel",
            "watercolor"
         ]
      },
      {
         "name":"yellow",
         "medium":[
            "acrylic",
            "watercolor"
         ]
      }
   ]
}

Bu kaynak belgeyi tamamen dizine almak istiyorsanız alan adlarının, düzeylerinin ve türlerinin karmaşık bir tür olarak yansıtıldığı bir dizin tanımı oluşturursunuz. Alan eşlemeleri arama dizinindeki karmaşık türler için desteklenmediğinden, dizin tanımınızın kaynak belgeyi yansıtması gerekir.

{
  "name": "my-test-index",
  "defaultScoringProfile": "",
  "fields": [
    { "name": "id", "type": "Edm.String", "searchable": false, "retrievable": true, "key": true},
    { "name": "palette", "type": "Edm.String", "searchable": true, "retrievable": true },
    { "name": "colors", "type": "Collection(Edm.ComplexType)",
      "fields": [
        {
          "name": "name",
          "type": "Edm.String",
          "searchable": true,
          "retrievable": true
        },
        {
          "name": "medium",
          "type": "Collection(Edm.String)",
          "searchable": true,
          "retrievable": true,
        }
      ]
    }
  ]
}

aşağıda içeri aktarma işlemini yürüten örnek bir dizin oluşturucu tanımı verilmiştir. Hiçbir alan eşlemesi ve beceri kümesi olmadığına dikkat edin.

{
  "name": "my-test-indexer",
  "dataSourceName": "my-test-ds",
  "skillsetName": null,
  "targetIndexName": "my-test-index",

  "fieldMappings": [],
  "outputFieldMappings": []
}

Sonuç, Azure Cosmos DB'deki özgün arama belgesine benzer şekilde aşağıdaki örnek arama belgesidir.

{
  "value": [
    {
      "@search.score": 1,
      "id": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
      "palette": "primary colors",
      "colors": [
        {
          "name": "blue",
          "medium": [
            "acrylic",
            "oil",
            "pastel"
          ]
        },
        {
          "name": "red",
          "medium": [
            "acrylic",
            "pastel",
            "watercolor"
          ]
        },
        {
          "name": "yellow",
          "medium": [
            "acrylic",
            "watercolor"
          ]
        }
      ]
    }
  ]
}

Arama dizininde alternatif bir işleme, kaynağın iç içe yapısındaki tek tek düğümleri arama dizinindeki bir dize koleksiyonuna düzleştirmektir.

Bu görevi gerçekleştirmek için, bellek içi düğümü outputFieldMappings dizindeki bir dize koleksiyonuyla eşleyen bir gerekir. Çıkış alanı eşlemeleri öncelikli olarak beceri çıkışları için geçerli olsa da, dizin oluşturucunun bir kaynak belgeyi açtığı ve belleğe okuduğu belgeyi kırdıktan sonra düğümleri ele almak için de bunları kullanabilirsiniz.

Aşağıdaki örnek dizin tanımı düzleştirilmiş çıkış almak için dize koleksiyonlarını kullanır:

{
  "name": "my-new-flattened-index",
  "defaultScoringProfile": "",
  "fields": [
    { "name": "id", "type": "Edm.String", "searchable": false, "retrievable": true, "key": true },
    { "name": "palette", "type": "Edm.String", "searchable": true, "retrievable": true },
    { "name": "color_names", "type": "Collection(Edm.String)", "searchable": true, "retrievable": true },
    { "name": "color_mediums", "type": "Collection(Edm.String)", "searchable": true, "retrievable": true}
  ]
}

İç içe JSON'ı dize koleksiyonu alanlarıyla ilişkilendirmek için kullanılan outputFieldMappings örnek dizin oluşturucu tanımı aşağıda verilmiştir. Beceri kümesi olmasa bile kaynak alanın zenginleştirme düğümleri için yol söz dizimini kullandığına dikkat edin. Belgenin kırılması sırasında sistemde zenginleştirilmiş belgeler oluşturulur. Bu, belge kırıldığında söz konusu düğümler mevcut olduğu sürece her belge ağacındaki düğümlere erişebileceğiniz anlamına gelir.

{
  "name": "my-test-indexer",
  "dataSourceName": "my-test-ds",
  "skillsetName": null,
  "targetIndexName": "my-new-flattened-index",
  "parameters": {  },
  "fieldMappings": [   ],
  "outputFieldMappings": [
    {
       "sourceFieldName": "/document/colors/*/name",
       "targetFieldName": "color_names"
    },
    {
       "sourceFieldName": "/document/colors/*/medium",
       "targetFieldName": "color_mediums"
    }
  ]
}

Tanımın sonuçları aşağıdaki gibidir. Yapıyı basitleştirmek bu durumda bağlamı kaybeder. Artık belirli bir renkle içinde bulunduğu ortamlar arasında ilişki yoktur. Ancak senaryonuza bağlı olarak, aşağıdaki örneğe benzer bir sonuç tam olarak ihtiyacınız olan şey olabilir.

{
  "value": [
    {
      "@search.score": 1,
      "id": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
      "palette": "primary colors",
      "color_names": [
        "blue",
        "red",
        "yellow"
      ],
      "color_mediums": [
        "[\"acrylic\",\"oil\",\"pastel\"]",
        "[\"acrylic\",\"pastel\",\"watercolor\"]",
        "[\"acrylic\",\"watercolor\"]"
      ]
    }
  ]
}

İlgili içerik

• Alan eşlemeleri ve dönüştürmeleri
• Yapay zeka zenginleştirmeye genel bakış
• Beceri kümesi kavramları