Bilgi deposunda projeksiyonları tanımlama

Makale
09/01/2024

Projeksiyonlar , yapay zekayla zenginleştirilmiş içeriğin Azure Depolama'da nerede depolandığını belirleyen bilgi deposu tanımının bileşenidir. Projeksiyonlar, içeriğinizi içeren veri yapılarının türünü, miktarını ve bileşimini belirler.

Bu makalede, her projeksiyon türü için söz dizimini öğrenin:

Tablo projeksiyonları
Nesne projeksiyonları
Dosya projeksiyonları

Projeksiyonların bir beceri kümesinin "knowledgeStore" özelliği altında tanımlandığını hatırlayın.

"knowledgeStore" : {
    "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
    "projections": [
      {
        "tables": [ ],
        "objects": [ ],
        "files": [ ]
      }
    ]
}

Başlamadan önce daha fazla arka plana ihtiyacınız varsa ipuçları ve iş akışı için bu denetim listesini gözden geçirin.

İpucu

Projeksiyonlar geliştirirken, projeksiyon tanımlarını düzenlerken var olan zenginleştirmeleri yeniden kullanabilmeniz için zenginleştirme önbelleğini (önizleme) etkinleştirin. Zenginleştirme önbelleği bir önizleme özelliğidir, bu nedenle dizin oluşturucu isteğinde önizleme REST API'sini kullandığınızdan emin olun. Önbelleğe alma olmadan, projeksiyonda yapılan basit düzenlemeler zenginleştirilmiş içeriğin tam olarak yeniden işlenmesine neden olur. Zenginleştirmeleri önbelleğe alarak, herhangi bir beceri kümesi işleme ücreti ödemeden projeksiyonları yineleyebilirsiniz.

Gereksinimler

Tüm projeksiyonlar kaynak ve hedef özelliklere sahiptir. Kaynak her zaman beceri kümesi yürütmesi sırasında oluşturulan bir zenginleştirme ağacından iç içeriktir. Hedef, Azure Depolama'da oluşturulan ve doldurulan bir dış nesnenin adı ve türüdür.

Yalnızca ikili görüntüleri kabul eden dosya projeksiyonları dışında kaynak şu şekilde olmalıdır:

Geçerli JSON
Zenginleştirme ağacındaki bir düğümün yolu (örneğin, "source": "/document/objectprojection")

Bir düğüm tek bir alana çözümlenebilirken, daha yaygın bir gösterim karmaşık bir şekle başvurudur. Karmaşık şekiller, Şekillendirici becerisi veya satır içi şekillendirme tanımı olmak üzere bir şekillendirme metodolojisi aracılığıyla oluşturulur, ancak genellikle bir Şekillendirici becerisidir. Şeklin alanları veya öğeleri, kapsayıcılardaki ve tablolardaki alanları belirler.

Şekillendirici becerileri, çoğu becerinin geçerli JSON'ı kendi başına çıkış yapmadığı JSON'un çıkışını yaptığı için tercih edilir. Çoğu durumda, bir Shaper becerisi tarafından oluşturulan aynı veri şekli hem tablo hem de nesne projeksiyonları tarafından eşit olarak kullanılabilir.

Verili kaynak giriş gereksinimleri, özellikle tablolarla çalışıyorsanız, verilerin nasıl şekillendirileceğini bilmek projeksiyon tanımı için pratik bir gereksinim haline gelir.

Tablo projeksiyonu tanımlama

Tablo projeksiyonları, Power BI ile analiz veya veri çerçeveleri kullanan iş yükleri gibi veri keşfi çağrısında bulunan senaryolar için önerilir. Projeksiyonlar dizisinin tablolar bölümü, yansıtmak istediğiniz tabloların listesidir.

Tablo projeksiyonunu tanımlamak için projeksiyonlar özelliğindeki diziyi kullanın tables . Tablo projeksiyonu üç gerekli özelliğe sahiptir:

Özellik	Açıklama
tableName	Azure Tablo Depolama'da oluşturulan yeni tablonun adını belirler.
generatedKeyName	Her satırı benzersiz olarak tanımlayan anahtarın sütun adı. Değer sistem tarafından oluşturulur. Bu özelliği atlarsanız, adlandırma kuralı olarak tablo adını ve "key" değerini kullanan bir sütun otomatik olarak oluşturulur.
kaynak	Zenginleştirme ağacındaki bir düğümün yolu. Düğüm, tabloda hangi sütunların oluşturulduğunu belirleyen karmaşık bir şekle başvuru olmalıdır.

