# SGLang-Omni: chạy mô hình giọng nói và đa phương thức nhanh — hướng dẫn cài đặt và dùng

> SGLang-Omni là một runtime phục vụ (serving) mã nguồn mở, giúp bạn chạy các mô hình nói, nghe, tạo nhạc, tạo ảnh và hội thoại đa phương thức thành một máy chủ có API giống OpenAI. Gói Python tên sglang-omni, cài bằng một lệnh uv pip. Cài gói thì dễ, nhưng chạy mô hình thật cần GPU và làm theo hướng dẫn riêng của từng mô hình trong Cookbook.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-06-11 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/sglang-omni-chay-mo-hinh-giong-noi-da-phuong-thuc

SGLang-Omni là một runtime (phần mềm chạy nền) mã nguồn mở, dùng để phục vụ các mô hình AI về giọng nói và đa phương thức: đọc văn bản thành tiếng, chuyển giọng nói thành chữ, trò chuyện bằng giọng nói theo thời gian thực, tạo nhạc, tạo ảnh. Nó nằm trong hệ sinh thái SGLang và đưa các mô hình đó ra ngoài bằng API tương thích OpenAI, nên ứng dụng của bạn gọi vào như gọi một dịch vụ AI bình thường.

Nếu bạn là lập trình viên hoặc người phụ trách kỹ thuật ở một công ty nhỏ, muốn tự dựng dịch vụ đọc văn bản (TTS), chép lời cuộc họp (ASR) hoặc trợ lý giọng nói chạy trên máy chủ của mình thay vì thuê API ngoài, đây là repo đáng xem. Nếu bạn chỉ muốn một công cụ bấm là dùng, repo cũng có Voxt, một ứng dụng nhập liệu bằng giọng nói cho máy Mac, sẽ nói ở phần dưới.

Điểm đáng giá nhất là cách nó chia việc: một câu trả lời bằng giọng nói đi qua nhiều công đoạn (tiền xử lý, mô hình ngôn ngữ, bộ giải mã, vocoder…), mỗi công đoạn cần kiểu tính toán khác nhau. SGLang-Omni xếp mỗi công đoạn vào một bộ lập lịch phù hợp. Cần nói rõ: repo này không dành cho người chưa từng chạy mô hình AI. Cài gói thì dễ, nhưng chạy mô hình thật cần GPU và cần làm theo hướng dẫn riêng của từng mô hình.

```repo
- repo | sgl-project/sglang-omni
- kind | Framework
- desc | SGLang-Omni là runtime mã nguồn mở để chạy mô hình giọng nói, TTS, ASR, đa phương thức qua API tương thích OpenAI, tận dụng SGLang để chạy nhanh.
- stars | 1.8k
- lang | Python
- license | Apache-2.0
```

## SGLang-Omni làm được gì

Theo README, repo hiện có khoảng 1771 sao và 726 fork, giấy phép Apache-2.0. Các khả năng chính như sau.

### Chạy nhiều công đoạn như một dây chuyền

Một mô hình giọng nói thường không phải một khối duy nhất mà là chuỗi công đoạn. Runtime điều phối các công đoạn này: tiền xử lý, bộ mã hóa, mô hình sinh tự hồi quy, bộ "talker", bộ giải mã, vocoder và bộ gộp kết quả. Lợi ích thực tế là công đoạn nặng không phải chờ công đoạn nhẹ, nên phản hồi nhanh hơn.

### Mỗi công đoạn có bộ lập lịch riêng

Phần sinh văn bản/token dùng bộ lập lịch của SGLang. Phần tiền xử lý nhẹ và vòng lặp vocoder phát trực tiếp dùng bộ lập lịch gọn hơn. Bạn không phải tự tối ưu từng chỗ.

### Chuyển dữ liệu giữa các công đoạn

Một lớp điều khiển lo việc nhận yêu cầu, còn lớp dữ liệu chuyển tensor giữa các công đoạn qua shared-memory, NCCL, NIXL hoặc Mooncake. Với người mới, bạn chỉ cần biết: nếu sau này chạy trên nhiều GPU, repo đã tính sẵn đường chuyển dữ liệu.

### API quen thuộc kiểu OpenAI

README liệt kê các điểm cuối (endpoint) sau:

- chat đa phương thức
- `/v1/audio/speech` để tạo giọng nói, hỗ trợ cả theo lô, phát trực tiếp và giọng tải lên
- `/v1/audio/transcriptions` để chép lời
- `/v1/realtime` để trò chuyện hai chiều thời gian thực

Ngoài ra có `/generate` cho một số mô hình như AuK.

### Danh sách mô hình khá rộng

- **Hội thoại đa phương thức:** Qwen3-Omni, MiniCPM-o 4.5, Ming-Omni.
- **Hội thoại song công (vừa nghe vừa nói):** MiniCPM-o 4.5, PersonaPlex, NemotronLabs VoiceChat.
- **Đọc văn bản thành tiếng (TTS):** Higgs Audio v3, MOSS-TTS, Fish Audio Drama 3, Qwen3-TTS, Fun-CosyVoice3 và nhiều mô hình khác.
- **Chép lời (ASR):** Qwen3-ASR, Fun-ASR, Nemotron, Whisper (đang ở mức thử nghiệm).
- **Tách người nói:** Nemotron 3 Diarization.
- **Dịch giọng nói:** Hy-SimulMT, hỗ trợ Trung → Anh và Anh → Trung.
- **Tạo nhạc:** MiniMax Music 3, nhập lời bài hát và mô tả để ra bài hát stereo.
- **Ảnh và video:** LLaDA2.0-Uni, Cosmos3 Nano.

README cũng nói bạn có thể ghép ASR → LLM → TTS thành trợ lý giọng nói theo lượt, có phát hiện giọng nói, lịch sử hội thoại và cho phép ngắt lời.

### Voxt cho máy Mac

Trong repo có thư mục Voxt, một công cụ nhập liệu bằng giọng nói mã nguồn mở cho Mac. Nó dùng SGLang-Omni để nhận dạng giọng nói tại chỗ trên chip Apple Silicon, có thể kết hợp mô hình ngôn ngữ để chỉnh văn bản. README cho biết có cả chế độ chạy hoàn toàn nội bộ lẫn chạy từ xa.

## Cần chuẩn bị gì

Tư liệu của repo nói những điều sau, mình không thêm gì ngoài đó.

- **Python:** file `pyproject.toml` yêu cầu Python từ 3.11 đến dưới 3.13 (tức 3.11 hoặc 3.12).
- **Phần cứng mặc định:** GPU NVIDIA với CUDA. Đây là nền tảng được hỗ trợ đầy đủ mô hình nhất.
- **Intel Arc (XPU):** được hỗ trợ cho nhiều mô hình, backend tự nhận diện. Mỗi mô hình cần bao nhiêu card thì xem hướng dẫn Intel XPU của dự án.
- **Apple Silicon:** mức thử nghiệm. Qwen3-ASR chạy qua Torch MPS trên macOS arm64, cài bằng `install.sh`.
- **Công cụ cài đặt:** README dùng `uv pip`, nên bạn cần có sẵn công cụ `uv`.
- **Tài khoản, API key:** README không yêu cầu key nào để cài runtime. Mỗi mô hình có thể cần tải trọng số từ nơi khác (ví dụ Hugging Face), chi tiết nằm trong trang Cookbook của mô hình đó.
- **Windows:** README chưa nói gì về Windows. Nếu bạn dùng Windows, hãy đọc trang Installation của dự án trước khi bắt tay vào.

```note
Mô hình giọng nói và đa phương thức thường nặng. Trước khi tải, hãy xem trang Cookbook của mô hình để biết cần bao nhiêu GPU. Nếu chạy trên thuê máy đám mây, nhớ tắt máy khi xong để khỏi mất tiền oan.
```

## Cài đặt từng bước

```steps
- Kiểm tra môi trường | Có Python 3.11 hoặc 3.12, GPU phù hợp và công cụ uv
- Cài gói | Chạy lệnh uv pip install cho sglang-omni phiên bản 0.2.0
- Chọn mô hình | Mở trang Cookbook của mô hình bạn muốn chạy
- Khởi động máy chủ | Làm theo lệnh khởi chạy ghi trong Cookbook
- Gọi thử API | Gửi yêu cầu tới endpoint tương ứng, ví dụ /v1/audio/speech
```

### Kiểm tra Python và công cụ uv

Mở terminal (trên Linux hoặc Mac là ứng dụng Terminal) và kiểm tra phiên bản Python. Phải là 3.11 hoặc 3.12, vì bản 3.13 trở lên bị loại bởi `pyproject.toml`.

