استخدام خدمة Speech من خلال نقطة نهاية خاصة

يتيح لك Azure Private Link الاتصال بالخدمات في Azure باستخدام نقطة نهاية خاصة. نقطة النهاية الخاصة هي عنوان IP خاص ضمن شبكة اتصال افتراضية معينة وشبكة فرعية.

تشرح هذه المقالة كيفية إعداد واستخدام Private Link ونقاط النهاية الخاصة مع خدمة Speech. ثم توضح هذه المقالة كيفية إزالة نقاط النهاية الخاصة لاحقاً، ولكن لا تزال تستخدم مورد الكلام.

إشعار

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

يتطلب إعداد مورد Speech لسيناريوهات نقطة النهاية الخاصة تنفيذ المهام التالية:

1. قم بإنشاء اسم مجال مخصص
2. قم بتشغيل نقاط النهاية الخاصة
3. ضبط التطبيقات والحلول الموجودة

نقاط النهاية الخاصة ونقاط نهاية خدمة الشبكة الظاهرية

يوفر Azure نقاط نهاية خاصة ونقاط نهاية خدمة الشبكة الظاهرية لنسبة استخدام الشبكة التي تنتقل عبر شبكة Azure الأساسية الخاصة. الغرض والتقنيات الأساسية لأنواع نقاط النهاية هذه متشابهة. ولكن هناك اختلافات بين التقنيتين. نوصي بالتعرف على إيجابيات وسلبيات كلتيهما قبل تصميم شبكتك.

هناك بعض الأشياء التي يجب مراعاتها عند تحديد التقنية التي يجب استخدامها:

• تضمن كلتا التقنيتين أن نسبة استخدام الشبكة بين الشبكة الظاهرية ومورد Speech لا تنتقل عبر الإنترنت العام.
• توفر نقطة النهاية الخاصة عنوان IP خاصًا مخصصًا لمورد Speech. يمكن الوصول إلى عنوان IP هذا فقط داخل شبكة ظاهرية وشبكة فرعية محددة. يمكنك التحكم بالكامل في الوصول إلى عنوان IP هذا داخل البنية الأساسية للشبكة.
• لا توفر نقاط نهاية خدمة الشبكة الظاهرية عنوان IP خاصًا مخصصًا لمورد Speech. بدلاً من ذلك، تغلّف جميع الحزم المُرسَلة إلى مورد Speech وتسلّمها مباشرة عبر شبكة Azure الأساسية.
• تدعم كلتا التقنيتين السيناريوهات المحلية. بشكل افتراضي، عند استخدام نقاط نهاية خدمة الشبكة الظاهرية، لا يمكن الوصول إلى موارد خدمة Azure المؤمنة للشبكات الظاهرية من خلال الشبكات المحلية. ولكن يمكنك تغيير هذا السلوك.
• غالبًا ما تستخدم نقاط نهاية خدمة الشبكة الظاهرية لتقييد الوصول إلى مورد Speech استنادًا إلى الشبكات الظاهرية التي تنشأ منها نسبة استخدام الشبكة.
• بالنسبة لخدمات Azure الذكاء الاصطناعي، يفرض تمكين نقطة نهاية خدمة الشبكة الظاهرية حركة المرور لجميع موارد خدمات الذكاء الاصطناعي Azure للانتقال عبر الشبكة الأساسية الخاصة. يتطلب ذلك تكوين وصول صريح إلى الشبكة. (للمزيد من المعلومات، راجع تكوين الشبكات الظاهرية وإعدادات شبكة موارد Speech.) لا تحتوي نقاط النهاية الخاصة على هذا القيد وتوفر مزيدًا من المرونة لتكوين شبكتك. يمكنك الوصول إلى مورد واحد من خلال الشبكة الأساسية الخاصة والآخر من خلال الإنترنت العام باستخدام نفس الشبكة الفرعية لنفس الشبكة الظاهرية.
• تتكبد نقاط النهاية الخاصة تكاليف إضافية. نقاط نهاية خدمة الشبكة الظاهرية مجانية.
• تتطلب نقاط النهاية الخاصة تكوين DNS إضافيًا.
• يمكن أن يعمل مورد Speech بشكلٍ متزامن مع كل من نقاط النهاية الخاصة ونقاط نهاية خدمة الشبكة الظاهرية.

نوصي بتجربة كلا نوعي نقاط النهاية قبل اتخاذ قرار بشأن تصميم الإنتاج الخاص بك.

لمزيد من المعلومات، راجع هذه الموارد:

• وثائق Azure Private Link ونقطة النهاية الخاصة
• وثائق نقاط نهاية خدمة الشبكة الظاهرية

توضح هذه المقالة استخدام نقاط النهاية الخاصة مع خدمة Speech. يتم وصف استخدام نقاط نهاية خدمة VNet هنا.

