使用秘密插入從線上部署存取秘密 (預覽)

發行項
09/03/2024

適用於：Azure CLI ml 延伸模組 v2 (目前)Python SDK azure-ai-ml v2 (目前)

您將在本文中了解如何使用秘密插入搭配線上端點和部署來存取 API 金鑰等秘密。

您將了解：

設定您的使用者身分識別及其權限
建立工作區連線和/或金鑰保存庫，以作為秘密存放區使用
使用秘密插入功能建立端點和部署

重要

此功能目前處於公開預覽。此預覽版本沒有服務等級協定，不建議用於處理生產工作負載。可能不支援特定功能，或可能已經限制功能。

如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。

必要條件

如要使用 Azure Machine Learning，您必須擁有 Azure 訂閱。如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。立即試用免費或付費版本的 Azure Machine Learning。
安裝並設定 Azure Machine Learning CLI (v2) 延伸模組或 Azure Machine Learning Python SDK (v2)。
Azure 資源群組，在其中您 (或您使用的服務主體) 必須擁有 User Access Administrator 和 Contributor 存取權。如果您已如先前所述設定 Azure Machine Learning 延伸模組，您將會有這類資源群組。
Azure Machine Learning 工作區。如果您已如先前所述設定 Azure Machine Learning 延伸模組，您將會有工作區。
已定型的機器學習模型，可供評分和部署。

選擇祕密存放區

您可以選擇使用下列其中一項來儲存秘密 (例如 API 金鑰):

工作區底下的工作區連線: 如果您使用這種秘密存放區，您稍後即可以授與端點身分識別權限 (在端點建立時) 以自動從工作區連線讀取秘密，前提是符合特定條件。如需詳細資訊，請參閱建立端點一節中的系統指派身分識別分頁。
不一定位於工作區下的金鑰保存庫: 如果您使用這種秘密存放區，則端點身分識別不會獲得自動從密鑰保存庫讀取秘密的權限。因此，如果您想要使用受控金鑰保存庫服務，例如 Microsoft Azure Key Vault 作為秘密存放區，您稍後必須指派適當的角色。

使用工作區連線作為秘密存放區

您可以建立要用於部署的工作區連線。例如，您可以使用工作區連線 - 建立 REST API 來建立與 Microsoft Azure OpenAI 服務的連線。

或者，您可以使用 Azure Machine Learning 工作室建立自訂連線 (請參閱如何為提示流程建立自訂連線) 或 Azure AI Studio (請參閱如何在 AI Studio 中建立自訂連線)。

建立 Azure OpenAI 連線:

PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}?api-version=2023-08-01-preview
Authorization: Bearer {{token}}
Content-Type: application/json

{
    "properties": {
        "authType": "ApiKey",
        "category": "AzureOpenAI",
        "credentials": {
            "key": "<key>",
            "endpoint": "https://<name>.openai.azure.com/",
        },
        "expiryTime": null,
        "target": "https://<name>.openai.azure.com/",
        "isSharedToAll": false,
        "sharedUserList": [],
        "metadata": {
            "ApiType": "Azure"
        }
    }
}

您也可以建立自訂連線:

PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}?api-version=2023-08-01-preview
Authorization: Bearer {{token}}
Content-Type: application/json

{
    "properties": {
        "authType": "CustomKeys",
        "category": "CustomKeys",
        "credentials": {
            "keys": {
                "OPENAI_API_KEY": "<key>",
                "SPEECH_API_KEY": "<key>"
            }
        },
        "expiryTime": null,
        "target": "_",
        "isSharedToAll": false,
        "sharedUserList": [],
        "metadata": {
            "OPENAI_API_BASE": "<oai endpoint>",
            "OPENAI_API_VERSION": "<oai version>",
            "OPENAI_API_TYPE": "azure",
            "SPEECH_REGION": "eastus",
        }
    }
}

使用工作區連線 - 列出秘密 REST API，確認使用者身分識別可以從工作區連線讀取秘密。

POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}/listsecrets?api-version=2023-08-01-preview
Authorization: Bearer {{token}}

注意

先前的程式碼片段會在進行 REST API 呼叫時，在 Authorization 標頭中使用權杖。您可以執行 az account get-access-token 來取得權杖。如需取得權杖的詳細資訊，請參閱取得存取權杖。

(選擇性) 使用 Azure Key Vault 作為秘密存放區

建立金鑰保存庫，並設定要用於部署的秘密。如需詳細資訊，請參閱使用 Azure CLI 從 Azure Key Vault 設定及擷取祕密。此外，

