Mengindeks blob dan file Markdown di Pencarian Azure AI

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

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

Prasyarat

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

  Untuk OneLake, pastikan Anda memenuhi semua persyaratan pengindeks OneLake.

  Azure Storage untuk pengindeks blob dan pengindeks file (pratinjau) 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=2026-04-01
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 struktur output dokumen pencarian. Mode penguraian markdown menyediakan opsi submode berikut:

Untuk oneToMany submode, Anda harus meninjau Pengindeksan satu blob untuk menghasilkan banyak dokumen pencarian agar memahami cara pengindeks blob menangani disambiguasi kunci dokumen ketika banyak dokumen pencarian 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 terbiasa dengan detail konfigurasi pengindeks blob dasar, yang tidak diulang di sini.

Parameter penguraian Markdown opsional

Parameter sensitif terhadap huruf besar dan kecil.

Pengaturan ini dapat diubah setelah pengindeks dibuat. 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, dan tabel, 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 bagian tersebut dalam dokumen. Markdown diurai berdasarkan header menjadi dokumen pencarian, yang berisi konten berikut ini:

• 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-bidang ini diindeks dengan mencerminkan struktur ini dalam indeks, atau melalui pemetaan bidang dalam format /sections/h1, , /sections/h2dan sebagainya. 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=2026-04-01
Content-Type: application/json
api-key: [admin key]

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

Hasil pengindeks untuk pemrosesan 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 pencarian dengan bidang berikut: raw_content jenis Edm.String, h1_header jenis Edm.String, dan h2_header 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-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 h6, memuat semua kemungkinan kedalaman header.

Markdown diurai berdasarkan header menjadi dokumen pencarian, yang berisi konten berikut ini:

• 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, , h2h3, dan sebagainya) 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, header_name, content, dan ordinal_position, memungkinkan adanya struktur rekursif yang menggambarkan 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=2026-04-01
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 pemetaan 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.

Jika tingkat header dilewati dalam konten, struktur dokumen yang dihasilkan mencerminkan header yang ada dalam konten Markdown dan tidak selalu berisi bagian bertingkat secara berurutan dari h1 melalui h6. Misalnya, ketika dokumen dimulai pada h2, elemen pertama di array bagian tingkat atas adalah h2.

Memetakan bidang satu ke satu dalam indeks pencarian

Untuk mengekstrak bidang dengan nama kustom dari dokumen, Anda bisa menggunakan pemetaan bidang. 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 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."
}

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, namun tidak menghapus dokumen yang tidak lagi berhubungan dengan konten dalam file yang telah 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-satu

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

• Perilaku Penimpaan: Dokumen yang ada sepenuhnya digantikan 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 Ubah dan hapus deteksi menggunakan pengindeks untuk Azure Storage di Pencarian Azure AI.

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:

• Identifikasi 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:

1. Identifikasi ID dokumen yang terkait dengan file. Gunakan kueri seperti contoh berikut untuk mengambil ID kunci dokumen (misalnya, id atau chunk_id) 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=2026-04-01
   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=2026-04-01
   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 berikutnya

• Mengonfigurasi pengindeks blob
• Menentukan pemetaan bidang
• Gambaran umum pengindeks
• Cara mengindeks blob CSV dengan pengindeks blob
• Tutorial: Cari data Markdown dari Azure Blob Storage