إدارة الذكاء الاصطناعي خدمة البحث Azure باستخدام Azure CLI

يمكنك تشغيل أوامر Azure CLI والبرامج النصية على Windows أو macOS أو Linux أو في Azure Cloud Shell لإنشاء وتكوين Azure الذكاء الاصطناعي Search. توسع وحدة البحث az CLI بتماثل كامل إلى واجهات برمجة تطبيقات REST لإدارة البحث والقدرة على تنفيذ المهام التالية:

في بعض الأحيان، يتم طرح أسئلة حول المهام غير الموجودة في القائمة أعلاه.

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

لا يمكنك استخدام الأدوات أو واجهات برمجة التطبيقات لنقل المحتوى، مثل الفهرس، من خدمة إلى أخرى. داخل الخدمة، يتم الإنشاء البرمجي للمحتوى من خلال Search Service REST API أو SDK مثل Azure SDK ل .NET. على الرغم من عدم وجود أوامر مخصصة لترحيل المحتوى، يمكنك كتابة برنامج نصي يستدعي واجهة برمجة تطبيقات REST أو مكتبة عميل لإنشاء الفهارس وتحميلها على خدمة جديدة.

عادة ما لا تتوفر ميزات إدارة المعاينة في الوحدة النمطية az search . إذا كنت ترغب في استخدام ميزة معاينة، فاستخدم Management REST API وإصدار واجهة برمجة تطبيقات المعاينة.

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

سرد الخدمات في اشتراك

الأوامر التالية من مورد az، وإرجاع معلومات حول الموارد والخدمات الموجودة التي تم توفيرها بالفعل في اشتراكك. إذا كنت لا تعرف عدد خدمات البحث التي تم إنشاؤها بالفعل، فترجع هذه الأوامر هذه المعلومات، مما يوفر لك رحلة إلى المدخل.

يقوم الأمر الأول بإرجاع كافة خدمات البحث.

az resource list --resource-type Microsoft.Search/searchServices --output table

من قائمة الخدمات، قم بإعادة معلومات حول مورد معين.

az resource list --name <search-service-name>

سرد كافة أوامر البحث من az

يمكنك عرض معلومات حول المجموعات الفرعية والأوامر المتوفرة في az search من داخل CLI. بدلا من ذلك، يمكنك مراجعة الوثائق.

لعرض المجموعات الفرعية المتوفرة داخل az search، قم بتشغيل الأمر التالي.

az search --help

يجب أن تبدو الاستجابة مشابهة للإخراج التالي.

Group
    az search : Manage Azure Search services, admin keys and query keys.
        WARNING: This command group is in preview and under development. Reference and support
        levels: https://aka.ms/CLI_refstatus
Subgroups:
    admin-key                    : Manage Azure Search admin keys.
    private-endpoint-connection  : Manage Azure Search private endpoint connections.
    private-link-resource        : Manage Azure Search private link resources.
    query-key                    : Manage Azure Search query keys.
    service                      : Manage Azure Search services.
    shared-private-link-resource : Manage Azure Search shared private link resources.

For more specific examples, use: az find "az search"

ضمن كل مجموعة فرعية، تتوفر أوامر متعددة. يمكنك مشاهدة الأوامر المتوفرة لمجموعة فرعية service عن طريق تشغيل السطر التالي.

az search service --help

يمكنك أيضا رؤية الوسيطات المتوفرة لأمر معين.

az search service create --help

الحصول على معلومات خدمة البحث

إذا كنت تعرف مجموعة الموارد التي تحتوي على خدمة البحث الخاصة بك، فقم بتشغيل az search service show لإرجاع تعريف الخدمة، بما في ذلك الاسم والمنطقة والطبقة والنسخ المتماثلة وعدد الأقسام. لهذا الأمر، قم بتوفير مجموعة الموارد التي تحتوي على خدمة البحث.

az search service show --name <service-name> --resource-group <search-service-resource-group-name>

إنشاء خدمة أو حذفها

لإنشاء خدمة بحث جديدة، استخدم الأمر az search service create.

az search service create \
    --name <service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1

يجب أن تبدو النتائج مشابهة للإخراج التالي:

{
  "hostingMode": "default",
  "id": "/subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp",
  "identity": null,
  "location": "West US",
  "name": "my-demo-searchapp",
  "networkRuleSet": {
    "bypass": "None",
    "ipRules": []
  },
  "partitionCount": 1,
  "privateEndpointConnections": [],
  "provisioningState": "succeeded",
  "publicNetworkAccess": "Enabled",
  "replicaCount": 1,
  "resourceGroup": "demo-westus",
  "sharedPrivateLinkResources": [],
  "sku": {
    "name": "standard"
  },
  "status": "running",
  "statusDetails": "",
  "tags": null,
  "type": "Microsoft.Search/searchServices"
}

az search service delete يزيل الخدمة وبياناتها.

az search service delete --name <service-name> \
                         --resource-group  <search-service-resource-group-name> \

