# Soup: tinh chỉnh 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 viết bằng Python, dùng để tinh chỉnh LLM từ một file cấu hình YAML rồi chat thử, gộp LoRA và xuất ra GGUF để dùng với Ollama hoặc llama.cpp. Cài bằng pip hoặc pipx chỉ vài lệnh, nhưng muốn huấn luyện thật bạn cần Python 3.11 đến 3.13 và nên có GPU. Người mới cần chút quen thuộc với terminal và dữ liệu dạng JSONL.

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

Soup là một công cụ dòng lệnh (CLI) viết bằng Python, giúp bạn tinh chỉnh (fine-tune) mô hình ngôn ngữ lớn chỉ với một file cấu hình YAML và một lệnh `soup train`. Bạn không cần tự ghép từng thư viện huấn luyện, không cần SSH vào máy chủ GPU, cũng không phải viết script dài.

Nếu bạn muốn có một mô hình "biết nghề" của riêng mình, ví dụ trả lời theo giọng cửa hàng, hiểu thuật ngữ ngành, hoặc làm theo định dạng bạn yêu cầu, thì Soup đáng thử. Nó hợp với lập trình viên mới, dân kỹ thuật trong doanh nghiệp nhỏ, và người muốn chạy mô hình ngay trên máy mình thay vì thuê cloud. Repo hiện có khoảng 10,5 nghìn sao và khoảng 1,7 nghìn fork, giấy phép Apache-2.0, và vẫn được cập nhật đều.

Điểm đáng giá nhất là tính năng "layer streaming". Theo tác giả, cách này cho phép tinh chỉnh mô hình 8B trên laptop có GPU chỉ 4 GB. Tính năng này còn ở mức BETA và phải bật riêng, nên bạn đừng kỳ vọng nó mượt như chế độ mặc định.

```repo
- repo | MakazhanAlpamys/Soup
- kind | CLI
- desc | Soup là công cụ dòng lệnh Python giúp tinh chỉnh (fine-tune) mô hình ngôn ngữ lớn bằng một file YAML và một lệnh, kể cả trên GPU laptop 4 GB.
- stars | 11k
- lang | Python
- license | Apache-2.0
```

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

Soup bao trọn quy trình từ chuẩn bị đến phát hành mô hình, trong cùng một bộ lệnh `soup`.

