tarioch/unsloth-lora

Unsloth LoRA 훈련

로컬 GPU에서 채팅 형식 데이터셋으로 Unsloth를 사용해 LoRA를 훈련하고 결과를 GGUF로 내보냅니다. 데이터셋은 사용자 고유의 것입니다(생성은 문제별로 다름). 이 스킬은 train.jsonl과 val.jsonl에서 시작합니다. 모델 서빙은 별도 단계입니다. 이 스킬이 남긴 run 폴더(GGUF + run.json)는 ollama-model과 같은 서빙 스킬이 사용합니다.

모든 스크립트는 Bash 도구로 런처를 통해 실행합니다: ${CLAUDE_SKILL_DIR}/scripts/run <script.py> [args]. 이 스킬은 정확히 이 명령만 허용하므로 자동 모드로 실행됩니다. 다른 방식으로 스크립트를 호출하면 거부됩니다. 사용자의 새 메시지 후에 런처 명령이 거부되면 이 스킬을 다시 호출하세요. 런처는 check_data.py를 Python 3로 실행하고, preflight.py, train.py, export_gguf.py는 Unsloth 환경의 Python으로 실행하며, --out/--run 폴더의 상위 폴더에서 실행합니다(Unsloth는 현재 디렉토리에 unsloth_compiled_cache/ 폴더를 씁니다). 모든 경로는 절대 경로로 지정하세요. 명령어는 작업 디렉토리를 공유하지 않습니다.

시작하기 전에 확인할 사항

• 데이터셋 폴더와 나중에 모델을 비교하는 데 사용할 평가 세트: 훈련에 포함되지 않아야 합니다. 평가 세트가 없다면 훈련 전에 예제를 분리할 것을 제안하세요.
• 기본 모델(들): Unsloth 4비트 이름(예: unsloth/Qwen2.5-Coder-3B-Instruct-bnb-4bit)을 사용합니다. 여러 기본 모델이면 각각 하나의 run 폴더를 만들고 각 모델에 대해 동일한 단계를 순차적으로 수행합니다(references/base-models.md 참조).
• 시스템: 훈련에는 CUDA GPU와 Unsloth 환경의 Python이 필요합니다. UNSLOTH_PYTHON 환경 변수가 설정되지 않았고 ~/.config/llm-finetune/unsloth-python 파일이 없으면 사용자에게 Python 경로를 물어보고, 사용자 동의를 얻어 해당 파일의 첫 줄에 경로를 기록하세요. 런처는 이 파일에서 경로를 읽습니다.
• runs 폴더: run 폴더들이 위치할 경로로, git 체크아웃 외부에 있어야 합니다. 아래에서 <runs>는 이 절대 경로를 나타냅니다.

단계

1. 데이터 확인

${CLAUDE_SKILL_DIR}/scripts/run check_data.py <data> --eval <eval.jsonl>

ok를 출력해야 합니다. 깨진 줄, assistant 응답으로 끝나지 않는 대화, 훈련 데이터에 이미 있는(동일하거나 다른 응답의) 검증/평가 프롬프트가 있으면 실패합니다. 모델이 해당 데이터를 이미 보았으므로 recall을 측정하게 됩니다. 수정 방법은 검증/평가 세트에서 해당 데이터를 제거하거나 데이터 분할 방식을 수정하는 것이며, 절대 확인을 통과시키기 위해 훈련 데이터를 변경해서는 안 됩니다. 또한 시스템 메시지가 어떻게 사용되는지 보고합니다: 없음, 하나만 공유, 혼합(references/chat-formats.md 참조).

2. 시스템 사전 점검

${CLAUDE_SKILL_DIR}/scripts/run preflight.py --params-b <parameters in billions> --out <runs>/<run>

여유 GPU 메모리는 전체 메모리보다 중요합니다. 게임, GPU 가속 브라우저, 로컬 서버가 여전히 점유하고 있는 모델(ollama ps, ollama stop <model>로 언로드) 때문에 메모리가 부족할 수 있습니다. 사전 점검에서 다른 GPU 사용자가 나열되면 사용자에게 알리고 결정을 맡기세요. 프로세스를 종료하지 마세요. --params-b는 메모리 필요량을 추정합니다(3B 모델 4비트, 시퀀스 길이 1024, 배치 크기 4에서 최대 6.6GiB, 7B 모델에서 8.1GiB). 여유 메모리가 부족하면 대신 사용할 --batch-size/--grad-accum 쌍을 출력합니다. 두 번의 실행으로 추정한 값이므로, 다른 크기나 시퀀스 길이에 대해서는 --need-gib을 전달하고 smoke run이 보고하는 최대값을 확인하세요.