Tablo projeksiyonlarında "kaynak", genellikle tablonun şeklini tanımlayan bir Shaper becerisinin çıkışıdır. Tabloların satırları ve sütunları vardır ve şekillendirme, satırların ve sütunların belirtildiği mekanizmadır. Bir Şekillendirici becerisi veya satır içi şekiller kullanabilirsiniz. Shaper becerisi geçerli JSON üretir, ancak kaynak geçerli JSON ise herhangi bir becerinin çıktısı olabilir.

Not

Tablo projeksiyonları, Azure Depolama tarafından uygulanan depolama sınırlarına tabidir. Varlık boyutu 1 MB'ı aşamaz ve tek bir özellik 64 KB'tan büyük olamaz. Bu kısıtlamalar tabloları çok sayıda küçük varlığı depolamak için iyi bir çözüm haline getirir.

Tek tablo örneği

Bir tablonun şeması kısmen projeksiyon (tablo adı ve anahtarı) ve ayrıca tablo şeklini (sütunlar) sağlayan kaynak tarafından belirtilir. Bu örnekte tanımın ayrıntılarına odaklanabilmeniz için yalnızca bir tablo gösterilmektedir.

"projections" : [
  {
    "tables": [
      { "tableName": "Hotels", "generatedKeyName": "HotelId", "source": "/document/tableprojection" }
    ]
  }
]

Sütunlar "kaynaktan" türetilir. HotelId, HotelName, Category ve Description içeren aşağıdaki veri şekli tabloda bu sütunların oluşturulmasına neden olur.

{
    "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
    "name": "#3",
    "description": null,
    "context": "/document",
    "inputs": [
    {
        "name": "HotelId",
        "source": "/document/HotelId"
    },
    {
        "name": "HotelName",
        "source": "/document/HotelName"
    },
    {
        "name": "Category",
        "source": "/document/Category"
    },
    {
        "name": "Description",
        "source": "/document/Description"
    },
    ],
    "outputs": [
    {
        "name": "output",
        "targetName": "tableprojection"
    }
    ]
}

Birden çok tablo (dilimleme) örneği

Tablo projeksiyonları için yaygın bir desen, sistem tarafından oluşturulan partitionKey ve rowKey sütunlarının aynı projeksiyon grubu altındaki tüm tablolar için tablolar arası ilişkileri desteklemek üzere oluşturulduğu birden çok ilişkili tabloya sahip olmaktır.

birden çok tablo oluşturmak, ilgili verilerin nasıl toplanıp toplanmayacağı üzerinde denetim sahibi olmak istiyorsanız yararlı olabilir. Zenginleştirilmiş içerik ilişkisiz veya bağımsız bileşenlere sahipse ( örneğin, bir belgeden ayıklanan anahtar sözcükler aynı belgede tanınan varlıklardan ilgisiz olabilir) bu alanları bitişik tablolara bölebilirsiniz.

Birden çok tabloya yansıttığınızda, alt düğüm aynı gruptaki başka bir tablonun kaynağı olmadığı sürece, şeklin tamamı her tabloya yansıtılır. Var olan bir projeksiyonun alt öğesi olan bir kaynak yola projeksiyon eklemek, alt düğümün üst düğümden dilimlenip yeni ancak ilişkili tabloya yansıtılmasıyla sonuçlanır. Bu teknik, bir Shaper becerisinde tüm projeksiyonlarınızın kaynağı olabilecek tek bir düğüm tanımlamanızı sağlar.

Birden çok tablo için desen şunlardan oluşur:

Üst tablo veya ana tablo olarak bir tablo
Zenginleştirilmiş içeriğin dilimlerini içeren ek tablolar

Örneğin, bir Shaper becerisinin otel bilgilerini ve anahtar ifadeler, konumlar ve kuruluşlar gibi zenginleştirilmiş içeriği içeren bir "Zenginleştirilmiş Şekil" oluşturduğunu varsayalım. Ana tabloda oteli açıklayan alanlar (kimlik, ad, açıklama, adres, kategori) yer alır. Anahtar ifadeler anahtar tümcecik sütununu alır. Varlıklar varlık sütunlarını alır.

"projections" : [
  {
    "tables": [
    { "tableName": "MainTable", "generatedKeyName": "HotelId", "source": "/document/EnrichedShape" },
    { "tableName": "KeyPhrases", "generatedKeyName": "KeyPhraseId", "source": "/document/EnrichedShape/*/KeyPhrases/*" },
    { "tableName": "Entities", "generatedKeyName": "EntityId", "source": "/document/EnrichedShape/*/Entities/*" }
    ]
  }
]

