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

메모

Foundry IQ (Azure AI 검색)는 관리 검색을 위해 고급 수준의 지식 원본 API 및 지식 베이스 API와 함께 직접 인덱싱 및 쿼리 API를 제공합니다. Azure 포털, REST API 또는 Azure SDK 사용하여 이러한 기능을 구성하거나 Microsoft Foundry 포털의 기술 자료에 에이전트를 연결합니다.

사용자 지정 Web API 벡터라이저를 사용하면 쿼리 시간에 포함을 생성하는 웹 API 엔드포인트를 호출하도록 검색 쿼리를 구성할 수 있습니다. 엔드포인트에 필요한 JSON 페이로드 구조는 이 문서의 뒷부분에 설명되어 있습니다. 데이터는 모델이 배포되는 geography에서 처리됩니다.

벡터라이저는 쿼리 시점에 사용되지만, 인덱스 정의에서 이를 지정하고 벡터 프로필을 통해 벡터 필드에 참조하도록 구성합니다. 자세한 내용은 검색 인덱스에서 벡터라이저 구성을 참조하세요.

사용자 지정 웹 API 벡터라이저는 REST API에서 호출 WebApiVectorizer 됩니다. 안정적인 최신 버전의 인덱스 - 만들기(REST API) 또는 기능을 제공하는 Azure SDK 패키지를 사용합니다.

벡터라이저 매개 변수

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

매개 변수 이름 설명
uri JSON 페이로드가 전송되는 웹 API의 URI입니다. https URI 체계만 허용됩니다. GET 및 LIST 응답은 sig 및 code를 포함한 민감한 쿼리 값을 마스킹합니다. 저장된 URI를 변경하지 않고 벡터라이저를 업데이트하려면 uri 전체를 <unchanged>로 설정합니다. 반환되는 자리 표시자와 일치 규칙은 RI 숨김 처리 및 자격 증명 보존 업데이트를 참조하세요.
httpMethod 페이로드를 보내는 데 사용되는 메서드입니다. 허용되는 메서드는 다음과 PUT같습니다POST.
httpHeaders 키가 헤더 이름이고 값이 웹 API로 전송되는 키-값 쌍의 컬렉션입니다. 다음 헤더는 금지되어 있습니다: Accept, Accept-Charset, Accept-Encoding, Content-Length, Content-Type, Cookie, Host, TE, Upgrade, 및 Via. GET 및 LIST 응답은 모든 헤더 값에 대해 <redacted>를 반환합니다. 업데이트 요구 사항은 GET 후 헤더 값 업데이트를 참조하세요.
authResourceId (선택 사항) 설정된 경우 이 벡터라이저가 코드를 호스팅하는 함수 또는 앱에 대한 연결에 관리 ID를 사용한다는 것을 나타내는 문자열입니다. 이 속성은 api://<appId>, <appId>/.default, api://<appId>/.default 형식 중 하나로 Microsoft Entra ID 애플리케이션(클라이언트) ID 또는 앱 등록을 사용합니다. 이 값은 쿼리 파이프라인에서 검색하고 사용자 지정 웹 API 요청과 함께 함수 또는 앱으로 전송되는 인증 토큰의 범위를 지정합니다. 이 속성을 설정하려면 Foundry IQ 서비스는 관리 ID를 사용하도록 구성되고 Azure 함수 앱은 Microsoft Entra 로그인을 사용하도록 구성되어야 합니다.
authIdentity (선택 사항) Foundry IQ 서비스에서 코드를 호스팅하는 함수 또는 앱에 연결하는 데 사용하는 사용자 관리 ID입니다. 시스템 관리 ID 또는 사용자 관리 ID를 사용할 수 있습니다. 시스템 관리 ID를 사용하려면 비워 둡니다 authIdentity .
timeout (선택 사항) API 호출을 수행하는 HTTP 클라이언트의 타임아웃입니다. XSD dayTimeDuration 값( ISO 8601 기간 값의 제한된 하위 집합)으로 서식을 지정해야 합니다. 예를 들어 PT60S 60초를 의미합니다. 설정하지 않으면 기본값은 30초입니다. 시간 제한은 1초에서 230초 사이일 수 있습니다.

지원되는 벡터 쿼리 형식

사용자 지정 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": "<your-header-value>"
            },
            "timeout": "PT60S",
            "authResourceId": null,
            "authIdentity": null
        }
    }
]

GET 후 헤더 값 업데이트

GET을 사용하여 인덱스 정의를 검색하거나 LIST를 사용하여 인덱스를 나열하면 서비스는 사용자 지정 Web API 벡터라이저의 모든 <redacted> 값에 대해 httpHeaders를 반환합니다. 다음은 그 예입니다.

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

저장된 api-key 값을 다시 사용하려면 같은 기존 벡터라이저를 같은 name, kind 엔드포인트로 업데이트합니다. 일치하는 헤더 이름에 대해 반환된 자리 표시자를 다시 제출합니다.

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

같은 기존 벡터라이저와 엔드포인트의 경우 유지할 헤더 값에는 <redacted> 또는 <unchanged>를 사용하고, 나머지에는 실제 대체 값을 함께 사용할 수 있습니다. 명시적 값이 자리 표시자보다 우선합니다. 자리 표시자에 명확한 기존 원본이 필요하기 때문에 추가되거나 이름이 바뀐 각 헤더에 대한 실제 값을 제공하세요. URI 쿼리 변경 내용은 URI 리다크션 및 자격 증명 유지 업데이트를 참조하세요.

엔드포인트를 변경하는 경우 동일한 업데이트에서 실제 URI 및 헤더 비밀도 함께 제공하세요. 서비스는 저장된 비밀을 다른 엔드포인트에 재사용하지 않습니다.

