الوصول إلى البيانات السرية من النشر عبر الإنترنت باستخدام إدخال البيانات السرية (معاينة)

ينطبق على:ملحق ML Azure CLI v2 (الحالي)Python SDK azure-ai-ml v2 (الحالي)

في هذه المقالة، تتعلم استخدام إدخال البيانات السرية مع نقطة نهاية عبر الإنترنت والنشر للوصول إلى الأسرار من مخزن سري.

هنا، ستتعلم ما يلي:

• إعداد هوية المستخدم وأذوناته
• إنشاء اتصالات مساحة العمل و/أو خزائن المفاتيح لاستخدامها كمتاجر سرية
• إنشاء نقطة النهاية والنشر باستخدام ميزة الحقن السري

هام

تُعد هذه الميزة قيد الإصدار الأولي العام في الوقت الحالي. يجري توفير إصدار المعاينة هذا دون اتفاقية على مستوى الخدمة، ولا نوصي باستخدامه لأحمال عمل الإنتاج. بعض الميزات ربما لا تكون مدعمة أو بها بعض القدرات المقيدة.

لمزيد من المعلومات، راجع ⁧⁩شروط الاستخدام التكميلية لمعاينات Microsoft Azure⁧⁩.

المتطلبات الأساسية

• لاستخدام التعلم الآلي من Azure، يجب أن يكون لديك اشتراك Azure. في حال لم يكن لديك اشتراك Azure، فأنشئ حساباً مجانيّاً قبل البدء. جرب الإصدار المجاني أو المدفوع الخاص بـ Azure Machine Learning اليوم.

• تثبيت وتكوين ملحق Azure التعلم الآلي CLI (v2) أو Azure التعلم الآلي Python SDK (v2).

• مجموعة موارد Azure، حيث تحتاج (أو مسؤول الخدمة الذي تستخدمه) إلى الحصول على حق الوصول إلى User Access Administrator وContributor. سيكون لديك مجموعة موارد مثل إذا قمت بتكوين ملحق Azure التعلم الآلي كما هو مذكور سابقا.

• مساحة عمل للتعلم الآلي من Microsoft Azure. سيكون لديك مساحة عمل إذا قمت بتكوين ملحق Azure التعلم الآلي كما هو مذكور سابقا.

• أي نموذج تعلم آلي مدرب جاهز للتسجيل والنشر.

اختيار مخزن سري

يمكنك اختيار تخزين أسرارك (مثل مفاتيح API) باستخدام إما:

• اتصالات مساحة العمل ضمن مساحة العمل: إذا كنت تستخدم هذا النوع من المخزن السري، يمكنك لاحقا منح الإذن لهوية نقطة النهاية (في وقت إنشاء نقطة النهاية) لقراءة البيانات السرية من اتصالات مساحة العمل تلقائيا، شريطة استيفاء شروط معينة. لمزيد من المعلومات، راجع علامة تبويب الهوية المعينة من قبل النظام من قسم إنشاء نقطة نهاية.
• خزائن المفاتيح التي ليست بالضرورة ضمن مساحة العمل: إذا كنت تستخدم هذا النوع من المخزن السري، فلن يتم منح هوية نقطة النهاية الإذن لقراءة الأسرار من خزائن المفاتيح تلقائيا. لذلك، إذا كنت ترغب في استخدام خدمة مخزن مفاتيح مدارة مثل Microsoft Azure Key Vault كمخزن سري، يجب عليك تعيين دور مناسب لاحقا.

استخدام اتصال مساحة العمل كمخزن سري

يمكنك إنشاء اتصالات مساحة العمل لاستخدامها في النشر الخاص بك. على سبيل المثال، يمكنك إنشاء اتصال بخدمة Microsoft Azure OpenAI باستخدام اتصالات مساحة العمل - إنشاء واجهة برمجة تطبيقات REST.

بدلا من ذلك، يمكنك إنشاء اتصال مخصص باستخدام Azure التعلم الآلي studio (راجع كيفية إنشاء اتصال مخصص لتدفق المطالبة) أو Azure الذكاء الاصطناعي Studio (راجع كيفية إنشاء اتصال مخصص في الذكاء الاصطناعي Studio).

1. إنشاء اتصال 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"
           }
       }
   }
   

