كيفية استخدام Qwen3.5-Omni: نص، صوت، فيديو، واستنساخ صوتي عبر API

باختصار

يقبل Qwen3.5-Omni النصوص والصور والصوت والفيديو كمدخلات ويعيد نصًا أو كلامًا في الوقت الفعلي. يمكنك الوصول إليه عبر واجهة برمجة تطبيقات Alibaba Cloud DashScope أو تشغيله محليًا عبر HuggingFace Transformers. يغطي هذا الدليل إعداد واجهة برمجة التطبيقات، وأمثلة تعليمات برمجية عملية لكل وسيلة، واستنساخ الصوت، وكيفية اختبار طلباتك باستخدام Apidog.

button

ما تتعامل معه

Qwen3.5-Omni هو نموذج واحد يتعامل مع أربعة أنواع من المدخلات في وقت واحد: النص، الصور، الصوت، والفيديو. ويعيد إما نصًا أو كلامًا طبيعيًا، اعتمادًا على كيفية تهيئة الطلب.

تم إطلاقه في 30 مارس 2026، وهو مبني على بنية Thinker-Talker مع بنية أساسية (backbone) من نوع MoE. يقوم Thinker بمعالجة المدخلات متعددة الوسائط والتعليل بناءً عليها. يقوم Talker بتحويل المخرجات إلى كلام باستخدام نظام متعدد القواميس (multi-codebook system) يبدأ في بث الصوت قبل اكتمال الاستجابة بالكامل.

تتوفر ثلاثة أنواع:

Plus: أعلى جودة، الأفضل للتعليل واستنساخ الصوت
Flash: توازن بين السرعة والجودة، موصى به لمعظم استخدامات الإنتاج
Light: أقل زمن استجابة، لسيناريوهات الأجهزة المحمولة والحافة

يستخدم هذا الدليل Flash لمعظم الأمثلة لأنه نقطة البداية الصحيحة لمعظم التطبيقات. استبدلها بـ Plus عندما تحتاج إلى أقصى جودة.

الوصول إلى واجهة برمجة التطبيقات (API) عبر DashScope

واجهة برمجة تطبيقات DashScope من Alibaba Cloud هي الطريقة الأساسية لاستخدام Qwen3.5-Omni في الإنتاج. ستحتاج إلى حساب DashScope ومفتاح API.

الخطوة 1: إنشاء حساب DashScope

انتقل إلى dashscope.aliyuncs.com وقم بالتسجيل. إذا كان لديك بالفعل حساب Alibaba Cloud، فاستخدمه.

الخطوة 2: الحصول على مفتاح API الخاص بك

سجل الدخول إلى لوحة تحكم DashScope
انقر فوق إدارة مفتاح API (API Key Management) في الشريط الجانبي الأيسر
انقر فوق إنشاء مفتاح API (Create API Key)
انسخ المفتاح (التنسيق: sk-...)

الخطوة 3: تثبيت حزمة SDK

pip install dashscope

أو استخدم نقطة نهاية متوافقة مع OpenAI مباشرةً مع حزمة openai SDK:

pip install openai

تكشف DashScope عن واجهة برمجة تطبيقات متوافقة مع OpenAI على https://dashscope.aliyuncs.com/compatible-mode/v1، مما يعني أنه يمكنك تبديل base_url واستخدام نفس الكود الذي ستكتبه لـ OpenAI.

المدخلات والمخرجات النصية

ابدأ بالحالة الأبسط: نص مدخل، نص مخرج.

from openai import OpenAI

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
)

response = client.chat.completions.create(
    model="qwen3.5-omni-flash",
    messages=[
        {
            "role": "user",
            "content": "Explain the difference between REST and GraphQL APIs in plain terms."
        }
    ],
)

print(response.choices[0].message.content)

غيّر إلى qwen3.5-omni-plus لمهام التعليل الأكثر صعوبة أو qwen3.5-omni-light عندما يكون زمن الاستجابة هو الأولوية.

مدخلات الصوت: النسخ والفهم

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

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
)

# Load a local audio file
with open("meeting_recording.wav", "rb") as f:
    audio_data = base64.b64encode(f.read()).decode("utf-8")

