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
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 (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.
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.
MakazhanAlpamys/Soup
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.
I.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ạysoup 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.trainvào file. - Chat, gộp, xuất, đẩy lên Hub.
soup chatđể nói chuyện thử,soup mergegộp LoRA vào mô hình gốc,soup exportxuất GGUF cho Ollama hoặc llama.cpp,soup pushđưa lên HuggingFace. - Máy chủ tương thích OpenAI.
soup servemở 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 uimở 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 doctorkiể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 filesoup.yaml. - Công thức làm sẵn.
soup recipes listliệt kê hơn 100 công thức cho các họ mô hình như Llama, Qwen, Gemma, Mistral, DeepSeek, Phi.
II.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 pushcần quyền ghi. Chi tiết xem trongdocs/.
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ẻ.
III.Cài đặt từng bước
- Kiểm tra PythonBảo đảm máy có Python 3.11 đến 3.13
- Cài SoupDùng pipx hoặc pip, nhớ thêm [train] nếu muốn huấn luyện
- Tạo cấu hìnhChạy soup init để có file soup.yaml
- Chạy huấn luyệnDùng soup train với file cấu hình
- Thử và xuất mô hìnhChat thử, rồi gộp LoRA hoặc xuất GGUF
A.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:
python --versionNế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.
B.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:
# Light core: CLI + config + data tools, no PyTorch
pipx install soup-cli
uv tool install soup-cli # same idea, if you already use uvBả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…):
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:
pipx install "soup-cli[all]"Hoặc cài bản mới nhất từ GitHub:
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.
C.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:
pip install soup-cli
pip install "soup-cli[train]"
pip install "soup-cli[all]"
pip install git+https://github.com/MakazhanAlpamys/Soup.gitNế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:
python3 -m venv .venv && source .venv/bin/activateSau khi kích hoạt môi trường ảo, bạn chạy pip install như bình thường.
D.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:
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 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.
E.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 đó:
soup init # interactive wizard
soup init --template chat # or start from a templateLệ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:
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: ./outputBạ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 đó.
F.Huấn luyện
soup train --config soup.yamlLầ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.
IV.Kiểm tra đã chạy được chưa
Sau khi cài, chạy:
soup doctorLệ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:
soup chat --model ./outputNế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:
pip install "soup-cli[ui]"
soup ui
# Opens http://127.0.0.1:7860/?token=<token> and prints the same URLLệnh sẽ in ra địa chỉ có kèm token. Mở địa chỉ đó trong trình duyệt trên cùng máy.
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
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:
soup data inspect ./data/train.jsonlSau đó tạo cấu hình chat rồi huấn luyện:
soup init --template chat
soup train --config soup.yaml
soup chat --model ./outputKế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
B.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:
soup profile --model meta-llama/Llama-3.1-8B-InstructLệ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.
C.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:
soup merge --adapter ./output
soup export --model ./output --format gguf --quant q4_k_mKế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.
D.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:
soup serve --model ./outputLệ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.
VI.Lỗi hay gặp và cách xử lý
soup trainbáo thiếu thư viện. Bạn mới cài bản nhẹsoup-cli. Cài lại vớipipx install "soup-cli[train]"hoặcpip 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ùngpipx,uv tool, hoặc tạo môi trường ảo bằngpython3 -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.yamltrướ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.
VII.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ủ.