2. بدلا من ذلك، يمكنك إنشاء اتصال مخصص:

   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. تحقق من أن هوية المستخدم يمكنها قراءة الأسرار من اتصال مساحة العمل، باستخدام Workspace Connections - List Secrets 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}}
   

إشعار

تستخدم القصاصات البرمجية السابقة رمزا مميزا في Authorization العنوان عند إجراء استدعاءات واجهة برمجة تطبيقات REST. يمكنك الحصول على الرمز المميز عن طريق تشغيل az account get-access-token. لمزيد من المعلومات حول الحصول على رمز مميز، راجع الحصول على رمز مميز للوصول.

(اختياري) استخدام Azure Key Vault كمخزن سري

قم بإنشاء مخزن المفاتيح وتعيين سر لاستخدامه في النشر الخاص بك. لمزيد من المعلومات حول إنشاء مخزن المفاتيح، راجع تعيين سر واسترداده من Azure Key Vault باستخدام Azure CLI. أيضًا

• توضح az keyvault CLI و Set Secret REST API كيفية تعيين سر.
• az keyvault secret show CLI and Get Secret Versions REST API show how to retrieve a secret version.

1. إنشاء Azure Key Vault:

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

2. إنشاء سر:

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

   يقوم هذا الأمر بإرجاع الإصدار السري الذي يقوم بإنشائه. يمكنك التحقق من id خاصية الاستجابة للحصول على الإصدار السري. تبدو الاستجابة التي تم إرجاعها مثل https://mykeyvault.vault.azure.net/secrets/<secret_name>/<secret_version>.

3. تحقق من أن هوية المستخدم يمكنها قراءة السر من مخزن المفاتيح:

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

هام

إذا كنت تستخدم مخزن المفاتيح كمخزن سري لحقن البيانات السرية، فيجب عليك تكوين نموذج إذن مخزن المفاتيح كعنصر تحكم في الوصول استنادا إلى دور Azure (RBAC). لمزيد من المعلومات، راجع Azure RBAC مقابل نهج الوصول ل Key Vault.

اختيار هوية مستخدم

اختر هوية المستخدم التي ستستخدمها لإنشاء نقطة النهاية عبر الإنترنت والنشر عبر الإنترنت. يمكن أن تكون هوية المستخدم هذه حساب مستخدم أو حساب كيان خدمة أو هوية مدارة في معرف Microsoft Entra. لإعداد هوية المستخدم، اتبع الخطوات الواردة في إعداد المصادقة لموارد Azure التعلم الآلي ومهام سير العمل.

(اختياري) تعيين دور لهوية المستخدم

