在 Azure AI 搜尋服務中編制 Markdown Blob 和檔案的索引

發行項
11/20/2024

注意

此功能目前處於公開預覽。此預覽版是在沒有服務等級協定的情況下提供，不建議用於生產工作負載。可能不支援特定功能，或可能已經限制功能。如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。

在 Azure AI 搜尋中，Azure Blob 儲存體、Azure 檔案儲存體和 OneLake 的索引器支援 markdown Markdown 檔案剖析模式。 Markdown 檔案可透過兩種方式編制索引：

一對多剖析模式，每個 Markdown 檔案建立多個搜尋檔
一對一剖析模式，每個 Markdown 檔案建立一個搜尋檔

提示

繼續閱讀本教學課程：檢閱本文之後，從 Azure Blob 儲存體搜尋 Markdown 數據。

必要條件

支持的數據源：Azure Blob 記憶體、Azure 檔案記憶體、Microsoft Fabric 中的 OneLake。

針對 OneLake，請確定您符合 OneLake 索引器的所有需求。

blob 索引器和檔案索引器 Azure 儲存體是支持經常性存取層和非經常性存取層的標準效能（一般用途 v2）實例。

Markdown 剖析模式參數

當您建立或更新索引器時，會在索引器定義中指定剖析模式參數。

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

Blob 索引器會提供 submode 參數來判斷搜尋文件的結構輸出。 Markdown 剖析模式提供下列子模式選項：

parsingMode	submode	搜尋檔	描述
`markdown`	`oneToMany`	一個 blob 多個	（預設值）將 Markdown 分成多個搜尋檔，每個檔都代表 Markdown 檔案的內容（非header）區段。除非您想要一對一剖析，否則您可以省略子模式。
`markdown`	`oneToOne`	一個 blob 一個	將 Markdown 剖析成一個搜尋檔，其中區段對應至 Markdown 檔案中的特定標頭。

針對 oneToMany 子模式，您應該檢閱編製一個 Blob 的索引，以產生許多搜尋檔，以瞭解 Blob 索引器如何處理檔索引鍵的混淆，以取得從相同 Blob 產生的多個搜尋檔。

稍後各節會更詳細地描述每個子模式。如果您不熟悉索引子用戶端和概念，請參閱建立搜尋索引子 (機器翻譯)。您也應熟悉基本 blob 索引子設定的詳細資料，本文不再重複。

選擇性 Markdown 剖析參數

這些參數會區分大小寫。

參數名稱	允許的值	描述
`markdownHeaderDepth`	`h1`、、`h2h3`、`h4`、、`h5`、`h6(default)`	此參數會決定剖析時考慮的最深層標頭層級，允許彈性處理檔結構（例如，當 `markdownHeaderDepth` 設定 `h1`為時，剖析器只會辨識開頭為 “#” 的最上層標頭，而且所有較低層級的標頭都會被視為純文本）。如果未指定，則預設為 `h6`。

建立索引器之後，可以變更此設定，不過產生的搜尋文件結構可能會根據 Markdown 內容而變更。

支援的 Markdown 元素

Markdown 剖析只會根據標頭分割內容。清單、程式代碼區塊、數據表等所有其他元素都會被視為純文本，並傳遞至內容欄位。

範例 Markdown 內容

下列 Markdown 內容用於此頁面的範例：

# Section 1
Content for section 1.

## Subsection 1.1
Content for subsection 1.1.

# Section 2
Content for section 2.

使用一對多剖析模式

一對多剖析模式會將 Markdown 檔案剖析成多個搜尋檔，其中每個檔會根據檔中的標頭元數據，對應至 Markdown 檔案的特定內容區段。 Markdown 會根據標頭剖析成包含下列內容的搜尋檔：

content：字串，其中包含在特定位置中找到的原始 Markdown，此字串會根據檔中該點的標頭元數據。
sections：物件，包含標頭元數據的子字段，最多可達所需的標頭層級。例如，當設定為時markdownHeaderDepth，會包含字串字段h1、 h2和 h3。h3 這些欄位會透過鏡像索引中的這個結構，或透過格式 /sections/h1、 sections/h2等的欄位對應來編制索引。如需內容中的範例，請參閱下列範例中的索引和索引器組態。包含的子欄位如下：
- h1 - 包含 h1 標頭值的字串。如果目前檔中未設定，則為空字串。
- （選擇性） h2- 包含 h2 標頭值的字串。如果目前檔中未設定，則為空字串。
- （選擇性） h3- 包含 h3 標頭值的字串。如果目前檔中未設定，則為空字串。
- （選擇性） h4- 包含 h4 標頭值的字串。如果目前檔中未設定，則為空字串。
- （選擇性） h5- 包含 h5 標頭值的字串。如果目前檔中未設定，則為空字串。
- （選擇性） h6- 包含 h6 標頭值的字串。如果目前檔中未設定，則為空字串。
ordinal_position：整數值，表示區段在文件階層中的位置。此欄位用於排序其原始序列中的區段，因為它們出現在檔中，從序數位置 1 開始，並依序遞增每個標頭。

一對多剖析的索引架構

範例索引組態看起來可能如下所示：

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

一對多剖析的索引器定義

