Ollama 트러블슈팅

설치 문제

1. "ollama: command not found"

$ ollama --version
bash: ollama: command not found

원인

• Ollama가 설치되지 않음
• PATH에 Ollama 경로가 없음
• 설치가 중간에 실패함

해결 방법

# 1. Ollama 설치 확인
which ollama
# 출력 없음 → 미설치

# 2. 재설치 (Linux/macOS)
curl -fsSL https://ollama.com/install.sh | sh

# 3. 수동 PATH 추가 (필요시)
export PATH="/usr/local/bin:$PATH"
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 4. 확인
ollama --version

Windows

# PowerShell에서
Get-Command ollama
# CommandNotFoundException → 재설치 필요

# 환경 변수 PATH 확인
$env:Path -split ';' | Select-String ollama

# PATH 추가 (영구 설정)
[System.Environment]::SetEnvironmentVariable(
    'Path',
    $env:Path + ';C:\Users\[사용자]\AppData\Local\Programs\Ollama\bin',
    [System.EnvironmentVariableTarget]::User
)

2. 권한 오류 (Permission Denied)

Permission denied when trying to install Ollama

해결 방법

# Linux - sudo 권한으로 재설치
curl -fsSL https://ollama.com/install.sh | sudo sh

# macOS - 관리자 권한
sudo curl -fsSL https://ollama.com/install.sh | sh

# 파일 권한 확인
ls -la /usr/local/bin/ollama
# -rwxr-xr-x ... ollama

# 권한 수정 (필요시)
sudo chmod +x /usr/local/bin/ollama

3. systemd 서비스 생성 실패

Failed to enable unit: Unit file ollama.service does not exist

해결 방법

# 1. 서비스 파일 수동 생성
sudo tee /etc/systemd/system/ollama.service <<EOF
[Unit]
Description=Ollama Service
After=network-online.target

[Service]
ExecStart=/usr/local/bin/ollama serve
User=ollama
Group=ollama
Restart=always
RestartSec=3
Environment="OLLAMA_HOST=0.0.0.0:11434"

[Install]
WantedBy=default.target
EOF

# 2. 사용자 생성 (없으면)
sudo useradd -r -s /bin/false -m -d /usr/share/ollama ollama

# 3. systemd 리로드 및 시작
sudo systemctl daemon-reload
sudo systemctl enable ollama
sudo systemctl start ollama

# 4. 상태 확인
sudo systemctl status ollama

연결 문제

1. "Connection Refused" (포트 11434)

curl: (7) Failed to connect to localhost port 11434: Connection refused

원인

• Ollama 서비스가 실행되지 않음
• 포트 11434가 다른 프로세스에 의해 사용 중
• 방화벽이 포트를 차단

해결 방법

# 1. Ollama 서비스 상태 확인
# Linux
sudo systemctl status ollama
# Active: active (running) 이어야 함

# macOS
ps aux | grep ollama
# ollama serve 프로세스가 있어야 함

# Windows
Get-Service Ollama

# 2. 서비스 시작
# Linux
sudo systemctl start ollama

# macOS
ollama serve &

# 3. 포트 사용 확인
sudo lsof -i :11434
# ollama ... LISTEN 이어야 함

# 다른 프로세스가 사용 중이면 종료
sudo kill -9 [PID]

# 4. 방화벽 확인 (Linux)
sudo ufw status
sudo ufw allow 11434/tcp

# 5. 재시작
sudo systemctl restart ollama

2. "Connection Timeout" (원격 접속)

curl: (28) Failed to connect to 192.168.1.100 port 11434: Connection timed out

해결 방법

# 1. OLLAMA_HOST 환경 변수 설정 (0.0.0.0으로)
# Linux - systemd 서비스 편집
sudo systemctl edit ollama
# 다음 추가:
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"

sudo systemctl restart ollama

# 2. 방화벽 포트 열기
# Ubuntu/Debian
sudo ufw allow 11434/tcp

# CentOS/RHEL
sudo firewall-cmd --permanent --add-port=11434/tcp
sudo firewall-cmd --reload

