Azure AI 검색에서 Markdown Blob 및 파일을 인덱싱하는 방법

Azure AI 검색 Azure Blob Storage, Azure Files 및 Microsoft OneLake의 인덱서는 Markdown 파일에 대한 markdown 구문 분석 모드를 지원합니다. Markdown 파일은 다음 두 가지 방법으로 인덱싱할 수 있습니다.

• Markdown 파일당 여러 검색 문서를 생성하는 일대다 구문 분석 모드입니다.
• 일대일 구문 분석 모드로 Markdown 파일당 하나의 검색 문서를 만듭니다.

필수 구성 요소

• 지원되는 데이터 원본: Azure Blob Storage, Azure File Storage, Microsoft OneLake.

  OneLake의 경우 OneLake 인덱서의 모든 요구 사항을 충족하는지 확인합니다.

  blob 인덱서 및 파일 인덱서(미리 보기)용 Azure Storage는 핫 및 쿨 액세스 계층을 지원하는 표준 성능(범용 v2) 인스턴스입니다.

Markdown 구문 분석 모드 매개 변수

구문 분석 모드 매개 변수는 인덱서 정의에서 인덱서를 만들거나 업데이트할 때 지정됩니다.

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

Blob 인덱서는 검색 문서의 출력 구조를 결정하는 매개 변수를 제공합니다 submode . Markdown 구문 분석 모드는 다음과 같은 하위 노드 옵션을 제공합니다.

oneToMany 서브모드의 경우, 하나의 Blob에서 다수의 검색 문서를 생성하기 위한 인덱싱을 검토하여 동일한 Blob에서 생성된 여러 검색 문서의 문서 키를 어떻게 구별하는지 이해해야 합니다.

이후 섹션에서는 각 하위 노드에 대해 자세히 설명합니다. 인덱서 클라이언트 및 개념에 익숙하지 않은 경우 검색 인덱서 만들기를 참조하세요. 여기에서 반복되지 않는 기본 Blob 인덱서 구성의 세부 정보도 잘 알고 있어야 합니다.

선택적 Markdown 구문 분석 매개 변수

매개변수는 대소문자를 구분합니다.

인덱서가 만들어지면 이 설정을 변경할 수 있습니다. 그러나 결과 검색 문서의 구조는 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가 h3로 설정되면, 문자열 필드 h1, h2, 및 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=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" }
  },
}

일대다 파싱을 위한 인덱서 출력

이 Markdown 파일은 세 개의 콘텐츠 섹션으로 인해 인덱싱 후 3개의 검색 문서를 생성합니다. 제공된 Markdown 문서의 첫 번째 콘텐츠 섹션에서 생성된 검색 문서에는 다음과 같은 값이 contentsectionsh1포함됩니다.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
  }
}

검색 인덱스에서 일대다 필드 매핑

필드 매핑은 필드 이름과 형식이 동일하지 않은 경우 원본 필드를 대상 필드와 연결합니다. 그러나 필드 매핑을 사용하여 Markdown 문서의 일부를 일치시키고 검색 문서의 최상위 필드로 "리프트"할 수도 있습니다.

다음 예제에서는 이 시나리오를 보여 줍니다. 일반적으로 필드 매핑에 대한 자세한 내용은 필드 매핑을 참조하세요.

raw_content 형식 Edm.String, h1_header 형식 Edm.String, 및 h2_header 형식 Edm.String의 필드를 가진 검색 인덱스라고 가정합니다. 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, h2, h3등)을 나타내는 문자열입니다. 이 필드는 콘텐츠의 계층 구조 및 구조화를 이해하는 데 도움이 됩니다.

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

일대일 구문 분석용 인덱서 정의

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

일대일 구문 분석을 위한 인덱서 출력

인덱싱하려는 Markdown은 h2 깊이 "##"까지만 가기 때문에, 이를 일치시키기 위해 깊이 2로 중첩된 sections 필드가 필요합니다. 이 구성은 인덱스에서 다음 데이터를 생성합니다.

  "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 콘텐츠에 있는 헤더를 반영하며 반드시 중첩된 섹션 h1h6을 포함할 필요는 없습니다. 예를 들어 문서가 시작될 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로 시작합니다. 예를 들어 /sections/0/content 섹션 배열의 위치 0에 있는 항목 아래의 콘텐츠에 매핑됩니다.

강력한 사용 사례의 예는 다음과 같습니다. 모든 Markdown 파일에는 첫 번째의 문서 제목, 첫 h1번째 h2의 하위 섹션 제목 및 최종 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" },
]