```bash
python3 --version
uv --version
```

Nếu máy chưa có `uv`, README chưa hướng dẫn cài. Bạn xem trang Installation của dự án (có trong phần trang chủ) để biết cách chuẩn bị.

### Tạo môi trường riêng (nên làm)

Tạo môi trường ảo để không làm lộn xộn Python của máy. Bước này không nằm trong README nhưng là thói quen an toàn với `uv`.

```bash
uv venv --python 3.12
source .venv/bin/activate
```

Lệnh thứ hai kích hoạt môi trường trên Linux/Mac. Sau khi kích hoạt, dòng lệnh thường hiện thêm tên môi trường ở đầu. Nếu bạn quên bước này, mọi thứ vẫn chạy nhưng gói sẽ cài vào Python chung.

### Cài gói sglang-omni

Đây là lệnh có trong README. Tên gói là `sglang-omni`, và cờ `--prerelease=allow` cho phép `uv` chọn các gói phụ thuộc ở dạng bản thử, nên đừng bỏ cờ này.

```bash
uv pip install --prerelease=allow "sglang-omni==0.2.0"
```

Chỗ người mới hay vấp: phải gõ cả dấu ngoặc kép quanh `sglang-omni==0.2.0`. Việc tải có thể mất một lúc vì phụ thuộc khá nặng.

Nếu bạn muốn lấy mã nguồn về để đọc ví dụ hoặc tự sửa, dùng lệnh git phổ thông:

```bash
git clone https://github.com/sgl-project/sglang-omni.git
cd sglang-omni
```

Trong thư mục có `install.sh` (README nhắc đến cho trường hợp Apple Silicon) và các file `pyproject_*.toml` cho CPU, ROCm, XPU, NPU, MUSA. README chưa ghi cách dùng từng file này, nên bạn xem thư mục `docs/` hoặc trang Installation trước khi đoán mò.

### Chọn mô hình và khởi động máy chủ

README chính không ghi sẵn lệnh khởi chạy, vì mỗi mô hình có lệnh riêng, số GPU riêng. Bạn vào trang Cookbook của mô hình mình chọn (ví dụ Qwen3-ASR để chép lời, hoặc Higgs Audio v3 để đọc văn bản) và chép đúng lệnh ở đó. Mình không tự bịa lệnh ở đây để tránh bạn chạy sai cờ.

Trong repo cũng có thư mục `examples/` và `docs/`, đáng mở ra xem nếu bạn thích đọc mã.

### Gọi thử API

Khi máy chủ chạy, bạn gọi vào các endpoint kiểu OpenAI đã nêu: `/v1/audio/speech` cho tạo giọng nói, `/v1/audio/transcriptions` cho chép lời. Các tham số cụ thể (tên mô hình, giọng, định dạng) khác nhau theo từng mô hình, nên hãy chép ví dụ trong Cookbook tương ứng. Một vài tính năng như theo lô, phát trực tiếp, giọng tải lên chỉ có ở một số mô hình.

## Kiểm tra đã chạy được chưa

README chính không ghi một lệnh kiểm tra riêng cho toàn hệ thống. Cách kiểm tra thực tế gồm ba mức:

- **Cài gói thành công:** lệnh `uv pip install` kết thúc không báo lỗi. Bạn có thể gõ `uv pip list` và tìm dòng `sglang-omni`.
- **Máy chủ lên:** sau khi chạy lệnh khởi động từ Cookbook, terminal không báo lỗi và giữ nguyên ở trạng thái đang chạy (không thoát ngay).
- **Có kết quả thật:** gọi endpoint theo ví dụ Cookbook. Với TTS, bạn nhận được file âm thanh nghe được. Với ASR, bạn nhận được đoạn chữ khớp với file ghi âm bạn gửi.

Nếu một trong ba mức thất bại, xem phần lỗi thường gặp ở dưới.

## Dùng vào việc thật

Dưới đây là bốn tình huống bám đúng những gì README nói repo làm được. Phần lệnh cụ thể bạn lấy từ Cookbook của mô hình tương ứng.

> Đừng hỏi "mô hình nào mạnh nhất", hãy hỏi "mô hình nào vừa GPU mình đang có" rồi mới đọc Cookbook.
>
> — Ông T

### Dựng giọng đọc cho chatbot của cửa hàng

