Azure OpenAI 벡터라이저

참고

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

Azure OpenAI 벡터라이저는 Azure Foundry 모델의 OpenAI 리소스 또는 Microsoft Foundry 프로젝트에 배포된 포함 모델에 연결하여 쿼리 시 포함을 생성합니다. 데이터는 모델이 배포된 지오(Geo )에서 처리됩니다.

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

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

참고

이 벡터라이저는 Azure OpenAI에 바인딩되며 Azure OpenAI 표준 가격 요금이 청구됩니다.

필수 구성 요소

  • 파운드리 모델에서의 Azure OpenAI 리소스 또는 파운드리 프로젝트.

    • Azure OpenAI 자원에는 같은 https://<resource-name>.openai.azure.com가 있어야 합니다. 이 엔드포인트는 Azure 포털의 Keys and Endpoint 페이지에서 찾을 수 있으며, 이 스킬의 resourceUri 속성에 사용할 수 있습니다.

    • Foundry 프로젝트의 상위 리소스는 , , https://<resource-name>.openai.azure.com, 등 https://<resource-name>.services.ai.azure.com여러 엔드포인트https://<resource-name>.cognitiveservices.azure.com에 접근할 수 있도록 합니다. 이 엔드포인트는 Azure 포털의 Keys 및 Endpoint 페이지에서 찾을 수 있으며, 이 스킬의 resourceUri 속성에 사용할 수 있습니다.

  • 귀하의 리소스나 프로젝트에 배포된 Azure OpenAI 임베딩 모델입니다. 지원되는 모델은 다음 섹션을 참조하세요.

벡터라이저 매개 변수

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

매개 변수 이름 설명
resourceUri (필수) 모델 리소스 기본 URI입니다. 지원되는 리소스 도메인은 다음과 같습니다.

  • openai.azure.com
  • services.ai.azure.com
  • cognitiveservices.azure.com

Azure API Management HTTPS 게이트웨이 기본 URI도 기본 azure-api.net 호스트 및 구성된 사용자 지정 도메인을 포함하여 지원됩니다. 별도로 설정합니다 deploymentId . 전체 포함 작업 URL을 제공하지 않습니다. 라우팅, 인증, RBAC 및 프라이빗 연결 요구 사항은 Azure AI 검색(Foundry IQ) 모델 호출에서 API Management 사용을 참조하세요.

apiKey 모델에 접근하는 데 사용된 비밀 키입니다. 하나의 인증 방법만 구성합니다. 키를 사용할 때는 authIdentity은 비워 둡니다.
deploymentId (필수) 배포된 Azure OpenAI 임베딩 모델의 ID입니다. 이것은 모델을 배포할 때 지정한 배포 이름입니다.
authIdentity 연결에 사용되는 사용자 할당 관리 ID 입니다. Foundry IQ 서비스의 시스템 할당 ID를 사용하려면 apiKey 및 authIdentity를 모두 생략합니다. 직접 호출 또는 토큰 통과의 경우 모델을 호스팅하는 Azure OpenAI 또는 상위 Foundry 리소스에 Cognitive Services OpenAI User를 할당합니다. ID 선택 및 별도의 게이트웨이/백엔드 할당에 대해서는 역할 범위 및 ID 식별자를 참조하세요.
modelName (필수) 지정된 deploymentId에 배포된 Azure OpenAI 모델의 이름입니다. 지원되는 값은 다음과 같습니다:

  • text-embedding-ada-002
  • text-embedding-3-large
  • text-embedding-3-small

지원되는 벡터 쿼리 형식

Azure OpenAI 벡터라이저는 text 벡터 쿼리만 지원합니다.

API Management 엔드포인트, 인증 및 프라이빗 네트워크 요구 사항은 Foundry IQ 모델 호출에 API Management 사용을 참조하세요.

예상 필드 크기

Azure OpenAI 벡터라이저로 구성된 필드에 대한 예상 필드 차원은 구성된 modelName 따라 달라집니다.

modelName 최소 차원 최대 크기
text-embedding-ada-002 1536 1536
text-embedding-3-large 1 3072
text-embedding-3-small (텍스트 임베딩 3 스몰) 1 1536

샘플 정의

다음 인덱스 정의 조각은 직접 Azure OpenAI 연결을 구성합니다. 요청을 보내기 전에 자격 증명으로 바꿉 <api-key> 다.

