Bỏ qua tới nội dung
Ông T.vn

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

11 phút đọcCập nhật

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 →

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

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.

CLI

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.

★ 11kPythonApache-2.0
Xem repo trên GitHub

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ạ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.

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 push cần quyền ghi. Chi tiết xem trong docs/.

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

  1. Kiểm tra PythonBảo đảm máy có Python 3.11 đến 3.13
  2. Cài SoupDùng pipx hoặc pip, nhớ thêm [train] nếu muốn huấn luyện
  3. Tạo cấu hìnhChạy soup init để có file soup.yaml
  4. Chạy huấn luyệnDùng soup train với file cấu hình
  5. 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:

Terminal
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.

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:

Terminal
# 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…):

Terminal
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:

Terminal
pipx install "soup-cli[all]"

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

Terminal
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:

Terminal
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:

Terminal
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.

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:

Terminal
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.

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 đó:

Terminal
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 đó.

F.Huấn luyện

Terminal
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.

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

Sau khi cài, chạy:

Terminal
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:

Terminal
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:

Terminal
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.

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:

Terminal
soup data inspect ./data/train.jsonl

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

Terminal
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

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:

Terminal
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.

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:

Terminal
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.

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:

Terminal
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.

VI.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.

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ử.

4.1/5 · Ông T chấm

Chưa có độc giả chấm

Bài này có ích với bạn không?

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ủ.

Chuyển nhanh tới mục

  1. I.Soup làm được gì
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Kiểm tra phiên bản Python
    2. B.Cài Soup bằng pipx hoặc uv
    3. C.Hoặc cài bằng pip
    4. D.Chạy bằng Docker (tùy chọn)
    5. E.Tạo file cấu hình
    6. F.Huấn luyện
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Chủ shop muốn chatbot trả lời đúng giọng cửa hàng
    2. B.Dev có laptop GPU nhỏ muốn thử mô hình 8B
    3. C.Nhân viên văn phòng đem mô hình về chạy với Ollama
    4. D.Nhóm nhỏ muốn dựng API nội bộ
  6. VI.Lỗi hay gặp và cách xử lý
  7. VII.Có nên dùng không

Repo & Skill · 13/11/2026 · 11 phút đọc

Garden Skills: bộ skill thiết kế web, tạo ảnh, làm video cho AI — hướng dẫn cài đặt và dùng

Garden Skills là bộ sưu tập Agent Skills (kỹ năng cho AI) của tác giả ConardLi, dùng được với Claude Code, Cursor, Codex và các AI coding agent khác. Mỗi skill dạy agent làm tốt một việc như thiết kế trang web, tạo ảnh, làm video bằng code, biến tài liệu thành bài viết đẹp. Cài không khó, nhưng README có nhiều cách cài nên bạn cần chọn một cách hợp với công cụ đang dùng.

Repo & Skill · 13/11/2026 · 15 phút đọc

thesysdev/openui: xây giao diện AI dạng streaming — hướng dẫn cài đặt và dùng

OpenUI là framework full-stack, độc lập framework, giúp mô hình AI sinh giao diện có cấu trúc và hiển thị dần khi dữ liệu streaming về. Bạn có thể dựng nhanh một ứng dụng chat bằng CLI hoặc cài từng gói cho React, Vue, Svelte, Angular và LangChain. Việc bắt đầu khá đơn giản nếu máy có đúng phiên bản Node; README chưa ghi đầy đủ lệnh chạy ứng dụng sau khi scaffold.

Repo & Skill · 13/11/2026 · 11 phút đọc

Ruflo: điều phối nhóm agent AI cho Claude Code và Codex — hướng dẫn cài đặt và dùng

Ruflo (trước đây là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên và khả năng chia việc cho nhóm agent. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng hệ thống rất rộng nên bạn nên bắt đầu từ một tác vụ nhỏ.