تكامل Qwen3-TTS

شغّل Qwen3-TTS من Alibaba محليًا لتحويل النص إلى كلام متعدد اللغات وعالي الجودة. يغطي هذا الدليل إعداد خادم TTS المتوافق مع OpenAI والمضمّن مع Libre WebUI.

نظرة عامة

Qwen3-TTS نظام متقدم لتحويل النص إلى كلام يوفر:

• 9 أصوات جاهزة تغطي الإنجليزية والصينية واليابانية والكورية
• دعم 10 لغات تشمل الألمانية والفرنسية والإسبانية والإيطالية والبرتغالية والروسية
• استنساخ الصوت من عينات صوتية مدتها 3 ثوانٍ
• تصميم الصوت باستخدام أوصاف بلغة طبيعية
• تحكم بالتعليمات في العاطفة والتنغيم

يلف الخادم المضمّن Qwen3-TTS بواجهة API متوافقة مع OpenAI، مما يتيح لـ Libre WebUI استخدامه عبر نظام المكوّنات الإضافية القياسي.

المتطلبات

المكوّن	الحد الأدنى	الموصى به
Python	3.12+	3.12 (لا 3.14)
GPU VRAM	4GB (نماذج 0.6B)	8GB+ (نماذج 1.7B)
RAM	8GB	16GB+
القرص	5GB	10GB

دعم المنصات

المنصة	المحرك	ملاحظات
GPU من NVIDIA	CUDA	أفضل أداء، مع دعم bfloat16
Apple Silicon	MPS	استخدم نماذج 0.6B لكفاءة الذاكرة
CPU	PyTorch	أبطأ؛ استخدم نماذج 0.6B

لمستخدمي Apple Silicon

استخدم نسخة النموذج customvoice-0.6b على Mac لتجنب ضغط الذاكرة. قد تسبب نماذج 1.7B عدم استقرار النظام على الأجهزة ذات 16GB من الذاكرة الموحدة.

البدء السريع

1. تثبيت الخادم

cd examples/qwen-tts-server

# Create virtual environment (Python 3.12 required)
python3.12 -m venv venv
source venv/bin/activate  # Linux/macOS
# or: venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

2. تشغيل الخادم

# NVIDIA GPU (recommended)
python server.py --model customvoice-1.7b

# Apple Silicon
python server.py --model customvoice-0.6b

# CPU (slower)
python server.py --model customvoice-0.6b

يعمل الخادم افتراضيًا على http://localhost:8100.

3. ضبط Libre WebUI

المكوّن الإضافي مضبوط مسبقًا في plugins/qwen-tts.json. فعّله من الإعدادات ← المكوّنات الإضافية ← Qwen3 TTS.

4. اختباره

curl http://localhost:8100/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3-tts", "input": "Hello, welcome to Libre WebUI!", "voice": "Ryan"}' \
  --output speech.wav

النماذج المتاحة

النموذج	الحجم	الاستخدام
customvoice-1.7b	~3.5GB	أصوات جاهزة مع تحكم بالتعليمات
customvoice-0.6b	~1.5GB	نسخة خفيفة لسعة VRAM المحدودة
voicedesign-1.7b	~3.5GB	إنشاء أصوات من أوصاف نصية
base-1.7b	~3.5GB	استنساخ صوت من عينات مدتها 3 ثوانٍ
base-0.6b	~1.5GB	استنساخ صوت خفيف

الأصوات

الأصوات الجاهزة (نماذج CustomVoice)

الصوت	اللغة	الوصف
Ryan	الإنجليزية	ذكوري، واضح وطبيعي
Aiden	الإنجليزية	ذكوري، بنبرة دافئة
Vivian	الصينية	أنثوي، احترافي
Serena	الصينية	أنثوي، ودود
Uncle_Fu	الصينية	ذكوري، ناضج
Dylan	الصينية	ذكوري، بلهجة بكين
Eric	الصينية	ذكوري، بلهجة سيتشوان
Ono_Anna	اليابانية	أنثوي
Sohee	الكورية	أنثوي