response = client.chat.completions.create(
    model="qwen3.5-omni-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_audio",
                    "input_audio": {
                        "data": audio_data,
                        "format": "wav"
                    }
                },
                {
                    "type": "text",
                    "text": "Summarize the key decisions made in this meeting and list any action items."
                }
            ]
        }
    ],
)

print(response.choices[0].message.content)

يتعامل النموذج مع 113 لغة للتعرف على الكلام. لا تحتاج إلى تحديد اللغة؛ فهو يكتشفها تلقائيًا.

تنسيقات الصوت المدعومة: WAV، MP3، M4A، OGG، FLAC.

مخرجات الصوت: تحويل النص إلى كلام في الاستجابة

للحصول على كلام بدلاً من النص، قم بتعيين معلمة modalities وقم بتهيئة مخرجات الصوت:

from openai import OpenAI
import base64

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
)

response = client.chat.completions.create(
    model="qwen3.5-omni-flash",
    modalities=["text", "audio"],
    audio={"voice": "Chelsie", "format": "wav"},
    messages=[
        {
            "role": "user",
            "content": "Describe the steps to authenticate a REST API using OAuth 2.0."
        }
    ],
)

# The response includes both text and audio
text_content = response.choices[0].message.content
audio_data = response.choices[0].message.audio.data  # base64-encoded WAV

# Save the audio
with open("response.wav", "wb") as f:
    f.write(base64.b64decode(audio_data))

print(f"Text: {text_content}")
print("Audio saved to response.wav")

يتوفر صوتان مدمجان: Chelsie (أنثى) و Ethan (ذكر). يعمل توليد الكلام في 36 لغة.

مدخلات الصورة: الفهم البصري

مرر عنوان URL للصورة أو صورة مشفرة بـ base64 جنبًا إلى جنب مع سؤال نصي:

from openai import OpenAI

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
)

response = client.chat.completions.create(
    model="qwen3.5-omni-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/api-diagram.png"
                    }
                },
                {
                    "type": "text",
                    "text": "Describe this API architecture diagram and identify any potential bottlenecks."
                }
            ]
        }
    ],
)

print(response.choices[0].message.content)

للصور المحلية، قم بتشفيرها كـ base64:

import base64

with open("screenshot.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

# Use data URL format
image_url = f"data:image/png;base64,{image_data}"

response = client.chat.completions.create(
    model="qwen3.5-omni-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {"url": image_url}
                },
                {
                    "type": "text",
                    "text": "What error is shown in this screenshot?"
                }
            ]
        }
    ],
)

مدخلات الفيديو: فهم التسجيلات والتقاط الشاشة

تتمثل مدخلات الفيديو في أن Qwen3.5-Omni يفعل شيئًا لا يمكن لأي نموذج نص أو صورة فعله: التعليل عبر كل من المسارين البصري والصوتي في وقت واحد.

from openai import OpenAI
import base64

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
)

# Pass a video URL
response = client.chat.completions.create(
    model="qwen3.5-omni-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://example.com/product-demo.mp4"
                    }
                },
                {
                    "type": "text",
                    "text": "Describe what the developer is building in this demo and write equivalent code."
                }
            ]
        }
    ],
)

print(response.choices[0].message.content)

الترميز البصري السمعي (Audio-Visual Vibe Coding)

حالة الاستخدام "ترميز المشاعر" هي تمرير تسجيل شاشة وطلب من النموذج إنشاء رمز مما يراه:

with open("screen_recording.mp4", "rb") as f:
    video_data = base64.b64encode(f.read()).decode("utf-8")

response = client.chat.completions.create(
    model="qwen3.5-omni-plus",  # Use Plus for best code generation quality
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "video_url",
                    "video_url": {
                        "url": f"data:video/mp4;base64,{video_data}"
                    }
                },
                {
                    "type": "text",
                    "text": "Watch this screen recording and write the complete code that replicates what you see being built. Include all the UI components and their interactions."
                }
            ]
        }
    ],
)

print(response.choices[0].message.content)

نافذة السياق بحجم 256K رمزًا تتسع تقريبًا لـ 400 ثانية من فيديو بدقة 720p مع صوت. للتسجيلات الأطول من ذلك، قم بالقص أو التقسيم.

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

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

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
)

