# Soup: fine-tune LLM bằng một lệnh — hướng dẫn cài đặt và dùng

> Soup là CLI Python giúp fine-tune, đánh giá, chat, xuất bản và triển khai mô hình ngôn ngữ bằng một file YAML. Công cụ hỗ trợ nhiều tác vụ như SFT, DPO, GRPO, PPO và QLoRA; cài đặt khá đơn giản nhưng phần training cần Python phù hợp và phần cứng đủ mạnh.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-10-21 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/soup-fine-tune-llm-bang-mot-lenh

Soup là một CLI Python giúp bạn fine-tune và post-train mô hình ngôn ngữ lớn bằng một file YAML và một lệnh. Công cụ gom nhiều việc thường gây rối như chọn batch size, quantization, phát hiện GPU, huấn luyện LoRA, đánh giá và xuất mô hình vào cùng một quy trình.

Soup phù hợp với lập trình viên mới làm quen với LLM, nhóm nhỏ muốn huấn luyện mô hình tại máy cá nhân, hoặc người làm sản phẩm cần thử nghiệm nhanh mà không muốn quản lý máy chủ GPU qua SSH. Điểm đáng giá nhất là QLoRA và layer streaming giúp chạy mô hình lớn trên phần cứng hạn chế. Tài liệu nêu khả năng fine-tune mô hình 8B trên GPU laptop 4 GB, nhưng layer streaming vẫn đang ở trạng thái BETA và cần tự kiểm tra với cấu hình cụ thể.

```repo
- repo | MakazhanAlpamys/Soup
- kind | CLI
- desc | Soup giúp fine-tune và post-train LLM bằng một file YAML, hỗ trợ QLoRA, DPO, GGUF, Web UI và GPU ít VRAM.
- stars | 11k
- lang | Python
- license | Apache-2.0
```

## Soup làm được gì

- **Fine-tune bằng một file YAML:** Bạn khai báo model, dữ liệu, số epoch, learning rate, LoRA và quantization trong `soup.yaml`. Sau đó chạy `soup train` thay vì tự nối nhiều thư viện và script.

- **Hỗ trợ nhiều phương pháp post-training:** Soup có các tác vụ SFT, DPO, GRPO, PPO, KTO, ORPO, SimPO, IPO và BCO. Bạn có thể bắt đầu bằng SFT cho dữ liệu hỏi đáp, rồi chuyển sang preference training khi đã có cặp câu trả lời tốt và chưa tốt.

- **QLoRA và quantization:** Cấu hình `4bit` giúp giảm lượng VRAM cần thiết khi huấn luyện. README ghi mức tham khảo là 8 GB VRAM cho mô hình 7B với QLoRA, còn mức thực tế phụ thuộc model, sequence length, batch size và phương pháp huấn luyện.

- **Layer streaming:** Base model đóng băng được đưa lên GPU theo từng decoder layer thay vì giữ toàn bộ trong VRAM. Đây là lý do Soup có thể thử huấn luyện model lớn hơn trên GPU laptop ít bộ nhớ. Tính năng này phải bật bằng `stream_layers: true`, đang ở BETA và cần kiểm tra kết quả.

- **Tự động hóa các thiết lập quan trọng:** Soup có thể tự xử lý batch size, phát hiện GPU và quantization trong quy trình training. Điều này giảm số lượng tham số người mới phải tự đoán.

- **Làm việc với nhiều định dạng dữ liệu:** Công cụ tự nhận diện Alpaca, ShareGPT, ChatML, preference pairs cho DPO, ORPO, SimPO, IPO, KTO, cùng dữ liệu vision, audio, ASR, plaintext, embedding và RAFT. Nguồn có thể là JSONL, JSON, CSV, Parquet hoặc TXT.

- **Chat, infer và dựng API:** Sau khi train, bạn có thể chat tương tác, chạy batch inference từ file JSONL hoặc chạy server tương thích OpenAI. Nhờ vậy model đã fine-tune có thể được thử nghiệm trước khi tích hợp vào ứng dụng.

- **Web UI cục bộ:** `soup ui` mở dashboard trên máy để thiết lập training, xem metric trực tiếp, khám phá dataset và chat với model. Người không thích dùng toàn bộ CLI có thể thao tác qua trình duyệt.

- **Xuất model cho công cụ khác:** Soup hỗ trợ merge LoRA vào base model và export sang GGUF cho Ollama hoặc llama.cpp. Tài liệu cũng nêu thêm các đích xuất như ONNX, TensorRT và BitNet.