إنشاء خدمة باستخدام قواعد IP

اعتمادا على متطلبات الأمان الخاصة بك، قد تحتاج إلى إنشاء خدمة بحث مع تكوين جدار حماية IP. للقيام بذلك، مرر عناوين IP العامة (v4) أو نطاقات CIDR إلى الوسيطة ip-rules كما هو موضح أدناه. يجب فصل القواعد بفاشمة (,) أو فاصلة منقوطة (;).

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --ip-rules "55.5.63.73;52.228.215.197;101.37.221.205"

إنشاء خدمة بهوية مدارة معينة من قبل النظام

في بعض الحالات، مثل عند استخدام الهوية المدارة للاتصال بمصدر بيانات، ستحتاج إلى تشغيل الهوية المدارة المعينة من قبل النظام. يتم ذلك عن طريق إضافة --identity-type SystemAssigned إلى الأمر .

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --identity-type SystemAssigned

إنشاء خدمة بنقطة نهاية خاصة

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

يوضح المثال التالي كيفية إنشاء خدمة بحث بنقطة نهاية خاصة.

أولا، انشر خدمة بحث مع PublicNetworkAccess تعيين إلى Disabled.

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --public-access Disabled

بعد ذلك، قم بإنشاء شبكة ظاهرية ونقطة نهاية خاصة.

# Create the virtual network
az network vnet create \
    --resource-group <vnet-resource-group-name> \
    --location "West US" \
    --name <virtual-network-name> \
    --address-prefixes 10.1.0.0/16 \
    --subnet-name <subnet-name> \
    --subnet-prefixes 10.1.0.0/24

# Update the subnet to disable private endpoint network policies
az network vnet subnet update \
    --name <subnet-name> \
    --resource-group <vnet-resource-group-name> \
    --vnet-name <virtual-network-name> \
    --disable-private-endpoint-network-policies true

# Get the id of the search service
id=$(az search service show \
    --resource-group <search-service-resource-group-name> \
    --name <search-service-name> \
    --query [id] \
    --output tsv)

# Create the private endpoint
az network private-endpoint create \
    --name <private-endpoint-name> \
    --resource-group <private-endpoint-resource-group-name> \
    --vnet-name <virtual-network-name> \
    --subnet <subnet-name> \
    --private-connection-resource-id $id \
    --group-id searchService \
    --connection-name <private-link-connection-name>  

وأخيرا، قم بإنشاء منطقة DNS خاصة.

## Create private DNS zone
az network private-dns zone create \
    --resource-group <private-dns-resource-group-name> \
    --name "privatelink.search.windows.net"

## Create DNS network link
az network private-dns link vnet create \
    --resource-group <private-dns-resource-group-name> \
    --zone-name "privatelink.search.windows.net" \
    --name "myLink" \
    --virtual-network <virtual-network-name> \
    --registration-enabled false

## Create DNS zone group
az network private-endpoint dns-zone-group create \
   --resource-group <private-endpoint-resource-group-name>\
   --endpoint-name <private-endpoint-name> \
   --name "myZoneGroup" \
   --private-dns-zone "privatelink.search.windows.net" \
   --zone-name "searchServiceZone"

لمزيد من المعلومات حول إنشاء نقاط نهاية خاصة في Azure CLI، راجع التشغيل السريع ل Private Link

إدارة اتصالات نقطة النهاية الخاصة

بالإضافة إلى إنشاء اتصال نقطة نهاية خاصة، يمكنك أيضا showالاتصال updateو و delete .

لاسترداد اتصال نقطة نهاية خاصة ورؤية حالته، استخدم az search private-endpoint-connection show.

az search private-endpoint-connection show \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> 

لتحديث الاتصال، استخدم az search private-endpoint-connection update. يعين المثال التالي اتصال نقطة نهاية خاصة إلى مرفوض:

az search private-endpoint-connection show \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> 
    --status Rejected \
    --description "Rejected" \
    --actions-required "Please fix XYZ"

لحذف اتصال نقطة النهاية الخاصة، استخدم az search private-endpoint-connection delete.

az search private-endpoint-connection delete \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> 

إعادة إنشاء مفاتيح المسؤول

لتدحرج مفاتيح واجهة برمجة تطبيقات المسؤول، استخدم az search admin-key renew. يتم إنشاء مفتاحي مسؤول مع كل خدمة للوصول المصادق عليه. المفاتيح مطلوبة في كل طلب. كلا المفتاحين المسؤولين مكافئان وظيفيا، ما يمنح حق الوصول للكتابة الكاملة إلى خدمة بحث مع القدرة على استرداد أي معلومات، أو إنشاء وحذف أي كائن. يوجد مفتاحان بحيث يمكنك استخدام أحدهما أثناء استبدال الآخر.

