Foundry IQ (Azure AI 검색) 모델 호출에 API Management 사용

메모

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

Important

이 문서에서 (미리 보기)로 표시된 기능 또는 성능은 공개 미리 보기로 제공되며 Microsoft Azure 미리 보기에 대한 추가 사용 약관의 적용을 받습니다.

Foundry IQ(Azure AI 검색)에 특정한 미리 보기 약관은 미리 보기 기능을 참조하세요.

지원되는 비-Microsoft 모델을 사용할 때 적용되는 용어는 타사 모델을 참조하세요. API Management가 지원되는 타사 게이트웨이로 라우팅되도록 구성하는 경우 API Management를 통한 타사 게이트웨이를 참조하세요.

Azure API Management를 지원되는 Foundry IQ(Azure AI 검색) 모델 호출을 위한 게이트웨이로 사용하여 라우팅, 제한, 부하 분산 및 모니터링을 중앙 집중화합니다. 지원은 검색 워크로드 및 해당 모델 프로토콜, 인증 및 실행 환경에 따라 달라집니다.

2026-11-01-preview부터 에이전트 검색용 OpenAI 호환 기술 자료 LLM은 전체 엔드포인트 URL을 수락합니다. 이러한 엔드포인트는 API Management, 고객 게이트웨이 또는 직접 구성된 호환되는 타사 공급자일 수 있습니다. 이 지식 베이스 구성에는 API Management가 필요하지 않습니다. Azure OpenAI 설정 및 호환되는 knowledge base 설정에는 서로 다른 스키마가 있습니다.

Prerequisites

  • Foundry IQ 서비스 및 워크로드를 구성할 수 있는 권한입니다. 예를 들어 인덱스 및 기술 자료를 만들거나 업데이트할 수 있도록 Search Service Contributor 역할을 할당합니다. 역할을 사용하여 연결을 참조하세요.
  • 필요한 경우 구조적 출력 및 도구 호출을 포함하여 워크로드에 필요한 프로토콜 및 기능을 구현하는 모델 엔드포인트입니다.
  • API Management의 경우, 검색-게이트웨이 연결과 게이트웨이-백엔드 연결에 대해 별도의 인증이 적용된 구성된 게이트웨이 API 및 백엔드입니다.
  • 호환되는 기술 자료 LLM 및 네이티브 GPT-6 KB 프로필의 경우 기술 자료 만들기, 업데이트 및 검색 요청에 api-version=2026-11-01-preview를 설정합니다. 11월 미리 보기 KB 구성 및 검색 확인을 따릅니다. 다른 구성에 기존 워크로드 API 버전을 사용합니다.
  • 관리형 ID의 경우 활성화된 Foundry IQ 서비스 ID, 수신 엔드포인트에서의 권한 부여, 그리고 필요한 역할을 할당할 수 있는 권한이 필요합니다.

지원되는 워크로드 및 API 선택

다음 표에서는 모델 연결에 대해 설명하며, 모든 프라이빗 네트워크 토폴로지에 대한 인증은 아닙니다. 네트워크 자격에 대해서는 프라이빗 연결을 참조하세요.

