Menentukan proyeksi di simpanan pengetahuan

  • Artikel

Proyeksi adalah komponen definisi penyimpanan pengetahuan yang menentukan tempat konten yang diperkaya AI disimpan di Azure Storage. Proyeksi menentukan jenis, kuantitas, dan komposisi struktur data yang berisi konten Anda.

Di artikel ini, pelajari sintaksis untuk setiap jenis proyeksi:

Ingat bahwa proyeksi didefinisikan di bawah properti "knowledgeStore" dari set keterampilan.

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

Jika Anda memerlukan lebih banyak latar belakang sebelum memulai, tinjau daftar periksa ini untuk tips dan alur kerja.

Tip

Saat mengembangkan proyeksi, aktifkan penembolokan pengayaan (pratinjau) sehingga Anda dapat menggunakan kembali pengayaan yang ada saat mengedit definisi proyeksi. Penembolokan pengayaan adalah fitur pratinjau, jadi pastikan untuk menggunakan PRATINJAU REST API (api-version=2020-06-30-preview atau yang lebih baru) pada permintaan pengindeks. Tanpa penembolokan, pengeditan sederhana ke proyeksi akan menghasilkan proses ulang penuh konten yang diperkaya. Dengan penembolokan pengayaan, Anda dapat melakukan iterasi atas proyeksi tanpa menimbulkan biaya pemrosesan set keterampilan apa pun.

Persyaratan

Semua proyeksi memiliki sumber dan properti tujuan. Sumbernya selalu merupakan konten internal dari pohon pengayaan yang dibuat selama eksekusi skillset. Tujuannya adalah nama dan jenis objek eksternal yang dibuat dan diisi di Azure Storage.

Kecuali untuk proyeksi file, yang hanya menerima gambar biner, sumbernya harus berupa:

  • JSON yang valid
  • Jalur ke node di pohon pengayaan (misalnya, "source": "/document/objectprojection")

Sementara node mungkin mengatasi untuk satu bidang, representasi yang lebih umum adalah referensi ke bentuk yang kompleks. Bentuk kompleks dibuat melalui metodologi pembentukan, baik keterampilan Shaper atau definisi pembentukan inline, tetapi biasanya keterampilan Shaper. Bidang atau elemen bentuk menentukan bidang dalam kontainer dan tabel.

Keterampilan pembentuk disukai karena menghasilkan JSON, di mana karena sebagian besar keterampilan tidak menghasilkan JSON yang valid sendiri. Dalam banyak kasus, bentuk data yang sama yang dibuat oleh keterampilan Shaper dapat digunakan secara merata oleh proyeksi tabel dan objek.

Mengingat persyaratan input sumber, mengetahui cara membentuk data menjadi persyaratan praktis untuk definisi proyeksi, terutama jika Anda bekerja dengan tabel.

Mendefinisikan proyeksi tabel

Proyeksi tabel direkomendasikan untuk skenario yang memanggil eksplorasi data, seperti analisis dengan Power BI atau beban kerja yang menggunakan bingkai data. Bagain tabel array proyeksi adalah daftar tabel yang ingin Anda proyeksikan.

Untuk menentukan proyeksi objek, gunakan array tables dalam properti proyeksi. Proyeksi tabel memiliki tiga properti yang diperlukan:

Properti Deskripsi
tableName Menentukan nama tabel baru yang dibuat di Azure Table Storage.
generatedKeyName Nama kolom untuk kunci yang secara unik mengidentifikasi baris ini. Nilainya dibuat oleh sistem. Jika Anda menghilangkan properti ini, kolom akan dibuat secara otomatis yang menggunakan nama tabel dan "kunci" sebagai konvensi penamaan.
sumber Jalan menuju simpul di pohon pengayaan. Node harus menjadi referensi ke bentuk kompleks yang menentukan kolom mana yang dibuat dalam tabel.

Di proyeksi tabel, “sumber” biasanya merupakan output keterampilan Shaper yang menentukan bentuk tabel. Tabel memiliki baris dan kolom, dan membentuk adalah mekanisme di mana baris dan kolom ditentukan. Anda dapat menggunakan kemampuan Pembentuk atau bentuk sebaris. Keterampilan Shaper membuat JSON yang valid, tetapi bisa menjadi output dari kemampuan apa pun, jika JSON valid.

Catatan

Proyeksi tabel tunduk pada batas penyimpanan yang diberlakukan oleh Azure Storage. Ukuran entitas tidak boleh melebihi 1 MB dan satu properti tidak boleh lebih besar dari 64 KB. Batasan ini menjadikan tabel sebagai solusi yang baik untuk menyimpan sejumlah besar entitas kecil.