임포트가 실패하면 환경이 손상된 것입니다. 재설치 전에 references/troubleshooting.md를 참조하세요.

3. Smoke run

${CLAUDE_SKILL_DIR}/scripts/run train.py --model <base> --data <data> --out <runs>/<run>-smoke --max-steps 2

종료 코드만 확인하지 말고 출력을 읽으세요:

• 첫 번째 예제가 렌더링된 방식: 상단의 시스템 라인은 모델이 학습할 예상 형식입니다.
• 손실을 받는 토큰: 질문이 아닌 응답만 손실을 받습니다.
• 토큰 길이: 잘림 경고는 --max-seq-length를 늘리거나 예제를 제거해야 함을 의미합니다.
• 서버가 보내야 하는 시스템 턴과 관련 경고. Qwen3, Qwen3.5와 같은 사고 템플릿은 모든 훈련된 응답 앞에 빈 사고 응답 블록을 추가합니다. 앱이 응답에서 이를 받게 되며 제거해야 한다고 사용자에게 알리세요.

4. 전체 실행

${CLAUDE_SKILL_DIR}/scripts/run train.py --model <base> --data <data> --out <runs>/<run>

잠시 실행됩니다(3B 모델에서 수천 개 예제에 대해 몇 분, 7B 모델은 더 오래 걸림). 세션을 열어두지 않고 Bash 도구의 백그라운드 옵션으로 시작하세요(도구는 출력을 파일에 저장하며, 이것이 로그입니다. 명령에 >, ;, &&를 추가하지 마세요. 사전 승인은 표시된 대로의 런처 명령만 다룹니다). ${CLAUDE_SKILL_DIR}/scripts/run train_status.py <runs>/<run>로 진행 상태를 확인하세요: 단계, 손실, 가장 낮은 검증 손실을 기록한 단계, 남은 시간(마지막 체크포인트 기준). 충돌 후에는 --resume을 사용하세요. 훈련 손실과 검증 손실, 최대 GPU 메모리를 보고하세요. 검증 손실이 훈련 손실보다 훨씬 높으면 과적합을 의미합니다. 에폭 수를 줄이거나 더 많은 데이터가 필요합니다.

5. 내보내기

${CLAUDE_SKILL_DIR}/scripts/run export_gguf.py --run <runs>/<run>

3B 모델의 경우 몇 분, 7B 모델의 경우 10분 이상 소요됩니다(병합, 변환, 양자화). Bash 도구가 포그라운드 명령을 허용하는 시간보다 깁니다. 훈련과 마찬가지로 백그라운드에서 시작하고 완료될 때까지 기다리세요. GGUF 파일을 <run>/gguf/에 쓰고, 크기와 체크섬을 run.json에 기록합니다. 병합된 16비트 모델(수 GB, --keep-merged를 사용하면 유지되며 GGUF는 <run>/gguf_gguf/에 남음)과 Unsloth가 GGUF 옆에 작성하는 Modelfile을 제거합니다. 해당 Modelfile은 기본 템플릿을 사용하므로 훈련에 사용된 레이아웃이 아니므로, Unsloth의 ollama create 힌트를 따르지 마세요. 모든 내보내기에서 llama.cpp 변환기에 대한 [CRITICAL] 경고가 예상됩니다. 사용자에게 그 의미를 설명하고(references/troubleshooting.md 참조), 내보내기를 중단하지 않습니다. 이제 run 폴더는 서빙 준비가 되었습니다. ollama-model 스킬로 계속 진행하거나, run.json의 chat 섹션을 모델을 서빙하는 모든 도구에 전달하세요(references/run-json.md 참조).

6. 정리 (먼저 물어볼 것)

모델이 내보내지고 평가된 후, 재개 또는 설정 확인에만 필요한 파일을 삭제할 것을 제안하세요: <run>/checkpoints/ (--resume용, 7B 모델의 경우 수 GB) 및 <run>-smoke 폴더. 각각이 차지하는 공간을 말하고 사용자가 동의한 것만 삭제하세요. adapter/와 run.json은 유지하세요. 이들은 크기가 작고 새 내보내기와 릴리스 노트에 필요합니다.

규칙

• 평가 결과를 좋게 보이기 위해 데이터셋을 절대 변경하지 말고, 훈련 데이터로 평가하지 마세요.
• 묻지 않고 Unsloth 환경에 패키지를 설치하거나 업그레이드하지 마세요. 해당 환경의 torch/CUDA 조합은 깨지기 쉽습니다.
• run 폴더나 체크포인트를 삭제하기 전에 물어보세요.