여기서는 해당 문서에서 관련 부분만 추출합니다. 이 기능을 가장 효과적으로 사용하려면 인덱싱하려는 문서가 동일한 계층적 헤더 구조를 공유해야 합니다.

인덱스의 결과 검색 문서는 다음과 같습니다.

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

Markdown 재색인에서 오래된 문서 처리

일대다 구문 분석 모드를 사용하는 경우 수정된 Markdown 파일을 다시 인덱싱하면 섹션이 제거될 경우 문서가 부실하거나 중복될 수 있습니다. 이 동작은 일대다 모드에 특정하며 일대일 구문 분석에 적용되지 않습니다.

동작 개요

일대다 구문 분석 모드

모드에서 oneToMany 각 Markdown 섹션(헤더 기반)은 별도의 검색 문서로 인덱싱됩니다. 파일이 다시 인덱싱되는 경우:

• 자동 삭제 없음: 인덱서는 기존 문서를 새 문서로 덮어쓰지만 업데이트된 파일의 콘텐츠에 더 이상 해당하지 않는 문서는 삭제하지 않습니다.
• 중복 가능성: 이 문제는 특히 인덱싱 실행 사이에 삽입된 것보다 더 많은 섹션이 삭제되는 경우에만 발생합니다. 이러한 경우 이전 버전의 남은 문서가 인덱스에 남아 있으므로 원본 파일의 현재 상태를 더 이상 반영하지 않는 부실 항목이 발생합니다.

일대일 구문 분석 모드

모드에서 oneToOne 전체 Markdown 파일은 단일 검색 문서로 인덱싱됩니다. 파일이 다시 인덱싱되는 경우:

• 덮어쓰기 동작: 기존 문서가 완전히 새 버전으로 대체됩니다.
• 부실 섹션 없음: 파일이 다시 인덱싱되면 기존 문서가 업데이트된 버전으로 대체되고 제거된 콘텐츠는 더 이상 포함되지 않습니다. 유일한 예외는 파일 경로 또는 Blob URI가 변경되어 새 문서가 이전 문서와 함께 만들어질 수 있는 경우입니다.

해결 방법 옵션

인덱스가 Markdown 파일의 현재 상태를 반영하도록 하려면 다음 방법 중 하나를 고려합니다.

옵션 1. 메타데이터를 사용하여 일시 삭제

이 메서드는 일시 삭제를 사용하여 특정 Blob과 연결된 문서를 삭제합니다. 자세한 내용은 Azure AI 검색 Azure Storage 인덱서를 사용하여 검색 변경 및 삭제를 참조하세요.

단계:

1. 메타데이터 필드를 설정하여 Blob을 삭제된 것으로 표시합니다.
2. 인덱서가 실행되도록 합니다. 해당 Blob과 연결된 인덱스의 모든 문서를 삭제합니다.
3. 일시 삭제 표식을 제거하고 파일을 다시 인덱싱합니다.

옵션 2. 삭제 API 사용

수정된 Markdown 파일을 다시 인덱싱하기 전에 삭제 API를 사용하여 해당 파일과 연결된 기존 문서를 명시적으로 삭제합니다. 다음 중 하나를 수행할 수 있습니다.

• 삭제할 인덱스의 중복 항목을 식별하여 개별 부실 문서를 수동으로 식별합니다. 이는 작고 잘 이해할 수 있는 변경에 적합할 수 있지만 시간이 많이 걸릴 수 있습니다.
• (권장) 다시 인덱싱하기 전에 동일한 부모 파일에서 생성된 모든 문서를 제거하여 불일치를 방지합니다.

단계:

1. 파일과 연결된 문서의 ID를 식별합니다. 다음 예제와 같은 쿼리를 사용하여 특정 파일에 연결된 모든 문서에 대한 문서 키 ID(예: id 또는 chunk_id)를 검색합니다. 인덱스 내에서 파일 경로나 Blob URI에 매핑되는 적절한 필드로 metadata_storage_path를 바꾸세요. 이 필드는 키 값이어야 합니다.

   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. 식별된 키를 사용하여 문서에 대한 삭제 요청을 실행합니다.

   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. 업데이트된 파일을 다시 인덱싱합니다.

다음 단계

• Blob 인덱서 구성
• 필드 매핑 정의
• 인덱서 개요
• Blob 인덱서로 CSV Blob을 인덱싱하는 방법
• 튜토리얼: Azure Blob Storage에서 Markdown 데이터 검색