Azure AI 검색에서 기술 세트 만들기

  • 아티클

indexer stages

기술 세트는 이미지 또는 비정형 텍스트가 포함된 문서에서 텍스트 콘텐츠 및 구조를 생성하는 작업을 정의합니다. 이미지에 대한 OCR, 개체 인식이 되었으나 특정할 수 없는 텍스트 및 텍스트 번역을 예로 들 수 있습니다. 기술 세트는 외부 데이터 원본에서 텍스트 및 이미지를 추출한 후 필드 매핑이 처리된 이후에 실행됩니다.

이 문서에서는 REST API를 사용하여 기술 세트를 만드는 방법에 대해 설명하지만 다른 프로그래밍 언어에도 동일한 개념과 단계가 적용됩니다.

기술 세트 정의에 대한 규칙은 다음과 같습니다.

  • 기술 세트 컬렉션 내의 고유한 이름. 기술 세트는 모든 인덱서에서 사용할 수 있는 최상위 리소스입니다.
  • 하나 이상의 기술. 3~5개의 기술이 일반적입니다. 최댓값은 30입니다.
  • 기술 세트는 동일한 유형의 기술(예: 여러 Shaper 기술)을 반복할 수 있습니다.
  • 기술 세트는 연결된 작업, 루핑 및 분기를 지원합니다.

인덱서는 기술 세트 실행을 주도합니다. 기술 세트를 테스트하기 전에 인덱서, 데이터 원본 및 인덱스가 필요합니다.

팁

보강 캐싱을 사용하여 이미 처리한 콘텐츠를 다시 사용하고 개발 비용을 절감할 수 있습니다.

기술 세트 정의 추가

기본 구조로 시작합니다. 기술 세트 REST API 만들기에서 요청 본문은 JSON으로 작성되며 다음 섹션이 있습니다.

{
   "name":"skillset-template",
   "description":"A description makes the skillset self-documenting (comments aren't allowed in JSON itself)",
   "skills":[
       
   ],
   "cognitiveServices":{
      "@odata.type":"#Microsoft.Azure.Search.CognitiveServicesByKey",
      "description":"An Azure AI services resource in the same region as Azure AI Search",
      "key":"<Your-Cognitive-Services-Multiservice-Key>"
   },
   "knowledgeStore":{
      "storageConnectionString":"<Your-Azure-Storage-Connection-String>",
      "projections":[
         {
            "tables":[ ],
            "objects":[ ],
            "files":[ ]
         }
      ]
    },
    "encryptionKey":{ }
}

기술 세트는 이름과 설명 뒤에 네 가지 기본 속성이 있습니다.

  • skills 배열, 정렬되지 않은 기술 컬렉션. 기술은 실용적(예: 텍스트 분할), 변형(Azure AI 서비스의 AI 기반) 또는 사용자가 제공하는 사용자 지정 기술이 될 수 있습니다. 다음 섹션에는 기술 배열의 예가 나와 있습니다.

  • cognitiveServices는 Azure AI 서비스 API를 호출하는 청구 가능 기술에 사용됩니다. 청구 가능한 기술 또는 사용자 지정 엔터티 조회를 사용하지 않는 경우 이 섹션을 제거합니다. 사용하는 경우 리소스를 연결합니다.

  • knowledgeStore(선택 사항)는 Azure Storage의 테이블, Blob, 파일에 기술 세트 출력을 프로젝션하기 위한 Azure Storage 계정과 설정을 지정합니다. 필요하지 않은 경우 이 섹션을 제거하고, 그렇지 않은 경우 지식 저장소를 지정합니다.

  • encryptionKey(선택 사항)는 기술 세트 정의에서 중요한 콘텐츠(설명, 연결 문자열, 키)를 암호화하는 데 사용되는 Azure Key Vault 및 고객 관리형 키를 지정합니다. 고객 관리형 암호화를 사용하지 않는 경우 이 속성을 제거합니다.

기술 추가

기술 세트 정의 내에서 기술 배열은 실행할 기술을 지정합니다. 3~5개의 기술이 일반적이지만 서비스 제한에 따라 필요한 만큼 기술을 추가할 수 있습니다.

