LLM 미세 조정 및 후 학습을 한 번의 명령으로 간편하게

요약

Soup은 복잡한 LLM 미세 조정 및 후 학습 과정을 간소화하여, 단일 설정과 명령어로 워크플로우를 완성합니다. 특히 레이어 스트리밍(Layer streaming) 기술을 활용해 4GB 노트북 GPU에서도 대형 모델(Llama-3.1-8B 등)의 효율적인 처리가 가능함을 입증했습니다.

핵심 포인트

Soup CLI를 사용하면 복잡한 LLM 학습 과정을 간편하게 처리할 수 있습니다.
레이어 스트리밍은 VRAM 사용을 최적화하여 저사양 GPU에서도 대형 모델 학습이 가능합니다.
4GB 노트북 GPU 환경에서 8B 모델을 효율적으로 미세 조정하는 성능 지표를 제시했습니다.

🌍 English | Türkçe | العربية | 日本語 | 中文

하나의 명령어로 LLM을 미세 조정하고 후 학습하세요. SSH나 복잡한 설정 과정이 필요 없습니다.

Website · Quick Start · Web UI · Config · Docs · Commands · Models · Discord · Telegram · Product Hunt

Soup은 LLM 미세 조정의 어려움을 간단한 워크플로우로 바꿉니다. 하나의 설정, 하나의 명령으로 끝납니다.

pip install "soup-cli[train]" # 미세 조정을 하려면 [train]을 추가하세요; 단순히 `soup-cli`는 가벼운 CLI입니다.
soup init --template chat
soup train

4GB 노트북 GPU에서 8B 모델을 미세 조정하기. 레이어 스트리밍(Layer streaming)은 고정된 기본 모델(frozen base)이 VRAM에 머무는 것을 방지하고, 디코더 레이어를 한 번에 하나씩 GPU로 공급합니다. RTX 3050 Laptop 4 GB에서 측정한 결과:
Llama-3.1-8B-Instruct + NF4를 952 MHz에서 119.6 tok/s, 최대 3.32 GB로 측정했습니다 (사전 수리 기준) — 일반적인 상주 실행(normal resident run)과 비트 단위로 일치하며, H100에서도 동일한 3.32 GB에서 113.00 tok/s로 독립적으로 재현되었습니다. (두 수치는 v0.72.2에서 측정되었으며, 이는 32B 모델에서 -4.8%의 비용이 발생했던 v0.73.0 정정 작업 이전입니다. 또 다른 RTX 3050 Laptop 4 GB에서 수행된 사후 수정 실행(post-repair run)은 2.40 GB 최대치에서 1935–1957 MHz로 208.6 tok/s를 기록했습니다. 이는 동일 세션의 GEMM 한계 대비 59%에 해당하며, 클럭당 약 14% 느린 속도이므로, 순수한 1.74배 증가는 속도 향상이 아닌 클럭 자체입니다. 대형 레이어 스트리밍은 두 행 사이의 메모리 패턴도 변경했기 때문에, 비율 역시 일대일 비교는 아닙니다 — 기록.) Opt-in (stream_layers: true)

그리고 여전히 베타 버전이며 —
작동 방식 ·
모든 측정값 · 논문 ·
무료 Colab T4에서 직접 확인해 보세요 (프로세스를 4 GB로 제한한 다음, 스트리밍된 모델이 일반 모델과 비트 단위로 동일함을 입증합니다)

