在 Azure AI 搜尋服務中設定搜尋服務以使用受控識別進行連線

發行項
11/24/2024

重要

使用者指派的受控識別指派依據補充使用規定，處於公開預覽狀態。管理預覽 REST API 提供適用於 Azure AI 搜尋服務的使用者指派受控識別指派。 系統指派的受控識別支援已正式推出。

您可以使用 Microsoft Entra ID 和角色指派，以便從 Azure AI 搜尋服務建立輸出連線，連接在編製索引或查詢期間提供資料、套用 AI 或向量化的資源。

若要在輸出連線上使用角色，請先將搜尋服務設定為使用系統指派或使用者指派的受控識別，做為 Microsoft Entra 租使用者中搜尋服務的安全性主體。擁有受控識別之後，您就可以指派角色以取得授權的存取權。受控識別和角色指派不需要在連接字串或程式碼中傳遞密碼和認證。

必要條件

任何區域中，基本層或更高層級的搜尋服務。
接受來自 Microsoft Entra 安全性主體 (具有效角色指派) 傳入要求的 Azure 資源。

支援的案例

Azure AI 搜尋服務可以依據其系統指派或使用者指派的受控識別，連線至其他 Azure 資源。

系統指派的受控識別搜尋服務設定已正式發行。
使用者指派的受控識別搜尋服務設定依據補充使用規定，處於公開預覽狀態。
受控識別 (不論是系統還是使用者指派) 的資料平面使用方式，均已正式發行。例如，如果您想要在索引子資料來源連線、金鑰保存庫、偵錯工作階段或擴充快取上使用使用者指派的受控識別，您可以使用正式發行的 REST API 版本來建立連線，前提是假設您使用的功能也已正式發行。

當連接字串是 Microsoft Entra ID 感知服務或應用程式的唯一資源識別碼時，就會指出系統受控識別。使用者指派的受控識別是透過「身分識別」屬性指定。

搜尋服務會使用 Azure 儲存體作為索引子資料來源，以及作為偵錯工作階段、擴充快取和知識存放區的資料接收。如需回寫至儲存體的搜尋功能，受控識別需要參與者角色指派，如指派角色一節所述。

案例	系統	使用者指派
索引子連線至支援的 Azure 資料來源¹	Yes	Yes
適用於客戶管理金鑰的 Azure Key Vault	Yes	Yes
偵錯工作階段 (裝載於 Azure 儲存體中)¹	是	No
擴充快取 (裝載於 Azure 儲存體中)^1、²	Yes	Yes
知識存放區 (裝載於 Azure 儲存體中)¹	Yes	Yes
透過技能/向量化程式 ^{3 連線至 Azure OpenAI、Azure AI Foundry 和 Azure Functions}	Yes	Yes

¹ 針對搜尋和儲存體之間的連線，您的網路安全性設定會對您可以使用的受控識別類型施加限制。只有系統受控識別可以透過受信任的服務例外狀況或資源執行個體規則，用於與儲存體的相同區域連線。如需詳細資訊，請參閱存取受網路保護的儲存體帳戶。

² AI 搜尋服務目前無法連線到已關閉共用金鑰存取的儲存體帳戶上的資料表。

³ 透過技能/向量化工具連線至 Azure OpenAI、Azure AI Foundry 和 Azure Functions 的連線包括：自定義技能、自定義向量化工具、Azure OpenAI 內嵌技能、Azure OpenAI 向量化工具、AML 技能與 Azure AI Foundry 模型目錄向量化工具。

建立系統受控識別

啟用系統指派的受控識別時，Microsoft Entra ID 會為您的搜尋服務建立身分識別，以便用來向相同租用戶內的其他 Azure 服務進行驗證。然後，您可以在角色指派中使用此身分識別來存取資料和模型。

系統指派的受控識別對您的搜尋服務而言為唯一，並繫結至服務的存留期。搜尋服務只能有一個系統指派的受控識別。

登入 Azure 入口網站，然後尋找您的搜尋服務。
在 [設定] 底下，選取 [身分識別]。
在 [系統指派] 索引標籤的 [狀態] 底下，選取 [開啟]。
選取 [儲存]。

儲存設定之後，即會更新頁面以顯示指派給搜尋服務的物件識別碼。

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

如需詳細資訊，請參閱使用系統指派的受控識別建立搜尋服務 (Azure PowerShell)。

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

如需詳細資訊，請參閱使用系統指派的受控識別建立搜尋服務 (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"
  }
}

系統會在回應中傳回系統受控識別的確認和物件身分識別碼。

如需詳細資訊，請參閱建立或更新服務 (管理 REST API)。

建立使用者指派的受控識別

重要

依據補充使用規定，此案例的一部分於公開預覽狀態。管理預覽 REST API 提供適用於 Azure AI 搜尋服務的使用者指派受控識別設定。

使用者指派的受控識別是 Azure 上的資源。如果您希望角色指派能夠更細緻，可以建立多個使用者指派的受控識別。例如，您可能想要在不同的應用程式和案例中使用不同的身分識別。

步驟如下：

在您的 Azure 訂用帳戶中，建立使用者指派的受控識別。
在搜尋服務上，更新服務定義以啟用使用者指派的受控識別 (此步驟處於預覽狀態)。
在您要連線的其他 Azure 服務上，建立該身分識別的角色指派。
在 Azure AI 搜尋服務的資料來源連線中 (例如索引子資料來源)，參考連線詳細資料中的使用者受控識別 (如果已正式發行此功能的支援，則此步驟即已正式發行)。

使用者指派的受控識別可以限定於訂用帳戶、資源群組或資源類型。