İlişkileri adlandırma

generatedKeyName ve referenceKeyName özellikleri, verileri tablolar arasında ve hatta projeksiyon türleri arasında ilişkilendirmek için kullanılır. Alt tablodaki her satırın üst öğeyi işaret eden bir özelliği vardır. Alt öğedeki sütunun veya özelliğin adı üst öğeden gelen addır referenceKeyName . referenceKeyName sağlanmayan hizmet varsayılan olarak generatedKeyName üst öğeden öğesini seçer.

Power BI, tablolardaki ilişkileri bulmak için bu oluşturulan anahtarlara dayanır. Alt tabloda farklı adlı bir sütuna ihtiyacınız varsa, üst tabloda özelliğini ayarlayın referenceKeyName . Bunun bir örneği, tblDocument tablosunda kimlik olarak ve referenceKeyName DocumentID olarak ayarlamaktırgeneratedKeyName. Bu, tblEntities ve tblKeyPhrases tablolarında belge kimliğini içeren sütunun DocumentID olarak adlandırılmasıyla sonuçlanır.

Nesne projeksiyonu tanımlama

Nesne projeksiyonları, herhangi bir düğümden kaynaklanabilen zenginleştirme ağacının JSON gösterimleridir. Tablo projeksiyonlarına kıyasla nesne projeksiyonlarının tanımlanması daha kolaydır ve tüm belgeler yansıtılırken kullanılır. Nesne projeksiyonları kapsayıcıdaki tek bir projeksiyonla sınırlıdır ve dilimlenemez.

Bir nesne projeksiyonu tanımlamak için projeksiyonlar özelliğindeki diziyi kullanın objects . Nesne projeksiyonu üç gerekli özelliğe sahiptir:

Özellik	Açıklama
storageContainer	Azure Depolama'da oluşturulan yeni kapsayıcının adını belirler.
generatedKeyName	Her satırı benzersiz olarak tanımlayan anahtarın sütun adı. Değer sistem tarafından oluşturulur. Bu özelliği atlarsanız, adlandırma kuralı olarak tablo adını ve "key" değerini kullanan bir sütun otomatik olarak oluşturulur.
kaynak	Projeksiyonun kökü olan zenginleştirme ağacındaki bir düğümün yolu. Düğüm genellikle blob yapısını belirleyen karmaşık bir veri şekline başvurudur.

Aşağıdaki örnek, blob başına bir otel belgesi olan tek tek otel belgelerini adlı hotelsbir kapsayıcıya projeler.

"knowledgeStore": {
  "storageConnectionString": "an Azure storage connection string",
  "projections" : [
    {
      "tables": [ ]
    },
    {
      "objects": [
        {
        "storageContainer": "hotels",
        "source": "/document/objectprojection",
        }
      ]
    },
    {
        "files": [ ]
    }
  ]
}

Kaynak, adlı "objectprojection"bir Shaper becerisinin çıktısıdır. Her blob, her alan girişinin bir JSON gösterimine sahip olur.

    {
      "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
      "name": "#3",
      "description": null,
      "context": "/document",
      "inputs": [
        {
          "name": "HotelId",
          "source": "/document/HotelId"
        },
        {
          "name": "HotelName",
          "source": "/document/HotelName"
        },
        {
          "name": "Category",
          "source": "/document/Category"
        },
        {
          "name": "keyPhrases",
          "source": "/document/HotelId/keyphrases/*"
        },
      ],
      "outputs": [
        {
          "name": "output",
          "targetName": "objectprojection"
        }
      ]
    }

Dosya projeksiyonu tanımlama

Dosya projeksiyonları her zaman ikili, normalleştirilmiş görüntülerdir; burada normalleştirme beceri kümesi yürütmesinde kullanılmak üzere olası yeniden boyutlandırma ve döndürme anlamına gelir. Nesne projeksiyonlarına benzer şekilde dosya projeksiyonları, Azure Depolama'da blob olarak oluşturulur ve ikili veriler içerir (JSON'un aksine).

Bir dosya projeksiyonu tanımlamak için projeksiyonlar özelliğindeki diziyi kullanın files . Dosya projeksiyonunun üç gerekli özelliği vardır:

