Azure AI 검색 보강 파이프라인의 사용자 지정 Web API 기술

아티클
04/17/2024

사용자 지정 Web API 기술을 사용하면 사용자 지정 작업을 제공하는 Web API 엔드포인트를 호출하여 AI 보강을 확장할 수 있습니다. 기본 제공 기술과 비슷하게 사용자 지정 Web API 기술에는 입/출력이 있습니다. 입력에 따라, 인덱서가 실행될 때 Web API는 JSON 페이로드를 수신하고, 성공 상태 코드와 함께 JSON 페이로드를 응답으로 출력합니다. 응답은 사용자 지정 기술로 지정된 출력을 포함해야 합니다. 다른 응답은 오류로 간주되며 강화는 수행되지 않습니다. JSON 페이로드의 구조는 이 문서의 아래쪽에 자세히 설명되어 있습니다.

사용자 지정 Web API 기술은 Azure OpenAI On Your Data 기능 구현에도 사용됩니다. Azure OpenAI가 역할 기반 액세스를 위해 구성되고 벡터 인덱스를 만들 때 403 Forbidden 호출을 받는 경우 Azure AI 검색에 시스템 할당 ID가 있고 Azure OpenAI에서 신뢰할 수 있는 서비스로 실행되는지 확인합니다.

참고 항목

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

502 Bad Gateway
503 Service Unavailable
429 Too Many Requests

@odata.type

Microsoft.Skills.Custom.WebApiSkill

기술 매개 변수

매개 변수는 대/소문자를 구분합니다.

매개 변수 이름	설명
`uri`	JSON 페이로드가 전송되는 웹 API의 URI입니다. https URI 체계만 허용됩니다.
`authResourceId`	(선택 사항) 설정된 경우 이 기술이 코드를 호스팅하는 함수 또는 앱에 대한 연결에서 관리 ID를 사용해야 함을 나타내는 문자열입니다. 이 속성은 지원되는 형식: `api://<appId>`의 Microsoft Entra ID에서 애플리케이션(클라이언트) ID 또는 앱 등록을 사용합니다. 이 값은 인덱서가 검색한 인증 토큰의 범위를 지정하는 데 사용되며 사용자 지정 웹 기술 API 요청과 함께 함수 또는 앱으로 전송됩니다. 이 속성을 설정하려면 검색 서비스가 관리 ID용으로 구성되고 Azure 함수 앱이 Microsoft Entra 로그인용으로 구성되어야 합니다. 이 매개 변수를 사용하려면 `api-version=2023-10-01-Preview`를 사용하여 API를 호출합니다.
`httpMethod`	페이로드를 보내는 데 사용하는 메서드입니다. 허용되는 메서드는 `PUT` 또는 `POST`입니다.
`httpHeaders`	키-값 쌍 컬렉션입니다. 여기서 키는 헤더 이름을 나타내고, 값은 페이로드와 함께 Web API로 보낼 헤더 값을 나타냅니다. 헤더 `Accept`, `Accept-Charset`, `Accept-Encoding`, `Content-Length`, `Content-Type`, `Cookie`, `Host`, `TE`, `Upgrade`, `Via`는 이 컬렉션에서 금지됩니다.
`timeout`	(선택 사항) 지정할 경우 API 호출을 수행하는 http 클라이언트에 대한 시간 제한을 나타냅니다. 형식은 XSD "dayTimeDuration" 값( ISO 8601 기간 값의 제한된 하위 집합)이어야 합니다. 예를 들어, 60초인 경우 `PT60S`입니다. 설정하지 않으면 기본값 30초가 선택됩니다. 시간 제한은 최대 230초, 최소 1초로 설정할 수 있습니다.
`batchSize`	(선택 사항) API 호출당 전송되는 "데이터 레코드"(아래 JSON 페이로드 구조 참조) 수를 나타냅니다. 설정하지 않으면 기본값인 1,000이 선택됩니다. 인덱싱 처리량과 API의 부하 간에 적절한 절충을 이루려면 이 매개 변수를 사용하는 것이 좋습니다.
`degreeOfParallelism`	(선택 사항) 지정된 경우 인덱서가 제공된 엔드포인트와 병렬로 수행하는 호출 수를 나타냅니다. 엔드포인트가 압력을 받고 실패하는 경우 이 값을 줄이거나 엔드포인트가 로드를 처리할 수 있는 경우 값을 높일 수 있습니다. 설정하지 않으면 기본값으로 5초가 사용됩니다. `degreeOfParallelism`은 최대 10자, 최소 1자로 설정할 수 있습니다.

기술 입력

이 기술에 대해 미리 정의된 입력은 없습니다. 입력은 사용자 지정 기술에 전달하려는 기존 필드 또는 보강 트리의 노드입니다.

