# 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 giai đoạn cho mô hình đa phương thức, speech và TTS, với API tương thích OpenAI. Repo phù hợp để dựng dịch vụ ASR, tạo giọng nói, hội thoại âm thanh, tạo nhạc hoặc xử lý ảnh/video. Cài đặt cần Python đúng phiên bản và phần cứng phù hợp; README có lệnh cài gói nhưng cách chạy cụ thể phụ thuộc model trong Cookbook.

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

SGLang-Omni là runtime Python dùng để phục vụ các hệ thống AI đa phương thức, speech và text-to-speech qua những pipeline nhiều giai đoạn. Thay vì chỉ chạy một model đơn lẻ, nó điều phối các bước như tiền xử lý, encoder, model sinh tự hồi quy, decoder, vocoder và bộ tổng hợp kết quả.

Repo này dành cho đội kỹ thuật muốn dựng dịch vụ AI có âm thanh, hình ảnh hoặc video, cũng như người làm sản phẩm cần thử nhanh các tính năng ASR, TTS, hội thoại giọng nói và tạo nhạc. Giá trị lớn nhất là một lớp phục vụ thống nhất với các endpoint tương thích OpenAI, trong khi việc lập lịch và truyền dữ liệu giữa các giai đoạn được thiết kế cho workload khác nhau.

Repo hiện có khoảng 1.776 sao và 729 fork, viết chủ yếu bằng Python, dùng giấy phép Apache-2.0. Đây là một framework hạ tầng hơn là ứng dụng bật lên dùng ngay cho người không kỹ thuật: bạn cần chọn model, đọc cookbook tương ứng và chuẩn bị phần cứng phù hợp.

