메모
Foundry IQ (Azure AI 검색)는 관리형 검색을 위한 상위 수준의 지식 원본 및 지식 베이스 API와 함께 직접 인덱싱 및 쿼리 API를 제공합니다. Azure 포털, REST API 또는 Azure SDK 사용하여 이러한 기능을 구성하거나 Microsoft Foundry 포털의 기술 자료에 에이전트를 연결합니다.
Azure AI 검색(Foundry IQ)에서 인덱싱 또는 쿼리 중에 데이터, 적용된 AI 또는 벡터화를 제공하는 다른 Azure 리소스로의 아웃바운드 연결에 Microsoft Entra ID 보안 주체 및 역할 할당을 사용할 수 있습니다.
아웃바운드 연결에서 역할을 사용하려면 먼저 Microsoft Entra 테넌트에서 Foundry IQ 서비스의 보안 주체로 둘 중 하나인 시스템 할당 또는 사용자 할당 관리형 ID를 사용하도록 Foundry IQ 서비스를 구성합니다. 관리 ID가 있으면 권한 있는 액세스에 대한 역할을 할당할 수 있습니다. 관리 ID 및 역할 할당은 연결 문자열 또는 코드에서 비밀 및 자격 증명을 전달할 필요가 없습니다.
필수 구성 요소
기본 계층 이상의 모든 지역에 있는 Foundry IQ 서비스입니다.
유효한 역할 할당이 있는 Microsoft Entra 보안 주체의 들어오는 요청을 수락하는 Azure 리소스입니다.
관리 ID를 만들려면 소유자 또는 사용자 액세스 관리자여야 합니다. 역할을 할당하려면 소유자, 사용자 액세스 관리자, 역할 기반 액세스 제어 관리자 또는 Microsoft.Authorization/roleAssignments/write 권한이 있는 사용자 지정 역할의 구성원이어야 합니다.
지원되는 시나리오
다음 시나리오에 관리 ID를 사용할 수 있습니다.
| 시나리오 | 시스템에 할당됨 | 사용자가 할당됨 |
|---|---|---|
| 인덱서 데이터 원본에 연결1 | 예 | 예 |
| 기술/벡터라이저 2를 통해 Azure OpenAI, Microsoft Foundry 및 Azure Functions의 임베딩 및 채팅 완료 모델에 연결합니다. | 예 | 예 |
| 고객 관리형 키를 위해 Azure Key Vault에 연결 | 예 | 예 |
| 디버그 세션에 연결(Azure Storage에 호스팅된)1 | 예 | 아니요 |
| Azure Storage에서 호스팅되는 보강 캐시에 연결(미리 보기)1,3 | 예 | 예 4 |
| 지식 저장소에 연결(Azure Storage에서 호스팅됨)1 | 예 | 예 |
1 Foundry IQ와 스토리지 간의 연결의 경우 네트워크 보안은 사용할 수 있는 관리 ID 유형에 제약 조건을 적용합니다. Azure Storage 동일한 지역 연결에 시스템 관리 ID만 사용할 수 있으며 해당 연결은 trusted 서비스 예외 또는 리소스 인스턴스 규칙을 통해야 합니다. 자세한 내용은 네트워크로 보호되는 스토리지 계정에 대한 액세스를 참조하세요 .
2 기술/벡터라이저를 통한 Azure OpenAI, Foundry 및 Azure Functions 연결에는 사용자 지정 기술, 사용자 지정 벡터라이저, Azure OpenAI 포함 기술, Azure OpenAI 벡터라이저, AML 기술 및 Microsoft Foundry 모델 카탈로그 벡터라이저가 포함됩니다.
3 Foundry IQ 서비스는 현재 공유 키 액세스가 꺼져 있는 스토리지 계정의 테이블에 연결할 수 없습니다.
4 보강 캐시 연결을 위한 사용자 할당 관리 ID에는 미리 보기 REST API(2025-11-01-preview 이상) 또는 미리 보기 SDK 패키지가 필요합니다. 이 테이블의 다른 모든 사용자 할당 관리 ID 시나리오는 REST API 버전 2026-04-01 이상에서 지원됩니다.
시스템 관리 ID 만들기
시스템 할당 관리 ID는 Foundry IQ 서비스와 같은 Azure 리소스에 자동으로 만들어지고 연결되는 Microsoft Entra ID 보안 주체입니다.
각 Foundry IQ 서비스에 대해 하나의 시스템 할당 관리 ID를 가질 수 있습니다. Foundry IQ 서비스에 고유하며 수명 동안 서비스에 바인딩됩니다.
시스템 할당 관리 ID를 사용하도록 설정하면 Microsoft Entra ID 다른 Azure 리소스에 인증하는 데 사용되는 Foundry IQ 서비스에 대한 보안 주체를 만듭니다. 그런 다음, 데이터 및 작업에 대한 권한 있는 액세스를 위해 역할 할당에서 이 ID를 사용할 수 있습니다.
Azure 포털에서 Foundry IQ 서비스로 이동합니다.
왼쪽 창에서 설정>ID를 선택합니다.
시스템 할당 탭의 상태 아래에서 켜기를 선택합니다.
저장을 선택합니다.
설정을 저장하면 페이지가 업데이트되어 Foundry IQ 서비스에 할당된 개체 식별자가 표시됩니다.
사용자 할당 관리 ID 만들기
사용자 할당 관리 ID는 구독, 리소스 그룹 또는 리소스 유형으로 범위를 지정할 수 있는 Azure 리소스입니다.
역할 할당에서 보다 세분성을 위해 여러 사용자 할당 관리 ID를 만들 수 있습니다. 예를 들어 다양한 애플리케이션 및 시나리오에 대해 별도의 ID를 원할 수 있습니다. 독립적으로 만들어지고 관리되는 리소스로서 서비스 자체에 바인딩되지 않습니다.
사용자 할당 관리 ID를 설정하는 단계는 다음과 같습니다.
Azure 구독에서 사용자 할당 관리 ID를 만듭니다.
Foundry IQ 서비스에서 사용자 할당 관리 ID를 Foundry IQ 서비스와 연결합니다.
연결하려는 다른 Azure 서비스에서 ID에 대한 역할 할당을 만듭니다.
사용자 할당 관리 ID를 Foundry IQ 서비스와 연결하면 Azure 포털, 검색 관리 REST API 및 기능을 제공하는 SDK 패키지에서 지원됩니다.
Azure 포털 로그인합니다.
대시보드의 왼쪽 위 모서리에서 리소스 만들기를 선택합니다.
검색 상자를 사용하여 사용자 할당 관리 ID를 찾은 다음 만들기를 선택합니다.
구독, 리소스 그룹 및 지역을 선택합니다. 식별자에 설명이 있는 이름을 지정하세요.
만들기를 선택하고 리소스 배포가 완료되기를 기다립니다.
ID를 사용하기까지 몇 분 정도 걸립니다.
Foundry IQ 서비스 페이지에서 설정>ID(Identity)를 선택합니다.
사용자 할당 탭에서 추가를 선택합니다.
이전에 만든 구독 및 사용자 할당 관리 ID를 선택합니다.
역할 할당
관리 ID가 있으면 Azure 리소스에 대한 Foundry IQ 서비스 권한을 결정하는 역할을 할당합니다.
직접 Azure OpenAI 모델 연결의 경우 Foundry IQ 서비스 구성에서 선택하는 시스템 할당 또는 사용자 할당 ID에 Cognitive Services OpenAI User를 할당합니다. 배포를 호스트하고 resourceUri에 해당하는 Azure OpenAI 또는 Microsoft Foundry 리소스로 할당 범위를 지정합니다. Foundry 프로젝트의 경우 프로젝트 개체, Foundry IQ 서비스, 인덱스, 지식 원본, 기술 자료 또는 배포 이름이 아닌 상위 리소스를 사용합니다.
| Value | Purpose |
|---|---|
| 관리형 ID 보안 주체/개체 ID | 역할 할당 수신자를 식별합니다. |
| 클라이언트 ID | ID와 연결된 애플리케이션을 식별합니다. 역할 할당 범위 또는 authIdentity.userAssignedIdentity의 값이 아닙니다. |
| 사용자 할당 ID 리소스 ID | 지원되는 검색 authIdentity 구성에서 연결된 ID를 선택합니다. 모델 리소스 범위가 아닙니다. |
| 모델 호스팅 리소스 ID | 역할 할당 범위를 설정합니다. 상위 Azure OpenAI 또는 Foundry 리소스를 식별합니다. |
| 배포 이름 및 엔드포인트 호스트 이름 | 역할 할당의 수신자가 아니라 모델 배포 및 연결 대상을 식별하세요. |
지원되는 모델 엔드포인트에서 openai.azure.com, services.ai.azure.com 또는 cognitiveservices.azure.com를 사용하는 경우에도 동일한 범위 규칙이 적용됩니다. Search 인증을 확인하고 자체 백엔드 ID를 사용하는 API Management의 경우, 대신 게이트웨이의 백엔드 ID에 모델 역할을 할당하세요. 게이트웨이에서 Search에 대한 권한을 별도로 부여합니다.
검색-게이트웨이 인증을 참조하세요.
인덱서 데이터 연결 및 Azure Key Vault 고객 관리형 키에 액세스하려면 읽기 권한이 필요합니다.
지식 저장소에서 디버그 세션 데이터, 보강 캐싱 및 장기 콘텐츠 스토리지를 호스팅하는 데 Azure Storage 사용하는 AI 보강 기능에는 쓰기 권한이 필요합니다.
다음 단계에서는 역할 할당 워크플로를 보여 줍니다. 이 예제는 Azure OpenAI용입니다. 다른 Azure 리소스는
Azure portal에서 모델을 호스팅하는 Azure OpenAI 리소스 또는 Foundry 프로젝트의 상위 리소스로 이동합니다.
왼쪽 메뉴에서 Access 컨트롤 을 선택합니다.
추가를 선택한 다음, 역할 할당 추가를 선택합니다.
작업 함수 역할에서 Cognitive Services OpenAI 사용자를 선택한 다음, 다음을 선택합니다.
구성원 아래에서 관리 ID를 선택한 다음 멤버를 선택합니다.
구독 및 리소스 유형(Foundry IQ 서비스)을 필터링한 다음 Foundry IQ 서비스의 관리 ID를 선택합니다.
검토 + 할당을 선택합니다.
역할 할당 전파 및 네트워크 연결은 ID 선택과는 별개입니다. 401 또는 403 오류의 경우 더 광범위한 액세스 권한을 부여하기 전에 선택한 ID 및 모델 호스팅 범위를 확인합니다. 로컬 키 인증을 사용하지 않도록 설정해도 올바른 ID, 역할 및 네트워크 경로는 여전히 필요합니다.
유효한 ID 및 역할 할당은 긴 인덱서 실행 중에 캐시된 원본 토큰이 만료되는 것을 방지하지 않습니다. 사전 실행 새로 고침 동작 및 임시 완화 방법은 실행 중 관리 ID 토큰이 만료됨을(를) 참조하세요.
연결 문자열 예제
다른 Azure 리소스에 대한 연결 문자열에서 관리 ID를 사용할 수 있다는 시나리오 설명을 기억하세요. 이 섹션에서는 예제를 제공합니다.
시스템 할당 관리 ID 연결은 일반적으로 사용 가능한 REST API 버전을 사용합니다. 사용자 할당 관리 ID 연결은 여전히 미리 보기 API 버전이 필요한 보강 캐시 연결을 제외하고 REST API 버전 2026-04-01 이상을 사용합니다.
팁
Azure 포털에서 이러한 개체의 대부분을 만들고 시스템 또는 사용자 할당 관리 ID를 지정한 다음 JSON 정의를 확인하여 연결 문자열 가져올 수 있습니다.
인덱서 데이터 원본에는 데이터 원본에 대한 연결 방법을 결정하는 속성이 포함되어 credentials 있습니다. 다음 예제에서는 스토리지 계정의 고유한 리소스 ID를 지정하는 연결 문자열 보여 줍니다.
시스템 관리 ID는 연결 문자열이 Microsoft Entra ID를 인식하는 서비스나 애플리케이션의 고유한 리소스 ID일 때 나타납니다. 사용자가 할당한 관리 ID는 속성을 통해 identity 지정됩니다.
"credentials": {
"connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}
사용자 할당 관리 ID는 REST API 버전 2026-04-01 이상이 있는 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는 REST API 버전 2026-04-01 이상이 있는 identity의 속성을 통해 지원됩니다.
"knowledgeStore": {
"storageConnectionString": "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}"
}
}
인덱서는 캐시된 데이터 확장에 사용되는 컨테이너를 만들고, 사용하며, 기억합니다. 캐시 연결 문자열에 컨테이너를 포함할 필요는 없습니다. 개체 ID는 Azure 포털에서 Foundry IQ 서비스의 ID 페이지에서 찾을 수 있습니다.
"cache": {
"enableReprocessing": true,
"storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}
디버그 세션은 Azure 포털에서 실행되며 세션을 시작할 때 연결 문자열을 받습니다. 다음 예제와 유사한 문자열을 붙여넣을 수 있습니다.
"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",
사용자 지정 기술은 사용자 지정 코드를 호스팅하는 Azure 함수 또는 앱의 엔드포인트를 대상으로 합니다.
uri는 함수 또는 앱의 엔드포인트입니다.authResourceId는 Foundry IQ 서비스에 관리 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": [ ...]
}
모델에 대한 연결 예제
관리 ID를 사용하여 만든 연결의 경우 이 섹션에서는 Foundry IQ 서비스에서 다른 리소스의 모델에 연결하는 데 사용하는 연결 정보의 예를 보여 줍니다. 시스템 관리 ID를 통한 연결은 투명합니다. ID와 역할이 제대로 구성되면 연결이 성공합니다. 반면 사용자 관리 ID에는 추가 연결 속성이 필요합니다.
Azure OpenAI 임베딩 기술 및 Azure OpenAI 벡터라이저:
Foundry IQ(Azure AI 검색) 임베딩 기술 및 벡터라이저는 임베딩 모델을 호스팅하는 Azure OpenAI의 엔드포인트를 대상으로 합니다. 엔드포인트는 Azure OpenAI 포함 기술 정의 및/또는 Azure OpenAI 벡터라이저 정의 지정됩니다.
"apikey" 및 "authIdentity"가 비어 있는 경우, 시스템 관리 ID는 자동으로 사용됩니다. 다음 예제를 참조하세요. 이 "authIdentity" 속성은 사용자 할당 관리 ID에만 사용됩니다.
시스템 관리형 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"
}
]
}
다음은 시스템 할당 관리 ID에 대해 구성된 벡터라이저 예제 입니다. 벡터라이저는 검색 인덱스로 지정됩니다.
"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"
}
}
]
사용자 할당 관리 ID 예제:
사용자가 할당한 관리 ID는 "apiKey"가 비어 있고 유효한 "authIdentity"가 제공된 경우 사용됩니다.
{
"@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"
}
],
"authIdentity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
}
}
다음은 사용자 할당 관리 ID에 대해 구성된 벡터라이저 예제 입니다. 벡터라이저는 검색 인덱스로 지정됩니다.
"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"
"authIdentity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
}
}
}
]
방화벽 액세스 확인
Azure 리소스가 방화벽 뒤에 있는 경우 Foundry IQ 서비스 및 Azure 포털에서 요청을 허용하는 인바운드 규칙이 있는지 확인합니다.
Azure Blob Storage 또는 Azure Data Lake Storage Gen2의 동일 지역 연결에 대해서는 시스템 관리 ID와 신뢰할 수 있는 서비스 예외를 사용하세요. 필요에 따라 요청을 인정하도록 리소스 인스턴스 규칙을 구성할 수 있습니다.
다른 모든 리소스 및 연결의 경우 Foundry IQ의 요청을 허용하는 IP 방화벽 규칙을 구성 합니다. 자세한 내용은 Azure 네트워크 보안 기능으로 보호되는 콘텐츠에 대한 인덱서 액세스를 참조하세요.