az keyvault CLI 和 Set Secret REST API 示範如何設定秘密。
az keyvault secret show CLI 和 Get Secret Versions REST API 示範如何擷取秘密版本。

建立 Azure Key Vault:

az keyvault create --name mykeyvault --resource-group myrg --location eastus

建立祕密:
```
az keyvault secret set --vault-name mykeyvault --name secret1 --value <value>
```
此命令會傳回所建立的秘密版本。您可以檢查回應的 id 屬性，以取得秘密版本。傳回的回應看起來像 https://mykeyvault.vault.azure.net/secrets/<secret_name>/<secret_version>。

確認使用者身分識別可以從金鑰保存庫讀取秘密:

az keyvault secret show --vault-name mykeyvault --name secret1 --version <secret_version>

重要

如果您使用金鑰保存庫作為秘密插入的秘密存放區，您必須將金鑰保存庫的權限模型設定為 Azure 角色型存取控制 (RBAC)。如需詳細資訊，請參閱 Azure RBAC 與 Key Vault 的存取原則。

選擇使用者身分識別

選擇您將用來建立線上端點和線上部署的使用者身分識別。此使用者身分識別可以是使用者帳戶、服務主體帳戶，或 Microsoft Entra ID 中的受控識別。依照設定 Azure Machine Learning 資源和工作流程的驗證中的步驟，在您的工作區中建立服務主體。

(選擇性) 將角色指派給使用者身分識別

如果您的使用者身分識別想要端點的系統指派身分識別 (SAI) 自動獲授與權限，以從工作區連線讀取秘密，則使用者身分識別必須在工作區範圍內具有 Azure Machine Learning Workspace Connection Secrets Reader 角色 (或更高權限)。
- 具有 Microsoft.Authorization/roleAssignments/write 權限的系統管理員可以執行 CLI 命令，將角色指派給 使用者身分識別:
```
az role assignment create --assignee <UserIdentityID> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
```
注意

端點的系統指派身分識別 (SAI) 不會自動獲得從金鑰保存庫讀取秘密的權限。因此，使用者身分識別不需要為 Key Vault 指派角色。

如果您想要將使用者指派的身分識別 (UAI) 用於端點，您不需要將角色指派給使用者身分識別。相反地，如果您想要使用秘密插入功能，您必須手動將角色指派給端點的 UAI。

具有 Microsoft.Authorization/roleAssignments/write 權限的系統管理員可以執行下列命令，將角色指派給 使用者身分識別:

針對工作區連線:

az role assignment create --assignee <EndpointIdentityID> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

針對金鑰保存庫:

az role assignment create --assignee <EndpointIdentityID> --role "Key Vault Secrets User" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.KeyVault/vaults/<vaultName>

移至 Azure 入口網站中的資源，確認身分識別(使用者身分識別或端點身分識別) 已獲指派角色。例如，在 Azure Machine Learning 工作區或 Key Vault 中:
1. 選取 [存取控制 (IAM)] 索引標籤。
2. 選取 [檢查存取] 按鈕，然後尋找身分識別。
3. 確認正確的角色會顯示在 [目前的角色指派] 索引標籤下。

如果您正使用系統指派的身分識別 (SAI) 作為端點身分識別，請指定是否要強制端點身分識別存取預設秘密存放區 (也就是工作區下的工作區連線)。

建立 endpoint.yaml 檔案︰

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: key
properties:
    enforce_access_to_default_secret_stores: enabled  # default: disabled

使用 endpoint.yaml 檔案建立端點:

az ml online-endpoint create -f endpoint.yaml

如果您未在端點定義中指定 identity 屬性，則端點預設會使用 SAI。

如果符合下列條件，端點身分識別會自動在工作區範圍上授與 Azure Machine Learning Workspace Connection Secrets Reader 角色 (或更高角色):

建立端點的使用者身分識別有權從工作區連線讀取秘密 (Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action)。
端點會使用 SAI。
端點會使用旗標來定義，以在建立端點時強制存取預設秘密存放區 (目前工作區下的工作區連線)。

端點身分識別不會自動獲授與角色，以從 Key Vault 讀取秘密。如果您想要使用 Key Vault 作為秘密存放區，您必須手動指派適當的角色 (例如 Key Vault Secrets User) 到 Key Vault 範圍上的端點身分識別。如需角色的詳細資訊，請參閱 Key Vault 資料平面作業的 Azure 內建角色。

如果您使用使用者指派的身分識別 (UAI) 作為端點身分識別，則不允許指定 enforce_access_to_default_secret_stores 旗標。

