# Cài đặt & backend

Source: https://docs.vieneu.io/vi/docs/sdk/standard-mode

Một gói, hai engine. `Vieneu()` tự chọn engine theo phần cứng; API giống nhau trên cả hai.

| Bạn có | Engine | Cài | Ghi chú |
|---|---|---|---|
| Chỉ CPU, macOS | ONNX Runtime, **không cần torch** | `pip install vieneu` | v3 Turbo 48 kHz, có nhân bản giọng và thẻ cảm xúc. Không bao giờ cài PyTorch. |
| GPU NVIDIA | PyTorch (CUDA) | `pip install "vieneu[cuda]"` | Tự batch; từ 3.7.0 mỗi frame là một CUDA graph. |
| CPU yếu / bo ARM | ONNX, **v3 Nano** | `pip install vieneu` + `Vieneu(mode="v3nano")` | Nhanh ~3× so với Turbo fp32, 24 kHz, chất lượng thấp hơn (nhất là tiếng Anh). |

## CPU (mặc định) {#cpu-default}

```bash
pip install vieneu
```

```python
from vieneu import Vieneu

tts = Vieneu()                       # v3 Turbo, ONNX, fp32
audio = tts.infer("Xin chào bạn", voice="Minh Quân Pro")
tts.save(audio, "output.wav")        # WAV 48 kHz
```

- **Precision.** Mặc định `fp32` để giữ chất lượng cao nhất. `Vieneu(precision="int8")` nhanh hơn ~1,6× và nhỏ hơn ~4×, nhưng cần CPU có VNNI (AVX-512 VNNI / AVX-VNNI). CPU cũ chạy int8 có thể ra tiếng rè; gặp vậy thì quay về fp32 hoặc thử v3 Nano.
- **Cài CPU nhanh nhất.** Từ bản clone của repo, `uv sync` tái tạo đúng môi trường đã khoá với bản ONNX Runtime tối ưu. Đo được nhanh hơn `pip install` thường.
- **Apple Silicon.** Dùng đường CPU/ONNX. Với v3 Turbo nó nhanh hơn bản MPS/PyTorch.

## GPU (CUDA) {#gpu-cuda}

Trên Linux wheel torch từ PyPI đã kèm CUDA:

```bash
pip install "vieneu[cuda]"
```

Trên Windows cài torch CUDA **trước**, rồi transformers ghim bản, rồi vieneu:

```bash
pip install torch==2.8.0 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu128
pip install "transformers==4.57.6"
pip install vieneu
```

```python
tts = Vieneu()                       # thấy CUDA → engine PyTorch
tts = Vieneu(backend="onnx")         # ép dùng engine CPU trên máy có GPU
```

`precision` chỉ áp dụng cho đường ONNX, trên GPU bị bỏ qua. Số đo thông lượng và batch xem trang [Batch trên GPU](/docs/sdk/fast-mode).

## v3 Nano (bản xem trước) {#v3-nano-preview}

Mô hình flow-matching 48M tham số cho phần cứng mà Turbo quá chậm. Cùng API nhân bản, 11 giọng có sẵn, xuất 24 kHz, không stream theo frame (mỗi chunk trả về trọn).

```python
tts = Vieneu(mode="v3nano")
audio = tts.infer("Bản nhanh cho máy rất yếu.", voice="Ái Hân", steps=8, sway=-1)
```

Đo trên i7 thế hệ 12 để bàn, 6 luồng ONNX (RTF = thời gian tính ÷ thời lượng audio, càng thấp càng nhanh):

| Engine | RTF | Tần số mẫu | Tải |
|---|---|---|---|
| v3 Turbo fp32 (mặc định CPU) | 0,62 | 48 kHz | ~19 s |
| v3 Turbo int8 | 0,37 | 48 kHz | ~14 s |
| v3 Nano, 16 bước (mặc định) | 0,22 | 24 kHz | ~3 s |
| v3 Nano, 8 bước, sway −1 | 0,11 | 24 kHz | ~3 s |

Núm chỉnh: `steps` (mặc định 16, 8 ≈ nhanh 2×), `cfg` (mặc định 3,0; 0 giảm nửa tính toán nhưng khó nghe hơn), `speed`, `seed`, `threads`.

## Mô hình và cache {#models-and-cache}

Trọng số backbone và codec tải từ Hugging Face lần đầu dùng, cache ở `~/.cache/huggingface/hub/`. Đường nhân bản của Turbo chạy trên onnxruntime + soxr + kaldi-native-fbank; Nano tải thêm ba graph nhân bản (~110 MB) lần đầu bạn clone.

## Backend cũ (v1 / v2) {#legacy-backends-v1--v2}

Backend GGUF (llama-cpp) và LMDeploy chỉ phục vụ **VieNeu-TTS v1/v2**, không còn được cập nhật. Chúng nằm sau `uv sync --group gpu` trong repo và `pip install "vieneu[legacy]"`. Dự án mới nên ở lại v3 Turbo.