- **Một file cấu hình, một lệnh chạy.** Bạn khai báo mô hình gốc, dữ liệu, số epoch, kiểu LoRA, kiểu nén (quantization) trong `soup.yaml`. Sau đó chạy `soup train`. Lợi ích thực tế là bạn lưu được cấu hình, chạy lại được và gửi cho đồng nghiệp.
- **Mẫu cấu hình dựng sẵn.** Lệnh `soup init --template ...` cho bạn điểm xuất phát: `chat`, `code`, `tool-calling`, `medical`, `reasoning`, `vision`, `kto`, `orpo`, `simpo`, `ipo`, `bco`, `rlhf`, `pretrain`, `moe`, `longcontext`, `embedding`, `audio`. Bạn đỡ phải viết YAML từ trang trắng.
- **Tự chọn nhiều thứ giúp bạn.** README ghi Soup xử lý tự động việc dò GPU, chọn batch size (`batch_size: auto`) và nén mô hình. Người mới ít phải đoán thông số.
- **Layer streaming cho GPU nhỏ.** Phần mô hình gốc bị đóng băng được giữ ngoài VRAM và đưa vào GPU từng lớp một. Tác giả đo trên RTX 3050 Laptop 4 GB với Llama-3.1-8B-Instruct dạng NF4: đỉnh bộ nhớ khoảng 3,32 GB ở bản đo trước, và 2,40 GB ở bản đo sau do một người dùng khác thực hiện. Bật bằng `stream_layers: true`.
- **Nhiều phương pháp huấn luyện.** SFT, DPO, GRPO, PPO, KTO, ORPO, SimPO, IPO, BCO và một số loại khác. Bạn bắt đầu bằng SFT, khi cần dạy mô hình "thích câu trả lời nào hơn" thì chuyển sang nhóm preference.
- **Đọc nhiều định dạng dữ liệu.** Alpaca, ShareGPT, ChatML, cặp ưa thích cho DPO, vision, audio, văn bản thuần… từ JSONL, JSON, CSV, Parquet hoặc TXT. README nói trong đa số trường hợp bạn chỉ cần trỏ `data.train` vào file.
- **Chat, gộp, xuất, đẩy lên Hub.** `soup chat` để nói chuyện thử, `soup merge` gộp LoRA vào mô hình gốc, `soup export` xuất GGUF cho Ollama hoặc llama.cpp, `soup push` đưa lên HuggingFace.
- **Máy chủ tương thích OpenAI.** `soup serve` mở một API giống OpenAI để ứng dụng khác gọi vào mô hình của bạn.
- **Giao diện web cục bộ.** `soup ui` mở bảng điều khiển trên trình duyệt để theo dõi thử nghiệm, xem số liệu huấn luyện, xem dữ liệu và chat.
- **Công cụ kiểm tra.** `soup doctor` kiểm tra GPU, tài nguyên, thư viện. `soup profile --model <id>` ước tính mô hình có vừa VRAM không mà chưa cần file `soup.yaml`.
- **Công thức làm sẵn.** `soup recipes list` liệt kê hơn 100 công thức cho các họ mô hình như Llama, Qwen, Gemma, Mistral, DeepSeek, Phi.

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

Theo README và `pyproject.toml`, bạn cần:

- **Python 3.11, 3.12 hoặc 3.13.** Python 3.14 trở lên chưa được hỗ trợ.
- **Phần cứng:** GPU có CUDA là lựa chọn được khuyến nghị. Apple Silicon (MPS) và CPU cũng chạy được, nhưng CPU được ghi là 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 của repo: 8 GB cho khoảng 7B, 16 GB cho khoảng 14B, 24 GB cho khoảng 34B, 48 GB cho khoảng 70B.
- **Hệ điều hành:** README nhắc đến `cmd.exe`, PowerShell, bash và zsh, nên Windows, Linux, macOS đều là đối tượng được tính tới. Nếu muốn tránh cài CUDA và PyTorch thủ công, có thể dùng Docker.
- **Dữ liệu huấn luyện** của bạn, thường là file JSONL.
- **Tài khoản HuggingFace:** README không nêu bắt buộc. Một số mô hình gốc như Llama thường yêu cầu đăng nhập hoặc chấp nhận điều khoản trên Hub, và `soup push` cần quyền ghi. Chi tiết xem trong `docs/`.

```note
Huấn luyện mô hình tốn điện, tốn thời gian và có thể tốn tiền nếu bạn thuê GPU đám mây. Trước khi chạy thật, hãy thử bằng `soup profile` hoặc `soup doctor`. Đừng dán token HuggingFace hay khóa API vào file bạn định chia sẻ.
```

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

```steps
- Kiểm tra Python | Bảo đảm máy có Python 3.11 đến 3.13
- Cài Soup | Dùng pipx hoặc pip, nhớ thêm [train] nếu muốn huấn luyện
- Tạo cấu hình | Chạy soup init để có file soup.yaml
- Chạy huấn luyện | Dùng soup train với file cấu hình
- Thử và xuất mô hình | Chat thử, rồi gộp LoRA hoặc xuất GGUF
```

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

Mở terminal (PowerShell trên Windows, Terminal trên macOS hoặc Linux) và xem Python của bạn. Lệnh sau là lệnh phổ thông, không nằm trong README:

```bash
python --version
```

Nếu ra 3.14 hoặc thấp hơn 3.11, hãy cài một phiên bản trong khoảng 3.11 đến 3.13 trước. Đây là chỗ người mới hay vấp nhất.