أسماء OpenAI البديلة للأصوات

للتوافق مع عملاء TTS لـ OpenAI، يطابق الخادم أسماء أصوات OpenAI كما يلي:

صوت OpenAI	يطابق
alloy	Ryan
echo	Aiden
fable	Vivian
onyx	Uncle_Fu
nova	Serena
shimmer	Ono_Anna

مرجع API

توليد الكلام

نقطة النهاية: POST /v1/audio/speech

{
  "model": "qwen3-tts",
  "input": "Text to convert to speech",
  "voice": "Ryan",
  "response_format": "wav",
  "instruct": "Speak with enthusiasm",
  "language": "English"
}

المعلمة	النوع	الافتراضي	الوصف
model	string	qwen3-tts	معرّف النموذج
input	string	مطلوب	النص المراد توليده (10,000 حرف كحد أقصى)
voice	string	ryan	اسم الصوت (راجع الجدول أعلاه)
response_format	string	wav	تنسيق الصوت (لا يُدعم سوى wav)
instruct	string	""	تعليمة العاطفة أو التنغيم
language	string	كشف تلقائي	تجاوز اكتشاف اللغة

الاستجابة: ملف صوتي (audio/wav)

تصميم الصوت

نقطة النهاية: POST /v1/audio/voice-design

أنشئ أصواتًا مخصصة من أوصاف بلغة طبيعية.

{
  "model": "qwen3-tts-voicedesign",
  "input": "Welcome to our service.",
  "voice_description": "A warm, friendly female voice with a slight British accent",
  "language": "English"
}

ملاحظة

يتطلب تحميل نموذج voicedesign-1.7b.

استنساخ الصوت

نقطة النهاية: POST /v1/audio/voice-clone

استنسخ صوتًا من عينة صوتية مدتها 3 ثوانٍ أو أكثر.

curl -X POST http://localhost:8100/v1/audio/voice-clone \
  -F "input=Hello, this is my cloned voice." \
  -F "[email protected]" \
  -F "reference_text=This is what was said in the reference." \
  --output cloned.wav

المعلمة	النوع	الوصف
input	string	النص المراد توليده
reference_audio	file	عينة صوتية مدتها 3 ثوانٍ أو أكثر
reference_text	string	نص التسجيل المرجعي

ملاحظة

يتطلب تحميل نموذج base-1.7b أو base-0.6b.

سرد الأصوات

نقطة النهاية: GET /v1/voices

{
  "voices": [
    {"id": "ryan", "name": "Ryan", "language": "English"},
    {"id": "aiden", "name": "Aiden", "language": "English"},
    ...
  ]
}

فحص الصحة

نقطة النهاية: GET /health

{ "status": "healthy", "model_loaded": true }

ضبط الخادم

python server.py [OPTIONS]

الخيار	الافتراضي	الوصف
--host	0.0.0.0	المضيف الذي يرتبط به
--port	8100	المنفذ الذي يرتبط به
--model	customvoice-1.7b	نسخة النموذج المراد تحميلها

الوصول عبر الشبكة

للوصول إلى الخادم من أجهزة أخرى على شبكتك:

# Start server on all interfaces
python server.py --host 0.0.0.0 --port 8100

# Access from another machine
curl http://192.168.1.100:8100/v1/audio/speech ...

حدّث نقطة نهاية المكوّن في plugins/qwen-tts.json:

{
  "endpoint": "http://192.168.1.100:8100/v1/audio/speech",
  "capabilities": {
    "tts": {
      "endpoint": "http://192.168.1.100:8100/v1/audio/speech"
    }
  }
}

ميزات الإنتاج

تنقية النص

ينقّي الخادم نص الإدخال تلقائيًا لمنع النموذج من التعليق:

• يزيل الرموز التعبيرية والرموز
• يزيل تنسيق markdown ‏(*bold* و_italic_ وغيرهما)
• يختصر الأحرف المتكررة (FUUUUU → FUU)
• يزيل تعليمات الأداء (*(action)* و(whispers))
• يطبّع المسافات