{
  "vectorizers": [
    {
        "name": "my-openai-vectorizer",
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
            "resourceUri": "https://my-fake-azure-openai-resource.openai.azure.com",
            "apiKey": "<api-key>",
            "deploymentId": "my-ada-002-deployment",
            "authIdentity": null,
            "modelName": "text-embedding-ada-002"
        }
    }
  ]
}

API Management 사용자 지정 도메인 예제

이 인덱스 정의 조각은 API Management 사용자 지정 게이트웨이 도메인 및 Foundry IQ 서비스의 시스템 할당 ID를 사용하여 벡터라이저를 구성합니다. 호스트 이름 및 배포 이름을 사용자의 값으로 바꾸세요. 대신 기본 게이트웨이 도메인을 사용하려면 https://<apim-name>.azure-api.net을(를) resourceUri(으)로 설정합니다.

{
  "vectorizers": [
    {
      "name": "apim-embedding",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://apim.contoso.com",
        "deploymentId": "my-text-embedding-3-small",
        "modelName": "text-embedding-3-small"
      }
    }
  ]
}

참조: 인덱스 - 만들기

인덱싱 시 사용되는 임베딩 모델과 일치하는 벡터 프로필에서 이 벡터라이저를 선택합니다. 연결된 사용자 할당 검색 ID를 대신 선택하려면 다음 개체를 azureOpenAIParameters 안에 추가합니다.

{
  "authIdentity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>"
  }
}

키 인증의 경우 apiKey를 제공하고 authIdentity는 생략합니다. Search는 키를 api-key 헤더에 전송합니다. 네이티브 임베딩 경로 및 인증에 대한 게이트웨이를 구성합니다.

성능 모범 사례

다음은 이 벡터라이저를 사용할 때 고려해야 하는 몇 가지 모범 사례입니다.

  • Azure OpenAI TPM(분당 토큰) 한도에 도달했다면, quota limits advisory를 참고해 적절히 대응할 수 있습니다. Azure OpenAI 인스턴스 성능에 대한 자세한 내용은 Azure OpenAI monitoring 문서를 참고하세요.

  • 이 벡터라이저에 사용하는 Azure OpenAI embeddings 모델 배포는 embedding skill 포함하여 다른 사용 사례에 사용되는 배포와 이상적으로 분리되어야 합니다. 이로 인해 각 배포가 특정 사용 사례에 맞게 맞춤화되어 최적화된 성능과 인덱서 및 인덱스 임베딩 호출의 트래픽 식별이 용이해집니다.

  • Azure OpenAI 인스턴스는 동일한 지역에 있거나 적어도 Foundry IQ 서비스가 호스트되는 지역과 지리적으로 가깝습니다. 이로 인해 지연 시간이 줄어들고 서비스 간 데이터 전송 속도가 향상됩니다.

  • 자주 발생하는 429 오류 코드를 방지하려면 여러 Azure OpenAI 포함 모델 배포 앞에서 부하 분산 게이트웨이를 구현하여 API Management를 통해 부하 분산을 구현하는 것이 좋습니다.

  • 할당량 및 제한 설명서에 게시된 기본 Azure OpenAI TPM(분당 토큰) 제한보다 더 큰 제한이 있는 경우, Foundry IQ 팀과 지원 사례를 열어 그에 따라 조정할 수 있습니다. 이렇게 하면 더 높은 한도가 있을 경우 문서화된 기본 TPM 한도 때문에 인덱싱 과정이 불필요하게 느려지지 않도록 도와줍니다.

관리 ID 인증에 대한 보안 고려 사항

