# sglang-omni: phục vụ AI đa phương thức hiệu năng cao — hướng dẫn cài đặt và dùng

> sglang-omni là runtime phục vụ nhiều mô hình AI đa phương thức, giọng nói và TTS theo kiến trúc nhiều giai đoạn. Công cụ phù hợp cho dev xây API hoặc hệ thống AI tương tác; cài đặt cần Python đúng phiên bản và phần cứng phù hợp, còn README chưa ghi đầy đủ quy trình cài đặt từng hệ điều hành.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-09-25 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/sglang-omni-phuc-vu-ai-da-phuong-thuc-2

sglang-omni là runtime Python hiệu năng cao để triển khai các hệ thống AI tương tác có nhiều giai đoạn xử lý, chẳng hạn nhận dạng giọng nói, suy luận ngôn ngữ, tổng hợp tiếng nói và tạo nội dung đa phương thức. Repo đứng giữa ứng dụng của bạn và nhiều loại mô hình, điều phối cách các giai đoạn trao đổi dữ liệu rồi mở dịch vụ qua API tương thích OpenAI.

Bạn nên xem repo này nếu đang xây trợ lý giọng nói, hệ thống ASR hoặc TTS, dịch giọng nói, chatbot có hình ảnh và âm thanh, hay dịch vụ AI cần phục vụ nhiều yêu cầu cùng lúc. Đây không phải công cụ kéo-thả dành cho người dùng cuối. Nó phù hợp hơn với lập trình viên, đội ML platform và doanh nghiệp muốn tự vận hành mô hình.

Điểm đáng giá nhất là sglang-omni không chỉ chạy một mô hình đơn lẻ. Nó tổ chức cả pipeline gồm tiền xử lý, encoder, engine sinh tự hồi quy, decoder, vocoder và các bộ tổng hợp. Repo hiện có khoảng 1.776 sao và 729 fork, dùng giấy phép Apache-2.0.

```repo
- repo | sgl-project/sglang-omni
- kind | Framework
- desc | Runtime Python để phục vụ mô hình đa phương thức, ASR, TTS, hội thoại giọng nói, tạo nhạc và nội dung hình ảnh qua API tương thích OpenAI.
- stars | 1.8k
- lang | Python
- license | Apache-2.0
```

## sglang-omni làm được gì

- **Phục vụ mô hình đa phương thức.** Runtime hỗ trợ các hệ thống vừa hiểu văn bản, hình ảnh, âm thanh vừa trả lời bằng văn bản hoặc âm thanh. Các hướng tích hợp được README nêu gồm Qwen3-Omni, MiniCPM-o 4.5, Ming-Omni và Ming-3.0-audio-flash.

- **Xây hội thoại giọng nói hai chiều theo thời gian thực.** MiniCPM-o 4.5, PersonaPlex và NemotronLabs VoiceChat có thể vừa nghe vừa nói qua `/v1/realtime`. Với MiniCPM-o, pipeline còn có thể nhận dữ liệu camera. Điều này phù hợp cho trợ lý giọng nói, tổng đài thử nghiệm hoặc ứng dụng tương tác liên tục.

- **Ghép pipeline ASR → LLM → TTS.** Bạn có thể kết hợp dịch vụ nhận dạng giọng nói, mô hình ngôn ngữ và tổng hợp tiếng nói thành một trợ lý hội thoại theo lượt hoặc dạng streaming. README nhắc tới voice activity detection, lịch sử hội thoại, điều phối lượt nói và khả năng ngắt lời.

- **Phục vụ TTS qua API thống nhất.** Nhiều mô hình speech generation được đưa ra qua `/v1/audio/speech`. Danh sách gồm Higgs Audio v3, MOSS-TTS, Fish Audio Drama 3, Fish Speech S2-Pro, Qwen3-TTS, Fun-CosyVoice3, Voxtral TTS, Ming-Omni-TTS, Ming-3.0-TTS, dots.tts và ZONOS2. Tính năng batch, streaming và voice phụ thuộc từng mô hình.