기술 출력

이 기술에 대해 미리 정의된 출력은 없습니다. 기술의 출력을 검색 인덱스의 필드로 보내야 하는 경우 인덱서에서 출력 필드 매핑을 정의해야 합니다.

샘플 정의

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "batchSize": 4,
  "context": "/document",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    },
    {
      "name": "language",
      "source": "/document/languageCode"
    },
    {
      "name": "phraseList",
      "source": "/document/keyphrases"
    }
  ],
  "outputs": [
    {
      "name": "hitPositions"
    }
  ]
}

샘플 입력 JSON 구조

이 JSON 구조는 웹 API로 전송되는 페이로드를 나타냅니다. 항상 다음 제약 조건을 따릅니다.

최상위 엔터티는 values라고 하며 개체 배열입니다. 그러한 개체의 수는 최대 batchSize가 됩니다.
values 배열의 각 개체에는 다음이 포함됩니다.
- 해당 레코드 식별에 사용되는 고유 문자열인 recordId 속성
- JSON 개체에 해당하는 data 속성. data 속성의 필드는 기술 정의의 inputs 섹션에 지정된 "이름"에 해당합니다. 해당 필드의 값은 해당 필드의 source(문서의 필드 또는 잠재적으로 다른 기술의 필드일 수 있음)에서 가져온 것입니다.

{
    "values": [
      {
        "recordId": "0",
        "data":
           {
             "text": "Este es un contrato en Inglés",
             "language": "es",
             "phraseList": ["Este", "Inglés"]
           }
      },
      {
        "recordId": "1",
        "data":
           {
             "text": "Hello world",
             "language": "en",
             "phraseList": ["Hi"]
           }
      },
      {
        "recordId": "2",
        "data":
           {
             "text": "Hello world, Hi world",
             "language": "en",
             "phraseList": ["world"]
           }
      },
      {
        "recordId": "3",
        "data":
           {
             "text": "Test",
             "language": "es",
             "phraseList": []
           }
      }
    ]
}

샘플 출력 JSON 구조

“출력”은 Web API에서 반환되는 응답에 해당합니다. 이 Web API는 JSON 페이로드(Content-Type 응답 헤더를 보고 확인)만 반환해야 하며 다음 제약 조건을 충족해야 합니다.

개체 배열에 해당하는 values라는 최상위 엔터티가 있어야 합니다.
배열의 개체 수는 Web API로 보낸 개체 수와 같아야 합니다.
각 개체에는 다음이 지정되어야 합니다.
- recordId 속성입니다.
- data 속성: 필드가 output의 “names”와 일치하는 강화에 해당하는 개체이며, 해당 값이 보강으로 간주됩니다.
- errors 속성은 인덱서 실행 기록에 추가되어 발생한 오류를 나열하는 배열입니다. 이 속성은 필요하지만 값이 null일 수 있습니다.
- warnings 속성은 인덱서 실행 기록에 추가되고 발생한 모든 경고를 나열하는 배열입니다. 이 속성은 필요하지만 값이 null일 수 있습니다.
요청 또는 응답에서 values의 개체 순서는 중요하지 않습니다. 그러나 recordId는 상관 관계에 사용되므로 웹 API에 대한 원래 요청의 일부가 아닌 recordId를 포함하는 응답의 모든 레코드는 삭제됩니다.

{
    "values": [
        {
            "recordId": "3",
            "data": {
            },
            "errors": [
              {
                "message" : "'phraseList' should not be null or empty"
              }
            ],
            "warnings": null
        },
        {
            "recordId": "2",
            "data": {
                "hitPositions": [6, 16]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "0",
            "data": {
                "hitPositions": [0, 23]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "1",
            "data": {
                "hitPositions": []
            },
            "errors": null,
            "warnings": [
              {
                "message": "No occurrences of 'Hi' were found in the input text"
              }
            ]
        },
    ]
}

오류 사례

Web API가 사용 가능하지 않거나 성공적이지 않은 상태 코드를 보내는 경우 외에도 다음과 같은 경우가 오류로 간주됩니다.

웹 API가 성공 상태 코드를 반환했지만 응답에 application/json이 아닌 것으로 나타나면 해당 응답은 유효하지 않은 것으로 간주되어 보강이 수행되지 않습니다.
응답 values 배열에 유효하지 않은 레코드(예: recordId가 누락되었거나 중복됨)가 있는 경우 유효하지 않은 레코드에 대해 보강이 수행되지 않습니다. 사용자 지정 기술을 개발할 때 Web API 기술 계약을 준수하는 것이 중요합니다. 예상 계약을 따르는 Power Skill 리포지토리에 제공된 이 예제를 참조할 수 있습니다.

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