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

@apidog

@apidog

31 tháng 3 2026

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

Apidog cho doanh nghiệp

Triển khai tại chỗ

SSO & RBAC

Tuân thủ SOC 2

Khám phá Apidog Enterprise

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.

button

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.

Đượ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ể có sẵn:

Hướng dẫn này sử dụng Flash cho hầu hết các ví dụ vì đây là điểm khởi đầu phù hợp cho hầu hết các ứng dụng. Hãy chuyển sang Plus khi bạn 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 sẽ cần một tài khoản DashScope và khóa API.

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

Truy cập dashscope.aliyuncs.com và đăng ký. Nếu bạn đã có tài khoản Alibaba Cloud, hãy sử dụng tài khoản đó.

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

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

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

pip install dashscope

Hoặc sử dụng trực tiếp điểm cuối tương thích OpenAI với SDK openai:

pip install openai

DashScope cung cấp một API tương thích OpenAI tại https://dashscope.aliyuncs.com/compatible-mode/v1, có nghĩa là bạn có thể hoán đổi base_url và sử dụng cùng mã bạn sẽ viết cho OpenAI.

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

Bắt đầu với trường hợp đơn giản nhất: văn bản vào, văn bản ra.

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)

Chuyển sang qwen3.5-omni-plus cho các tác vụ suy luận khó hơn hoặc qwen3.5-omni-light khi độ trễ là ưu tiên hàng đầu.


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

Truyền URL tệp âm thanh hoặc âm thanh được mã hóa base64. Mô hình tự động phiên âm, hiểu và suy luận về nội dung. Không cần bước ASR riêng biệt.

import base64
from openai import OpenAI

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

# Tải tệp âm thanh cục bộ
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)

Mô hình xử lý 113 ngôn ngữ để nhận dạng giọng nói. Bạn không cần chỉ định ngôn ngữ; nó tự động phát hiện.

Các định dạng âm thanh được hỗ trợ: 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, hãy đặt tham số modalities và cấu hình đầu ra âm thanh:

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."
        }
    ],
)

# Phản hồi bao gồm cả văn bản và âm thanh
text_content = response.choices[0].message.content
audio_data = response.choices[0].message.audio.data  # WAV được mã hóa base64

# Lưu âm thanh
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")

Có hai giọng nói tích hợp sẵn: Chelsie (nữ) và Ethan (nam). Tính năng tạo giọng nói hoạt động bằng 36 ngôn ngữ.

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

Truyền URL hình ảnh hoặc hình ảnh được mã hóa base64 cùng với câu 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": [
                {
                    "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)

Đối với hình ảnh cục bộ, mã hóa chúng dưới dạng base64:

import base64

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

# Sử dụng định dạng URL dữ liệu
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?"
                }
            ]
        }
    ],
)

Đầu vào video: hiểu các bản ghi và chụp màn hình

Đầu vào video là nơi Qwen3.5-Omni làm điều mà không mô hình văn bản hoặc hình ảnh nào có thể làm được: suy luận đồng thời trên cả luồng hình ảnh và âm thanh.

from openai import OpenAI
import base64

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

# Truyền URL video
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)

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

Trường hợp sử dụng "Lập trình theo cảm xúc" là truyền một bản ghi màn hình và yêu cầu mô hình tạo mã từ những gì nó thấy:

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",  # Sử dụng Plus để có chất lượng tạo mã 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)

Cửa sổ ngữ cảnh 256K token phù hợp với khoảng 400 giây video 720p có âm thanh. Đối với các bản ghi dài hơn, hãy cắt hoặc chia nhỏ.

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

Nhân bản giọng nói cho phép bạn cung cấp cho mô hình một giọng nói mục tiêu và yêu cầu nó phản hồi bằng giọng nói đó. Tính năng này có sẵn trên 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",
)

# Tải mẫu giọng nói 10-30 giây để nhân bản
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))

Mẹo để có chất lượng nhân bản giọng nói tốt:

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

Để trò chuyện bằng giọng nói theo thời gian thực hoặc các ứng dụng tương tác, hãy sử dụng tính năng phát trực tuyến. Mô hình bắt đầu trả về âm thanh trước khi phản hồi hoàn chỉnh được tạo:

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()  # xuống dòng sau văn bản phát trực tuyến

# Kết hợp và lưu các đoạn âm thanh
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)

Định dạng PCM16 hoạt động tốt cho việc phát trực tuyến vì bạn có thể truyền trực tiếp nó đến bộ đệm đầu ra âm thanh mà không cần đợi tệp hoàn chỉnh.

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

Các cuộc hội thoại thực tế trộn lẫn các đầu vào qua các lượt. Đây là cách quản lý lịch sử hội thoại với các phương thức khác nhau:

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?"}]))

Cửa sổ ngữ cảnh 256K có nghĩa là bạn có thể thực hiện các cuộc hội thoại dài, bao gồm cả những cuộc có hình ảnh và âm thanh được nhúng, mà không gặp vấn đề cắt bớt.

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

Nếu bạn cần chạy Qwen3.5-Omni trên cơ sở hạ tầng của riêng mình:

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": "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)

