기술 세트 만들기(Azure AI Search REST API)
기술 세트는 AZURE Storage에서 외부 지식 저장소를 만들기 위한 선택적 사양과 함께 AI 보강에 사용되는 인지 기술 모음입니다. 기술은 자연어 처리 및 기타 변환(예: 엔터티 인식, 핵심 구 추출, 텍스트를 논리적 페이지로 청크 분할)을 호출합니다.
기술 세트는 인덱서에 연결됩니다. 기술 세트를 사용하려면 인덱서에서 참조한 다음 인덱서 를 실행하여 데이터를 가져오고, 변환 및 보강을 호출하고, 출력 필드를 인덱스에 매핑합니다. 기술 세트는 개략적인 리소스이지만 인덱서 처리 내에서만 작동합니다. 상위 수준 리소스이므로 기능을 한 번 디자인한 후 여러 인덱서에서 참조할 수 있습니다.
요청에 POST 또는 PUT을 사용할 수 있습니다. 둘 중 하나에 대해 요청 본문의 JSON 문서는 개체 정의를 제공합니다.
PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
모든 서비스 요청에는 HTTPS를 사용해야 합니다. 기술 세트가 없으면 생성됩니다. 이미 있는 경우 새 정의로 업데이트됩니다.
참고
기술 세트는 AI 보강의 기초입니다. 제한된 처리를 위해 무료 리소스를 사용할 수 있지만 더 크거나 더 빈번한 워크로드의 경우 청구 가능한 Cognitive Services 리소스 가 필요합니다.
URI 매개 변수
| 매개 변수 | Description |
|---|---|
| 서비스 이름 | 필수 사항입니다. 검색 서비스의 고유한 사용자 정의 이름으로 설정합니다. |
| skillset name | PUT을 사용하는 경우 URI에 필요합니다. 이름은 소문자여야 하고, 문자 또는 숫자로 시작하고, 슬래시나 점이 없고, 128자 미만이어야 합니다. 이름은 문자 또는 숫자로 시작해야 하지만 대시가 연속되지 않는 한 나머지 이름에는 문자, 숫자 및 대시가 포함될 수 있습니다. |
| api-version | 필수 사항입니다. 지원되는 버전 목록은 API 버전을 참조하세요. |
요청 헤더
다음 표에서는 필수 요청 헤더와 선택적 요청 헤더에 대해 설명합니다.
| 필드 | Description |
|---|---|
| 콘텐츠 형식 | 필수 사항입니다. application/json |
| api-key | Azure 역할을 사용하고 요청에 전달자 토큰이 제공된 경우 선택 사항이며, 그렇지 않으면 키가 필요합니다. 만들기 요청에는 쿼리 키가 아닌 관리자 키로 설정된 헤더가 포함되어 api-key 야 합니다. 자세한 내용은 키 인증을 사용하여 Azure AI Search에 연결을 참조하세요. |
요청 본문
요청 본문에는 기술 세트 정의가 포함됩니다. 기술은 독립 실행형이거나 한 변환의 출력이 다른 변환에 대한 입력이 되는 입력 출력 연결을 통해 함께 연결됩니다. 기술 집합에는 최소 하나 이상의 기술이 있어야 합니다. 최대 기술 수에 대한 이론적 제한은 없지만 3~5개는 일반적인 구성입니다.
다음 JSON은 정의의 기본 부분에 대한 개략적인 표현입니다.
{
"name" : (optional on PUT; required on POST) "Name of the skillset",
"description" : (optional) "Anything you want, or nothing at all",
"skills" : (required) ["An array of skills. Each skill has an odata.type, name, input and output parameters"],
"cognitiveServices":
{
"@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
"description": "Optional. Anything you want, or null",
"key": "<YOUR-COGNITIVE-SERVICES-ALL-IN-ONE-KEY>"
},
"knowledgeStore": (optional) { ... },
"encryptionKey": (optional) { }
}
요청에는 다음 속성이 포함됩니다.
| 속성 | Description |
|---|---|
| name | 필수 사항입니다. 기술 세트의 이름입니다. 이름은 소문자여야 하고, 문자 또는 숫자로 시작하고, 슬래시나 점이 없고, 128자 미만이어야 합니다. 이름은 문자 또는 숫자로 시작해야 하지만 대시가 연속되지 않는 한 나머지 이름에는 문자, 숫자 및 대시가 포함될 수 있습니다. |
| 기술 | 기술 배열입니다. 각 기술에는 odata.type, 이름, 컨텍스트, 입력 및 출력 매개 변수가 있습니다. 배열에는 기본 제공 기술과사용자 지정 기술이 포함될 수 있습니다. 하나 이상의 기술이 필요합니다. 지식 저장소를 사용하는 경우 프로젝션 내에서 데이터 셰이프를 정의하지 않는 한 쉐이퍼 기술을 포함합니다. |
| cognitiveServices | 인덱서당 매일 20개 이상의 문서에서 Cognitive Services API 호출하는 청구 가능한 기술에는 올인원 키가 필요합니다. 키는 검색 서비스와 동일한 지역에 있는 리소스에 대한 키여야 합니다. 자세한 내용은 Cognitive Services 리소스 연결을 참조하세요. 사용자 지정 엔터티 조회 기술을 사용하는 경우 인덱서당 매일 20개 이상의 트랜잭션을 사용할 수 있도록 이 섹션과 키를 포함합니다. Cognitive Services 키가 필요하지 않으므로 기술 세트가 사용자 지정 기술, 유틸리티 기술(조건부, 셰이퍼, 텍스트 병합, 텍스트 분할) 또는 문서 추출 기술로만 구성된 경우 섹션을 제외 cognitiveServices 할 수 있습니다. 기술 세트에서 연결된 Cognitive Service 리소스를 제거하려면("기본" 제한을 사용하는 되돌리기) 을 로 #Microsoft.Azure.Search.DefaultCognitiveServices지정 @odata.type 합니다. 자세한 내용은 이 예제를 참조하세요. |
| knowledgeStore | 선택 사항입니다. Azure Storage에 대한 보강 출력 대상입니다. Azure Storage 계정 및 프로젝션에 대한 연결 문자열 필요합니다. storageConnectionString (필수) 형식의 문자열입니다 "DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net". projections(필수) , , objectsfiles로 구성된 프로젝션 개체의 tables배열로, 지정된 개체 또는 null입니다. tablesAzure Table Storage에서 하나 이상의 테이블을 만들고 각 문서의 콘텐츠를 테이블의 행으로 프로젝션합니다. 각 테이블에는 다음과 같은 세 가지 속성이 있을 수 있습니다.
objects문서를 Azure Blob Storage Blob으로 프로젝트합니다. 각 개체에는 다음과 같은 두 가지 필수 속성이 있습니다.
files각 파일 항목은 Blob Storage에서 이진 이미지의 스토리지를 정의합니다. 파일 프로젝션에는 두 가지 필수 속성이 있습니다.
|
| encryptionKey | 선택 사항입니다. Azure Key Vault 관리되는 자체 키를 사용하여 미사용 기술 세트 정의를 암호화하는 데 사용됩니다. 2019-01-01 또는 그 이후에 생성된 청구 가능한 검색 서비스에 사용할 수 있습니다. encryptionKey 섹션에는 사용자 정의 keyVaultKeyName (필수), 시스템 생성 keyVaultKeyVersion (필수) 및 keyVaultUri 제공 키(필수, DNS 이름이라고도 함)가 포함됩니다. 예제 URI는 "https://my-keyvault-name.vault.azure.net"일 수 있습니다. 필요에 따라 관리되는 시스템 ID를 사용하지 않는지 지정할 accessCredentials 수 있습니다. 의 accessCredentials 속성에는 지정된 Azure Key Vault 대한 액세스 권한이 부여된 (Microsoft Entra ID 애플리케이션 ID) 및 applicationSecret (등록된 애플리케이션의 인증 키)가 포함 applicationId 됩니다. 다음 섹션의 예제에서는 구문을 보여 줍니다. |
응답
성공적인 요청의 경우, 상태 코드 “201 생성됨”이 표시되어야 합니다.
기본적으로 응답 본문에는 생성된 기능 정의에 대한 JSON이 포함됩니다. 그러나 요청 헤더가 로 설정된 return=minimal경우 Prefer 응답 본문은 비어 있고 성공 상태 코드는 "201 만든" 대신 "204 콘텐츠 없음"입니다. 기능을 만드는 데 사용한 방법(PUT 또는 POST)에 상관없이 결과는 동일합니다.
예제
예: 고객 리뷰에서 비즈니스 엔터티 및 감정을 인식하는 기술 세트
이 기술 세트는 두 가지 기술을 비동기적으로 사용하고 독립적으로 두 가지 변환으로 처리 /document/content 합니다. 기술은 엔터티 인식 및 감정입니다. 보강 트리 /document/content 에서 는 외부 데이터 원본의 콘텐츠(또는 고객 리뷰)를 제공합니다.
{
"name": "reviews-ss",
"description":
"Extract company names from customer reviews, and detect positive or negative sentiment from the same reviews.",
"skills":
[
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"context": "/document/content",
"categories": [ "Organization" ],
"defaultLanguageCode": "en",
"inputs": [
{
"name": "text",
"source": "/document/content"
}
],
"outputs": [
{
"name": "organizations",
"targetName": "companyName"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.V3.SentimentSkill",
"inputs": [
{
"name": "text",
"source": "/document/content"
},
{
"name": "languageCode",
"source": "/document/languageCode"
}
],
"outputs": [
{
"name": "sentiment",
"targetName": "reviewSentiment"
},
{
"name": "confidenceScores",
"targetName": "sentimentScore"
}
]
}
],
"cognitiveServices":
{
"@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
"description": "mycogsvcs resource in West US 2",
"key": "<your cognitive services all-in-one key goes here>"
},
"knowledgeStore": { },
"encryptionKey": { }
}
예: 지식 저장소
기술 세트는 필요에 따라 Azure Storage의 지식 저장소 에 출력을 보낼 수 있습니다. Azure Storage 계정에 대한 연결 문자열 및 보강된 콘텐츠가 테이블 또는 Blob Storage(개체 또는 파일)에 배치되는지 여부를 결정하는 프로젝션이 필요합니다. 프로젝션에는 일반적으로 보강 트리의 노드를 입력으로 수집하여 프로젝션에 전달할 수 있는 단일 셰이프를 출력하는 업스트림 Shaper 기술이 필요합니다. 쉐이퍼는 일반적으로 처리할 마지막 기술입니다.
{
"name": "reviews-ss",
"description":
"Extract company names from customer reviews, and detect positive or negative sentiment from the same reviews.",
"skills":
[
{ ... },
{ ... },
{
"@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
"context": "/document/content",
"inputs": [
{
"name": "Company",
"source": "/document/content/companyName"
},
{
"name": "Sentiment_Score",
"source": "/document/content/sentimentScore"
},
{
"name": "Sentiment_Label",
"source": "/document/content/reviewSentiment"
}
],
"outputs": [
{
"name": "output",
"targetName": "shapeCustomerReviews"
}
]
}
],
"cognitiveServices":
{
"@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
"description": "mycogsvcs resource in West US 2",
"key": "<your cognitive services all-in-one key goes here>"
},
"knowledgeStore": {
"storageConnectionString": "<your storage account connection string>",
"projections": [
{
"tables": [
{ "tableName": "CustomerReviews", "generatedKeyName": "DocID", "source": "/document/shapeCustomerReviews" }
. . .
],
"objects": [ ],
"files": [ ]
}
]
}
"encryptionKey": { }
}
예: 암호화 키
암호화 키는 중요한 콘텐츠의 추가 암호화 에 사용되는 고객 관리형 키입니다. 이 예제에서는 기술 세트에 고객 관리형 암호화를 지정하는 방법을 보여줍니다.
{
"name": "reviews-ss",
"description": "A brief description of the skillset",
"skills": [ omitted for brevity ],
"cognitiveServices": { omitted for brevity },
"knowledgeStore": { omitted for brevity },
"encryptionKey": (optional) {
"keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
"keyVaultKeyVersion": "Version of the Azure Key Vault key",
"keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
"accessCredentials": (optional, only if not using managed system identity) {
"applicationId": "Azure Active Directory Application ID that was granted access permissions to your specified Azure Key Vault",
"applicationSecret": "Authentication key of the specified Azure AD application)"}
}
}