soup train pre-flight for Llama-3.1-8B on a 4 GB card: a 3.60 GB base store pinned in RAM across 32 layers and two 113 MB VRAM buffers, then a measured peak of 3.32 GB at 119.6 tok/s, stopping short of the 4 GB line (pre-repair row, measured on v0.72.2 at 952 MHz; the post-#331 row is in the caption below)

Llama-3.1-8B-Instruct + NF4, LoRA, 배치 1, 시퀀스 512를 RTX 3050 Laptop 4 GB에서 측정 — 최대 3.32 GB, 952 MHz에서 119.6 tok/s (사전 수리 v0.72.2; 사후 #331: 2.40 GB에서 1935 MHz로 208.6 tok/s, 직접 비교 불가, @umran666, #1103). 전체 영상(90초)

LLM을 학습시키는 것은 여전히 고통스럽습니다. 숙련된 팀조차 모델 개선보다는 인프라 문제 해결에 시간의 30~50%를 소비합니다. Soup이 이 문제를 해결해 줍니다.

Zero SSH. 더 이상 오작동하는 GPU 박스에 SSH 접속할 필요가 없습니다. One config. 간단한 YAML 파일 하나만 있으면 됩니다. Auto everything. 배치 크기(Batch size), GPU 감지, 양자화(quantization) — 모두 자동으로 처리됩니다. Works locally. 클라우드가 필요하지 않습니다. QLoRA를 사용하여 로컬에서 자체 GPU로 학습하세요.

v0.76.0 — settings Soup accepted and never applied now stop the load. 이전에 유효성 검사 및 문서화되었으나, 실제로 설정하는 경로에서는 읽히지 않았던 옵션들은 이제 로드 시 거부됩니다. 해당 설정과 변경해야 할 내용을 명시하며, 나머지는 경고를 표시하고 이를 거부할 릴리스 버전을 명시합니다. 이전에 로드했던 설정 파일도 다시 로드할 수 없습니다: 먼저 soup doctor --config soup.yaml을 실행하세요.

Breaking: 더 이상 적용되지 않았던 설정이 로드 시 거부됩니다. 그중에는 training.quantization_aware: true (실제 양자화 인식 학습(quantization-aware training)을 수행하지 않음), training.use_longlora, training.ebft_variant, training.gdpo_variant, training.rope_scaling_type 등, 어떤 설정도 읽지 않는 곳에 있는 것들, 텍스트의 sft/tts 경로 외부의 freeze_layers/freeze_ratio와 트랜스포머 백엔드(transformers backend)에서, sft/tts 외부의 auto_mixed_precision, 그리고 설정이 없는 일곱 가지 추가 작업에서의 backend: unsloth가 있습니다. 각 메시지는 필드 이름과 변경해야 할 내용을 명시합니다. lr_groups, early_stop_patience, forgetting_eval_steps 및 기타 읽히지 않는 노브(knobs)들은 이제 로드 시 경고를 표시하며 v0.77부터는 거부됩니다.

Validation loss is now evaluated. 이제 모든 실행에서 학습 데이터셋에서 행을 제외하는(data.val_split) 것이 아니라, 트레이너가 이를 평가하지 않던 상황이 사라졌습니다. transformers 백엔드에서 어떤 작업도 분할(split)이 적용되면 각 에포크 끝 또는 training.eval_steps로 지정된 N 스텝마다 이를 평가하고 검증 손실(val loss)을 기록합니다. 이로 인해 실행 시간이 몇 퍼센트 더 걸립니다.

Breaking for 기본적으로 이제 행을 제외하지 않습니다 (grpo, ppo, 그리고 online_dpo: data.val_split은 무시되며 참고 사항이 표시됩니다). 따라서 모든 행이 학습에 사용됩니다.

Breaking: every non-standard grpo_variant는 grpo_beta KL 페널티를 적용합니다. gspo, dapo, dr_grpo, bnpo, two_sided, 그리고 rft가 검증된 grpo_beta입니다.

그리고 그것을 제거하여 기존의 variant 설정이 이전 실행 결과를 재현하지 못하게 합니다. grpo_beta: 0

이제 KL-free로 실행되며 참조 순방향 계산(reference forward pass)은 건너뜁니다.**레이어 스트리밍(Layer streaming)**은 백그라운드 스레드를 통해 직접 I/O(direct I/O) 방식으로 디스크 계층에서 읽고, NVMe 드라이브에 걸쳐 스트라이프(stripe)할 수 있습니다.36 GB의 70B 크기 NF4 저장소는 RAM보다 크며 (RTX 5070 Laptop 8 GB 박스 하나 분량), 콜드 스텝(cold step)은 동기식 읽기 시 110.5초에서 16.2~17.3초로, 그리고 SOUP_LAYER_STREAM_STRIPE_DIRS를 통해 두 드라이브에 걸쳐는 17.4초에서 9.97초로 단축되었습니다.

(지속적인 부하 프로빙: 두 라운드, 1.28배 및 1.41배, 공식적인 판결 없음; 기록). RAM에 맞는 저장소의 경우 여전히 RAM 계층에서 더 빠르며, stream_source: auto가 선택됩니다. 옵트인(stream_layers: true)이며 아직 BETA 상태입니다. 기록된 내용: 직접 I/O, 스트라이핑.새로운 명령어 및 옵션.soup adapters check는 LoRA 어댑터를 조용한 실패(silent failure)에 대해 검사합니다. soup bench train은 지정된 횟수만큼 스텝을 학습하고 모델이 학습되지 않은 경우 1로 종료됩니다 (이는 task: sft를 커버합니다). soup bench는 이제 그룹이며, soup bench infer가 이전 추론 벤치마크입니다. soup data clean은 입력 파일을 건드리지 않고 데이터셋을 정리하고 복구합니다. soup recipes verify는 가중치를 다운로드하지 않고 메타 장치에서 모든 배포된 레시피가 LoRA 어댑터를 연결할 수 있는지 확인합니다. soup rewind는 손실 급증(loss spike)이 발생한 데이터셋 행의 이름을 지정합니다. soup infer는 옵트인 --batch-size와 실험적인 --cuda-graphs를 얻습니다 (PyTorch 2.14 이상; RTX 5070 Laptop 하나에서 unpinned, Qwen2.5-1.5B FP16 기준, 가장 느린 실행이 이 기능을 사용하지 않은 가장 빠른 실행보다 2.9배 빠르게 디코딩되었습니다).soup ab는 양방향의 분산에 강한 테스트를 수행하며, soup adapters sign --backend sigstore와 soup attest emit --sign sigstore로 Sigstore 키리스 OIDC(pip install

3.10–3.12만 해당합니다. 3.13 이상 버전에서는 Soup이 실행되기 전에 네이티브 확장(native extension)에서 충돌을 일으키는 테스트되지 않은 PyTorch wheel을 해결하는 데 pip가 사용되었습니다.

이전 하이라이트는 GitHub Releases 페이지에서 확인할 수 있습니다.

Soup은 명령줄 애플리케이션(command-line application)이므로, 가장 깔끔한 설치 방법은 자체 환경을 제공하고 soup을 시스템의 PATH에 추가하는 것입니다:

# Light core: CLI + config + data tools, no PyTorch
pipx install soup-cli
uv tool install soup-cli # 이미 uv를 사용 중이라면 같은 아이디어로
...

이미 가상 환경(virtualenv), Colab 노트북 또는 Docker 이미지 내부에 있습니까? 동일한 이름과 추가 옵션(extras)을 사용하여 pip를 직접 사용하십시오:

pip install soup-cli
pip install "soup-cli[train]"
pip install "soup-cli[all]"
...

만약 자체 코드에서 soup_cli를 import하고 싶다면, pipx 대신 pip를 사용하십시오. 왜냐하면 pipx는 애플리케이션을 다른 모든 것과 의도적으로 격리(isolate)하기 때문입니다.

전체 추가 옵션 표(fast, mlx, serve, eval, ui, vision, audio, …)는 docs/models.md에 있습니다.

이것은 PEP 668이며, Soup의 문제가 아닙니다. Debian 12, Ubuntu 23.04 이상 버전에서는 apt가 해당 파일을 관리하기 때문에 시스템 Python에 쓰려고 할 때 error: externally-managed-environment 오류를 발생시키지 않습니다. pipx와 uv tool은 Soup에게 자체 환경을 제공함으로써 이를 우회(sidestep)하므로, 위에서 이들이 먼저 나열된 것입니다. 따라서 python3 -m venv .venv && source .venv/bin/activate를 실행한 후 일반적인 pip도 똑같이 잘 작동합니다.

작은따옴표가 아닌 큰따옴표를 사용하십시오. 모든 셸(cmd.exe, PowerShell, bash, zsh)에서 작동하는 유일한 철자는 `

, rlhf

, pretrain

, moe

, longcontext

, embedding

, audio

soup train --config soup.yaml # LoRA, quantization, batching — all handled
soup chat --model ./output # talk to your model
soup push --model ./output --repo you/my-model
...

더 많은 내보내기 대상(ONNX, TensorRT, AWQ, GPTQ, BitNet) 및 배포 옵션은 docs/serving-and-export.md에 있습니다.

브라우저를 선호하시나요? soup ui
실험, 훈련 설정, 실시간 지표, 데이터셋 탐색 및 모델 채팅을 위한 로컬 대시보드를 제공합니다.

pip install "soup-cli[ui]"
soup ui
# http://127.0.0.1:7860/?token=<token>를 열고 동일한 URL을 출력합니다

완벽한 soup.yaml
:

base: meta-llama/Llama-3.1-8B-Instruct
task: sft
# backend: unsloth # 2-5x faster, pip install "soup-cli[fast]"
...

config/schema.py는 모든 필드에 대한 단일 진실 공급원(single source of truth)입니다. 고급 데이터, 훈련 및 PEFT 옵션은 Documentation에서 문서화되어 있습니다.

알 수 없는 설정 키(Unknown config keys)는 v0.75부터 거부됩니다. quantizaton과 같은 오타나 더 최신 Soup 버전에서만 존재하는 필드와 같이 모델이 선언하지 않은 키는 깨끗하게 검증되어 무시되며, 따라서 실행은 해당 설정이 적용되지 않은 상태로 진행됩니다. v0.74에서는 아마도 의도했을 필드를 로드할 때 보고했지만, v0.75부터는 동일한 설정 파일이 로드에 실패하므로, 무시되기를 기대하기보다는 키를 수정하거나 제거해야 합니다. Unknown config keys를 참조하세요.

전체 기능 참고 자료는 docs/에 있습니다. 여기서 시작하세요:

가이드	포함 내용
훈련 작업 및 방법 (Training tasks & methods)	SFT, DPO/GRPO/PPO/KTO/ORPO/SimPO/IPO/BCO, 도구 호출(tool-calling), PRM, 사전 훈련(pre-training), 증류(distillation), 분류(classification), 비전/오디오/TTS, 언러닝(unlearning), RAFT/RA-DIT, 루프 강화 검출기(loop-hardening detectors)
...

Alpaca, ShareGPT, ChatML, 선호 쌍(preference pairs) (DPO / ORPO / SimPO / IPO / KTO), 비전, 오디오, ASR, 평문(plaintext), 임베딩(embedding), RAFT 등 — JSONL, JSON, CSV, Parquet 또는 TXT에서 모두 자동 감지되므로, 대부분의 경우 data.train을 지정하기만 하면 됩니다.

파일 하나만 변경되고 다른 것은 아무것도 바뀌지 않습니다. 형식별로 작업 예제가 포함된 스키마와 데이터 파이프라인(원격 URI, 스트리밍, 샤딩, 인터리빙, 어휘 확장, 문서 수집)은 docs/data.md에 있습니다.

soup train --config soup.yaml # 학습 (SFT/DPO/GRPO/PPO/KTO/ORPO/SimPO/IPO/...)
soup infer --model ./output --input prompts.jsonl --output results.jsonl # 배치 추론
soup chat --model ./output # 대화형 채팅
...

전체 명령어 목록은 docs/commands.md에 있습니다.

Soup는 HuggingFace Hub의 모든 텍스트 생성 모델과 함께 작동합니다. AutoModelForCausalLM으로 로드되면, 설정 변경 없이 작동합니다. Llama 3.x/4, Qwen 2.5/3, Gemma 3, Mistral, Mixtral, DeepSeek R1/V3, Phi-4 및 100개 이상의 모델이 준비된 레시피로 제공됩니다 (soup recipes list).

VRAM	최대 모델 (QLoRA 4비트)	예시
8 GB	~7B	Llama-3.1-8B, Mistral-7B
...
전체 모델 + 비전 테이블 및 선택적 추가 기능 매트릭스는 `docs/models.md`에 있습니다.

CUDA나 PyTorch를 로컬에 설치하지 않고 Soup 실행하기 (릴리스마다 GHCR에 게시되는 이미지):

docker pull ghcr.io/makazhanalpamys/soup:latest
docker run --gpus all -v $(pwd):/workspace ghcr.io/makazhanalpamys/soup train --config soup.yaml
docker compose up # 또는 로컬에서 빌드

Python 3.10, 3.11 또는 3.12 (CI 테스트 버전; PyTorch 스택이 아직 검증되지 않아 3.13+는 지원하지 않음)
CUDA GPU (권장), Apple Silicon (MPS) 또는 CPU (실험적 — 매우 느림)
QLoRA를 사용한 7B 모델의 경우 8 GB 이상 VRAM

모든 학습 작업은 테스트를 위해 CPU에서 실행됩니다 (양자화 자동 비활성화). 선택적 추가 기능(train, all, fast, vision, qat, serve, serve-fast, ui, eval, deepspeed, liger, mlx, onnx, tensorrt 등)은 docs/models.md에 나열되어 있습니다.

soup doctor # GPU, 시스템 리소스, 종속성 및 버전을 한 곳에서 확인

CUDA 휠, 버전 불일치: docs/backends-and-ops.md

git clone https://github.com/MakazhanAlpamys/Soup.git
cd Soup
pip install -e ".[dev]"
...

전체 워크플로우는 CONTRIBUTING.md를 참조하고, 취약점 보고는 SECURITY.md를 참고하세요. 텔레메트리는 엄격하게 옵트인(opt-in) 방식이며 (SOUP_TELEMETRY=1, 기본값은 꺼짐; Privacy Policy 참조).

AI 자동 생성 콘텐츠

원문 바로가기

가이드

포함 내용

훈련 작업 및 방법 (Training tasks & methods)

SFT, DPO/GRPO/PPO/KTO/ORPO/SimPO/IPO/BCO, 도구 호출(tool-calling), PRM, 사전 훈련(pre-training), 증류(distillation), 분류(classification), 비전/오디오/TTS, 언러닝(unlearning), RAFT/RA-DIT, 루프 강화 검출기(loop-hardening detectors)

...

soup train --config soup.yaml # 학습 (SFT/DPO/GRPO/PPO/KTO/ORPO/SimPO/IPO/...) soup infer --model ./output --input prompts.jsonl --output results.jsonl # 배치 추론 soup chat --model ./output # 대화형 채팅 ...

VRAM

최대 모델 (QLoRA 4비트)

예시

8 GB

~7B

Llama-3.1-8B, Mistral-7B

...

전체 모델 + 비전 테이블 및 선택적 추가 기능 매트릭스는 docs/models.md에 있습니다.

LLM 미세 조정 및 후 학습을 한 번의 명령으로 간편하게

요약

핵심 포인트

댓글