تقسيم النص

يُقسَّم النص الطويل تلقائيًا عند حدود الجمل:

• 500 حرف كحد أقصى لكل جزء
• مهلة 30 ثانية لكل جزء
• تُتجاوز الأجزاء الفاشلة وتستمر بقية الأجزاء
• تُدمج الأجزاء في استجابة صوتية واحدة

يمنع ذلك انتهاء مهلة ردود AI الطويلة مع الحفاظ على تدفق كلام طبيعي.

إعداد متعدد وحدات GPU

في الأنظمة متعددة وحدات GPU، يفرض الخادم التنفيذ على GPU واحدة لتجنب عدم تطابق أجهزة tensor:

device_map = {"": "cuda:0"}  # Uses first GPU only

لاستخدام GPU محددة:

CUDA_VISIBLE_DEVICES=1 python server.py --model customvoice-1.7b

استكشاف الأخطاء وإصلاحها

فشل تنزيل النموذج

يُنزَّل النموذج من Hugging Face عند أول تشغيل. إذا فشل:

# Set Hugging Face token for gated models
export HF_TOKEN=hf_...

# Or download manually
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice

نفاد الذاكرة (Apple Silicon)

RuntimeError: MPS backend out of memory

استخدم نسخة النموذج الأصغر:

python server.py --model customvoice-0.6b

نفاد ذاكرة CUDA

torch.cuda.OutOfMemoryError: CUDA out of memory

1. أغلق التطبيقات الأخرى التي تستخدم GPU
2. استخدم نسخة النموذج 0.6B
3. اخفض حجم الجزء في server.py ‏(max_chunk_size=300)

انتهاء مهلة الخادم

إذا انتهت مهلة التوليد مع نص طويل:

1. يقسّم الخادم النص تلقائيًا ويواصل بالأجزاء المتبقية
2. افحص سجلات الخادم لمعرفة الأجزاء التي انتهت مهلتها
3. فكّر في تقصير نص الإدخال

الصوت غير صحيح

• مقاطع متكررة: تسببها عادةً الرموز التعبيرية أو الأحرف الخاصة. يفترض أن يعالجها المنقّي تلقائيًا.
• لغة خاطئة: اضبط معلمة language صراحةً في الطلب.
• وقفات غير طبيعية: قد يُقسّم النص عند حدود خاطئة. تحقق من علامات ترقيم غير مألوفة.

ضبط المكوّن الإضافي

المكوّن المضمّن (plugins/qwen-tts.json):

{
  "id": "qwen-tts",
  "name": "Qwen3 TTS",
  "type": "tts",
  "endpoint": "http://localhost:8100/v1/audio/speech",
  "auth": {
    "header": "",
    "key_env": ""
  },
  "model_map": [
    "qwen3-tts",
    "qwen3-tts-customvoice",
    "qwen3-tts-voicedesign",
    "qwen3-tts-clone"
  ],
  "capabilities": {
    "tts": {
      "endpoint": "http://localhost:8100/v1/audio/speech",
      "model_map": [
        "qwen3-tts",
        "qwen3-tts-customvoice",
        "qwen3-tts-voicedesign",
        "qwen3-tts-clone"
      ],
      "config": {
        "voices": [
          "Ryan",
          "Aiden",
          "Vivian",
          "Serena",
          "Uncle_Fu",
          "Dylan",
          "Eric",
          "Ono_Anna",
          "Sohee"
        ],
        "default_voice": "Ryan",
        "formats": ["wav"],
        "default_format": "wav",
        "max_characters": 10000,
        "supports_streaming": false,
        "no_auth_required": true
      }
    }
  },
  "description": "Qwen3-TTS local TTS server (NVIDIA CUDA, Apple MPS, or CPU)",
  "documentation_url": "https://github.com/QwenLM/Qwen3-TTS"
}

الموارد

• Qwen3-TTS على GitHub - المستودع الرسمي
• عرض Qwen3-TTS - جرّبه عبر الإنترنت
• مستندات TTS من Alibaba Cloud - توثيق API السحابي