### Cài Soup bằng pipx hoặc uv

Soup là ứng dụng dòng lệnh, nên README khuyên cài vào môi trường riêng để lệnh `soup` nằm sẵn trong `PATH`. Có hai cách tương đương:

```bash
# Light core: CLI + config + data tools, no PyTorch
pipx install soup-cli
uv tool install soup-cli          # same idea, if you already use uv
```

Bản nhẹ này đủ để dùng `soup init` và các lệnh xử lý dữ liệu. Muốn huấn luyện thật, thêm gói `[train]` (kéo theo torch, transformers, peft, trl, datasets…):

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

Muốn cài trọn bộ gồm huấn luyện, máy chủ, giao diện và công cụ dữ liệu:

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

Hoặc cài bản mới nhất từ GitHub:

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

Lưu ý: hãy dùng dấu nháy kép `"soup-cli[train]"`. README nói đây là cách duy nhất chạy được trên mọi shell, kể cả `cmd.exe` và PowerShell. Dấu nháy đơn có thể bị pip từ chối.

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

Nếu bạn đang ở trong virtualenv, Colab hoặc Docker, hay muốn `import soup_cli` trong code của mình, hãy dùng pip:

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

Nếu gặp `error: externally-managed-environment` trên Debian 12 hoặc Ubuntu 23.04 trở lên, đó là cơ chế bảo vệ Python hệ thống, không phải lỗi của Soup. Dùng `pipx` ở trên, hoặc tạo môi trường ảo:

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

Sau khi kích hoạt môi trường ảo, bạn chạy `pip install` như bình thường.

### Chạy bằng Docker (tùy chọn)

Nếu không muốn cài CUDA và PyTorch trên máy, README cho cách dùng image dựng sẵn:

```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 run` gắn thư mục hiện tại vào `/workspace`. Vì vậy file `soup.yaml` và dữ liệu của bạn phải nằm đúng trong thư mục bạn đang đứng. Cách này cần Docker hỗ trợ GPU. Dấu `$(pwd)` là cú pháp bash; trên PowerShell bạn cần viết khác, và README chưa hướng dẫn riêng cho PowerShell.

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

Tạo một thư mục làm việc rồi chạy một trong hai lệnh sau trong đó:

```bash
soup init                       # interactive wizard
soup init --template chat       # or start from a template
```

Lệnh đầu hỏi bạn từng bước. Lệnh sau tạo sẵn cấu hình mẫu cho bài toán chat. Bạn sẽ có file `soup.yaml` để chỉnh. Một cấu hình đầy đủ mà README đưa ra:

```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
```

Bạn đổi `base` sang mô hình mình muốn, và `data.train` sang đường dẫn file dữ liệu của bạn. Lưu ý: từ bản 0.75, khóa lạ trong cấu hình (ví dụ gõ sai `quantizaton`) sẽ làm cấu hình không nạp được thay vì bị bỏ qua lặng lẽ. Nếu gặp lỗi này, hãy sửa chính tả khóa đó.

### Huấn luyện

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

Lần đầu chạy, công cụ có thể phải tải mô hình gốc từ HuggingFace Hub nên sẽ mất thời gian. Đừng đóng terminal giữa chừng.

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

Sau khi cài, chạy:

```bash
soup doctor
```

Lệnh này báo GPU, tài nguyên hệ thống, thư viện và phiên bản trong một chỗ. Nếu nó chạy được và nhận ra GPU (hoặc báo rõ bạn đang dùng CPU), nghĩa là cài đặt ổn. README không mô tả chi tiết màn hình kết quả mong đợi, nên bạn chỉ cần xem có lỗi thiếu thư viện hay không.

Sau khi huấn luyện xong, thử mô hình bằng:

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