# 3. 클라우드 보안 그룹 설정 (AWS, GCP 등)
# Inbound 규칙: TCP 11434 허용

# 4. 테스트
curl http://[서버IP]:11434/api/tags

3. SSL/TLS 오류

SSL certificate problem: unable to get local issuer certificate

해결 방법

# 1. 인증서 무시 (테스트 전용)
curl -k https://localhost:11434/api/tags

# 2. CA 인증서 설치 (프로덕션)
# Ubuntu/Debian
sudo apt install ca-certificates
sudo update-ca-certificates

# 3. Python requests에서
import requests
response = requests.post(
    'https://localhost:11434/api/generate',
    json={...},
    verify=False  # 또는 인증서 경로
)

GPU 문제

1. GPU 미감지 (NVIDIA)

Ollama는 실행되지만 CPU만 사용, GPU 사용률 0%

진단

# 1. nvidia-smi 실행
nvidia-smi
# GPU 정보가 표시되어야 함

# 오류 발생 시 → 드라이버 문제
# "NVIDIA-SMI has failed..." → 드라이버 재설치 필요

# 2. CUDA 버전 확인
nvcc --version
# CUDA 11.8+ 필요

# 3. Ollama 로그 확인
sudo journalctl -u ollama -n 100
# "GPU" 또는 "CUDA" 관련 메시지 찾기

해결 방법

# 1. NVIDIA 드라이버 재설치 (Ubuntu)
# 기존 드라이버 제거
sudo apt purge nvidia-*
sudo apt autoremove

# 최신 드라이버 설치
sudo apt update
sudo apt install nvidia-driver-535

# 재부팅 필수
sudo reboot

# 2. CUDA Toolkit 설치 (선택사항)
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update
sudo apt install cuda-toolkit-12-3

# 3. Ollama 재시작
sudo systemctl restart ollama

# 4. GPU 사용 확인
ollama run llama3.2 "Hello"
# 동시에 다른 터미널에서
watch -n 1 nvidia-smi
# GPU 사용률이 올라가야 함

2. GPU 메모리 부족 (OOM)

CUDA out of memory. Tried to allocate X MiB

해결 방법

# 1. 더 작은 모델 사용
ollama pull llama3.2:3b      # 3B 모델 (2GB VRAM)
ollama pull phi3:mini        # Phi-3 Mini (2GB VRAM)

# 2. 양자화 버전 사용
ollama pull llama3.2:7b-q4_0  # 4-bit 양자화 (4GB VRAM)

# 3. GPU 레이어 수 제한
export OLLAMA_NUM_GPU=20  # 일부만 GPU, 나머지는 CPU
sudo systemctl restart ollama

# 4. 컨텍스트 윈도우 줄이기
# Modelfile
PARAMETER num_ctx 2048  # 기본 4096 → 2048

# 5. 다른 GPU 프로세스 종료
nvidia-smi
# GPU 메모리 사용 중인 프로세스 확인
kill -9 [PID]

3. 다중 GPU 설정

# 특정 GPU만 사용
export CUDA_VISIBLE_DEVICES=0  # GPU 0만 사용
export CUDA_VISIBLE_DEVICES=0,1  # GPU 0, 1 사용

# systemd 서비스에 적용
sudo systemctl edit ollama
[Service]
Environment="CUDA_VISIBLE_DEVICES=0,1"

sudo systemctl restart ollama

# 확인
nvidia-smi
# 지정한 GPU만 사용 중이어야 함

4. AMD GPU (ROCm) 문제

# ROCm 설치 (Ubuntu)
wget https://repo.radeon.com/amdgpu-install/latest/ubuntu/focal/amdgpu-install_*_all.deb
sudo dpkg -i amdgpu-install_*_all.deb
sudo amdgpu-install --usecase=rocm

# 재부팅
sudo reboot

# ROCm 확인
rocm-smi

# Ollama 재시작
sudo systemctl restart ollama

5. Apple Silicon (M1/M2/M3) 최적화

