Azure AI 검색에서 관리 ID를 사용하여 연결하도록 검색 서비스 구성

아티클
06/28/2024

Important

사용자가 할당한 관리 ID 할당은 추가 사용 약관에 따라 공개 미리 보기로 제공됩니다. 관리 미리 보기 REST API는 Azure AI 검색에 대한 사용자가 할당한 관리 ID 할당을 제공합니다. 시스템이 할당한 관리 ID에 대한 지원은 일반적으로 사용할 수 있습니다.

인덱싱 또는 쿼리 중에 Azure AI 검색에서 데이터, 적용된 AI 또는 벡터화를 제공하는 리소스에 대한 아웃바운드 연결에 Microsoft Entra ID 및 역할 할당을 사용할 수 있습니다.

아웃바운드 연결에서 역할을 사용하려면 먼저 Microsoft Entra 테넌트에서 검색 서비스에 대한 보안 원칙으로 시스템이 할당한 또는 사용자가 할당한 관리 ID를 사용하도록 검색 서비스를 구성합니다. 관리 ID가 있으면 권한 있는 액세스에 대한 역할을 할당할 수 있습니다. 관리 ID 및 역할 할당을 사용하면 연결 문자열 또는 코드에서 비밀 및 자격 증명을 전달할 필요가 없습니다.

필수 조건

모든 지역에서 기본 계층 이상의 검색 서비스입니다.
유효한 역할 할당이 있는 Microsoft Entra 보안 주체로부터 들어오는 요청을 수락하는 Azure 리소스입니다.

지원되는 시나리오

Azure AI 검색은 시스템이 할당한 또는 사용자가 할당한 관리 ID로 다른 Azure 리소스에 연결할 수 있습니다.

시스템이 할당한 관리 ID의 검색 서비스 구성은 일반적으로 사용할 수 있습니다.
사용자가 할당한 관리 ID의 검색 서비스 구성은 추가 사용 약관에 따라 공개 미리 보기로 제공됩니다.
시스템 또는 사용자 할당 여부와 관계없이 관리 ID의 데이터 평면 사용이 일반적으로 가능합니다. 예를 들어 인덱서 데이터 원본 연결, 키 자격 증명 모음, 디버그 세션 또는 보강 캐시에서 사용자가 할당한 관리 ID를 원하는 경우 사용 중인 기능도 일반적으로 사용 가능하다고 가정하며 일반적으로 사용 가능한 REST API 버전을 사용하여 연결을 만들 수 있습니다.

연결 문자열이 Microsoft Entra ID 인식 서비스 또는 애플리케이션의 고유한 리소스 ID인 경우 시스템 관리 ID가 표시됩니다. 사용자가 할당한 관리 ID는 "identity" 속성을 통해 지정됩니다.

검색 서비스는 Azure Storage를 인덱서 데이터 원본으로 사용하고, 디버그 세션, 보강 캐싱 및 지식 저장소에 대한 데이터 싱크로 사용합니다. 스토리지에 쓰기 저장하는 검색 기능의 경우 "역할 할당" 섹션에 설명된 대로 관리 ID에 기여자 역할 할당이 필요합니다.

시나리오	시스템	사용자 할당
지원되는 Azure 데이터 원본에 대한 인덱서 연결¹	예	예
고객 관리형 키를 위한 Azure Key Vault	예	예
디버그 세션(Azure Storage에서 호스트됨)¹	예	아니요
보강 캐시(Azure Storage에서 호스트됨)^1,²	예	예
지식 저장소(Azure Storage에서 호스트됨)¹	예	예
Azure OpenAI 또는 Azure AI ³에 대한 연결	예	예

¹ 검색과 스토리지 간 연결의 경우 네트워크 보안 구성에 따라 사용할 수 있는 관리 ID 유형에 제약 조건이 적용됩니다. 신뢰할 수 있는 서비스 예외 또는 리소스 인스턴스 규칙을 통해 스토리지에 대한 동일한 지역 연결에 시스템 관리 ID만 사용할 수 있습니다. 자세한 내용은 네트워크로 보호되는 스토리지 계정에 대한 액세스를 참조하세요.