Contoh tabel tunggal

Skema tabel ditentukan sebagian oleh proyeksi (nama tabel dan kunci), dan juga oleh sumber yang menyediakan bentuk tabel (kolom). Contoh ini hanya menunjukkan satu tabel sehingga Anda dapat berfokus pada detail definisi.

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

Kolom berasal dari "sumber". Bentuk data berikut yang berisi HotelId, HotelName, Category, dan Description akan membuat pembuatan kolom tersebut dalam tabel.

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

Contoh beberapa tabel (iris)

Pola umum untuk proyeksi tabel adalah memiliki beberapa tabel terkait, yang mana kolom partitionKey dan rowKey yang dibuat sistem dibuat untuk mendukung hubungan lintas tabel untuk semua tabel di bawah kelompok proyeksi yang sama.

Membuat beberapa tabel dapat berguna jika Anda ingin mengontrol cara data terkait dikumpulkan. Jika konten yang diperkaya memiliki komponen yang tidak terkait atau independen, misalnya kata kunci yang diekstraksi dari dokumen mungkin tidak terkait dari entitas yang diakui dalam dokumen yang sama, Anda dapat membagi bidang tersebut menjadi tabel yang berdekatan.

Saat Anda memproyeksikan ke beberapa tabel, bentuk lengkap diproyeksikan ke dalam setiap tabel, kecuali simpul anak adalah sumber tabel lain dalam grup yang sama. Menambahkan proyeksi dengan jalur sumber yang merupakan anak dari proyeksi yang ada mengakibatkan node anak diiris keluar dari node induk dan diproyeksikan ke dalam tabel baru tetapi terkait. Teknik ini memungkinkan Anda untuk menentukan satu simpul dalam kemampuan Pembentuk yang dapat menjadi sumber untuk semua proyeksi Anda.

Pola untuk beberapa tabel terdiri dari:

  • Satu tabel sebagai tabel induk atau utama
  • Tabel tambahan untuk berisi irisan konten yang diperkaya

Misalnya, asumsikan keterampilan Shaper menghasilkan "EnrichedShape" yang berisi informasi hotel, ditambah konten yang diperkaya seperti frasa kunci, lokasi, dan organisasi. Tabel utama akan mencakup bidang yang menggambarkan hotel (ID, nama, deskripsi, alamat, kategori). Frasa kunci akan mendapatkan kolom frasa kunci. Entitas akan mendapatkan kolom entitas.

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

Penamaan hubungan

Properti generatedKeyName dan referenceKeyName digunakan untuk menghubungkan data lintas tabel atau bahkan di seluruh jenis proyeksi. Setiap baris dalam tabel anak memiliki properti yang menunjuk kembali ke induk. Nama kolom atau properti dalam anak adalah referenceKeyName dari induknya. referenceKeyName Ketika tidak disediakan, layanan akan default ke generatedKeyName dari induk.

Power BI mengandalkan tombol yang dihasilkan ini untuk menemukan hubungan dalam tabel. Jika Anda memerlukan kolom dalam tabel anak bernama berbeda, atur properti referenceKeyName di tabel induk. Salah satu contohnya adalah mengatur generatedKeyName sebagai ID pada tabel tbIDocument dan referenceKeyName sebagai DocumentID. Hal ini akan menghasilkan kolom dalam tabel tbIEntities dan tbIKeyPhrases yang berisi ID dokumen bernama DocumentID.

Menentukan proyeksi objek

Proyeksi objek adalah representasi JSON dari pohon pengayaan yang dapat bersumber dari node apa pun. Dibandingkan dengan proyeksi tabel, proyeksi objek lebih mudah untuk didefinisikan dan digunakan saat memproyeksikan seluruh dokumen. Proyeksi objek terbatas pada satu proyeksi dalam kontainer dan tidak dapat diiris.

Untuk menentukan proyeksi objek, gunakan array objects dalam properti proyeksi. Proyeksi objek memiliki tiga sifat yang diperlukan:

Properti Deskripsi
storageContainer Menentukan nama kontainer baru yang dibuat di Azure Storage.
generatedKeyName Nama kolom untuk kunci yang secara unik mengidentifikasi baris ini. Nilainya dibuat oleh sistem. Jika Anda menghilangkan properti ini, kolom akan dibuat secara otomatis yang menggunakan nama tabel dan "kunci" sebagai konvensi penamaan.
sumber Jalur ke node dalam pohon pengayaan yang merupakan akar dari proyeksi. Node biasanya mengacu pada bentuk data kompleks yang menentukan struktur blob.

Contoh berikut memproyeksikan dokumen hotel individu, satu dokumen hotel per blob, ke dalam kontainer yang disebut hotels.

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