- **Nhận dạng và chép lời âm thanh.** Các mô hình Qwen3-ASR, Fun-ASR, ARK-ASR, Nemotron 3.5 ASR, Nemotron Transcribe, Ming-3.0-ASR, Whisper thử nghiệm và MOSS-Transcribe-Diarize hoạt động qua `/v1/audio/transcriptions`. MOSS-Transcribe-Diarize còn trả về nhãn người nói và mốc thời gian khi dùng định dạng `verbose_json`.

- **Phân tách người nói.** Nemotron 3 Diarization có thể xác định các khoảng thời gian của từng người nói trong tệp ghi âm hoặc luồng âm thanh trực tiếp. README cũng nêu hỗ trợ trường hợp nhiều người nói chồng lên nhau.

- **Dịch giọng nói.** Hy-SimulMT hỗ trợ hướng tiếng Trung nói sang văn bản tiếng Anh và tiếng Anh nói sang văn bản tiếng Trung, cùng các luồng dịch tệp và dịch thời gian thực. Model và endpoint cụ thể cần xem trong hướng dẫn của từng cookbook.

- **Tạo và chỉnh sửa hình ảnh, video.** LLaDA2.0-Uni hỗ trợ hiểu văn bản hoặc hình ảnh, tạo và chỉnh sửa hình ảnh. Cosmos3 Nano hỗ trợ hiểu và tạo nội dung đan xen, gồm các route cho hình ảnh, video và hành động.

- **Tạo nhạc.** MiniMax Music 3 nhận lời bài hát cùng mô tả để tạo bài hát stereo 32 kHz. Đây là hướng dùng phù hợp cho nguyên mẫu nội dung âm thanh hoặc công cụ sáng tạo nội bộ.

- **Điều phối tài nguyên theo từng giai đoạn.** Mỗi stage có scheduler phù hợp với kiểu tải của nó. Stage tự hồi quy có thể dùng scheduling của SGLang, còn tiền xử lý và vocoder streaming có vòng lặp nhẹ hơn. Thiết kế này giúp pipeline không bị ép chạy mọi phần theo cùng một kiểu.

- **Vận chuyển tensor giữa các stage.** Control plane điều phối request, còn data plane chuyển payload tensor qua shared memory, NCCL, NIXL và Mooncake. Đây là phần quan trọng khi bạn muốn phân bố pipeline trên nhiều tiến trình hoặc nhiều GPU.

- **Mở rộng theo topology.** Runtime quản lý topology pipeline, vòng đời stage, giao tiếp giữa stage và lớp tích hợp theo họ mô hình. Vì vậy đội phát triển có thể tập trung tích hợp model và tối ưu serving thay vì tự viết toàn bộ lớp điều phối.

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

- **Python:** `pyproject.toml` yêu cầu Python từ 3.11 trở lên và nhỏ hơn 3.13. Bạn cần chọn đúng phiên bản trong khoảng này.

- **Môi trường chạy:** README mô tả NVIDIA CUDA là backend mặc định và có độ bao phủ mô hình đầy đủ. Apple Silicon ở trạng thái thử nghiệm, trong đó Qwen3-ASR chạy qua Torch MPS trên macOS arm64. Intel GPU XPU được hỗ trợ cho nhiều model và backend được tự phát hiện.

- **Phần cứng:** nhu cầu GPU hoặc số lượng card phụ thuộc model. README cho biết hướng dẫn Intel XPU nêu rõ model nào cần bao nhiêu card, nhưng phần nội dung được cung cấp không đưa ra cấu hình GPU chung cho toàn bộ repo. Vì vậy bạn cần xem cookbook của model mình định chạy trước khi chuẩn bị máy.

- **Tài khoản hoặc API key:** README không nêu yêu cầu tài khoản hay API key chung cho runtime. Một số model có thể có yêu cầu riêng, nhưng tư liệu được cung cấp chưa nói rõ.

- **Mô hình:** bạn cần chọn model và đọc cookbook tương ứng. SGLang-Omni là runtime phục vụ model, không phải một model duy nhất đã bao gồm sẵn mọi khả năng.

