Azure AI Search 보강 파이프라인의 AML 기술

  • 아티클

Important

이 기술은 추가 사용 약관에 따라 공개 미리 보기로 제공됩니다. 미리 보기 REST API는 이 기술을 지원합니다.

AML 기술을 사용하면 사용자 지정 AML(Azure Machine Learning) 모델을 사용하여 AI 보강을 확장할 수 있습니다. AML 모델이 학습되고 배포되면AML 기술은 이를 AI 보강에 통합합니다.

기본 제공 기술과 마찬가지로 AML 기술에는 입력 및 출력이 있습니다. 입력은 JSON 개체로 배포된 AML 온라인 엔드포인트로 전송되며, 성공 상태 코드와 함께 JSON 페이로드를 응답으로 출력합니다. 응답에는 AML 기술에서 지정한 출력이 있어야 합니다. 다른 응답은 오류로 간주되며 보강이 수행되지 않습니다.

참고 항목

인덱서는 AML 온라인 엔드포인트에서 반환된 특정 표준 HTTP 상태 코드에 대해 두 번 다시 시도합니다. 이러한 HTTP 상태 코드는 다음과 같습니다.

  • 503 Service Unavailable
  • 429 Too Many Requests

필수 조건

@odata.type

Microsoft.Skills.Custom.AmlSkill

기술 매개 변수

매개 변수는 대/소문자를 구분합니다. 사용할 매개 변수는 AML 온라인 엔드포인트에 필요한 인증(있는 경우)에 따라 달라집니다.

매개 변수 이름 설명
uri (키 인증에 필요) JSON 페이로드가 전송되는 AML 온라인 엔드포인트의 점수 매기기 URI입니다. https URI 스키마만 허용됩니다.
key (키 인증에 필요) AML 온라인 엔드포인트의 키입니다.
resourceId (토큰 인증에 필요). AML 온라인 엔드포인트의 Azure Resource Manager 리소스 ID입니다. 구독/{guid}/resourceGroups/{resource-group-name}/Microsoft.MachineLearningServices/workspaces/{workspace-name}/onlineendpoints/{endpoint_name}형식이어야 합니다.
region (토큰 인증의 경우 선택 사항). AML 온라인 엔드포인트가 배포된 지역입니다.
timeout (선택 사항) 지정할 경우 API 호출을 수행하는 http 클라이언트에 대한 시간 제한을 나타냅니다. 형식은 XSD "dayTimeDuration" 값( ISO 8601 기간 값의 제한된 하위 집합)이어야 합니다. 예를 들어 PT60S 60초 동안입니다. 설정하지 않으면 기본값 30초가 선택됩니다. 제한 시간은 최대 230초, 최소 1초로 설정할 수 있습니다.
degreeOfParallelism (선택 사항) 지정된 경우 인덱서가 제공한 엔드포인트와 병렬로 호출하는 수를 나타냅니다. 요청 부하가 너무 높은 상태에서 엔드포인트가 실패하는 경우 이 값을 줄일 수 있습니다. 엔드포인트가 더 많은 요청을 수락할 수 있고 인덱서의 성능을 향상시키려면 이를 발생시킬 수 있습니다. 설정하지 않으면 기본값 5가 사용됩니다. degreeOfParallelism은 최대 10개까지 설정할 수 있으며 최솟값은 1입니다.

사용할 기술 매개 변수

필요한 AML 기술 매개 변수는 AML 온라인 엔드포인트에서 사용하는 인증(있는 경우)에 따라 달라집니다. AML 온라인 엔드포인트는 다음 두 가지 인증 옵션을 제공합니다.

  • 키 기반 인증. AML 기술에서 점수 매기기 요청을 인증하기 위해 정적 키가 제공됩니다.
    • uri와 키 매개 변수 사용
  • 토큰 기반 인증. AML 온라인 엔드포인트는 토큰 기반 인증을 사용하여 배포됩니다. Azure AI Search 서비스의 관리 ID를 사용하도록 설정해야 합니다. 그런 다음 AML 기술은 서비스의 관리 ID를 사용하여 정적 키 없이 AML 온라인 엔드포인트에 대해 인증합니다. ID에는 소유자 또는 기여자 역할이 할당되어야 합니다.
    • resourceId 매개 변수를 사용합니다.
    • 검색 서비스가 AML 작업 영역과 다른 지역에 있는 경우 지역 매개 변수를 사용하여 AML 온라인 엔드포인트가 배포된 지역을 설정합니다.

기술 입력

이 기술에 대해 "미리 정의된" 입력은 없습니다. 입력으로 이 기술을 실행할 때 이미 사용할 수 있는 하나 이상의 필드를 선택할 수 있으며 AML 온라인 엔드포인트로 전송된 JSON 페이로드에는 다른 필드가 있습니다.

기술 출력

이 기술에 대한 "미리 정의된" 출력은 없습니다. AML 온라인 엔드포인트가 반환하는 응답에 따라 JSON 응답에서 선택할 수 있도록 출력 필드를 추가합니다.

샘플 정의

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://contoso.count-things.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

샘플 입력 JSON 구조

이 JSON 구조는 AML 온라인 엔드포인트로 전송되는 페이로드를 나타냅니다. 구조체의 최상위 필드는 기술 정의 섹션에 지정된 "이름"에 inputs 해당합니다. 해당 필드의 값은 source 해당 필드의 값입니다(문서의 필드 또는 잠재적으로 다른 기술에서 가져올 수 있음).

{
  "text": "Este es un contrato en Inglés"
}

샘플 출력 JSON 구조

출력은 AML 온라인 엔드포인트에서 반환된 응답에 해당합니다. AML 온라인 엔드포인트는 JSON 페이로드만 반환해야 하며(응답 헤더를 확인 Content-Type 하여 확인됨) 필드가 "이름"output과 일치하는 보강이고 값이 보강으로 간주되는 개체여야 합니다.

{
    "detected_language_code": "es"
}

인라인 셰이핑 샘플 정의

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://contoso.count-things.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "shapedText",
        "sourceContext": "/document",
        "inputs": [
            {
              "name": "content",
              "source": "/document/content"
            }
        ]
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

인라인 셰이핑 입력 JSON 구조체

{
  "shapedText": { "content": "Este es un contrato en Inglés" }
}

인라인 셰이핑 샘플 출력 JSON 구조

{
    "detected_language_code": "es"
}

오류 사례

AML을 사용할 수 없거나 비uccessful 상태 코드를 보내는 것 외에도 다음과 같은 경우는 잘못된 경우로 간주됩니다.

  • AML 온라인 엔드포인트가 성공 상태 코드를 반환하지만 응답이 그렇지 않음application/json을 나타내는 경우 응답은 잘못된 것으로 간주되고 보강이 수행되지 않습니다.
  • AML 온라인 엔드포인트가 잘못된 json을 반환하는 경우

AML 온라인 엔드포인트를 사용할 수 없거나 HTTP 오류를 반환하는 경우 HTTP 오류에 대한 사용 가능한 세부 정보가 포함된 친숙한 오류가 인덱서 실행 기록에 추가됩니다.

참고 항목