DEV Community

Cover image for Hướng Dẫn Sử Dụng Qwen3.5-Omni: Văn Bản, Âm Thanh, Video và Sao Chép Giọng Nói Qua API
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Hướng Dẫn Sử Dụng Qwen3.5-Omni: Văn Bản, Âm Thanh, Video và Sao Chép Giọng Nói Qua API

TL;DR

Qwen3.5-Omni chấp nhận văn bản, hình ảnh, âm thanh và video làm đầu vào, đồng thời trả về văn bản hoặc giọng nói theo thời gian thực. Truy cập nó thông qua API DashScope của Alibaba Cloud hoặc chạy cục bộ thông qua HuggingFace Transformers. Hướng dẫn này bao gồm thiết lập API, các ví dụ mã hoạt động cho từng phương thức, nhân bản giọng nói và cách kiểm tra các yêu cầu của bạn với Apidog.

Dùng thử Apidog ngay hôm nay

Bạn đang làm việc với gì

Qwen3.5-Omni là một mô hình duy nhất xử lý đồng thời bốn loại đầu vào: văn bản, hình ảnh, âm thanh và video. Nó trả về văn bản hoặc giọng nói tự nhiên, tùy thuộc vào cách bạn cấu hình yêu cầu.

Qwen3.5-Omni multi-modal

Được phát hành vào ngày 30 tháng 3 năm 2026, nó được xây dựng trên kiến trúc Thinker-Talker với xương sống MoE (Mixture of Experts). Thinker xử lý đầu vào đa phương thức và suy luận trên đó. Talker chuyển đổi đầu ra thành giọng nói bằng cách sử dụng hệ thống multi-codebook bắt đầu phát trực tuyến âm thanh trước khi phản hồi hoàn chỉnh.

Có ba biến thể:

  • Plus: Chất lượng cao nhất, tốt nhất cho suy luận và nhân bản giọng nói.
  • Flash: Tốc độ và chất lượng cân bằng, phù hợp cho đa số ứng dụng sản xuất.
  • Light: Độ trễ thấp nhất, dành cho mobile và edge.

Hướng dẫn này sử dụng Flash cho phần lớn ví dụ. Chuyển sang Plus khi cần chất lượng tối đa.

Truy cập API qua DashScope

API DashScope của Alibaba Cloud là cách chính để sử dụng Qwen3.5-Omni trong sản xuất. Bạn cần tài khoản DashScope và API key.

Bước 1: Tạo tài khoản DashScope

Truy cập dashscope.aliyuncs.com và đăng ký. Nếu đã có tài khoản Alibaba Cloud, hãy dùng luôn tài khoản đó.

Bước 2: Lấy khóa API của bạn

  1. Đăng nhập bảng điều khiển DashScope.
  2. Chọn Quản lý khóa API ở sidebar.
  3. Nhấn Tạo khóa API.
  4. Sao chép khóa (dạng: sk-...).

Bước 3: Cài đặt SDK

Cài đặt SDK DashScope:

pip install dashscope
Enter fullscreen mode Exit fullscreen mode

Hoặc dùng OpenAI Python SDK với endpoint tương thích:

pip install openai
Enter fullscreen mode Exit fullscreen mode

DashScope có endpoint OpenAI-compatible: https://dashscope.aliyuncs.com/compatible-mode/v1. Bạn chỉ cần đổi base_url và dùng cùng đoạn mã như OpenAI.

Đầu vào và đầu ra văn bản

Gửi văn bản và nhận phản hồi văn bản:

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": "Giải thích sự khác biệt giữa API REST và GraphQL một cách đơn giản."
        }
    ],
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

Tùy tác vụ, chuyển sang qwen3.5-omni-plus (chất lượng cao) hoặc qwen3.5-omni-light (ưu tiên độ trễ thấp).

Đầu vào âm thanh: phiên âm và hiểu

Truyền URL file âm thanh hoặc base64. Mô hình tự động phiên âm và suy luận, không cần bước ASR riêng.

import base64
from openai import OpenAI

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

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": "Tóm tắt các quyết định chính được đưa ra trong cuộc họp này và liệt kê các mục hành động."
                }
            ]
        }
    ],
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode
  • Hỗ trợ 113 ngôn ngữ, tự động phát hiện.
  • Định dạng: WAV, MP3, M4A, OGG, FLAC.

Đầu ra âm thanh: chuyển văn bản thành giọng nói trong phản hồi

Nhận lại giọng nói thay vì văn bản bằng cách cấu hình output audio:

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": "Mô tả các bước để xác thực API REST bằng OAuth 2.0."
        }
    ],
)

text_content = response.choices[0].message.content
audio_data = response.choices[0].message.audio.data

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

print(f"Văn bản: {text_content}")
print("Âm thanh đã được lưu vào response.wav")
Enter fullscreen mode Exit fullscreen mode
  • Có hai giọng nói tích hợp: Chelsie (nữ), Ethan (nam).
  • Hỗ trợ tạo giọng nói ở 36 ngôn ngữ.