업무량 검색 API 가용성 프로토콜 및 모델 선택 엔드포인트 및 인증
Azure OpenAI 임베딩 기술 2023-10-01-preview에서 기본적으로 지원; 안정적인 2024-07-01. 2024-05-01-preview 또는 안정적인 2024-07-01에서 선택할 수 있는 구성 가능한 최신 모델 차원. 임베딩; 임베딩 프로필 3개. 네이티브 리소스 URI 및 배포 ID 기본 및 사용자 지정 API Management 게이트웨이 도메인이 지원됩니다. 네이티브 키 또는 관리 ID입니다.
Azure OpenAI 벡터라이저 2023-10-01-preview의 기본 지원; 안정적인 2024-07-01. 텍스트 쿼리에 대한 임베딩; 임베딩 프로필 3개. 네이티브 리소스 URI 및 배포 ID 기본 및 사용자 지정 API Management 게이트웨이 도메인이 지원됩니다. 네이티브 키 또는 관리 ID입니다.
GenAI 프롬프트 기술 출처: 2025-05-01-preview; GA 2026-04-01. 스킬의 입력 및 생성 매개 변수를 지원하는 엔드포인트와 모델을 사용한 채팅 완료 입력 uri; 기본 또는 사용자 지정 API Management 게이트웨이 도메인입니다. 네이티브 키/ID 속성입니다.
Content Understanding 선택적 LLM 기본 기술 GA 2026-04-01; 선택적 LLM 속성 GA 2026-10-01. 연결된 리소스의 지원되는 모델을 사용하는 Content Understanding 작업 기술 세트에 연결된 Foundry 리소스의 모델 및 배포 설정입니다.
네이티브 KB 검색 모델 기존 네이티브 KB 계약; GPT-6 응답 프로필에는 .2026-11-01-preview 검색은 모델 프로필에서 채팅 완료 또는 응답을 선택합니다. 네이티브 리소스/배포 설정입니다. API Management는 이러한 설정에서 지원되지 않습니다. 게이트웨이 연결에는 별도로 지원되는 호환 KB 미리 보기를 사용하세요.
호환 KB 검색 모델 2026-11-01-preview; 프로필에서 선택한 채팅 완성 또는 응답; 지원되는 KB 프로필 21개. HTTPS POST URL 완료; 헤더 또는 사용자 지정 대상 관리 ID입니다. 웹 지식 소스에서는 지원되지 않습니다.
네이티브 지식 원본 수집 채팅 기존 관리되는 수집 계약입니다. Non-Content Understanding 이미지 언어화는 채팅 완료 요청을 구성합니다. Content Understanding은 자체 작업을 사용합니다. 기본 제공 수집 모델 및 배포 설정.
네이티브 지식 소스 임베딩 기존 관리형 수집 계약. 네이티브 포함. 네이티브 리소스 및 배포 설정.

API Management는 Content Understanding 분석기 요청 또는 선택적 이미지 설명 모델 호출에 대한 게이트웨이로 사용하는 것은 지원되지 않습니다.

호환되는 KB 미리 보기는 검색 모델 구성에만 적용됩니다. 지식 원본 수집 모델 구성을 변경하거나 네이티브 임베딩 기술 및 벡터라이저를 호환되는 공급자 프로토콜로 확장하지 않습니다.

권한으로 보호되는 콘텐츠의 경우 별도의 GenAI 프롬프트(채팅 완료) 스킬이 API Management를 지원되는 대상으로 만들지 않습니다. ACL 전용 수집의 경우 해당 스킬에는 API Management가 아닌 지원되는 Microsoft 자사 엔드포인트가 필요합니다. 민감도 레이블 수집의 경우 해당 기능은 지원되지 않습니다. 보강을 구성하기 전에 SharePoint ACL 제한을 검토합니다. 인증 또는 프라이빗 라우팅은 이러한 제한을 제거하지 않습니다.

검색 데이터 평면 API 버전, 검색 관리 API 버전, API Management 버전, 다운스트림 모델 API 버전 및 배포된 모델 버전은 독립적입니다. Search API 버전을 변경해도 다운스트림 API가 변경되거나 다른 모델이 배포되지는 않습니다.

엔드포인트 및 프로토콜 요구 사항 이해

네이티브 엔드포인트