إنشاء اسم مجال مخصص

تنبيه

يستخدم مورد Speech مع تمكين اسم مجال مخصص طريقة مختلفة للتفاعل مع خدمة الكلام. قد تضطر إلى ضبط التعليمات البرمجية للتطبيق الخاص بك لكل من هذين السيناريوهين: مع نقطة نهاية خاصة ومن دون نقطة نهاية خاصة.

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

تنبيه

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

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

مدخل Microsoft Azure

لإنشاء اسم مجال مخصص باستخدام مدخل Microsoft Azure، اتبع الخطوات التالية:

1. انتقل إلى مدخل Azure ثم قم بتسجيل الدخول إلى حساب Azure الخاص بك.

2. حدد مورد Speech المطلوب.

3. في مجموعة Resource Management في الجزء الأيمن، حدد Networking.

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

5. في لوحة إنشاء اسم مجال مخصص، أدخل اسم مجال مخصص. سيبدو المجال المخصص الكامل بالشكل التالي: https://{your custom name}.cognitiveservices.azure.com.

   تذكر أنه بعد إنشاء اسم مجال مخصص، لا يمكن تغييره.

   بعد إدخال اسم المجال المخصص، اختر حفظ.

6. بعد انتهاء العملية، في مجموعة إدارة الموارد، حدد المفاتيح ونقطة النهاية. تأكد من أن اسم نقطة النهاية الجديدة لموردك يبدأ بهذه الطريقة: https://{your custom name}.cognitiveservices.azure.com.

بوويرشيل

لإنشاء اسم مجال مخصص باستخدام PowerShell، تأكد من أن جهاز الكمبيوتر الخاص بك يحتوي على الإصدار 7.x من PowerShell أو أحدث باستخدام إصدار الوحدة النمطية Azure PowerShell 5.1.0 أو أحدث. للاطلاع على إصدارات هذه الأدوات، اتبع الخطوات التالية:

1. في نافذة PowerShell، أدخل:

   $PSVersionTable

   تأكد من القيمة PSVersion تمثل 7.x أو أحدث. لترقية PowerShell، اتبع الإرشادات الموجودة في تثبيت إصدارات مختلفة من PowerShell.

2. في نافذة PowerShell، أدخل:

   Get-Module -ListAvailable Az

   إذا لم يظهر أي شيء، أو إذا كان هذا الإصدار من الوحدة النمطية Azure PowerShell أقدم من 5.1.0، فاتبع الإرشادات الموجودة في تثبيت الوحدة النمطية Azure PowerShell للترقية.

قبل المتابعة، قم بتشغيل Connect-AzAccount لإنشاء اتصال مع Azure.

تحقق من توفر اسم مجال مخصص

تحقق مما إن كان المجال المخصص الذي ترغب في استخدامه متوفرًا. تؤكد التعليمات البرمجية التالية أن المجال متوفر باستخدام عملية التحقق من توفر المجال في Azure الذكاء الاصطناعي خدمات REST API.

إشعار

لن تعمل التعليمات البرمجية التالية في Azure Cloud Shell.

$subscriptionId = "Your Azure subscription Id"
$subdomainName = "custom domain name"

# Select the Azure subscription that contains the Speech resource.
# You can skip this step if your Azure account has only one active subscription.
Set-AzContext -SubscriptionId $subscriptionId

# Prepare the OAuth token to use in the request to the Azure AI services REST API.
$Context = Get-AzContext
$AccessToken = (Get-AzAccessToken -TenantId $Context.Tenant.Id).Token
$token = ConvertTo-SecureString -String $AccessToken -AsPlainText -Force

# Prepare and send the request to the Azure AI services REST API.
$uri = "https://management.azure.com/subscriptions/" + $subscriptionId + `
    "/providers/Microsoft.CognitiveServices/checkDomainAvailability?api-version=2017-04-18"
$body = @{
subdomainName = $subdomainName
type = "Microsoft.CognitiveServices/accounts"
}
$jsonBody = $body | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri $uri -ContentType "application/json" -Authentication Bearer `
    -Token $token -Body $jsonBody | Format-List

إن كان الاسم المطلوب متوفرًا، فسترى استجابة مثل هذا:

isSubdomainAvailable : True
reason               :
type                 :
subdomainName        : my-custom-name

إذا تم أخذ الاسم بالفعل، فسترى الاستجابة التالية:

isSubdomainAvailable : False
reason               : Sub domain name 'my-custom-name' is already used. Please pick a different name.
type                 :
subdomainName        : my-custom-name

قم بإنشاء اسم المجال المخصص الخاص بك

لتشغيل اسم مجال مخصص لمورد الكلام المحدد، استخدم الأمر Cmdlet Set-AzCognitiveServicesAccount.

تنبيه

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