Nếu bạn chat được và câu trả lời mang dấu ấn dữ liệu bạn đã dạy, huấn luyện đã thành công. README cũng nói mọi tác vụ huấn luyện đều có thể chạy thử trên CPU (khi đó quantization tự tắt), hợp để kiểm tra quy trình bằng dữ liệu rất nhỏ trước khi dùng GPU.

Muốn xem giao diện web, cài thêm gói `ui`:

```bash
pip install "soup-cli[ui]"
soup ui
# Opens http://127.0.0.1:7860/?token=<token> and prints the same URL
```

Lệnh sẽ in ra địa chỉ có kèm token. Mở địa chỉ đó trong trình duyệt trên cùng máy.

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

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

Chị Lan bán mỹ phẩm online, có vài trăm đoạn hội thoại tư vấn khách đã lưu. Chị nhờ bạn kỹ thuật chuyển chúng thành file JSONL theo định dạng Alpaca hoặc ShareGPT (xem `docs/data.md` để biết đúng cấu trúc). Trước hết xem thống kê dữ liệu:

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

Sau đó tạo cấu hình chat rồi huấn luyện:

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

Kết quả: một mô hình đã học cách xưng hô và cách trả lời của shop. Bạn kiểm tra bằng `soup chat` trước khi đưa vào dùng.

> Tinh chỉnh không phải phép màu; dữ liệu sạch và đúng giọng mới là thứ quyết định chất lượng.
>
> — Ông T

### Dev có laptop GPU nhỏ muốn thử mô hình 8B

Anh Minh có laptop GPU 4 GB và không có ngân sách thuê máy chủ. Anh trước hết hỏi xem mô hình có vừa không:

```bash
soup profile --model meta-llama/Llama-3.1-8B-Instruct
```

Lệnh này ước tính dựa trên `config.json` của mô hình, không cần `soup.yaml`. Nếu muốn thử layer streaming, anh thêm `stream_layers: true` vào cấu hình, nhớ rằng tính năng còn BETA. README có đưa một ví dụ trên Colab T4 miễn phí để tự kiểm chứng. Kết quả: có thể huấn luyện trên phần cứng mà bình thường không đủ, đổi lại tốc độ chậm hơn và cần kiên nhẫn.

### Nhân viên văn phòng đem mô hình về chạy với Ollama

Bạn đã có mô hình tinh chỉnh ở thư mục `./output` và muốn dùng với Ollama hoặc llama.cpp. Gộp LoRA, rồi xuất GGUF:

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

Kết quả là file GGUF nén kiểu `q4_k_m`, gọn hơn để chạy trên máy thường. Cách đưa file vào Ollama thì README chỉ dẫn sang `docs/serving-and-export.md`.

### Nhóm nhỏ muốn dựng API nội bộ

Một công ty nhỏ muốn ứng dụng nội bộ gọi mô hình của riêng họ qua giao diện quen thuộc kiểu OpenAI:

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

Lệnh này mở máy chủ tương thích OpenAI. Nếu bật xác thực công cụ bằng `--tool-auth-token`, README yêu cầu token dài 16 đến 128 ký tự, chỉ gồm chữ, số, `_` và `-`. Nên đặt mật khẩu khi mở ra ngoài máy cá nhân.

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

