Jackrong-llm-finetuning-guide — 초보자용 엔드투엔드 LLM 파인튜닝 학습 파이프라인

한 줄 요약: Google Colab/Kaggle 환경에서 Unsloth, LoRA/PEFT, SFT, GRPO, Hugging Face Hub, GGUF 내보내기를 한 흐름으로 묶어 LLM 파인튜닝을 재현 가능하게 학습하도록 만든 교육형 저장소다.

분석 기준일: 2026-04-21
검토 범위: README.md, docs/README_ko.md, train_code/*.ipynb, High-fidelity Dataset/, guidePDF/, download_datasets.py, split_large_files.py, Issues/PR 탭, Wiki/Discussions 접근 여부.

---

Quick Links

구분	링크
GitHub Repository	https://github.com/R6410418/Jackrong-llm-finetuning-guide
Hugging Face Profile	https://huggingface.co/Jackrong
Training Notebooks	https://github.com/R6410418/Jackrong-llm-finetuning-guide/tree/main/train_code
Colab: Qwopus3.5 27B SFT	https://colab.research.google.com/github/R6410418/Jackrong-llm-finetuning-guide/blob/main/train_code/Qwopus3-5-27b-Colab.ipynb
Kaggle: Qwen3.5 9B SFT	https://kaggle.com/kernels/welcome?src=https://github.com/R6410418/Jackrong-llm-finetuning-guide/blob/main/train_code/Qwen3.5-9B-Neo-Kaggle.ipynb
Kaggle: Qwopus3.5 35B SFT	https://kaggle.com/kernels/welcome?src=https://github.com/R6410418/Jackrong-llm-finetuning-guide/blob/main/train_code/Qwopus-3.5-35B-A3B-Kaggle.ipynb
Kaggle: Llama3.2-R1 GRPO	https://kaggle.com/kernels/welcome?src=https://github.com/R6410418/Jackrong-llm-finetuning-guide/blob/main/train_code/Llama-3.2-3B-R1-Zero-GRPO.ipynb
PDF Guide	https://github.com/R6410418/Jackrong-llm-finetuning-guide/blob/main/guidePDF/Qwopus3-5-27b-Colab_complete_guide_to_llm_finetuning.pdf
Unsloth	https://github.com/unslothai/unsloth
PyTorch	https://pytorch.org/
Hugging Face Hub	https://huggingface.co/
논문 링크	저장소 README와 Wiki/Discussion에서 별도 공식 논문 링크는 확인되지 않았다.

 

Wiki/Discussions 상태: /wiki는 저장소 메인 페이지로 리다이렉트되며 별도 Wiki 문서는 확인되지 않았다. /discussions는 404로 확인되어 Discussions 탭은 공개 활성화 상태가 아닌 것으로 보인다. 커뮤니티 논의는 Issues 중심이며, 열린 이슈는 생각의 사슬 비활성화, 멀티모달 능력 보존형 파인튜닝, 평가 리포트 PDF 요청, MiniMax 모델 지원 등으로 구성된다.

---

Visual Asset Map

이 저장소에서 확인된 실질적 다이어그램 자산은 README의 Project Overview 이미지 1개였다. Colab/Kaggle 실행 배지와 Shields 배지는 기능 설명용 UI 스크린샷으로 보기 어려워 핵심 본문 이미지에서는 제외했다. 아래 두 이미지는 노트북과 코드 구조 분석을 바탕으로 작성한 보조 도식이다.

파일	출처	배치 섹션	설명
figures/project_overview.png	README 원본 이미지	Architecture	데이터 수집 → 정규화 → SFT/RL → 모델/16-bit/GGUF 산출 흐름을 시각화한 프로젝트 개요
figures/pipeline_architecture.png	분석 기반 재구성	Architecture	노트북 코드 흐름을 계층형 시스템 아키텍처로 재구성
figures/notebook_matrix.png	분석 기반 재구성	Key Features	4개 실행 노트북의 런타임, 모델, 파이프라인, 역할 비교
figures/repo_structure.png	분석 기반 재구성	Quick Links 이후	저장소 폴더와 핵심 파일 역할 요약

 

 

Figure: 저장소의 실제 상위 구조를 문서·노트북·데이터셋·PDF·보조 스크립트 관점에서 요약한 도식.

---

Key Features

1. 0-to-1 학습 경로

저장소의 중심 메시지는 “브라우저와 클라우드 노트북만으로 LLM 파인튜닝의 전체 생애주기를 따라간다”는 것이다. README는 기술 배경이 약한 사용자도 Google 계정, Colab/Kaggle, 공개 데이터셋, 오픈소스 모델을 이용해 데이터 준비부터 학습, 추론, 배포까지 접근할 수 있도록 구성되어 있다.

2. SFT 중심의 실행 노트북 3종

train_code/에는 Qwen/Qwopus 계열 SFT 노트북이 3개 포함되어 있다. 각각 Colab 또는 Kaggle을 대상으로 하며, FastLanguageModel.from_pretrained(), get_peft_model(), SFTTrainer, train_on_responses_only()를 통해 LoRA 기반 지도 미세조정을 실행한다.

 

 

Figure: 4개 노트북의 런타임, 파이프라인, 베이스 모델, 컨텍스트 길이, 핵심 역할을 비교한 표.

3. Llama3.2-R1용 Cold-start SFT + GRPO 파이프라인

Llama-3.2-3B-R1-Zero-GRPO.ipynb는 먼저 OpenMathReasoning-mini로 <think>...</think><answer>\boxed{...}</answer> 형식을 학습시키는 Cold-start SFT를 수행한 뒤, open-r1/DAPO-Math-17k-Processed 기반 GRPO 단계로 넘어간다. GRPO reward 함수는 샘플 출력 확인, 구조 보상, boxed answer 검증, n-gram 반복 패널티를 포함한다.

4. 다중 데이터셋 정규화와 샘플링 패턴

Qwopus/Qwen SFT 노트북은 서로 다른 데이터 스키마를 conversations 구조로 정규화한다. 예를 들어 problem/thinking/solution, conversation=[{from,value}], messages=[{role,content}], raw JSON/Parquet 기반 데이터가 하나의 chat-template 적용 가능한 형식으로 변환된다. 이후 길이 필터, 형식 검증, 중복 제거, 셔플링을 거쳐 dataset_text_field="text"로 학습에 투입된다.

5. 단일 GPU 친화적 효율화

저장소는 Unsloth, 4-bit 로딩, LoRA/PEFT, gradient checkpointing, adamw_8bit 또는 paged_adamw_8bit를 결합한다. README는 이 구조를 Colab 같은 단일 GPU 제약 환경에서 대규모 모델 학습의 진입 장벽을 낮추는 핵심 요소로 설명한다.

6. Hugging Face Hub 및 GGUF 배포 흐름

학습 후 산출물은 LoRA adapter 저장, merged 16-bit export, GGUF 변환으로 이어진다. Qwopus/Qwen 노트북에는 model.save_pretrained(), model.push_to_hub_merged(), model.push_to_hub_gguf() 흐름이 있고, Llama GRPO 노트북은 Q4_K_M 및 Q8_0 GGUF 저장 루틴을 포함한다. 이는 연구 노트북을 로컬 추론 산출물까지 연결하는 장점이다.

7. 고품질 증류 데이터셋 컬렉션

High-fidelity Dataset/에는 reasoning, math/STEM, code, instruction, multi-turn chat 관련 24개 데이터셋 폴더가 노출되어 있다. README는 이 데이터셋들이 DeepSeek, Qwen, GLM, GPT-OSS 계열 대형 모델의 증류 결과와 CoT 형식을 중심으로 구성된다고 설명한다.

8. 실험 추적과 Secret 관리

Colab 노트북은 google.colab.userdata, Kaggle 노트북은 kaggle_secrets.UserSecretsClient를 사용해 WANDB_API_KEY와 HF_TOKEN을 읽는다. W&B는 학습 로그와 checkpoint 추적에 사용되며, Hugging Face token은 모델 또는 GGUF 산출물을 Hub에 업로드할 때 사용된다.

---

Tech Stack

레이어	사용 기술	저장소에서 확인된 버전/설정
실행 환경	Google Colab, Kaggle Notebook	README의 1-click notebook 링크 중심
주 언어	Jupyter Notebook, Python	GitHub 언어 비중: Jupyter Notebook 97.9%, Python 2.1%
모델 로딩/효율화	Unsloth, Unsloth Zoo, PEFT/LoRA	일부 노트북은 git+https://github.com/unslothai/unsloth 및 unsloth_zoo 설치
딥러닝 프레임워크	PyTorch	Qwopus 계열: torch==2.8.0, triton>=3.3.0
Transformer	Hugging Face Transformers	Qwopus 27B/35B: transformers==5.2.0; Qwen 9B: 5.3.0; Llama GRPO: 4.56.2
RL/SFT Trainer	TRL	trl==0.22.2
데이터	Hugging Face Datasets, pandas, numpy	Kaggle/Llama 노트북: datasets==4.3.0; HF Hub >=0.34.0
메모리 최적화	bitsandbytes, xformers, flash-linear-attention, causal-conv1d	Qwopus 계열: xformers==0.0.32.post2, causal_conv1d==1.6.0
추론/GRPO 지원	vLLM	Llama GRPO 노트북: T4면 vllm==0.9.2, 그 외 vllm==0.10.2
실험 추적	Weights & Biases	WANDB_API_KEY 기반 로그인
배포	Hugging Face Hub, GGUF	LoRA 저장, merged 16-bit push, GGUF push/save
보조 스크립트	download_datasets.py, split_large_files.py	HF dataset snapshot 다운로드, 1.5GB chunking helper

 

주의할 점: 저장소에는 requirements.txt나 pyproject.toml 같은 단일 패키지 매니페스트가 없다. 노트북마다 설치 버전이 다르므로 재현성을 높이려면 사용하려는 노트북별 환경을 별도로 고정하는 것이 안전하다.

---

Architecture

 

Figure: README에 포함된 원본 Project Overview. 시작점은 Google/Colab 접근과 데이터 파일이며, 중앙은 Unsloth 기반 모델 적재·정규화·SFT/RL 후처리, 우측은 trained LLM과 GGUF/16-bit merge 산출물을 나타낸다.

계층별 구조

1. Input/Data Layer
   Hugging Face dataset, raw JSON, Parquet, 로컬 데이터셋 폴더가 입력이다. 각 노트북은 데이터셋별 스키마를 감지해 샘플링하고, 목표 샘플 수보다 실제 데이터가 적으면 min(sample_count, len(ds)) 방식으로 제한한다.
2. Normalization Layer
   서로 다른 필드 구조를 conversations 배열로 통합한다. reasoning 데이터는 <think> 또는 reasoning block과 answer를 분리하거나 재조립하며, multi-turn 데이터는 role/content 형식으로 변환한다.
3. Prompt/Template Layer
   Qwen 계열은 qwen3-thinking chat template을 중심으로, Llama GRPO 노트북은 strict reasoning format을 중심으로 학습 문자열을 만든다.
4. Training Layer
   SFT는 SFTTrainer와 SFTConfig가 담당한다. GRPO는 GRPOTrainer와 GRPOConfig가 담당하며, reward function으로 구조 준수, boxed answer 정확도, 반복 패널티를 결합한다.
5. Adapter/Export Layer
   LoRA adapter를 저장한 뒤, 필요에 따라 16-bit merged model 또는 GGUF quantization 산출물을 만든다. 이 구조는 “실험용 노트북”에서 “로컬 실행 가능한 모델 산출물”까지 연결한다.

Figure: 노트북 코드와 README 설명을 바탕으로 재구성한 시스템 흐름. 데이터 수집, 정규화, template 적용, SFT/GRPO, LoRA/merged/GGUF 내보내기, Hub/로컬 배포 계층을 분리했다.

저장소 구조 관점

Jackrong-llm-finetuning-guide/
├── README.md
├── docs/
│   ├── README_ko.md
│   ├── README_zh.md
│   └── README_ja.md
├── train_code/
│   ├── Qwopus3-5-27b-Colab.ipynb
│   ├── Qwen3.5-9B-Neo-Kaggle.ipynb
│   ├── Qwopus-3.5-35B-A3B-Kaggle.ipynb
│   └── Llama-3.2-3B-R1-Zero-GRPO.ipynb
├── High-fidelity Dataset/
│   └── 24개 reasoning/math/code/chat 데이터셋 폴더
├── guidePDF/
│   └── Qwopus3-5-27b-Colab_complete_guide_to_llm_finetuning.pdf
├── download_datasets.py
└── split_large_files.py

노트북별 동작 원리 요약

노트북	주요 모델	핵심 동작	데이터 흐름
Qwopus3-5-27b-Colab.ipynb	unsloth/Qwen3.5-27B	4-bit 로딩, LoRA r=64, SFT, W&B, HF/GGUF export	nohurry/Opus-4.6, Jackrong/Qwen3.5-reasoning-700x, Roman1111111/claude-opus-4.6-10000x
Qwen3.5-9B-Neo-Kaggle.ipynb	Unsloth/Qwen3.5-9B	Step-3.5 raw JSON sampling, dedup, SFT	Jackrong/Competitive-Programming-python-blend, stepfun-ai/Step-3.5-Flash-SFT
Qwopus-3.5-35B-A3B-Kaggle.ipynb	unsloth/Qwen3.5-35B-A3B	LoRA r=32, SFT, multi-source reasoning mix	Opus/Qwen reasoning/chat 데이터 3종
Llama-3.2-3B-R1-Zero-GRPO.ipynb	unsloth/Llama-3.2-3B-Instruct	Cold-start SFT 후 GRPO	unsloth/OpenMathReasoning-mini, open-r1/DAPO-Math-17k-Processed

---

Usage & Setup

1. 브라우저 기반 실행

가장 권장되는 경로는 README의 Colab/Kaggle 버튼을 사용하는 것이다.

1. Colab 또는 Kaggle에서 대상 노트북을 연다.
2. Secret Manager에 WANDB_API_KEY와 HF_TOKEN을 등록한다.
3. 런타임을 GPU로 설정한다.
4. 설치 셀 → 모델 로딩 셀 → 데이터 처리 셀 → 학습 셀 → export 셀 순서로 실행한다.

저장소에는 별도 터미널 캡처나 실행 GIF가 포함되어 있지 않아, 이 섹션은 명령 요약으로 대체한다.

2. 로컬 실험용 최소 명령

git clone https://github.com/R6410418/Jackrong-llm-finetuning-guide.git
cd Jackrong-llm-finetuning-guide

python -m venv .venv
source .venv/bin/activate

pip install -U uv jupyterlab

Qwopus 27B/35B 계열 노트북에 가까운 환경:

uv pip install "torch==2.8.0" "triton>=3.3.0" torchvision bitsandbytes xformers==0.0.32.post2
uv pip install "unsloth_zoo[base] @ git+https://github.com/unslothai/unsloth-zoo"
uv pip install "unsloth[base] @ git+https://github.com/unslothai/unsloth"
uv pip install --upgrade --no-deps tokenizers trl==0.22.2 unsloth unsloth_zoo
uv pip install transformers==5.2.0
uv pip install --no-build-isolation flash-linear-attention causal_conv1d==1.6.0

Qwen 9B Kaggle 노트북에 가까운 환경:

pip install unsloth
pip install sentencepiece protobuf "datasets==4.3.0" "huggingface_hub>=0.34.0" hf_transfer
pip install --no-deps unsloth_zoo bitsandbytes accelerate peft trl triton unsloth
pip install transformers==5.3.0
pip install --no-deps trl==0.22.2

Llama GRPO 노트북에 가까운 환경:

uv pip install -U unsloth torchvision bitsandbytes xformers
uv pip install "huggingface_hub>=0.34.0" "datasets==4.3.0"
uv pip install transformers==4.56.2
uv pip install --no-deps trl==0.22.2

환경 변수를 사용하는 로컬 실행 예시:

export WANDB_API_KEY="..."
export HF_TOKEN="..."

jupyter lab train_code/Qwopus3-5-27b-Colab.ipynb

3. 데이터셋 다운로드

pip install huggingface_hub
python download_datasets.py

단, download_datasets.py는 단순 다운로드만 하는 스크립트가 아니라 git add, git commit, git push origin main까지 실행하도록 작성되어 있다. 개인 fork나 로컬 분석 환경에서는 push 라인을 주석 처리한 뒤 실행하는 편이 안전하다.

4. 대용량 파일 분할

python split_large_files.py

split_large_files.py는 특정 JSONL 파일을 1.5GB 단위 chunk로 나누고 원본을 삭제하도록 되어 있다. 데이터 원본 보존이 필요하다면 실행 전 백업을 먼저 만드는 것이 좋다.

---

Personal Insights

의료 AI 관점

이 저장소의 장점은 도메인 데이터 정규화 패턴이 명확하다는 점이다. 의료 QA, 임상 노트 요약, guideline 기반 triage assistant를 만들 때도 원천 데이터는 문진 기록, guideline paragraph, QA pair, ICD/SNOMED 코드, discharge summary처럼 서로 다른 schema를 가진다. 이 프로젝트의 conversations 통합 방식은 그런 heterogeneous clinical data를 instruction tuning용 공통 포맷으로 묶는 데 직접 응용 가능하다.

 

다만 의료 AI에서는 생각의 사슬(CoT)을 그대로 노출하는 설계가 항상 바람직하지 않다. 내부 reasoning supervision은 유용할 수 있지만, 사용자에게는 검증 가능한 근거, guideline citation, 불확실성, 의뢰/응급 판단 기준을 중심으로 응답해야 한다. 특히 PHI 제거, consent, data lineage, audit log, adverse-event escalation, model card 관리가 추가되어야 한다.

Bioinformatics 관점

Bioinformatics에서는 “정답이 하나인 수학 문제”보다 pipeline reproducibility가 중요하다. 이 저장소의 SFT/GRPO 구조는 variant annotation, RNA-seq workflow, protein design prompt, literature mining agent를 훈련하는 기반이 될 수 있다. 그러나 reward 설계는 단순 boxed answer가 아니라 다음처럼 바뀌어야 한다.

• 명령어가 실제로 실행 가능한가
• FASTQ/BAM/VCF 파일 경로와 reference genome 버전이 일관적인가
• Snakemake/Nextflow rule이 dependency graph를 깨뜨리지 않는가
• BioPython, scikit-bio, samtools, bcftools 호출이 unit test를 통과하는가
• gene/protein identifier가 HGNC/UniProt/Ensembl 같은 canonical namespace로 정규화되는가

즉, GRPO reward를 텍스트 평가가 아니라 도구 실행 결과, schema validation, ontology matching, regression test와 결합해야 실용성이 높아진다.

Autonomous Agent 개발 관점

이 프로젝트의 Llama3.2-R1 노트북은 agent policy training의 초기 형태로 볼 수 있다. Cold-start SFT로 구조화된 reasoning/action format을 먼저 안정화하고, GRPO reward로 올바른 출력 구조와 정답성을 강화하는 접근은 tool-calling agent에도 적용 가능하다.

자율 에이전트로 확장하려면 reward matrix가 다음 요소를 포함해야 한다.

• tool call JSON schema 준수
• 불필요한 tool call 감소
• hallucinated tool/result 사용 패널티
• plan-step consistency
• sandbox 실행 성공률
• task completion latency와 cost
• 반복 행동 또는 무한 루프 억제

이 저장소는 “학습 파이프라인을 이해하기 위한 교육형 skeleton”으로 적합하다. production agent로 쓰려면 평가 harness, deterministic replay, tool sandbox, safety policy, regression benchmark가 추가되어야 한다.

기술적 개선 제안

1. requirements.txt 또는 pyproject.toml을 노트북별로 분리하면 재현성이 크게 좋아진다.
2. download_datasets.py의 git push 동작은 --sync-git 같은 명시 플래그 뒤로 숨기는 것이 안전하다.
3. notebook output artifact, W&B example screenshot, training loss curve를 README에 추가하면 사용자 이해도가 높아진다.
4. GRPO reward 함수에 unit-test 기반 reward hook을 추가하면 code/bioinformatics agent 훈련으로 확장하기 쉽다.
5. 의료/생명과학 도메인 적용 시 dataset card, license scan, PHI scrubber, prompt safety filter를 pipeline 전단에 넣는 것이 필요하다.

---

Source Notes

• README는 저장소를 초보자와 개발자를 위한 교육용 LLM fine-tuning repository로 설명하며, SFT와 향후 RL 구현, 데이터 처리, 배포 전략을 포함한다고 명시한다.
• train_code/에는 4개 실행 노트북이 있으며, Qwopus/Qwen SFT 3종과 Llama3.2-R1 GRPO 1종으로 구성된다.
• High-fidelity Dataset/에는 24개 데이터셋 폴더가 확인되며, README는 reasoning, math/STEM, code, instruction/multi-turn chat 카테고리로 설명한다.
• Issues에는 기능 요청과 모델 지원 요청이 있으나, Pull requests는 공개 탭 기준 open/closed PR이 없는 것으로 확인된다.
• Wiki와 Discussions는 별도 문서/게시판으로 확인되지 않았다.