# Metal 가속 자동 활성화 (설정 불필요)
ollama run llama3.2

# 메모리 압력 모니터링
sudo memory_pressure

# Activity Monitor에서 확인
# GPU 탭에서 "ollama" 프로세스의 GPU 사용률 확인

# 메모리 스왑 최소화
# 더 작은 모델 사용
ollama pull llama3.2:3b  # M1 8GB에 적합

성능 문제

1. 응답 속도가 매우 느림

원인 및 해결

# 1. CPU만 사용 (GPU 미활용)
# → GPU 설정 확인 (위 GPU 섹션 참조)
nvidia-smi  # GPU 사용률 0% → 문제

# 2. 모델이 너무 큼
# → 더 작은 모델 사용
ollama pull llama3.2:7b  # 70B → 7B

# 3. RAM 부족 (스왑 사용)
free -h
# Swap 사용량이 높으면 문제
# → 모델 크기 줄이기 또는 RAM 증설

# 4. 컨텍스트 윈도우가 너무 큼
# Modelfile
PARAMETER num_ctx 2048  # 8192 → 2048

# 5. 다른 프로세스가 리소스 사용
top
# CPU/메모리 많이 쓰는 프로세스 종료

2. 메모리 부족 (OOM Killed)

Killed
dmesg | grep -i "out of memory"
# Out of memory: Killed process [PID] (ollama)

해결 방법

# 1. 메모리 사용량 확인
free -h
# 사용 가능한 메모리 확인

# 2. 더 작은 모델 사용
# 모델별 RAM 요구사항:
# - 3B: 8GB
# - 7B: 16GB
# - 13B: 24GB
# - 70B: 64GB+

ollama pull phi3:mini  # 3B, 8GB RAM

# 3. 양자화 버전 사용
ollama pull llama3.2:7b-q4_0  # 절반 크기

# 4. 스왑 메모리 증가 (임시 방편)
sudo fallocate -l 8G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 5. 동시 실행 모델 수 제한
export OLLAMA_MAX_LOADED_MODELS=1
sudo systemctl restart ollama

3. 디스크 공간 부족

Error: no space left on device

해결 방법

# 1. 디스크 사용량 확인
df -h
# ~/.ollama 경로의 사용량 확인

du -sh ~/.ollama/models
# 모델 총 크기 확인

# 2. 미사용 모델 삭제
ollama list
ollama rm [모델명]

# 3. 모델 저장 경로 변경 (더 큰 디스크로)
# Linux
sudo systemctl edit ollama
[Service]
Environment="OLLAMA_MODELS=/mnt/storage/ollama"

sudo mkdir -p /mnt/storage/ollama
sudo chown ollama:ollama /mnt/storage/ollama
sudo systemctl restart ollama

# 4. Docker 이미지 정리 (Docker 사용 시)
docker system prune -a

4. 동시 요청 시 느려짐

# 병렬 요청 수 증가
export OLLAMA_NUM_PARALLEL=4  # 기본 1 → 4

# systemd 서비스
sudo systemctl edit ollama
[Service]
Environment="OLLAMA_NUM_PARALLEL=4"

sudo systemctl restart ollama

# 주의: 메모리 사용량 증가
# 병렬 처리 수 = 동시 로드 모델 수

모델 문제

1. 모델 다운로드 실패

Error: failed to download model
Error: unexpected EOF

해결 방법

# 1. 네트워크 연결 확인
ping ollama.com
curl https://ollama.com

# 2. 재시도 (단순 네트워크 오류)
ollama pull llama3.2

# 3. 기존 부분 다운로드 삭제 후 재시도
rm -rf ~/.ollama/models/blobs/sha256-*
ollama pull llama3.2

# 4. 프록시 설정 (필요시)
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"

# 5. DNS 문제 (드문 경우)
echo "1.1.1.1" | sudo tee /etc/resolv.conf

2. 손상된 모델 파일

Error: invalid model file
Error: checksum mismatch

해결 방법

# 1. 모델 삭제
ollama rm llama3.2

