Azure AI 검색 기술 세트의 컨텍스트 및 원본 속성을 사용하여 보강된 노드에 대한 경로 참조

아티클
03/08/2024

기술 세트 실행 중에 엔진은 인식된 엔터티 또는 번역된 텍스트와 같은 각 보강을 캡처하는 메모리 내 보강 트리를 빌드합니다. 이 문서에서는 출력을 다운스트림 기술에 전달하거나 검색 인덱스 필드에 대한 출력 필드 매핑을 지정할 수 있도록 보강 트리에서 보강 노드를 참조하는 방법을 알아봅니다.

이 문서에서는 예제를 사용하여 다양한 시나리오를 설명합니다. 전체 구문은 기술 컨텍스트 및 입력 주석 언어 언어를 참조하세요.

배경 개념

구문을 검토를 하기 전에 이 문서의 뒷부분에 제공되는 예제를 보다 잘 이해하려면 몇 가지 중요한 개념을 다시 확인하겠습니다.

용어	설명
“보강된 문서”	보강된 문서는 생성 시 기술 출력을 수집하고 문서와 관련된 모든 보강을 보유하는 메모리 내 구조입니다. 보강된 문서를 트리라고 생각하면 됩니다. 일반적으로 트리는 루트 문서 수준에서 시작하고 각각의 새로운 보강은 이전 보강에서 하위로 만들어집니다.
"노드"	보강된 문서 내에 노드("주석"이라고도 함)가 생성되고 OCR 기술의 "text" 및 "layoutText"와 같은 기술로 채워집니다. 보강된 문서는 보강과 원본 소스 필드 값 또는 원본에서 복사된 메타데이터로 채워집니다.
“컨텍스트”	전체 문서, 문서의 일부 또는 이미지로 작업하는 경우 문서에서 추출된 이미지 중 하나인 보강 범위입니다. 기본적으로 보강 컨텍스트는 `"/document"` 수준이며, 데이터 원본에 포함된 개별 문서로 범위가 지정됩니다. 기술을 실행할 때 해당 기술의 출력은 정의된 컨텍스트의 속성이 됩니다.

다양한 시나리오에 대한 경로

경로는 기술 세트의 “context” 및 “source” 속성과 인덱서의 출력 필드 매핑에 지정됩니다.

스크린샷의 예제에서는 Azure Cosmos DB 컬렉션의 항목 경로를 보여 줍니다.

context 경로는 컬력션이 /HotelId 필드에 의해 문서로 분할되기 때문에 /document/HotelId입니다.
source 경로는 기술이 번역 기술이며, 기술을 번역할 필드는 각 문서의 Description 필드이기 때문에 /document/Description입니다.

모든 경로는 /document로 시작합니다. 인덱서가 문서를 열거나 데이터 원본에서 행을 읽는 경우 인덱서 실행의 “문서 크래킹” 단계에서 보강된 문서가 만들어집니다. 처음에 보강된 문서의 유일한 노드는 루트 노드(/document)이며 다른 모든 보강이 발생하는 노드입니다.

다음 목록에는 몇 가지 일반적인 예제가 포함되어 있습니다.

