Mengindeks blob dan file Markdown di Azure AI Search

Di Azure AI Search, pengindeks untuk Azure Blob Storage, Azure Files, dan OneLake mendukung markdown mode penguraian untuk file Markdown. File markdown dapat diindeks dengan dua cara:

• Mode penguraian satu ke banyak, membuat beberapa dokumen pencarian per file Markdown
• Mode penguraian satu ke satu, membuat satu dokumen pencarian per file Markdown

Prasyarat

• Sumber data yang didukung: Penyimpanan Azure Blob, penyimpanan File Azure, OneLake di Microsoft Fabric.

  Untuk OneLake, pastikan Anda memenuhi semua persyaratan pengindeks OneLake.

  Azure Storage untuk pengindeks blob dan pengindeks file adalah instans performa standar (tujuan umum v2) yang mendukung tingkat akses panas dan dingin.

Parameter mode penguraian markdown

Parameter mode penguraian ditentukan dalam definisi pengindeks saat Anda membuat atau memperbarui pengindeks.

POST https://[service name].search.windows.net/indexers?api-version=2024-11-01-preview
Content-Type: application/json
api-key: [admin key]

{
  "name": "my-markdown-indexer",
  "dataSourceName": "my-blob-datasource",
  "targetIndexName": "my-target-index",
  "parameters": {
    "configuration": {
      "parsingMode": "markdown",
      "markdownParsingSubmode": "oneToMany",
      "markdownHeaderDepth": "h6"
    }
  },
}

Pengindeks blob menyediakan submode parameter untuk menentukan output struktur dokumen pencarian. Mode penguraian markdown menyediakan opsi submode berikut:

Untuk oneToMany submode, Anda harus meninjau Pengindeksan satu blob untuk menghasilkan banyak dokumen pencarian untuk memahami bagaimana pengindeks blob menangani disambiguasi kunci dokumen untuk beberapa dokumen pencarian yang dihasilkan dari blob yang sama.

Bagian selanjutnya menjelaskan setiap submode secara lebih rinci. Jika Anda tidak terbiasa dengan klien dan konsep pengindeks, lihat Membuat pengindeks pencarian. Anda juga harus memahami detail konfigurasi pengindeks blob dasar, yang tidak diulang di sini.

Parameter penguraian Markdown opsional

Parameternya peka huruf besar/kecil.

Pengaturan ini dapat diubah setelah pembuatan awal pengindeks, namun struktur dokumen pencarian yang dihasilkan mungkin berubah tergantung pada konten Markdown.

Elemen Markdown yang didukung

Penguraian markdown hanya akan membagi konten berdasarkan header. Semua elemen lain seperti daftar, blok kode, tabel, dan sebagainya, diperlakukan sebagai teks biasa dan diteruskan ke bidang konten.

Sampel konten Markdown

Konten Markdown berikut digunakan untuk contoh di halaman ini:

# Section 1
Content for section 1.

## Subsection 1.1
Content for subsection 1.1.

# Section 2
Content for section 2.

Gunakan mode penguraian satu-ke-banyak

Mode penguraian satu-ke-banyak menguraikan file Markdown ke dalam beberapa dokumen pencarian, di mana setiap dokumen sesuai dengan bagian konten tertentu dari file Markdown berdasarkan metadata header pada saat itu dalam dokumen. Markdown diurai berdasarkan header ke dalam dokumen pencarian yang berisi konten berikut:

• content: String yang berisi Markdown mentah yang ditemukan di lokasi tertentu, berdasarkan metadata header pada saat itu dalam dokumen.

• sections: Objek yang berisi subbidang untuk metadata header hingga tingkat header yang diinginkan. Misalnya, ketika markdownHeaderDepth diatur ke h3, berisi bidang h1string , , h2dan h3. Bidang ini diindeks dengan mencerminkan struktur ini dalam indeks, atau melalui pemetaan bidang dalam format /sections/h1, , sections/h2dll. Lihat konfigurasi indeks dan pengindeks dalam sampel berikut untuk contoh dalam konteks. Subbidang yang terkandung adalah:

  • h1 - String yang berisi nilai header h1. String kosong jika tidak diatur pada titik ini dalam dokumen.
  • (Opsional) h2- String yang berisi nilai header h2. String kosong jika tidak diatur pada titik ini dalam dokumen.
  • (Opsional) h3- String yang berisi nilai header h3. String kosong jika tidak diatur pada titik ini dalam dokumen.
  • (Opsional) h4- String yang berisi nilai header h4. String kosong jika tidak diatur pada titik ini dalam dokumen.
  • (Opsional) h5- String yang berisi nilai header h5. String kosong jika tidak diatur pada titik ini dalam dokumen.
  • (Opsional) h6- String yang berisi nilai header h6. String kosong jika tidak diatur pada titik ini dalam dokumen.