# 2. 캐시 정리
rm -rf ~/.ollama/models/manifests/registry.ollama.ai/library/llama3.2
rm -rf ~/.ollama/models/blobs/sha256-*

# 3. 재다운로드
ollama pull llama3.2

# 4. 여전히 실패 시 - Ollama 재설치
sudo systemctl stop ollama
sudo rm -rf ~/.ollama
curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.2

3. "Model Not Found"

Error: model 'llama3.2' not found

해결 방법

# 1. 설치된 모델 확인
ollama list
# 목록에 없으면 다운로드 필요

# 2. 모델 다운로드
ollama pull llama3.2

# 3. 모델 이름 오타 확인
# 정확한 이름: llama3.2 (llama-3.2 ❌)

# 4. 사용 가능한 모델 검색
curl https://ollama.com/api/tags | jq '.models[] | .name'

4. 모델 버전 충돌

# 특정 버전 다운로드
ollama pull llama3.2:latest
ollama pull llama3.2:7b-q4_0

# 모든 버전 확인
ollama list
# llama3.2:latest
# llama3.2:7b-q4_0

# 특정 버전 실행
ollama run llama3.2:7b-q4_0

# 기본 버전 (latest) 변경
ollama rm llama3.2:latest
ollama pull llama3.2:7b-q4_0
ollama tag llama3.2:7b-q4_0 llama3.2:latest

일반적인 에러 메시지 (A-Z)

1. "API version mismatch"

# Ollama 버전 불일치
# 해결: Ollama 업데이트
curl -fsSL https://ollama.com/install.sh | sh
sudo systemctl restart ollama

2. "context window exceeded"

# 입력 토큰이 모델의 컨텍스트 윈도우 초과
# 해결: 입력 줄이기 또는 num_ctx 증가
PARAMETER num_ctx 8192  # Modelfile

3. "embedding model not found"

# 임베딩 모델 미설치
ollama pull nomic-embed-text

4. "failed to load model"

# 메모리 부족 또는 손상된 모델
# 1. 메모리 확인
free -h

# 2. 모델 재다운로드
ollama rm llama3.2
ollama pull llama3.2

5. "invalid modelfile syntax"

# Modelfile 문법 오류
# 확인: 대소문자, 따옴표, 줄바꿈
FROM llama3.2  # 올바름
from llama3.2  # 잘못됨 (소문자)

SYSTEM "..."  # 따옴표 필수

6. "model is too large"

# 모델이 메모리보다 큼
# 해결: 양자화 버전 사용
ollama pull llama3.2:7b-q4_0  # 7b 대신

7. "NUMA node not available"

# CPU NUMA 설정 문제 (무시 가능)
# 성능에 영향 없음, 경고 메시지일 뿐

8. "port already in use"

# 포트 11434가 이미 사용 중
sudo lsof -i :11434
sudo kill -9 [PID]

# 또는 다른 포트 사용
export OLLAMA_HOST=0.0.0.0:11435
sudo systemctl restart ollama

9. "request timeout"

# 모델 응답이 너무 느림
# API 호출 시 타임아웃 증가
requests.post(..., timeout=300)  # 5분

# 또는 더 빠른 모델 사용
ollama pull llama3.2:3b

10. "stream error"

# 스트리밍 응답 중 연결 끊김
# 해결: 재시도 또는 stream=false 사용
{
  "model": "llama3.2",
  "prompt": "...",
  "stream": false  # 스트리밍 비활성화
}

11. "temperature out of range"

# temperature 값이 범위 밖 (0.0 ~ 2.0)
PARAMETER temperature 0.8  # 0.0 ~ 2.0 사이

12. "unable to locate model"

# 커스텀 모델 파일 경로 오류
# Modelfile의 FROM 경로 확인
FROM ./model.gguf  # 상대 경로
FROM /absolute/path/model.gguf  # 절대 경로

13. "unsupported model format"

# GGUF 형식이 아닌 파일
# 해결: GGUF 변환 (llama.cpp 사용)
python convert.py --outtype f16 --outfile model.gguf model/

14. "WSL GPU not available"