يمكنك إعادة إنشاء واحد فقط في كل مرة، محددة إما primary كمفتاح أو secondary . للخدمة دون انقطاع، تذكر تحديث جميع التعليمات البرمجية للعميل لاستخدام مفتاح ثانوي أثناء التدحرج فوق المفتاح الأساسي. تجنب تغيير المفاتيح أثناء تشغيل العمليات.

كما قد تتوقع، إذا قمت بإعادة إنشاء المفاتيح دون تحديث التعليمات البرمجية للعميل، فستفشل الطلبات التي تستخدم المفتاح القديم. لا تؤدي إعادة إنشاء جميع المفاتيح الجديدة إلى قفل الخدمة بشكل دائم، ولا يزال بإمكانك الوصول إلى الخدمة من خلال المدخل. بعد إعادة إنشاء المفاتيح الأساسية والثانوية، يمكنك تحديث التعليمات البرمجية للعميل لاستخدام المفاتيح الجديدة وستستأنف العمليات وفقا لذلك.

يتم إنشاء قيم مفاتيح API بواسطة الخدمة. لا يمكنك توفير مفتاح مخصص لاستخدام Azure الذكاء الاصطناعي Search. وبالمثل، لا يوجد اسم معرف من قبل المستخدم لمفاتيح واجهة برمجة تطبيقات المسؤول. المراجع إلى المفتاح هي سلاسل ثابتة، إما primary أو secondary.

az search admin-key renew \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name> \
    --key-kind primary

ينبغي أن تتشابه النتائج مع المثال التالي. يتم إرجاع كلا المفتاحين على الرغم من أنك تقوم بتغيير واحد فقط في كل مرة.

{
  "primaryKey": <alphanumeric-guid>,
  "secondaryKey": <alphanumeric-guid>  
}

إنشاء مفاتيح الاستعلام أو حذفها

لإنشاء مفاتيح واجهة برمجة تطبيقات الاستعلام للوصول للقراءة فقط من تطبيقات العميل إلى فهرس Azure الذكاء الاصطناعي Search، استخدم az search query-key create. يتم استخدام مفاتيح الاستعلام للمصادقة على فهرس معين لغرض استرداد نتائج البحث. لا تمنح مفاتيح الاستعلام حق الوصول للقراءة فقط إلى عناصر أخرى في الخدمة، مثل فهرس أو مصدر بيانات أو مفهرس.

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

az search query-key create \
    --name myQueryKey \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name>

توسيع نطاق النسخ المتماثلة والأقسام

لزيادة النسخ المتماثلة والأقسام أو تقليلها، استخدم az search service update. تؤدي زيادة النسخ المتماثلة أو الأقسام إلى إضافة إلى الفاتورة، والتي تحتوي على رسوم ثابتة ومتغيرة. إذا كانت لديك حاجة مؤقتة إلى طاقة معالجة إضافية، يمكنك زيادة النسخ المتماثلة والأقسام للتعامل مع حمل العمل. تحتوي منطقة المراقبة في صفحة مدخل النظرة العامة على تجانبات حول زمن انتقال الاستعلام والاستعلامات في الثانية والتقييد، ما يشير إلى ما إذا كانت السعة الحالية كافية.

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

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

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

az search service update \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --partition-count 6 \
    --replica-count 6

بالإضافة إلى تحديث النسخ المتماثلة وعدد الأقسام، يمكنك أيضا تحديث ip-rulesو public-accessو.identity-type

يشار إلى نقاط النهاية الخاصة للموارد الآمنة التي تم إنشاؤها من خلال واجهات برمجة تطبيقات Azure الذكاء الاصطناعي Search باسم موارد الارتباط الخاص المشتركة. وذلك لأنك "تشارك" الوصول إلى مورد، مثل حساب تخزين، تم دمجه مع خدمة Azure Private Link.

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

يمكن العثور على قائمة كاملة بموارد Azure التي يمكنك إنشاء نقاط نهاية خاصة صادرة لها من Azure الذكاء الاصطناعي Search هنا جنبا إلى جنب مع قيم معرف المجموعة ذات الصلة.

لإنشاء مورد الارتباط الخاص المشترك، استخدم az search shared-private-link-resource create. ضع في اعتبارك أن بعض التكوين قد يكون مطلوبا لمصدر البيانات قبل تشغيل هذا الأمر.

az search shared-private-link-resource create \
    --name <spl-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --group-id blob \
    --resource-id "/subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage"  \
    --request-message "Please approve" 

لاسترداد موارد الارتباط الخاص المشترك وعرض حالتها، استخدم az search shared-private-link-resource list.

az search shared-private-link-resource list \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> 

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

id = (az storage account show -n myBlobStorage --query "privateEndpointConnections[0].id")

az network private-endpoint-connection approve --id $id

لحذف مورد الارتباط الخاص المشترك، استخدم az search shared-private-link-resource delete.

az search shared-private-link-resource delete \
    --name <spl-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> 

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

الخطوات التالية

إنشاء فهرس أو الاستعلام عن فهرس باستخدام المدخل أو واجهات برمجة تطبيقات REST أو .NET SDK.