보강 파이프라인의 종료 결과는 검색 인덱스 또는 지식 저장소 중 하나의 텍스트 콘텐츠입니다. 이러한 이유로 대부분의 기술은 이미지(OCR 텍스트, 캡션, 태그)에서 텍스트를 만들거나 기존 텍스트를 분석하여 새 정보(엔터티, 핵심 구, 감정)를 만듭니다. 독립적으로 작동하는 기술은 병렬로 처리됩니다. 서로 의존하는 한 기술(예: 핵심 구)의 출력을 다른 기술은 기술(예: 텍스트 번역)의 입력으로 지정합니다. 검색 서비스는 기술 실행 순서와 실행 환경을 결정합니다.

모든 기술에는 형식, 컨텍스트, 입력 및 출력이 있습니다. 기술에는 필요에 따라 이름과 설명이 있을 수 있습니다. 다음 예제에서는 기본 구조를 비교할 수 있도록 관련 없는 두 가지 기본 제공 기술을 보여줍니다.

"skills": [
    {
        "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
        "name": "#1",
        "description": "This skill detects organizations in the source content",
        "context": "/document",
        "categories": [
            "Organization"
        ],
        "inputs": [
            {
                "name": "text",
                "source": "/document/content"
            }
        ],
        "outputs": [
            {
                "name": "organizations",
                "targetName": "orgs"
            }
        ]
    },
    {
        "name": "#2",
        "description": "This skill detects corporate logos in the source files",
        "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
        "context": "/document/normalized_images/*",
        "visualFeatures": [
            "brands"
        ],
        "inputs": [
            {
                "name": "image",
                "source": "/document/normalized_images/*"
            }
        ],
        "outputs": [
            {
                "name": "brands"
            }
        ]
    }
]

각 기술은 입력 값과 필요한 매개 변수 측면에서 고유합니다. 기술 참고 문서에서는 지정된 기술에 대한 매개 변수와 속성을 모두 설명합니다. 차이점이 있지만 대부분의 기술은 공통된 세트를 공유하고 패턴이 비슷합니다.

참고 항목

조건부 기술을 사용하여 식을 만들면 루프와 분기를 사용하여 복잡한 기술 세트를 빌드할 수 있습니다. 구문은 몇 가지 수정 사항이 포함된 JSON 포인터 경로 표기를 기반으로 보강 트리의 노드를 식별합니다. "/"는 트리에서 더 낮은 수준으로 트래버스하고, "*"는 컨텍스트에서 for-each 연산자 역할을 합니다. 이 문서의 다양한 예제에서 구문을 보여 줍니다.

기술 컨텍스트 설정

각 기술에는 작업이 수행되는 수준을 결정하는 컨텍스트 속성이 있습니다. “컨텍스트” 속성이 명시적으로 설정되지 않은 경우 기본값은 "/document"이며, 여기서 컨텍스트는 전체 문서입니다(기술은 문서당 한 번 호출됨).

"skills":[
  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "context": "/document",
    "inputs": [],
    "outputs": []
  },
  {
      "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
      "context": "/document/normalized_images/*",
      "visualFeatures": [],
      "inputs": [],
      "outputs": []
  }
]

컨텍스트는 일반적으로 다음 예제 중 하나로 설정됩니다.