² Azure 테이블 스토리지의 보강 캐싱의 경우 검색 서비스는 현재 공유 키 액세스가 해제된 스토리지 계정의 테이블에 연결할 수 없습니다.

Azure OpenAI 또는 Azure AI에 대한 ^3가지 연결에는 사용자 지정 기술, 사용자 지정 벡터라이저, Azure OpenAI 포함 기술, Azure OpenAI 벡터라이저, AML 기술, Azure AI 스튜디오 모델 카탈로그 벡터라이저, Azure AI 비전 다중 모달 포함 기술, Azure AI 비전 벡터라이저 등이 포함됩니다.

시스템 관리 ID 만들기

시스템이 할당한 관리 ID를 사용하도록 설정하면 Microsoft Entra ID는 동일한 테넌트 내의 다른 Azure 서비스에 인증하는 데 사용할 수 있는 검색 서비스에 대한 ID를 만듭니다. 그런 다음, 데이터 및 모델에 액세스하기 위해 역할 할당에서 이 ID를 사용할 수 있습니다.

시스템이 할당한 관리 ID는 검색 서비스에 고유하며 수명 동안 서비스에 바인딩됩니다. 검색 서비스에는 시스템이 할당한 관리 ID가 하나만 있을 수 있습니다.

Azure Portal에 로그인하고 검색 서비스를 찾습니다.
설정에서 ID를 선택합니다.
시스템 할당 탭의 상태에서 켜기를 선택합니다.
저장을 선택합니다.

설정을 저장하면 검색 서비스에 할당된 개체 식별자가 표시되도록 페이지가 업데이트됩니다.

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -IdentityType SystemAssigned

자세한 내용은 시스템이 할당한 관리 ID(Azure PowerShell)를 사용하여 검색 서비스 만들기를 참조하세요.

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --identity-type SystemAssigned

자세한 내용은 시스템이 할당한 관리 ID(Azure CLI)를 사용하여 검색 서비스 만들기를 참조하세요.

검색 서비스 만들기 또는 업데이트 요청을 작성합니다.

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2023-11-01
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "SystemAssigned"
  }
}

시스템 관리 ID의 확인 및 개체 식별자가 응답에 반환됩니다.

자세한 내용은 서비스 만들기 또는 업데이트(관리 REST API)를 참조하세요.

사용자 할당 관리 ID 만들기

Important

이 시나리오의 일부는 추가 사용 약관에 따라 공개 미리 보기로 제공됩니다. 관리 미리 보기 REST API는 Azure AI 검색에 대한 사용자가 할당한 관리 ID 구성을 제공합니다.

사용자가 할당한 관리 ID는 Azure 리소스입니다. 역할 할당에서 더 세분성을 원하는 경우 여러 사용자가 할당한 관리 ID를 만들 수 있습니다. 예를 들어 다양한 애플리케이션 및 시나리오에 대해 별도의 ID를 원할 수 있습니다.

단계는 다음과 같습니다.

Azure 구독에서 사용자가 할당한 관리 ID를 만듭니다.
검색 서비스에서 서비스 정의를 업데이트하여 사용자가 할당한 관리 ID를 사용하도록 설정합니다(이 단계는 미리 보기 상태임).
연결하려는 다른 Azure 서비스에서 ID에 대한 역할 할당을 만듭니다.
인덱서 데이터 원본과 같은 Azure AI 검색의 데이터 원본 연결에서 연결 세부 정보에서 사용자 관리 ID를 참조합니다(이 단계는 기능에 대한 지원을 일반적으로 사용할 수 있는 경우 일반적으로 사용 가능).

사용자가 할당한 관리 ID는 구독, 리소스 그룹 또는 리소스 유형으로 범위를 지정할 수 있습니다.

사용자 할당 관리 ID 연결은 Azure Portal, 관리 REST API의 미리 보기 버전 및 기능을 제공하는 베타 SDK 패키지에서 지원됩니다.

Azure Portal
REST API

