콘텐츠로 이동

06. 막힐 때 대처법 (Troubleshooting)#

📚 학습 목표: 흔한 문제를 혼자 해결할 수 있게
🎯 사용법: 문제 생기면 목차에서 유사한 것 찾아 점프

목차#

환경 설정 문제#

데이터 준비 문제#

학습 문제#

배포 문제#

성능/운영 문제#

E1. make setup 에러#

증상#

ERROR: Could not find a version that satisfies the requirement ...

원인#

  • Python 버전 맞지 않음
  • pip 버전 오래됨

해결#

# Python 버전 확인
python3 --version
# Python 3.10+ 여야 함. 아니면 업그레이드

# pip 업그레이드
python3 -m pip install --upgrade pip

# 다시 시도
make setup

E2. make setup-mlx 실패#

증상#

❌ MLX는 Apple Silicon 전용

원인#

Intel Mac에서 실행 중

해결#

MLX는 Intel Mac에서 설치 불가. Apple Silicon(M1/M2/M3/M4)에서 실행해야 함.

맥미니 M4에서 실행했는데도 에러면: 

# 아키텍처 확인
uname -m
# "arm64"가 나와야 함. "x86_64"면 Rosetta 환경

# Rosetta 터미널 닫고 네이티브 arm64 터미널 열기
# 또는 새 터미널에서:
arch -arm64 bash
make setup-mlx

E3. llama.cpp 빌드 실패#

증상#

error: Metal framework not found

해결#

# Xcode CLI tools 설치
xcode-select --install

# cmake 업그레이드
brew upgrade cmake

# 재빌드
cd ~/llama.cpp
rm -rf build
cmake -B build -DGGML_METAL=ON
cmake --build build --config Release -j

E4. Ollama 설치/실행 문제#

증상 A: ollama: command not found#

brew install ollama
brew services start ollama

증상 B: Error: could not connect to ollama server#

# 서비스 상태 확인
brew services list | grep ollama

# 재시작
brew services restart ollama

# 또는 수동 실행
ollama serve &

증상 C: 모델 목록이 안 나옴#

# 로그 확인
tail -f ~/.ollama/logs/server.log

# 완전 재설치
brew services stop ollama
brew uninstall ollama
brew install ollama
brew services start ollama

D1. 더미 데이터 생성 실패#

증상#

FileNotFoundError: scripts/00_generate_dummy.py

해결#

# 프로젝트 루트인지 확인
pwd
# → .../mediconsol-llm 여야 함

# 파일 있는지
ls scripts/00_generate_dummy.py

