Azure AI 검색 보강 파이프라인에 사용자 지정 기술 추가

아티클
09/03/2024

AI 보강 파이프라인에는 기본 제공 기술과 직접 만들고 게시하는 사용자 지정 기술이 모두 포함될 수 있습니다. 사용자 지정 코드는 검색 서비스에서 외부적으로(예: Azure 함수로) 실행되지만 다른 기술과 마찬가지로 입력을 수락하고 기술 집합에 출력을 보냅니다. 데이터는 모델이 배포된 지역에서 처리됩니다.

사용자 지정 기술은 복잡해 보일 수 있지만 구현 측면에서 간단하고 단순할 수 있습니다. 패턴 일치 또는 분류 모델을 제공하는 기존 패키지가 있는 경우 Blob에서 추출한 콘텐츠를 이러한 모델에 전달하여 처리할 수 있습니다. AI 보강은 Azure 기반이므로 모델도 Azure에 있어야 합니다. 몇 가지 일반적인 호스팅 방법론에는 Azure Functions 또는 컨테이너 사용이 포함됩니다.

사용자 지정 기술을 빌드하는 경우 이 문서에서는 기술을 파이프라인에 통합하는 데 사용할 인터페이스에 대해 설명합니다. 기본 요구 사항은 전체적으로 기술 세트 내에서 소비 가능한 방식으로 입력을 수락하고 출력을 내보낼 수 있는 기능입니다. 따라서 이 문서에서는 보강 파이프라인에 필요한 입력 및 출력 형식을 중심으로 설명합니다.

사용자 지정 기술의 이점

사용자 지정 기술을 작성하면 콘텐츠에 고유한 변환을 삽입할 수 있습니다. 예를 들어, 필드별 사용자 지정 분류 모델을 빌드하여 비즈니스 및 재무 계약과 문서를 구별하거나, 음성 인식 기술을 추가하여 관련 콘텐츠의 오디오 파일을 더 자세히 조사할 수 있습니다. 단계별 예제는 예제: AI 보강을 위한 사용자 지정 기술 만들기를 참조하세요.

엔드포인트 및 시간 제한 간격 설정

사용자 지정 기술의 인터페이스는 사용자 지정 웹 API 기술을 통해 지정됩니다.

"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "This skill has a 230 second timeout",
"uri": "https://[your custom skill uri goes here]",
"authResourceId": "[for managed identity connections, your app's client ID goes here]",
"timeout": "PT230S",

URI는 함수 또는 앱의 HTTPS 엔드포인트입니다. URI를 설정할 때 URI가 안전한지(HTTPS) 확인합니다. 코드가 Azure 함수 앱에서 호스트되는 경우 요청을 승인하려면 URI에 헤더에 API 키를 포함하거나 URI 매개 변수로 포함해야 합니다.

대신 함수 또는 앱이 인증 및 권한 부여를 위해 Azure 관리 ID 및 Azure 역할을 사용하는 경우 사용자 지정 기술은 요청에 인증 토큰을 포함할 수 있습니다. 다음 사항은 이 방식에 대한 요구 사항을 설명합니다.

