Aracılığıyla paylaş

Gizli dizi ekleme (önizleme) kullanarak çevrimiçi dağıtımdan gizli dizilere erişme

  • Makale

ŞUNLAR IÇIN GEÇERLIDIR: Azure CLI ml uzantısı v2 (geçerli)Python SDK azure-ai-ml v2 (geçerli)

Bu makalede, bir gizli dizi deposundan gizli dizilere erişmek için çevrimiçi uç nokta ve dağıtım ile gizli dizi ekleme kullanmayı öğreneceksiniz.

Öğrenecekleriniz:

  • Kullanıcı kimliğinizi ve izinlerini ayarlama
  • Gizli dizi depoları olarak kullanmak için çalışma alanı bağlantıları ve/veya anahtar kasaları oluşturma
  • Gizli dizi ekleme özelliğini kullanarak uç nokta ve dağıtım oluşturma

Önemli

Bu özellik şu anda genel önizlemededir. Bu önizleme sürümü hizmet düzeyi sözleşmesi olmadan sağlanır ve üretim iş yükleri için bu sürümü önermeyiz. Bazı özellikler desteklenmiyor olabileceği gibi özellikleri sınırlandırılmış da olabilir.

Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri Ek Kullanım Koşulları.

Önkoşullar

  • Azure Machine Learning'i kullanmak için bir Azure aboneliğiniz olmalıdır. Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap oluşturun. Azure Machine Learning'in ücretsiz veya ücretli sürümünü bugün deneyin.

  • Azure Machine Learning CLI (v2) uzantısını veya Azure Machine Learning Python SDK'sını (v2) yükleyin ve yapılandırın.

  • Sizin (veya kullandığınız hizmet sorumlusunun) sahip User Access Administrator olması ve Contributor erişmesi gereken bir Azure Kaynak grubu. Azure Machine Learning uzantınızı daha önce belirtildiği gibi yapılandırdıysanız böyle bir kaynak grubunuz olur.

  • Azure Machine Learning çalışma alanı. Azure Machine Learning uzantınızı daha önce belirtildiği gibi yapılandırdıysanız bir çalışma alanınız olur.

  • Puanlama ve dağıtım için hazır olan tüm eğitilmiş makine öğrenmesi modelleri.

Gizli dizi deposu seçme

Aşağıdakilerden birini kullanarak gizli dizilerinizi (API anahtarları gibi) depolamayı seçebilirsiniz:

  • Çalışma alanı altındaki çalışma alanı bağlantıları: Bu tür bir gizli dizi deposu kullanıyorsanız, daha sonra belirli koşulların karşılanması koşuluyla, çalışma alanı bağlantılarından gizli dizileri otomatik olarak okumak için uç nokta kimliğine (uç nokta oluşturma zamanında) izin vekleyebilirsiniz. Daha fazla bilgi için Uç nokta oluşturma bölümündeki sistem tarafından atanan kimlik sekmesine bakın.
  • Çalışma alanı altında olması gerekmeyen anahtar kasaları : Bu tür bir gizli dizi deposu kullanırsanız, uç nokta kimliğine anahtar kasalarından gizli dizileri otomatik olarak okuma izni verilmez. Bu nedenle, Microsoft Azure Key Vault gibi bir yönetilen anahtar kasası hizmetini gizli dizi deposu olarak kullanmak istiyorsanız, daha sonra uygun bir rol atamanız gerekir.

Çalışma alanı bağlantısını gizli dizi deposu olarak kullanma

Dağıtımınızda kullanmak üzere çalışma alanı bağlantıları oluşturabilirsiniz. Örneğin, Çalışma Alanı Bağlantıları - REST API oluştur'u kullanarak Microsoft Azure OpenAI Hizmeti'ne bağlantı oluşturabilirsiniz.

