사용자 지정 엔터티 조회 인식 기술
사용자 지정 엔터티 조회 기술은 정의한 엔터티를 검색하거나 인식하는 데 사용됩니다. 기술 세트를 실행하는 동안 기술은 사용자 지정된 단어 및 구의 사용자 정의 목록에서 텍스트를 찾습니다. 기술은 이 목록을 사용하여 원본 문서 내에 있는 일치하는 모든 엔터티에 레이블을 지정합니다. 이 기술은 유사하지만 정확하지 않은 일치 항목을 찾기 위해 적용할 수 있는 유사 항목 일치 수준도 지원합니다.
참고 항목
이 기술은 Azure AI 서비스 API에 바인딩되지 않지만 20개 이상의 트랜잭션을 허용하려면 Azure AI 서비스 키가 필요합니다. 이 기술은 Azure AI Search를 통해 계량됩니다.
@odata.type
Microsoft.Skills.Text.CustomEntityLookupSkill
데이터 제한
- 지원되는 최대 입력 레코드 크기는 256MB입니다. 데이터를 사용자 지정 엔터티 조회 기술로 보내기 전에 분할해야 하는 경우 텍스트 분할 기술을 사용하는 것이 좋습니다. 텍스트 분할 기술을 사용하는 경우 최상의 성능을 위해 페이지 길이를 5000으로 설정합니다.
- 사용자 지정 엔터티 정의의 최대 크기는 "entitiesDefinitionUri" 매개 변수를 통해 지정된 외부 파일로 제공되는 경우 10MB입니다.
- 엔터티가 "inlineEntitiesDefinition" 매개 변수를 사용하여 인라인으로 정의된 경우 최대 크기는 10KB입니다.
기술 매개 변수
매개 변수는 대/소문자를 구분합니다.
| 매개 변수 이름 | 설명 |
|---|---|
entitiesDefinitionUri |
일치시킬 모든 대상 텍스트를 포함하는 외부 JSON 또는 CSV 파일의 경로입니다. 이 엔터티 정의는 인덱서 실행의 시작 부분에서 읽습니다. 실행 중간에 이 파일에 대한 모든 업데이트는 후속 실행까지 실현되지 않습니다. 이 파일은 HTTPS를 통해 액세스할 수 있어야 합니다. 필요한 CSV 또는 JSON 스키마는 아래 사용자 지정 엔터티 정의 형식을 참조하세요. |
inlineEntitiesDefinition |
인라인 JSON 엔터티 정의입니다. 이 매개 변수가 있는 경우 entitiesDefinitionUri 매개 변수를 대체합니다. 10KB 이하의 구성은 인라인으로 제공될 수 있습니다. 예상되는 JSON 스키마는 아래의 사용자 지정 엔터티 정의를 참조하세요. |
defaultLanguageCode |
(선택 사항) 입력 텍스트를 토큰화하고 구분하는 데 사용되는 입력 텍스트의 언어 코드입니다. 지원 da, de, en, es, fi, fr, it, pt되는 언어는 다음과 같습니다. 기본값은 영어(en)입니다. languagecode-countrycode 형식을 전달하는 경우 형식의 languagecode 부분만 사용됩니다. |
globalDefaultCaseSensitive |
(선택 사항) 기술에 대한 기본 대/소문자 구분 값입니다. 엔터티의 defaultCaseSensitive 값이 지정되지 않은 경우 이 값은 해당 엔터티의 defaultCaseSensitive 값이 됩니다. |
globalDefaultAccentSensitive |
(선택 사항) 기술에 대한 기본 악센트 구분 값입니다. 엔터티의 defaultAccentSensitive 값이 지정되지 않은 경우 이 값은 해당 엔터티의 defaultAccentSensitive 값이 됩니다. |
globalDefaultFuzzyEditDistance |
(선택 사항) 기술의 기본 유사 항목 편집 거릿값입니다. 엔터티의 defaultFuzzyEditDistance 값이 지정되지 않은 경우 이 값은 해당 엔터티의 defaultFuzzyEditDistance 값이 됩니다. |
기술 입력
| 입력 이름 | 설명 |
|---|---|
text |
분석할 텍스트입니다. |
languageCode |
선택 사항. 기본값은 "en"입니다. |
기술 출력
| 출력 이름 | 설명 |
|---|---|
entities |
다음 필드를 포함하는 복합 형식의 배열입니다.
|
사용자 지정 엔터티 정의 형식
사용자 지정 엔터티 조회 기술에 사용자 지정 엔터티 목록을 제공하는 방법에는 세 가지가 있습니다.
- .CSV 파일(UTF-8 인코딩)
- .JSON 파일(UTF-8 인코딩)
- 기술 정의 내 인라인
정의 파일이 .CSV 또는 .JSON 파일에 있는 경우 "entitiesDefinitionUri" 매개 변수에 전체 경로를 제공합니다. 파일은 각 인덱서 실행이 시작될 때 다운로드됩니다. 인덱서가 중지될 때까지 액세스할 수 있어야 합니다.
인라인 정의를 사용하는 경우 "inlineEntitiesDefinition" 기술 매개 변수 아래에 지정합니다.
참고 항목
인덱서는 JSON 및 CSV 파일에 대한 특수 구문 분석 모드를 지원합니다. 사용자 지정 엔터티 조회 기술을 사용할 때 "parsingMode"를 "default"로 설정합니다. 이 기술은 JSON 및 CSV가 구문 분석되지 않은 상태일 것으로 예상합니다.
CSV 형식
파일의 경로를 제공하고 "entitiesDefinitionUri" 기술 매개 변수에서 설정하여 CSV(쉼표로 구분된 값) 파일에서 찾을 사용자 지정 엔터티의 정의를 제공할 수 있습니다. 경로는 https 위치에 있어야 합니다. 정의 파일의 크기는 최대 10MB입니다.
CSV 형식은 간단합니다. 각 줄은 아래와 같이 고유한 엔터티를 나타냅니다.
Bill Gates, BillG, William H. Gates
Microsoft, MSFT
Satya Nadella
이 경우 반환할 수 있는 세 개의 엔터티(Bill Gates, Satya Nadella, Microsoft)가 있습니다. 별칭은 주 엔터티 뒤에 나옵니다. 별칭에 대한 일치 항목은 기본 엔터티 아래에 번들로 제공됩니다. 예를 들어, 문서에서 “William H. Gates” 문자열을 찾은 경우 “Bill Gates” 엔터티와 일치하는 항목이 반환됩니다.
JSON 형식
JSON 파일에서도 찾을 사용자 지정 엔터티의 정의를 제공할 수 있습니다. JSON 형식에서는 용어마다 일치 규칙을 정의할 수 있으므로 좀 더 유연하게 사용할 수 있습니다. 예를 들어 각 용어의 유사 일치 거리(Damerau-Levenshtein 거리)를 지정하거나 일치가 대/소문자를 구분하는지 여부를 지정할 수 있습니다.
CSV 파일의 경우와 마찬가지로 JSON 파일의 경로를 제공하고 "entitiesDefinitionUri" 기술 매개 변수에서 설정해야 합니다. 경로는 https 위치에 있어야 합니다. 정의 파일의 크기는 최대 10MB입니다.
가장 기본적인 JSON 사용자 지정 엔터티 목록 정의는 일치시킬 엔터티 목록일 수 있습니다.
[
{
"name" : "Bill Gates"
},
{
"name" : "Microsoft"
},
{
"name" : "Satya Nadella"
}
]
더 복잡한 정의는 사용자 정의 ID, 설명, 형식, 하위 형식 및 별칭을 제공할 수 있습니다. 별칭 용어가 일치하면 엔터티도 반환됩니다.
[
{
"name" : "Bill Gates",
"description" : "Microsoft founder." ,
"aliases" : [
{ "text" : "William H. Gates", "caseSensitive" : false },
{ "text" : "BillG", "caseSensitive" : true }
]
},
{
"name" : "Xbox One",
"type": "Hardware",
"subtype" : "Gaming Device",
"id" : "4e36bf9d-5550-4396-8647-8e43d7564a76",
"description" : "The Xbox One product"
},
{
"name" : "LinkedIn" ,
"description" : "The LinkedIn company",
"id" : "differentIdentifyingScheme123",
"fuzzyEditDistance" : 0
},
{
"name" : "Microsoft" ,
"description" : "Microsoft Corporation",
"id" : "differentIdentifyingScheme987",
"defaultCaseSensitive" : false,
"defaultFuzzyEditDistance" : 1,
"aliases" : [
{ "text" : "MSFT", "caseSensitive" : true }
]
}
]
아래 표에서는 사용자 지정 엔터티를 정의할 때 설정할 수 있는 구성 매개 변수를 설명합니다.
| 필드 이름 | 설명 |
|---|---|
name |
최상위 엔터티 설명자입니다. 기술 출력의 일치 항목은 이 이름으로 그룹화되며 찾은 텍스트의 "정규화된" 형식을 나타내야 합니다. |
description |
(선택 사항) 이 필드는 일치하는 텍스트에 대한 사용자 지정 메타데이터의 통과로 사용할 수 있습니다. 이 필드의 값은 기술 출력에서 엔터티의 모든 일치 항목과 함께 표시됩니다. |
type |
(선택 사항) 이 필드는 일치하는 텍스트에 대한 사용자 지정 메타데이터의 통과로 사용할 수 있습니다. 이 필드의 값은 기술 출력에서 엔터티의 모든 일치 항목과 함께 표시됩니다. |
subtype |
(선택 사항) 이 필드는 일치하는 텍스트에 대한 사용자 지정 메타데이터의 통과로 사용할 수 있습니다. 이 필드의 값은 기술 출력에서 엔터티의 모든 일치 항목과 함께 표시됩니다. |
id |
(선택 사항) 이 필드는 일치하는 텍스트에 대한 사용자 지정 메타데이터의 통과로 사용할 수 있습니다. 이 필드의 값은 기술 출력에서 엔터티의 모든 일치 항목과 함께 표시됩니다. |
caseSensitive |
(선택 사항) 기본값은 false입니다. 엔터티 이름과의 비교가 문자 대/소문자를 구분해야 하는지 여부를 나타내는 부울 값입니다. "Microsoft"의 샘플 대/소문자를 구분하지 않는 일치 항목은 microsoft, microSoft, MICROSOFT일 수 있습니다. |
accentSensitive |
(선택 사항) 기본값은 false입니다. ‘é’ 및 ‘e’와 같이 악센트가 있는 문자와 없는 문자가 동일한지를 나타내는 부울 값입니다. |
fuzzyEditDistance |
(선택 사항) 기본값은 0입니다. 최대값은 5입니다. 엔터티 이름과 일치를 구성하는 허용되는 분기 문자 수를 나타냅니다. 지정된 일치 항목에 대해 가능한 가장 작은 유사 항목이 반환됩니다. 예를 들어 편집 거리가 3으로 설정된 경우 "Windows 10"은 여전히 "Windows", "Windows10" 및 "windows 7"과 일치합니다. 대/소문자 구분이 false로 설정된 경우 대/소문자 차이는 허용 오차에 포함되지 않지만 그렇지 않은 경우에는 포함됩니다. |
defaultCaseSensitive |
(선택 사항) 이 엔터티의 기본 대/소문자 구분 값을 변경합니다. 모든 별칭 caseSensitive 값의 기본값을 변경하는 데 사용할 수 있습니다. |
defaultAccentSensitive |
(선택 사항) 이 엔터티의 기본 악센트 구분 값을 변경합니다. 모든 별칭 accentSensitive 값의 기본값을 변경하는 데 사용할 수 있습니다. |
defaultFuzzyEditDistance |
(선택 사항) 이 엔터티의 기본 유사 항목 편집 거릿값을 변경합니다. 모든 별칭 fuzzyEditDistance 값의 기본값을 변경하는 데 사용할 수 있습니다. |
aliases |
(선택 사항) 루트 엔터티 이름에 대한 대체 맞춤법 또는 동의어를 지정하는 데 사용할 수 있는 복합 개체의 배열입니다. |
| 별칭 속성 | 설명 |
|---|---|
text |
일부 대상 엔터티 이름의 대체 철자 또는 표현입니다. |
caseSensitive |
(선택 사항) 위의 루트 엔터티 "caseSensitive" 매개 변수와 동일하게 작동하지만 이 별칭 하나에만 적용됩니다. |
accentSensitive |
(선택 사항) 위의 루트 엔터티 "accentSensitive" 매개 변수와 동일하게 작동하지만 이 별칭 하나에만 적용됩니다. |
fuzzyEditDistance |
(선택 사항) 위의 루트 엔터티 "fuzzyEditDistance" 매개 변수와 동일하게 작동하지만 이 별칭 하나에만 적용됩니다. |
인라인 형식
경우에 따라 기술 정의와 인라인되도록 사용자 지정 엔터티 정의를 포함하는 것이 더 편리할 수 있습니다. 기술 정의 내에 포함된다는 점을 제외하고 위에서 설명한 것과 동일한 JSON 형식을 사용할 수 있습니다. 크기가 10KB 미만인 구성(직렬화된 크기)만 인라인으로 정의할 수 있습니다.
샘플 기술 정의
인라인 형식을 사용하는 샘플 기술 정의는 다음과 같습니다.
{
"@odata.type": "#Microsoft.Skills.Text.CustomEntityLookupSkill",
"context": "/document",
"inlineEntitiesDefinition":
[
{
"name" : "Bill Gates",
"description" : "Microsoft founder." ,
"aliases" : [
{ "text" : "William H. Gates", "caseSensitive" : false },
{ "text" : "BillG", "caseSensitive" : true }
]
},
{
"name" : "Xbox One",
"type": "Hardware",
"subtype" : "Gaming Device",
"id" : "4e36bf9d-5550-4396-8647-8e43d7564a76",
"description" : "The Xbox One product"
}
],
"inputs": [
{
"name": "text",
"source": "/document/content"
}
],
"outputs": [
{
"name": "entities",
"targetName": "matchedEntities"
}
]
}
또는 외부 엔터티 정의 파일을 가리킬 수 있습니다. entitiesDefinitionUri 형식을 사용하는 샘플 기술 정의는 다음과 같습니다.
{
"@odata.type": "#Microsoft.Skills.Text.CustomEntityLookupSkill",
"context": "/document",
"entitiesDefinitionUri": "https://myblobhost.net/keyWordsConfig.csv",
"inputs": [
{
"name": "text",
"source": "/document/content"
}
],
"outputs": [
{
"name": "entities",
"targetName": "matchedEntities"
}
]
}
샘플 인덱스 정의
이 섹션에서는 샘플 인덱스 정의를 제공합니다. "entities"와 "matches"는 모두 복합 형식의 배열입니다. 문서당 여러 개의 엔터티가 있고 각 엔터티에 대해 여러 개의 일치 항목을 가질 수 있습니다.
{
"name": "entities",
"type": "Collection(Edm.ComplexType)",
"fields": [
{
"name": "name",
"type": "Edm.String",
"facetable": false,
"filterable": false,
"retrievable": true,
"searchable": true,
"sortable": false,
},
{
"name": "id",
"type": "Edm.String",
"facetable": false,
"filterable": false,
"retrievable": true,
"searchable": false,
"sortable": false,
},
{
"name": "description",
"type": "Edm.String",
"facetable": false,
"filterable": false,
"retrievable": true,
"searchable": true,
"sortable": false,
},
{
"name": "type",
"type": "Edm.String",
"facetable": true,
"filterable": true,
"retrievable": true,
"searchable": false,
"sortable": false,
},
{
"name": "subtype",
"type": "Edm.String",
"facetable": true,
"filterable": true,
"retrievable": true,
"searchable": false,
"sortable": false,
},
{
"name": "matches",
"type": "Collection(Edm.ComplexType)",
"fields": [
{
"name": "text",
"type": "Edm.String",
"facetable": false,
"filterable": false,
"retrievable": true,
"searchable": true,
"sortable": false,
},
{
"name": "offset",
"type": "Edm.Int32",
"facetable": true,
"filterable": true,
"retrievable": true,
"sortable": false,
},
{
"name": "length",
"type": "Edm.Int32",
"facetable": true,
"filterable": true,
"retrievable": true,
"sortable": false,
},
{
"name": "matchDistance",
"type": "Edm.Double",
"facetable": true,
"filterable": true,
"retrievable": true,
"sortable": false,
}
]
}
]
}
샘플 입력 데이터
{
"values": [
{
"recordId": "1",
"data":
{
"text": "The company, Microsoft, was founded by Bill Gates. Microsoft's gaming console is called Xbox",
"languageCode": "en"
}
}
]
}
샘플 출력
{
"values" :
[
{
"recordId": "1",
"data" : {
"entities": [
{
"name" : "Microsoft",
"description" : "This document refers to Microsoft the company",
"id" : "differentIdentifyingScheme987",
"matches" : [
{
"text" : "microsoft",
"offset" : 13,
"length" : 9,
"matchDistance" : 0
},
{
"text" : "Microsoft",
"offset" : 49,
"length" : 9,
"matchDistance" : 0
}
]
},
{
"name" : "Bill Gates",
"description" : "William Henry Gates III, founder of Microsoft.",
"matches" : [
{
"text" : "Bill Gates",
"offset" : 37,
"length" : 10,
"matchDistance" : 0
}
]
}
]
}
}
]
}
경고
"Reached maximum capacity for matches, skipping all further duplicate matches."
이 경고는 검색된 일치 항목의 수가 허용되는 최댓값보다 큰 경우에 나타납니다. 중복 일치 항목이 더 이상 반환되지 않습니다. 더 높은 임계값이 필요한 경우 개별 사용 사례에 대한 지원을 위해 지원 티켓을 제출할 수 있습니다.