Azure AI Search에서 Markdown Blob 및 파일 인덱싱

아티클
11/20/2024

참고 항목

이 기능은 현재 공개 미리 보기로 제공됩니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며 프로덕션 워크로드에는 사용하지 않는 것이 좋습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 Microsoft Azure Preview에 대한 추가 사용 약관을 참조하세요.

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

일대다 구문 분석 모드, Markdown 파일당 여러 검색 문서 만들기
일대일 구문 분석 모드, Markdown 파일당 하나의 검색 문서 만들기

팁

자습서: 이 문서를 검토한 후 Azure Blob Storage 에서 Markdown 데이터를 검색합니다.

필수 조건

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

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

Blob 인덱서 및 파일 인덱서 용 Azure Storage는 핫 및 쿨 액세스 계층을 지원하는 표준 성능(범용 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 파일의 콘텐츠(비헤이더) 섹션을 나타냅니다. 일대일 구문 분석을 원하지 않는 한 하위 노드를 생략할 수 있습니다.
`markdown`	`oneToOne`	Blob 당 하나	Markdown 파일의 특정 헤더에 매핑된 섹션을 사용하여 Markdown을 하나의 검색 문서로 구문 분석합니다.

하위 노드의 경우 oneToMany Blob 인덱싱을 검토 하여 여러 검색 문서를 생성하여 Blob 인덱서가 동일한 Blob에서 생성된 여러 검색 문서에 대해 문서 키의 명확성을 처리하는 방법을 이해해야 합니다.

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

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

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

매개 변수 이름	허용되는 값	설명
`markdownHeaderDepth`	`h1`, `h2`, `h3`, `h4`, `h5h6(default)`	이 매개 변수는 구문 분석 시 고려되는 가장 깊은 머리글 수준을 결정하여 문서 구조를 유연하게 처리할 `h1`수 있도록 합니다(예: 설정된 경우 `markdownHeaderDepth` 파서는 "#"로 시작하는 최상위 머리글만 인식하고 모든 하위 수준 머리글은 일반 텍스트로 처리됨). 지정하지 않으면 기본값인 `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 문자열 필드 h1h2및 h3.h3 이러한 필드는 인덱스에 이 구조를 미러링하거나 형식/sections/h1sections/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 파일은 세 개의 콘텐츠 섹션으로 인해 인덱싱 후 3개의 검색 문서를 생성합니다. 제공된 Markdown 문서의 첫 번째 콘텐츠 섹션에서 생성된 검색 문서에는 다음과 같은 값이 sectionsh1h2포함됩니다.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 문서가 단일 검색 문서로 인덱싱되어 원래 콘텐츠의 계층 구조와 구조를 유지합니다. 이 모드는 인덱싱할 파일이 공통 구조를 공유하는 경우에 가장 유용하므로 인덱스에서 이 공통 구조를 사용하여 관련 필드를 검색할 수 있도록 할 수 있습니다.

인덱서 정의 내에서 선택적 markdownHeaderDepth 매개 변수를 "markdown" 설정하고 parsingMode 사용하여 청크의 최대 제목 깊이를 정의합니다. 지정하지 않으면 기본값으로 설정 h6되며 가능한 모든 헤더 깊이를 캡처합니다.

Markdown은 헤더를 기반으로 다음 콘텐츠를 포함하는 검색 문서로 구문 분석됩니다.

document_content: 전체 Markdown 텍스트를 단일 문자열로 포함합니다. 이 필드는 입력 문서의 원시 표현으로 사용됩니다.
sections: Markdown 문서 내 섹션의 계층적 표현을 포함하는 개체의 배열입니다. 각 섹션은 이 배열 내의 개체로 표시되며 머리글 및 해당 콘텐츠에 해당하는 중첩된 방식으로 문서의 구조를 캡처합니다. 예를 들어 /sections/content경로를 참조하여 필드 매핑을 통해 필드에 액세스할 수 있습니다. 이 배열의 개체에는 다음과 같은 속성이 있습니다.
- header_level: Markdown 구문의 헤더 수준(h1, h2, h3등)을 나타내는 문자열입니다. 이 필드는 콘텐츠의 계층 구조 및 구조화를 이해하는 데 도움이 됩니다.
- header_name: Markdown 문서에 나타나는 머리글 텍스트를 포함하는 문자열입니다. 이 필드는 섹션의 레이블 또는 제목을 제공합니다.
- content: 다음 머리글까지 머리글 바로 뒤에 오는 텍스트 콘텐츠를 포함하는 문자열입니다. 이 필드는 헤더와 연결된 자세한 정보 또는 설명을 캡처합니다. 헤더 바로 아래에 콘텐츠가 없으면 빈 문자열입니다.
- ordinal_position: 문서 계층 구조 내의 구역 위치를 나타내는 정수 값입니다. 이 필드는 서수 위치 1부터 시작하여 각 콘텐츠 블록에 대해 순차적으로 증가하여 문서에 나타나는 대로 원래 시퀀스의 섹션 순서를 지정하는 데 사용됩니다.
- sections: 현재 섹션 아래에 중첩된 하위 섹션을 나타내는 개체를 포함하는 배열입니다. 이 배열은 최상위 sections 배열과 동일한 구조를 따르며 중첩된 콘텐츠의 여러 수준을 표시할 수 있습니다. 각 하위 섹션 개체에는 Markdown 콘텐츠의 계층 및 계층 구조를 나타내는 재귀 구조를 사용하도록 설정하는 , header_namecontentordinal_position 및 속성도 포함header_level됩니다.

다음은 각 구문 분석 모드를 중심으로 설계된 인덱스 스키마를 설명하는 데 사용하는 샘플 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",
    }
  }
}

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

인덱싱하려는 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 콘텐츠에 있는 머리글을 반영하며 연속적으로 중첩된 섹션 h1 h6 을 반드시 포함하지는 않습니다. 예를 들어 문서가 시작될 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에서 특정 필드 추출은 경로가 대신 /document시작된다는 점을 제외하고 문서 경로가 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."
}

참고 항목

이러한 예제에서는 필드 매핑을 사용하거나 사용하지 않고 이러한 구문 분석 모드를 완전히 사용하는 방법을 지정하지만 필요에 맞는 경우 한 시나리오에서 둘 다 활용할 수 있습니다.

다음을 통해 공유

Azure AI Search에서 Markdown Blob 및 파일 인덱싱

필수 조건

Markdown 구문 분석 모드 매개 변수

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

지원되는 Markdown 요소

Markdown 콘텐츠 샘플

일대다 구문 분석 모드 사용

일대다 구문 분석의 인덱스 스키마

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

일대다 구문 분석용 인덱서 출력

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

일대일 구문 분석 모드 사용

일대일 구문 분석을 위한 인덱스 스키마

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

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

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

다음 단계

피드백

추가 리소스