# Load a 10-30 second voice sample for cloning
with open("voice_sample.wav", "rb") as f:
    voice_sample = base64.b64encode(f.read()).decode("utf-8")

response = client.chat.completions.create(
    model="qwen3.5-omni-plus",
    modalities=["text", "audio"],
    audio={
        "voice": "custom",
        "format": "wav",
        "voice_sample": {
            "data": voice_sample,
            "format": "wav"
        }
    },
    messages=[
        {
            "role": "user",
            "content": "Welcome to the Apidog developer portal. How can I help you today?"
        }
    ],
)

audio_data = response.choices[0].message.audio.data
with open("cloned_response.wav", "wb") as f:
    f.write(base64.b64decode(audio_data))

نصائح لجودة استنساخ الصوت:

استخدم تسجيلًا نظيفًا بدون ضوضاء خلفية
15-30 ثانية تعمل بشكل أفضل من المقاطع القصيرة جدًا
تنسيق WAV بتردد 16 كيلو هرتز أو أعلى
يجب أن يحتوي نموذج الصوت على كلام طبيعي، وليس نصًا مقروءًا، لمطابقة أفضل للتلحين

تدفق الاستجابات

للمحادثة الصوتية في الوقت الفعلي أو التطبيقات التفاعلية، استخدم التدفق (streaming). يبدأ النموذج في إرجاع الصوت قبل أن يتم توليد الاستجابة الكاملة:

from openai import OpenAI

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
)

stream = client.chat.completions.create(
    model="qwen3.5-omni-flash",
    modalities=["text", "audio"],
    audio={"voice": "Ethan", "format": "pcm16"},
    messages=[
        {
            "role": "user",
            "content": "Explain how WebSocket connections differ from HTTP polling."
        }
    ],
    stream=True,
)

audio_chunks = []
text_chunks = []

for chunk in stream:
    delta = chunk.choices[0].delta
    if hasattr(delta, "audio") and delta.audio:
        if delta.audio.get("data"):
            audio_chunks.append(delta.audio["data"])
    if delta.content:
        text_chunks.append(delta.content)
        print(delta.content, end="", flush=True)

print()  # newline after streaming text

# Combine and save audio chunks
if audio_chunks:
    import base64
    full_audio = b"".join(base64.b64decode(chunk) for chunk in audio_chunks)
    with open("streamed_response.pcm", "wb") as f:
        f.write(full_audio)

يعمل تنسيق PCM16 جيدًا للتدفق حيث يمكنك تمريره مباشرة إلى مخزن مؤقت لمخرجات الصوت دون انتظار ملف كامل.

محادثة متعددة الأدوار بوسائل متعددة مختلطة

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

from openai import OpenAI

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
)

conversation = []

def send_message(content_parts):
    conversation.append({"role": "user", "content": content_parts})
    
    response = client.chat.completions.create(
        model="qwen3.5-omni-flash",
        messages=conversation,
    )
    
    reply = response.choices[0].message.content
    conversation.append({"role": "assistant", "content": reply})
    return reply

# Turn 1: text
print(send_message([{"type": "text", "text": "I have an API that keeps returning 503 errors."}]))

# Turn 2: add an image (error log screenshot)
import base64
with open("error_log.png", "rb") as f:
    img = base64.b64encode(f.read()).decode()

