MakazhanAlpamys/Soup

Fine-tune LLMs from one YAML. Layer streaming trains an 8B model on a 4 GB laptop GPU.

Soup – 단일 명령어로 LLM 미세조정 및 후처리

무엇인가요 – Soup은 Python 기반 CLI(옵션으로 웹 UI 포함)로, LLM 미세조정 파이프라인을 단일하고 재현 가능한 워크플로우로 통합합니다. 작은 YAML 설정 파일 하나로 다음을 수행할 수 있습니다:

HuggingFace에서 베이스 모델을 다운로드하고,
LoRA/QLoRA 어댑터를 적용하며,
레이어 스트리밍 기술을 사용해 고정된 베이스 모델을 GPU에 유지하지 않고, 보통 GPU(최소 4GB VRAM)에서 양자화된 학습을 수행하고,
평가, 병합, GGUF/ONNX/TensorRT 등으로 내보내기, OpenAI 호환 API를 통해 모델 제공까지 가능합니다.

이 모든 작업은 soup 명령어 하나로 자동 조율되며, 수동 SSH, 사용자 정의 스크립트, 번거로운 환경 변수 설정이 필요 없습니다.

주요 기능 (README에 설명됨)

기능	제공되는 기능
단일 명령어 워크플로우	`soup init … && soup train`은 데이터 로딩부터 체크포인트 저장까지 모든 작업을 수행합니다.
레이어 스트리밍 (베타)	디코더 레이어를 RAM에서 GPU로 하나씩 스트리밍하여, 8B 모델을 4GB 랩톱 GPU에서 학습 가능 (약 120토큰/초, 최대 3.3GB 사용).
QLoRA 및 4비트 양자화	메모리 효율적인 미세조정으로, 배치 크기, 그래디언트 스케일링 등을 자동 선택합니다.
광범위한 모델 지원	`AutoModelForCausalLM`로 로드 가능한 모든 모델 – Llama‑3.x/4, Qwen, Gemma, Mistral, Mixtral, Phi‑4 등.
다양한 학습 목표	SFT, DPO, GRPO, PPO, KTO, ORPO, SimPO, IPO, BCO, 도구 호출, 사전 학습, 지식 증류, 비전/오디오 등.
웹 UI 및 대시보드	`soup ui`로 로컬 Gradio 스타일 인터페이스를 시작해 데이터셋 검사, 실시간 메트릭, 채팅이 가능합니다.
내보내기 및 서빙	LoRA 병합, GGUF(llama.cpp/Ollama), ONNX, TensorRT, AWQ, GPTQ, BitNet로 내보내기, OpenAI 호환 서버 실행 (`soup serve`).
풍부한 문서 및 레시피	100개 이상의 준비된 모델 레시피, 데이터 형식, 준수, 성능 튜닝에 대한 상세 가이드.
크로스플랫폼	CUDA GPU, Apple Silicon(MPS), CPU(테스트용)에서 작동. Docker 이미지 제공.
커뮤니티 주도	최근 릴리스는 95% 이상이 외부 PR, 활발한 Discord/Telegram, DOI 링크된 논문 포함.

빠른 시작 (README에서)

# 가벼운 CLI 설치 (PyTorch 없음)
pipx install soup-cli
# 학습 스택 추가 (torch, transformers, peft 등)
pipx install "soup-cli[train]"

# 설정 초기화 (인터랙티브 마법사 또는 템플릿)
soup init --template chat

# 생성된 soup.yaml로 학습
soup train

동일한 명령어는 pip, uv tool, 또는 Git 체크아웃에서 직접 사용 가능합니다.

강점

저자원 미세조정 – 레이어 스트리밍으로 저가 랩톱에서도 8B 모델 학습 가능.
제로 설정 사용성 – 배치 크기, GPU 유형, 양자화 수준, 데이터 형식을 자동 감지.
통합 도구 체인 – 학습, 평가, 병합, 내보내기, 서빙을 모두 커버.
확장성 – 선택적 확장([fast], [mlx], [ui], [serve] 등)으로 속도 향상, Apple Silicon 지원, UI 추가 가능하며 불필요한 무거운 종속성은 포함하지 않음.
좋은 문서 – 완전한 docs 폴더, 명령어 참조, 많은 튜토리얼(콜랩 노트북, 동영상).

제한 사항 / 주의사항 (프로젝트에서 언급됨)

레이어 스트리밍은 여전히 베타 – 일부 GPU 모델(예: 무료 Colab/T4 레벨)에서 실패할 수 있으며, 설정 파일에 stream_layers: true 필요.
Python 버전 제한 – 공식 지원은 3.10~3.12; 3.13+는 wheel 해결 문제 발생 가능.
Torch 2.5.x 호환성 문제 – torch>=2.5.0과 trl>=0.29는 충돌; 최신 torch로 새 설치 필요.
CPU 학습은 테스트용 – 매우 느리며, 생산용으로는 적합하지 않음.
일부 고급 백엔드(DeepSpeed, FSDP)는 선택적 확장이며 추가 설정 필요.
보안 – soup serve는 루프백 호스트 외에 바인딩할 경우 도구 인증 토큰 없이 오류로 종료됨. /v1/tools/bash 엔드포인트는 OS 수준 격리 뒤에만 재활성화됨.

누구에게 적합한가

CUDA 설정에 애를 먹지 않고 개인 워크스테이션에서 LLM을 미세조정하고 싶은 연구자나 애호가.
재현 가능하고 단일 명령어로 파이프라인을 완성하며, 배포 형식으로 내보내는 것을 원하는 소규모 팀.
학습 중 데이터셋 검사나 실시간 채팅용 UI가 필요한 사람.

결론

Soup은 진정한, 활발히 유지 관리되는 오픈소스 프로젝트로, LLM 미세조정의 복잡한 하드웨어 작업을 추상화합니다. 가장 두드러진 특징은 레이어 스트리밍으로, 저VRAM 하드웨어에서 학습 가능한 한계를 극복하며, 설정 기반 CLI, 웹 UI, 내보내기 옵션 등 다른 도구 체인은 실험과 가벼운 생산 환경 모두에 실용적인 선택입니다.