# WSL2에서 GPU 미지원
# 1. Windows NVIDIA 드라이버 최신 버전 설치
# 2. WSL2에서 nvidia-smi 실행 확인
nvidia-smi

# 3. CUDA WSL 설정
# https://docs.nvidia.com/cuda/wsl-user-guide/

15. "model loading timeout"

# 모델 로드에 시간 오래 걸림
# OLLAMA_KEEP_ALIVE 증가
export OLLAMA_KEEP_ALIVE=30m  # 기본 5m
sudo systemctl restart ollama

16. "CUDA driver version insufficient"

# CUDA 드라이버 버전 낮음
nvidia-smi
# Driver Version 확인

# 535 이상 필요
sudo apt install nvidia-driver-535
sudo reboot

17. "Metal not available"

# macOS에서 Metal 미지원 (구형 Mac)
# CPU 모드로 동작 (정상)
# Intel Mac은 Metal 미지원

18. "quantization not supported"

# 지원되지 않는 양자화 형식
# 사용 가능: Q4_0, Q5_K_M, Q8_0 등
ollama pull llama3.2:7b-q4_0  # 올바름

19. "disk write error"

# 디스크 쓰기 권한 또는 공간 문제
# 1. 권한 확인
ls -ld ~/.ollama
# drwxr-xr-x 사용자 사용자

# 2. 공간 확인
df -h

# 3. 권한 수정
sudo chown -R $USER:$USER ~/.ollama

20. "unexpected token in JSON"

# API 요청 JSON 형식 오류
# 올바른 형식:
{
  "model": "llama3.2",
  "prompt": "Hello",
  "stream": false
}

# 잘못된 예:
# - 따옴표 누락
# - 마지막 쉼표
# - 잘못된 불린 값 (False → false)

디버깅 도구

로그 확인

# Linux (systemd)
sudo journalctl -u ollama -f
sudo journalctl -u ollama -n 100  # 최근 100줄
sudo journalctl -u ollama --since "1 hour ago"

# macOS
tail -f ~/.ollama/logs/server.log

# Docker
docker logs -f ollama
docker logs --tail 100 ollama

# 디버그 모드 활성화
export OLLAMA_DEBUG=1
sudo systemctl restart ollama

API 테스트

# 1. 서버 상태 확인
curl http://localhost:11434/api/tags

# 2. 모델 목록
curl http://localhost:11434/api/tags | jq

# 3. 간단한 생성 테스트
curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "Hello",
  "stream": false
}' | jq

# 4. 스트리밍 테스트
curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "Tell me a story",
  "stream": true
}'

시스템 모니터링

# CPU, 메모리 사용률
top
htop

# GPU 모니터링 (NVIDIA)
watch -n 1 nvidia-smi

# 네트워크 연결
netstat -tuln | grep 11434
ss -tuln | grep 11434

# 디스크 I/O
iostat -x 1

# 프로세스 상세 정보
ps aux | grep ollama
pstree -p | grep ollama

벤치마크

# 간단한 성능 테스트
time ollama run llama3.2 "Count from 1 to 100"

# Python 벤치마크 스크립트
import time
import requests

def benchmark(model, prompt, iterations=10):
    times = []
    for _ in range(iterations):
        start = time.time()
        response = requests.post(
            'http://localhost:11434/api/generate',
            json={'model': model, 'prompt': prompt, 'stream': False}
        )
        duration = time.time() - start
        times.append(duration)

    print(f"평균: {sum(times)/len(times):.2f}초")
    print(f"최소: {min(times):.2f}초")
    print(f"최대: {max(times):.2f}초")

benchmark("llama3.2", "Hello, how are you?")

자주 묻는 질문 (FAQ)

Q1. Ollama를 완전히 삭제하려면?

# Linux
sudo systemctl stop ollama
sudo systemctl disable ollama
sudo rm /etc/systemd/system/ollama.service
sudo rm /usr/local/bin/ollama
rm -rf ~/.ollama

# macOS
rm -rf /Applications/Ollama.app
rm -rf ~/.ollama
rm /usr/local/bin/ollama