인덱서를 대신하여 요청을 보내는 검색 서비스는 호출자가 Microsoft Entra ID에서 인증될 수 있도록 관리 ID를 사용하도록 구성(시스템 또는 사용자 할당)되어야 합니다.
함수 또는 앱은 Microsoft Entra ID용으로 구성되어야 합니다.
사용자 지정 기술 정의에는 authResourceId 속성이 포함되어야 합니다. 이 속성은 지원되는 형식(api://<appId>)으로 애플리케이션(클라이언트) ID를 사용합니다.

기본적으로 30초 기간(PT30S) 내에 응답이 반환되지 않으면 엔드포인트에 대한 연결 시간이 초과됩니다. 인덱싱 파이프라인은 동기식이며 해당 시간 프레임에 응답이 수신되지 않으면 인덱싱에서 시간 초과 오류가 발생합니다. timeout 매개 변수(PT230S)를 설정하여 간격을 최댓값인 230초로 늘릴 수 있습니다.

웹 API 입력 형식 지정

Web API가 처리할 레코드 배열을 수락해야 합니다. 각 레코드 내에서 웹 API에 대한 입력으로 속성 모음을 제공합니다.

계약 텍스트에 언급된 첫 번째 날짜를 식별하는 기본 보강자를 만든다고 가정해 보세요. 이 예에서 사용자 지정 기술은 단일 입력 "contractText"를 계약 텍스트로 허용합니다. 또한 기술에는 계약 날짜인 단일 출력이 있습니다. 이 보강자에서 더 흥미로운 점은 이 "contractDate"를 다중 파트 복합 형식의 형태로 반환한다는 것입니다.

Web API가 입력 레코드 배치를 수신할 준비가 되어 있어야 합니다. "values" 배열의 각 멤버는 특정 레코드의 입력을 나타냅니다. 각 레코드에 다음 요소가 있어야 합니다.

특정 레코드의 고유 식별자인 "recordId" 멤버. 보강자는 결과를 반환할 때 호출자가 레코드 결과를 입력과 일치시킬 수 있도록 이 "recordId"를 제공해야 합니다.
기본적으로 각 레코드의 입력 필드 모음인 "data" 멤버.

결과 웹 API 요청은 다음과 같습니다.

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issues on November 3, 2023 and that involves... "
           }
      },
      {
        "recordId": "b5",
        "data":
           {
             "contractText": 
                "In the City of Seattle, WA on February 5, 2018 there was a decision made..."
           }
      },
      {
        "recordId": "c3",
        "data":
           {
             "contractText": null
           }
      }
    ]
}

실제로는 여기에 표시된 세 개의 레코드 대신 수백 또는 수천 개의 레코드로 코드를 호출할 수 있습니다.

웹 API 출력 형식 지정

출력 형식은 "recordId"와 속성 모음을 포함하는 레코드 집합입니다. 이 특정 예제에는 하나의 출력만 있지만, 둘 이상의 속성을 출력할 수 있습니다. 가장 좋은 방법은 레코드를 처리할 수 없는 경우 오류 및 경고 메시지를 반환하는 것입니다.

{
  "values": 
  [
      {
        "recordId": "b5",
        "data" : 
        {
            "contractDate":  { "day" : 5, "month": 2, "year" : 2018 }
        }
      },
      {
        "recordId": "a1",
        "data" : {
            "contractDate": { "day" : 3, "month": 11, "year" : 2023 }                    
        }
      },
      {
        "recordId": "c3",
        "data" : 
        {
        },
        "errors": [ { "message": "contractText field required "}   ],  
        "warnings": [ {"message": "Date not found" }  ]
      }
    ]
}

기술 세트에 사용자 지정 기술 추가

Web API 보강자를 만들 때 요청의 일부로 HTTP 헤더 및 매개 변수를 설명할 수 있습니다. 다음 코드 조각은 요청 매개 변수 및 선택적 HTTP 헤더가 기술 집합 정의에 포함될 수 있는 방법을 보여 줍니다. HTTP 헤더 설정은 구성 설정을 코드에 전달해야 하는 경우에 유용합니다.

{
    "skills": [
      {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "name": "myCustomSkill",
        "description": "This skill calls an Azure function, which in turn calls TA sentiment",
        "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/DateExtractor?language=en",
        "context": "/document",
        "httpHeaders": {
            "DateExtractor-Api-Key": "foo"
        },
        "inputs": [
          {
            "name": "contractText",
            "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "contractDate",
            "targetName": "date"
          }
        ]
      }
  ]
}

이 비디오 보기

동영상 소개 및 데모를 보려면 다음 데모를 시청합니다.

다음 단계

이 문서에서는 사용자 지정 기술을 기술 세트에 통합하는 데 필요한 인터페이스 요구 사항에 대해 다룹니다. 사용자 지정 기술 및 기술 집합 구성에 대해 자세히 알아보려면 이 링크를 계속 진행합니다.

다음을 통해 공유