99. 명령어 치트시트 (한 장 요약)#
🎯 용도: 책상 옆에 붙여두고 빠르게 참조
💾 인쇄 권장: PDF로 저장 후 출력
🚀 가장 자주 쓰는 명령#
# 환경 (1회만)
make setup && make setup-mlx
# 첫 실험 (더미)
make dummy && make data-dummy && make all-mlx
# 실전 (실제 데이터)
make data && make all-mlx
# 추론 테스트
ollama run mediconsol-v1
📋 전체 Makefile 타겟#
| 명령 | 하는 일 | 예상 시간 |
|---|---|---|
make setup |
기본 패키지 | 2분 |
make setup-mlx |
MLX 설치 | 1분 |
make dummy |
더미 데이터 250건 생성 | 10초 |
make data |
실제 데이터 전처리 | 1분 |
make data-dummy |
더미 데이터 전처리 | 10초 |
make train-mlx |
MLX LoRA 학습 ⭐ | 3-5시간 |
make fuse-mlx |
어댑터 병합 | 10분 |
make convert |
GGUF 변환 (Q4_K_M) | 15분 |
make deploy |
Ollama 등록 | 2분 |
make evaluate |
품질 평가 | 5분 |
make all-mlx |
데이터부터 평가까지 전체 | 4-6시간 |
make upload-all |
HuggingFace 백업 | 10분 |
make clean |
outputs/ 정리 | 5초 |
🔧 하이퍼파라미터 프리셋#
scripts/02b_train_mlx.sh 상단 수정:
첫 실험 (기본) ⭐#
MVP (실전 데이터 1500건)#
빠른 실험#
메모리 절약 (OOM 시)#
🩺 헬스 체크#
# 하드웨어 확인
uname -m # arm64 (Apple Silicon)
sysctl hw.memsize | awk '{print $2/1024/1024/1024 " GB"}' # 24GB
# Python
python3 --version # 3.10+
# MLX
python3 -c "import mlx_lm; print('OK')"
# Ollama
ollama list # mediconsol-v1:latest 있어야 함
brew services list | grep ollama
# Hugging Face
huggingface-cli whoami
📊 학습 중 모니터링#
다른 터미널에서 (학습 중)#
# 리소스 사용량
top -o mem # 메모리 많이 쓰는 앱
htop # 더 예쁘게
# 메모리 압박 확인
vm_stat | head
# Swap 사용량 (문제 신호)
sysctl vm.swapusage
정상 범위#
| 지표 | 정상 값 |
|---|---|
| 메모리 사용 | 10-15 GB |
| It/sec | 0.8-1.2 |
| Swap used | < 1 GB |
| Loss (초기) | 2.0-2.8 |
| Loss (수렴) | 0.7-1.2 |
🆘 응급 처치#
Ctrl+C로 학습 중단#
# 100 iter마다 저장되어 있음
ls outputs/mlx_adapter/*_adapters.safetensors
# 재개
python3 -m mlx_lm.lora \
--model outputs/mlx_base_4bit \
--train \
--data data/processed/mlx \
--adapter-path outputs/mlx_adapter \
--resume-adapter-file outputs/mlx_adapter/adapters.safetensors \
--iters 300
OOM (메모리 부족)#
# 1. 다른 앱 전부 닫기 (Chrome 특히!)
# 2. scripts/02b_train_mlx.sh 에서:
BATCH_SIZE=1 # 2 → 1
LORA_R=16 # 32 → 16
Loss NaN (폭주)#
즉시 Ctrl+C, LR 낮추기:
롤백 (3분)#
🎯 Ollama 명령#
모델 관리#
ollama list # 전체 목록
ollama show mediconsol-v1 # 상세 정보
ollama show --modelfile mediconsol-v1 # Modelfile
ollama rm mediconsol-v1:1.0.0 # 삭제
ollama cp mediconsol-v1:1.0.0 mediconsol-v1:latest # 태그 복사
실행#
# 대화형
ollama run mediconsol-v1
# 한 번만
ollama run mediconsol-v1 "KPCS가 뭔가요?"
# 온도 조절 (일관성 ↑)
ollama run mediconsol-v1 --option temperature=0.3
# API 호출
curl http://localhost:11434/api/generate -d '{
"model": "mediconsol-v1:latest",
"prompt": "KPCS가 뭔가요?",
"stream": false
}'
서비스#
brew services start ollama
brew services stop ollama
brew services restart ollama
tail -f ~/.ollama/logs/server.log
📁 디렉토리 구조#
mediconsol-llm/
├── data/
│ ├── raw/ ← 원본 데이터 (수동 추가)
│ ├── samples/ ← 더미 데이터
│ └── processed/ ← 전처리 결과 (자동)
├── outputs/
│ ├── mlx_base/ ← MLX 변환된 베이스
│ ├── mlx_base_4bit/ ← 4bit 양자화
│ ├── mlx_adapter/ ← 학습된 어댑터 ⭐
│ ├── merged/ ← 병합 모델
│ └── *.gguf ← Ollama용 파일
├── scripts/
│ ├── 02b_train_mlx.sh ← 학습 (자주 수정)
│ └── ...
├── training/ ← 이 매뉴얼들
└── Makefile ← 명령 정의
💾 백업 체크리스트#
학습 완료 후 반드시 백업#
# 1. 어댑터 (가장 중요)
tar -czf backups/v1.0.0_adapter_$(date +%Y%m%d).tar.gz \
outputs/mlx_adapter/adapters.safetensors
# 2. 학습 데이터
cp -r data/processed/ archives/v1.0.0/data/
# 3. 평가 결과
cp outputs/eval_report.json archives/v1.0.0/
# 4. HuggingFace 업로드 (클라우드 백업)
export HF_TOKEN="hf_xxx"
make upload-all
절대 지우지 말 것#
data/raw/- 원본 데이터outputs/mlx_adapter/adapters.safetensors- 어댑터outputs/eval_report.json- 평가 기록data/bad_cases/- 개선 단서
📅 월간 재학습 루틴#
첫째 주 일요일 밤:
20:00 데이터 수집 마감
21:00 학습 시작
└─ tmux new -s train
make all-mlx
익일 월요일:
06:00 학습 완료 확인
09:00 자동 평가
10:00 블라인드 평가 (수간호사)
13:00 배포 결정
14:00 프로덕션 전환 (or 롤백)
🔐 PHI 안전 체크#
학습 전 반드시#
# PHI 패턴 자동 스캔
python3 -c "
import re
patterns = [r'\d{6}-\d{7}', r'01[0-9]-?\d{3,4}-?\d{4}']
with open('data/processed/train.jsonl') as f:
for i, line in enumerate(f, 1):
for pat in patterns:
if re.search(pat, line):
print(f'⚠️ Line {i}: 위험')
break
print('✅ 스캔 완료')
"
발견 시#
- 즉시 해당 라인 수정 또는 삭제
- 원본 (data/raw/)에서도 확인
- 전체 재전처리:
make data
🎓 교육 문서 위치#
| 필요할 때 | 읽을 문서 |
|---|---|
| 처음 시작 | training/index.md |
| LLM 기초 | training/01_WHAT_IS_LLM.md |
| 용어 모르겠음 | training/02_GLOSSARY.md |
| 그림으로 이해 | training/03_MENTAL_MODEL.md |
| 처음 돌려보기 | training/04_FIRST_RUN.md ⭐ |
| 학습 결과 해석 | training/05_UNDERSTANDING_OUTPUT.md |
| 에러 났을 때 | training/06_TROUBLESHOOTING.md |
| 데이터 준비 | training/07_DATA_COLLECTION.md |
| 설정 조정 | training/08_HYPERPARAMETERS.md |
| 품질 평가 | training/09_EVALUATION.md |
| 재학습/운영 | training/10_OPERATIONS.md |
| 기타 궁금증 | training/99_FAQ.md |
🌐 유용한 링크#
HuggingFace Gemma 4:
https://huggingface.co/google/gemma-4-E4B-it
MLX-LM GitHub:
https://github.com/ml-explore/mlx-lm
Ollama Docs:
https://github.com/ollama/ollama
내 HF 저장소 (배포 후):
https://huggingface.co/mediconsol/mediconsol-v1
로컬 Ollama API:
http://localhost:11434
Cloudflare Tunnel (운영 시):
https://llm.mediconsol.com
⚡ 원 라이너 모음#
# 학습 중 실시간 Loss 모니터
tail -f outputs/training.log | grep -E "Train loss|Val loss"
# 카테고리 분포 확인
python3 -c "import json;from collections import Counter;print(Counter(json.loads(l).get('category','?') for l in open('data/processed/train.jsonl')))"
# 데이터 개수
wc -l data/processed/*.jsonl
# GGUF 파일 크기
ls -lh outputs/*.gguf | awk '{print $5, $9}'
# 맥미니 온도 (높으면 쿨링 필요)
sudo powermetrics --samplers smc -n 1 | grep -i "CPU die"
# Ollama 디스크 사용량
du -sh ~/.ollama/models/
# 학습 시작 → 완료 예상 시각
echo "완료 예상: $(date -v+5H)"
📞 도움 청하기#
Claude Code에게 물어보기#
자가 진단 순서#
- 에러 메시지 전체 복사
- 치트시트에서 유사 상황 찾기
06_TROUBLESHOOTING.md참조- 그래도 막히면 Claude Code에게
- GitHub Issues 검색 (MLX, Ollama, llama.cpp)
✅ 오늘의 체크리스트#
처음 시작하는 날:
- [ ] make setup && make setup-mlx
- [ ] make dummy && make data-dummy
- [ ] make train-mlx 시작 (tmux 권장)
- [ ] 커피 ☕
- [ ] 완료 후 make fuse-mlx convert deploy evaluate
- [ ] ollama run mediconsol-v1로 첫 대화
매월 첫째 주: - [ ] Bad case 정리 - [ ] 신규 데이터 추가 - [ ] PHI 스캔 통과 - [ ] 일요일 밤 학습 - [ ] 월요일 평가 - [ ] 배포 or 롤백
💡 한 줄 요약#
처음:
make setup && make setup-mlx && make dummy && make all-mlx(하루)
매월: 데이터 추가 → 학습 → 평가 → 배포 (1주)
응급:ollama cp mediconsol-v1:1.0.0 mediconsol-v1:latest(3분)