Azure OpenAI 벡터라이저가 관리 ID를 사용하는 경우 Foundry IQ는 Cognitive Services 대상 그룹(https://cognitiveservices.azure.com)에 대한 Microsoft Entra 액세스 토큰과 쿼리 텍스트를 구성된 엔드포인트로 resourceUri보냅니다. 이 프로세스는 apiKey으로 사용자 할당 ID를 선택하거나 authIdentity 및 authIdentity를 모두 생략하여 시스템 할당 ID를 사용하는 경우에 적용됩니다.

신뢰하고 제어할 수 있으며 토큰과 텍스트를 모두 수신하도록 의도된 엔드포인트만 구성합니다. 호스트 이름만으로는 소유권이나 신뢰를 입증하지 않습니다. 연결 검사에 의존하여 API Management 게이트웨이가 사용자가 소유한 리소스 앞에 있음을 확인하지 마세요.

발급자, 대상 그룹, 테넌트, 수명 및 필요한 권한을 포함하여 토큰의 서명 및 표준 클레임의 유효성을 검사하도록 수신 엔드포인트를 구성합니다. Foundry IQ 서비스의 관리 ID에 최소 권한을 적용합니다. 게이트웨이 설정 및 별도의 API Management-백엔드 간 ID는 Foundry IQ 모델 호출에서 API Management 사용을 참조하세요.

참고

Foundry Tools audience(대상)에 대해 발급된 관리 ID 토큰은 ID에 권한이 부여된 모든 Foundry Tools 또는 Azure OpenAI 리소스에 대해 유효합니다. 신뢰할 수 없는 엔드포인트로 보내면 토큰이 노출될 수 있습니다.

보안 배포를 유지 관리하려면 다음 방법을 따르세요.

  • resourceUri은(는) 소유하고 신뢰하는 엔드포인트로만 설정하세요. Vectorizer 매개 변수에서 리소스 도메인을 사용합니다. APIM 엔드포인트를 사용하는 경우 관리 ID를 사용하도록 설정하기 전에 라우팅을 확인합니다. 신뢰할 수 있는 호스트 이름은 소유권 증명이 아닙니다.
  • 각 연결에 최소 권한을 적용합니다. 직접 Azure OpenAI 호출 또는 의도적인 토큰 패스스루의 경우, 배포를 호스팅하는 Azure OpenAI 또는 상위 Foundry 리소스에서 선택한 Search ID에 Cognitive Services OpenAI User 역할을 부여합니다. APIM이 검색 인증을 종료하고 자체 ID를 사용하는 경우 APIM에서 검색 권한을 부여하고 검색이 아닌 모델 호스팅 리소스에서 APIM의 ID에 해당 백 엔드 역할을 부여합니다. 지나치게 광범위한 역할은 피하세요.
  • 특정 워크로드에 대한 NSP(네트워크 보안 경계) 및 프라이빗 연결을 평가합니다. 수신기 측에 프라이빗 엔드포인트를 구성하거나 VNet 통합을 설정하는 것만으로는 쿼리 실행 호스트에서의 경로가 프로비저닝되지 않습니다.
  • APIM 엔드포인트를 사용하는 경우 게이트웨이가 인바운드 요청의 유효성을 검사하고 의도한 백 엔드에만 전달해야 합니다. 또한 해당 액세스 정책을 주기적으로 검토해야 합니다.
  • apiKey보다 관리 ID를 선호합니다. apiKey를 사용하는 경우 이를 안전하게 저장하고 정기적으로 교체하며 소스 제어에 포함하지 않습니다. 하나의 인증 방법만 구성합니다.
  • 인덱스 정의, 관리 ID 역할 할당 및 APIM 구성을 주기적으로 검토하여 resourceUri 값, 액세스 제어 및 ID 권한이 최신 상태로 적절하게 유지되는지 확인합니다. 설정된 변경 관리 및 보안 검토 프로세스를 통해 구성 변경 내용을 검토합니다.
  • Azure OpenAI 및 Foundry Tools 로그인 로그, 인증 이벤트 및 액세스 로그를 모니터링하여 예기치 않거나 권한이 없는 활동을 확인합니다.
  • 더 이상 필요하지 않은 사용되지 않는 벡터라이저, 엔드포인트, 역할 할당 및 API 키를 제거합니다.

인덱스 및 벡터라이저 구성에 대한 액세스 제한

인덱스 정의를 만들거나 수정할 수 있는 사용자는 대상 엔드포인트(resourceUri)와 벡터라이저에서 사용하는 인증 구성을 모두 제어합니다. 벡터라이저는 Cognitive Services 대상 그룹에 대한 관리 ID 토큰을 해당 엔드포인트로 보내기 때문에 이러한 권한을 신뢰할 수 있는 관리자로 제한하고 관리 ID 사용 벡터라이저를 구성할 때 표준 변경 관리 및 보안 검토 프로세스를 따릅니다.

관리 설정 properties.dataExfiltrationProtections: ["BlockAll"]이 모든 Azure OpenAI 벡터라이저를 사용 안 함으로 설정한다고 가정하지 마세요. 인덱스 편집 권한을 제한하고 대상, 게이트웨이 정책 및 역할 할당을 검토합니다. 인덱싱에서 동일한 대상 신뢰와 관련된 책임에 대해서는 사용자 지정 Web API 기술 보안 고려 사항을 참조하세요.

참고 사항