Alternatif olarak, Azure Machine Learning stüdyosu (bkz. komut istemi akışı için özel bağlantı oluşturma) veya Azure AI Studio kullanarak özel bağlantı oluşturabilirsiniz (bkz. AI Studio'da özel bağlantı oluşturma).

  1. Azure OpenAI bağlantısı oluşturma:

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

  2. Alternatif olarak, özel bir bağlantı oluşturabilirsiniz:

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

  3. Çalışma Alanı Bağlantıları - Gizli Dizileri Listeleme REST API'sini (önizleme) kullanarak kullanıcı kimliğinin çalışma alanı bağlantısındaki gizli dizileri okuyabildiğini doğrulayın.

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

Not

Önceki kod parçacıkları REST API çağrıları yaparken üst bilgide Authorization bir belirteç kullanır. komutunu çalıştırarak az account get-access-tokenbelirteci alabilirsiniz. Belirteç alma hakkında daha fazla bilgi için bkz . Erişim belirteci alma.

(İsteğe bağlı) Azure Key Vault'un gizli dizi deposu olarak kullanılmasını sağlama

Anahtar kasasını oluşturun ve dağıtımınızda kullanmak üzere bir gizli dizi ayarlayın. Anahtar kasasını oluşturma hakkında daha fazla bilgi için bkz . Azure CLI kullanarak Azure Key Vault'tan gizli dizi ayarlama ve alma. Ayrıca

  1. Azure Key Vault oluşturma:

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

  2. Gizli dizi oluşturma:

    az keyvault secret set --vault-name mykeyvault --name secret1 --value <value>

    Bu komut, oluşturduğu gizli dizi sürümünü döndürür. Gizli dizi sürümünü almak için yanıtın özelliğini de kontrol id edebilirsiniz. Döndürülen yanıt gibi https://mykeyvault.vault.azure.net/secrets/<secret_name>/<secret_version>görünür.

  3. Kullanıcı kimliğinin anahtar kasasından gizli diziyi okuyabildiğini doğrulayın:

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

Önemli

Anahtar kasasını gizli dizi ekleme için gizli dizi deposu olarak kullanıyorsanız, anahtar kasasının izin modelini Azure rol tabanlı erişim denetimi (RBAC) olarak yapılandırmanız gerekir. Daha fazla bilgi için bkz . Azure RBAC ile Key Vault için erişim ilkesi karşılaştırması.

Kullanıcı kimliği seçme

Çevrimiçi uç noktayı ve çevrimiçi dağıtımı oluşturmak için kullanacağınız kullanıcı kimliğini seçin. Bu kullanıcı kimliği bir kullanıcı hesabı, hizmet sorumlusu hesabı veya Microsoft Entra Id'de yönetilen kimlik olabilir. Kullanıcı kimliğini ayarlamak için Azure Machine Learning kaynakları ve iş akışları için kimlik doğrulamasını ayarlama bölümünde yer alan adımları izleyin.

(İsteğe bağlı) Kullanıcı kimliğine rol atama

  • Kullanıcı kimliğiniz uç noktanın sistem tarafından atanan kimliğine (SAI) çalışma alanı bağlantılarından gizli dizileri okuma izninin otomatik olarak verilmesini istiyorsa, kullanıcı kimliğinin çalışma alanı kapsamında rolü (veya üzeri) olmalıdırAzure Machine Learning Workspace Connection Secrets Reader.

    • İzine Microsoft.Authorization/roleAssignments/write sahip bir yönetici, rolü kullanıcı kimliğine atamak için bir CLI komutu çalıştırabilir:

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

    Not

    Uç noktanın sistem tarafından atanan kimliğine (SAI) anahtar kasalarından gizli dizileri okuma izni otomatik olarak verilmez. Bu nedenle, kullanıcı kimliğine Key Vault için bir rol atanması gerekmez.

  • Uç nokta için kullanıcı tarafından atanan bir kimlik (UAI) kullanmak istiyorsanız, rolü kullanıcı kimliğinize atamanız gerekmez . Bunun yerine gizli dizi ekleme özelliğini kullanmayı planlıyorsanız, rolü uç noktanın UAI'sine el ile atamanız gerekir.

    • İzine Microsoft.Authorization/roleAssignments/write sahip bir yönetici, rolü uç nokta kimliğine atamak için aşağıdaki komutları çalıştırabilir:

      Çalışma alanı bağlantıları için:

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

      Anahtar kasaları için:

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

  • Azure portalındaki kaynağa giderek bir kimliğin (kullanıcı kimliği veya uç nokta kimliği) rolüne atandığını doğrulayın. Örneğin, Azure Machine Learning çalışma alanında veya Key Vault'ta:

    1. Erişim denetimi (IAM) sekmesini seçin.
    2. Erişimi denetle düğmesini seçin ve kimliği bulun.
    3. Geçerli rol atamaları sekmesinde doğru rolün gösterildiğini doğrulayın.

Uç nokta oluşturma

Uç nokta kimliği olarak sistem tarafından atanan bir kimlik (SAI) kullanıyorsanız, uç nokta kimliğine varsayılan gizli dizi depolarına (çalışma alanı altındaki çalışma alanı bağlantıları) erişimi zorunlu kılmak isteyip istemediğinizi belirtin.

  1. Bir endpoint.yaml dosyası oluşturun:

    $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

  2. Dosyasını kullanarak endpoint.yaml uç noktayı oluşturun:

    az ml online-endpoint create -f endpoint.yaml

Uç nokta tanımında identity özelliğini belirtmezseniz, uç nokta varsayılan olarak bir SAI kullanır.

Aşağıdaki koşullar karşılanırsa, uç nokta kimliğine otomatik olarak çalışma alanı kapsamında rol (veya üzeri) verilir Azure Machine Learning Workspace Connection Secrets Reader :

  • Uç noktayı oluşturan kullanıcı kimliği, çalışma alanı bağlantılarından ( ) gizli dizileri okuma iznine sahiptirMicrosoft.MachineLearningServices/workspaces/connections/listsecrets/action.
  • Uç nokta bir SAI kullanır.
  • Uç nokta, uç nokta oluşturulurken varsayılan gizli dizi depolarına (geçerli çalışma alanı altındaki çalışma alanı bağlantıları) erişimi zorlamak için bir bayrakla tanımlanır.

Key Vault'tan gizli dizileri okumak için uç nokta kimliğine otomatik olarak bir rol verilmez. Key Vault'un gizli dizi deposu olarak kullanılmasını istiyorsanız, Key Vault kapsamındaki uç nokta kimliğine gibi Key Vault Secrets User uygun bir rolü el ile atamanız gerekir. Roller hakkında daha fazla bilgi için bkz . Key Vault veri düzlemi işlemleri için Azure yerleşik rolleri.

Dağıtım oluşturma

  1. Dağıtımın ortam değişkenleri aracılığıyla gizli dizileri tüketmesi için bir puanlama betiği veya Dockerfile ve ilgili betikler yazın.

    • Çalışma alanı bağlantıları veya anahtar kasaları için gizli dizi alma API'lerini çağırmanıza gerek yoktur. Ortam değişkenleri, dağıtımdaki kullanıcı kapsayıcısı başlatıldığında gizli dizilerle doldurulur.

    • Ortam değişkenine eklenen değer üç türden biri olabilir:

      • Tüm Liste Gizli Dizileri API'si (önizleme) yanıtı. API yanıt yapısını anlamanız, ayrıştırmanız ve kullanıcı kapsayıcınızda kullanmanız gerekir.
      • Çalışma alanı bağlantısından tek tek gizli dizi veya meta veriler. Çalışma alanı bağlantı API'sinin yanıt yapısını anlamadan bunu kullanabilirsiniz.
      • Key Vault'tan tek tek gizli sürüm. Key Vault API yanıt yapısını anlamadan kullanabilirsiniz.

  2. Puanlama betiğini (özel model kullanıyorsanız) veya bir Dockerfile kullanarak (KCG yaklaşımını dağıtıma alırsanız) dağıtımın oluşturulmasını başlatın. Kullanıcının kullanıcı kapsayıcısı içinde beklediği ortam değişkenlerini belirtin.

    Ortam değişkenlerine eşlenen değerler belirli desenleri izlerse, gizli dizi alma ve ekleme gerçekleştirmek için uç nokta kimliği kullanılır.

    Desen Davranış
    ${{azureml://connections/<connection_name>}} Liste Gizli Dizileri API'sinin tamamı (önizleme) yanıtı ortam değişkenine eklenir.
    ${{azureml://connections/<connection_name>/credentials/<credential_name>}} Kimlik bilgilerinin değeri ortam değişkenine eklenir.
    ${{azureml://connections/<connection_name>/metadata/<metadata_name>}} Meta verilerin değeri ortam değişkenine eklenir.
    ${{azureml://connections/<connection_name>/target}} Hedef değeri (uygun olduğunda) ortam değişkenine eklenir.
    ${{keyvault:https://<keyvault_name>.vault.azure.net/secrets/<secret_name>/<secret_version>}} Gizli sürüm değeri ortam değişkenine eklenir.

    Örneğin:

    1. Oluşturma 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}}

    2. Dağıtımı oluşturun:

      az ml online-deployment create -f deployment.yaml

enforce_access_to_default_secret_stores Uç nokta için bayrak ayarlandıysa, kullanıcı kimliğinin çalışma alanı bağlantılarından gizli dizileri okuma izni hem uç nokta oluşturma hem de dağıtım oluşturma zamanında denetlenecektir. Kullanıcı kimliğinin izni yoksa oluşturma başarısız olur.

Dağıtım oluşturma zamanında, herhangi bir ortam değişkeni önceki tablodaki desenleri izleyen bir değerle eşlenirse, gizli dizi alma ve ekleme uç nokta kimliğiyle (SAI veya UAI) gerçekleştirilir. Uç nokta kimliğinin belirlenen gizli dizi depolarından gizli dizileri okuma izni yoksa (çalışma alanı bağlantıları veya anahtar kasaları), dağıtım oluşturma başarısız olur. Ayrıca, belirtilen gizli dizi başvurusu gizli dizi depolarında yoksa dağıtım oluşturma başarısız olur.

Azure Machine Learning çevrimiçi uç noktalarının dağıtımı sırasında oluşabilecek hatalar hakkında daha fazla bilgi için bkz . Gizli Dizi Ekleme Hataları.

Gizli dizileri kullanma

Gizli dizileri, dağıtımlarınızda çalışan kullanıcı kapsayıcısı içindeki ortam değişkenlerinden alarak kullanabilirsiniz.

İlgili içerik