# Windows
# 제어판 → 프로그램 제거
# %USERPROFILE%\.ollama 폴더 삭제

Q2. 모델 다운로드 폴더를 옮기려면?

# 1. 새 폴더로 모델 복사
sudo mkdir -p /mnt/storage/ollama
sudo cp -r ~/.ollama/* /mnt/storage/ollama/

# 2. 환경 변수 설정
sudo systemctl edit ollama
[Service]
Environment="OLLAMA_MODELS=/mnt/storage/ollama"

# 3. 재시작
sudo systemctl restart ollama

# 4. 확인
ollama list

Q3. API 키 인증을 추가하려면?

# NGINX 리버스 프록시에 Basic Auth 추가
# nginx.conf
location / {
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://localhost:11434;
}

# htpasswd 생성
sudo htpasswd -c /etc/nginx/.htpasswd admin

# 사용
curl -u admin:password http://your-server/api/generate ...

Q4. 여러 모델을 동시에 사용하려면?

# OLLAMA_MAX_LOADED_MODELS 증가
export OLLAMA_MAX_LOADED_MODELS=3  # 최대 3개
sudo systemctl restart ollama

# 주의: 메모리 사용량 증가
# 모델당 3-7GB → 총 9-21GB 필요

Q5. Ollama를 백그라운드에서 실행하지 않으려면?

# Linux - systemd 비활성화
sudo systemctl stop ollama
sudo systemctl disable ollama

# 수동 실행 (포그라운드)
ollama serve

# 또는 백그라운드
ollama serve &

# 종료
pkill ollama

Q6. 특정 IP만 접속 허용하려면?

# 방화벽 규칙 (UFW)
sudo ufw deny 11434/tcp
sudo ufw allow from 192.168.1.0/24 to any port 11434

# NGINX에서 IP 제한
location / {
    allow 192.168.1.0/24;
    deny all;
    proxy_pass http://localhost:11434;
}

Q7. CPU 사용량이 너무 높습니다

# 1. GPU 사용 확인 (GPU 있으면)
nvidia-smi

# 2. 더 작은 모델 사용
ollama pull phi3:mini

# 3. 컨텍스트 윈도우 줄이기
PARAMETER num_ctx 1024

# 4. 동시 요청 수 제한
export OLLAMA_NUM_PARALLEL=1

Q8. 오프라인 환경에서 사용하려면?

# 1. 인터넷 연결된 PC에서 모델 다운로드
ollama pull llama3.2

# 2. 모델 폴더 압축
tar -czf ollama-models.tar.gz ~/.ollama

# 3. 오프라인 PC로 전송
scp ollama-models.tar.gz user@offline-pc:~

# 4. 오프라인 PC에서 압축 해제
tar -xzf ollama-models.tar.gz -C ~/

# 5. Ollama 설치 (인터넷 필요)
# 설치 파일을 미리 다운로드하여 전송

추가 리소스

공식 문서

• GitHub - ollama/ollama
• Model Library
• API Documentation

커뮤니티

• Discord Server
• Reddit - r/ollama
• Reddit - r/LocalLLaMA

관련 도구

• Continue.dev - VS Code 확장 (가이드)
• Aider - CLI 코딩 도구 (가이드)
• Open WebUI - ChatGPT 스타일 웹 UI (가이드)
• LangChain - Python 프레임워크 (가이드)
• LlamaIndex - RAG 전문 (가이드)

다음 단계

문제를 해결했다면, 이제 Ollama를 실전에서 활용해봅시다!

핵심 정리

• Ollama 트러블슈팅의 핵심 개념과 흐름을 정리합니다.
• 설치 문제를 단계별로 이해합니다.
• 실전 적용 시 기준과 주의점을 확인합니다.

실무 팁

• 입력/출력 예시를 고정해 재현성을 확보하세요.
• Ollama 트러블슈팅 범위를 작게 잡고 단계적으로 확장하세요.
• 설치 문제 조건을 문서화해 대응 시간을 줄이세요.