استكشاف واجهة برمجة تطبيقات Azure Voice Live

مكتمل

تلميح

راجع علامة التبويب النص والصور لمزيد من التفاصيل!

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

الميزات الرئيسية لواجهة برمجة تطبيقات Voice Live

توفر واجهة برمجة تطبيقات Voice Live اتصالا في الوقت الفعلي باستخدام اتصالات WebSocket. وهو يدعم الميزات المتقدمة مثل التعرف على الكلام وتوليف تحويل النص إلى كلام وتدفق الصورة الرمزية ومعالجة الصوت.

• تدير الأحداث بتنسيق JSON المحادثات والتدفقات الصوتية والاستجابات.
• يتم تصنيف الأحداث إلى أحداث العميل (المرسلة من عميل إلى خادم) وأحداث الخادم (المرسلة من الخادم إلى العميل).

تتضمن الميزات الرئيسية:

• معالجة الصوت في الوقت الفعلي مع دعم تنسيقات متعددة مثل PCM16 و G.711.
• خيارات صوت متقدمة، بما في ذلك أصوات OpenAI وأصوات Azure المخصصة.
• تكامل الصورة الرمزية باستخدام WebRTC للفيديو والرسوم المتحركة.
• تقليل الضوضاء المدمج وإلغاء الصدى.

إشعار

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

للحصول على جدول للنماذج والمناطق المتوافقة، انتقل إلى نظرة عامة على واجهة برمجة تطبيقات Voice Live.

الاتصال بواجهة برمجة تطبيقات Voice Live

تدعم واجهة برمجة تطبيقات Voice Live طريقتين للمصادقة: Microsoft Entra (بدون مفتاح) ومفتاح واجهة برمجة التطبيقات. تستخدم Microsoft Entra المصادقة المعتمدة على الرموز لمورد Microsoft Foundry. يمكنك تطبيق رمز مميز للمصادقة تم استرداده باستخدام Bearer رمز مميز مع الرأس Authorization .

للمصادقة بدون مفتاح الموصى بها باستخدام معرف Microsoft Entra، تحتاج إلى تعيين دور مستخدم الخدمات المعرفية إلى حساب المستخدم الخاص بك أو هوية مدارة. يمكنك إنشاء رمز مميز باستخدام Azure CLI أو Azure SDKs. يجب إنشاء الرمز المميز باستخدام النطاق https://ai.azure.com/.default أو النطاق القديم https://cognitiveservices.azure.com/.default . استخدم الرمز المميز في Authorization رأس طلب اتصال WebSocket، بالتنسيق Bearer <token>.

للوصول إلى المفتاح، يمكن توفير مفتاح واجهة برمجة التطبيقات بإحدى طريقتين. يمكنك استخدام api-key رأس اتصال على اتصال المصافحة المسبقة. هذا الخيار غير متوفر في بيئة المستعرض. أو يمكنك استخدام api-key معلمة سلسلة استعلام في عنوان URI للطلب. يتم تشفير معلمات سلسلة الاستعلام عند استخدام https/wss.

إشعار

api-key رأس الاتصال في اتصال المصافحة المسبقة غير متوفر في بيئة المستعرض.

نقطة نهاية WebSocket

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

• اتصال المشروع: نقطة النهاية هي wss://<your-ai-foundry-resource-name>.services.ai.azure.com/voice-live/realtime?api-version=2025-10-01
• اتصال النموذج: نقطة النهاية هي wss://<your-ai-foundry-resource-name>.cognitiveservices.azure.com/voice-live/realtime?api-version=2025-10-01.

نقطة النهاية هي نفسها لجميع النماذج. الاختلاف الوحيد هو معلمة الاستعلام المطلوبة model ، أو، عند استخدام خدمة الوكيل، المعلمات agent_id و project_id .

أحداث واجهة برمجة تطبيقات Voice Live

تسهل أحداث العميل والخادم الاتصال والتحكم داخل واجهة برمجة تطبيقات Voice المباشرة. تشمل أحداث العملاء الرئيسية ما يلي:

• session.updateتعديل تكوينات الجلسة.:
• input_audio_buffer.appendأضف بيانات الصوت إلى المخزن المؤقت.:
• response.createإنشاء استجابات عبر استدلال النموذج.:

توفر أحداث الخادم ملاحظات وتحديثات الحالة:

• session.updatedتأكيد تغييرات تكوين الجلسة.:
• response.doneتشير إلى اكتمال إنشاء الاستجابة.:
• conversation.item.createdإشعار عند إضافة عنصر محادثة جديد.:

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

إشعار

يضمن التعامل السليم مع الأحداث التفاعل السلس بين العميل والخادم.

ضبط إعدادات الجلسة لواجهة برمجة تطبيقات Voice Live

غالبا ما يكون الحدث الأول الذي يرسله المتصل في جلسة واجهة برمجة تطبيقات Voice المباشرة التي تم إنشاؤها حديثا هو session.update الحدث. يتحكم هذا الحدث في مجموعة واسعة من سلوك الإدخال والإخراج. يمكن تحديث إعدادات الجلسة ديناميكيا باستخدام الحدث session.update . يمكن للمطورين تكوين أنواع الصوت والطرائق واكتشاف الأدوار وتنسيقات الصوت.

مثال على التكوين:

{
  "type": "session.update",
  "session": {
    "modalities": ["text", "audio"],
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "instructions": "You are a helpful assistant. Be concise and friendly.",
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000,
    "turn_detection": {
      "type": "azure_semantic_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 300,
      "silence_duration_ms": 500
    },
    "temperature": 0.8,
    "max_response_output_tokens": "inf"
  }
}

تلميح

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

تنفيذ معالجة الصوت في الوقت الفعلي باستخدام واجهة برمجة تطبيقات Voice Live

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

• إلحاق الصوت: أضف وحدات بايت صوتية إلى مخزن الإدخال.
• الالتزام بالصوت: قم بمعالجة المخزن المؤقت للصوت للنسخ أو إنشاء الاستجابة.
• صوت واضح: قم بإزالة بيانات الصوت من المخزن المؤقت.

يمكن تكوين تقليل الضوضاء وإلغاء الصدى لتحسين جودة الصوت. على سبيل المثال:

{
  "type": "session.update",
  "session": {
    "input_audio_noise_reduction": {
      "type": "azure_deep_noise_suppression"
    },
    "input_audio_echo_cancellation": {
      "type": "server_echo_cancellation"
    }
  }
}

إشعار

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

دمج بث الصور الرمزية باستخدام واجهة برمجة تطبيقات Voice Live

تدعم واجهة برمجة تطبيقات Voice Live بث الصورة الرمزية المستندة إلى WebRTC للتطبيقات التفاعلية. يمكن للمطورين تكوين إعدادات الفيديو والرسوم المتحركة وشكل المزج.

• استخدم الحدث session.avatar.connect لتقديم عرض SDP للعميل.
• قم بتكوين إعدادات دقة الفيديو ومعدل البت وبرنامج الترميز.
• حدد مخرجات الرسوم المتحركة مثل blendshape و visemes.

مثال على التكوين:

{
  "type": "session.avatar.connect",
  "client_sdp": "<client_sdp>"
}

تلميح

استخدم إعدادات الفيديو عالية الدقة لتحسين جودة المرئيات في تفاعلات الصورة الرمزية.