다음을 통해 공유

사용자 지정 Web API 벡터라이저

  • 아티클

Important

이 기능은 추가 사용 약관에 따라 공개 미리 보기로 제공됩니다. 2023-10-01-Preview REST API 및 모든 최신 미리 보기 REST API는 이 기능을 지원합니다.

사용자 지정 웹 API 벡터라이저를 사용하면 Web API 엔드포인트를 호출하여 쿼리 시 임베딩을 생성하도록 검색 쿼리를 구성할 수 있습니다. 제공된 엔드포인트에서 구현하는 데 필요한 JSON 페이로드의 구조를 이 문서에서 자세히 설명합니다. 데이터는 모델이 배포된 지역에서 처리됩니다.

벡터라이저 매개 변수

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

매개 변수 이름 설명
uri JSON 페이로드가 전송되는 웹 API의 URI입니다. https URI 체계만 허용됩니다.
httpMethod 페이로드를 보내는 데 사용하는 메서드입니다. 허용되는 메서드는 PUT 또는 POST입니다.
httpHeaders 키-값 쌍 컬렉션입니다. 여기서 키는 헤더 이름을 나타내고, 값은 페이로드와 함께 Web API로 보낼 헤더 값을 나타냅니다. 헤더 Accept, Accept-Charset, Accept-Encoding, Content-Length, Content-Type, Cookie, Host, TE, Upgrade, Via는 이 컬렉션에서 금지됩니다.
authResourceId (선택 사항) 설정된 경우 이 벡터라이저가 코드를 호스팅하는 함수 또는 앱에 대한 연결에서 관리 ID를 사용해야 함을 나타내는 문자열입니다. 이 속성은 지원되는 형식: api://<appId>의 Microsoft Entra ID에서 애플리케이션(클라이언트) ID 또는 앱 등록을 사용합니다. 이 값은 인덱서가 검색한 인증 토큰의 범위를 지정하는 데 사용되며 사용자 지정 웹 API 요청과 함께 함수 또는 앱으로 전송됩니다. 이 속성을 설정하려면 검색 서비스가 관리 ID용으로 구성되고 Azure 함수 앱이 Microsoft Entra 로그인용으로 구성되어야 합니다.
authIdentity (선택 사항) 코드를 호스트하는 함수 또는 앱에 연결하기 위해 검색 서비스에서 사용하는 사용자 관리 ID입니다. 시스템 관리 ID 또는 사용자 관리 ID를 지정할 수 있습니다. 시스템 관리 ID를 사용하려면 authIdentity을 비워 둡니다.
timeout (선택 사항) 지정할 경우 API 호출을 수행하는 http 클라이언트에 대한 시간 제한을 나타냅니다. 형식은 XSD "dayTimeDuration" 값( ISO 8601 기간 값의 제한된 하위 집합)이어야 합니다. 예를 들어, 60초인 경우 PT60S입니다. 설정하지 않으면 기본값 30초가 선택됩니다. 시간 제한은 최대 230초, 최소 1초로 설정할 수 있습니다.

지원되는 벡터 쿼리 형식

사용자 지정 Web API 벡터라이저는 text, imageUrl 및 imageBinary 벡터 쿼리를 지원합니다.

샘플 정의

"vectorizers": [
    {
        "name": "my-custom-web-api-vectorizer",
        "kind": "customWebApi",
        "customWebApiParameters": {
            "uri": "https://contoso.embeddings.com",
            "httpMethod": "POST",
            "httpHeaders": {
                "api-key": "0000000000000000000000000000000000000"
            },
            "timeout": "PT60S",
            "authResourceId": null,
            "authIdentity": null
        },
    }
]

JSON 페이로드 구조

엔드포인트를 사용자 지정 웹 API 벡터라이저와 함께 사용할 때 엔드포인트에 필요한 필수 JSON 페이로드 구조는 사용자 지정 웹 API 기술과 동일합니다. 이와 관련하여 기술 설명서에서 더 자세히 설명합니다.

사용자 지정 웹 API 벡터라이저와 함께 사용할 웹 API 엔드포인트를 구현할 때 고려해야 할 기타 사항은 다음과 같습니다.

  • 벡터라이저는 엔드포인트에 요청할 때 values 배열에서 한 번에 하나의 레코드만 보냅니다.

  • 벡터라이저는 요청 페이로드의 data JSON 개체에 있는 특정 키에서 벡터화할 데이터를 전달합니다. 이 키는 요청된 벡터 쿼리 유형에 따라 text, imageUrlimageBinary이 됩니다.

  • 벡터라이저는 결과 임베딩이 응답 페이로드의 data JSON 개체에 있는 vector 키 아래에 있을 것으로 예상합니다.

  • 엔드포인트에서 반환된 오류 또는 경고는 벡터라이저에서 무시되며 쿼리 시 디버깅 목적으로 가져올 수 없습니다.

  • imageBinary 벡터 쿼리가 요청된 경우 엔드포인트로 전송된 요청 페이로드는 다음과 같습니다.

    {
    "values": [
        {
            "recordId": "0",
            "data":
            {
                "imageBinary": {
                    "data": "<base 64 encoded image binary data>"
                }
            }
        }
    ]
}

참고 항목