• إذا كانت هوية المستخدم تريد منح الهوية المعينة من قبل النظام لنقطة النهاية (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>
    

• تحقق من أن الهوية (إما هوية المستخدم أو هوية نقطة النهاية) لها الدور المعين، عن طريق الانتقال إلى المورد في مدخل Microsoft Azure. على سبيل المثال، في مساحة عمل Azure التعلم الآلي أو Key Vault:

  1. حدد علامة التبويب Access control (IAM).
  2. حدد زر التحقق من الوصول وابحث عن الهوية.
  3. تحقق من ظهور الدور الصحيح ضمن علامة التبويب تعيينات الدور الحالي.

إنشاء نقطة النهاية

الهوية المعينة من قبل النظام

إذا كنت تستخدم هوية معينة من قبل النظام (SAI) كهوية نقطة النهاية، فحدد ما إذا كنت تريد فرض الوصول إلى المتاجر السرية الافتراضية (أي اتصالات مساحة العمل ضمن مساحة العمل) إلى هوية نقطة النهاية.

1. 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
   

2. إنشاء نقطة النهاية، باستخدام 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. لمزيد من المعلومات حول الأدوار، راجع الأدوار المضمنة في Azure لعمليات مستوى بيانات Key Vault.

الهوية التي تم تعيينها من قبل المستخدم

إذا كنت تستخدم هوية معينة من قبل المستخدم (UAI) كهوية نقطة النهاية، فلا يسمح لك بتحديد العلامة enforce_access_to_default_secret_stores .

1. 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 
   

2. إنشاء نقطة النهاية، باستخدام endpoint.yaml الملف:

   az ml online-endpoint create -f endpoint.yaml
   

عند استخدام UAI، يجب تعيين أي أدوار مطلوبة يدويا إلى هوية نقطة النهاية كما هو موضح في القسم الاختياري تعيين دور لهوية المستخدم.

إنشاء توزيع

1. تأليف برنامج نصي لتسجيل النقاط أو Dockerfile والبرامج النصية ذات الصلة بحيث يمكن أن يستهلك النشر الأسرار عبر متغيرات البيئة.

   • ليست هناك حاجة لك لاستدعاء واجهات برمجة التطبيقات الخاصة باسترداد البيانات السرية لاتصالات مساحة العمل أو خزائن المفاتيح. يتم ملء متغيرات البيئة بالبيانات السرية عند بدء حاوية المستخدم في النشر.

   • يمكن أن تكون القيمة التي يتم إدخالها في متغير البيئة أحد الأنواع الثلاثة:

     • استجابة List Secrets API (معاينة) بأكملها. ستحتاج إلى فهم بنية استجابة واجهة برمجة التطبيقات وتحليلها واستخدامها في حاوية المستخدم.
     • بيانات سرية أو بيانات تعريف فردية من اتصال مساحة العمل. يمكنك استخدامه دون فهم بنية استجابة واجهة برمجة تطبيقات اتصال مساحة العمل.
     • إصدار سري فردي من Key Vault. يمكنك استخدامه دون فهم بنية استجابة واجهة برمجة تطبيقات Key Vault.

2. ابدأ إنشاء النشر، باستخدام إما البرنامج النصي لتسجيل النقاط (إذا كنت تستخدم نموذجا مخصصا) أو Dockerfile (إذا اتبعت نهج BYOC للتوزيع). حدد متغيرات البيئة التي يتوقعها المستخدم داخل حاوية المستخدم.

   إذا كانت القيم التي تم تعيينها إلى متغيرات البيئة تتبع أنماطا معينة، استخدام هوية نقطة النهاية لإجراء استرداد البيانات السرية والحقن.

   النمط	سلوك
   ${{azureml://connections/<connection_name>}}	يتم إدخال استجابة List Secrets 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>}}	يتم إدخال قيمة الإصدار السري في متغير البيئة.

   على سبيل المثال:

   1. إنشاء 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. إنشاء التوزيع:

      az ml online-deployment create -f deployment.yaml
      

enforce_access_to_default_secret_stores إذا تم تعيين العلامة لنقطة النهاية، التحقق من إذن هوية المستخدم لقراءة البيانات السرية من اتصالات مساحة العمل في وقت إنشاء نقطة النهاية وإنشاء النشر. إذا لم يكن لدى هوية المستخدم الإذن، فسيفشل الإنشاء.

في وقت إنشاء النشر، إذا تم تعيين أي متغير بيئة إلى قيمة تتبع الأنماط في الجدول السابق، إجراء استرداد البيانات السرية والإدخال بهوية نقطة النهاية (إما SAI أو UAI). إذا لم يكن لدى هوية نقطة النهاية الإذن لقراءة الأسرار من المتاجر السرية المعينة (إما اتصالات مساحة العمل أو خزائن المفاتيح)، فسيفشل إنشاء النشر. أيضا، إذا لم يكن المرجع السري المحدد موجودا في المتاجر السرية، فسيفشل إنشاء النشر.

لمزيد من المعلومات حول الأخطاء التي يمكن أن تحدث أثناء نشر Azure التعلم الآلي نقاط النهاية عبر الإنترنت، راجع أخطاء الحقن السري.

استهلاك الأسرار

يمكنك استهلاك الأسرار عن طريق استردادها من متغيرات البيئة داخل حاوية المستخدم التي تعمل في عمليات النشر الخاصة بك.

المحتوى ذو الصلة

• إدخال البيانات السرية في نقاط النهاية عبر الإنترنت (معاينة)
• كيفية مصادقة العملاء لنقطة النهاية عبر الإنترنت
• توزيع نموذج وتسجيله باستخدام نقطة نهاية عبر الإنترنت
• استخدام حاوية مخصصة لنشر نموذج باستخدام نقطة نهاية عبر الإنترنت