Bagikan melalui

Mengindeks blob dan file Markdown di Azure AI Search

Nota

Fitur ini saat ini dalam pratinjau publik. Pratinjau ini disediakan tanpa perjanjian tingkat layanan dan tidak direkomendasikan untuk beban kerja produksi. Fitur tertentu mungkin tidak didukung atau mungkin memiliki kemampuan terbatas. Untuk informasi lebih lanjut, lihat Supplemental Terms of Use for Microsoft Azure Previews.

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

  • Mode analisis satu-ke-banyak, membuat beberapa dokumen pencarian untuk setiap file Markdown.
  • Mode penguraian satu ke satu, membuat satu dokumen pencarian per file Markdown

Petunjuk / Saran

Lanjutkan ke Tutorial: Cari data Markdown dari Azure Blob Storage setelah meninjau artikel ini.

Prasyarat

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

    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 modus 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=2025-08-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:

mode penguraian submode Dokumen pencarian Description
markdown oneToMany Beberapa per blob (default) Memecah Markdown menjadi beberapa dokumen pencarian, masing-masing mewakili bagian konten (nonheader) dari file Markdown. Anda bisa mengabaikan submode kecuali jika Anda menginginkan penguraian satu-ke-satu.
markdown oneToOne Satu per blob Mengurai Markdown ke dalam satu dokumen pencarian, dengan bagian yang dipetakan ke header tertentu dalam file Markdown.

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 opsional untuk penguraian Markdown

Parameter sensitif terhadap huruf besar/kecil.

Nama Parameter Nilai yang diizinkan Description
markdownHeaderDepth h1, h2h3, h4, h5, h6(default) Parameter ini menentukan tingkat header terdalam yang dipertimbangkan saat mengurai, memungkinkan penanganan fleksibel struktur dokumen (misalnya, ketika markdownHeaderDepth diatur ke h1, pengurai hanya mengenali header tingkat atas yang dimulai dengan "#", dan semua header tingkat bawah diperlakukan sebagai teks biasa). Jika tidak ditentukan, defaultnya adalah h6.

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 memisahkan 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 pemrosesan satu-ke-banyak memproses file Markdown ke dalam beberapa dokumen pencarian, di mana setiap dokumen berhubungan dengan bagian konten tertentu dari file Markdown berdasarkan metadata header dalam dokumen tersebut. 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 string h1, h2, dan 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=2025-08-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" }
  },
}

Nota

submode Tidak perlu diatur secara eksplisit di sini karena oneToMany merupakan default.

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": "",
  }
}

Gunakan mode penguraian satu-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 h6, menangkap semua kemungkinan kedalaman header.

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, nilainya 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_level, properti header_name, content, dan ordinal_position, memungkinkan struktur rekursif yang mewakili struktur 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": "id",
    "type": "Edm.String",
    "key": true
  },
  {
    "name": "document_content",
    "type": "Edm.String"
  },
  {
    "name": "sections",
    "type": "Collection(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.Int32"
    },
    {
      "name": "sections",
      "type": "Collection(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.Int32"
      }]
    }]
  }]
}

Definisi pengindeks untuk penguraian satu-ke-satu

POST https://[service name].search.windows.net/indexers?api-version=2025-08-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",
    }
  }
}

Hasil pengindeks untuk penguraian satu-ke-satu

Karena Markdown yang ingin kita indeks hanya masuk ke kedalaman h2 ("##"), kita perlu sections bidang yang disarang 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, maka struktur dokumen yang dihasilkan mencerminkan header yang ada dalam konten Markdown, dan belum tentu mengandung bagian berlapis untuk h1 hingga 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 mengacu pada konten di bawah item pada posisi 0 dalam 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."
}

Nota

Contoh-contoh ini menentukan cara menggunakan mode penguraian ini sepenuhnya dengan atau tanpa pemetaan bidang, tetapi Anda dapat menerapkan keduanya dalam satu skenario jika sesuai dengan kebutuhan Anda.

Mengelola dokumen kedaluarsa dari pengindeksan ulang Markdown

Saat menggunakan mode penguraian satu-ke-banyak, pengindeksan ulang file Markdown yang dimodifikasi dapat mengakibatkan dokumen basi atau duplikat jika bagian dihapus. Perilaku ini khusus untuk mode satu-ke-banyak dan tidak berlaku untuk penguraian satu-ke-satu.