- **Hệ điều hành:** README nêu macOS arm64 cho nhánh Apple Silicon thử nghiệm và hỗ trợ Intel Arc qua PyTorch XPU. README được cung cấp không liệt kê đầy đủ ma trận phiên bản hệ điều hành cho mọi backend.

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

```steps
- Chọn môi trường | Kiểm tra Python và phần cứng phù hợp với model
- Lấy mã nguồn | Clone repo và đi vào thư mục dự án
- Cài gói | Dùng lệnh cài phiên bản SGLang-Omni được README nêu
- Chọn model | Mở cookbook tương ứng với ASR, TTS hoặc ứng dụng cần chạy
- Khởi chạy dịch vụ | Dùng lệnh launch trong cookbook của model
```

### Kiểm tra Python và backend

Trước tiên, hãy mở Terminal hoặc PowerShell tại thư mục bạn muốn lưu mã nguồn. Tạo hoặc chọn môi trường Python có phiên bản phù hợp với yêu cầu `>=3.11,<3.13` trong `pyproject.toml`.

README chưa ghi một lệnh kiểm tra phiên bản Python cụ thể, cũng chưa ghi đầy đủ các bước tạo virtual environment cho từng hệ điều hành. Bạn không nên tự suy đoán cờ khởi chạy model từ tên repo. Hãy kiểm tra đúng cookbook sau khi chọn model.

Nếu dùng NVIDIA, hãy chuẩn bị backend CUDA vì đây là backend mặc định và có độ bao phủ model đầy đủ. Nếu dùng Apple Silicon, cần hiểu đây là đường chạy thử nghiệm cho Qwen3-ASR qua Torch MPS. Nếu dùng Intel Arc, backend XPU được tự phát hiện theo README.

### Lấy mã nguồn

Bạn có thể clone repo bằng lệnh Git phổ thông sau:

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

Lệnh đầu tải mã nguồn về máy. Lệnh thứ hai chuyển terminal vào thư mục dự án. Người mới thường chạy lệnh thứ hai ở một thư mục khác nên nhận lỗi không tìm thấy đường dẫn. Hãy kiểm tra terminal đang đứng trong thư mục có `pyproject.toml`, `README.md`, `sglang_omni/` và `examples/`.

### Cài gói Python

README cung cấp lệnh cài gói trên PyPI như sau:

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

Lệnh này dùng `uv pip` để cài đúng phiên bản `sglang-omni==0.2.0` và cho phép cài pre-release. README được cung cấp không ghi bước cài `uv`, không ghi lệnh cài từ mã nguồn và cũng không ghi một lệnh chung cho CUDA, ROCm, MUSA, NPU hay XPU.

Nếu lệnh báo lỗi, trước hết hãy kiểm tra bạn đang dùng Python trong khoảng mà `pyproject.toml` yêu cầu. Đừng đổi ngẫu nhiên sang Python mới hơn hoặc thấp hơn, vì có thể không thỏa điều kiện phiên bản. Các file `pyproject_cpu.toml`, `pyproject_musa.toml`, `pyproject_npu.toml`, `pyproject_rocm.toml` và `pyproject_xpu.toml` cho thấy repo có các hướng backend khác nhau, nhưng README được cung cấp chưa chép lệnh cài cụ thể cho từng file.

### Chọn cookbook cho model

Sau khi cài package, hãy chọn đúng cookbook trong repo hoặc tài liệu dự án. Ví dụ, Qwen3-ASR dành cho chép lời, Qwen3-TTS hoặc Fish Audio Drama 3 dành cho tổng hợp tiếng nói, MiniMax Music 3 dành cho tạo nhạc, còn MiniCPM-o dành cho tương tác đa phương thức và full-duplex.

README có các endpoint chính như `/v1/audio/speech`, `/v1/audio/transcriptions` và `/v1/realtime`, nhưng phần tư liệu được cung cấp không có lệnh launch cụ thể của từng model. Vì vậy README chưa ghi cách chạy hoàn chỉnh cho một model cụ thể trong nội dung này. Bạn cần mở cookbook tương ứng để lấy đúng tên model, tham số, số GPU và lệnh khởi động.