컨텍스트 예제 설명
“context”: “/document” (기본값) 입력 및 출력이 문서 수준에 있습니다.
“context”: “/document/pages/*” 감정 분석과 같은 일부 기술은 작은 텍스트 청크보다 더 잘 수행됩니다. 큰 콘텐츠 필드를 페이지 또는 문장으로 분할하는 경우 컨텍스트는 각 구성 요소 부분에 걸쳐 있어야 합니다.
“context”: “/document/normalized_images/*” 이미지 콘텐츠의 경우 입력 및 출력은 부모 문서의 이미지당 1개입니다.

컨텍스트는 보강 트리에서 출력이 생성되는 위치도 결정합니다. 예를 들어 엔터티 인식 기술은 orgs로 캡처된 "organizations"라는 속성을 반환합니다. 컨텍스트가 "/document"이면 “organizations” 노드가 "/document"의 자식으로 추가됩니다. 그런 다음 다운스트림 기술에서 이 노드를 참조하려는 경우 경로는 "/document/orgs"입니다.

입력 정의

보강된 문서에서 읽고 쓰는 기술. 기술 입력은 들어오는 데이터의 원본을 지정합니다. 보강된 문서의 루트 노드인 경우가 많습니다. Blob의 경우 일반적인 기술 입력은 문서의 콘텐츠 속성입니다.

각 기술에 대한 기술 참조 설명서에서는 사용할 수 있는 입력에 대해 설명합니다. 각 입력에는 특정 입력을 식별하는 “이름”과 보강된 문서의 데이터의 위치를 지정하는 “원본”이 있습니다. 다음 예제는 엔터티 인식 기술입니다.

"inputs": [
    {
        "name": "text", 
        "source": "/document/content"
    },
    {
        "name": "languageCode", 
        "source": "/document/language"
    }
]

  • 기술에는 여러 입력이 있을 수 있습니다. “name”은 특정 입력입니다. 엔터티 인식의 경우 특정 입력은 “text” 및 “languageCode”입니다.

  • “source” 속성은 처리할 콘텐츠를 제공하는 필드 또는 행을 지정합니다. 텍스트 기반 기술의 경우 원본은 텍스트를 제공하는 문서 또는 행의 필드입니다. 이미지 기반 기술의 경우 입력을 제공하는 노드는 정규화된 이미지입니다.

    원본 예 설명
    “source”: “/document” 표 형식 데이터 세트의 경우 문서는 행에 해당합니다.
    “source”: “/document/content” Blob의 경우 원본은 일반적으로 Blob의 콘텐츠 속성입니다.
    “source”: “/document/some-named-field” 엔터티 인식 또는 핵심 구 추출과 같은 텍스트 기반 기술의 경우 원본은 “설명” 또는 “요약”과 같이 분석할 수 있는 충분한 텍스트가 포함된 필드여야 합니다.
    "source": "/document/normalized_images/*" 이미지 콘텐츠의 경우 원본은 문서 크래킹 중에 정규화된 이미지입니다.

기술이 배열을 반복하는 경우 컨텍스트와 입력 원본이 모두 /*를 올바른 위치에 포함해야 합니다.

출력 정의

각 기술은 기술 세트에서 이름으로 참조되는 특정 종류의 출력을 내보내도록 설계되었습니다. 기술 출력에는 “name”과 선택적 “targetName”이 있습니다.

각 기술에 대한 기술 참조 설명서에서는 생성할 수 있는 출력을 설명합니다. 다음 예제는 엔터티 인식 기술입니다.

"outputs": [
    {
        "name": "persons", 
        "targetName": "people"
    },
    {
        "name": "organizations", 
        "targetName": "orgs"
    },
    {
        "name": "locations", 
        "targetName": "places"
    }
]

  • 기술에는 여러 출력이 있을 수 있습니다. “name”은 특정 출력을 식별합니다. 예를 들어 엔터티 인식의 경우 출력은 “persons”, “locations”, “organizations”일 수 있습니다.

  • “targetName”은 보강된 문서에 이 노드의 이름을 지정합니다. 기술 출력의 이름이 같은 경우에 유용합니다. 동일한 출력을 반환하는 기술이 다수 있는 경우 "targetName"을 사용하여 보강 노드 경로에서 이름을 명확하게 밝힙니다. 대상 이름을 지정하지 않으면 name 속성이 둘 다에 사용됩니다.

일부 상황에서는 별도로 배열의 각 요소를 참조하기 위해 호출합니다. 예를 들어, "/document/orgs"의 각 요소를 다른 기술에 개별적으로 전달하려고 한다고 가정해 보겠습니다. 이렇게 하려면 "/document/orgs/*" 경로에 별표를 추가합니다.

기술 출력은 보강된 문서에 보강 트리의 새 노드로 기록됩니다. 감정 점수 또는 언어 코드와 같은 간단한 값일 수 있습니다. 조직, 사람 또는 위치 목록과 같은 컬렉션일 수도 있습니다. 쉐이퍼 기술의 경우처럼 기술 출력이 복잡한 구조일 수도 있습니다. 기술의 입력은 셰이프의 컴퍼지션을 결정하지만 출력은 명명된 개체로, 검색 인덱스, 지식 저장소 프로젝션 또는 이름으로 다른 기술에서 참조할 수 있습니다.

사용자 지정 기술 추가

이 섹션에는 사용자 지정 기술의 예가 포함되어 있습니다. URI는 Azure 함수를 가리키며, 사용자가 제공하는 모델 또는 변환을 호출합니다. 자세한 내용은 사용자 지정 인터페이스 정의를 참조하세요.

사용자 지정 기술은 파이프라인 외부에 있는 코드를 실행하지만 기술 배열에서는 또 다른 기술에 불과합니다. 기본 제공 기술처럼 형식과 컨텍스트, 입력, 출력을 포함합니다. 또한 기본 제공 기술과 마찬가지로 보강 트리를 읽고 씁니다. 별표를 사용하여 "컨텍스트" 필드가 "/document/orgs/*"로 설정되는 것은 보강 단계가 "/document/orgs"에서 각 조직에 대해 호출된다는 의미입니다.

이 예제의 회사 설명과 같은 출력은 식별된 각 조직에 대해 생성됩니다. 다운스트림 단계에서 노드를 언급할 때(예: 핵심 구문 추출) 그렇게 하려면 "/document/orgs/*/companyDescription" 경로를 사용합니다.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "This skill calls an Azure function, which in turn calls custom code",
  "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/InvokeCode?code=foo",
  "httpHeaders": {
      "Ocp-Apim-Subscription-Key": "foobar"
  },
  "context": "/document/orgs/*",
  "inputs": [
    {
      "name": "query",
      "source": "/document/orgs/*"
    }
  ],
  "outputs": [
    {
      "name": "description",
      "targetName": "companyDescription"
    }
  ]
}

