# Soup: fine-tune LLM chỉ với một file YAML, GPU 4 GB cũng chạy — hướng dẫn cài đặt và dùng

> Soup (gói soup-cli) là công cụ dòng lệnh giúp bạn fine-tune và hậu huấn luyện LLM chỉ với một file cấu hình YAML và lệnh soup train. Bạn có thể huấn luyện ngay trên GPU của mình bằng QLoRA, rồi chat thử, gộp LoRA hoặc xuất GGUF. Cài bằng pipx hoặc pip khá đơn giản, nhưng cần Python 3.11 đến 3.13 và nên có GPU NVIDIA.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-07-01 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/soup-fine-tune-llm-mot-file-yaml-gpu-4gb

Soup là một công cụ dòng lệnh viết bằng Python, dùng để fine-tune (huấn luyện tiếp) và hậu huấn luyện các mô hình ngôn ngữ lớn (LLM) chỉ bằng một file cấu hình YAML và một lệnh `soup train`. Thay vì tự ghép PyTorch, transformers, peft, trl và đủ thứ cấu hình, bạn khai báo mô hình gốc, file dữ liệu, rồi để Soup lo phần còn lại.

Bạn nên xem repo này nếu bạn là lập trình viên mới, dân kỹ thuật trong doanh nghiệp, hoặc người muốn thử "dạy" một mô hình mở theo dữ liệu riêng (chăm sóc khách hàng, tài liệu nội bộ, trả lời theo giọng thương hiệu…) mà không muốn thuê máy chủ hay SSH vào hộp GPU. Repo hiện có khoảng 10.500 sao và 1.700 fork, giấy phép Apache-2.0, và vẫn được cập nhật đều trong vài tháng gần đây.

Điểm đáng giá nhất là tính năng layer streaming: theo README, nó cho phép fine-tune model 8B trên GPU laptop chỉ 4 GB VRAM. Tính năng này còn ở mức BETA và phải bật thủ công, nhưng nó cho thấy hướng đi của dự án: làm cho việc huấn luyện LLM chạy được trên phần cứng bình thường.

```repo
- repo | MakazhanAlpamys/Soup
- kind | CLI
- desc | Soup là công cụ dòng lệnh Python để fine-tune LLM bằng một file YAML và vài lệnh, có chế độ layer streaming giúp model 8B chạy trên GPU laptop 4 GB.
- stars | 11k
- lang | Python
- license | Apache-2.0
```

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

Dưới đây là những phần chính, giải thích theo lợi ích thực tế.

**Một file YAML, một lệnh.** Bạn viết `soup.yaml` gồm mô hình gốc (`base`), loại tác vụ (`task`), đường dẫn dữ liệu, số epoch, learning rate, rồi gõ `soup train --config soup.yaml`. Việc xử lý LoRA, lượng tử hoá và chia batch do Soup làm. Bạn không phải viết script huấn luyện.

**Tự động nhiều thứ.** README nói batch size, nhận diện GPU và lượng tử hoá đều được xử lý tự động. Trong cấu hình mẫu, bạn chỉ cần ghi `batch_size: auto` và `quantization: 4bit`.

**Mẫu có sẵn để bắt đầu nhanh.** Lệnh `soup init --template chat` tạo cấu hình mẫu. Các mẫu README liệt kê gồm `chat`, `code`, `tool-calling`, `medical`, `reasoning`, `vision`, `kto`, `orpo`, `simpo`, `ipo`, `bco`, `rlhf`, `pretrain`, `moe`, `longcontext`, `embedding`, `audio`. Nếu chưa biết chọn gì, `chat` là điểm xuất phát hợp lý. Bạn cũng có thể gõ `soup init` không kèm gì để dùng trình hướng dẫn tương tác.

**Nhiều phương pháp huấn luyện.** Ngoài SFT thông thường, Soup hỗ trợ DPO, GRPO, PPO, KTO, ORPO, SimPO, IPO, BCO và nhiều thứ khác (tool-calling, pre-training, distillation, vision, audio…). Bạn không cần hiểu hết ngay. Chỉ cần biết khi nhu cầu lớn lên thì không phải đổi công cụ.

**Tự nhận định dạng dữ liệu.** Alpaca, ShareGPT, ChatML, cặp ưu tiên cho DPO, vision, audio… đều được tự phát hiện từ file JSONL, JSON, CSV, Parquet hoặc TXT. Thông thường bạn chỉ trỏ `data.train` vào file của mình.