Yêu cầu bộ nhớ GPU để triển khai cục bộ:

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 sản xuất, hãy sử dụng vLLM thay vì HuggingFace Transformers. Các mô hình MoE chạy nhanh hơn dưới sự tối ưu hóa định tuyến của vLLM.

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 khó gỡ lỗi hơn JSON đơn thuần. Bạn đang xử lý âm thanh và video được mã hóa base64, các mảng nội dung lồng nhau và các phản hồi có thể bao gồm cả văn bản và âm thanh. Thực hiện điều này từ một thiết bị đầu cuối sẽ nhanh chóng trở nên tẻ nhạt.

Apidog xử lý điều này một cách gọn gàng. Thiết lập điểm cuối DashScope của bạn dưới dạng một bộ sưu tập mới, lưu trữ khóa API của bạn dưới dạng biến môi trường và xây dựng các mẫu yêu cầu cho từng phương thức bạn đang làm việc.

Đối với mỗi biến thể (Plus, Flash, Light), bạn có thể sao chép yêu cầu cơ bản và thay đổi tham số mô hình. Chạy cả ba theo thứ tự và so sánh các phản hồi, độ trễ và chất lượng đầu ra trong một chế độ xem.

Bạn cũng có thể viết các xác nhận thử nghiệm trong Apidog để xác minh các phản hồi đa phương thức của mình:

Điều này hữu ích khi bạn quyết định sử dụng biến thể nào trong sản xuất.

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

Giới hạn tốc độ và thời gian chờ là phổ biến với các mô hình đa phương thức lớn, đặc biệt đối với đầu vào video. Xây dựng xử lý thử lại 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,  # Thời gian chờ 2 phút cho đầu vào 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ử")

Đối với đầu vào video lớn hơn 100MB, hãy xem xét:


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"Đây là vấn đề mà công nghệ ARIA giải quyết. Đảm bảo bạn đang sử dụng Qwen3.5-Omni (không phải phiên bản cũ hơn). Nếu bạn tự lưu trữ, hãy sử dụng trọng số mô hình mới nhất từ HuggingFace.

"Mô hình cứ nói khi tôi gửi gián đoạn âm thanh"Gián đoạn ngữ nghĩa yêu cầu biến thể Flash hoặc Plus. Light có thể không có tính năng này. Đồng thời kiểm tra xem bạn có đang phát trực tuyến phản hồi (không phải hàng loạt) để gián đoạn hoạt động hay không.

"Chất lượng nhân bản giọng nói kém"Mẫu giọng nói cần sạch. Loại bỏ tiếng ồn xung quanh bằng một công cụ như Audacity trước khi tải lên. Sử dụng ít nhất 15 giây âm thanh. WAV ở 16kHz hoặc 44.1kHz hoạt động tốt nhất.

"Đầu vào video trả về lỗi về giới hạn token"256K token bao gồm khoảng 400 giây video 720p. Các video dài hơn cần được cắt bớt hoặc giảm độ phân giải. Kiểm tra thời lượng video của bạn và giảm xuống dưới 6 phút để an toàn.

"Triển khai cục bộ rất chậm"Sử dụng vLLM, không phải HuggingFace Transformers, để suy luận cục bộ trong sản xuất. Các mô hình MoE cần tối ưu hóa định tuyến của vLLM để có thông lượng hợp lý.

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?

Sử dụng qwen3.5-omni-plus, qwen3.5-omni-flash hoặc qwen3.5-omni-light tùy thuộc vào nhu cầu về chất lượng và độ trễ của bạn. Bắt đầu với Flash cho hầu hết các trường hợp sử dụng.

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

Có. Đặt base_url="https://dashscope.aliyuncs.com/compatible-mode/v1" và sử dụng khóa DashScope của bạn làm api_key. Định dạng yêu cầu và phản hồi giống hệt với OpenAI API.

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

Đặt chúng vào mảng content dưới dạng các đối tượng được đánh máy riêng biệt cùng với lời nhắc văn bản của bạn. Cả bốn phương thức có thể xuất hiện trong cùng một tin nhắn.

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

DashScope có giới hạn tải trọng cho mỗi yêu cầu. Đối với các tệp lớn, hãy sử dụng tham chiếu URL thay vì mã hóa base64. Lưu trữ tệp trên bộ nhớ có thể truy cập và truyền URL vào trường 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. Các phản hồi chỉ bằng văn bản nhanh hơn và rẻ hơn.

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

Có. Sử dụng tham số tools tiêu chuẩn với định nghĩa hàm, giống như với bất kỳ mô hình tương thích OpenAI nào. Mô hình trả về các đối tượng gọi công cụ có cấu trúc mà bạn thực thi trong mã của riêng mình.

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

Đối với các bản ghi dưới 10 giờ, hãy gửi chúng dưới dạng một yêu cầu duy nhất. Đối với các bản ghi dài hơn, hãy chia nhỏ tại các điểm dừng tự nhiên và xử lý từng phân đoạn riêng biệt. Tổng hợp kết quả trong lớp ứng dụng của bạn.

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?

Sử dụng Apidog để xây dựng và lưu các mẫu yêu cầu cho từng phương thức. Bạn có thể chuyển đổi giữa các biến thể mô hình, kiểm tra cấu trúc phản hồi đầy đủ và viết các xác nhận để xác minh chất lượng đầu ra mà không cần viết mã ứng dụng trước.

button

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API