Azure 포털
리소스 만들기를 선택합니다.
“검색 서비스 및 마켓플레이스” 검색 창에서 “사용자가 할당한 관리 ID”를 검색한 다음, 만들기를 선택합니다.
구독, 리소스 그룹 및 지역을 선택합니다. ID에 설명이 포함된 이름을 지정합니다.
만들기를 선택하고 리소스 배포가 완료될 때까지 기다립니다.

ID를 사용하기까지 몇 분 정도 걸립니다.
검색 서비스 페이지의 설정에서 ID를 선택합니다.
사용자 할당 탭에서 추가를 클릭합니다.
구독을 선택한 다음, 이전 단계에서 만든 사용자가 할당한 관리되는 리소스를 선택합니다.

포털 대신 미리 보기 관리 REST API를 사용하여 사용자가 할당한 관리 ID를 할당할 수 있습니다. API 버전 2021-04-01-preview 이상을 사용합니다. 이 예제에서는 2024-06-01-preview를 사용합니다.

검색 서비스 업데이트 요청을 작성합니다.

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2024-06-01-preview
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/[subscription ID]/resourcegroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[name of managed identity]": {}
    }
  }
}

"identity" 속성을 설정하여 정규화된 관리 ID 지정:
- "type"은 ID 유형입니다. 유효한 값은 “SystemAssigned”, “UserAssigned” 또는 둘 다 사용하려는 경우 “SystemAssigned, UserAssigned”입니다. "None" 값은 검색 서비스에서 이전에 할당된 ID를 지웁니다.
- "userAssignedIdentities"에는 사용자가 할당한 관리 ID의 세부 정보가 포함됩니다. 이 ID는 업데이트 서비스 요청에서 지정하기 전에 이미 존재해야 합니다.

역할 할당

관리 ID가 있으면 Azure 리소스에 대한 검색 서비스 권한을 결정하는 역할을 할당합니다.

인덱서 데이터 연결 및 Azure Key Vault에서 고객 관리형 키에 액세스하려면 읽기 권한이 필요합니다.
지식 저장소에서 디버그 세션 데이터, 보강 캐싱 및 장기 콘텐츠 스토리지를 호스트하는 데 Azure Storage를 사용하는 AI 보강 기능에는 쓰기 권한이 필요합니다.

다음 단계에서는 역할 할당 워크플로를 보여 줍니다. 이 예제는 Azure OpenAI용입니다. 다른 Azure 리소스는 Azure Storage에 연결, Azure Cosmos DB에 연결 또는 Azure SQL에 연결을 참조하세요.

Azure 계정으로 Azure Portal에 로그인하고 Azure OpenAI 리소스로 이동합니다.
왼쪽 메뉴에서 액세스 제어를 선택합니다.
추가를 선택한 다음 역할 할당 추가를 선택합니다.
작업 함수 역할에서 Cognitive Services OpenAI 사용자를 선택한 다음, 다음을 선택합니다.
구성원 아래에서 관리 ID를 선택한 다음, 구성원을 선택합니다.
구독 및 리소스 종류(Search Services)를 필터링한 다음 검색 서비스의 관리 ID를 선택합니다.
검토 + 할당을 선택합니다.

연결 문자열 예제

검색 서비스의 관리 ID가 정의되고 역할 할당이 제공되면 다른 Azure 리소스의 고유 리소스 ID를 사용하도록 아웃바운드 연결을 수정할 수 있습니다. 다음은 다양한 시나리오에 대한 연결 문자열의 몇 가지 예입니다.

이러한 연결에 일반적으로 사용 가능한 REST API 버전 및 Azure SDK 패키지를 사용할 수 있습니다.

팁

Azure Portal에서 이러한 개체의 대부분을 만들고 시스템 또는 사용자기 할당한 관리 ID를 지정한 다음, JSON 정의를 확인하여 연결 문자열을 가져올 수 있습니다.

Blob 데이터 원본(시스템):