**Layer streaming cho GPU yếu.** Mô hình gốc bị đóng băng được giữ ngoài VRAM và đưa vào GPU từng lớp decoder một. README đo trên RTX 3050 Laptop 4 GB với Llama-3.1-8B-Instruct dạng NF4: khoảng 3,32 GB VRAM đỉnh và 119,6 token/giây ở phép đo cũ, và 2,40 GB ở phép đo sau bản sửa lỗi trên một máy khác. Tác giả nói thẳng hai phép đo không so sánh trực tiếp được. Bật bằng `stream_layers: true`, và vẫn là BETA.

**Vòng đời đầy đủ sau huấn luyện.** `soup chat` để trò chuyện thử, `soup merge` để gộp LoRA vào mô hình gốc, `soup export` để xuất GGUF dùng với Ollama hoặc llama.cpp, `soup push` để đẩy lên Hugging Face, `soup serve` để mở server tương thích OpenAI.

**Giao diện web.** Nếu ngại terminal, `soup ui` mở bảng điều khiển trên máy bạn để xem thí nghiệm, số liệu huấn luyện, khám phá dữ liệu và chat với mô hình.

**Công cụ kiểm tra.** `soup doctor` kiểm tra GPU, tài nguyên hệ thống, thư viện phụ thuộc. `soup profile --model <id>` ước tính xem mô hình có vừa VRAM không, kể cả khi bạn chưa có file `soup.yaml`.

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

Chỉ liệt kê những gì README ghi:

- **Python 3.11, 3.12 hoặc 3.13.** Đây là các bản được CI kiểm thử. Python 3.14 trở lên chưa được hỗ trợ vì chồng PyTorch chưa được kiểm chứng ở đó. `pyproject.toml` cũng yêu cầu `>=3.11,<3.14`.
- **Phần cứng:** GPU có CUDA là khuyến nghị. Apple Silicon (MPS) cũng dùng được. CPU chỉ ở mức thử nghiệm và rất chậm.
- **VRAM:** README ghi cần 8 GB trở lên cho mô hình 7B với QLoRA. Bảng tham khảo: 8 GB cho khoảng 7B, 16 GB cho khoảng 14B, 24 GB cho khoảng 34B, 48 GB cho khoảng 70B. Với chế độ layer streaming thì 4 GB có thể đủ cho 8B, theo số đo của tác giả.
- **Trình cài:** `pipx` hoặc `uv tool` được khuyến nghị cho ứng dụng dòng lệnh. Nếu bạn đang ở trong virtualenv, Colab hoặc Docker thì dùng `pip`.
- **Dữ liệu huấn luyện:** một file JSONL, JSON, CSV, Parquet hoặc TXT của bạn.
- **Tài khoản/API key:** README phần được cung cấp không yêu cầu key bắt buộc cho việc huấn luyện cơ bản. Nếu bạn muốn `soup push` lên Hugging Face thì tất nhiên cần tài khoản ở đó. Một số mô hình gốc như Llama có thể yêu cầu bạn chấp nhận điều khoản trên Hugging Face, nhưng README không nói rõ điều này nên bạn hãy kiểm tra trang của mô hình.
- **Hệ điều hành:** README không có mục riêng liệt kê hệ điều hành, nhưng có nhắc cách gõ lệnh trong `cmd.exe`, PowerShell, bash và zsh, nên bạn có thể kỳ vọng nó dùng được trên Windows, macOS và Linux. Nếu cần chắc chắn, hãy xem `docs/backends-and-ops.md` trong repo.

```note
Huấn luyện LLM chiếm rất nhiều VRAM và điện. Trước khi chạy, hãy dùng soup doctor và soup profile để biết máy bạn có kham nổi không. Telemetry của Soup mặc định tắt, chỉ bật khi bạn đặt SOUP_TELEMETRY=1.
```

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

```steps
- Kiểm tra Python | Đảm bảo máy có Python 3.11 đến 3.13
- Cài Soup | Dùng pipx cài gói soup-cli kèm phần huấn luyện [train]
- Tạo cấu hình | Chạy soup init --template chat để có file soup.yaml mẫu
- Kiểm tra máy | Chạy soup doctor xem GPU và thư viện
- Huấn luyện | Chạy soup train --config soup.yaml
```

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

Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux) và xem phiên bản Python. Bạn cần 3.11, 3.12 hoặc 3.13.

```bash
python --version
```

Nếu máy bạn dùng 3.14 trở lên, hãy cài thêm một bản 3.11–3.13 trước. Đây là chỗ người mới hay vấp nhất.