Sumbernya adalah output dari keterampilan Shaper, bernama "objectprojection". Setiap blob akan memiliki representasi JSON dari setiap input bidang.

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

Menentukan proyeksi file

Proyeksi file selalu biner, gambar dinormalisasi, di mana normalisasi mengacu pada ukuran ulang potensial dan rotasi untuk digunakan dalam eksekusi set kemampuan. Proyeksi file, mirip dengan proyeksi objek, dibuat sebagai blob dalam Azure Storage, dan berisi data biner (sebagai lawan JSON).

Untuk menentukan proyeksi file, gunakan array files dalam properti proyeksi. Proyeksi file memiliki tiga properti yang diperlukan:

Properti Deskripsi
storageContainer Menentukan nama kontainer baru yang dibuat di Azure Storage.
generatedKeyName Nama kolom untuk kunci yang secara unik mengidentifikasi baris ini. Nilainya dibuat oleh sistem. Jika Anda menghilangkan properti ini, kolom akan dibuat secara otomatis yang menggunakan nama tabel dan "kunci" sebagai konvensi penamaan.
sumber Jalur ke node dalam pohon pengayaan yang merupakan akar dari proyeksi. Untuk file gambar, sumbernya selalu /document/normalized_images/*. Proyeksi file hanya bertindak pada kumpulan normalized_images. Baik pengindeks maupun set keterampilan tidak akan melewati gambar asli yang tidak dinormalisasi.

Tujuannya selalu kontainer blob, dengan awalan folder dari nilai yang dikodekan base64 dari ID dokumen. Jika ada beberapa gambar, gambar tersebut akan ditempatkan bersama di folder yang sama. Proyeksi file tidak dapat berbagi kontainer yang sama dengan proyeksi objek dan perlu diproyeksikan ke dalam kontainer yang berbeda.

Contoh berikut memproyeksikan semua gambar yang dinormalisasi yang diekstraksi dari node dokumen pada dokumen yang diperkaya ke dalam kontainer yang disebut myImages.

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

Menguji proyeksi

Anda dapat memproses proyeksi dengan mengikuti langkah-langkah berikut:

  1. Atur properti storageConnectionString penyimpanan pengetahuan ke string koneksi akun penyimpanan tujuan umum V2 yang valid.

  2. Perbarui set keterampilan dengan mengeluarkan permintaan PUT dengan definisi proyeksi Anda di tubuh set keterampilan.

  3. Jalankan pengindeks untuk menempatkan set keterampilan ke dalam eksekusi.

  4. Pantau eksekusi pengindeks untuk memeriksa kemajuan dan menangkap kesalahan apa pun.

  5. Gunakan portal Azure untuk memverifikasi pembuatan objek di Azure Storage.

  6. Jika Anda memproyeksikan tabel, impor tabel ke Power BI untuk manipulasi dan visualisasi tabel. Dalam kebanyakan kasus, Power BI akan otomatis menemukan hubungan antara tabel.

Masalah umum

Menghilangkan salah satu langkah berikut dapat membuat hasil yang tidak terduga. Periksa kondisi berikut jika output Anda tidak terlihat benar.

  • Pengayaan string tidak dibentuk menjadi JSON yang valid. Ketika string diperkaya, contohnya merged_content diperkaya dengan frasa kunci, properti yang diperkaya diwakili sebagai anak merged_content di dalam pohon pengayaan tersebut. Representasi default bukan JSON yang terbentuk dengan baik. Pada waktu proyeksi, pastikan untuk mengubah pengayaan menjadi objek JSON yang valid dengan nama dan nilai. Menggunakan keterampilan Shaper atau mendefinisikan bentuk inline akan membantu menyelesaikan masalah ini.

  • Menghilangkan /* di akhir jalur sumber. Jika sumber proyeksi adalah /document/projectionShape/keyPhrases, larik frasa kunci diproyeksikan sebagai objek/baris tunggal. Sebagai gantinya, atur jalur sumber ke /document/projectionShape/keyPhrases/* untuk menghasilkan satu baris atau objek untuk setiap frasa kunci.

  • Kesalahan sintaksis jalur. Pemilih jalur peka huruf besar/kecil dan dapat menyebabkan peringatan input yang hilang jika Anda tidak menggunakan kasus yang tepat untuk pemilih.

Langkah berikutnya

Langkah selanjutnya memandu Anda melalui pembentukan dan proyeksi output dari set keterampilan yang kaya. Jika set keterampilan Anda rumit, artikel berikut memberikan contoh dari kedua bentuk dan proyeksi.

Contoh mendetail bentuk dan proyeksi