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

아티클
09/01/2024

Important

Azure AI Studio 모델 카탈로그에 대한 인덱서 연결 지원은 추가 사용 약관에 따라 공개 미리 보기로 제공됩니다. 미리 보기 REST API는 이 기술을 지원합니다.

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

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

AML 기술은 Azure AI Studio의 모델 카탈로그에 연결하기 위해 2024-07-01 안정적인 API 버전 또는 2024-05-01-preview API 버전으로 호출할 수 있습니다.

2024-05-01-preview REST API 및 Azure Portal(2024-05-01-preview를 대상으로 하는)부터 Azure AI Search는 Azure AI Studio의 모델 카탈로그에 대한 쿼리 시간 연결을 위한 Azure AI Studio 모델 카탈로그 벡터라이저를 도입했습니다. 쿼리에 해당 벡터라이저를 사용하려는 경우 AML 기술은 Azure AI Studio 모델 카탈로그의 모델을 사용하여 포함을 생성하기 위한 인덱싱 기술입니다.

인덱싱하는 동안 AML 기술은 모델 카탈로그에 연결하여 인덱스에 대한 벡터를 생성할 수 있습니다. 쿼리 시 쿼리는 벡터라이저를 사용하여 동일한 모델에 연결하여 벡터 쿼리에 대한 텍스트 문자열을 벡터화할 수 있습니다. 이 워크플로 에서는 인덱싱과 쿼리 모두에 동일한 포함 모델을 사용할 수 있도록 AML 기술과 모델 카탈로그 벡터라이저를 함께 사용해야 합니다. 이 워크플로에 대한 자세한 내용은 Azure AI Studio의 모델을 사용하여 통합 벡터화를 구현하는 방법을 참조하세요.

참고 항목

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

503 Service Unavailable
429 Too Many Requests

필수 조건

AML 작업 영역
이 작업 영역의 온라인 엔드포인트(실시간).

@odata.type

Microsoft.Skills.Custom.AmlSkill

기술 매개 변수

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

매개 변수 이름	설명
`uri`	(키 인증에 필요) JSON 페이로드를 보낼 AML 온라인 엔드포인트의 채점 URI입니다. https URI 체계만 허용됩니다.
`key`	(키 인증에 필요) AML 온라인 엔드포인트의 키입니다.
`resourceId`	(토큰 인증에 필요) AML 온라인 엔드포인트의 Azure Resource Manager 리소스 ID. ID는 subscriptions/{guid}/resourceGroups/{resource-group-name}/Microsoft.MachineLearningServices/workspaces/{workspace-name}/onlineendpoints/{endpoint_name} 형식이어야 합니다.
`region`	(토큰 인증의 경우 선택 사항). AML 온라인 엔드포인트가 배포되는 지역.
`timeout`	(선택 사항) 지정할 경우 API 호출을 수행하는 http 클라이언트에 대한 시간 제한을 나타냅니다. 형식은 XSD "dayTimeDuration" 값( ISO 8601 기간 값의 제한된 하위 집합)이어야 합니다. 예를 들어, 60초인 경우 `PT60S`입니다. 설정하지 않으면 기본값 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 섹션에 지정된 “names”에 해당합니다. 해당 필드의 값은 해당 필드의 source(문서의 필드 또는 잠재적으로 다른 기술의 필드일 수 있음)에서 가져온 것입니다.

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

샘플 출력 JSON 구조

출력은 AML 온라인 엔드포인트에서 반환된 응답에 해당합니다. AML 온라인 엔드포인트는 (Content-Type 응답 헤더에서 확인된) JSON 페이로드만 반환해야 하며, 필드가 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이 사용 가능하지 않거나 성공하지 못한 상태 코드를 보내는 것 외에도 다음 상황이 잘못된 경우로 간주됩니다.

AML 온라인 엔드포인트가 성공 상태 코드를 반환했지만 응답에 application/json이 아닌 것으로 나타나면 해당 응답은 유효하지 않은 것으로 간주되어 보강이 수행되지 않습니다.
AML 온라인 엔드포인트가 잘못된 json을 반환하는 경우

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

다음을 통해 공유