### Cài Soup bằng pipx

Soup là ứng dụng dòng lệnh, nên cách sạch nhất là cho nó một môi trường riêng và đưa lệnh `soup` vào `PATH`. README đưa ra các cách sau:

```bash
# Bản nhẹ: CLI + cấu hình + công cụ dữ liệu, không có PyTorch
pipx install soup-cli
uv tool install soup-cli          # tương tự, nếu bạn đã dùng uv

# Thêm bộ công cụ huấn luyện (torch, transformers, peft, trl, datasets, …)
pipx install "soup-cli[train]"

# Cài tất cả (train + serve + ui + data) một lần
pipx install "soup-cli[all]"

# Hoặc từ GitHub (bản dev mới nhất)
pipx install "git+https://github.com/MakazhanAlpamys/Soup.git"
```

Bạn chỉ cần chọn MỘT dòng. Muốn fine-tune thì chọn `soup-cli[train]`. Bản nhẹ không có PyTorch nên chỉ dùng được `soup init`, `soup data …` và các lệnh kiểm tra dữ liệu. Hãy dùng dấu nháy kép, không dùng nháy đơn, vì nháy kép chạy được ở mọi shell.

### Hoặc cài bằng pip

Nếu bạn đang trong virtualenv, Colab hoặc Docker thì dùng `pip` với cùng tên gói:

```bash
pip install soup-cli
pip install "soup-cli[train]"
pip install "soup-cli[all]"
pip install git+https://github.com/MakazhanAlpamys/Soup.git
```

Dùng `pip` thay vì `pipx` nếu bạn còn muốn `import soup_cli` trong code của mình.

### Hoặc chạy bằng Docker

Nếu không muốn cài CUDA hay PyTorch lên máy, README có sẵn ảnh 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   # hoặc build tại máy
```

Lệnh `docker run` gắn thư mục hiện tại vào `/workspace`, nên file `soup.yaml` và dữ liệu phải nằm trong thư mục bạn đang đứng. Cách này cần Docker và hỗ trợ GPU (`--gpus all`) đã được cấu hình sẵn.

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

Đứng trong thư mục làm việc của bạn (thư mục sẽ chứa dữ liệu và kết quả), rồi chạy:

```bash
soup init                       # trình hướng dẫn tương tác
soup init --template chat       # hoặc bắt đầu từ mẫu
```

Sau đó mở `soup.yaml` bằng trình soạn thảo bất kỳ. README đưa ra ví dụ cấu hình đầy đủ như 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
```

Các chỗ cần sửa là `base` (mô hình gốc trên Hugging Face), `data.train` (đường dẫn file dữ liệu của bạn) và `output` (nơi lưu kết quả). Lưu ý: từ phiên bản 0.75, khoá cấu hình lạ hoặc gõ sai (ví dụ `quantizaton`) sẽ làm file không nạp được, thay vì bị lặng lẽ bỏ qua như trước.

### Chạy huấn luyện

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

`soup doctor` cho bạn xem GPU, tài nguyên, thư viện và phiên bản trong một chỗ. Nên chạy trước để biết máy có sẵn sàng không. `soup train` mới là lệnh bắt đầu huấn luyện. Lần đầu có thể mất thời gian tải mô hình gốc về.

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

Có ba dấu hiệu theo thứ tự từ dễ đến khó:

1. **`soup doctor` chạy ra báo cáo.** Nếu gõ `soup` mà máy báo không tìm thấy lệnh, hãy mở lại terminal để `PATH` được nạp lại. README không mô tả chi tiết màn hình kết quả, nhưng lệnh này sinh ra báo cáo về GPU, tài nguyên hệ thống, thư viện và phiên bản.
2. **`soup train --config soup.yaml` chạy và thư mục `output` xuất hiện.** Đó là nơi cấu hình mẫu lưu kết quả.
3. **Chat thử được với mô hình vừa huấn luyện:**

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

Nếu bạn trả lời được và câu trả lời mang dấu ấn của dữ liệu bạn đưa vào, thế là thành công. Muốn xem bằng giao diện đồ hoạ thì cài thêm phần UI rồi mở:

```bash
pip install "soup-cli[ui]"
soup ui
# Mở http://127.0.0.1:7860/?token=<token> và in ra cùng địa chỉ đó
```

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

### Chủ shop muốn chatbot trả lời đúng giọng cửa hàng