# 실행 권한
chmod +x scripts/*.sh

D2. make data 에러#

증상 A: data/raw/ 디렉토리 없음#

mkdir -p data/raw/{01_nursing,02_management,03_medical_terms,04_consulting,05_communication}

증상 B: JSON decode error at line X#

데이터 파일이 손상됨. 해당 줄 확인:

# 몇 번째 줄이 문제인지
sed -n '5p' data/raw/01_nursing/data.jsonl

# Python으로 검증
python3 -c "
import json
with open('data/raw/01_nursing/data.jsonl') as f:
    for i, line in enumerate(f, 1):
        try:
            json.loads(line)
        except Exception as e:
            print(f'Line {i}: {e}')
"

D3. JSONL 포맷 에러#

올바른 포맷#

JSON Lines: 한 줄에 하나의 JSON 객체 

{"messages": [...], "category": "nursing"}
{"messages": [...], "category": "management"}

자주 하는 실수#

❌ 여러 줄 JSON (일반 JSON): 

{
  "messages": [...]
}

❌ 배열로 감쌈: 

[
  {"messages": [...]},
  {"messages": [...]}
]

✅ 올바른 JSONL: 

{"messages":[{"role":"user","content":"Q1"}]}
{"messages":[{"role":"user","content":"Q2"}]}

T1. Gemma 4 다운로드 실패#

증상#

401 Client Error: Unauthorized

해결#

  1. HuggingFace 로그인 확인: 

    huggingface-cli whoami

  2. 라이선스 동의:

  3. https://huggingface.co/google/gemma-4-E4B-it

  4. "Acknowledge license" 클릭

  5. 토큰 재발급: 

    huggingface-cli login

T2. HuggingFace 403 에러#

증상#

403 Forbidden: repository not accessible

해결#

# 토큰 권한 확인
# HuggingFace 웹사이트 → Settings → Tokens
# "Read" 권한 있는지 확인

# 모델 페이지에서 라이선스 동의 재확인
# https://huggingface.co/google/gemma-4-E4B-it

# 토큰 재설정
huggingface-cli logout
huggingface-cli login

T3. Out of Memory (OOM)#

증상#

RuntimeError: MLX GPU memory allocation failed

또는 맥미니가 심하게 느려지고 Swap 사용량 급증

원인#

  • 24GB 중 학습이 15GB+ 사용, 시스템이 남은 메모리로 부족

해결 순서#

  1. 다른 앱 전부 닫기 (Chrome 특히 메모리 많이 씀)

  2. 배치 사이즈 줄이기: 

    # scripts/02b_train_mlx.sh에서
BATCH_SIZE=2 → BATCH_SIZE=1

  3. 더 작은 모델로: 

    BASE_MODEL="google/gemma-4-E2B-it"  # E4B → E2B

  4. LoRA layers 줄이기: 

    # --num-layers 16 → --num-layers 8

T4. Loss가 감소 안 함#

증상#

Iter 10:  Train loss 2.45
Iter 100: Train loss 2.44
Iter 300: Train loss 2.43  ← 거의 변화 없음

원인 1: Learning Rate 너무 낮음#

# scripts/02b_train_mlx.sh에서
LEARNING_RATE=2e-4 → LEARNING_RATE=5e-4

원인 2: 데이터 품질#

# 데이터 샘플 확인
head -3 data/processed/train.jsonl | python3 -m json.tool

# 카테고리 분포
python3 -c "
import json
from collections import Counter
cats = []
with open('data/processed/train.jsonl') as f:
    for line in f:
        cats.append(json.loads(line).get('category', 'unknown'))
print(Counter(cats))
"

원인 3: 한국어 토크나이저 문제#

Gemma 4는 한국어 지원하지만, 간호 전문 용어가 여러 토큰으로 쪼개질 수 있음. 정상.

T5. Loss NaN#

증상#

Iter 50:  Train loss 5.82
Iter 100: Train loss 12.4
Iter 150: Train loss NaN  💥

해결#

  1. 즉시 Ctrl+C

  2. Learning Rate 대폭 감소: 

    LEARNING_RATE=2e-4 → LEARNING_RATE=5e-5

  3. 그래디언트 클리핑 추가 (스크립트 수정): 

    # scripts/02b_train_mlx.sh에 추가
--grad-clip 1.0

  4. 데이터 이상치 확인: 극단적으로 긴 텍스트(>4096 토큰) 있는지

T6. 학습이 너무 느림#

증상#

  • 1시간 지났는데 Iter 50도 안 감
  • It/sec 0.3 이하

해결#

# 1. 다른 앱 확인
top -o mem
# Chrome, Slack, Docker 등 닫기

# 2. 전원 어댑터 연결 확인
pmset -g
# "AC Power" 나와야 함

# 3. 절전 모드 해제
sudo pmset -a powernap 0
sudo pmset -a sleep 0  # 학습 중만

# 4. Swap 사용량
sysctl vm.swapusage
# Swap used > 2GB면 문제

T7. Overfitting#

증상#

Train loss: 0.15  ← 너무 낮음
Val loss:   1.40  ← 올라가는 중

해결#

방법 1: 체크포인트 롤백 

# 가장 좋았던 체크포인트 찾기
ls outputs/mlx_adapter/*_adapters.safetensors

# 해당 체크포인트를 최종 어댑터로
cp outputs/mlx_adapter/0000300_adapters.safetensors \
   outputs/mlx_adapter/adapters.safetensors

방법 2: 다음 학습 시 개선 

# iter 줄이기
ITERS=600 → ITERS=300

# 데이터 더 많이
# data/raw/ 에 더 추가

방법 3: 일반 데이터 섞기 

간호 도메인 데이터 80%
+ 일반 한국어 대화 20%

T8. 학습 중단 후 재개#

증상#

학습 중 실수로 Ctrl+C, 전원 꺼짐 등

해결#

이미 체크포인트가 저장되어 있으면 이어서 학습 가능:

# 마지막 체크포인트 확인
ls -lt outputs/mlx_adapter/*_adapters.safetensors | head -1

# 재개
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  # 추가로 돌릴 iter

B1. Fuse 실패#

증상#

Error: adapter not found

해결#

# 어댑터 존재 확인
ls outputs/mlx_adapter/adapters.safetensors

# 없으면 학습 안 끝난 것. 재학습 필요

증상#

Error: de-quantize failed

해결#

# 수동 실행
python3 -m mlx_lm.fuse \
    --model outputs/mlx_base_4bit \
    --adapter-path outputs/mlx_adapter \
    --save-path outputs/merged \
    --de-quantize \
    --hf-path google/gemma-4-E4B-it

B2. GGUF 변환 실패#

증상#

Error: Unsupported model architecture

해결#

llama.cpp를 최신으로:

cd ~/llama.cpp
git pull
cmake --build build --config Release -j

# 재시도
cd ~/projects/mediconsol-llm
make convert

증상 (메모리 부족)#

Killed: 9

해결#

# 다른 앱 닫고 재시도
# 또는 양자화 레벨 낮추기
bash scripts/04_convert_gguf.sh outputs/merged mediconsol-v1 Q5_K_M

B3. Ollama 등록 실패#

증상#

Error: couldn't load model: manifest error

해결#

# Modelfile 직접 확인
cat Modelfile

# 수동으로 등록
ollama create mediconsol-v1 -f Modelfile

# 로그 확인
tail -f ~/.ollama/logs/server.log

증상#

Error: model not found after creation

해결#

# Ollama 재시작
brew services restart ollama

# 다시 등록
ollama list  # 비어있어야 함
make deploy

B4. 답변이 이상함#

증상 A: 프롬프트를 그대로 반복#

>>> KPCS가 뭔가요?
KPCS가 뭔가요?

원인: 학습이 충분하지 않음
해결: iter 늘리거나 데이터 추가

증상 B: 횡설수설#

>>> KPCS가 뭔가요?
Hello how are apple banana in the morning...

원인: - 데이터 포맷 문제 - 학습 실패 (loss NaN 후) - 토크나이저 오류

해결: 1. 학습 로그 다시 확인 2. 데이터 재검증 3. 처음부터 재학습

증상 C: "Sorry I don't know"만 반복#

원인: 거부 응답 데이터가 너무 많음
해결: 데이터에서 거부 응답 비율 확인 (10% 미만이어야)

P1. 추론이 느림#

증상#

  • 답변 생성이 30초 이상 걸림
  • 첫 토큰까지 10초

원인#

  • 첫 요청: 모델 로딩 (정상, 한 번만)
  • 지속적으로 느림: 문제

해결#

# Ollama 로그 확인
tail -f ~/.ollama/logs/server.log

# GPU 사용 확인 (Metal)
# Activity Monitor → 창 → GPU 히스토리

# Q4_K_M 사용 중인지 확인
ollama show mediconsol-v1
# QUANTIZATION: Q4_K_M 이어야 함

# 더 작은 양자화 시도 (품질 감소)
# Q3_K_M → 더 빠름, 품질 약간 낮음

P2. 답변이 영어로 나옴#

증상#

>>> 간호 기록 SOAP로 정리해주세요
S: The patient complained about...

원인#

  • 시스템 프롬프트에 영어 포함
  • 학습 데이터에 영어 응답 섞임

해결#

  1. Modelfile 확인: 

    ollama show --modelfile mediconsol-v1
# SYSTEM 메시지가 한국어여야 함

  2. 데이터 확인: 

    import json
with open('data/processed/train.jsonl') as f:
    for line in f:
        msg = json.loads(line)['messages'][-1]['content']
        if any(c.isascii() and c.isalpha() for c in msg[:20]):
            print(msg[:50])

  3. 명시적 시스템 프롬프트: 

    당신은 한국 요양병원 전문 AI입니다. 반드시 한국어로만 답변하세요.

P3. 할루시네이션#

증상#

>>> KPCS 등급 기준이 뭐예요?
KPCS는 5등급으로 분류되며, 1등급은 간호 요구가 없는...
(실제: KPCS는 6등급, 1등급이 가장 높음 - 반대)

원인#

  • 학습 데이터에 해당 정보 없거나 부정확
  • 모델이 "그럴듯한 답변"을 생성

해결#

  1. Bad case 기록:

  2. 문제 질문과 틀린 답변을 bad_cases.md 에 저장

  3. 정답 데이터 추가:

  4. data/raw/03_medical_terms/ 에 해당 정보 정확하게 추가

  5. 재학습:

  6. 다음 버전에 반영

  7. 단기 대응: 프롬프트에 "확실하지 않으면 '의료진에게 확인' 이라고 답하세요" 추가

P4. 이전 버전으로 롤백#

즉시 롤백#

# 현재 버전 확인
ollama list

# 이전 버전을 latest로
ollama cp mediconsol-v1:1.0.0 mediconsol-v1:latest

# 문제 있는 버전 삭제 (선택)
ollama rm mediconsol-v1:1.1.0

Harness 메타데이터 업데이트#

Harness 프로젝트의 llm_metadata.current_version을 이전 값으로 되돌리기.

EVAL_REPORT 업데이트#

롤백 사유를 EVAL_REPORT.md 에 기록: 

## v1.0.0 (롤백, 2026-05-10)

v1.1.0에서 [문제]가 발견되어 v1.0.0으로 롤백.
다음 버전에서 [대응책] 반영 예정.

🆘 여기에 없는 문제라면#

1. Claude Code에게 물어보기#

"06_TROUBLESHOOTING.md 에 없는 문제인데, [문제 상황]에서 [에러 메시지]가 나와. 
어떻게 해결하면 좋을까?"

2. 로그 수집#

# 학습 로그
cat outputs/training.log | tail -100

# Ollama 로그
tail -100 ~/.ollama/logs/server.log

# 시스템 로그
log show --last 1h --predicate 'processImagePath CONTAINS "mlx"' 2>&1 | tail -50

3. GitHub Issues 확인#

✅ 자가 체크#

  • 에러 메시지를 보고 대충 어디 문제인지 감 잡음
  • 환경/데이터/학습/배포/운영 5개 카테고리 구분 가능
  • OOM, NaN, Overfitting 세 가지 증상 즉시 대응 가능
  • 롤백 절차 알고 있음

다음 단계#

기본기가 준비되었습니다. 이제 실전 데이터 수집으로 갑니다.

다음 문서: 07_DATA_COLLECTION.md - 진짜 데이터 모으기

💡 핵심 요약#

에러 났다 → 메시지 읽기 → 이 문서 목차 → 유사한 것 찾기
그래도 모름 → Claude Code에게 로그와 함께 질문
OOM → 앱 닫기, batch_size 감소
NaN → 즉시 중단, LR 감소
롤백 → ollama cp mediconsol-v1:1.0.0 mediconsol-v1:latest