2025-12-12 15:14:52 +08:00
|
|
|
# Qwen3-Omni
|
2025-11-30 18:20:44 +08:00
|
|
|
|
2025-12-03 11:25:58 +08:00
|
|
|
Source <https://github.com/vllm-project/vllm-omni/tree/main/examples/online_serving/qwen3_omni>.
|
2025-11-30 18:20:44 +08:00
|
|
|
|
|
|
|
|
|
|
|
|
|
## 🛠️ Installation
|
|
|
|
|
|
2025-12-03 11:25:58 +08:00
|
|
|
Please refer to [README.md](https://github.com/vllm-project/vllm-omni/tree/main/README.md)
|
2025-11-30 18:20:44 +08:00
|
|
|
|
|
|
|
|
## Run examples (Qwen3-Omni)
|
|
|
|
|
|
2025-12-03 11:25:58 +08:00
|
|
|
### Launch the Server
|
|
|
|
|
|
2025-11-30 18:20:44 +08:00
|
|
|
```bash
|
|
|
|
|
vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
If you have custom stage configs file, launch the server with command below
|
|
|
|
|
```bash
|
|
|
|
|
vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091 --stage-configs-path /path/to/stage_configs_file
|
|
|
|
|
```
|
|
|
|
|
|
2025-12-03 11:25:58 +08:00
|
|
|
### Send Multi-modal Request
|
|
|
|
|
|
2025-11-30 18:20:44 +08:00
|
|
|
Get into the example folder
|
|
|
|
|
```bash
|
2025-12-01 16:01:54 +08:00
|
|
|
cd examples/online_serving/qwen3_omni
|
2025-11-30 18:20:44 +08:00
|
|
|
```
|
|
|
|
|
|
2025-12-03 11:25:58 +08:00
|
|
|
#### Send request via python
|
|
|
|
|
|
2025-11-30 18:20:44 +08:00
|
|
|
```bash
|
2025-11-30 21:30:17 +08:00
|
|
|
python openai_chat_completion_client_for_multimodal_generation.py --query-type use_image
|
2025-11-30 18:20:44 +08:00
|
|
|
```
|
|
|
|
|
|
2025-12-03 11:25:58 +08:00
|
|
|
The Python client supports the following command-line arguments:
|
|
|
|
|
|
|
|
|
|
- `--query-type` (or `-q`): Query type (default: `use_video`)
|
|
|
|
|
- Options: `text`, `use_audio`, `use_image`, `use_video`
|
|
|
|
|
- `--model` (or `-m`): Model name/path (default: `Qwen/Qwen3-Omni-30B-A3B-Instruct`)
|
|
|
|
|
- `--video-path` (or `-v`): Path to local video file or URL
|
|
|
|
|
- If not provided and query-type is `use_video`, uses default video URL
|
|
|
|
|
- Supports local file paths (automatically encoded to base64) or HTTP/HTTPS URLs
|
|
|
|
|
- Example: `--video-path /path/to/video.mp4` or `--video-path https://example.com/video.mp4`
|
|
|
|
|
- `--image-path` (or `-i`): Path to local image file or URL
|
|
|
|
|
- If not provided and query-type is `use_image`, uses default image URL
|
|
|
|
|
- Supports local file paths (automatically encoded to base64) or HTTP/HTTPS URLs
|
|
|
|
|
- Supports common image formats: JPEG, PNG, GIF, WebP
|
|
|
|
|
- Example: `--image-path /path/to/image.jpg` or `--image-path https://example.com/image.png`
|
|
|
|
|
- `--audio-path` (or `-a`): Path to local audio file or URL
|
|
|
|
|
- If not provided and query-type is `use_audio`, uses default audio URL
|
|
|
|
|
- Supports local file paths (automatically encoded to base64) or HTTP/HTTPS URLs
|
|
|
|
|
- Supports common audio formats: MP3, WAV, OGG, FLAC, M4A
|
|
|
|
|
- Example: `--audio-path /path/to/audio.wav` or `--audio-path https://example.com/audio.mp3`
|
|
|
|
|
- `--prompt` (or `-p`): Custom text prompt/question
|
|
|
|
|
- If not provided, uses default prompt for the selected query type
|
|
|
|
|
- Example: `--prompt "What are the main activities shown in this video?"`
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
For example, to use a local video file with custom prompt:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
python openai_chat_completion_client_for_multimodal_generation.py \
|
|
|
|
|
--query-type use_video \
|
|
|
|
|
--video-path /path/to/your/video.mp4 \
|
|
|
|
|
--prompt "What are the main activities shown in this video?"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
#### Send request via curl
|
|
|
|
|
|
2025-11-30 18:20:44 +08:00
|
|
|
```bash
|
2025-11-30 21:30:17 +08:00
|
|
|
bash run_curl_multimodal_generation.sh use_image
|
2025-11-30 18:20:44 +08:00
|
|
|
```
|
|
|
|
|
|
2025-12-03 11:25:58 +08:00
|
|
|
|
2025-11-30 18:20:44 +08:00
|
|
|
### FAQ
|
|
|
|
|
|
|
|
|
|
If you encounter error about backend of librosa, try to install ffmpeg with command below.
|
|
|
|
|
```
|
|
|
|
|
sudo apt update
|
|
|
|
|
sudo apt install ffmpeg
|
|
|
|
|
```
|
|
|
|
|
|
2025-12-17 17:19:56 +08:00
|
|
|
## Modality control
|
|
|
|
|
If you want to control output modalities, e.g. only output text, you can run the command below:
|
|
|
|
|
```bash
|
|
|
|
|
python openai_chat_completion_client_for_multimodal_generation.py \
|
|
|
|
|
--query-type use_image \
|
|
|
|
|
--modalities text
|
|
|
|
|
```
|
|
|
|
|
|
2025-11-30 18:20:44 +08:00
|
|
|
## Run Local Web UI Demo
|
|
|
|
|
|
|
|
|
|
This Web UI demo allows users to interact with the model through a web browser.
|
|
|
|
|
|
|
|
|
|
### Running Gradio Demo
|
|
|
|
|
|
2025-12-19 18:09:43 +08:00
|
|
|
The Gradio demo connects to a vLLM API server. You have two options:
|
|
|
|
|
|
|
|
|
|
#### Option 1: One-step Launch Script (Recommended)
|
|
|
|
|
|
|
|
|
|
The convenience script launches both the vLLM server and Gradio demo together:
|
2025-11-30 18:20:44 +08:00
|
|
|
|
|
|
|
|
```bash
|
2025-12-19 18:09:43 +08:00
|
|
|
./run_gradio_demo.sh --model Qwen/Qwen3-Omni-30B-A3B-Instruct --server-port 8091 --gradio-port 7861
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This script will:
|
|
|
|
|
1. Start the vLLM server in the background
|
|
|
|
|
2. Wait for the server to be ready
|
|
|
|
|
3. Launch the Gradio demo
|
|
|
|
|
4. Handle cleanup when you press Ctrl+C
|
|
|
|
|
|
|
|
|
|
The script supports the following arguments:
|
|
|
|
|
- `--model`: Model name/path (default: Qwen/Qwen3-Omni-30B-A3B-Instruct)
|
|
|
|
|
- `--server-port`: Port for vLLM server (default: 8091)
|
|
|
|
|
- `--gradio-port`: Port for Gradio demo (default: 7861)
|
|
|
|
|
- `--stage-configs-path`: Path to custom stage configs YAML file (optional)
|
|
|
|
|
- `--server-host`: Host for vLLM server (default: 0.0.0.0)
|
|
|
|
|
- `--gradio-ip`: IP for Gradio demo (default: 127.0.0.1)
|
|
|
|
|
- `--share`: Share Gradio demo publicly (creates a public link)
|
|
|
|
|
|
|
|
|
|
#### Option 2: Manual Launch (Two-Step Process)
|
|
|
|
|
|
|
|
|
|
**Step 1: Launch the vLLM API server**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
If you have custom stage configs file:
|
|
|
|
|
```bash
|
|
|
|
|
vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091 --stage-configs-path /path/to/stage_configs_file
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Step 2: Run the Gradio demo**
|
|
|
|
|
|
|
|
|
|
In a separate terminal:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
python gradio_demo.py --model Qwen/Qwen3-Omni-30B-A3B-Instruct --api-base http://localhost:8091/v1 --port 7861
|
2025-11-30 18:20:44 +08:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Then open `http://localhost:7861/` on your local browser to interact with the web UI.
|
|
|
|
|
|
2025-12-03 11:25:58 +08:00
|
|
|
The gradio script supports the following arguments:
|
2025-11-30 18:20:44 +08:00
|
|
|
|
2025-12-19 18:09:43 +08:00
|
|
|
- `--model`: Model name/path (should match the server model)
|
|
|
|
|
- `--api-base`: Base URL for the vLLM API server (default: http://localhost:8091/v1)
|
2025-11-30 18:20:44 +08:00
|
|
|
- `--ip`: Host/IP for Gradio server (default: 127.0.0.1)
|
|
|
|
|
- `--port`: Port for Gradio server (default: 7861)
|
2025-12-19 18:09:43 +08:00
|
|
|
- `--share`: Share the Gradio demo publicly (creates a public link)
|
2025-11-30 18:20:44 +08:00
|
|
|
|
|
|
|
|
## Example materials
|
|
|
|
|
|
|
|
|
|
??? abstract "gradio_demo.py"
|
|
|
|
|
``````py
|
2025-12-01 16:01:54 +08:00
|
|
|
--8<-- "examples/online_serving/qwen3_omni/gradio_demo.py"
|
2025-11-30 18:20:44 +08:00
|
|
|
``````
|
|
|
|
|
??? abstract "openai_chat_completion_client_for_multimodal_generation.py"
|
|
|
|
|
``````py
|
2025-12-01 16:01:54 +08:00
|
|
|
--8<-- "examples/online_serving/qwen3_omni/openai_chat_completion_client_for_multimodal_generation.py"
|
2025-11-30 18:20:44 +08:00
|
|
|
``````
|
2025-12-08 02:43:48 +08:00
|
|
|
??? abstract "qwen3_omni_moe_thinking.yaml"
|
|
|
|
|
``````yaml
|
|
|
|
|
--8<-- "examples/online_serving/qwen3_omni/qwen3_omni_moe_thinking.yaml"
|
|
|
|
|
``````
|
2025-11-30 18:20:44 +08:00
|
|
|
??? abstract "run_curl_multimodal_generation.sh"
|
|
|
|
|
``````sh
|
2025-12-01 16:01:54 +08:00
|
|
|
--8<-- "examples/online_serving/qwen3_omni/run_curl_multimodal_generation.sh"
|
2025-11-30 18:20:44 +08:00
|
|
|
``````
|
2025-12-22 21:29:40 +08:00
|
|
|
??? abstract "run_gradio_demo.sh"
|
|
|
|
|
``````sh
|
|
|
|
|
--8<-- "examples/online_serving/qwen3_omni/run_gradio_demo.sh"
|
|
|
|
|
``````
|