지식 저장소에서 프로젝션 정의
프로젝션은 AI 보강 콘텐츠가 Azure Storage에 저장되는 위치를 결정하는 지식 저장소 정의의 구성 요소입니다. 프로젝션은 콘텐츠를 포함하는 데이터 구조의 형식, 수량 및 구성을 결정합니다.
이 문서에서는 각 프로젝션 유형에 대한 구문을 알아봅니다.
프로젝션은 기술 세트의 "knowledgeStore" 속성 아래에 정의되어 있습니다.
"knowledgeStore" : {
"storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
"projections": [
{
"tables": [ ],
"objects": [ ],
"files": [ ]
}
]
}
시작하기 전에 더 많은 배경 지식이 필요한 경우 이 확인 목록에서 팁과 워크플로를 검토하세요.
팁
프로젝션을 개발할 때 프로젝션 정의를 편집하는 동안 기존 보강을 다시 사용할 수 있도록 보강 캐싱(미리 보기)을 사용하도록 설정합니다. 보강 캐싱은 미리 보기 기능이므로 인덱서 요청 시 미리 보기 REST API(api-version=2020-06-30-preview 이상)를 사용해야 합니다. 캐싱이 없으면 프로젝션을 간단하게 편집하면 보강된 콘텐츠가 완전히 다시 처리됩니다. 보강을 캐싱하면 기술 세트 처리 요금이 발생하지 않고 프로젝션을 반복할 수 있습니다.
요구 사항
모든 프로젝션에는 원본 및 대상 속성이 있습니다. 원본은 항상 기술 세트 실행 중에 만들어진 보강 트리의 내부 콘텐츠입니다. 대상은 Azure Storage에서 만들어지고 채워지는 외부 개체의 이름 및 형식입니다.
이진 이미지만 허용하는 파일 프로젝션을 제외하고 원본은 다음과 같아야 합니다.
- 유효한 JSON
- 보강 트리의 노드 경로(예:
"source": "/document/objectprojection")
노드가 단일 필드로 확인될 수 있지만 더 일반적인 표현은 복잡한 셰이프에 대한 참조입니다. 복잡한 셰이프는 셰이퍼 기술 또는 인라인 셰이핑 정의 중 하나인 셰이핑 방법론을 통해 생성되지만 일반적으로 쉐이퍼 기술입니다. 셰이프의 필드 또는 요소는 컨테이너 및 테이블의 필드를 결정합니다.
셰이퍼 기술은 JSON을 출력하기 때문에 선호됩니다. 대부분의 기술은 자체적으로 유효한 JSON을 출력하지 않습니다. 대부분의 경우 셰이퍼 기술로 만든 동일한 데이터 셰이프를 테이블 및 개체 프로젝션 모두에서 동일하게 사용할 수 있습니다.
원본 입력 요구 사항이 지정된 경우, 특히 테이블을 사용하는 경우 데이터를 셰이프하는 방법을 아는 것이 프로젝션 정의에 대한 실질적인 요구 사항이 됩니다.
테이블 프로젝션 정의
테이블 프로젝션은 Power BI를 사용한 분석 또는 데이터 프레임을 사용하는 워크로드와 같이 데이터 탐색을 호출하는 시나리오에 사용하는 것이 좋습니다. 프로젝션 배열의 테이블 섹션은 프로젝트하려는 테이블의 목록입니다.
테이블 프로젝션을 정의하려면 프로젝션 속성에서 tables 배열을 사용합니다. 테이블 프로젝션에는 다음과 같은 세 가지 필수 속성이 있습니다.
| 속성 | 설명 |
|---|---|
| tableName | Azure Table Storage에서 만든 새 테이블의 이름을 결정합니다. |
| generatedKeyName | 각 행을 고유하게 식별하는 키의 열 이름입니다. 값은 시스템에서 생성됩니다. 이 속성을 생략하면 테이블 이름과 ‘키’를 명명 규칙으로 사용하는 열이 자동으로 만들어집니다. |
| source | 보강 트리의 노드에 대한 경로입니다. 노드는 테이블에서 생성되는 열을 결정하는 복잡한 셰이프에 대한 참조여야 합니다. |
테이블 프로젝션에서 "원본"은 일반적으로 테이블 모양을 정의하는 쉐이퍼 기술의 출력입니다. 테이블에는 행과 열이 있으며 셰이핑은 행과 열을 지정하는 메커니즘입니다. 쉐이퍼 기술이나 인라인 도형을 사용할 수 있습니다. 쉐이퍼 기술은 유효한 JSON을 생성하지만 원본은 유효한 JSON인 경우 모든 기술의 출력일 수 있습니다.
참고 항목
테이블 프로젝션은 Azure Storage에서 적용하는 스토리지 제한에 따릅니다. 엔터티 크기는 1MB를 초과할 수 없으며 단일 속성은 64KB를 초과할 수 없습니다. 이러한 제약 조건으로 인해 테이블은 많은 수의 작은 엔터티를 저장하는 데 좋은 솔루션이 됩니다.
단일 테이블 예제
테이블의 스키마는 부분적으로 프로젝션(테이블 이름 및 키)과 테이블의 모양(열)을 제공하는 소스에 의해 지정됩니다. 이 예제에서는 정의의 세부 정보에 집중할 수 있도록 하나의 테이블만 보여줍니다.
"projections" : [
{
"tables": [
{ "tableName": "Hotels", "generatedKeyName": "HotelId", "source": "/document/tableprojection" }
]
}
]
열은 "원본"에서 파생됩니다. HotelId, HotelName, Category 및 Description이 포함된 다음 데이터 셰이프는 테이블에 해당 열을 만듭니다.
{
"@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
"name": "#3",
"description": null,
"context": "/document",
"inputs": [
{
"name": "HotelId",
"source": "/document/HotelId"
},
{
"name": "HotelName",
"source": "/document/HotelName"
},
{
"name": "Category",
"source": "/document/Category"
},
{
"name": "Description",
"source": "/document/Description"
},
],
"outputs": [
{
"name": "output",
"targetName": "tableprojection"
}
]
}
여러 테이블(조각화) 예제
테이블 프로젝션의 일반적인 패턴은 동일한 프로젝션 그룹의 모든 테이블에 대해 테이블 간 관계를 지원하기 위해 시스템 생성 partitionKey 및 rowKey 열이 만들어지는 여러 관련 테이블을 갖는 것입니다.
관련 데이터를 집계하는 방식을 제어하려는 경우 여러 테이블을 만드는 것이 유용할 수 있습니다. 보강된 콘텐츠에 관련이 없거나 독립적인 구성 요소가 있는 경우(예: 문서에서 추출된 키워드가 동일한 문서에서 인식되는 엔터티와 관련이 없을 수 있음) 해당 필드를 인접 테이블로 분할할 수 있습니다.
여러 테이블로 프로젝션하는 경우, 자식 노드가 동일한 그룹 내에 있는 다른 테이블의 원본이 아니면 전체 셰이프가 각 테이블에 프로젝션됩니다. 기존 프로젝션의 자식인 원본 경로를 사용하여 프로젝션을 추가하면 자식 노드가 부모 노드에서 분리되어 새로운 관련 테이블로 프로젝션됩니다. 이 기법을 사용하면 모든 프로젝션의 원본이 될 수 있는 단일 노드를 쉐이퍼 기술에 정의할 수 있습니다.
여러 테이블의 패턴은 다음으로 구성됩니다.
- 부모 또는 주 테이블인 하나의 테이블
- 보강된 콘텐츠의 조각을 포함하는 추가 테이블
예를 들어 셰이퍼 기술이 호텔 정보와 핵심 구, 위치 및 조직과 같은 보강된 콘텐츠를 포함하는 "EnrichedShape"를 출력한다고 가정합니다. 기본 테이블에는 호텔을 설명하는 필드(ID, 이름, 설명, 주소, 범주)가 포함됩니다. 핵심 구는 핵심 구 열을 가져옵니다. 엔터티는 엔터티 열을 가져옵니다.
"projections" : [
{
"tables": [
{ "tableName": "MainTable", "generatedKeyName": "HotelId", "source": "/document/EnrichedShape" },
{ "tableName": "KeyPhrases", "generatedKeyName": "KeyPhraseId", "source": "/document/EnrichedShape/*/KeyPhrases/*" },
{ "tableName": "Entities", "generatedKeyName": "EntityId", "source": "/document/EnrichedShape/*/Entities/*" }
]
}
]
관계 이름 지정
generatedKeyName및 referenceKeyName 속성은 여러 테이블 또는 프로젝션 형식 간에 데이터를 연관하는 데 사용됩니다. 자식 테이블/프로젝션의 각 행에는 부모를 가리키는 속성이 있습니다. 자식의 열 또는 속성 이름은 부모에서 referenceKeyName입니다. referenceKeyName이 제공되지 않으면 서비스는 이를 부모 항목의 generatedKeyName으로 기본 설정합니다.
Power BI는 이러한 생성된 키를 사용하여 테이블 내의 관계를 검색합니다. 자식 테이블의 열이 다른 이름으로 지정 되어야 하는 경우 부모 테이블에서 referenceKeyName 속성을 설정합니다. 한 가지 예를 들면 generatedKeyName을 pbiDocument 테이블의 ID로 설정하고 referenceKeyName을 DocumentID로 설정하는 것입니다. 그러면 문서 ID가 포함된 pbiEntities 및 pbiKeyPhrases 테이블의 열이 DocumentID로 명명됩니다.
개체 프로젝션 정의
개체 프로젝션은 모든 노드에서 원본으로 사용할 수 있는 보강 트리의 JSON 표현입니다. 테이블 프로젝션에 비해 개체 프로젝션은 정의하기가 더 간단하며 전체 문서를 프로젝션할 때 사용됩니다. 개체 프로젝션은 컨테이너의 단일 프로젝션으로 제한되며 조각화할 수 없습니다.
개체 프로젝션을 정의하려면 프로젝션 속성에서 objects 배열을 사용합니다. 개체 프로젝션에는 다음과 같은 세 가지 필수 속성이 있습니다.
| 속성 | 설명 |
|---|---|
| storageContainer | Azure Storage에서 만든 새 컨테이너의 이름을 결정합니다. |
| generatedKeyName | 각 행을 고유하게 식별하는 키의 열 이름입니다. 값은 시스템에서 생성됩니다. 이 속성을 생략하면 테이블 이름과 ‘키’를 명명 규칙으로 사용하는 열이 자동으로 만들어집니다. |
| source | 프로젝션의 루트인 보강 트리의 노드에 대한 경로입니다. 노드는 일반적으로 Blob 구조를 결정하는 복잡한 데이터 셰이프에 대한 참조입니다. |
다음 예제에서는 개별 호텔 문서를 Blob당 하나의 호텔 문서로 hotels라는 컨테이너에 프로젝션합니다.
"knowledgeStore": {
"storageConnectionString": "an Azure storage connection string",
"projections" : [
{
"tables": [ ]
},
{
"objects": [
{
"storageContainer": "hotels",
"source": "/document/objectprojection",
}
]
},
{
"files": [ ]
}
]
}
원본은 "objectprojection"이라는 Shaper 기술의 출력입니다. 각 Blob에는 각 필드 입력의 JSON 표현이 있습니다.
{
"@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
"name": "#3",
"description": null,
"context": "/document",
"inputs": [
{
"name": "HotelId",
"source": "/document/HotelId"
},
{
"name": "HotelName",
"source": "/document/HotelName"
},
{
"name": "Category",
"source": "/document/Category"
},
{
"name": "keyPhrases",
"source": "/document/HotelId/keyphrases/*"
},
],
"outputs": [
{
"name": "output",
"targetName": "objectprojection"
}
]
}
파일 프로젝션 정의
파일 프로젝션은 항상 정규화된 이진 이미지로, 정규화는 기술 세트 실행에 사용할 수 있는 잠재적인 크기 조정 및 회전을 나타냅니다. 개체 프로젝션과 비슷한 파일 프로젝션은 Azure Storage에서 Blob으로 생성되며 이진 데이터(JSON과 반대)를 포함합니다.
파일 프로젝션을 정의하려면 프로젝션 속성에서 files 배열을 사용합니다. 파일 프로젝션에는 다음과 같은 세 가지 필수 속성이 있습니다.
| 속성 | 설명 |
|---|---|
| storageContainer | Azure Storage에서 만든 새 컨테이너의 이름을 결정합니다. |
| generatedKeyName | 각 행을 고유하게 식별하는 키의 열 이름입니다. 값은 시스템에서 생성됩니다. 이 속성을 생략하면 테이블 이름과 ‘키’를 명명 규칙으로 사용하는 열이 자동으로 만들어집니다. |
| source | 프로젝션의 루트인 보강 트리의 노드에 대한 경로입니다. 이미지 파일의 경우 원본은 항상 /document/normalized_images/*입니다. 파일 프로젝션은 normalized_images 컬렉션에서만 작동합니다. 인덱서나 기술 세트 모두 원래 정규화되지 않은 이미지를 통과하지 않습니다. |
대상은 항상 문서 ID의 base64로 인코딩된 값을 폴더 접두사로 사용하는 Blob 컨테이너입니다. 여러 이미지가 있는 경우 동일한 폴더에 함께 배치됩니다. 파일 프로젝션은 개체 프로젝션과 동일한 컨테이너를 공유할 수 없으며, 다른 컨테이너에 프로젝션되어야 합니다.
다음 예제에서는 보강된 문서의 문서 노드에서 추출된 모든 정규화된 이미지를 myImages라는 컨테이너에 프로젝션합니다.
"projections": [
{
"tables": [ ],
"objects": [ ],
"files": [
{
"storageContainer": "myImages",
"source": "/document/normalized_images/*"
}
]
}
]
테스트 프로젝션
다음 단계를 수행하여 프로젝션을 처리할 수 있습니다.
지식 저장소의
storageConnectionString속성을 유효한 V2 범용 저장소 계정 연결 문자열로 설정합니다.기술 세트 본문에 있는 프로젝션 정의를 사용하여 PUT 요청을 실행하여 기술 세트를 업데이트합니다.
인덱서를 실행하여 기술 세트를 실행합니다.
인덱서 실행을 모니터링하여 진행률을 확인하고 오류를 catch합니다.
Azure Portal을 사용하여 Azure Storage에서 개체 생성을 확인합니다.
테이블을 프로젝션하는 경우 테이블 조작 및 시각화를 위해 Power BI로 가져옵니다. 대부분의 경우 Power BI는 테이블 간의 관계를 자동으로 검색합니다.
일반적인 문제
다음 단계를 생략하면 예기치 않은 결과가 발생할 수 있습니다. 출력이 제대로 표시되지 않는 경우 다음 조건을 확인합니다.
문자열 보강은 유효한 JSON으로 형성되지 않습니다. 예를 들어 키 구로 보강된
merged_content문자열이 보강되면 보강된 속성은 보강 트리 내에서merged_content의 자식으로 표시됩니다. 기본 표현은 올바른 형식의 JSON이 아닙니다. 프로젝션 시 이름과 값이 있는 유효한 JSON 개체로 보강을 변환해야 합니다. 쉐이퍼 기술을 사용하거나 인라인 셰이프를 정의하면 이 문제를 해결하는 데 도움이 됩니다.원본 경로의 끝에서
/*를 생략합니다. 프로젝션의 원본이/document/projectionShape/keyPhrases인 경우 키 구 배열은 단일 개체/행으로 프로젝션됩니다. 대신의 원본 경로를/document/projectionShape/keyPhrases/*로 설정하여 각 키 구에 대해 단일 행 또는 개체를 생성합니다.경로 구문 오류입니다. 경로 선택기는 대/소문자를 구분 하며 선택기에 대해 정확한 대/소문자를 사용하지 않는 경우 입력 경고가 누락될 수 있습니다.
다음 단계
다음 단계에서는 다양한 기술 세트의 출력을 셰이핑하고 프로젝션하는 단계를 안내합니다. 기술 세트가 복잡한 경우 다음 문서에서 도형과 프로젝션의 예제를 제공합니다.