$resourceGroup = "Resource group name where Speech resource is located"
$speechResourceName = "Your Speech resource name"
$subdomainName = "custom domain name"

# Select the Azure subscription that contains the Speech resource.
# You can skip this step if your Azure account has only one active subscription.
$subscriptionId = "Your Azure subscription Id"
Set-AzContext -SubscriptionId $subscriptionId

# Set the custom domain name to the selected resource.
# WARNING: THIS CANNOT BE CHANGED OR UNDONE!
Set-AzCognitiveServicesAccount -ResourceGroupName $resourceGroup `
    -Name $speechResourceName -CustomSubdomainName $subdomainName

Azure CLI

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

• استخدم بيئة Bash في Azure Cloud Shell. لمزيد من المعلومات، راجع التشغيل السريع ل Bash في Azure Cloud Shell.

  

• إذا كنت تفضل تشغيل أوامر مرجع CLI محلياً قم بتثبيت CLI Azure. إذا كنت تعمل على نظام تشغيل Windows أو macOS، ففكر في تشغيل Azure CLI في حاوية Docker. لمزيد من المعلومات، راجع كيفية تشغيل Azure CLI في حاوية Docker.

  • إذا كنت تستخدم تثبيت محلي، يُرجى تسجيل الدخول إلى Azure CLI مستخدمًا أمر az login. لإنهاء عملية المصادقة، اتبع الخطوات المعروضة في جهازك. للحصول على خيارات أخرى لتسجيل دخول، راجع تسجيل الدخول باستخدام Azure CLI.

  • عندما يُطلب منك، قم بتثبيت ملحق Azure CLI عند الاستخدام لأول مرة. لمزيد من المعلومات بشأن الامتدادات، راجع استخدام امتدادات مع Azure CLI.

  • يُرجى تشغيل إصدار az للوصول إلى الإصدار والمكتبات التابعة التي تم تثبيتها. للتحديث لآخر إصدار، يُرجى تشغيل تحديث az.

تتطلب هذا القسم أحدث إصدار من Azure CLI. إذا كنت تستخدم Azure Cloud Shell، فإن أحدث إصدار مثبت بالفعل.

تحقق من توفر اسم المجال المخصص

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

انسخ مقطع التعليمات البرمجية التالي، وأدرج اسم المجال المخصص المفضل لديك، واحفظ في الملف subdomain.json.

{
    "subdomainName": "custom domain name",
    "type": "Microsoft.CognitiveServices/accounts"
}

انسخ الملف إلى المجلد الحالي أو قم بتحميله إلى Azure Cloud Shell وقم بتشغيل الأمر التالي. استبدل xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx بمعرف اشتراك Azure الخاص بك.

az rest --method post --url "https://management.azure.com/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/providers/Microsoft.CognitiveServices/checkDomainAvailability?api-version=2017-04-18" --body @subdomain.json

إن كان الاسم المطلوب متوفرًا، فسترى استجابة مثل هذا:

{
  "isSubdomainAvailable": true,
  "reason": null,
  "subdomainName": "my-custom-name",
  "type": null
}

إذا تم أخذ الاسم بالفعل، فسترى الاستجابة التالية:

{
  "isSubdomainAvailable": false,
  "reason": "Sub domain name 'my-custom-name' is already used. Please pick a different name.",
  "subdomainName": "my-custom-name",
  "type": null
}

قم بتشغيل اسم مجال مخصص

لاستخدام اسم مجال مخصص مع مورد الكلام المحدد، استخدم الأمر az cognitiveservices account update.

(إذا كان حساب Azure الخاص بك يحتوي على اشتراك نشط واحد فقط، يمكنك تخطي هذه الخطوة.) حدد اشتراك Azure الذي يحتوي على مورد الكلام. استبدل xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx بمعرف اشتراك Azure الخاص بك.

az account set --subscription xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

قم بتعيين اسم المجال المخصص للمورد المحدد. استبدل قيم المعلمات النموذجية بالقيم الفعلية وقم بتشغيل الأمر التالي.

تنبيه

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

az cognitiveservices account update --name my-speech-resource-name --resource-group my-resource-group-name --custom-domain my-custom-name

قم بتشغيل نقاط النهاية الخاصة

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

حدد إستراتيجية DNS قبل توفير نقاط نهاية خاصة لمورد الكلام الإنتاجي. واختبر تغييرات DNS، خاصة إذا كنت تستخدم خادم DNS الخاص بك.

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

• إنشاء نقطة نهاية خاصة باستخدام مدخل Microsoft Azure
• إنشاء نقطة نهاية خاصة باستخدام Azure PowerShell
• إنشاء نقطة نهاية خاصة باستخدام Azure CLI

استخدم هذه المعلمات بدلاً من المعلمات في المقالة التي اخترتها:

الإعداد	القيمة‬
نوع المورد	Microsoft.CognitiveServices/accounts
Resource	<اسم مورد الكلام الخاص بك>
المورد الفرعي المستهدف	الحساب

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

قم بحل DNS من الشبكة الظاهرية

هذا الفحص مطلوب.

اتبع هذه الخطوات لاختبار إدخال DNS المخصص من شبكتك الظاهرية:

1. سجل الدخول إلى جهاز ظاهري موجود في الشبكة الظاهرية التي قمت بربط نقطة النهاية الخاصة بها.

2. افتح موجه أوامر Windows أو Bash shell، وقم بتشغيل nslookup، وتأكد من أن يحل اسم المجال المخصص لموردك بنجاح.

   C:\>nslookup my-private-link-speech.cognitiveservices.azure.com
   Server:  UnKnown
   Address:  168.63.129.16
   
   Non-authoritative answer:
   Name:    my-private-link-speech.privatelink.cognitiveservices.azure.com
   Address:  172.28.0.10
   Aliases:  my-private-link-speech.cognitiveservices.azure.com
   

3. تأكد من أن عنوان IP يطابق عنوان IP لنقطة النهاية الخاصة بك.

قم بحل DNS من الشبكات الأخرى

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

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

1. تسجيل الدخول إلى كمبيوتر متصل بشبكة يسمح له بالوصول إلى المورد.

2. افتح موجه أوامر Windows أو Bash shell، وقم بتشغيل nslookup، وتأكد من أن يحل اسم المجال المخصص لموردك بنجاح.

   C:\>nslookup my-private-link-speech.cognitiveservices.azure.com
   Server:  UnKnown
   Address:  fe80::1
   
   Non-authoritative answer:
   Name:    vnetproxyv1-weu-prod.westeurope.cloudapp.azure.com
   Address:  13.69.67.71
   Aliases:  my-private-link-speech.cognitiveservices.azure.com
             my-private-link-speech.privatelink.cognitiveservices.azure.com
             westeurope.prod.vnet.cog.trafficmanager.net
   

إشعار

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

قم بضبط تطبيق لاستخدام مورد Speech بنقطة النهاية الخاصة

يتفاعل مورد Speech مع مجال مخصص مع خدمة Speech بطريقة مختلفة. هذا صحيح بالنسبة لمورد الكلام الممكّن للمجال المخصص مع نقاط النهاية الخاصة ودونها. تنطبق المعلومات الواردة في هذا القسم على كلا السيناريوهين.

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

يستخدم مورد Speech مع اسم مجال مخصص ونقطة نهاية خاصة قيد التشغيل طريقة مختلفة للتفاعل مع خدمة Speech. يشرح هذا القسم كيفية استخدام مثل هذا المورد مع واجهات برمجة تطبيقات REST لخدمة الكلام وSDK الكلام.

إشعار

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

مورد الكلام باسم مجال مخصص ونقطة نهاية خاصة: الاستخدام مع واجهات برمجة تطبيقات REST

نستخدم my-private-link-speech.cognitiveservices.azure.com كنموذج اسم DNS لمورد الكلام (مجال مخصص) لهذا القسم.

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

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

واجهات برمجة تطبيقات REST لتحويل الكلام إلى نص هي:

• Speech to text REST API، والذي يستخدم للنسخ الدفعي والكلام المخصص.
• Speech to text REST API for short audio, which is used for real-time speech to text.

استخدام Speech to text REST API للصوت القصير وواجهة برمجة تطبيقات Rest لتحويل النص إلى كلام في سيناريو نقطة النهاية الخاصة هو نفسه. وهو ما يعادل حالة Speech SDK الموضحة لاحقاً في هذه المقالة.

يستخدم Speech to text REST API مجموعة مختلفة من نقاط النهاية، لذلك يتطلب نهجا مختلفا للسيناريو الممكن لنقطة النهاية الخاصة.

تصف الأقسام الفرعية التالية كلتا الحالتين.

Speech to text REST API

عادة ما تستخدم موارد الكلام نقاط النهاية الإقليمية لخدمات Azure الذكاء الاصطناعي للتواصل مع Speech to text REST API. تحتوي هذه الموارد على تنسيق التسمية التالي:

{region}.api.cognitive.microsoft.com.

هذا هو نموذج عنوان URL للطلب:

https://westeurope.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions

إشعار

راجع هذه المقالة ل Azure Government وMicrosoft Azure المشغلة بواسطة نقاط نهاية 21Vianet.

بعد تشغيل مجال مخصص لمورد Speech (وهو ضروري لنقاط النهاية الخاصة)، سيستخدم هذا المورد نمط اسم DNS التالي لنقطة نهاية واجهة برمجة تطبيقات REST الأساسية:

{your custom name}.cognitiveservices.azure.com

وهذا يعني أنه في مثالنا، اسم نقطة نهاية REST API هو:

my-private-link-speech.cognitiveservices.azure.com

ويجب تحويل نموذج عنوان URL للطلب إلى:

https://my-private-link-speech.cognitiveservices.azure.com/speechtotext/v3.1/transcriptions

يجب أن يمكن الوصول إلى عنوان URL هذا من الشبكة الظاهرية مع إرفاق نقطة النهاية الخاصة (بشرط دقة DNS الصحيحة).

بعد تشغيل اسم مجال مخصص لمورد Speech، عادة ما تستبدل اسم المضيف في جميع عناوين URL للطلب باسم مضيف المجال المخصص الجديد. تظل جميع الأجزاء الأخرى من الطلب (مثل المسار /speechtotext/v3.1/transcriptions في المثال السابق) كما هي.

تلميح

يقوم بعض العملاء بتطوير التطبيقات التي تستخدم جزء المنطقة من اسم DNS لنقطة النهاية الإقليمية (على سبيل المثال، لإرسال الطلب إلى مورد الكلام المنشور في منطقة Azure المحددة).

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

واجهة برمجة تطبيقات REST لتحويل الكلام إلى نص للصوت القصير وواجهة برمجة تطبيقات REST لتحويل النص إلى كلام

تستخدم واجهة برمجة تطبيقات REST لتحويل الكلام إلى نص للصوت القصير وواجهة برمجة تطبيقات REST لتحويل النص إلى كلام نوعين من نقاط النهاية:

• خدمات Azure الذكاء الاصطناعي نقاط النهاية الإقليمية للتواصل مع خدمات Azure الذكاء الاصطناعي REST API للحصول على رمز مميز للتخويل
• نقاط نهاية خاصة لجميع العمليات الأخرى

إشعار

راجع هذه المقالة ل Azure Government وAzure المشغلة بواسطة نقاط نهاية 21Vianet.

يتم توفير الوصف التفصيلي لنقاط النهاية الخاصة وكيفية تحويل عنوان URL الخاص بها لمورد Speech الممكن لنقطة النهاية الخاصة في هذا القسم الفرعي بشأن الاستخدام مع Speech SDK. ينطبق نفس المبدأ الموضح ل SDK على Speech to text REST API للصوت القصير وواجهة برمجة تطبيقات Rest لتحويل النص إلى كلام.

تعرف على المادة الواردة في القسم الفرعي المذكور في الفقرة السابقة واطلع على المثال التالي. يصف المثال واجهة برمجة تطبيقات REST لتحويل النص إلى كلام. استخدام Speech to text REST API للصوت القصير مكافئ تماما.

إشعار

عند استخدام Speech to text REST API للصوت القصير وواجهة برمجة تطبيقات Rest لتحويل النص إلى كلام في سيناريوهات نقطة النهاية الخاصة، استخدم مفتاح مورد تم تمريره عبر Ocp-Apim-Subscription-Key العنوان. (راجع تفاصيل Speech to text REST API for short audio and Text to speech REST API)

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

مثال على استخدام واجهة برمجة تطبيقات REST لتحويل النص إلى كلام

نستخدم غرب أوروبا كنموذج لمنطقة Azure وكنموذج my-private-link-speech.cognitiveservices.azure.com اسم DNS لمورد الكلام (مجال مخصص). ينتمي اسم my-private-link-speech.cognitiveservices.azure.com المجال المخصص في مثالنا إلى مورد الكلام الذي تم إنشاؤه في منطقة غرب أوروبا.

للحصول على قائمة الأصوات المدعومة في المنطقة، قم بتنفيذ الطلب التالي:

https://westeurope.tts.speech.microsoft.com/cognitiveservices/voices/list

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

بالنسبة لمورد Speech الممكن لنقطة النهاية الخاصة، يجب تعديل عنوان URL لنقطة النهاية لنفس العملية. يبدو نفس الطلب كما يلي:

https://my-private-link-speech.cognitiveservices.azure.com/tts/cognitiveservices/voices/list

راجع شرحاً مفصلاً في القسم الفرعي إنشاء عنوان URL لنقطة النهاية لـ Speech SDK.

مورد الكلام باسم مجال مخصص ونقطة نهاية خاصة: الاستخدام مع Speech SDK

يتطلب استخدام Speech SDK مع اسم مجال مخصص وموارد Speech الممكنة لنقطة النهاية الخاصة مراجعة التعليمات البرمجية للتطبيق وتغييرها على الأرجح.

نستخدم my-private-link-speech.cognitiveservices.azure.com كنموذج اسم DNS لمورد الكلام (مجال مخصص) لهذا القسم.

إنشاء عنوان URL لنقطة النهاية

عادة في سيناريوهات SDK (وفي الكلام إلى نص REST API للصوت القصير والنص إلى سيناريوهات Speech REST API)، تستخدم موارد الكلام نقاط النهاية الإقليمية المخصصة لعروض الخدمة المختلفة. تنسيق اسم DNS لنقاط النهاية هذه هو:

{region}.{speech service offering}.speech.microsoft.com

مثال على اسم DNS هو:

westeurope.stt.speech.microsoft.com

يتم سرد جميع القيم الممكنة للمنطقة (العنصر الأول من اسم DNS) في المناطق المدعومة بخدمة الكلام. (راجع هذه المقالة ل Azure Government وAzure المشغلة بواسطة نقاط نهاية 21Vianet.) يعرض الجدول التالي القيم المحتملة لعرض خدمة الكلام (العنصر الثاني من اسم DNS):

قيمة اسم DNS	تقديم خدمة الكلام
commands	أوامر مخصصة
convai	نسخ الاجتماع
s2s	ترجمة الكلام
stt	تحويل الكلام إلى نص
tts	تحويل النص إلى كلام
voice	صوت مخصص

لذا فإن المثال السابق (westeurope.stt.speech.microsoft.com) يرمز إلى نقطة نهاية الكلام إلى النص في غرب أوروبا.

تتصل نقاط النهاية الممكنة لنقطة النهاية الخاصة بخدمة Speech عبر وكيل خاص. ولهذا السبب، يجب تغيير عناوين URL لاتصال نقطة النهاية.

يبدو عنوان URL لنقطة النهاية "القياسية" بالشكل التالي:

{region}.{speech service offering}.speech.microsoft.com/{URL path}

يبدو عنوان URL لنقطة النهاية الخاصة بالشكل التالي:

{your custom name}.cognitiveservices.azure.com/{speech service offering}/{URL path}

مثال1. يتصل التطبيق باستخدام عنوان URL التالي (التعرف على الكلام باستخدام النموذج الأساسي للغة الإنجليزية الأمريكية في غرب أوروبا):

wss://westeurope.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US

لاستخدامه في السيناريو الخاص بتمكين نقطة النهاية عندما يكون اسم المجال المخصص لمورد الكلام هو my-private-link-speech.cognitiveservices.azure.com، يجب عليك تعديل عنوان URL كما يلي:

wss://my-private-link-speech.cognitiveservices.azure.com/stt/speech/recognition/conversation/cognitiveservices/v1?language=en-US

لاحظ التفاصيل:

• تم استبدال باسم مضيف المجال المخصص my-private-link-speech.cognitiveservices.azure.com باسم المضيف westeurope.stt.speech.microsoft.com.
• يصبح العنصر الثاني من اسم DNS الأصلي (stt) العنصر الأول من مسار URL ويسبق المسار الأصلي. لذلك عنوان URL /speech/recognition/conversation/cognitiveservices/v1?language=en-US الأصلي يصبح /stt/speech/recognition/conversation/cognitiveservices/v1?language=en-US.

مثال 2. يستخدم التطبيق عنوان URL التالي لتركيب الكلام في غرب أوروبا:

wss://westeurope.tts.speech.microsoft.com/cognitiveservices/websocket/v1

يستخدم عنوان URL المكافئ التالي نقطة نهاية خاصة، حيث يكون اسم المجال المخصص لمورد الكلام هو my-private-link-speech.cognitiveservices.azure.com:

wss://my-private-link-speech.cognitiveservices.azure.com/tts/cognitiveservices/websocket/v1

يتم تطبيق نفس المبدأ في المثال 1، ولكن العنصر الأساسي هذه المرة هو tts.

تعديل التطبيقات

اتبع هذه الخطوات لتعديل التعليمات البرمجية الخاصة بك:

1. حدد عنوان URL لنقطة نهاية التطبيق:

   • قم بتشغيل التسجيل للتطبيق الخاص بك وتشغيله لتسجيل النشاط.
   • في ملف السجل، ابحث عن SPEECH-ConnectionUrl. في الأسطر المطابقة، تحتوي المعلمة value على عنوان URL الكامل الذي استخدمه التطبيق الخاص بك للوصول إلى خدمة Speech.

   مثال:

   (114917): 41ms SPX_DBG_TRACE_VERBOSE:  property_bag_impl.cpp:138 ISpxPropertyBagImpl::LogPropertyAndValue: this=0x0000028FE4809D78; name='SPEECH-ConnectionUrl'; value='wss://westeurope.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?traffictype=spx&language=en-US'
   

   لذا فإن عنوان URL الذي استخدمه التطبيق في هذا المثال هو:

   wss://westeurope.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US
   

2. قم بإنشاء مثيل SpeechConfig باستخدام عنوان URL الكامل لنقطة النهاية:

   1. قم بتعديل نقطة النهاية التي حددتها، كما هو موضح في قسم عنوان URL لنقطة النهاية الإنشائية السابق.

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

      var config = SpeechConfig.FromSubscription(speechKey, azureRegion);
      

      لا يعمل هذا المثال لمورد Speech ممكن لنقطة النهاية الخاصة بسبب تغييرات اسم المضيف وعنوان URL التي وصفناها في الأقسام السابقة. إذا حاولت تشغيل التطبيق الحالي دون أي تعديلات باستخدام مفتاح مورد ممكن لنقطة النهاية الخاصة، فستحصل على خطأ مصادقة (401).

      لجعلها تعمل، قم بتعديل كيفية إنشاء SpeechConfig مثيل للفئة واستخدام تهيئة "من نقطة النهاية"/"مع نقطة النهاية". لنفترض أن لدينا المتغيرين التاليين المحددين:

      • speechKey يحتوي على مفتاح مورد Speech الممكن لنقطة النهاية الخاصة.
      • endPoint يحتوي على عنوان URL الكامل لنقطة النهاية المعدلة (باستخدام النوع المطلوب من قبل لغة البرمجة المقابلة). في مثالنا، يجب أن يحتوي هذا المتغير على:

        wss://my-private-link-speech.cognitiveservices.azure.com/stt/speech/recognition/conversation/cognitiveservices/v1?language=en-US
        

      إنشاء مثيل SpeechConfig:

      var config = SpeechConfig.FromEndpoint(endPoint, speechKey);
      

      auto config = SpeechConfig::FromEndpoint(endPoint, speechKey);
      

      SpeechConfig config = SpeechConfig.fromEndpoint(endPoint, speechKey);
      

      import azure.cognitiveservices.speech as speechsdk
      config = speechsdk.SpeechConfig(endpoint=endPoint, subscription=speechKey)
      

      SPXSpeechConfiguration *config = [[SPXSpeechConfiguration alloc] initWithEndpoint:endPoint subscription:speechKey];
      

      import * as sdk from "microsoft.cognitiveservices.speech.sdk";
      config: sdk.SpeechConfig = sdk.SpeechConfig.fromEndpoint(new URL(endPoint), speechKey);
      

تلميح

لا يتم تغيير معلمات الاستعلام المحددة في URI لنقطة النهاية، حتى إذا تم تعيينها بواسطة واجهات برمجة التطبيقات الأخرى. على سبيل المثال، إذا تم تعريف لغة التعرف في URI كمعلمة استعلام language=en-US، وتم تعيينها أيضاً إلى ru-RU عبر الخاصية المقابلة، يتم استخدام إعداد اللغة في URI. ثم تكون اللغة الفعالة هي en-US.

المعلمات التي تم تعيينها في URI لنقطة النهاية لها الأسبقية دائماً. يمكن لواجهات برمجة التطبيقات الأخرى تجاوز المعلمات التي لم يتم تحديدها في URI لنقطة النهاية فقط.

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

استخدام Speech Studio

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

الوصول إلى مدخل ويب Speech Studio من شبكة ظاهرية

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

الوصول إلى نقطة نهاية مورد Speech لا يساوي الوصول إلى مدخل ويب Speech Studio. لا يتم دعم الوصول إلى مدخل ويب Speech Studio عبر نقاط نهاية خدمة الشبكة الظاهرية أو الخاصة.

العمل باستخدام مشاريع Speech Studio

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

1. انتقل إلى مدخل Azure ثم قم بتسجيل الدخول إلى حساب Azure الخاص بك.
2. حدد مورد Speech.
3. في مجموعة إدارة الموارد في الجزء الأيمن، حدد الشبكات>جدران الحماية والشبكات الظاهرية.
4. حدد خيارًا واحدًا من كل الشبكات أو الشبكات ونقاط النهاية الخاصة المحددة أو معطلة.

الكلام المخصص

يصف الجدول التالي إمكانية الوصول إلى مشروع الكلام المخصص لكل مورد الكلام جدران حماية شبكة>الاتصال وإعداد أمان الشبكات الظاهرية.

إشعار

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

إعداد أمان شبكة مورد Speech	إمكانية الوصول إلى مشروع Speech Studio
جميع الشبكات	لا توجد قيود
الشبكات ونقاط النهاية الخاصة المحددة	يمكن الوصول إليها من عناوين IP العامة المسموح بها
⁧⁩مُعطل⁧⁩	لا يمكن الوصول إليها

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

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

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

• أنشئ مورد Speech آخر للتطوير يمكن استخدامه على شبكة عامة. أعِد النموذج المخصص في Speech Studio على مورد التطوير، ثم انسخ النموذج إلى مورد الإنتاج الخاص بك. راجع طلب REST Models_CopyTo مع Speech to text REST API.
• لديك خيار عدم استخدام Speech Studio لأدوات تخصيص الكلام. استخدم Speech to text REST API لجميع عمليات الكلام المخصصة.

إنشاء محتوى صوتي وصوتي مخصص

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

قم بضبط تطبيق لاستخدام مورد Speech دون نقاط نهاية خاصة

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

يشرح هذا القسم كيفية استخدام مورد الكلام مع اسم مجال مخصص ولكن دون أي نقاط نهاية خاصة مع واجهات برمجة تطبيقات REST لخدمة الكلام وSDK الكلام. قد يكون هذا مورداً تم استخدامه مرة واحدة في سيناريو نقطة نهاية خاصة، ولكن بعد ذلك تم حذف نقاط النهاية الخاصة به.

تكوين DNS

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

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

لذلك يبدو إخراج nslookup الأمر كما يلي:

C:\>nslookup my-private-link-speech.cognitiveservices.azure.com
Server:  UnKnown
Address:  fe80::1

Non-authoritative answer:
Name:    apimgmthskquihpkz6d90kmhvnabrx3ms3pdubscpdfk1tsx3a.cloudapp.net
Address:  13.93.122.1
Aliases:  my-private-link-speech.cognitiveservices.azure.com
          westeurope.api.cognitive.microsoft.com
          cognitiveweprod.trafficmanager.net
          cognitiveweprod.azure-api.net
          apimgmttmdjylckcx6clmh2isu2wr38uqzm63s8n4ub2y3e6xs.trafficmanager.net
          cognitiveweprod-westeurope-01.regional.azure-api.net

قارنه مع الإخراج من هذا القسم.

مورد الكلام مع اسم مجال مخصص ودون نقاط نهاية خاصة: الاستخدام مع واجهات برمجة تطبيقات REST

Speech to text REST API

استخدام واجهة برمجة تطبيقات REST لتحويل الكلام إلى نص يعادل تماما حالة موارد الكلام الممكنة لنقطة النهاية الخاصة.

واجهة برمجة تطبيقات REST لتحويل الكلام إلى نص للصوت القصير وواجهة برمجة تطبيقات REST لتحويل النص إلى كلام

في هذه الحالة، لا يختلف استخدام Speech to text REST API للصوت القصير واستخدام واجهة برمجة تطبيقات Rest للنص إلى كلام عن الحالة العامة، باستثناء واحد. (راجع الملاحظة التالية.) يجب استخدام كل من واجهات برمجة التطبيقات كما هو موضح في Speech to text REST API للصوت القصير ووثائق واجهة برمجة تطبيقات REST لتحويل النص إلى كلام.

إشعار

عند استخدام Speech to text REST API للصوت القصير والنص إلى كلام REST API في سيناريوهات المجال المخصصة، استخدم مفتاح مورد الكلام الذي تم تمريره عبر Ocp-Apim-Subscription-Key العنوان. (راجع تفاصيل Speech to text REST API for short audio and Text to speech REST API)

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

مورد الكلام مع اسم مجال مخصص ودون نقاط نهاية خاصة: استخدام مع Speech SDK

يعد استخدام Speech SDK مع موارد الكلام الممكّنة للمجال المخصص دون نقاط نهاية خاصة مكافئاً للحالة العامة كما هو موضح في وثائق Speech SDK.

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

في القسم الخاص بموارد الكلام الممكنة لنقطة النهاية الخاصة، أوضحنا كيفية تحديد عنوان URL لنقطة النهاية وتعديله وجعله يعمل من خلال تهيئة "من نقطة النهاية"/"بنقطة النهاية" لمثيل الفئة SpeechConfig.

ومع ذلك، إذا حاولت تشغيل نفس التطبيق بعد إزالة جميع نقاط النهاية الخاصة (ما يتيح بعض الوقت لإعادة توفير سجل DNS المطابق)، فستحصل على خطأ في الخدمة الداخلية (404). والسبب هو أن سجل DNS يشير الآن إلى نقطة نهاية خدمات Azure الذكاء الاصطناعي الإقليمية بدلا من وكيل الشبكة الظاهرية، ولم يتم العثور على مسارات URL مثل /stt/speech/recognition/conversation/cognitiveservices/v1?language=en-US هناك.

تحتاج إلى التراجع عن تطبيقك إلى الإصدار القياسي لـ SpeechConfig بأسلوب الشفرة التالية:

var config = SpeechConfig.FromSubscription(speechKey, azureRegion);

يمكنك استخدام نقاط النهاية الخاصة ونقاط نهاية خدمة الشبكة الافتراضية للوصول إلى مورد الكلام نفسه بشكل متزامن

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

التسعير

للحصول على تفاصيل التسعير، راجع تسعير Azure Private Link.

معرفة المزيد

• استخدام خدمة الكلام من خلال نقطة نهاية خدمة الشبكة الظاهرية
• Azure Private Link
• نقاط نهاية خدمة شبكة Azure الظاهرية
• Speech SDK
• Speech to text REST API
• واجهة برمجة تطبيقات REST لتحويل النص إلى كلام