print(send_message([
    {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{img}"}},
    {"type": "text", "text": "Here's the error log screenshot. What's causing this?"}
]))

# Turn 3: follow-up text
print(send_message([{"type": "text", "text": "How do I fix the connection pool exhaustion you mentioned?"}]))

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

النشر المحلي باستخدام HuggingFace

إذا كنت بحاجة إلى تشغيل Qwen3.5-Omni على البنية التحتية الخاصة بك:

pip install transformers==4.57.3
pip install accelerate
pip install qwen-omni-utils -U
pip install -U flash-attn --no-build-isolation

import soundfile as sf
from transformers import Qwen3OmniMoeForConditionalGeneration, Qwen3OmniMoeProcessor
from qwen_omni_utils import process_mm_info

model_path = "Qwen/Qwen3-Omni-30B-A3B-Instruct"

model = Qwen3OmniMoeForConditionalGeneration.from_pretrained(
    model_path,
    device_map="auto",
    attn_implementation="flash_attention_2",
)
processor = Qwen3OmniMoeProcessor.from_pretrained(model_path)

conversation = [
    {
        "role": "system",
        "content": [
            {"type": "text", "text": "You are Qwen, a virtual human developed by the Qwen Team, Alibaba Group, capable of perceiving auditory and visual inputs, as well as generating text and speech."}
        ],
    },
    {
        "role": "user",
        "content": [
            {"type": "audio", "audio": "path/to/your/audio.wav"},
            {"type": "text", "text": "What is being discussed in this audio?"}
        ],
    },
]

text = processor.apply_chat_template(
    conversation,
    add_generation_prompt=True,
    tokenize=False,
)
audios, images, videos = process_mm_info(conversation, use_audio_in_video=True)
inputs = processor(
    text=text,
    audio=audios,
    images=images,
    videos=videos,
    return_tensors="pt",
    padding=True,
)
inputs = inputs.to(model.device).to(model.dtype)

text_ids, audio_output = model.generate(**inputs, speaker="Chelsie")

text_response = processor.batch_decode(text_ids, skip_special_tokens=True)[0]
sf.write("local_response.wav", audio_output.reshape(-1).cpu().numpy(), samplerate=24000)

print(text_response)

متطلبات ذاكرة GPU للنشر المحلي:

النوع	الدقة	الحد الأدنى لـ VRAM
Plus (30B MoE)	BF16	~40GB
Flash	BF16	~20GB
Light	BF16	~10GB

للاستدلال المحلي في الإنتاج، استخدم vLLM بدلاً من HuggingFace Transformers. تعمل نماذج MoE بشكل أسرع تحت تحسينات توجيه vLLM.

اختبار طلبات Qwen3.5-Omni الخاصة بك باستخدام Apidog

طلبات واجهة برمجة التطبيقات متعددة الوسائط أصعب في تصحيح الأخطاء من JSON العادي. أنت تتعامل مع صوت وفيديو مشفرين بـ base64، ومصفوفات محتوى متداخلة، واستجابات يمكن أن تتضمن نصًا وصوتًا. يصبح القيام بذلك من المحطة الطرفية مملًا بسرعة.

اختبار طلبات Qwen3.5-Omni باستخدام Apidog

Apidog يتعامل مع هذا بوضوح. قم بإعداد نقطة نهاية DashScope كجمع جديد، وقم بتخزين مفتاح API الخاص بك كمتغير بيئة، وقم بإنشاء قوالب طلبات لكل وسيلة تعمل معها.

لكل نوع (Plus، Flash، Light)، يمكنك تكرار الطلب الأساسي وتغيير معلمة النموذج. قم بتشغيل الثلاثة بالتتابع وقارن الاستجابات، وزمن الاستجابة، وجودة المخرجات في عرض واحد.

يمكنك أيضًا كتابة تأكيدات الاختبار في Apidog للتحقق من استجاباتك متعددة الوسائط:

تحقق من أن choices[0].message.content ليس فارغًا للاستجابات النصية
تحقق من وجود choices[0].message.audio.data عند طلب مخرجات الصوت
تأكد من أن زمن استجابة Flash أقل من العتبة المستهدفة

هذا مفيد عندما تقرر أي نوع ستستخدمه في الإنتاج.

معالجة الأخطاء ومنطق إعادة المحاولة

حدود السرعة (Rate limits) والمهلات (timeouts) شائعة مع النماذج الكبيرة متعددة الوسائط، خاصة لمدخلات الفيديو. قم ببناء معالجة إعادة المحاولة من البداية:

import time
import random
from openai import OpenAI, RateLimitError, APITimeoutError, APIConnectionError

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="sk-YOUR_DASHSCOPE_KEY",
    timeout=120,  # 2-minute timeout for large video inputs
)

def call_with_retry(messages, model="qwen3.5-omni-flash", max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model=model,
                messages=messages,
            )
        except RateLimitError:
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"Rate limit hit. Waiting {wait:.1f}s...")
            time.sleep(wait)
        except (APITimeoutError, APIConnectionError) as e:
            if attempt == max_retries - 1:
                raise
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"Connection error: {e}. Retrying in {wait:.1f}s...")
            time.sleep(wait)
    raise RuntimeError(f"Failed after {max_retries} attempts")