- **`soup train` báo thiếu thư viện.** Bạn mới cài bản nhẹ `soup-cli`. Cài lại với `pipx install "soup-cli[train]"` hoặc `pip install "soup-cli[train]"`.
- **pip từ chối `soup-cli[train]`.** Có thể bạn dùng dấu nháy đơn từ hướng dẫn cũ. Dùng dấu nháy kép như trong README.
- **`error: externally-managed-environment`.** Do cơ chế bảo vệ Python hệ thống (PEP 668). Dùng `pipx`, `uv tool`, hoặc tạo môi trường ảo bằng `python3 -m venv .venv`.
- **Cấu hình không nạp được vì khóa lạ.** Từ bản 0.75, khóa không được khai báo (như gõ sai chính tả) bị từ chối. Sửa hoặc xóa khóa đó. Nếu bạn nâng cấp từ bản cũ, chạy `soup doctor --config soup.yaml` trước, theo gợi ý trong README.
- **Hết VRAM hoặc chạy cực chậm.** Dùng `soup profile --model <id>` để ước tính, chọn mô hình nhỏ hơn, giữ `quantization: 4bit`, hoặc cân nhắc layer streaming. Nếu bạn không có GPU, README cảnh báo CPU rất chậm.
- **Không cài được do phiên bản Python.** Kiểm tra Python nằm trong 3.11 đến 3.13. Các lỗi về CUDA wheel và xung đột phiên bản được README chỉ sang `docs/backends-and-ops.md`.

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

**Điểm mạnh:** Soup gom cả quy trình vào một bộ lệnh thống nhất, có mẫu cấu hình, nhiều phương pháp huấn luyện, xuất GGUF và có giao diện web. Giấy phép Apache-2.0, miễn phí, dự án hoạt động đều. Layer streaming mở đường cho người chỉ có GPU nhỏ. Telemetry mặc định tắt, chỉ bật khi bạn đặt `SOUP_TELEMETRY=1`.

**Giới hạn:** Tính năng layer streaming còn BETA. Tài liệu rất rộng, nên người mới dễ choáng khi đọc hết `docs/`. Các bản phát hành gần đây có thay đổi hành vi, ví dụ cấu hình lạ bị từ chối, nên khi nâng cấp bạn cần đọc ghi chú phát hành. Chạy CPU chỉ để thử nghiệm. README cũng không hứa chất lượng mô hình; điều đó phụ thuộc dữ liệu của bạn.

**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 của mình, thường không cần tinh chỉnh; hãy cân nhắc cách khác như đưa tài liệu vào prompt. Nếu bạn không có dữ liệu mẫu đủ tốt, hoặc không muốn đụng terminal, thì công cụ này chưa phù hợp. Còn nếu bạn muốn một quy trình tinh chỉnh chạy cục bộ, lặp lại được, thì Soup là lựa chọn đáng thử.

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

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

Có. Repo dùng giấy phép Apache-2.0 và README ghi rõ Soup miễn phí, và sẽ tiếp tục như vậy. Chi phí bạn có thể phải trả là điện, phần cứng hoặc tiền thuê GPU nếu chạy trên đám mây.

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

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

### Soup có chạy trên Windows không?

README có nhắc đến cmd.exe và PowerShell khi hướng dẫn cú pháp cài đặt, nên Windows nằm trong phạm vi sử dụng. Tuy nhiên README không có mục riêng cho Windows. Nếu gặp lỗi về CUDA hoặc phiên bản, xem docs/backends-and-ops.md.

### Cần phiên bản Python nào?

Python 3.11, 3.12 hoặc 3.13, đúng theo pyproject.toml và các phiên bản CI kiểm thử. Python 3.14 trở lên chưa được hỗ trợ vì bộ PyTorch chưa được kiểm chứng ở đó.

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

Soup chạy trên máy của bạn và 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. Với các tính năng như push lên Hub hoặc mở máy chủ, bạn nên tự kiểm tra quyền truy cập; chi tiết bảo mật xem SECURITY.md trong repo.

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

README nói Soup chạy với bất kỳ mô hình sinh văn bản nào trên HuggingFace Hub nếu tải đượ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.

### Soup khác gì so với các công cụ tinh chỉnh khác?

Tư liệu chưa có so sánh trực tiếp với từng công cụ cụ thể. Điểm Soup nhấn mạnh là quy trình một file YAML cùng một lệnh, các lệnh đi kèm như chat, merge, export, serve, ui, và layer streaming cho GPU nhỏ. Unsloth được hỗ trợ như một backend tùy chọn thay vì đối thủ.
