Definisikan proyeksi dalam penyimpanan pengetahuan

Note

Penyimpanan pengetahuan adalah penyimpanan sekunder yang ada di Azure Storage dan berisi output set keterampilan Pencarian Azure AI. Mereka terpisah dari sumber pengetahuan dan pangkalan pengetahuan, yang digunakan dalam alur kerja pengambilan agenik .

Proyeksi adalah komponen definisi penyimpanan pengetahuan yang menentukan bagaimana 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 dalam properti skillset.

"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 penyimpanan sementara pengayaan (pratinjau) agar dapat menggunakan kembali pengayaan yang ada saat mengedit definisi proyeksi. Penembolokan pengayaan adalah fitur pratinjau, jadi pastikan untuk menggunakan pratinjau REST API pada permintaan pengindeksan. Tanpa penyimpanan sementara, pengeditan sederhana pada proyeksi akan menghasilkan pemrosesan ulang secara penuh dari konten yang diperkaya. Dengan penyimpanan sementara pengayaan, Anda dapat mengulangi proyeksi tanpa menimbulkan biaya pemrosesan kumpulan keterampilan apa pun.

Requirements

Semua proyeksi memiliki sumber dan properti tujuan. Sumbernya selalu merupakan konten internal dari pohon pengayaan yang dibuat selama eksekusi skillset. Destinasi adalah nama dan jenis objek eksternal yang dibuat dan dipopulasikan 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")

Meskipun sebuah node dapat mengacu pada satu field, representasi yang lebih umum adalah referensi ke bentuk yang kompleks. Bentuk kompleks dibentuk melalui metodologi pembentukan, baik menggunakan keterampilan Shaper atau definisi pembentukan inline, tetapi biasanya menggunakan keterampilan Shaper. Bidang atau elemen bentuk menentukan bidang dalam kontainer dan tabel.

Keterampilan pembentuk disukai karena menghasilkan JSON, sedangkan sebagian besar fitur tidak menghasilkan JSON yang valid secara mandiri. Dalam banyak kasus, bentuk data yang sama yang dibuat oleh skill Shaper dapat digunakan sama baiknya 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. Bagian tabel dari array proyeksi adalah daftar tabel yang ingin Anda proyeksikan.

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

Property Description
tableName Menentukan nama tabel baru yang dibuat di Penyimpanan Tabel Azure.
generatedKeyName Nama kolom untuk kunci yang secara unik mengidentifikasi baris ini. Nilainya dibuat oleh sistem. Jika Anda menghilangkan properti ini, kolom 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 pembentukan adalah mekanisme di mana baris dan kolom ditentukan. Anda dapat menggunakan kemampuan Shaper atau bentuk sebaris. Keterampilan Shaper menghasilkan JSON yang valid, tetapi sumbernya bisa berasal dari kemampuan apa pun asalkan JSON tersebut valid.

Note

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 tabel majemuk (pemotongan)

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 diekstrak dari dokumen mungkin tidak terkait dari entitas yang dikenali 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 jika node turunan merupakan sumber bagi tabel lain dalam grup yang sama. Menambahkan proyeksi dengan jalur sumber yang merupakan anak dari proyeksi yang ada mengakibatkan node anak dipisahkan dari node induk dan diproyeksikan ke dalam tabel baru yang masih 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 lain untuk menyimpan irisan konten yang telah 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 ditempatkan di 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/*" }
    ]
  }
]

Menamai 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. Ketika referenceKeyName tidak disediakan, layanan akan menjadi 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:

Property Description
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 dibuat secara otomatis yang menggunakan nama tabel dan "kunci" sebagai konvensi penamaan.
sumber Jalur menuju simpul dalam pohon pengayaan yang menjadi akar 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 keahlian Shaper, bernama "objectprojection". Setiap blob 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 berkas

Proyeksi berkas selalu biner, gambar yang dinormalisasi, di mana normalisasi mengacu pada ukuran ulang dan rotasi potensial untuk digunakan dalam eksekusi keahlian. 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:

Property Description
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 dibuat secara otomatis yang menggunakan nama tabel dan "kunci" sebagai konvensi penamaan.
sumber Jalur menuju simpul dalam pohon pengayaan yang menjadi akar 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 merupakan wadah blob, dengan awalan direktori dari nilai ID dokumen yang telah dikodekan dalam base64. Jika ada beberapa gambar, gambar ditempatkan bersama-sama 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/*"
            }
        ]
    }
]

Proyeksi pengujian

Anda dapat memproses proyeksi dengan mengikuti langkah-langkah berikut:

  1. Atur properti storageConnectionString dari knowledge store 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 secara otomatis mendeteksi hubungan di 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 berbentuk 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 menentukan bentuk sebaris membantu mengatasi 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 terhadap kapitalisasi dan dapat menyebabkan peringatan input yang tidak ditemukan jika Anda tidak menggunakan kapitalisasi yang tepat untuk pemilih tersebut.

Langkah selanjutnya

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

Contoh mendetail bentuk dan proyeksi

  • Last updated on