Azure OpenAI 임베딩 기술 및 벡터라이저의 경우 resourceUri을 리소스 기본 URI 또는 HTTPS API Management 게이트웨이 기본 URI로 설정합니다. 기본 게이트웨이 호스트 이름(예: https://<apim-name>.azure-api.net)과 구성된 사용자 지정 도메인(예: https://apim.contoso.com.)을 모두 사용할 수 있습니다. deploymentId를 별도로 설정합니다. 사용자 지정 도메인 지원은 네이티브 임베딩 프로토콜을 변경하거나 임의의 호환 공급자에 대한 지원을 추가하지 않습니다.

검색은 이러한 네이티브 임베딩 호출에 대해 /openai/deployments/<deploymentId>/embeddings?api-version=2023-05-15를 구성합니다. 게이트웨이 API 및 정책을 구성하여 해당 경로와 쿼리 문자열을 허용하고 대상 Azure OpenAI 배포로 라우팅되도록 합니다. 백 엔드에 다른 경로, 배포 이름 또는 API 버전이 필요한 경우 API Management에서 다시 작성합니다. resourceUri에 전체 embeddings 작업 URL을 넣지 마세요.

다음 매개 변수 조각은 기본 게이트웨이 도메인을 사용합니다. 임베딩 기술의 매개 변수로 사용하거나 벡터라이저 내의 azureOpenAIParameters 매개 변수에 사용합니다. 둘 다 apiKey와 authIdentity를 생략하므로 Foundry IQ 서비스의 시스템 할당 ID를 사용합니다.

{
  "resourceUri": "https://contoso-models.azure-api.net",
  "deploymentId": "my-text-embedding-3-small",
  "modelName": "text-embedding-3-small"
}

사용자 지정 게이트웨이 도메인의 경우 resourceUri만 https://apim.contoso.com로 변경합니다. API Management 게이트웨이에서 해당 호스트 이름과 TLS 인증서를 구성합니다. 배포 및 모델 설정은 별도로 유지됩니다. 전체 정의 및 사용자 할당 ID 선택은 임베딩 기술 및 벡터라이저 예제를 참조하세요.

GenAI 프롬프트 기술의 경우 작업 경로 및 필요한 쿼리 매개 변수를 포함하여 전체 모델 호출 uri을 제공하세요. API Management 기본 및 사용자 지정 게이트웨이 도메인이 지원됩니다. 게이트웨이 기본 URL만으로는 완전한 GenAI 작업 URL이 아닙니다.

네이티브 KB 채팅 완료 호출은 배포 경로(예: https://<resource-name>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=2024-08-01-preview.)를 사용합니다. 네이티브 GPT-6 KB 프로필은 model를 사용하며, 배포 ID는 요청 본문의 https://<resource-name>.openai.azure.com/openai/v1/responses에 있습니다.

호환되는 엔드포인트

검색에 사용되는 호환되는 기술 자료 LLM의 경우:

  1. 경로 및 쿼리 매개 변수를 포함하여 전체 절대 HTTPS POST URL을 uri에 제공하세요. 예를 들어:
    • Chat completions: https://<apim-name>.azure-api.net/openai/deployments/<deployment>/chat/completions?api-version=<downstream-api-version>.
    • 응답: https://<gateway-host>/openai/v1/responses.
  2. 선택한 프로토콜을 수락하도록 엔드포인트를 구성합니다. 검색은 변경되지 않은 URL을 보냅니다. 즉, 배포 경로, 작업 또는 api-versionURL을 추가하지 않습니다.
  3. URL에 자격 증명 또는 조각을 포함하지 마세요. 검색은 동일한 호스트로의 리디렉션을 포함하여 리디렉션을 따르지 않습니다.
  4. URL 또는 게이트웨이에서 라우팅을 구성합니다. 호환되는 기술 자료 요청 본문은 model를 생략합니다. 공급자가 model 식별자를 요구하는 경우 게이트웨이에서 식별자를 제공해야 합니다.

사용자 지정 게이트웨이 도메인 및 직접 타사 호환 엔드포인트는 동일한 계약을 사용합니다. 공급자 URL에 요청 본문에 모델이 필요한 경우 해당 값을 제공하는 게이트웨이 또는 어댑터가 필요합니다.

modelName은 Search의 프로필 및 기능을 선택합니다. 실제 다운스트림 배포를 선택하거나 확인하거나, 날짜가 지정된 공급자 모델 버전을 식별하거나, 임의의 공급자 프로토콜을 호환되도록 만들지 않습니다. 호환되는 기술 자료 구성에는 공용 프로토콜 선택기가 없습니다.

Responses 지식 기반 검색의 경우 상태 비저장 연속 구조, 함수 호출 입력 및 출력 및 암호화된 추론 콘텐츠를 유지합니다. 검색이 store:false전송합니다. 모델 이름 문자열 또는 간단한 텍스트 요청을 수락하는 것만으로는 충분한 호환성이 아닙니다. 게이트웨이의 프로토콜 변환은 다운스트림 프로토콜을 네이티브 Search 프로토콜로 만들지 않습니다.

Search-게이트웨이 간 인증 구성

애플리케이션-검색 인증을 검색-게이트웨이 인증과 별도로 유지합니다. Search 개체를 만들거나 쿼리하는 데 사용하는 자격 증명은 아웃바운드 모델 호출에 사용되는 자격 증명이 아닙니다.

기본 인증

네이티브 Azure OpenAI 임베딩 설정은 apiKey 또는 Search 관리 ID를 사용합니다. 키 인증은 api-key를 내보내지만 Ocp-Apim-Subscription-Key는 자동으로 내보내지 않습니다. 워크로드가 보내는 헤더와 일치하도록 API Management의 구독 키 헤더 또는 정책을 구성합니다.

네이티브 관리 ID는 Cognitive Services audience(https://cognitiveservices.azure.com)에 대한 토큰을 가져옵니다. 시스템 할당 ID의 경우 apiKey 및 authIdentity를 생략하거나, 연결된 사용자 할당 ID의 경우 워크로드의 ID 개체를 사용하세요. 하나의 인증 방법만 구성합니다. 각 워크로드 참조에서 지원되는 ID 속성을 확인하세요.

토큰의 유효성을 검사하고 서명, 발급자, Cognitive Services 대상 그룹, 테넌트, 수명 및 필요한 권한을 포함하여 선택한 검색 ID에 권한을 부여하도록 게이트웨이를 구성합니다. 네이티브 인증은 사용자 지정 게이트웨이 애플리케이션 audience에 대한 토큰을 획득하지 않습니다. 시나리오 2: 클라이언트 앱이 API Management에 권한을 부여의 클라이언트-게이트웨이 패턴을 사용하고, 이 워크로드가 실제로 보내는 대상에 맞게 유효성 검사가 구성되도록 합니다. 시나리오 3에서는 이 연결이 아닌 SaaS 백 엔드에 대한 자격 증명 관리자 인증 및 권한 부여를 설명합니다.

호환되는 인증

호환되는 기술 자료 LLM 연결을 만들 때 정확히 하나의 유효 인증 모드를 openAICompatibleParameters: 지정합니다.

Mode Configuration 수신 엔드포인트 요구 사항
저장된 헤더 비어 있지 않은 headers 맵. 헤더 이름과 값은 비밀입니다. 구성된 자격 증명을 수락하고 유효성을 검사합니다. API Management의 경우 이 요구 사항에는 구독 헤더가 포함될 수 있습니다.
관리되는 아이덴티티 managedIdentityAudience, 선택적으로 authIdentity. 고객 애플리케이션의 대상에 대한 Search ID의 유효성을 검사하고 승인합니다.

managedIdentityAudience는 정식 bare Microsoft Entra 애플리케이션 GUID여야 합니다( 예: 11111111-2222-3333-4444-555555555555.). /.default, api://, 범위 또는 Cognitive Services 대상 그룹을 사용하지 마세요. authIdentity를 생략하면 Foundry IQ 서비스의 시스템 할당 ID를 사용합니다.

연결된 사용자 할당 ID를 선택하려면 managedIdentityAudience와 함께 이 ID 개체를 추가하세요:

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

이 속성 조각은 완전한 연결이 아닙니다. 두 모드를 함께 사용하거나, 생성 시 두 모드 모두 꺼진 상태, 빈 헤더 맵 또는 managedIdentityAudience 없이 authIdentity는 모두 유효하지 않습니다. 토큰 획득 또는 유효성 검사 실패는 익명 인증으로 대체되지 않습니다.

게이트웨이와 백엔드 간 인증 구성

백엔드 연결을 별도로 보호하세요. Microsoft 운영 Azure OpenAI 백 엔드의 경우 일반적인 패턴은 API Management에서 자격 증명 종료, API Management의 자체 시스템 또는 사용자 할당 관리 ID를 사용한 인증입니다. 백엔드 배포를 호스팅하고 해당 엔드포인트를 소유한 Azure OpenAI 또는 상위 Foundry 리소스에서 해당 ID에 Cognitive Services OpenAI User 역할을 할당합니다. 해당 ID를 사용하도록 백 엔드 정책을 구성합니다. API Management가 자격 증명을 종료하고 자체 ID를 사용하는 경우 검색 ID는 해당 백 엔드에서 역할이 필요하지 않습니다.

또는 백 엔드 키를 API Management에 명명된 값 에 저장하고 정책을 사용하여 백 엔드로 보냅니다. 백엔드 키는 Search-게이트웨이 구독 키가 아닙니다.

고객 또는 타사 백 엔드의 경우 백 엔드의 필수 권한 부여, 라우팅 및 프로토콜 적응을 구성합니다. 검색-게이트웨이 관리 ID는 해당 백 엔드에서 권한 부여를 설정해 주지 않습니다.

서비스 측 인증 옵션, API Management 관리형 ID 및 생성형 AI 게이트웨이 기능을 참조하세요.

역할 범위 및 ID 선택

직접 Azure OpenAI 호출 또는 의도적인 토큰 통과의 경우 Cognitive Services OpenAI 사용자를 선택한 검색 관리 ID에 할당합니다. 배포를 호스트하고 엔드포인트를 소유하는 Azure OpenAI 또는 부모 Foundry 리소스로 할당 범위를 지정합니다.

예를 들어 프로젝트 contoso-project가 부모 리소스 my-text-embedding-3-small에서 배포 contoso-foundry를 사용하는 경우 역할 범위는 /subscriptions/<model-subscription-id>/resourceGroups/<model-resource-group>/providers/Microsoft.CognitiveServices/accounts/contoso-foundry입니다. contoso-models라는 이름의 독립 실행형 Azure OpenAI 리소스의 경우, /Microsoft.CognitiveServices/accounts/contoso-models로 끝나는 해당 리소스 ID를 사용합니다. 두 범위 모두 /projects/<project-name> 또는 배포 이름을 포함하지 않습니다.

ID 식별자 및 역할 할당 단계는 역할 할당을 참조하세요. API Management 사용자 지정 도메인의 경우 게이트웨이 호스트 이름이 아닌 게이트웨이의 백 엔드 구성에서 모델 호스팅 리소스를 식별합니다.

모델 호스팅 리소스의 IAM(액세스 제어) 페이지에서 역할을 올바른 보안 주체에 할당합니다. 검색 및 모델 리소스가 동일한 Microsoft Entra 테넌트의 다른 리소스 그룹 또는 구독에 있는 경우 역할 할당 범위에서 모델 리소스의 구독 및 리소스 그룹을 사용합니다. 해당 범위에서 역할 할당 권한이 있는지 확인합니다. Azure RBAC 범위를 참조하세요. 관리되는 ID는 디렉터리 간 액세스를 지원하지 않습니다.

401 또는 403 오류의 경우 선택한 ID, 리소스 범위, 역할 할당 전파 및 인증의 각 단계를 확인합니다. 모델 리소스에서 로컬 인증이 비활성화된 경우 키 대신 권한 있는 관리 ID를 사용합니다. RBAC는 권한 부여를 부여합니다. DNS, 방화벽 또는 프라이빗 경로를 구성하지 않습니다.

호환되는 기술 자료 모델 사용

전체 REST 구성, 정확한 21KB 모델 프로필 및 별도의 채팅 완료 및 응답 예제는 OpenAI 호환 모델 사용(미리 보기)을 참조하세요.

기존 기술 자료를 네이티브 Azure OpenAI 또는 Microsoft Foundry 모델 엔드포인트에서 APIM 또는 사용자 지정 도메인 엔드포인트로 다시 만들지 않고 전환할 수 있습니다. 2026-11-01-preview를 사용하거나 나중에 지원되는 미리 보기 버전을 사용하고 모델 연결 업데이트 요구 사항을 따릅니다.

kind: "openAICompatible" 기술 자료의 models 컬렉션에서 openAICompatibleParameters 및 models를 사용하여 검색 LLM을 구성합니다. 웹 지식 원본이 있는 기술 자료에는 네이티브 Azure OpenAI 채팅 구성이 필요합니다.

구성 후 동일한 KB에서 를 사용하여 2026-11-01-preview합니다. LLM 지원 검색을 사용하고 비보안 모델 활동 및 게이트웨이 라우팅을 검사합니다. 성공적인 만들기 또는 GET만으로는 모델 호출을 확인하지 않습니다.

지원되는 Azure OpenAI 임베딩 모델

임베딩 프로필

Azure OpenAI 포함 기술 및 벡터라이저는 다음 모델을 지원합니다. 기존 워크로드 구성을 resourceUri, deploymentId, modelName와 함께 사용하세요.

Profile 기본 차원 허용되는 크기
text-embedding-ada-002 1536 1536만
text-embedding-3-small 1536 1–1536
text-embedding-3-large 3072 1–3072

유효 출력 차원은 벡터 필드와 일치해야 합니다. 데이터 수집 시와 쿼리 시에 동일한 임베딩 모델과 설정을 사용하세요. 차원이 같다고 해서 공유된 의미 공간이 보장되는 것은 아닙니다. 전체 구성은 embedding skill 및 Azure OpenAI 벡터라이저 참조를 참조하세요.

자격 증명 및 모델 구성 업데이트

호환되는 기술 자료 LLM의 headers 경우 쓰기 전용입니다. 공용 응답은 헤더 이름을 포함하여 속성을 완전히 생략합니다. 마스킹된 값 {}또는 null.

동일한 기술 자료 및 모델 바인딩의 경우, 생략 headers 하는 업데이트는 정확한 엔드포인트, 모델 프로필 및 인증 ID가 변경되지 않은 상태로 유지되는 경우에만 저장된 자격 증명을 유지할 수 있습니다.

Update 필요한 작업
변경되지 않은 read-to-PUT 동일한 리소스/바인딩 및 연결/프로필/ID 설정을 유지합니다. 생략된 헤더는 저장된 자격 증명을 보존할 수 있습니다.
대상, 프로필 또는 ID 변경됨 새 인증을 제공합니다. 생략된 시크릿을 변경된 스코프로 전송하지 마세요.
읽기 결과에서 복사, 이름 바꾸기 또는 만들기 인증 정보를 명시적으로 제공하십시오. 인증 정보를 생략해도 다른 개체의 자격 증명을 상속하지 않습니다.
헤더 자격 증명 회전 동일한 모델 바인딩에서 유효한 전체 대체 헤더 맵을 보냅니다.
헤더/관리형 ID 모드 전환 새 유효한 모드를 제공하고 요청에서 이전 모드를 제거합니다.
업데이트 거부 기존 저장된 자격 증명은 변경되지 않은 상태로 유지됩니다.

예를 들어 대체 headers 맵이 포함된 기존의 완전한 KB 정의를 전송하여 KB 헤더를 교체합니다. 후속 GET에서는 headers가 생략됩니다. 해당 읽기 결과를 변경하지 않고 PUT하면 대체 항목을 유지할 수 있습니다. 해당 읽기 결과에서 uri를 변경하지 말고, 생략된 비밀이 이를 따라오기를 기대하지 마세요.

회전 후 및 변경되지 않은 읽기에서 PUT으로의 업데이트 후에 LLM 지원 검색 확인을 반복합니다. 게이트웨이가 대체 자격 증명을 수락하고 헤더 이름, 값 또는 토큰을 로깅하지 않고 검색이 여전히 성공했는지 확인합니다.

프라이빗 연결 구성

API Management 프라이빗 엔드포인트는 Gateway 런타임 하위 리소스에 대한 인바운드 연결입니다. Gateway 는 계층이 아닙니다. 관리, 포털 및 개발자 설명서 URL은 모델 호출 엔드포인트가 아니며 이 게이트웨이 Private Link 연결에서 다루지 않습니다.

API Management 계층 및 토폴로지

계층 또는 토폴로지 API Management 기능 검색 조건
표준 v2 인바운드 프라이빗 엔드포인트 및 아웃바운드 가상 네트워크 통합. 검색 워크로드의 실행 경로를 별도로 검증합니다.
프리미엄 v2 인바운드 프라이빗 엔드포인트 및 가상 네트워크 통합/삽입 옵션. API Management 기능은 삽입된 모든 토폴로지에서 검색 공유 Private Link로 작동한다는 보장은 아닙니다.
Classic Premium, VNet 삽입 안 됨 인바운드 프라이빗 엔드포인트를 지원합니다. 모든 클래식 Premium 인스턴스를 미지원으로 취급하지 마세요.
클래식 프리미엄, 내부 VNet 삽입 프라이빗 엔드포인트는 지원되지 않습니다. 이 공유-프라이빗 링크 디자인에는 지원되지 않습니다.
클래식 프리미엄, 외부 VNet 삽입 프라이빗 엔드포인트는 지원되지 않습니다. 이 공유 프라이빗 링크 구성에서는 지원되지 않습니다.
클래식 개발자, 기본, 표준 API Management 프라이빗 엔드포인트 적용 가능성에 포함되며 해당 제한 사항이 적용됩니다. 검색 워크로드 경로의 포괄적 인증이 아닙니다.
자체 호스팅 또는 작업 영역 게이트웨이 문서에 설명된 인바운드 프라이빗 엔드포인트 연결에는 지원되지 않습니다. 이 제한은 모든 공용 프로토콜 시나리오가 아닌 프라이빗 연결과 관련이 있습니다.

API Management v2 계층 및 프라이빗 엔드포인트 제한을 참조하세요. API Management v2 기능은 2024-05-01 이상의 관리 API를 사용합니다. 이 버전은 Search 데이터 평면 또는 관리 API를 선택하지 않습니다.

클래식 프리미엄은 계속 지원되며 사용 중지되지 않습니다. API Management에는 현재 프리미엄을 비롯한 기존 클래식 계층 인스턴스를 v2 계층 인스턴스로 마이그레이션하는 자동화된 도구가 없습니다. v2 계층은 새로 만든 인스턴스에 사용할 수 있습니다. API Management v2 마이그레이션 및 클래식 계층 FAQ를 참조하세요.

예를 들어 내부 VNet 삽입 및 검색 공유 프라이빗 링크 대상 지정 Microsoft.ApiManagement/service / Gateway 이 있는 클래식 프리미엄 인스턴스는 지원되지 않습니다. 외부 VNet 삽입에는 동일한 제한이 있습니다. 올바른 리소스 ID, 승인된 연결 요청 또는 사용자 지정 도메인은 이 토폴로지 제한을 제거하지 않습니다.

적격 인덱서 보강의 경우 공유 프라이빗 링크를 통해 아웃바운드 연결 만들기의 지침을 따르세요.

  1. 검색 계층, 클라우드, 워크로드 및 프라이빗 실행 자격을 확인합니다.
  2. 그룹 IDGateway를 사용하여 리소스 유형을 Microsoft.ApiManagement/service 대상으로 하는 공유 프라이빗 링크를 만듭니다. 기존 Search 가이드에서는 관리 API 2025-05-01를 사용합니다. 이는 다운스트림 모델 API 버전이 아닙니다.
  3. API Management에서 연결을 승인하고 성공적인 프로비전 및 승인을 확인합니다.
  4. 적격 인덱서의 parameters.configuration.executionEnvironment를 "private"로 설정합니다.
  5. 실제 실행 환경에서 DNS 이름 확인, TLS 및 라우팅을 검증합니다. 모델 URI에서 개인 IP 주소가 아닌 구성된 게이트웨이 호스트 이름을 사용합니다. 해당 인증서는 해당 호스트 이름과 일치해야 합니다. 사용자 지정 도메인의 경우 해당 이름에 대한 DNS뿐만 아니라 기본 privatelink.azure-api.net 프라이빗 DNS 설정도 구성합니다. 표준 v2 및 프리미엄 v2에는 사용자 지정 게이트웨이 이름도 공개적으로 확인할 수 있어야 합니다. 사용자 지정 도메인 DNS 제한 사항을 참조하세요.
  6. 프라이빗 엔드포인트가 구성되고 프라이빗 경로가 확인된 후에만 API Management 공용 네트워크 액세스를 사용하지 않도록 설정합니다. 퍼블릭 Search-APIM 연결의 경우 네트워크 정책에 따라 게이트웨이의 퍼블릭 엔드포인트에 액세스할 수 있도록 유지합니다. 검색, API Management 및 백 엔드의 공용 네트워크 설정은 독립적입니다.
  7. API Management와 백 엔드 간 네트워킹을 독립적으로 보호합니다.

KB 검색 또는 쿼리 벡터화 요청에 인덱서 실행 속성을 추가하지 마세요. API Management Gateway 대상 등록은 모든 KB 또는 쿼리 벡터라이저 실행 호스트에 대한 프라이빗 경로 지원을 보장하지 않습니다. 프라이빗 대상 주소를 수락해도 경로가 프로비전되지 않습니다. 또한 API Management 지원은 임의의 Microsoft.Network/privateLinkServices 대상에 대한 일반적인 지원도 설정하지 않습니다.

보안 고려 사항

Foundry IQ는 모델 입력 및 구성된 인증 자료를 선택한 엔드포인트로 보냅니다. 신뢰하고 제어할 수 있으며 이러한 입력 및 자격 증명을 수신하도록 의도된 엔드포인트만 구성하세요. 호스트 이름 또는 audience GUID만으로는 엔드포인트 소유권, 권한 부여 또는 프라이빗 연결을 입증하지 않습니다.

서명, 발급자, 대상, 테넌트, 수명 및 필요한 권한을 포함하여 수신 엔드포인트에서 관리 ID 토큰의 유효성을 검사합니다. 검색 및 API Management ID 모두에 최소 권한을 적용합니다. 인덱스 정의, 지식 베이스, 지식 원본 및 게이트웨이 정책을 수정할 수 있는 권한을 제한합니다.

연결을 사용하도록 설정하기 전에 라우팅, 다운스트림 공급자, 로깅, 보존, 지리적 처리 및 액세스 제어를 검토합니다. 게이트웨이-백 엔드 인증과 별도로 검색-게이트웨이 인증을 보호합니다. 관리 ID는 고객 또는 타사 백엔드가 Microsoft에서 운영하는 것이 되도록 만들지 않습니다.

검색 관리 설정 properties.dataExfiltrationProtections 은 공용 값을 ["BlockAll"]사용합니다. 호환되는 기술 자료 모델 호출을 차단합니다. 이 값을 모든 Azure OpenAI 벡터라이저를 사용하지 않도록 설정하는 스위치로 처리하지 마세요. Azure OpenAI 벡터라이저 보안 지침 및 특정 워크로드의 네트워크 제어를 검토합니다.

지원되지 않는 조합 문제 해결

증상 또는 구성 확인할 사항
작업을 찾을 수 없거나 리디렉션됨 호환되는 전체 POST URL 및 올바른 쿼리 매개 변수를 제공하세요. 검색은 경로를 추가하거나 리디렉션을 따르지 않습니다.
누락된 공급자 모델 호환되는 KB 본문에서는 model이 생략됩니다. URL 라우팅 또는 게이트웨이 삽입 구성; modelName 는 공급자 배포 선택기가 아닙니다.
Responses KB 실패 11월 프리뷰를 지원하고 필수 continuation 구조를 갖춘 Responses KB 프로필 및 엔드포인트를 사용합니다. 보장된 Chat Completions 폴백은 없습니다.
인증이 거부되었습니다 유효한 모드를 정확히 하나만 사용하세요. 네이티브 앱과 사용자 지정 앱의 대상, 토큰 유효성 검사, 헤더 이름, 그리고 두 인증 단계를 확인하세요.
개체를 읽은 후 업데이트가 실패함 변경된 범위에 대해 새 자격 증명을 제공하세요. 누락하여 쓰기 전용 자격 증명을 복사하지 마세요.
Azure OpenAI 임베딩 요청이 실패함 지원되는 임베딩 모델, 차원이 일치하는 모델, 그리고 스킬 또는 벡터라이저에 대해 문서화된 리소스 URI 및 배포 설정을 사용합니다.
비공개 요청 실패 워크로드 실행 경로 적격성, 승인, DNS, TLS, API Management 계층/토폴로지 및 백 엔드 연결을 독립적으로 확인합니다.
호환되는 KB 모델을 사용하는 웹 지식 소스 기본 제공 Azure OpenAI 채팅 구성을 사용합니다.