Đầu vào hình ảnh: hiểu trực quan

Truyền URL ảnh hoặc base64 cùng câu hỏi:

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": "Mô tả sơ đồ kiến trúc API này và xác định bất kỳ nút thắt cổ chai tiềm ẩn nào."
                }
            ]
        }
    ],
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

Đối với ảnh cục bộ, mã hóa base64:

import base64

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

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": "Lỗi nào được hiển thị trong ảnh chụp màn hình này?"
                }
            ]
        }
    ],
)
Enter fullscreen mode Exit fullscreen mode

Đầu vào video: hiểu bản ghi và màn hình

Qwen3.5-Omni có khả năng suy luận đồng thời hình ảnh và âm thanh trong video.

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",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://example.com/product-demo.mp4"
                    }
                },
                {
                    "type": "text",
                    "text": "Mô tả những gì nhà phát triển đang xây dựng trong bản demo này và viết mã tương đương."
                }
            ]
        }
    ],
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

Lập trình theo cảm xúc nghe-nhìn (Audio-Visual Vibe Coding)

Truyền bản ghi màn hình và yêu cầu mô hình sinh code:

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",  # Dùng Plus cho chất lượng tốt nhất
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "video_url",
                    "video_url": {
                        "url": f"data:video/mp4;base64,{video_data}"
                    }
                },
                {
                    "type": "text",
                    "text": "Xem bản ghi màn hình này và viết mã hoàn chỉnh để tái tạo những gì bạn thấy đang được xây dựng. Bao gồm tất cả các thành phần giao diện người dùng và tương tác của chúng."
                }
            ]
        }
    ],
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode
  • Cửa sổ ngữ cảnh 256K token ≈ 400 giây video 720p có âm thanh. Nếu dài hơn, hãy cắt hoặc chia nhỏ file.

Nhân bản giọng nói

Cung cấp mẫu giọng nói và nhận phản hồi với giọng nói đó. Áp dụng cho Plus và Flash qua API.

import base64
from openai import OpenAI

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

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": "Chào mừng bạn đến với cổng nhà phát triển Apidog. Tôi có thể giúp gì cho bạn hôm nay?"
        }
    ],
)

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

Mẹo:

  • Bản ghi mẫu sạch, không tiếng ồn.
  • 15-30 giây là tối ưu.
  • Định dạng WAV 16kHz trở lên.
  • Mẫu nên là lời nói tự nhiên.

Phản hồi phát trực tuyến

Để nhận phản hồi âm thanh theo thời gian thực, dùng chế độ stream:

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": "Giải thích sự khác biệt giữa kết nối WebSocket và 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()

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)
Enter fullscreen mode Exit fullscreen mode
  • PCM16 phù hợp để phát trực tiếp.

Hội thoại đa lượt với các phương thức hỗn hợp

Quản lý lịch sử hội thoại với nhiều loại đầu vào:

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

# Lượt 1: văn bản
print(send_message([{"type": "text", "text": "Tôi có một API liên tục trả về lỗi 503."}]))

# Lượt 2: thêm hình ảnh (ảnh chụp màn hình nhật ký lỗi)
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": "Đây là ảnh chụp màn hình nhật ký lỗi. Nguyên nhân là gì?"}
]))

# Lượt 3: văn bản theo dõi
print(send_message([{"type": "text", "text": "Làm thế nào để tôi khắc phục tình trạng cạn kiệt connection pool mà bạn đã đề cập?"}]))
Enter fullscreen mode Exit fullscreen mode
  • Cửa sổ 256K token đủ cho hội thoại dài, kể cả có hình và âm thanh nhúng.

Triển khai cục bộ với HuggingFace

Chạy Qwen3.5-Omni trên hạ tầng của bạn:

pip install transformers==4.57.3
pip install accelerate
pip install qwen-omni-utils -U
pip install -U flash-attn --no-build-isolation
Enter fullscreen mode Exit fullscreen mode 
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": "Bạn là Qwen, một con người ảo được phát triển bởi Qwen Team, Alibaba Group, có khả năng nhận biết đầu vào âm thanh và hình ảnh, cũng như tạo văn bản và giọng nói."}
        ],
    },
    {
        "role": "user",
        "content": [
            {"type": "audio", "audio": "path/to/your/audio.wav"},
            {"type": "text", "text": "Những gì đang được thảo luận trong âm thanh này?"}
        ],
    },
]

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)
Enter fullscreen mode Exit fullscreen mode

Yêu cầu bộ nhớ GPU:

Biến thể Độ chính xác VRAM tối thiểu
Plus (30B MoE) BF16 ~40GB
Flash BF16 ~20GB
Light BF16 ~10GB
  • Để suy luận cục bộ trong production, nên dùng vLLM (tối ưu hóa routing cho MoE).

Kiểm tra các yêu cầu Qwen3.5-Omni của bạn với Apidog