**Bối cảnh:** bạn là dev của một shop online, muốn chatbot trả lời khách bằng giọng nói tự nhiên, chạy trên máy chủ riêng để không phụ thuộc dịch vụ ngoài.

**Cách làm:** chọn một mô hình TTS trong danh sách (ví dụ Higgs Audio v3 hoặc Qwen3-TTS), khởi động theo Cookbook, rồi cho ứng dụng gọi `/v1/audio/speech`. Vì API tương thích kiểu OpenAI, phần code phía ứng dụng đổi sang rất ít.

**Kết quả:** văn bản trả lời được đọc thành tiếng. Mô hình nào hỗ trợ phát trực tiếp thì khách nghe được ngay từ đoạn đầu, không phải chờ tạo xong cả file.

### Chép lời cuộc họp và tách người nói

**Bối cảnh:** nhân viên văn phòng có nhiều file ghi âm họp nội bộ, muốn có biên bản chữ và biết ai nói đoạn nào.

**Cách làm:** chạy một mô hình ASR như Qwen3-ASR và gửi file tới `/v1/audio/transcriptions`. README nói riêng MOSS-Transcribe-Diarize còn trả về nhãn người nói và mốc thời gian khi đặt `response_format=verbose_json`. Muốn chỉ tách người nói thì có Nemotron 3 Diarization.

**Kết quả:** văn bản chép lời kèm thông tin ai nói, vào lúc nào. Chất lượng với tiếng Việt thì README chưa có thông tin, bạn nên thử với file của mình trước khi tin hẳn.

### Làm trợ lý giọng nói theo lượt

**Bối cảnh:** một nhóm nhỏ muốn thử nghiệm tổng đài ảo, nơi khách nói và hệ thống trả lời bằng giọng.

**Cách làm:** ghép ASR → LLM → TTS thành chuỗi phát trực tiếp, như README mô tả, có phát hiện giọng nói, lịch sử hội thoại và ngắt lời. Nếu muốn nghe-nói đồng thời thì dùng các mô hình song công như MiniCPM-o 4.5 hoặc PersonaPlex qua `/v1/realtime`.

**Kết quả:** một cuộc hội thoại gần với nói chuyện thật, người dùng có thể ngắt lời giữa chừng. Đây là hướng đi dành cho dev, cần đọc kỹ hướng dẫn full-duplex của dự án.

### Nhập liệu bằng giọng nói trên Mac với Voxt

**Bối cảnh:** bạn dùng máy Mac chip Apple Silicon, hay soạn email, ghi chú và muốn đọc thay vì gõ.

**Cách làm:** README chỉ liên kết tải bản cài của Voxt, nằm ở mục Releases của repo. Voxt dùng nhận dạng giọng nói chạy tại máy, kết hợp mô hình ngôn ngữ để sửa văn bản theo gợi ý hệ thống cá nhân của bạn (hữu ích với thuật ngữ chuyên ngành). Bạn tải file `.dmg` về và cài như ứng dụng Mac thông thường.

**Kết quả:** văn bản đọc xong được chỉnh gọn. README khẳng định phiên bản 2.0 giảm 92% thời gian chờ sau khi đọc dài so với 1.x. Voxt không cần bạn dựng máy chủ như phần trên.

## Lỗi hay gặp và cách xử lý

README không có mục xử lý lỗi, nên các lỗi dưới đây là những chỗ rất dễ vướng với loại công cụ này. Mình không khẳng định thông báo lỗi cụ thể.

### Cài lỗi vì sai phiên bản Python

Nếu `uv` hoặc `pip` báo gói không tương thích, hãy kiểm tra Python. Dự án yêu cầu từ 3.11 đến dưới 3.13. Cách xử lý an toàn: tạo môi trường ảo mới với Python 3.12 rồi cài lại.

### Quên cờ cho phép bản thử

README dùng `--prerelease=allow`. Nếu bạn gõ lệnh cài mà bỏ cờ này, việc phân giải gói có thể thất bại. Hãy chép đúng nguyên lệnh trong README.

### Hết bộ nhớ GPU khi tải mô hình

Đây là lỗi rất dễ gặp với mô hình giọng nói và đa phương thức. Mỗi mô hình có yêu cầu số card riêng, ghi trong Cookbook (README nhắc rõ với Intel XPU). Cách khắc phục: chọn mô hình nhẹ hơn hoặc tăng số GPU theo hướng dẫn, đừng cố chạy mô hình quá sức máy.