Bạn là chủ một shop online, có sẵn vài trăm đoạn hội thoại hỏi đáp với khách (đã ẩn thông tin cá nhân). Hãy xếp chúng thành file JSONL theo định dạng Alpaca hoặc ShareGPT, đặt vào `./data/train.jsonl`. Trước khi huấn luyện, xem thống kê dữ liệu:

```bash
soup data inspect ./data/train.jsonl
```

Sau đó tạo cấu hình mẫu `chat`, sửa `data.train`, chạy `soup train --config soup.yaml`, rồi thử bằng `soup chat --model ./output`. Kết quả là một mô hình nhỏ biết cách trả lời theo kiểu của shop bạn. Hãy đọc lại từng câu trả lời trước khi dùng thật với khách.

> Đừng đoán máy mình chạy nổi hay không, hãy hỏi máy trước khi bắt đầu.
>
> — Ông T

### Lập trình viên mới có laptop GPU 4 GB

Bạn muốn thử fine-tune model 8B nhưng chỉ có laptop 4 GB VRAM. Trước hết dùng công cụ ước tính để biết có vừa không (thay `<id>` bằng tên mô hình trên Hugging Face):

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

Lệnh này tính dựa trên `config.json` của mô hình, không cần có `soup.yaml`. Nếu cần tiết kiệm VRAM, bạn thêm `stream_layers: true` vào cấu hình để bật layer streaming. README ghi rõ đây là BETA và đã có người đo thành công trên RTX 3050 Laptop 4 GB. Đừng kỳ vọng tốc độ nhanh. Hãy xem nó như cách để chạy được thay vì không chạy được.

### Nhân viên văn phòng muốn mang mô hình sang Ollama

Sau khi huấn luyện xong, bạn muốn dùng mô hình đó trong Ollama hoặc llama.cpp trên máy cá nhân. Gộp LoRA vào mô hình gốc rồi xuất GGUF:

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

Định dạng GGUF với mức lượng tử q4_k_m cho file gọn, phù hợp chạy trên máy cá nhân. Từ đó bạn nạp nó vào công cụ chạy cục bộ mà bạn quen dùng.

### Nhóm dev dựng API nội bộ và chia sẻ mô hình

Nhóm bạn cần một endpoint để các ứng dụng khác gọi. Soup có lệnh mở server tương thích OpenAI, và lệnh đẩy mô hình lên Hugging Face để chia sẻ:

```bash
soup serve --model ./output
soup push  --model ./output --repo you/my-model
```

Thay `you/my-model` bằng tài khoản và tên repo của bạn. Nếu mở server cho nhiều người dùng, hãy đọc phần `soup serve` trong `docs/serving-and-export.md`, vì bản mới có quy tắc riêng cho `--tool-auth-token`: dài 16 đến 128 ký tự, chỉ gồm chữ, số, `_` và `-`.

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

**Báo `error: externally-managed-environment` khi dùng pip.** Đây là quy định PEP 668 của Debian 12, Ubuntu 23.04 trở lên, không phải lỗi của Soup. Cách an toàn nhất là dùng `pipx` hoặc `uv tool`. Hoặc tạo môi trường ảo riêng: `python3 -m venv .venv && source .venv/bin/activate` rồi dùng `pip` bình thường.

**`pip` từ chối `soup-cli[train]` khi bạn copy lệnh có nháy đơn.** Hãy viết lại với dấu nháy kép: `"soup-cli[train]"`. README nói đây là cách duy nhất chạy trong mọi shell (cmd.exe, PowerShell, bash, zsh).

**Cài lỗi hoặc lệnh không chạy vì phiên bản Python.** Soup yêu cầu Python 3.11 đến 3.13. Nếu bạn đang dùng 3.14 trở lên, hãy cài bản 3.11–3.13 và tạo môi trường mới. README cũng nói sự không khớp phiên bản và bánh xe CUDA (CUDA wheels) được trình bày trong `docs/backends-and-ops.md`.

**`soup train` báo thiếu thành phần huấn luyện.** Nếu bạn chỉ cài bản nhẹ `soup-cli`, nó không có PyTorch và các thư viện huấn luyện. Cài thêm bằng `pipx install "soup-cli[train]"` (hoặc `pip install "soup-cli[train]"`).

**File `soup.yaml` không nạp được.** Từ bản 0.75, khoá không được khai báo trong schema sẽ làm cấu hình thất bại, thay vì bị bỏ qua. Hãy kiểm tra chính tả của từng khoá. Nếu bạn nâng cấp từ bản 0.76.x, README khuyên chạy `soup doctor --config soup.yaml` trước và đọc ghi chú phát hành.

