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.
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:
- 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, được khuyến nghị cho hầu hết các ứng dụng sản xuất
- Light: Độ trễ thấp nhất, dành cho các tình huống di động và biê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
- Đăng nhập vào bảng điều khiển DashScope
- Nhấp vào Quản lý khóa API ở thanh bên trái
- Nhấp vào Tạo khóa API
- 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:
- Sử dụng bản ghi sạch không có tiếng ồn xung quanh
- 15-30 giây hoạt động tốt hơn các đoạn clip rất ngắn
- Định dạng WAV ở 16kHz hoặc cao hơn
- Mẫu giọng nói nên có lời nói tự nhiên, không phải văn bản đọc to, để khớp ngữ điệu tốt hơn
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:
- Kiểm tra xem
choices[0].message.contentkhông trống cho các phản hồi văn bản - Xác minh rằng
choices[0].message.audio.datacó mặt khi yêu cầu đầu ra âm thanh - Khẳng định rằng độ trễ phản hồi cho Flash nằm dưới ngưỡng mục tiêu của bạn
Đ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ắt bớt đến phần có liên quan trước khi gửi
- Giảm độ phân giải xuống 480p nếu nội dung trực quan không yêu cầu độ phân giải cao
- Chia các bản ghi dài thành các phân đoạn và tổng hợp kết quả
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.