- **Kiểm tra môi trường và ước tính phần cứng:** `soup doctor` kiểm tra GPU, tài nguyên hệ thống, dependency và version. `soup profile --model <id>` ước tính model có vừa phần cứng hay không dựa trên các tham số như sequence length, batch, phương pháp, LoRA rank và optimizer.

- **Recipe có sẵn:** `soup recipes list` liệt kê hơn 100 recipe cho các họ model phổ biến. Điều này giúp bạn bắt đầu nhanh hơn thay vì tự tìm toàn bộ cấu hình từ đầu.

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

Bạn cần Python 3.11, 3.12 hoặc 3.13. Dự án khai báo yêu cầu `Python >=3.11,<3.14`; Python 3.14 trở lên chưa được hỗ trợ vì stack PyTorch chưa được kiểm chứng.

Để training thực tế, nên có GPU CUDA. Soup cũng hỗ trợ Apple Silicon qua MPS. CPU có thể chạy để kiểm thử nhưng rất chậm. README đưa mức tham khảo tối thiểu là 8 GB VRAM cho model 7B với QLoRA. Các model lớn hơn cần nhiều VRAM hơn; bảng tham khảo ghi khoảng 16 GB cho 14B, 24 GB cho 34B, 48 GB cho 70B và 80 GB trở lên cho model 70B+ hoặc MoE.

Bạn cần cài thêm training stack nếu muốn chạy `soup train`. Bản light chỉ có CLI, cấu hình và công cụ dữ liệu, không có PyTorch. Extra `[train]` bao gồm các thành phần training như torch, transformers, peft, trl và datasets. Nếu muốn dùng Web UI, cần extra `[ui]`; nếu muốn dùng toàn bộ tính năng, có extra `[all]`.

Bạn cũng cần dữ liệu training phù hợp với task. README cho phép trỏ `data.train` tới file JSONL, JSON, CSV, Parquet hoặc TXT. Với model trên Hugging Face Hub, Soup hỗ trợ các model text-generation có thể tải bằng `AutoModelForCausalLM`.

Nếu dùng model hoặc dataset yêu cầu quyền truy cập riêng, README được cung cấp ở đây chưa ghi chi tiết quy trình cấp quyền hay biến môi trường tương ứng. Hãy xem thêm `docs/models.md` và tài liệu của model trước khi chạy.

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

```steps
- Chuẩn bị Python | Dùng Python 3.11, 3.12 hoặc 3.13 và chọn cách cài phù hợp
- Cài Soup | Cài bản light, bản training hoặc toàn bộ extra
- Tạo cấu hình | Dùng wizard hoặc template để tạo soup.yaml
- Chuẩn bị dữ liệu | Trỏ data.train tới file dữ liệu đúng định dạng
- Huấn luyện và thử model | Chạy train, chat, infer hoặc UI
```

### Chuẩn bị môi trường Python

Mở Terminal, PowerShell hoặc shell trong môi trường bạn muốn dùng. Nếu bạn đang ở máy Linux có Python hệ thống được quản lý bởi `apt`, README khuyên dùng `pipx` hoặc `uv tool`. Nếu đang ở virtualenv, Colab hoặc Docker image, bạn có thể dùng `pip`.

Kiểm tra phiên bản Python trước khi cài:

```bash
python --version
```

Phiên bản cần nằm trong khoảng 3.11 đến 3.13. Nếu dùng Windows, hãy mở terminal sau khi cài Python và kiểm tra lệnh `python` có trỏ đúng phiên bản hay chưa.

### Cài Soup

Bản nhẹ chỉ cài CLI, config và công cụ dữ liệu:

```bash
pipx install soup-cli
uv tool install soup-cli          # same idea, if you already use uv
```

Nếu mục tiêu là fine-tune, cài thêm training stack:

```bash
pipx install "soup-cli[train]"
```

Nếu muốn có training, serving, UI và data tools trong một lần cài:

```bash
pipx install "soup-cli[all]"
```

Nếu đã ở trong virtualenv, Colab hoặc Docker image, dùng `pip`:

```bash
pip install soup-cli
pip install "soup-cli[train]"
pip install "soup-cli[all]"
```

Bạn cũng có thể cài bản phát triển mới nhất từ GitHub:

```bash
pipx install "git+https://github.com/MakazhanAlpamys/Soup.git"
pip install git+https://github.com/MakazhanAlpamys/Soup.git
```