Các yêu cầu API đa phương thức phức tạp hơn JSON đơn thuần. Bạn cần xử lý base64, mảng content lồng nhau và phản hồi có thể gồm văn bản + âm thanh. Làm bằng terminal sẽ rất mất thời gian.

Apidog multi-modal debug

Apidog giúp bạn kiểm tra các endpoint DashScope, lưu khóa API thành biến môi trường và xây mẫu request cho từng phương thức.

  • Clone và chỉnh tham số model cho từng biến thể (Plus, Flash, Light).
  • Chạy các biến thể và so sánh output, latency, chất lượng ngay trong một tab.

  • Viết xác nhận kiểm thử cho response đa phương thức:

    • Kiểm tra choices[0].message.content không rỗng với văn bản
    • Kiểm tra choices[0].message.audio.data tồn tại nếu yêu cầu audio
    • Đo latency để đảm bảo Flash đáp ứng mục tiêu

Giúp bạn chọn biến thể phù hợp cho production.

Xử lý lỗi và logic thử lại

Với mô hình lớn, đặc biệt khi input là video, dễ gặp rate limit hoặc timeout. Cần xử lý retry ngay từ đầu:

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,  # Timeout 2 phút cho video lớn
)

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"Đã đạt giới hạn tốc độ. Đang chờ {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"Lỗi kết nối: {e}. Đang thử lại sau {wait:.1f}s...")
            time.sleep(wait)
    raise RuntimeError(f"Thất bại sau {max_retries} lần thử")
Enter fullscreen mode Exit fullscreen mode

Đối với video lớn (>100MB):

  • Cắt lấy đoạn liên quan trước khi gửi.
  • Giảm độ phân giải xuống 480p nếu không cần hình ảnh sắc nét.
  • Chia bản ghi dài thành segment, tổng hợp sau.

Các vấn đề thường gặp và cách khắc phục

"Đầu ra âm thanh bị rè khi nói về số hoặc thuật ngữ kỹ thuật"

Hãy chắc chắn bạn dùng Qwen3.5-Omni. Nếu tự host, tải trọng số mới nhất từ HuggingFace.

"Mô hình cứ nói khi tôi gửi gián đoạn âm thanh"

Chỉ Flash hoặc Plus hỗ trợ gián đoạn ngữ nghĩa tốt. Light có thể không hỗ trợ. Đảm bảo bạn dùng chế độ streaming.

"Chất lượng nhân bản giọng nói kém"

Dùng bản ghi sạch, không noise. Audacity có thể giúp lọc noise. Đoạn mẫu >15s, WAV 16kHz/44.1kHz.

"Video trả về lỗi token limit"

256K token ≈ 400 giây video 720p. Cắt video ngắn lại, hoặc giảm độ phân giải/duration.

"Triển khai cục bộ rất chậm"

Dùng vLLM thay vì HuggingFace Transformers để suy luận local với MoE.

Câu hỏi thường gặp

Tôi nên sử dụng ID mô hình DashScope nào cho Qwen3.5-Omni?

Dùng qwen3.5-omni-plus, qwen3.5-omni-flash hoặc qwen3.5-omni-light tùy ứng dụng. Flash là baseline tốt.

Tôi có thể sử dụng OpenAI Python SDK với DashScope không?

Hoàn toàn được. Đặt base_url="https://dashscope.aliyuncs.com/compatible-mode/v1", dùng DashScope API key. Format request/response giống hệt OpenAI.

Làm cách nào để gửi nhiều tệp (âm thanh + hình ảnh) trong một yêu cầu?

Đưa vào mảng content với object type khác nhau, cùng prompt text. Hỗ trợ đủ 4 loại trong 1 message.

Có giới hạn kích thước cho tệp âm thanh hoặc video không?

DashScope giới hạn payload từng request. File lớn thì dùng URL, không nên base64. Host file lên nơi truy cập được, truyền URL vào audio hoặc video_url.

Làm cách nào để tắt đầu ra âm thanh và chỉ nhận văn bản?

Đặt modalities=["text"] hoặc bỏ qua tham số modalities (default: chỉ trả về văn bản).

Nó có hỗ trợ gọi hàm/công cụ không?

Có. Dùng tham số tools chuẩn (OpenAI function calling). Mô hình trả về đối tượng gọi công cụ, bạn thực thi phần đó.

Cách tốt nhất để xử lý các bản ghi âm dài là gì?

<10h: gửi một lần. Dài hơn: chia theo điểm dừng tự nhiên, gửi batch nhỏ, tổng hợp kết quả ở client.

Làm cách nào để kiểm tra các yêu cầu đa phương thức của tôi trước khi xây dựng một ứng dụng hoàn chỉnh?

Dùng Apidog xây dựng/lưu mẫu request cho từng phương thức, chuyển đổi model, kiểm tra response, viết assertion kiểm thử -- mà không cần code app trước.

Top comments (0)