{
    "name": "my-custom-web-api-vectorizer",
    "kind": "customWebApi",
    "customWebApiParameters": {
        "uri": "https://new.contoso.embeddings.com",
        "httpMethod": "POST",
        "httpHeaders": {
            "api-key": "<new-header-value>"
        },
        "timeout": "PT60S",
        "authResourceId": null,
        "authIdentity": null
    }
}

자격 증명을 사용할 수 없는데 엔드포인트를 변경해야 하는 경우 외부 엔드포인트에서 자격 증명을 순환하거나 다시 생성합니다. 그런 다음 새 uri 값과 헤더 값을 함께 제출합니다.

<redacted> 값은 서비스 센티널이며 자격 증명이 아닙니다. 벡터라이저를 만들거나 다른 벡터라이저에 대해 저장된 헤더 값을 검색하거나 다시 사용할 수 없습니다.

새 인덱스, 이름이 바뀐 벡터라이저 또는 다른 서비스의 경우 대상 URI 쿼리 및 헤더 자격 증명을 제공합니다. 관리 ID의 경우 지원되는 인증 속성 및 대상 권한 부여를 명시적으로 구성합니다.

URI 숨김 처리 및 자격 증명 보존 업데이트

이 URI 쿼리 동작은 모든 API 버전에 적용됩니다.

LIST를 사용하여 인덱스를 검색하거나 인덱스를 나열하면 Foundry IQ는 중요한 사용자 지정 Web API URI 쿼리 값(sig 및 code 포함)과 HTTP 헤더 값을 가립니다. 숨김 처리된 이러한 값은 SAS(공유 액세스 서명) 서명, 함수 키, 헤더 자격 증명을 보호합니다.

저장된 비밀을 유지하려면 동일한 벡터라이저 이름, 종류 및 엔드포인트로 동일한 기존 인덱스 및 벡터라이저를 업데이트하세요. 반환된 <redacted> 또는 <unchanged> 자리 표시자를 관리 PUT 요청의 전체 인덱스 정의에 제출합니다. 보존된 헤더는 기존 헤더 이름과 일치해야 합니다. 이 PUT은 인덱스 정의를 업데이트하는 요청이며, 벡터라이저의 httpMethod에 의해 제어되는 엔드포인트 호출이 아닙니다. 저장된 URI를 유지하도록 <unchanged> 전체를 uri로 설정할 수도 있습니다.

비밀 값은 다른 엔드포인트로 전달되거나 새 리소스에 복사되지 않습니다. 엔드포인트를 변경하거나, 숨김 처리된 정의를 복제하거나, 그 밖의 방식으로 리소스를 다시 지정하려면 명시적인 비밀이 필요합니다.

서비스가 자리 표시자에 대해 명확한 기존 원본을 하나로 식별할 수 없으면 PUT이 400 Bad Request로 실패하고 실제 비밀 값을 요청합니다. 확인되지 않았거나 저장된 자리 표시자는 사용할 수 있는 자격 증명이 아닙니다. 비밀 복원은 원자성입니다. 실패한 복원은 URI 또는 헤더 변경 내용을 부분적으로 적용하지 않습니다.

언제든지 대체 URI 또는 헤더 비밀을 제공할 수 있습니다. 명시적 값이 자리 표시자보다 우선합니다.

URI 쿼리 업데이트는 다음 규칙을 따릅니다.

  • Azure 함수 code 매개 변수의 경우 동일한 엔드포인트에 대해 저장된 함수 키를 유지하면서 다른 비밀이 아닌 쿼리 매개 변수를 업데이트할 수 있습니다.
  • SAS sig 매개 변수의 경우 서명은 주변 비비밀 쿼리 구성에 바인딩됩니다. 범위, 사용 권한, 만료, 리소스, 버전, 순서 지정, 대/소문자 또는 인코딩이 변경되는 경우 새 서명을 제공하세요. 의미적으로 동등하지만 순서가 바뀌거나 다시 인코딩된 쿼리 텍스트에도 새 서명이 필요합니다.

비밀 쿼리 매개 변수 이름은 대/소문자를 구분하지 않고 퍼센트 인코딩된 경우에도 인식됩니다. 서비스는 URI 표현을 정규화하지 않고 사용자의 URI 표현을 유지합니다. 반복되는 비밀 매개 변수는 나타나는 순서에 따라 일치시킵니다. 해당 발생 패턴이 저장된 URI와 더 이상 일치하지 않는 경우 실제 값을 제공하세요.

<redacted> 또는 <unchanged>를 사용하는 기존 GET-then-PUT 워크플로는 계속 지원됩니다. 헤더 예제는 GET 이후의 헤더 값 업데이트를 참조하세요.

사용자 지정 기술은 사용자 지정 Web API 기술 URI 민감 정보 숨김 및 자격 증명 유지 업데이트를 참조하세요.

이러한 URI 및 헤더 규칙은 다른 벡터라이저 형식 또는 속성에 대한 보존 지원을 설정하지 않습니다. 대상 종속성 검사 및 안전한 복원 절차에 대해서는 인덱스 백업, 복원 또는 복제를 참조하세요.

JSON 페이로드 구조

사용자 지정 Web API 벡터라이저와 함께 사용되는 엔드포인트에 필요한 JSON 페이로드 구조는 사용자 지정 Web API 기술에서 사용하는 구조와 동일합니다. 자세한 내용은 기술 설명서를 참조하세요.

사용자 지정 Web API 벡터라이저에 대한 웹 API 엔드포인트를 구현할 때는 다음 사항을 고려해야 합니다.

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

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

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

  • 벡터라이저는 엔드포인트에서 반환된 오류 또는 경고를 무시합니다. 이러한 오류 및 경고는 쿼리 시간 디버깅에 사용할 수 없습니다.

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

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

참고 사항