Soup

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

Soup

LLM을 명령어 하나로 파인튜닝하고 포스트트레이닝하세요. SSH도, 설정 지옥도 없습니다.

웹사이트 ·
빠른 시작 ·
웹 UI ·
설정 ·
문서 ·
명령어 ·
모델 ·
Discord ·
Telegram ·
Product Hunt

Soup는 LLM 파인튜닝의 고통을 단순한 워크플로로 바꿉니다. 설정 하나, 명령어 하나면 끝입니다.

pip install " soup-cli[train] " # 파인튜닝하려면 [train] 추가; `soup-cli`만 쓰면 경량 CLI
soup init --template chat
soup train
4 GB 노트북 GPU에서 8B 모델을 파인튜닝하세요. 레이어 스트리밍은 동결된 베이스를
VRAM 밖에 두고 디코더 레이어 하나씩 GPU에 공급합니다. RTX 3050 Laptop 4 GB에서 측정:
Llama-3.1-8B-Instruct + NF4, 952 MHz에서 119.6 tok/s, 피크 3.32 GB (수리 전) — 일반 상주 실행과
비트 단위로 동일하며, H100에서도 동일한 3.32 GB로 113.00 tok/s로 독립 재현되었습니다.
(두 수치 모두 v0.72.2에서 측정되었으며, 32B에서 −4.8% 비용이 든 v0.73.0 정확성 수리 이전입니다.
수리 후 실행은 다른 RTX 3050 Laptop 4 GB(@umran666, #1103)에서 1935–1957 MHz로 208.6 tok/s,
피크 2.40 GB 입니다. 이는 같은 세션 GEMM 상한의 59%로, 68% 대비 클록당 약 14% 느리므로
원시 1.74x 이득은 속도 향상이 아니라 클록입니다. 대형 레이어 스트리밍은 두 행 사이의 메모리
패턴도 바꾸었으므로 비율조차 동일 조건 비교가 아닙니다 — 기록 .) 옵트인( stream_layers: true )
이며 여전히 BETA —
작동 방식 ·
모든 측정값 · 논문 ·
무료 Colab T4에서 직접 확인하세요 (프로세스를
4 GB로 제한한 뒤, 스트리밍 모델이 일반 모델과 비트 단위로 동일한지 검증)

Llama-3.1-8B-Instruct + NF4, LoRA, batch 1, seq 512, RTX 3050 Laptop 4 GB — 피크 3.32 GB, 952 MHz에서 119.6 tok/s (수리 전, v0.72.2; #331 이후: 1935 MHz에서 208.6 tok/s, 2.40 GB, 직접 비교 불가, @umran666, #1103). 전체 영상 (90초)

왜 Soup인가?
LLM 학습은 여전히 고통스럽습니다. 숙련된 팀조차 시간의 30-50%를 모델 개선 대신
인프라와 싸우는 데 씁니다. Soup가 이를 해결합니다.

SSH 제로. 망가진 GPU 박스에 다시 SSH할 일이 없습니다.
설정 하나. 간단한 YAML 파일 하나면 충분합니다.
모든 것 자동. 배치 크기, GPU 감지, 양자화 — 모두 처리됩니다.
로컬에서 작동. QLoRA로 자신의 GPU에서 학습하세요. 클라우드 불필요.

새로운 소식
v0.77.1 — 패치: soup data는 입력을 보존하고, soup plan은 soup train과 일치하며,
GRPO는 Apple Silicon에서 학습합니다. v0.77.0의 어떤 것도 철회되지 않습니다. 해당 릴리스는
v0.76이 경고하거나 무시했던 설정을 거부하므로, v0.76에서 로드되던 설정이 로드되지 않을 수 있습니다:
0.76.x에서 오신 경우, 먼저 soup doctor --config soup.yaml을 실행하고
v0.77.0 릴리스 노트를 읽으세요.

soup data 명령어는 더 이상 입력을 덮어쓰지 않습니다. 열여덟 개( dedup ,
filter , convert , merge , sample , pii , toxicity 등)는 어떤 표기로든 입력과 같은 파일인
--output을 읽기 전에 거부하며, 입력이 이미 가진 기본 출력 이름도 거부됩니다. 새 파일에 쓰세요.
soup plan과 soup apply는 soup train이 거부하는 설정을 동일한 메시지로 거부하고,
계획을 쓰지 않습니다.
GRPO는 Apple Silicon에서 네이티브로 학습합니다. task: grpo와 backend: mlx는
transformers 경로가 학습하는 목적함수 위에서 Soup 자체의 MLX 루프를 실행하며, 내장 accuracy 또는
format 보상을 사용합니다. soup infer --backend mlx는 Torch 없이 MLX 베이스와 네이티브 텍스트 LoRA
어댑터로 생성합니다.
soup train의 사전 점검, soup profile, soup plan에 대한 단일 피크 VRAM 추정치로,
39회 측정 실행으로 보정되었습니다( 기록 ). 약 3.5B 파라미터까지의 dense
모델, 즉 적합 범위 내에서는 사전 점검이 이전에 통과시키던 일부 긴 시퀀스·대형 어휘 실행을
거부하며, --allow-oom-attempt는 여전히 이를 실행합니다. 그 범위 밖(더 큰 모델 또는
mixture-of-experts 모델, medium 또는 selective 체크포인팅, use_liger / use_cut_ce , backend: unsloth )에서는
맞지 않는 실행이 추정치를 경고로 받고 시작됩니다. 단, 가중치, CUDA 컨텍스트, 학습하는 파라미터의
그래디언트와 옵티마이저 상태가 카드 용량을 초과하는 경우(80 GB에서 7B 전체 파인튜닝, 24 GB에서
Llama-3.1-70B 4-bit)는 그곳에서도 거부됩니다. LoRA 실행과 일부만 학습하는 실행(Spectrum, LISA,
freezing)은 더 적은 항목으로 판정되며, --allow-oom-attempt는 거부된 실행도 여전히 실행합니다.
외부 프로그램은 PATH에서 찾은 절대 경로로 시작합니다. 현재 디렉터리와 상대 PATH 항목은
더 이상 검색되지 않습니다: 그곳에만 있는 도구는 해당 디렉터리를 PATH에 두어야 합니다.
또한 새로 추가됨. soup ship --progress jsonl ; 다른 라이브러리가 부르는 방식으로 작성된 알 수 없는
설정 키는 Soup 필드를 제안합니다( learning_rate는 lr을 제안); 아래 Docker 예제는 --yes를 전달하며,
비대화형 soup train은 v0.77.0부터 이를 필요로 합니다.

더 오래된 하이라이트는 GitHub Releases 페이지에 있습니다.

빠른 시작
1. 설치
Soup는 명령줄 애플리케이션이므로, 가장 깔끔한 설치는 자체 환경을 주고 soup를 PATH에 두는 것입니다:

# 경량 코어: CLI + 설정 + 데이터 도구, PyTorch 없음
pipx install soup-cli
uv tool install soup-cli # 같은 방식, uv를 이미 쓴다면

# 학습 스택 추가 (torch, transformers, peft, trl, datasets, …)
pipx install " soup-cli[train] "

# 모든 것 (train + serve + ui + data)을 한 번에
pipx install " soup-cli[all] "

# 또는 GitHub에서 (최신 dev)
pipx install " git+https://github.com/MakazhanAlpamys/Soup.git "
이미 virtualenv, Colab 노트북, Docker 이미지 안에 있나요? 같은 이름과 extras로 pip를
직접 사용하세요:

pip install soup-cli
pip install " soup-cli[train] "
pip install " soup-cli[all] "
pip install git+https://github.com/MakazhanAlpamys/Soup.git
자신의 코드에서 soup_cli를 import하려면 pipx 대신 pip를 사용하세요.
pipx는 애플리케이션을 다른 모든 것으로부터 의도적으로 격리하기 때문입니다.

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

error: externally-managed-environment ? 그것은
PEP 668 이지 Soup 문제가 아닙니다. Debian 12,
Ubuntu 23.04 이후는 pip가 시스템 Python에 쓰는 것을 막습니다. apt가 그 파일들을
관리하기 때문입니다. pipx와 uv tool은 Soup에 자체 환경을 주어 이를 우회하며, 그래서 위에 먼저
나열되어 있습니다. python3 -m venv .venv && source .venv/bin/activate 후 일반 pip도 잘 작동합니다.

작은따옴표가 아니라 큰따옴표. "soup-cli[train]"이 모든
셸 — cmd.exe , PowerShell, bash, zsh — 에서 작동하는 유일한 표기입니다. 오래된
튜토리얼에서 'soup-cli[train]'을 복사했는데 pip가 거부했다면, 그것이 이유입니다:
이유, 그리고 정확한 오류 .

soup init , soup data … 및 기타 데이터/검사 명령어는 경량 설치에서 작동합니다.
파인튜닝( soup train )에는 [train] extra가 필요합니다.

2. 설정 생성
soup init # 대화형 마법사
soup init --template chat # 또는 템플릿에서 시작
템플릿: chat , code , tool-calling , medical , reasoning , vision , kto , orpo ,
simpo , ipo , bco , rlhf , pretrain , moe , longcontext , embedding , audio .

3. 학습, 테스트, 배포
soup train --config soup.yaml # LoRA, 양자화, 배칭 — 모두 처리
soup chat --model ./output # 모델과 대화
soup push --model ./output --repo you/my-model

soup merge --adapter ./output # LoRA를 베이스에 병합
soup export --model ./output --format gguf --quant q4_k_m # Ollama / llama.cpp용 GGUF
더 많은 export 대상(ONNX, TensorRT, BitNet)과 배포 옵션은
docs/serving-and-export.md 에 있습니다.

웹 UI
브라우저가 좋으신가요? soup ui는 실험, 학습 설정, 실시간 지표, 데이터셋 탐색, 모델 채팅을 위한
로컬 대시보드를 제공합니다.

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

웹 UI 문서

설정
완전한 soup.yaml :

base : meta-llama/Llama-3.1-8B-Instruct
task : sft
# backend: unsloth # 2-5x 빠름, 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
config/schema.py는 모든 필드의 단일 진실 공급원입니다. 고급 데이터, 학습,
PEFT 옵션은 문서 에 설명되어 있습니다.

알 수 없는 설정 키는 v0.75부터 거부됩니다. 어떤 모델도 선언하지 않는 키 — quantizaton 같은
오타, 또는 더 새로운 Soup에만 있는 필드 — 는 예전에는 검증을 통과하고 버려져서, 설정이
적용되지 않은 채 실행이 진행되었습니다. v0.74는 로드 시 아마도 의도했을 필드와 함께 이를
보고했습니다; v0.75부터 같은 설정은 로드에 실패하므로, 무시되리라 기대하지 말고 키를 고치거나
제거하세요. 알 수 없는 설정 키 를 참조하세요.

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

가이드
다루는 내용

학습 작업 & 방법
SFT, DPO/GRPO/PPO/KTO/ORPO/SimPO/IPO/BCO, tool-calling, PRM, 사전 학습, 증류, 분류, vision/audio/TTS, unlearning, RAFT/RA-DIT, loop-hardening 탐지기

PEFT, 긴 컨텍스트 & 효율성
DoRA, LoRA+, rsLoRA, VeRA, OLoRA, NEFTune, PiSSA, ReLoRA, 옵티마이저 & PEFT 모음, LLaMA Pro, GaLore, YaRN/LongLoRA, 패킹, 커리큘럼, 자동 튜닝

성능 & 양자화
QAT, FP8, Quant Menu (I + II), KV-cache, NVFP4, 저장 형식, Cut Cross-Entropy, 그래디언트 체크포인팅, 커널, 활성화 오프로딩, 레이어 스트리밍, 멀티 GPU / DeepSpeed / FSDP

데이터 엔지니어링
형식, Axolotl/LF 패리티 파이프라인, 데이터 도구, 합성 생성 & forge, 품질 스코어카드, 트레이스 도구, 원격 데이터셋, 믹싱, 레시피 DAG

평가 & 프로브
Eval 설계/게이트, eval-gated 학습, 벤치마크, NLG 지표, 캘리브레이션, Elo 아레나, diagnose, 포스트트레인 X-ray 프로브, A/B, 드리프트, 튜너빌리티, soup advise

서빙 & export
OpenAI 호환 서버, 배치 추론, 벤치마킹, merge/export, Anthropic Messages 엔드포인트, 추측 디코딩(자신의 draft 학습 + 측정), 배포 오토파일럿, 웹 UI, Agent Forge

어댑터, 레지스트리 & 거버넌스
어댑터 라이프사이클/관리, 모델 레지스트리, Soup Cans, 데이터 플라이휠( soup loop ), 지식 편집, 스티어링, 공급망 제어(scan/sign/BOM/attest/audit/airgap)

컴플라이언스 & 거버넌스 빠른 시작
HIPAA/SOC2/EU-AI-Act/SR-11-7 init 템플릿, 출처(BOM/attest/repro-receipt), 감사 로그, 에어갭, 모델 카드 자동 생성( soup card ), CI 게이트( soup ci init )

백엔드, 플랫폼 & 운영
MLX/Unsloth 백엔드, 대체 허브, HF Hub 통합, 오토파일럿, 실험 추적, plan/apply, 환경 lockfile, 하드웨어 적합성, completions, 플러그인, 유틸리티 명령어

명령어 참조
전체 soup 명령어 목록

지원 모델 & extras
권장 모델 패밀리, VRAM 크기 가이드, pip extras 매트릭스

데이터 형식
Alpaca, ShareGPT, ChatML, 선호 쌍(DPO / ORPO / SimPO / IPO / KTO), vision, audio,
ASR, 평문, embedding, RAFT 등 — 모두 JSONL, JSON, CSV, Parquet 또는
TXT에서 자동 감지되므로, 대부분의 경우 data.train을 파일로 지정하면 다른 것은 바뀌지 않습니다. 형식별 예제가 있는 스키마와
데이터 파이프라인(원격 URI, 스트리밍, 샤딩, 인터리빙, 어휘 확장, 문서 수집)은
docs/data.md 에 있으며, 네이티브 Sesame CSM 오디오 학습은 별도로 문서화되어 있습니다.

자주 쓰는 명령어
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 # 대화형 채팅
soup serve --model ./output # OpenAI 호환 API 서버
soup ui # 로컬 브라우저 대시보드
soup merge --adapter ./output # LoRA를 베이스 모델에 병합
soup export --model ./output --format gguf # 배포용 export
soup eval benchmark --model ./output # 평가
soup data inspect ./data/train.jsonl # 데이터셋 통계
soup recipes list # 100+ 즉시 사용 가능한 모델 레시피
soup autopilot --model < id > --data d.jsonl --goal chat # 제로 설정
soup doctor # GPU / 의존성 / 환경 확인
전체 명령어 목록은 docs/commands.md 에 있습니다.

지원 모델
Soup는 HuggingFace Hub의 모든 텍스트 생성 모델과 작동합니다 — AutoModelForCausalLM으로
로드되면 작동하며, 설정 변경이 필요 없습니다. Llama 3.x/4, Qwen 2.5/3, Gemma 3, Mis…