Soup: fine-tune LLM bằng một lệnh — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về MakazhanAlpamys/Soup — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: 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 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.
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ể.
MakazhanAlpamys/Soup
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.
I.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ạysoup trainthay 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
4bitgiú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 uimở 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 doctorkiể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 listliệ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.
II.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.
III.Cài đặt từng bước
- Chuẩn bị PythonDùng Python 3.11, 3.12 hoặc 3.13 và chọn cách cài phù hợp
- Cài SoupCài bản light, bản training hoặc toàn bộ extra
- Tạo cấu hìnhDùng wizard hoặc template để tạo soup.yaml
- Chuẩn bị dữ liệuTrỏ data.train tới file dữ liệu đúng định dạng
- Huấn luyện và thử modelChạy train, chat, infer hoặc UI
A.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:
python --versionPhiê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.
B.Cài Soup
Bản nhẹ chỉ cài CLI, config và công cụ dữ liệu:
pipx install soup-cli
uv tool install soup-cli # same idea, if you already use uvNếu mục tiêu là fine-tune, cài thêm training stack:
pipx install "soup-cli[train]"Nếu muốn có training, serving, UI và data tools trong một lần cài:
pipx install "soup-cli[all]"Nếu đã ở trong virtualenv, Colab hoặc Docker image, dùng pip:
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:
pipx install "git+https://github.com/MakazhanAlpamys/Soup.git"
pip install git+https://github.com/MakazhanAlpamys/Soup.gitGiữ 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 đó:
python3 -m venv .venv && source .venv/bin/activateLệ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.
C.Tạo file cấu hình
Sau khi cài xong, chạy wizard tương tác:
soup initHoặc tạo cấu hình từ template chat:
soup init --template chatCá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:
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: ./outputbase 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.
D.Huấn luyện model
Chạy training với file cấu hình:
soup train --config soup.yaml # LoRA, quantization, batching — all handledLệ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:
soup chat --model ./outputBạn cũng có thể chạy batch inference:
soup infer --model ./output --input prompts.jsonl --output results.jsonlE.Dùng Web UI hoặc Docker
Nếu đã cài extra UI, chạy:
pip install "soup-cli[ui]"
soup uiSoup 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:
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 locallyLệ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.
IV.Kiểm tra đã chạy được chưa
Kiểm tra nhanh môi trường bằng:
soup doctorREADME 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:
soup init --template chatNếu wizard tạo được soup.yaml, phần CLI và config đã hoạt động. Sau đó chạy:
soup train --config soup.yamlKế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:
pytest tests/ -v
pytest tests/ -m smoke -v
pytest tests/ -m gpu --no-cov -vTest unit không cần GPU. Smoke test tải một model nhỏ và train thử. GPU test cần card CUDA.
V.Dùng vào việc thật
A.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:
soup train --config soup.yaml
soup chat --model ./outputKế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.
B.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:
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.
C.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:
soup merge --adapter ./outputSau đó export sang GGUF:
soup export --model ./output --format gguf --quant q4_k_mKế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.
D.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:
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
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.
VI.Lỗi hay gặp và cách xử lý
A.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.
B.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ý.
C.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:
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.
D.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.
E.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.
VII.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.