Giữ dấu ngoặc kép quanh `soup-cli[train]`. README ghi đây là cách viết hoạt động trong `cmd.exe`, PowerShell, bash và zsh. Nếu gặp lỗi `externally-managed-environment`, đừng cố ghi vào Python hệ thống. Có thể dùng `pipx`, `uv tool`, hoặc tạo virtualenv rồi chạy pip trong đó:

```bash
python3 -m venv .venv && source .venv/bin/activate
```

Lệnh trên dùng cú pháp shell Unix. Trên Windows, hãy dùng cách tạo và kích hoạt virtualenv phù hợp với shell đang sử dụng.

### Tạo file cấu hình

Sau khi cài xong, chạy wizard tương tác:

```bash
soup init
```

Hoặc tạo cấu hình từ template chat:

```bash
soup init --template chat
```

Các template được README liệt kê gồm `chat`, `code`, `tool-calling`, `medical`, `reasoning`, `vision`, `kto`, `orpo`, `simpo`, `ipo`, `bco`, `rlhf`, `pretrain`, `moe`, `longcontext`, `embedding` và `audio`.

Bạn cũng có thể tạo một `soup.yaml` tương tự cấu hình mẫu sau:

```yaml
base: meta-llama/Llama-3.1-8B-Instruct
task: sft
# backend: unsloth  # 2-5x faster, pip install "soup-cli[fast]"

data:
  train: ./data/train.jsonl
  format: alpaca
  val_split: 0.1

training:
  epochs: 3
  lr: 2e-5
  batch_size: auto
  lora:
    r: 64
    alpha: 16
  quantization: 4bit

output: ./output
```

`base` là model nền, `task: sft` là kiểu training, còn `data.train` trỏ tới dữ liệu. `batch_size: auto` để Soup tự xử lý theo thiết lập của nó. Từ phiên bản được README mô tả, key không hợp lệ sẽ bị từ chối. Vì vậy, lỗi chính tả như `quantizaton` không còn bị bỏ qua âm thầm.

### Huấn luyện model

Chạy training với file cấu hình:

```bash
soup train --config soup.yaml                 # LoRA, quantization, batching — all handled
```

Lệnh cần được chạy ở thư mục chứa `soup.yaml`, hoặc bạn phải truyền đúng đường dẫn tới file. Nếu file dữ liệu nằm ở `./data/train.jsonl`, đường dẫn này được tính từ thư mục hiện tại.

Sau khi training xong, output mẫu là `./output`. Bạn có thể chat với model:

```bash
soup chat  --model ./output
```

Bạn cũng có thể chạy batch inference:

```bash
soup infer  --model ./output --input prompts.jsonl --output results.jsonl
```

### Dùng Web UI hoặc Docker

Nếu đã cài extra UI, chạy:

```bash
pip install "soup-cli[ui]"
soup ui
```

Soup sẽ mở dashboard cục bộ tại URL dạng `http://127.0.0.1:7860/?token=<token>` và in cùng URL trong terminal. Tính năng này phù hợp khi bạn muốn xem metric, khám phá dữ liệu và chat bằng trình duyệt.

Nếu không muốn cài CUDA hoặc PyTorch trực tiếp, README cung cấp image Docker:

```bash
docker pull ghcr.io/makazhanalpamys/soup:latest
docker run --gpus all -v $(pwd):/workspace ghcr.io/makazhanalpamys/soup train --config soup.yaml --yes
docker compose up   # or build locally
```

Lệnh Docker cần GPU và Docker được cấu hình để nhận GPU. Cú pháp `$(pwd)` là cú pháp shell; trên Windows, bạn cần điều chỉnh cách mount thư mục theo shell Docker đang dùng.

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

Kiểm tra nhanh môi trường bằng:

```bash
soup doctor
```

README cho biết lệnh này kiểm tra GPU, tài nguyên hệ thống, dependency và version. Nếu lệnh báo lỗi CUDA hoặc version mismatch, xem `docs/backends-and-ops.md`.

Kiểm tra CLI đã nhận được lệnh bằng cách tạo cấu hình:

```bash
soup init --template chat
```

Nếu wizard tạo được `soup.yaml`, phần CLI và config đã hoạt động. Sau đó chạy:

```bash
soup train --config soup.yaml
```

Kết quả mong đợi là quá trình training sử dụng cấu hình đã khai báo và ghi model vào thư mục `output` nếu bạn dùng cấu hình mẫu. Với test tự động, README cung cấp các lệnh sau:

```bash
pytest tests/ -v
pytest tests/ -m smoke -v
pytest tests/ -m gpu --no-cov -v
```

Test unit không cần GPU. Smoke test tải một model nhỏ và train thử. GPU test cần card CUDA.

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

### Chủ shop muốn chatbot trả lời đúng giọng thương hiệu

Chủ shop có thể chuẩn bị dữ liệu hỏi đáp theo format Alpaca trong `data/train.jsonl`, chẳng hạn các câu hỏi về phí vận chuyển, đổi trả và bảo hành. Tạo cấu hình bằng `soup init --template chat`, đặt `format: alpaca`, rồi chạy:

```bash
soup train --config soup.yaml
soup chat --model ./output
```

Kết quả là một model LoRA đã được fine-tune để thử nghiệm trong hội thoại. Nếu cần chạy nhiều câu hỏi cùng lúc, dùng `soup infer` với file `prompts.jsonl` và lưu kết quả vào `results.jsonl`.

### Nhân viên văn phòng muốn thử trợ lý nội bộ trên máy cá nhân

Nhân viên có thể gom các cặp câu hỏi và câu trả lời mẫu thành dữ liệu ChatML hoặc ShareGPT. Nếu máy có GPU phù hợp, dùng QLoRA 4-bit trong `soup.yaml` để giảm yêu cầu bộ nhớ. Sau đó chạy `soup chat --model ./output` để kiểm tra câu trả lời trước khi đưa vào ứng dụng.

Nếu chưa biết model có vừa GPU hay không, dùng:

```bash
soup profile --model <id>
```

Có thể thêm các tham số được README hỗ trợ như `--seq`, `--batch`, `--method`, `--lora-r`, `--optimizer` và `--gradient-checkpointing` để ước tính sát hơn.

### Lập trình viên muốn đóng gói model cho Ollama hoặc llama.cpp

Sau khi training, lập trình viên có thể merge adapter vào base model:

```bash
soup merge --adapter ./output
```

Sau đó export sang GGUF:

```bash
soup export --model ./output --format gguf --quant q4_k_m
```

Kết quả là model ở định dạng phù hợp cho Ollama hoặc llama.cpp theo mô tả trong README. Hãy kiểm tra lại model sau khi export bằng cách chat hoặc chạy inference.

### Nhóm nhỏ muốn chạy API nội bộ

Sau khi có model trong `./output`, chạy server tương thích OpenAI:

```bash
soup serve --model ./output
```

Ứng dụng nội bộ có thể gọi server theo giao thức tương thích OpenAI. Nếu bật xác thực bằng `--tool-auth-token`, token phải dài từ 16 đến 128 ký tự và chỉ dùng chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch ngang; nếu không, lệnh sẽ thoát với mã 2.

> Một file YAML đủ để biến dữ liệu riêng thành một model có thể thử nghiệm ngay trên máy của bạn.
>
> — Ông T

```note
Training model có thể dùng nhiều VRAM, thời gian và dung lượng lưu trữ. Không đưa dữ liệu riêng tư hoặc khóa truy cập vào file cấu hình khi chưa kiểm tra quyền truy cập. Telemetry của Soup là opt-in, mặc định tắt; nếu bật bằng SOUP_TELEMETRY=1, hãy xem chính sách riêng tư của dự án.
```

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

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

Nếu đang dùng Python 3.10 hoặc 3.14 trở lên, quá trình cài hoặc dependency có thể không phù hợp. Hãy chuyển sang Python 3.11, 3.12 hoặc 3.13 rồi cài lại trong môi trường riêng.

### Gặp lỗi externally-managed-environment

Đây là cơ chế của một số bản Debian và Ubuntu ngăn `pip` ghi vào Python hệ thống. Dùng `pipx`, `uv tool`, hoặc tạo virtualenv rồi chạy pip bên trong môi trường đó. Không nên ép ghi đè Python do hệ điều hành quản lý.

### Thiếu training stack hoặc PyTorch

Nếu cài bản `soup-cli` light rồi chạy `soup train`, các gói training có thể chưa có. Cài lại với extra:

```bash
pip install "soup-cli[train]"
```

Nếu dùng GPU, kiểm tra thêm bằng `soup doctor` và xem `docs/backends-and-ops.md` khi có lỗi CUDA hoặc version mismatch.

### GPU không đủ VRAM