### Khởi chạy dịch vụ theo model

Khi đã chọn model, hãy dùng lệnh launch trong cookbook của model đó. Không nên lấy lệnh của Qwen3-ASR áp dụng cho TTS hoặc lấy cấu hình TTS áp dụng cho full-duplex, vì mỗi model có stage và yêu cầu tài nguyên khác nhau.

README mô tả API sau khi dịch vụ chạy, nhưng không cung cấp trong phần được gửi một đoạn lệnh `curl`, Python client hay tên process launch chung. Do đó, README chưa ghi đủ cách khởi chạy độc lập chỉ bằng các thông tin hiện có. Chỗ cần xem tiếp là các cookbook cho model và phần Installation trong tài liệu dự án.

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

Dấu hiệu thành công phụ thuộc model bạn chọn. Với dịch vụ TTS, hãy kiểm tra endpoint `/v1/audio/speech` theo cookbook. Kết quả mong đợi là audio được sinh ra; một số model hỗ trợ streaming, batch hoặc voice tùy khả năng của model.

Với ASR, kiểm tra endpoint `/v1/audio/transcriptions` bằng một tệp âm thanh theo hướng dẫn của model. Kết quả mong đợi là văn bản chép lời. Nếu dùng MOSS-Transcribe-Diarize với `response_format=verbose_json`, kết quả còn có thể bao gồm nhãn người nói và timestamp.

Với hội thoại full-duplex, kiểm tra endpoint `/v1/realtime`. Dấu hiệu đúng là hệ thống có thể tiếp nhận âm thanh, xử lý hội thoại và phát phản hồi theo luồng. Với MiniCPM-o, cookbook còn có thể hướng dẫn đưa camera input vào pipeline.

README không cung cấp màn hình kiểm tra chung, mã trạng thái HTTP mẫu hoặc output cố định cho toàn bộ model. Vì vậy hãy đối chiếu cả log khởi động, endpoint và định dạng kết quả trong cookbook cụ thể. Nếu model yêu cầu nhiều GPU, việc process khởi động nhưng không tạo được output có thể là dấu hiệu cấu hình tài nguyên chưa đúng.

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

### Chủ shop chép lời cuộc gọi và phân loại nội dung

Một chủ shop có thể dùng một model ASR được SGLang-Omni hỗ trợ để chuyển file ghi âm cuộc gọi thành văn bản qua `/v1/audio/transcriptions`. Sau đó, ứng dụng nội bộ có thể đưa văn bản vào bước phân loại riêng như “khách hỏi giá”, “khách cần đổi hàng” hoặc “khách phàn nàn”.

Prompt mẫu cho bước xử lý văn bản có thể là: “Tóm tắt nội dung cuộc gọi trong ba ý. Nêu sản phẩm khách hỏi, vấn đề cần xử lý và hành động tiếp theo.” Phần ASR thuộc khả năng của runtime; việc phân loại sau đó cần một mô hình hoặc ứng dụng xử lý tiếp.

### Nhân viên văn phòng tạo bản nháp từ giọng nói

Một nhân viên có thể ghi âm ý tưởng cuộc họp, gửi tệp vào endpoint transcription rồi dùng văn bản nhận được để tạo biên bản. Với MOSS-Transcribe-Diarize, dữ liệu còn có thể bao gồm người nói và mốc thời gian, hữu ích khi cần biết ai phát biểu phần nào.

Prompt mẫu là: “Chuyển nội dung này thành biên bản gồm quyết định, việc cần làm, người phụ trách và hạn hoàn thành. Nếu không có thông tin thì ghi rõ chưa xác định.” Cần kiểm tra quyền sử dụng bản ghi âm trước khi đưa vào hệ thống.

### Đội sản phẩm xây trợ lý chăm sóc khách hàng bằng giọng nói