**Hết VRAM giữa chừng.** README không đưa ra một thông báo lỗi cụ thể, nhưng đây là vấn đề rất dễ gặp khi fine-tune. Hãy dùng `soup profile --model <id>` để ước tính từ đầu. Chọn mô hình nhỏ hơn theo bảng VRAM ở trên, hoặc thử `stream_layers: true`.

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

**Điểm mạnh.** Soup đóng gói cả quy trình (khởi tạo, huấn luyện, chat thử, gộp, xuất, đẩy lên Hub) vào cùng một công cụ và cùng một kiểu cấu hình. Nó miễn phí, giấy phép Apache-2.0, chạy ngay trên máy bạn, có sẵn mẫu cho nhiều bài toán và hỗ trợ cả Docker. Layer streaming mở đường cho những ai chỉ có GPU nhỏ. Tác giả cũng khá trung thực khi công bố cả những số đo kém thuận lợi.

**Giới hạn.** Layer streaming vẫn là BETA và phải bật thủ công. Phần cứng vẫn quyết định: README khuyến nghị GPU CUDA, còn CPU chỉ thử nghiệm và rất chậm. Dự án thay đổi nhanh, và ghi chú phát hành cho biết có những quy tắc mới có thể từ chối cấu hình mà bản trước chấp nhận, nên khi nâng cấp bạn cần đọc ghi chú. Phạm vi tính năng rất rộng, nên người mới sẽ chỉ cần dùng một phần nhỏ trong đó. Chất lượng mô hình sau fine-tune còn phụ thuộc chủ yếu vào dữ liệu của bạn, không phải công cụ.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần mô hình trả lời theo tài liệu và không cần huấn luyện, một giải pháp tìm kiếm tài liệu kết hợp với mô hình có sẵn có thể đơn giản hơn. Nếu bạn không có GPU và không muốn chờ rất lâu, hãy cân nhắc thuê máy hoặc dùng Colab. README có nhắc tới việc kiểm chứng trên Colab T4 miễn phí cho tính năng streaming. Còn nếu bạn muốn một công cụ dòng lệnh gọn nhẹ để thử và học cách fine-tune, Soup là lựa chọn dễ bắt đầu.

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

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

Có. Soup dùng giấy phép Apache-2.0 và tác giả nói dự án miễn phí và sẽ giữ như vậy. Bạn chỉ tốn chi phí điện, phần cứng hoặc thuê máy GPU nếu có.

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

README khuyến nghị GPU có CUDA, và Apple Silicon (MPS) cũng được hỗ trợ. CPU chỉ ở mức thử nghiệm và rất chậm. Với mô hình 7B dùng QLoRA, README ghi cần từ 8 GB VRAM trở lên, còn chế độ layer streaming (BETA) cho phép model 8B chạy trên GPU laptop 4 GB.

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

README không có mục liệt kê hệ điều hành riêng. Tuy nhiên nó có hướng dẫn cú pháp cho cmd.exe và PowerShell, nên Windows có vẻ được tính đến. Nếu cần chắc chắn, hãy xem docs/backends-and-ops.md trong repo hoặc chạy soup doctor.

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

Soup huấn luyện ngay trên máy bạn, README nói không cần cloud. Telemetry mặc định tắt và chỉ bật khi bạn đặt SOUP_TELEMETRY=1. Các chi tiết bảo mật khác bạn nên xem SECURITY.md và chính sách riêng tư của dự án.

### Python phiên bản nào thì dùng được?

Python 3.11, 3.12 hoặc 3.13. Python 3.14 trở lên chưa được hỗ trợ vì chồng PyTorch chưa được kiểm chứng ở đó.

### Tôi chỉ cài soup-cli thì có fine-tune được không?

Không. Bản nhẹ không có PyTorch và chỉ dùng cho các lệnh như soup init và soup data. Để huấn luyện bạn cần cài thêm phần train bằng pipx install "soup-cli[train]" hoặc pip install "soup-cli[train]".

### Soup hỗ trợ những mô hình nào?

README nói Soup dùng được với mọi mô hình sinh văn bản trên Hugging Face nếu nạp được bằng AutoModelForCausalLM. Hơn 100 họ mô hình như Llama 3.x/4, Qwen 2.5/3, Gemma 3, Mistral, DeepSeek, Phi-4 có công thức dựng sẵn, xem bằng soup recipes list.