### Máy chủ lên nhưng gọi API không ra kết quả

Có thể bạn gọi sai endpoint hoặc sai tham số. Không phải mô hình nào cũng hỗ trợ đủ tính năng: theo lô, phát trực tiếp, giọng tải lên đều khác nhau theo mô hình. Hãy đối chiếu với ví dụ trong trang Cookbook của đúng mô hình đó.

### Chạy trên Mac hoặc Windows không giống Linux

Backend mặc định là CUDA. Apple Silicon mới ở mức thử nghiệm và chỉ ghi rõ Qwen3-ASR. Nếu bạn không có GPU NVIDIA hoặc Intel, đừng kỳ vọng chạy được mọi mô hình trong danh sách. Hãy xem bảng phần cứng của README trước khi mất công cài.

## Có nên dùng không

**Điểm mạnh.** Phạm vi mô hình rất rộng, từ TTS, ASR, dịch giọng nói đến tạo nhạc và hội thoại thời gian thực, gói chung vào một runtime. API tương thích kiểu OpenAI giúp tích hợp dễ. Giấy phép Apache-2.0, repo vẫn được cập nhật trong vài tháng gần đây và có đội ngũ gắn với hệ sinh thái SGLang.

**Giới hạn.** Đây là hạ tầng cho người đã quen chạy mô hình AI, không phải ứng dụng bấm là dùng. README chính không ghi lệnh khởi chạy, bạn phải đi theo Cookbook từng mô hình. Phần cứng chính là GPU NVIDIA hoặc Intel Arc; Apple Silicon còn thử nghiệm. Chất lượng tiếng Việt của từng mô hình, README chưa có thông tin.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần chép lời hoặc đọc văn bản thỉnh thoảng, không có GPU, dịch vụ API thuê sẽ đơn giản hơn. Nếu bạn dùng Mac và chỉ muốn gõ bằng giọng nói, hãy thử thẳng Voxt. Còn nếu bạn muốn tự dựng dịch vụ giọng nói quy mô vừa, kiểm soát dữ liệu và chi phí, SGLang-Omni là lựa chọn đáng thử.

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

### SGLang-Omni có miễn phí không?

Repo dùng giấy phép Apache-2.0, là giấy phép mã nguồn mở cho phép dùng tự do. Tuy nhiên mỗi mô hình bạn tải về có thể có giấy phép riêng, README chưa tổng hợp việc này. Bạn nên kiểm tra giấy phép trên trang của từng mô hình.

### Cần GPU không?

Backend mặc định là NVIDIA CUDA và hỗ trợ đầy đủ mô hình nhất. Intel Arc (XPU) cũng được hỗ trợ cho nhiều mô hình. Apple Silicon ở mức thử nghiệm với Qwen3-ASR. Số GPU cần cho từng mô hình ghi trong Cookbook.

### Chạy được trên Windows không?

README chưa có thông tin về Windows. Bạn nên đọc trang Installation của dự án trước khi cài. Với Mac chip Apple Silicon, README có nhắc dùng install.sh cho Qwen3-ASR.

### Cài đặt bằng lệnh nào?

README ghi: uv pip install --prerelease=allow "sglang-omni==0.2.0". Yêu cầu Python từ 3.11 đến dưới 3.13. Sau khi cài, bạn khởi động từng mô hình theo trang Cookbook tương ứng.

### Dữ liệu của tôi có an toàn không?

Bạn tự chạy máy chủ nên âm thanh và văn bản đi qua máy của bạn. README chưa có phần nói riêng về bảo mật. Riêng Voxt, README nói có chế độ chạy hoàn toàn nội bộ hoặc suy luận từ xa, tuỳ bạn chọn.

### Khác gì SGLang thường?

SGLang là engine chạy mô hình ngôn ngữ nhanh. SGLang-Omni phụ trách phần điều phối nhiều công đoạn của mô hình giọng nói và đa phương thức, rồi kết hợp với SGLang để chạy phần sinh tự hồi quy khi phù hợp. Nó cũng cung cấp API kiểu OpenAI cho giọng nói, chép lời và hội thoại thời gian thực.

### Có hỗ trợ tiếng Việt không?

README chưa có thông tin về tiếng Việt cho từng mô hình. Bạn nên thử mô hình đã chọn với dữ liệu tiếng Việt của mình rồi mới triển khai thật.