```repo
- repo | sgl-project/sglang-omni
- kind | Framework
- desc | Runtime Python phục vụ mô hình đa phương thức, giọng nói, TTS, ASR, tạo nhạc và tương tác thời gian thực.
- 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 qua một runtime chung

SGLang-Omni hỗ trợ các hệ thống nhận và tạo nhiều loại dữ liệu như văn bản, âm thanh, hình ảnh và video. Bạn có thể dùng nó cho chatbot nhìn ảnh, trợ lý giọng nói, xử lý video hoặc pipeline kết hợp nhiều model.

Thiết kế nhiều giai đoạn giúp mỗi phần chạy theo cách phù hợp với công việc của nó. Phần tiền xử lý nhẹ không nhất thiết phải dùng cùng kiểu scheduler với model tự hồi quy hoặc vocoder streaming.

### Cung cấp API tương thích OpenAI

Runtime có các bề mặt API cho multimodal chat, tạo speech, tạo speech theo lô, speech streaming, voice đã tải lên và transcription. Lợi ích thực tế là ứng dụng phía khách hàng có thể gọi dịch vụ theo cách quen thuộc với hệ sinh thái API tương thích OpenAI.

Tuy nhiên, endpoint và tham số cụ thể thay đổi theo model. Bạn cần xem cookbook của model mình chọn trước khi viết client, vì không phải model nào cũng có cùng tính năng streaming, voice hay định dạng đầu ra.

### Chạy ASR và transcription

SGLang-Omni phục vụ nhiều model chuyển âm thanh thành văn bản qua `/v1/audio/transcriptions`. Danh sách được README nêu gồm Qwen3-ASR, Fun-ASR, ARK-ASR, Nemotron 3.5 ASR, Nemotron Transcribe, Ming-3.0-ASR, Whisper ở trạng thái thử nghiệm và MOSS-Transcribe-Diarize.

MOSS-Transcribe-Diarize còn có thể trả nhãn người nói và mốc thời gian khi dùng `response_format=verbose_json`. Đây là nền tảng hữu ích cho biên bản họp, tổng hợp cuộc gọi hoặc phân tích bản ghi âm có nhiều người.

### Tạo giọng nói và phát trực tiếp

Nhiều model TTS được phục vụ qua `/v1/audio/speech`, gồm Higgs Audio v3, MOSS-TTS, Fish Audio Drama 3, Qwen3-TTS, Fun-CosyVoice3, Voxtral TTS, ZONOS2 và nhiều model khác. Tùy model, bạn có thể có đầu ra theo lô, streaming hoặc các tính năng liên quan đến voice.

Fish Audio Drama 3 được README mô tả là hỗ trợ speech nhiều người, voice cloning và điều khiển bằng ngôn ngữ tự nhiên. Với người làm nội dung, điều này mở ra hướng tạo đoạn hội thoại hoặc bản đọc có nhiều vai, nhưng quyền sử dụng giọng và dữ liệu tham chiếu vẫn cần được kiểm tra riêng.

### Xây dựng hội thoại full-duplex

MiniCPM-o 4.5, PersonaPlex và NemotronLabs VoiceChat hỗ trợ hội thoại native full-duplex qua `/v1/realtime`. Hệ thống có thể vừa nghe vừa nói trong phiên tương tác trực tiếp; MiniCPM-o còn có đường xử lý camera.

Ngoài model full-duplex, runtime cũng hỗ trợ cascade ASR → LLM → TTS. Cascade có thể kết hợp phát hiện hoạt động giọng nói, lịch sử hội thoại, quản lý lượt nói và ngắt lời. Đây là cách phù hợp khi bạn muốn ghép các model chuyên biệt thay vì dùng một model hội thoại âm thanh duy nhất.

### Tạo và chỉnh sửa ảnh, video, nhạc

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

MiniMax Music 3 nhận lyrics cùng caption để tạo bài hát stereo 32 kHz. Đây là khả năng đáng chú ý cho thử nghiệm nội dung âm nhạc, nhưng README không cung cấp chi tiết về giới hạn bản quyền, hạn mức sử dụng hay chi phí model.

### Điều phối dữ liệu giữa nhiều giai đoạn

Một control plane điều phối request, còn data plane chuyển tensor giữa các stage. README nêu các backend truyền dữ liệu gồm shared memory, NCCL, NIXL và Mooncake.

Cách tổ chức này phù hợp với hệ thống mà các stage có nhu cầu tài nguyên khác nhau. Đội kỹ thuật có thể mở rộng model integration, benchmark, scheduler hoặc topology mà không phải gom toàn bộ pipeline vào một tiến trình duy nhất.

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

Bạn cần Python từ 3.11 đến trước 3.13. Thông tin này được khai báo trong `pyproject.toml`, vì vậy nên kiểm tra phiên bản Python trước khi cài.

Bạn cần một môi trường chạy phù hợp với model. NVIDIA CUDA là backend mặc định và có độ bao phủ model đầy đủ theo README. Intel Arc GPU được hỗ trợ qua PyTorch XPU; backend này tự phát hiện và cookbook của Intel có hướng dẫn số card cần cho từng model.

Apple Silicon ở trạng thái thử nghiệm. README nêu Qwen3-ASR có thể chạy qua Torch MPS trên macOS arm64 và hướng dẫn dùng `install.sh` cùng cookbook Qwen3-ASR.

Bạn cần chọn model cụ thể trước khi triển khai. Mỗi model có thể có yêu cầu riêng về GPU, số card, model weights, endpoint và khả năng streaming. README tổng quan không nói rằng mọi model chạy được trên mọi loại phần cứng.

README không nêu yêu cầu API key bắt buộc cho bản thân runtime. README cũng không cung cấp thông tin chung về chi phí, giới hạn request, nơi lưu model weights hoặc chính sách dữ liệu. Nếu triển khai cho dữ liệu khách hàng, bạn cần tự kiểm tra cấu hình lưu trữ, log và quyền truy cập của môi trường chạy.

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

```steps
- Kiểm tra Python | Bảo đảm phiên bản nằm trong khoảng được repo yêu cầu
- Lấy mã nguồn | Clone repo và chuyển vào thư mục dự án
- Cài gói | Cài bản sglang-omni được README nêu
- Chọn cookbook | Chọn model và backend phù hợp với phần cứng
- Khởi chạy theo model | Dùng lệnh trong cookbook tương ứng
```

### Kiểm tra phiên bản Python

Mở PowerShell hoặc terminal tại máy bạn sẽ dùng để chạy service. Kiểm tra Python trước để tránh cài vào phiên bản ngoài khoảng mà `pyproject.toml` cho phép.

```powershell
python --version
```

Kết quả cần là Python 3.11 hoặc 3.12. Nếu máy có nhiều bản Python, hãy bảo đảm lệnh `python` đang trỏ tới đúng bản trước khi cài. README không cung cấp lệnh đổi phiên bản Python trên từng hệ điều hành.

### Lấy mã nguồn

Bạn có thể clone repo rồi đi vào thư mục dự án. Đây là hai lệnh phổ thông để lấy mã nguồn và không phụ thuộc vào model cụ thể.

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

Bạn cần mở terminal ở thư mục mà mình có quyền ghi, vì môi trường cài đặt có thể tạo file cache hoặc metadata. Sau khi `cd`, hãy nhìn prompt terminal để chắc rằng bạn đang ở thư mục `sglang-omni`.

### Cài bản Python package được README nêu

README nêu bản `sglang-omni==0.2.0` trên PyPI và lệnh cài bằng `uv`. Chạy đúng lệnh sau trong terminal.

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

Tùy môi trường, `uv` có thể cần được cài sẵn; phần README được cung cấp không ghi lệnh cài `uv`. Nếu máy báo không nhận diện được `uv`, hãy xem tài liệu cài đặt trong repo hoặc trang hướng dẫn Installation của dự án. Không nên tự đổi tên package, bỏ cờ `--prerelease=allow` hoặc thay phiên bản nếu chưa kiểm tra yêu cầu của model bạn định chạy.

### Chọn model và backend

Sau khi cài package, hãy mở cookbook tương ứng với model. README liệt kê các nhóm cookbook như Qwen3-ASR, Qwen3-TTS, Fish Audio Drama 3, MiniCPM-o, PersonaPlex và MiniMax Music 3.

Ở bước này, bạn phải xác định model dùng endpoint nào, cần bao nhiêu GPU và có hỗ trợ streaming hay không. Với Intel XPU, README nói backend tự phát hiện; với Apple Silicon, đường thử nghiệm được mô tả cho Qwen3-ASR trên macOS arm64. Những thông tin này không thể suy ra chung cho toàn bộ model.

README tổng quan không chép một lệnh khởi chạy server dùng chung cho mọi model. Vì vậy, hãy dùng lệnh đúng trong cookbook của model đã chọn. Không nên lấy lệnh của TTS để chạy cho ASR hoặc tự thêm tham số chưa được cookbook nêu.

### Dùng script cài đặt cho Apple Silicon khi cookbook yêu cầu

README nêu người dùng Qwen3-ASR trên macOS arm64 cài với `install.sh` và làm theo hướng dẫn Qwen3-ASR. Repo có file `install.sh`, nhưng phần README được cung cấp không chép nội dung lệnh bên trong file.

Do đó, hãy xem chính file `install.sh` và cookbook liên quan trước khi chạy. Không tự đoán tham số hoặc đường dẫn. Đây cũng là trường hợp cần đặc biệt chú ý vì Apple Silicon đang được ghi là experimental.

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

Cách kiểm tra phụ thuộc model. Dấu hiệu đầu tiên là lệnh cài package hoàn tất mà không có lỗi dependency, sau đó lệnh khởi chạy trong cookbook tạo được service tương ứng.

Với ASR, kiểm tra bằng cách gửi một file âm thanh tới `/v1/audio/transcriptions` theo mẫu request của cookbook. Kết quả mong đợi là văn bản được nhận dạng; với MOSS-Transcribe-Diarize và định dạng `verbose_json`, kết quả còn có thể gồm nhãn người nói và timestamp.

Với TTS, kiểm tra endpoint `/v1/audio/speech` bằng request mẫu của model. Kết quả mong đợi là dữ liệu speech; khả năng streaming, batch, voice cloning hoặc điều khiển giọng phải đối chiếu riêng với model.

Với hội thoại realtime, dùng client theo hướng dẫn full-duplex và kiểm tra service có nhận âm thanh, phản hồi âm thanh hoặc camera input hay không. Không nên kết luận runtime đã chạy đúng chỉ vì process khởi động; cần thực hiện một request thật với model đã chọn.

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

### Chủ shop tạo bản đọc giới thiệu sản phẩm

Một chủ shop có nhiều mô tả sản phẩm và muốn tạo bản đọc bằng giọng nói có thể chọn một model TTS trong cookbook. Nội dung sản phẩm được gửi tới `/v1/audio/speech` theo request mẫu của model, sau đó nhận file hoặc luồng speech tùy khả năng model.

Prompt mẫu có thể là: `Đọc phần mô tả này với giọng rõ ràng, tốc độ vừa phải, nhấn nhẹ vào tên sản phẩm và giá bán: [nội dung]`. Kết quả phù hợp là đoạn âm thanh dùng cho video, gian hàng hoặc bản xem trước. README không khẳng định model nào có giọng tiếng Việt, nên bạn phải thử model cụ thể trước khi đưa vào quy trình bán hàng.

### Nhân viên văn phòng chuyển cuộc họp thành biên bản

Nhân viên có thể đưa bản ghi âm cuộc họp vào endpoint `/v1/audio/transcriptions` bằng model ASR phù hợp. Nếu cuộc họp có nhiều người, MOSS-Transcribe-Diarize có thể hữu ích vì README nói model này trả speaker labels và timestamps với `response_format=verbose_json`.

Sau đó, ứng dụng văn phòng có thể dùng văn bản và mốc thời gian để tạo biên bản, danh sách việc cần làm hoặc tra cứu đoạn phát biểu. Hãy kiểm tra độ chính xác trên tiếng địa phương, tiếng ồn và tên riêng trước khi dùng làm tài liệu chính thức.

### Dev xây trợ lý giọng nói có thể ngắt lời

Một dev muốn làm trợ lý nghe và nói trực tiếp có thể chọn MiniCPM-o 4.5, PersonaPlex hoặc NemotronLabs VoiceChat, rồi dùng `/v1/realtime` theo cookbook tương ứng. Những model này được README mô tả cho native full-duplex conversation.

Prompt hệ thống mẫu: `Bạn là trợ lý nội bộ. Trả lời ngắn, hỏi lại khi thiếu thông tin và dừng nói khi người dùng bắt đầu lượt mới.` Kết quả mong đợi là phiên tương tác có thể vừa nghe vừa nói. Việc nhận camera input chỉ được README nêu cho MiniCPM-o, nên không nên áp dụng giả định đó cho hai model còn lại.

### Đội nội dung thử nghiệm tạo nhạc từ lời bài hát

Đội nội dung có lyrics và ý tưởng phối khí có thể thử MiniMax Music 3. README mô tả luồng `lyrics + caption` tạo bài hát stereo 32 kHz thông qua `/v1/audio/speech`.

Caption mẫu có thể là: `Pop điện tử, nhịp vừa, không khí tích cực, điệp khúc dễ nhớ`. Kết quả là một bản nhạc để thử ý tưởng hoặc làm bản nháp. Trước khi phát hành, đội cần tự kiểm tra quyền sử dụng lyrics, giọng, dữ liệu tham chiếu và đầu ra; README không cung cấp chính sách bản quyền hay cam kết thương mại.

> Hãy chọn model theo đúng loại dữ liệu và phần cứng, rồi kiểm tra bằng một request thật trước khi đưa vào quy trình.
>
> — Ông T

```note
Âm thanh, voice clone, bản ghi họp và dữ liệu camera có thể chứa thông tin nhạy cảm. Hãy giới hạn quyền truy cập service, kiểm tra log và chỉ dùng dữ liệu mà bạn có quyền xử lý. README không nêu chính sách lưu trữ dữ liệu chung cho runtime.
```

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

### Python không đúng phiên bản

Nếu Python thấp hơn 3.11 hoặc từ 3.13 trở lên, package có thể không đáp ứng điều kiện trong `pyproject.toml`. Hãy cài hoặc chọn Python 3.11/3.12 trong môi trường riêng rồi chạy lại lệnh cài.

### Không nhận diện được lệnh uv

README dùng `uv pip install`, nhưng phần nội dung được cung cấp không ghi cách cài `uv`. Kiểm tra `uv` đã có trong PATH chưa và xem hướng dẫn Installation của repo để làm theo cách được dự án hỗ trợ. Đừng thay bằng một lệnh pip khác nếu chưa xác nhận dependency tương đương.

### Chọn model không phù hợp với phần cứng

NVIDIA CUDA là backend mặc định có độ bao phủ đầy đủ hơn. Apple Silicon chỉ được ghi là experimental cho Qwen3-ASR, còn Intel XPU có danh sách model và yêu cầu card riêng. Hãy đọc cookbook đúng model trước khi khởi chạy, thay vì giả định mọi model dùng chung một backend.

### Dùng sai endpoint hoặc tham số

ASR dùng `/v1/audio/transcriptions`, còn nhiều model tạo speech dùng `/v1/audio/speech`; hội thoại full-duplex dùng `/v1/realtime`. Endpoint đúng vẫn chưa đủ vì tham số và tính năng có thể khác theo model. Lấy request mẫu từ cookbook tương ứng.

### Service khởi động nhưng kết quả không đúng kỳ vọng

Process chạy được không có nghĩa model đã tải đúng hoặc pipeline đã xử lý đúng loại dữ liệu. Hãy kiểm tra bằng một audio, prompt hoặc request nhỏ theo ví dụ của cookbook, rồi xác nhận định dạng đầu ra. Nếu dùng voice cloning, camera hoặc streaming, hãy kiểm tra xem tính năng đó có được model cụ thể hỗ trợ hay không.

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

Nên dùng SGLang-Omni nếu bạn cần một runtime chung cho speech, TTS, ASR, multimodal chat, hội thoại realtime, tạo nhạc hoặc pipeline nhiều stage. Repo có phạm vi model rộng, API tương thích OpenAI và kiến trúc tách scheduler, transport, model integration cùng serving surface. Đây là nền tảng đáng xem cho đội xây hạ tầng inference thay vì chỉ chạy thử một model trong notebook.

Giới hạn lớn là việc dùng không hoàn toàn theo kiểu cài xong rồi bấm chạy. Bạn phải chọn model, đọc cookbook, xác định backend, GPU và endpoint. README tổng quan cũng không cung cấp một lệnh khởi chạy duy nhất, không nêu chung yêu cầu API key, chi phí, chính sách dữ liệu hoặc hiệu năng cho từng tình huống.

Nếu bạn chỉ cần chép một file âm thanh thành văn bản trên máy cá nhân, một công cụ ASR chuyên dụng có thể đơn giản hơn. Nếu bạn chỉ cần tạo một đoạn TTS nhỏ, dịch vụ API chuyên biệt có thể giảm công sức vận hành GPU. Còn nếu bạn cần phục vụ nhiều model tương tác, streaming và pipeline âm thanh đa giai đoạn, SGLang-Omni là lựa chọn phù hợp hơn để nghiên cứu và xây hệ thống lâu dài.

## 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 cung cấp thông tin chung về chi phí phần cứng, model weights, hạ tầng hoặc dịch vụ bên ngoài, nên chưa thể kết luận tổng chi phí sử dụng.

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

Không bắt buộc 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 và Intel Arc GPU được hỗ trợ qua PyTorch XPU; khả năng cụ thể phụ thuộc model.

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

README được cung cấp không nêu rõ Windows có được hỗ trợ hay không. Tài liệu chỉ nêu các backend NVIDIA CUDA, Apple Silicon trên macOS arm64 và Intel XPU.

### Có cần API key không?

README không nói API key là yêu cầu chung của SGLang-Omni. Từng model hoặc nguồn model có thể có yêu cầu riêng, nhưng phần tư liệu này chưa cung cấp thông tin đó.

### SGLang-Omni khác gì một thư viện ASR hoặc TTS đơn lẻ?

SGLang-Omni là runtime nhiều giai đoạn, phục vụ ASR, TTS, multimodal chat, hội thoại realtime, tạo nhạc và nhiều loại model. Nó còn điều phối scheduler, transport và API serving, thay vì chỉ thực hiện một tác vụ âm thanh.

### Có thể dùng để tạo voice clone không?

README nêu Fish Audio Drama 3 có voice cloning và điều khiển bằng ngôn ngữ tự nhiên. Tuy vậy, tư liệu không nói chi tiết về quy trình xin phép, giới hạn sử dụng hay chính sách dữ liệu của voice clone.

### Cài xong có một lệnh chạy chung cho mọi model không?

Không. README tổng quan cho biết endpoint và khả năng thay đổi theo model, đồng thời hướng người dùng tới cookbook tương ứng. Bạn cần dùng lệnh khởi chạy và request mẫu của model đã chọn.