인덱서 데이터 원본에는 데이터 원본에 대한 연결 방법을 결정하는 "credentials" 속성이 포함되어 있습니다. 다음 예에서는 스토리지 계정의 고유 리소스 ID를 지정하는 연결 문자열을 보여 줍니다.

Microsoft Entra ID는 검색 서비스의 시스템 관리 ID를 사용하여 요청을 인증합니다. 연결 문자열에는 컨테이너가 포함되지 않습니다. 데이터 원본 정의에서 컨테이너 이름은 연결 문자열이 아닌 "container" 속성(표시되지 않음)에 지정됩니다.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    }

Blob 데이터 원본(사용자):

사용자가 할당한 관리 ID로 Azure Storage에 대한 검색 요청을 수행할 수도 있습니다. 검색 서비스 사용자 ID는 "identity" 속성에 지정됩니다.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    },
  . . .
"identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
  }

지식 저장소:

지식 저장소 정의에는 Azure Storage에 대한 연결 문자열이 포함됩니다. 연결 문자열은 스토리지 계정의 고유한 리소스 ID입니다. 문자열은 경로의 컨테이너나 테이블을 포함하지 않습니다. 이는 연결 문자열이 아닌 포함된 프로젝션 정의에 정의되어 있습니다.

"knowledgeStore": {
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/storage-account-name};"
}

보강 캐시:

인덱서는 캐시된 보강에 사용되는 컨테이너를 만들고, 사용하고, 기억합니다. 캐시 연결 문자열에 컨테이너를 포함할 필요는 없습니다. 포털에서 검색 서비스의 ID 페이지에서 개체 ID를 찾을 수 있습니다.

"cache": {
  "enableReprocessing": true,
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

디버그 세션:

디버그 세션은 포털에서 실행되며 사용자가 세션을 시작할 때 연결 문자열을 사용합니다. 다음 예제와 유사한 문자열을 붙여넣을 수 있습니다.

"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",

사용자 지정 기술:

사용자 지정 기술은 사용자 지정 코드를 호스트하는 Azure 함수 또는 앱의 엔드포인트를 대상으로 합니다. 엔드포인트는 사용자 지정 기술 정의에 지정됩니다. "authResourceId"가 있으면 검색 서비스에 관리 ID를 사용하여 연결하도록 지시하고, 속성에 있는 대상 함수 또는 앱의 애플리케이션 ID를 전달합니다.

{
  "@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",
  "authResourceId": "<Azure-AD-registered-application-ID>",
  "batchSize": 4,
  "context": "/document",
  "inputs": [ ... ],
  "outputs": [ ...]
}

Azure OpenAI 포함 기술 및 Azure OpenAI 벡터라이저:

AI Search의 Azure OpenAI 포함 기술 및 벡터라이저는 포함 모델을 호스팅하는 Azure OpenAI 서비스의 엔드포인트를 대상으로 합니다. 엔드포인트는 Azure OpenAI 포함 기술 정의 및/또는 Azure OpenAI 벡터라이저 정의에서 지정됩니다. 시스템 관리 ID는 구성된 경우와 "apikey" 및 "authIdentity"가 비어 있는 경우 사용됩니다. "authIdentity" 속성은 사용자 할당 관리 ID에만 사용됩니다.

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "modelName": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002",
        "modelName": "text-embedding-ada-002"
      }
    }
  ]

방화벽 액세스 확인

Azure 리소스가 방화벽 뒤에 있는 경우 검색 서비스의 요청을 허용하는 인바운드 규칙이 있는지 확인합니다.

Azure Blob Storage 또는 Azure Data Lake Storage Gen2에 대한 동일한 지역 연결의 경우 시스템 관리 ID 및 신뢰할 수 있는 서비스 예외를 사용합니다. 필요에 따라 요청을 허용하도록 리소스 인스턴스 규칙을 구성할 수 있습니다.
다른 모든 리소스 및 연결의 경우 검색에서 요청을 허용하는 IP 방화벽 규칙을 구성합니다. 자세한 내용은 Azure 네트워크 보안 기능으로 보호되는 콘텐츠에 대한 인덱서 액세스를 참조하세요.

다음을 통해 공유