Azure 入口網站、管理 REST API 的預覽版本，以及提供此功能的搶鮮版 (Beta) SDK 套件均支援關聯使用者指派的受控識別。

Azure 入口網站
REST API

登入 Azure 入口網站
選取 [建立資源]。
在 [搜尋服務和市集] 搜尋列中，搜尋「使用者指派的受控識別」，然後選取 [建立]。
選取訂用帳戶、資源群組和區域。為身分識別提供描述性名稱。
選取 [建立] 並等候資源完成部署。

您必須在幾分鐘後才能使用該身分識別。
在搜尋服務頁面的 [設定] 底下，選取 [身分識別]。
在 [使用者指派] 索引標籤上，選取 [新增]。
選擇訂用帳戶，然後選取您在上一個步驟中建立的使用者指派受控資源。

您可以使用預覽管理 REST API，而不是 Azure 入口網站來指派使用者指派的受控識別。使用 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]": {}
    }
  }
}

設定「身分識別」屬性以指定完整的受控識別：
- 「類型」是身分識別的類型。有效值為「SystemAssigned」、「UserAssigned」或「SystemAssigned、UserAssigned」兩者。值「無」會清除搜尋服務中任何先前指派的身分識別。
- 「userAssignedIdentities」包含使用者指派受控識別的詳細資料。必須先存在此身分識別，您才能在更新服務要求中加以指定。

指派角色

擁有受控識別之後，請指派角色，以決定 Azure 資源的搜尋服務權限。

索引子資料連線以及在 Azure Key Vault 中存取客戶自控金鑰，都需要讀取權限。
使用 Azure 儲存體裝載偵錯工作階段資料、擴充快取和知識存放區長期內容儲存體的 AI 擴充功能，需要寫入權限。

下列步驟說明角色指派工作流程。此範例適用於 Azure OpenAI。如需其他 Azure 資源，請參閱連線至 Azure 儲存體、連線至 Azure Cosmos DB 或連線至 Azure SQL。

使用您的 Azure 帳戶登入 Azure 入口網站，然後前往您的 Azure OpenAI 資源。
從左側功能表中選取 [存取控制]。
選取 [新增]，然後選取 [新增角色指派]。
在 [作業函式角色] 底下，選取 [認知服務 OpenAI 使用者]，然後選取 [下一步]。
在 [成員] 底下，選取 [受控識別]，然後選取 [成員]。
依訂用帳戶和資源類型篩選 (搜尋服務)，然後選取搜尋服務的受控識別。
選取檢閱+指派。

連接字串範例

定義搜尋服務並指定角色指派的受控識別之後，即可修改輸出連線，以使用其他 Azure 資源的唯一資源身分識別碼。以下是各種案例的連接字串範例。

您可以在這些連線中使用公開發行的 REST API 版本和 Azure SDK 套件。

提示

您可以在 Azure 入口網站中建立大部分的物件，並指定系統或使用者指派的受控識別，然後檢視 JSON 定義以取得連接字串。

Blob 資料來源 (系統)：

索引子資料來源包含「認證」屬性，可決定資料來源的連接方式。下列範例顯示指定儲存體帳戶唯一資源身分識別碼的連接字串。

Microsoft Entra ID 會使用搜尋服務的系統受控識別來驗證要求。請注意，連接字串不包含容器。在資料來源定義中，容器名稱是在「容器」屬性 (未顯示) 中指定，而不是連接字串。

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

Blob 資料來源 (使用者)：

Azure 儲存體搜尋要求也可以在使用者指派受控識別下進行。搜尋服務使用者身分識別是在「身分識別」屬性中指定。

"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 儲存體的連接字串。連接字串是您儲存體帳戶的唯一資源身分識別碼。請注意，字串不包含路徑中的容器或資料表。這些定義是在內嵌投影定義中定義，而不是連接字串。

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

擴充快取：

索引子會建立、使用及記住用於快取擴充的容器。不需要在快取連接字串中包含容器。您可以在搜尋服務的 [身分識別] 頁面上，於 Azure 入口網站中找到對象識別碼。

"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 告知搜尋服務使用受控識別進行連線，並在屬性中傳遞目標函式或應用程式的應用程式識別碼。

{
  "@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 向量化工具：

Azure OpenAI 內嵌技能和 AI 搜尋服務中的向量化工具，均以裝載內嵌模型的 Azure OpenAI 服務端點為目標。端點是在 Azure OpenAI 內嵌技能定義和/或 Azure OpenAI 向量化工具定義中指定。

如果 "apikey" 和 "authIdentity" 是空的，系統受控識別會自動使用，如下列範例所示。屬性 "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"
    }
  ]
}

以下是針對系統指派的受控識別所設定的向量化程式範例。向量化工具是在搜尋索引中指定。

 "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"
      }
    }
  ]

使用者指派的受控識別範例：

如果 "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>"
   }
}

以下是針對使用者指派的受控識別所設定的向量化程式範例。向量化工具是在搜尋索引中指定。

 "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 資源位於防火牆後方，請確定有輸入規則可承認來自搜尋服務和 Azure 入口網站的要求。

針對與 Azure Blob 儲存體或 Azure Data Lake Storage Gen2 的相同區域連線，請使用系統受控識別和受信任的服務例外狀況。您可以選擇性地設定資源執行個體規則來允許要求。
針對所有其他資源和連線，設定可允許來自 Azure AI 搜尋要求的 IP 防火牆規則。如需詳細資料，請參閱索引子存取受 Azure 網路安全性功能保護的內容。

共用方式為