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

Tóm tắt nhanh
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.
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.
MakazhanAlpamys/Soup
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.
I.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.
II.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.tomlcũ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:
pipxhoặcuv 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ùngpip. - 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 pushlê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 xemdocs/backends-and-ops.mdtrong repo.
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.
III.Cài đặt từng bước
- Kiểm tra PythonĐảm bảo máy có Python 3.11 đến 3.13
- Cài SoupDùng pipx cài gói soup-cli kèm phần huấn luyện [train]
- Tạo cấu hìnhChạy soup init --template chat để có file soup.yaml mẫu
- Kiểm tra máyChạy soup doctor xem GPU và thư viện
- Huấn luyệnChạy soup train --config soup.yaml
A.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.
python --versionNế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.
B.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:
# 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.
C.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:
pip install soup-cli
pip install "soup-cli[train]"
pip install "soup-cli[all]"
pip install git+https://github.com/MakazhanAlpamys/Soup.gitDùng pip thay vì pipx nếu bạn còn muốn import soup_cli trong code của mình.
D.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:
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áyLệ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.
E.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:
soup init # trình hướng dẫn tương tác
soup init --template chat # hoặc bắt đầu từ mẫuSau đó 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:
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: ./outputCá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.
F.Chạy huấn luyện
soup doctor
soup train --config soup.yamlsoup 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ề.
IV.Kiểm tra đã chạy được chưa
Có ba dấu hiệu theo thứ tự từ dễ đến khó:
soup doctorchạy ra báo cáo. Nếu gõsoupmà 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.soup train --config soup.yamlchạy và thư mụcoutputxuất hiện. Đó là nơi cấu hình mẫu lưu kết quả.- Chat thử được với mô hình vừa huấn luyện:
soup chat --model ./outputNế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ở:
pip install "soup-cli[ui]"
soup ui
# Mở http://127.0.0.1:7860/?token=<token> và in ra cùng địa chỉ đóV.Dùng vào việc thật
A.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:
soup data inspect ./data/train.jsonlSau đó 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
B.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):
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.
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:
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.
D.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ẻ:
soup serve --model ./output
soup push --model ./output --repo you/my-modelThay 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à -.
VI.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.
VII.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.