대상에 출력 보내기

기술 출력은 필요에 따라 재사용 목적으로 캐시할 수 있지만 일반적으로 일시적이며, 기술 실행이 진행되는 동안에만 존재합니다.

  • 검색 인덱스의 필드에 출력을 보내려면 인덱서에서 출력 필드 매핑을 만듭니다.

  • 출력을 지식 저장소로 보내려면 프로젝션을 만듭니다.

  • 다운스트림 기술에 출력을 보내려면 다운스트림 기술의 입력 원본 속성에서 노드 이름(예: "/document/organization")으로 출력을 참조합니다. 예제는 주석 참조를 참조하세요.

첫 번째 기술 세트 팁

  • 데이터 가져오기 마법사를 사용해 보세요.

    마법사는 처음에는 어려운 수 있는 여러 단계를 자동화합니다. 필드 매핑 및 출력 필드 매핑을 포함하여 기술 세트, 인덱스 및 인덱서가 정의됩니다. 또한 지식 저장소에서 프로젝션을 사용하는 경우 프로젝션을 정의합니다. OCR 또는 이미지 분석과 같은 일부 기술의 경우 마법사는 문서 크래킹 중에 구분된 이미지 및 텍스트 콘텐츠를 병합하는 유틸리티 기술을 추가합니다.

    마법사가 실행된 후 Azure Portal에서 각 개체를 열어 JSON 정의를 볼 수 있습니다.

  • 디버그 세션을 사용하여 대상 문서에 대한 기술 세트 실행을 호출하고 기술 세트가 만드는 보강된 문서를 검사합니다. 입력 및 출력 설정 및 값을 보고 수정할 수 있습니다. 이 자습서를 시작하는 것이 좋습니다. 자습서: 디버그 세션을 사용하여 기술 세트 디버그.

다음 단계

컨텍스트 및 입력 원본 필드는 보강 트리에 있는 노드의 경로입니다. 다음 단계로, 보강 트리에서 노드에 대한 경로 구문에 대해 자세히 알아봅니다.

기술 세트의 주석 참조