如果功能變數名稱和數據類型一致，Blob 索引器可以在要求中沒有明確的欄位對應來推斷對應，因此對應至所提供索引組態的索引器組態可能如下所示：

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

注意

這裡不需要明確設定， submode 因為 oneToMany 是預設值。

一對多剖析的索引器輸出

由於三個內容區段，此 Markdown 檔案會在編製索引之後產生三個搜尋檔。所提供 Markdown 檔第一個內容區段所產生的搜尋檔案會包含、sections、 h1和 h2的下列值content：

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

對應搜尋索引中的一對多欄位

欄位對應會在欄位名稱與類型不相同的情況下，將來源欄位與目的地欄位建立關聯。但是，欄位對應也可以用來比對 Markdown 檔的部分，並將這些對應「提升」到搜尋檔的最上層欄位。

下列範例會說明此情節。如需一般欄位對應的詳細資訊，請參閱欄位對應 (機器翻譯)。

假設搜尋索引有下列欄位︰Edm.String 類型的 raw_content、Edm.String 類型的 h1_header、Edm.String 類型的 h2_header。若要將 Markdown 對應到所需的圖形，請使用下列字段對應：

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

索引中產生的搜尋檔如下所示：

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

使用一對一剖析模式

在一對一剖析模式中，整個 Markdown 檔會編製成單一搜尋檔索引，保留原始內容的階層和結構。當要編製索引的檔案共用通用結構時，此模式最有用，因此您可以在索引中使用這個通用結構，讓相關字段可供搜尋。

在索引器定義中，將設定 parsingMode 為 "markdown" ，並使用選擇性 markdownHeaderDepth 參數來定義區塊化的最大標題深度。如果未指定，它會預設為 h6，並擷取所有可能的標頭深度。

Markdown 會根據標頭剖析成包含下列內容的搜尋檔：

document_content：包含完整 Markdown 文字做為單一字串。此欄位可作為輸入檔的原始表示法。
sections：對象的陣列，其中包含 Markdown 檔中區段的階層表示法。每個區段都會以這個陣列中的物件表示，並以巢狀方式擷取檔的結構，其對應至標頭及其各自的內容。藉由參考路徑，即可透過欄位對應來存取欄位，例如 /sections/content。此陣列中的物件具有下列屬性：
- header_level：字串，表示 Markdown 語法中標頭的層級（h1、 h2h3等等）。此欄位有助於瞭解內容的階層和結構。
- header_name：字串，包含出現在 Markdown 檔中的標頭文字。此欄位提供區段的標籤或標題。
- content：字串，包含緊接在標頭後面，至下一個標頭的文字內容。此欄位會擷取與標頭相關聯的詳細資訊或描述。如果沒有直接在標頭下的內容，這是空字串。
- ordinal_position：整數值，表示區段在文件階層中的位置。此欄位用於排序其原始序列中的區段，因為它們出現在檔中，從序數位置 1 開始，並依序遞增每個內容區塊。
- sections：陣列，包含表示目前區段下巢狀子區段的物件。此陣列遵循與最上層 sections 數位相同的結構，允許表示多個巢狀內容層級。每個子區段物件也包含 header_level、 header_name、 content和 ordinal_position 屬性，啟用遞歸結構，代表 Markdown 內容的階層。

以下是我們用來說明針對每個剖析模式所設計的索引架構範例 Markdown。

# Section 1
Content for section 1.

## Subsection 1.1
Content for subsection 1.1.

# Section 2
Content for section 2.

一對一剖析的索引架構

如果您未使用欄位對應，索引的形狀應該會反映 Markdown 內容的形狀。假設範例 Markdown 的結構及其兩個區段和單一子區段，索引看起來應該類似下列範例：

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

一對一剖析的索引器定義

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

一對一剖析的索引器輸出

由於我們想要編製索引的 h2 Markdown 只會進入深度（“##），因此我們需要 sections 巢狀至深度 2 的字段才能符合該深度。此組態會導致索引中的下列資料：

  "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": []
    }]
  }

如您所見，序數位置會根據文件內內容的位置遞增。

也應該指出，如果內容中略過標頭層級，則產生的文件結構會反映 Markdown 內容中存在的標頭，不一定包含連續的h6巢狀區段h1。例如，當檔案從開始 h2時，最上層區段陣列中的第一個專案是 h2。

對應搜尋索引中的一對一欄位

如果您想要從檔中擷取具有自定義名稱的欄位，您可以使用欄位對應來執行此動作。使用與之前相同的 Markdown 範例，請考慮下列索引組態：

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

從剖析的 Markdown 擷取特定欄位的處理方式與 outputFieldMappings 中的文件路徑的方式類似，但路徑開頭/sections為而非 /document。因此，例如， /sections/0/content 會對應至區段數位中位置 0 的專案底下的內容。

強式使用案例的範例可能看起來像這樣：所有 Markdown 檔案在第一個、第h1h2一個的子區段標題中都有文件標題，以及最後h1一個段落下方最後一段內容的摘要。您可以使用下列欄位對應來編制該內容的索引：

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

在這裡，您只會從該檔擷取相關的部分。若要有效地使用這項功能，您打算編製索引的文件應該共用相同的階層式標頭結構。