建立 endpoint.yaml 檔案︰

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: key
identity:
    type: user_assigned
    user_assigned_identities: /subscriptions/00000000-0000-0000-000-000000000000/resourcegroups/myrg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/my-identity

使用 endpoint.yaml 檔案建立端點:

az ml online-endpoint create -f endpoint.yaml

使用 UAI 時，您必須手動將任何必要的角色指派給端點身分識別，如選擇性區段將角色指派給使用者身分識別中所述。

建立部署

撰寫評分指令碼或 Dockerfile 和相關指令碼，讓部署可以透過環境變數取用秘密。
- 您不需要呼叫工作區連線或金鑰保存庫的秘密擷取 API。當部署中的使用者容器起始時，環境變數會填入秘密。
- 插入環境變數的值可以是下列三種類型之一:
  - 整個清單秘密 API (預覽) 回應。您必須了解 API 回應結構、剖析它，並在您的使用者容器中使用它。
  - 工作區連線中的個別秘密或中繼資料。您可以在不了解工作區連線 API 回應結構的情況下使用它。
  - Key Vault 中的個別秘密版本。您可以在不了解 Key Vault API 回應結構的情況下使用它。

使用評分指令碼 (如果您使用自訂模型) 或 Dockerfile (如果您採用 BYOC 方法部署) 來起始部署的建立。指定使用者預期在使用者容器內的環境變數。

如果對應至環境變數的值遵循特定模式，則會使用端點身份識別來執行秘密擷取和插入。

模式	行為
`${{azureml://connections/<connection_name>}}`	整個清單秘密 API (預覽) 回應會插入環境變數中。
`${{azureml://connections/<connection_name>/credentials/<credential_name>}}`	認證的值會插入環境變數中。
`${{azureml://connections/<connection_name>/metadata/<metadata_name>}}`	中繼資料的值會插入環境變數中。
`${{azureml://connections/<connection_name>/target}}`	目標的值 (如果適用) 會插入環境變數中。
`${{keyvault:https://<keyvault_name>.vault.azure.net/secrets/<secret_name>/<secret_version>}}`	秘密版本的值會插入環境變數中。

例如：

建立 deployment.yaml：

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-endpoint
#…
environment_variables:
    AOAI_CONNECTION: ${{azureml://connections/aoai_connection}}
    LANGCHAIN_CONNECTION: ${{azureml://connections/multi_connection_langchain}}

    OPENAI_KEY: ${{azureml://connections/multi_connection_langchain/credentials/OPENAI_API_KEY}}
    OPENAI_VERSION: ${{azureml://connections/multi_connection_langchain/metadata/OPENAI_API_VERSION}}

    USER_SECRET_KV1_KEY: ${{keyvault:https://mykeyvault.vault.azure.net/secrets/secret1/secretversion1}}

建立部署：

az ml online-deployment create -f deployment.yaml

如果已為端點設定 enforce_access_to_default_secret_stores 旗標，則會在端點建立和部署建立時檢查使用者身分識別從工作區連線讀取秘密的權限。如果使用者身分識別沒有權限，建立將會失敗。

在部署建立期間，如果任何環境變數都對應至遵循上表模式的值，則會使用端點身分識別執行秘密擷取和插入 (SAI 或 UAI)。如果端點身分識別沒有權限從指定的秘密存放區讀取秘密 (工作區連線或金鑰保存庫)，則部署建立將會失敗。此外，如果指定的秘密參考不存在於秘密存放區中，則部署建立將會失敗。

如需部署 Azure Machine Learning 線上端點期間可能發生之錯誤的詳細資訊，請參閱秘密插入錯誤。

取用秘密

您可以從部署中執行的使用者容器內的環境變數擷取秘密，以取用秘密。

共用方式為

使用秘密插入從線上部署存取秘密 (預覽)

必要條件

選擇祕密存放區

使用工作區連線作為秘密存放區

(選擇性) 使用 Azure Key Vault 作為秘密存放區

選擇使用者身分識別

(選擇性) 將角色指派給使用者身分識別

建立端點

建立部署

取用秘密

意見反應

其他資源

共用方式為

使用秘密插入從線上部署存取秘密 (預覽)

必要條件

選擇祕密存放區

使用工作區連線作為秘密存放區

(選擇性) 使用 Azure Key Vault 作為秘密存放區

選擇使用者身分識別

(選擇性) 將角色指派給使用者身分識別

建立端點

建立部署

取用秘密

相關內容

意見反應

其他資源