Giảm kích thước model hoặc dùng QLoRA 4-bit. Có thể chạy `soup profile --model <id>` để ước tính trước. Layer streaming có thể giảm áp lực VRAM nhưng đang BETA; hãy kiểm tra kết quả và tính đúng đắn trước khi dùng cho công việc quan trọng.

### Config bị từ chối vì key không hợp lệ

Soup không còn bỏ qua key lạ. Kiểm tra chính tả và đối chiếu schema trong `config/schema.py` cùng tài liệu trong `docs/`. Ví dụ, `quantizaton` sẽ bị từ chối thay vì âm thầm chạy mà không áp dụng quantization.

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

Soup đáng thử nếu bạn muốn một quy trình fine-tune tương đối gọn, chạy local, dùng YAML thay cho nhiều script rời rạc và có sẵn đường đi từ dữ liệu đến model, chat, API hoặc GGUF. Số liệu repo hiện có khoảng 10.516 sao và 1.738 fork, giấy phép Apache-2.0, đồng thời dự án vẫn còn được cập nhật.

Điểm mạnh là phạm vi tính năng rộng, hỗ trợ nhiều task training, nhiều format dữ liệu, GPU CUDA, Apple Silicon, Docker, Web UI và các công cụ kiểm tra phần cứng. Layer streaming đặc biệt hữu ích khi bạn chỉ có GPU laptop ít VRAM, nhưng không nên xem đó là cam kết rằng mọi model 8B đều chạy tốt trên mọi máy 4 GB.

Giới hạn chính là training LLM vẫn cần phần cứng, dữ liệu và thời gian. CPU chỉ phù hợp để test và rất chậm. Các tính năng nâng cao có thể cần extra riêng, còn cấu hình mới có thể thay đổi quy tắc giữa các bản phát hành. Trước khi nâng cấp server hoặc task SFT, nên đọc release notes và chạy `soup doctor --config soup.yaml` theo hướng dẫn README.

Bạn nên chọn Soup nếu muốn thử nghiệm hoặc xây pipeline post-training local có nhiều khả năng trong một CLI. Nếu chỉ cần chạy inference đơn giản, một runtime chuyên dụng có thể nhẹ hơn. Nếu cần một nền tảng training production đã được kiểm định nghiêm ngặt theo hạ tầng cụ thể, hãy đánh giá thêm công cụ phù hợp với quy trình vận hành, bảo mật và phần cứng của đội bạn.

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

### Soup có miễn phí không?

README cho biết Soup dùng giấy phép Apache-2.0 và miễn phí. Tuy nhiên, chi phí GPU, lưu trữ, model, dữ liệu hoặc dịch vụ bên ngoài không được tính vào phần mềm.

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

Không bắt buộc cho mọi thao tác. Soup có thể chạy training trên CPU để kiểm thử nhưng rất chậm; training thực tế nên dùng GPU CUDA hoặc Apple Silicon MPS.

### Máy Windows có chạy được không?

README ghi cách viết gói có dấu ngoặc kép hoạt động trong PowerShell và cmd.exe. Tài liệu được cung cấp chưa nêu đầy đủ ma trận hỗ trợ Windows cho CUDA, Docker hoặc từng backend, nên cần kiểm tra môi trường bằng `soup doctor`.

### Có thể fine-tune model 8B trên GPU 4 GB không?

README mô tả layer streaming có thể fine-tune model 8B trên GPU laptop 4 GB và đưa số đo cụ thể cho một RTX 3050 Laptop 4 GB. Tính năng này đang BETA, nên khả năng chạy thực tế còn phụ thuộc model, cấu hình và dữ liệu.

### Soup hỗ trợ những loại model nào?

Soup hỗ trợ model text-generation trên Hugging Face Hub nếu model tải được bằng `AutoModelForCausalLM`. README cũng liệt kê nhiều họ model có recipe sẵn như Llama, Qwen, Gemma, Mistral, DeepSeek và Phi.

### Dữ liệu training có an toàn không?

README nêu Soup làm việc local và telemetry là opt-in, mặc định tắt. Tài liệu được cung cấp chưa đưa ra cam kết bảo mật cho mọi dữ liệu hoặc cấu hình, nên bạn vẫn cần tự kiểm soát file, quyền truy cập, model và server.

### Có thể xuất model sang GGUF không?

Có. Sau khi training, bạn có thể merge adapter bằng `soup merge --adapter ./output`, rồi dùng `soup export --model ./output --format gguf --quant q4_k_m` để xuất cho Ollama hoặc llama.cpp.