بالنسبة لمدخلات الفيديو التي يزيد حجمها عن 100 ميجابايت، ضع في اعتبارك ما يلي:

القص إلى الجزء ذي الصلة قبل الإرسال
تقليل الدقة إلى 480p إذا كان المحتوى المرئي لا يتطلب دقة عالية
تقسيم التسجيلات الطويلة إلى أجزاء وتجميع النتائج

المشكلات الشائعة والإصلاحات

"مخرجات الصوت مشوهة على الأرقام أو المصطلحات التقنية"هذه هي المشكلة التي تعالجها تقنية ARIA. تأكد من أنك تستخدم Qwen3.5-Omni (وليس إصدارًا سابقًا). إذا كنت تستضيف ذاتيًا، استخدم أحدث أوزان النموذج من HuggingFace.

"النموذج يستمر في الكلام عندما أرسل مقاطعة صوتية"تتطلب المقاطعة الدلالية نوع Flash أو Plus. قد لا يدعم Light هذه الميزة. تحقق أيضًا من أنك تقوم ببث الاستجابة (وليس الدفعة) لكي تعمل المقاطعة.

"جودة استنساخ الصوت رديئة"يجب أن يكون نموذج الصوت نظيفًا. أزل ضوضاء الخلفية باستخدام أداة مثل Audacity قبل الرفع. استخدم 15 ثانية على الأقل من الصوت. يعمل WAV بتردد 16 كيلو هرتز أو 44.1 كيلو هرتز بشكل أفضل.

"مدخلات الفيديو ترجع خطأ حول حدود الرموز"256 ألف رمز يغطي ما يقرب من 400 ثانية من فيديو بدقة 720p. تتطلب مقاطع الفيديو الأطول القص أو دقة أقل. تحقق من مدة الفيديو وقم بتقليلها إلى أقل من 6 دقائق للسلامة.

"النشر المحلي بطيء جدًا"استخدم vLLM، وليس HuggingFace Transformers، للاستدلال المحلي في الإنتاج. تحتاج نماذج MoE إلى تحسينات توجيه vLLM للحصول على إنتاجية معقولة.

الأسئلة الشائعة

ما هو معرف نموذج DashScope الذي أستخدمه لـ Qwen3.5-Omni؟

استخدم qwen3.5-omni-plus أو qwen3.5-omni-flash أو qwen3.5-omni-light اعتمادًا على احتياجاتك من الجودة وزمن الاستجابة. ابدأ بـ Flash لمعظم حالات الاستخدام.

هل يمكنني استخدام حزمة OpenAI Python SDK مع DashScope؟

نعم. قم بتعيين base_url="https://dashscope.aliyuncs.com/compatible-mode/v1" واستخدم مفتاح DashScope الخاص بك كـ api_key. تنسيق الطلب والاستجابة متطابق مع واجهة برمجة تطبيقات OpenAI.

كيف أرسل ملفات متعددة (صوت + صورة) في طلب واحد؟

ضعها في مصفوفة content ككائنات منفصلة ذات أنواع محددة جنبًا إلى جنب مع موجه النص الخاص بك. يمكن أن تظهر جميع الوسائل الأربعة في نفس الرسالة.

هل هناك حد لحجم ملفات الصوت أو الفيديو؟

لدى DashScope قيود على حجم الحمولة لكل طلب. للملفات الكبيرة، استخدم مرجع URL بدلاً من تشفير base64. استضف الملف على تخزين يمكن الوصول إليه ومرر عنوان URL في حقل audio أو video_url.

كيف أوقف مخرجات الصوت وأحصل على نص فقط؟

عيّن modalities=["text"] أو احذف معلمة modalities. الاستجابات النصية فقط أسرع وأقل تكلفة.

هل يدعم استدعاء الدالة/الأداة؟

نعم. استخدم معلمة tools القياسية مع تعريفات الدالة، تمامًا كما هو الحال مع أي نموذج متوافق مع OpenAI. يعيد النموذج كائنات استدعاء أداة منظمة تقوم بتنفيذها في الكود الخاص بك.

ما هي أفضل طريقة للتعامل مع التسجيلات الصوتية الطويلة؟

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

كيف أختبر طلباتي متعددة الوسائط قبل بناء تطبيق كامل؟

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

button