/document는 루트 노드이며 Azure Storage의 전체 Blob 또는 SQL 테이블의 행을 나타냅니다.
/document/{key}는 Azure Cosmos DB 컬렉션의 문서 또는 항목에 대한 구문입니다. 여기서 {key}는 이전 예제의 /document/HotelId와 같은 실제 키입니다.
/document/content는 JSON Blob의 “content” 속성을 지정합니다.
/document/{field}는 이전 예제에서 볼 수 있는 /document/Description 필드 변환과 같이 특정 필드에 대해 수행되는 작업의 구문입니다.
/document/pages/* 또는 /document/sentences/*는 대규모 문서를 처리하기 위해 작은 청크로 나누는 경우 컨텍스트가 됩니다. “context”가 /document/pages/*인 경우 기술은 문서의 각 페이지에서 한 번 실행됩니다. 둘 이상의 페이지 또는 문장이 있을 수 있으므로 모두 catch하기 위해 /*를 추가합니다.
/document/normalized_images/*는 문서에 이미지가 포함된 경우 문서 크래킹 중에 만들어집니다. 이미지의 모든 경로는 normalized_images로 시작합니다. 문서에 여러 이미지가 포함되어 있는 경우가 많으므로 /*를 추가합니다.

이 문서의 예제는 문서 크래킹 단계의 일부로서 Azure Blob 인덱서에서 자동으로 생성한 “content” 필드를 기준으로 합니다. Blob 컨테이너에서 문서를 참조할 때는 “content” 필드가 “document”의 일부인 "/document/content"와 같은 형식을 사용합니다.

예제 1: 단순 주석 참조

Azure Blob Storage에서는 엔터티 인식을 사용하여 추출할 사용자 이름에 대한 참조가 포함된 다양한 파일이 있다고 가정합니다. 다음의 기술 정의에서 "/document/content"은 전체 문서의 텍스트 표현이며 "사람"은 사용자로 식별되는 엔터티에 대한 전체 이름의 추출입니다.

기본 컨텍스트가 "/document"이므로 사람의 목록은 이제 "/document/people"로서 참조될 수 있습니다. 특정한 경우에 "/document/people"은 인덱스의 필드에 매핑되거나 동일 기술 집합의 다른 기술에 사용될 수 있는 주석입니다.

  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "categories": [ "Person"],
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "persons",
        "targetName": "people"
      }
    ]
  }

예제 2: 문서 내에서 배열을 참조

이 예제는 동일 문서에 대해 보강 단계를 여러 번 호출하는 방법을 보여주며 이전 예제를 기반으로 빌드합니다. 이전 예제가 단일 문서에서 10명의 이름을 통해 문자열 배열을 생성했다고 가정합니다. 합리적인 다음 단계는 전체 이름에서 성을 추출하는 두 번째 보강일 수 있습니다. 10개 이름이 있으므로 이 문서에서 이 단계를 한 명당 한 번씩 10번을 호출하고자 합니다.

올바른 반복 횟수를 호출하려면 컨텍스트를 "/document/people/*"로 설정합니다. 여기서 별표("*")는 "/document/people"의 하위 항목으로 보강된 문서의 모든 노드를 나타냅니다. 이 기술은 기술 배열에서 한 번만 정의되지만, 모든 구성원이 처리될 때까지 문서 내의 각 구성원에 대해 호출됩니다.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the last name from a full name",
    "uri": "http://names.azurewebsites.net/api/GetLastName",
    "context" : "/document/people/*",
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "fullname",
        "source": "/document/people/*"
      }
    ],
    "outputs": [
      {
        "name": "lastname",
        "targetName": "last"
      }
    ]
  }

주석이 문자열의 컬렉션이나 배열인 경우 전체로서의 배열이 아닌 구체적 구성원을 대상으로 할 수 있습니다. 위의 예제에서는 컨텍스트가 나타내는 각 노드에서 "last"이라는 주석을 생성합니다. 주석군을 참조하려는 경우 구문 "/document/people/*/last"을 사용할 수 있습니다. 특정 주석을 참조하려는 경우 명시적 인덱스를 사용할 수 있습니다: 문서에서 식별된 첫 번째 사용자의 성을 참조하기 위한 "/document/people/1/last". 이 구문에서 배열은 "1 인덱싱됨"입니다.

예제 3: 배열 내에서 구성원 참조

경우에 따라 특정 기술에 전달하는 특정 형식의 모든 주석을 그룹화해야 합니다. 예제 2에서 추출된 모든 성 가운데 가장 일반적인 성을 식별하는 가상의 사용자 지정 기술을 고려합니다. 사용자 지정 기술에 성만 제공하려면 컨텍스트를 "/document"로, 입력을 "/document/people/*/lastname"로 지정합니다.

"/document/people/*/lastname"의 카디널리티는 문서의 카디널리티보다 큽니다. 이 문서에 대한 문서 노드가 하나만 있는 반면 성 노드는 10개가 있을 수 있습니다. 이 경우 시스템은 문서의 모든 요소를 포함하는 "/document/people/*/lastname"의 배열을 자동으로 만듭니다.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the most common string from an array of strings",
    "uri": "http://names.azurewebsites.net/api/MostCommonString",
    "context" : "/document",
    "inputs": [
      {
        "name": "strings",
        "source": "/document/people/*/lastname"
      }
    ],
    "outputs": [
      {
        "name": "mostcommon",
        "targetName": "common-lastname"
      }
    ]
  }

주석 경로 문제 해결을 위한 팁

기술 입력을 지정하는 데 문제가 있는 경우 이러한 팁이 진행하는 데 도움이 될 수 있습니다.

데이터에 대해 데이터 가져오기 마법사를 실행하여 마법사에서 생성하는 기술 세트 정의 및 필드 매핑을 검토합니다.
기술 세트에서 디버그 세션을 시작하여 보강된 문서의 구조를 봅니다. 기술 정의의 경로 및 기타 부분을 편집한 다음, 기술을 실행하여 변경 내용의 유효성을 검사할 수 있습니다.