• ordinal_position: Nilai bilangan bulat yang menunjukkan posisi bagian dalam hierarki dokumen. Bidang ini digunakan untuk mengurutkan bagian dalam urutan aslinya saat muncul dalam dokumen, dimulai dengan posisi ordinal 1 dan bertahap secara berurutan untuk setiap header.

Skema indeks untuk penguraian satu-ke-banyak

Contoh konfigurasi indeks mungkin terlihat seperti ini:

{
  "name": "my-markdown-index",
  "fields": [
  {
    "name": "id",
    "type": "Edm.String",
    "key": true
  },
  {
    "name": "content",
    "type": "Edm.String",
  },
  {
    "name": "ordinal_position",
    "type": "Edm.Int32"
  },
  {
    "name": "sections",
    "type": "Edm.ComplexType",
    "fields": [
    {
      "name": "h1",
      "type": "Edm.String"
    },
    {
      "name": "h2",
      "type": "Edm.String"
    }]
  }]
}

Definisi pengindeks untuk penguraian satu ke banyak

Jika nama bidang dan jenis data selaras, pengindeks blob dapat menyimpulkan pemetaan tanpa pemetaan bidang eksplisit yang ada dalam permintaan, sehingga konfigurasi pengindeks yang sesuai dengan konfigurasi indeks yang disediakan mungkin terlihat seperti ini:

POST https://[service name].search.windows.net/indexers?api-version=2024-11-01-preview
Content-Type: application/json
api-key: [admin key]

{
  "name": "my-markdown-indexer",
  "dataSourceName": "my-blob-datasource",
  "targetIndexName": "my-target-index",
  "parameters": {
    "configuration": { "parsingMode": "markdown" }
  },
}

Output pengindeks untuk penguraian satu-ke-banyak

File Markdown ini akan menghasilkan tiga dokumen pencarian setelah pengindeksan, karena tiga bagian konten. Dokumen pencarian yang dihasilkan dari bagian konten pertama dari dokumen Markdown yang disediakan akan berisi nilai berikut untuk content, , sectionsh1, dan h2:

{
  {
    "content": "Content for section 1.\r\n",
    "sections": {
      "h1": "Section 1",
      "h2": ""
    },
    "ordinal_position": 1
  },
  {
    "content": "Content for subsection 1.1.\r\n",
    "sections": {
      "h1": "Section 1",
      "h2": "Subsection 1.1"
    },
    "ordinal_position": 2
  },
  {
    "content": "Content for section 2.\r\n",
    "sections": {
      "h1": "Section 2",
      "h2": ""
    },
    "ordinal_position": 3
  }
}   

Memetakan bidang satu ke banyak dalam indeks pencarian

Pemetaan bidang mengaitkan bidang sumber dengan bidang tujuan dalam situasi di mana nama dan jenis bidang tidak identik. Tetapi pemetaan bidang juga dapat digunakan untuk mencocokkan bagian dokumen Markdown dan "angkat" ke bidang tingkat atas dokumen pencarian.

Contoh berikut mengilustrasikan skenario ini. Untuk informasi selengkapnya tentang pemetaan bidang secara umum, lihat pemetaan bidang.

Asumsikan indeks penelusuran dengan bidang berikut: raw_content dari jenis Edm.String, h1_header dari jenis Edm.String, dan h2_header dari jenis Edm.String. Untuk memetakan Markdown Anda ke bentuk yang diinginkan, gunakan pemetaan bidang berikut:

"fieldMappings" : [
    { "sourceFieldName" : "/content", "targetFieldName" : "raw_content" },
    { "sourceFieldName" : "/sections/h1", "targetFieldName" : "h1_header" },
    { "sourceFieldName" : "/sections/h2", "targetFieldName" : "h2_header" },
  ]

Dokumen pencarian yang dihasilkan dalam indeks akan terlihat sebagai berikut:

{
  {
    "raw_content": "Content for section 1.\r\n",
    "h1_header": "Section 1",
    "h2_header": "",
  },
  {
    "raw_content": "Content for section 1.1.\r\n",
    "h1_header": "Section 1",
    "h2_header": "Subsection 1.1",
  },
  {
    "raw_content": "Content for section 2.\r\n",
    "h1_header": "Section 2",
    "h2_header": "",
  }
}