Gambaran umum perilaku

Mode penguraian satu ke banyak

Dalam oneToMany mode, setiap bagian Markdown (berdasarkan header) diindeks sebagai dokumen pencarian terpisah. Ketika file diindeks ulang:

  • Tidak ada penghapusan otomatis: Pengindeks menimpa dokumen yang ada dengan dokumen baru, tetapi tidak menghapus dokumen yang tidak lagi sesuai dengan konten apa pun dalam file yang diperbarui.
  • Potensi duplikat: Masalah ini secara khusus muncul hanya ketika lebih banyak bagian dihapus daripada disisipkan di antara pengindeksan berjalan. Dalam kasus seperti itu, dokumen sisa dari versi sebelumnya tetap berada dalam indeks, yang mengarah ke entri kedaluarsa yang tidak lagi mencerminkan status file sumber saat ini.

Mode penguraian satu ke satu

Dalam oneToOne mode, seluruh file Markdown diindeks sebagai dokumen pencarian tunggal. Ketika file diindeks ulang:

  • Menimpa perilaku: Dokumen yang ada diganti sepenuhnya dengan versi baru.
  • Tidak ada bagian kedaluarsa: Saat file diindeks ulang, dokumen yang ada diganti dengan versi yang diperbarui dan konten yang dihapus tidak lagi disertakan. Satu-satunya pengecualian adalah jika jalur file atau URI blob berubah, yang dapat mengakibatkan dokumen baru dibuat bersama yang lama.

Opsi penanganan masalah

Untuk memastikan indeks mencerminkan status file Markdown Anda saat ini, pertimbangkan salah satu pendekatan berikut:

Opsi 1. Penghapusan sementara dengan metadata

Metode ini menggunakan penghapusan sementara untuk menghapus dokumen yang terkait dengan blob tertentu. Untuk informasi selengkapnya, lihat Mengubah dan menghapus deteksi menggunakan pengindeks untuk Azure Storage di Azure AI Search.

Langkah-langkah:

  1. Tandai blob sebagai dihapus dengan mengatur bidang metadata.
  2. Biarkan pengindeks berjalan. Ini menghapus semua dokumen dalam indeks yang terkait dengan blob tersebut.
  3. Hapus penanda penghapusan sementara dan indeks ulang file.

Opsi 2. Menggunakan API penghapusan

Sebelum mengindeks ulang file Markdown yang dimodifikasi, secara eksplisit menghapus dokumen yang ada yang terkait dengan file tersebut menggunakan API penghapusan. Anda dapat:

  • Indentifikasi dokumen kedaluarsa individual secara manual dengan mengidentifikasi duplikat dalam indeks yang akan dihapus. Ini mungkin layak untuk perubahan kecil yang dipahami dengan baik tetapi dapat memakan waktu.
  • (Disarankan) Hapus semua dokumen yang dihasilkan dari file induk yang sama sebelum pengindeksan ulang, memastikan inkonsistensi dihindari.

Langkah-langkah:

  1. Identifikasi id dokumen yang terkait dengan file. Gunakan kueri seperti contoh berikut untuk mengambil ID kunci dokumen (misalnya, id, , chunk_iddll.) untuk semua dokumen yang terkait dengan file tertentu. Ganti metadata_storage_path dengan bidang yang sesuai dalam indeks Anda yang memetakan ke jalur file atau URI blob. Bidang ini harus berupa kunci.

    GET https://[service name].search.windows.net/indexes/[index name]/docs?api-version=2025-05-01-preview
Content-Type: application/json
api-key: [admin key]


  {  
      "filter": "metadata_storage_path eq 'https://<storage-account>.blob.core.windows.net/<container-name>/<file-name>.md'",
      "select": "id"
  }

  2. Terbitkan permintaan penghapusan untuk dokumen dengan kunci yang diidentifikasi.

    POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=2025-05-01-preview
Content-Type: application/json
api-key: [admin key]

{  
  "value": [  
    {  
      "@search.action": "delete",  
      "id": "aHR0c...jI1"  
    },
    {  
      "@search.action": "delete",  
      "id": "aHR0...MQ2"  
    }  
  ]  
}

  3. Indeks ulang file yang diperbarui.

Langkah selanjutnya

  • Last updated on