41장. 트러블슈팅 25선
이 장의 목표 실전에서 자주 만나는 문제 25가지를 증상 → 원인 → 대처 로 정리합니다.
막힐 때마다 이 장만 펼치면 됩니다.
설치·실행
#1 ollama: command not found
원인 PATH에 ollama 바이너리가 없음.
대처
- Ollama 앱 정상 설치 확인
- 또는
brew install ollama ~/.zshrc에export PATH="/usr/local/bin:$PATH"추가
#2 LM Studio가 실행은 되는데 모델이 안 뜸
원인 Models 경로 변경 후 새 위치 인식 못 함.
대처
- Settings → Models Directory 재설정
- 앱 재시작
- 모델 파일이
.gguf또는 MLX 폴더로 올바른지 확인
#3 port 11434 already in use
원인 Ollama 데몬이 이미 떠 있음.
대처
$ lsof -i :11434
$ ollama list # 이미 떠 있다면 정상
중복 실행 안 해도 OK.
다운로드
#4 모델 다운로드가 도중 끊김
원인 네트워크 불안정 / Hugging Face 일시 장애.
대처
huggingface-cli는 이어받기 자동- Ollama
pull도 다시 실행하면 이어받기
#5 디스크 부족 (No space left on device)
원인 모델이 너무 많이 받아짐.
대처
$ du -sh ~/.ollama/models ~/.lmstudio/models ~/.cache/huggingface
$ ollama rm <안 쓰는 모델>
또는 OLLAMA_MODELS=/Volumes/External/... 로 외장 SSD.
#6 Llama 모델이 다운로드가 안 됨 (게이트)
원인 Meta 라이선스 동의 필요.
대처
- HF에서 Llama 페이지 가서 동의
huggingface-cli login으로 토큰 등록
메모리·성능
#7 모델 로드 시 macOS 멈춤
원인 메모리 한계 초과 → swap 폭주.
대처
- 모델·컨텍스트를 한 단계 줄임
- 다른 앱 종료
- 활성 상태 보기에서 메모리 압력 확인
#8 갑자기 응답 속도가 절반으로
원인
- 컨텍스트가 길어짐 (KV Cache)
- 다른 모델이 메모리에 떠 있음
- 발열로 쓰로틀링
대처
$ ollama ps
안 쓰는 모델 stop. 새 채팅 시작. 쿨다운.
#9 70B 모델이 도는데 너무 답답
원인 64GB 맥에서 70B는 한계.
대처
- 32B Q4 또는 32B Q5 로 다운그레이드
- 70B는 시범 용도로만
#10 활성 상태 보기에서 메모리 압력 빨강
원인 실사용 메모리가 통합 메모리 한계 근처.
대처
- 36장 6가지 방법 적용
- Docker · 브라우저부터 정리
응답 품질
#11 답이 영어로 자꾸 섞임
원인
- 작은 모델의 한국어 약함
- Top-p 너무 큼
- 시스템 프롬프트에 한국어 강제 없음
대처
- 14B 이상 모델
- Top-p 0.9 이하, Temperature 0.5 이하
- 시스템 프롬프트: “모든 답은 한국어로만 작성”
#12 모델이 자기 소개부터 시작 (“저는 AI 어시스턴트…”)
원인
- chat template 잘못 적용 (22장)
- Base 모델에 chat 호출
대처
- 모델이 Instruct/Chat 인지 확인
- 도구를 최신 버전으로 (
brew upgrade) - llama.cpp 직접 호출 시
--chat-template명시
#13 같은 문장 무한 반복
원인 Repeat Penalty 부족 / Temperature 0.
대처
- Repeat Penalty 1.0 → 1.15
- Temperature 0.3~0.5
#14 JSON 형식이 자꾸 깨짐
원인 Temperature 높음 / 프롬프트 약함.
대처
- Temperature 0.1~0.2
- 시스템 프롬프트: “JSON 외 어떤 텍스트도 출력 금지”
- Few-shot 예시 1~2개
response_format지원 도구 사용 (24장)
#15 모델이 자신 있게 거짓말함 (환각)
원인 RAG 없이 순수 LLM.
대처
- 시스템 프롬프트에 “모르면 모른다고”
- RAG 적용 (26장)
- 큰 모델로 (14B 이상)
#16 모델이 멀쩡한 질문을 거절함
원인 Alignment 과적합 또는 모호한 입력.
대처
- 시스템 프롬프트에 컨텍스트 추가 (34장)
- 다른 모델 시도 (Qwen·Mistral 균형 좋음)
API·도구 연결
#17 OpenAI SDK 코드가 timeout
원인
- Ollama 데몬 안 떠 있음
- base_url 오타
- 컨텍스트가 너무 큼
대처
$ curl http://localhost:11434/v1/models
응답 오는지 확인. timeout 30초 설정.
#18 Continue.dev에서 자동완성 안 됨
원인
tabAutocompleteModel미설정- Base 모델이 아닌 Chat 모델을 자동완성용으로
- Ollama가 죽음
대처
*-base모델로 변경ollama list로 모델 존재 확인
#19 Open WebUI에서 모델이 안 보임
원인
- Docker가 host의 Ollama에 못 닿음
host.docker.internal누락
대처 docker run 시:
-e OPENAI_API_BASE_URL=http://host.docker.internal:11434/v1
#20 도구가 OpenAI 호환인데 응답 형식이 깨짐
원인 모델 또는 도구가 일부 OpenAI 기능 미지원 (24장).
대처
tool_calls/response_format지원 여부 확인- Ollama → 도구별 호환 매트릭스 확인
- 시스템 프롬프트로 우회
RAG
#21 RAG 검색이 자꾸 엉뚱한 문서를 가져옴
원인
- 청크 너무 큼
- 임베딩 모델 약함 (영어 중심)
- 메타 필터 부재
대처
- 청크 300~500자
bge-m3(다국어)- 메타데이터 + 필터 추가
#22 RAG 답에 청크에 없는 정보가 들어감
원인 시스템 프롬프트가 약함.
대처
근거에 명시된 내용만 사용.
명시되지 않은 사실 절대 추가 금지.
- Temperature 낮춤.
#23 한국어 PDF가 잘 검색 안 됨
원인 PDF 텍스트 추출 품질 낮음.
대처
- 31장 OCR (GOT-OCR / dots.ocr)
- 또는 PDF를 Markdown으로 사전 변환
음성·비전
#24 Whisper가 영어로 받아씀
원인 언어 자동 감지 실패.
대처
-l ko명시- 무음 30초 잘라내고 시도
#25 비전 모델이 이미지를 무시
원인 GGUF에 vision projector 미포함.
대처
- LM Studio에서 vision 표시된 모델만
- Ollama는
qwen2.5vl:*처럼 vision 명시 태그
빠른 진단 흐름
문제가 생기면 이 순서로:
1. 활성 상태 보기 — 메모리 압력?
2. ollama ps — 어떤 모델이 떠 있나?
3. curl /v1/models — API 살아있나?
4. 챗 새로 시작 — 컨텍스트 초기화
5. 작은 모델로 — 모델 자체 문제인지 분리
6. 도구 최신 버전 — brew upgrade
이 장에서 기억할 한 가지
로컬 AI 문제의 80%는 세 가지에서 옵니다:
- 메모리 (37장·36장)
- Chat template / 시스템 프롬프트 (22장)
- 양자화 너무 낮음 또는 모델 너무 작음
손으로 해볼 것
1. 본인의 트러블슈팅 일지
이 장에 없는 문제·해결을 만나면 한 줄 적어두세요.
2026-05-16:
qwen3:32b가 32K 컨텍스트에서 OOM →
컨텍스트 16K로 줄이고 KV q8_0 적용 → 해결
이게 쌓이면 회사 위키 한 페이지가 됩니다.
여기까지가 7부의 끝 입니다.
여기까지 마치면 회사에 실제로 도입할 수 있는 도구 3개와 평소 운영 노하우를 손에 쥐었습니다.
다음 부(8부)에서는 책을 마무리합니다. 오해 정리, 의사결정 트리, 다음에 공부할 것들.