Đội dev có thể ghép ASR, LLM và TTS thành pipeline streaming. Luồng cơ bản là nhận tiếng nói của khách, phát hiện lượt nói, chuyển thành văn bản, tạo câu trả lời rồi đọc lại bằng model TTS qua `/v1/audio/speech`.

Prompt mẫu cho trợ lý là: “Bạn là trợ lý hỗ trợ đơn hàng. Trả lời ngắn, xác nhận mã đơn trước khi đề xuất thay đổi, và chuyển người dùng sang nhân viên khi thiếu dữ liệu.” README cho biết runtime hỗ trợ conversation history, turn taking, voice activity detection và interruption trong cascade, nhưng chất lượng thực tế vẫn phụ thuộc model và cách đội dev tích hợp.

### Nhà sáng tạo làm bản nháp nhạc hoặc giọng đọc

Với MiniMax Music 3, người dùng có thể cung cấp lyrics và caption để tạo bài hát stereo 32 kHz. Ví dụ mô tả: “Bài hát pop nhẹ, tiết tấu vừa, không khí ấm áp, chủ đề khai trương cửa hàng nhỏ.” Kết quả là một bản nhạc được sinh theo khả năng của model.

Với TTS, đội nội dung có thể dùng các model được hỗ trợ để tạo giọng đọc cho video hướng dẫn hoặc bản nháp quảng cáo. Các tính năng voice cloning, streaming hay batch không giống nhau giữa các model, nên phải xem cookbook tương ứng trước khi đưa vào quy trình sản xuất.

> Chọn đúng model và đúng topology quan trọng không kém việc gọi đúng API.
>
> — Ông T

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

### Python không thỏa điều kiện phiên bản

Nếu package không cài được, hãy kiểm tra Python có nằm trong khoảng từ 3.11 đến dưới 3.13 hay không. `pyproject.toml` là nơi repo khai báo điều kiện này. Đừng vội sửa file dự án để bỏ qua giới hạn, vì các dependency có thể chưa hỗ trợ phiên bản bạn đang dùng.

### Dùng sai lệnh cài cho backend

CUDA là backend mặc định, còn Apple Silicon, Intel XPU và các biến thể khác có hướng riêng. README được cung cấp chưa đưa lệnh đầy đủ cho từng backend. Hãy đọc đúng hướng dẫn phần cứng và cookbook thay vì sao chép lệnh của một nền tảng khác.

### Model khởi động nhưng thiếu tài nguyên

Mỗi model có thể cần số lượng card và cách chia stage khác nhau. Đặc biệt với pipeline đa giai đoạn, lỗi có thể xuất hiện khi một stage không đủ bộ nhớ hoặc không kết nối được với stage khác. Kiểm tra yêu cầu phần cứng trong cookbook của model, nhất là hướng dẫn Intel XPU có nêu số card theo từng model.

### Gọi nhầm endpoint hoặc sai định dạng dữ liệu

TTS dùng `/v1/audio/speech`, transcription dùng `/v1/audio/transcriptions`, còn hội thoại realtime dùng `/v1/realtime`. Hãy dùng đúng endpoint và định dạng mà cookbook yêu cầu. Không nên giả định mọi model đều hỗ trợ cùng một bộ tham số như streaming, voice hoặc batch.

### Mong đợi tính năng không có ở model đã chọn

SGLang-Omni hỗ trợ nhiều model, nhưng capability không đồng nhất. Một model có thể tạo audio nhưng không hỗ trợ voice cloning; model khác có thể hỗ trợ streaming nhưng không có full-duplex. Đọc phần mô tả model trước khi thiết kế giao diện hoặc cam kết tính năng với người dùng.

```note
Âm thanh, hình ảnh và dữ liệu hội thoại có thể chứa thông tin riêng tư. README không nêu chính sách lưu trữ dữ liệu chung hay yêu cầu API key chung cho runtime. Hãy tự kiểm tra cấu hình model, quyền truy cập endpoint và chi phí hạ tầng trước khi đưa dịch vụ vào vận hành.
```

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