Özellik	Açıklama
storageContainer	Azure Depolama'da oluşturulan yeni kapsayıcının adını belirler.
generatedKeyName	Her satırı benzersiz olarak tanımlayan anahtarın sütun adı. Değer sistem tarafından oluşturulur. Bu özelliği atlarsanız, adlandırma kuralı olarak tablo adını ve "key" değerini kullanan bir sütun otomatik olarak oluşturulur.
kaynak	Projeksiyonun kökü olan zenginleştirme ağacındaki bir düğümün yolu. Görüntü dosyaları için kaynak her zaman `/document/normalized_images/*`şeklindedir. Dosya projeksiyonları yalnızca koleksiyon üzerinde `normalized_images` işlem gösterir. Dizin oluşturucular veya beceri kümesi özgün normalleştirilmemiş görüntüden geçmez.

Hedef her zaman belge kimliğinin base64 kodlanmış değerinin klasör ön ekine sahip bir blob kapsayıcıdır. Birden çok resim varsa, bunlar aynı klasöre yerleştirilir. Dosya projeksiyonları, nesne projeksiyonlarıyla aynı kapsayıcıyı paylaşamaz ve farklı bir kapsayıcıya yansıtılması gerekir.

Aşağıdaki örnek, zenginleştirilmiş bir belgenin belge düğümünden ayıklanan tüm normalleştirilmiş görüntüleri adlı myImagesbir kapsayıcıya projeler.

"projections": [
    {
        "tables": [ ],
        "objects": [ ],
        "files": [
            {
                "storageContainer": "myImages",
                "source": "/document/normalized_images/*"
            }
        ]
    }
]

Test projeksiyonları

Aşağıdaki adımları izleyerek projeksiyonları işleyebilirsiniz:

Bilgi deposunun storageConnectionString özelliğini geçerli bir V2 genel amaçlı depolama hesabı bağlantı dizesi olarak ayarlayın.
Beceri kümesinin gövdesinde projeksiyon tanımınızla bir PUT isteği vererek beceri kümesini güncelleştirin.
Beceri kümesini yürütmeye yerleştirmek için dizin oluşturucuyu çalıştırın.
İlerleme durumunu denetlemek ve hataları yakalamak için dizin oluşturucu yürütmesini izleyin.
Azure Depolama'da nesne oluşturmayı doğrulamak için Azure portalını kullanın.
Tabloları yansıtıyorsanız, tablo işleme ve görselleştirme için bunları Power BI'a aktarın. Çoğu durumda Power BI tablolar arasındaki ilişkileri otomatik olarak bulur.

Genel sorunlar

Aşağıdaki adımlardan herhangi birinin atlanması beklenmeyen sonuçlara neden olabilir. Çıkışınız doğru görünmüyorsa aşağıdaki koşulları denetleyin.

Dize zenginleştirmeleri geçerli JSON şeklinde değildir. Dizeler zenginleştirildiğinde, örneğin merged_content anahtar ifadelerle zenginleştirildiğinde, zenginleştirilmiş özellik zenginleştirme ağacı içinde öğesinin merged_content alt öğesi olarak temsil edilir. Varsayılan gösterim iyi biçimlendirilmiş JSON değildir. Yansıtma zamanında zenginleştirmeyi bir ad ve değer içeren geçerli bir JSON nesnesine dönüştürdüğünüzden emin olun. Bir Şekillendirici becerisi kullanmak veya satır içi şekiller tanımlamak bu sorunun çözülmesine yardımcı olur.
Kaynak yolun sonundaki değerinin atlanırsa /* . Projeksiyonun kaynağı ise /document/projectionShape/keyPhrases, anahtar ifadeler dizisi tek bir nesne/satır olarak yansıtılır. Bunun yerine, anahtar tümceciklerin her biri için tek bir satır veya nesne vermek üzere kaynak yolu /document/projectionShape/keyPhrases/* olarak ayarlayın.
Yol söz dizimi hataları. Yol seçiciler büyük/küçük harfe duyarlıdır ve seçici için tam büyük/küçük harf kullanmazsanız eksik giriş uyarılarına yol açabilir.

Sonraki adımlar

Sonraki adım, zengin beceri kümesinden elde ettiğiniz çıkışı şekillendirme ve yansıtma konusunda size yol gösterir. Beceri kümesiniz karmaşıksa, aşağıdaki makalede hem şekillere hem de projeksiyonlara örnekler verilmiştir.

Şekillerin ve projeksiyonların ayrıntılı örneği

Aracılığıyla paylaş