Menggunakan mode penguraian satu-ke-satu

Dalam mode penguraian satu-ke-satu, seluruh dokumen Markdown diindeks sebagai dokumen pencarian tunggal, mempertahankan hierarki dan struktur konten asli. Mode ini paling berguna ketika file yang akan diindeks berbagi struktur umum, sehingga Anda dapat menggunakan struktur umum ini dalam indeks untuk membuat bidang yang relevan dapat dicari.

Dalam definisi pengindeks, atur parsingMode ke "markdown" dan gunakan parameter opsional markdownHeaderDepth untuk menentukan kedalaman judul maksimum untuk penggugusan. Jika tidak ditentukan, defaultnya adalah , menangkap semua kemungkinan kedalaman h6header.

Markdown diurai berdasarkan header ke dalam dokumen pencarian yang berisi konten berikut:

• document_content: Berisi teks Markdown lengkap sebagai string tunggal. Bidang ini berfungsi sebagai representasi mentah dari dokumen input.

• sections: Array objek yang berisi representasi hierarkis bagian dalam dokumen Markdown. Setiap bagian direpresentasikan sebagai objek dalam array ini dan mengambil struktur dokumen dengan cara berlapis yang sesuai dengan header dan konten masing-masing. Bidang dapat diakses melalui pemetaan bidang dengan mereferensikan jalur, misalnya /sections/content. Objek dalam array ini memiliki properti berikut:

  • header_level: String yang menunjukkan tingkat header (h1, , h2, h3dll.) dalam sintaks Markdown. Bidang ini membantu dalam memahami hierarki dan penataan konten.

  • header_name: String yang berisi teks header seperti yang muncul di dokumen Markdown. Bidang ini menyediakan label atau judul untuk bagian tersebut.

  • content: String yang berisi konten teks yang segera mengikuti header, hingga header berikutnya. Bidang ini menangkap informasi atau deskripsi terperinci yang terkait dengan header. Jika tidak ada konten langsung di bawah header, ini adalah string kosong.

  • ordinal_position: Nilai bilangan bulat yang menunjukkan posisi bagian dalam hierarki dokumen. Bidang ini digunakan untuk mengurutkan bagian dalam urutan aslinya saat muncul di dokumen, dimulai dengan posisi ordinal 1 dan bertahap secara berurutan untuk setiap blok konten.

  • sections: Array yang berisi objek yang mewakili subbagian yang ditumpuk di bawah bagian saat ini. Array ini mengikuti struktur yang sama dengan array tingkat sections atas, memungkinkan representasi beberapa tingkat konten berlapis. Setiap objek subbagian juga mencakup header_levelproperti , header_name, content, dan ordinal_position , memungkinkan struktur rekursif yang mewakili dan hierarki konten Markdown.

Berikut adalah sampel Markdown yang kami gunakan untuk menjelaskan skema indeks yang dirancang di sekitar setiap mode penguraian.

# Section 1
Content for section 1.

## Subsection 1.1
Content for subsection 1.1.

# Section 2
Content for section 2.

Skema indeks untuk penguraian satu-ke-satu

Jika Anda tidak menggunakan pemetaan bidang, bentuk indeks harus mencerminkan bentuk konten Markdown. Mengingat struktur sampel Markdown dengan dua bagian dan subbagian tunggalnya, indeks akan terlihat mirip dengan contoh berikut:

{
  "name": "my-markdown-index",
  "fields": [
  {
    "name": "document_content",
    "type": "Edm.String",
  {
    "name": "sections",
    "type": "Edm.ComplexType",
    "fields": [
    {
      "name": "header_level",
      "type": "Edm.String",
    },
    {
      "name": "header_name",
      "type": "Edm.String",
    },
    {
      "name": "content",
      "type": "Edm.String"
    },
    {
      "name": "ordinal_position",
      "type": "Edm.Int"
    },
    {
      "name": "sections",
      "type": "Edm.ComplexType",
      "fields": [
      {
        "name": "header_level",
        "type": "Edm.String",
      },
      {
        "name": "header_name",
        "type": "Edm.String",
      },
      {
        "name": "content",
        "type": "Edm.String"
      },
      {
        "name": "ordinal_position",
        "type": "Edm.Int"
      }]
    }]
  }
}

Definisi pengindeks untuk penguraian satu-ke-satu

POST https://[service name].search.windows.net/indexers?api-version=2024-11-01-preview
Content-Type: application/json
api-key: [admin key]

{
  "name": "my-markdown-indexer",
  "dataSourceName": "my-blob-datasource",
  "targetIndexName": "my-target-index",
  "parameters": {
    "configuration": {
      "parsingMode": "markdown",
      "markdownParsingSubmode": "oneToOne",
    }
  }
}

Output pengindeks untuk penguraian satu-ke-satu

Karena Markdown yang ingin kita indeks hanya masuk ke kedalaman h2 ("##"), kita perlu sections bidang yang ditumpuk ke kedalaman 2 untuk mencocokkan itu. Konfigurasi ini akan menghasilkan data berikut dalam indeks:

  "document_content": "# Section 1\r\nContent for section 1.\r\n## Subsection 1.1\r\nContent for subsection 1.1.\r\n# Section 2\r\nContent for section 2.\r\n",
  "sections": [
    {
      "header_level": "h1",
      "header_name": "Section 1",
      "content": "Content for section 1.",
      "ordinal_position": 1,
      "sections": [
        {
          "header_level": "h2",
          "header_name": "Subsection 1.1",
          "content": "Content for subsection 1.1.",
          "ordinal_position": 2,
        }]
    }],
    {
      "header_level": "h1",
      "header_name": "Section 2",
      "content": "Content for section 2.",
      "ordinal_position": 3,
      "sections": []
    }]
  }

Seperti yang Anda lihat, kenaikan posisi ordinal berdasarkan lokasi konten dalam dokumen.

Perlu juga dicatat bahwa jika tingkat header dilewati dalam konten, struktur dokumen yang dihasilkan mencerminkan header yang ada dalam konten Markdown, belum tentu berisi bagian berlapis melalui h1 h6 secara berurutan. Misalnya, ketika dokumen dimulai pada h2, maka elemen pertama di array bagian tingkat atas adalah h2.

Memetakan bidang satu ke satu dalam indeks pencarian

Jika Anda ingin mengekstrak bidang dengan nama kustom dari dokumen, Anda bisa menggunakan pemetaan bidang untuk melakukannya. Menggunakan sampel Markdown yang sama seperti sebelumnya, pertimbangkan konfigurasi indeks berikut:

{
  "name": "my-markdown-index",
  "fields": [
    {
      "name": "document_content",
      "type": "Edm.String",
    },
    {
      "name": "document_title",
      "type": "Edm.String",
    },
    {
      "name": "opening_subsection_title"
      "type": "Edm.String",
    }
    {
      "name": "summary_content",
      "type": "Edm.String",
    }
  ]
}

Mengekstrak bidang tertentu dari Markdown yang diurai ditangani mirip dengan bagaimana jalur dokumen berada dalam outputFieldMappings, kecuali jalur dimulai dengan /sections alih-alih /document. Jadi, misalnya, /sections/0/content akan memetakan ke konten di bawah item pada posisi 0 di array bagian.

Contoh kasus penggunaan yang kuat mungkin terlihat seperti ini: semua file Markdown memiliki judul dokumen di judul pertama h1, subbagian di yang pertama h2, dan ringkasan dalam konten paragraf akhir di bawah final h1. Anda dapat menggunakan pemetaan bidang berikut untuk mengindeks konten tersebut saja:

"fieldMappings" : [
  { "sourceFieldName" : "/content", "targetFieldName" : "raw_content" },
  { "sourceFieldName" : "/sections/0/header_name", "targetFieldName" : "document_title" },
  { "sourceFieldName" : "/sections/0/sections/header_name", "targetFieldName" : "opening_subsection_title" },
  { "sourceFieldName" : "/sections/1/content", "targetFieldName" : "summary_content" },
]

Di sini Anda hanya akan mengekstrak potongan-potongan yang relevan dari dokumen tersebut. Untuk menggunakan fungsionalitas ini secara paling efektif, dokumen yang Anda rencanakan untuk diindeks harus berbagi struktur header hierarkis yang sama.

Dokumen pencarian yang dihasilkan dalam indeks akan terlihat sebagai berikut:

{
  "content": "Content for section 1.\r\n",
  "document_title": "Section 1",
  "opening_subsection_title": "Subsection 1.1",
  "summary_content": "Content for section 2."
}

Langkah berikutnya

• Mengonfigurasi pengindeks blob
• Menentukan pemetaan bidang
• Ringkasan pengindeks
• Cara mengindeks blob CSV dengan pengindeks blob
• Tutorial: Mencari data Markdown dari Azure Blob Storage