Nên chọn sglang-omni nếu bạn cần phục vụ mô hình đa phương thức hoặc giọng nói bằng một runtime có kiến trúc nhiều stage. Repo có phạm vi khá rộng: ASR, TTS, hội thoại full-duplex, dịch giọng nói, diarization, tạo nhạc, hình ảnh và video. API tương thích OpenAI giúp đội dev có một bề mặt tích hợp quen thuộc hơn, trong khi scheduler và transport được thiết kế cho pipeline phân tán.

Repo cũng phù hợp với đội muốn tối ưu serving ở cấp hệ thống. Bạn có thể quan tâm tới topology, vòng đời stage, inter-stage transport và scheduling thay vì chỉ chạy một script inference đơn giản. Giấy phép Apache-2.0 cũng thuận tiện cho nhiều dự án phát triển và tích hợp, nhưng vẫn cần tuân thủ điều kiện của repo và model liên quan.

Giới hạn lớn là độ phức tạp. Đây không phải lựa chọn nhẹ nhất nếu bạn chỉ cần chép một file âm thanh hoặc gọi một API TTS đơn giản. Bạn phải chọn model, hiểu backend, chuẩn bị tài nguyên và đọc cookbook riêng. README được cung cấp cũng chưa ghi đầy đủ quy trình cài đặt cho từng hệ điều hành, chưa có lệnh launch chung và chưa đưa cấu hình phần cứng tổng quát.

Nếu cần thử nhanh một mô hình duy nhất trên máy cá nhân, một thư viện inference chuyên biệt hoặc dịch vụ hosted có thể dễ bắt đầu hơn. Nếu cần xây nền tảng phục vụ nhiều model, streaming và pipeline tương tác, sglang-omni đáng để đánh giá. Cách an toàn là bắt đầu với một cookbook cụ thể, kiểm tra endpoint bằng dữ liệu thử nghiệm rồi mới mở rộng sang nhiều stage và nhiều GPU.

## 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. README không nêu chi phí vận hành, chi phí GPU, chi phí model hoặc điều khoản thương mại riêng; các khoản này cần kiểm tra theo hạ tầng và model bạn chọn.

### Có cần GPU NVIDIA không?

Không nhất thiết trong mọi trường hợp. README nêu NVIDIA CUDA là backend mặc định, Apple Silicon được hỗ trợ thử nghiệm cho Qwen3-ASR qua Torch MPS, còn Intel Arc được hỗ trợ qua PyTorch XPU cho nhiều model.

### Có chạy được trên Windows không?

Tư liệu được cung cấp không xác nhận ma trận hỗ trợ Windows. README chỉ nêu rõ các backend NVIDIA CUDA, Apple Silicon và Intel XPU, nên bạn cần kiểm tra hướng dẫn cài đặt cụ thể trước khi triển khai Windows.

### sglang-omni có cần API key không?

README không nêu yêu cầu API key chung cho runtime. Một model hoặc nguồn model riêng có thể có điều kiện khác, nhưng tư liệu hiện có chưa cung cấp thông tin đó.

### Có dùng được cho chép lời tiếng Việt không?

README xác nhận runtime phục vụ nhiều model ASR như Qwen3-ASR, Fun-ASR và các model khác, nhưng không nêu riêng chất lượng hoặc hỗ trợ tiếng Việt. Bạn cần xem ngôn ngữ mà model cụ thể hỗ trợ.

### Có thể dùng sglang-omni cho TTS streaming không?

Có, README cho biết nhiều model speech generation được phục vụ qua `/v1/audio/speech`, trong đó khả năng streaming thay đổi theo từng model. Bạn cần kiểm tra cookbook trước khi chọn model.

### sglang-omni khác gì so với chạy một model bằng script riêng?

sglang-omni là runtime nhiều stage, quản lý scheduler, topology, vòng đời stage, vận chuyển tensor và API serving. Vì vậy nó phù hợp với pipeline đa phương thức hoặc hệ thống tương tác, nhưng phức tạp hơn một script inference đơn lẻ.
