Ollama 사용법: Ollama를 이용한 로컬 LLM 완전 초보 가이드

인공지능의 세계는 끊임없이 발전하고 있으며, 대규모 언어 모델(LLM)은 점점 더 강력해지고 접근성이 높아지고 있습니다. 많은 사람들이 클라우드 기반 서비스를 통해 이러한 모델과 상호작용하지만, 개인 컴퓨터에서 직접 실행하는 데 초점을 맞추는 움직임이 커지고 있습니다. 바로 여기서 Ollama가 등장합니다. Ollama는 Llama 3, Mistral, Gemma, Phi 등 최첨단 LLM을 로컬에서 다운로드, 설정 및 실행하는 복잡한 과정을 획기적으로 단순화하도록 설계된 강력하면서도 사용자 친화적인 도구입니다.

이 포괄적인 가이드는 설치 및 기본 사용법부터 고급 사용자 지정, API 사용 및 필수 문제 해결까지 Ollama를 시작하는 데 필요한 모든 것을 안내합니다. 로컬 LLM을 애플리케이션에 통합하려는 개발자, 다양한 아키텍처를 실험하려는 연구원, 또는 오프라인에서 AI를 실행하는 데 관심이 있는 애호가이든 관계없이 Ollama는 간소화되고 효율적인 플랫폼을 제공합니다.

💡

아름다운 API 문서를 생성하는 훌륭한 API 테스트 도구가 필요하신가요?

개발 팀이 최대 생산성으로 함께 작업할 수 있는 통합 All-in-One 플랫폼이 필요하신가요?

Apidog은 모든 요구를 충족시키고 Postman을 훨씬 더 저렴한 가격에 대체합니다!

버튼

로컬 LLM 실행에 왜 Ollama를 선택해야 할까요?

기술적인 세부 사항으로 들어가기 전에, 클라우드 기반 대안 대신 Ollama와 로컬 LLM을 선택하는 이유를 고려해 보는 것이 중요합니다. 왜 단순히 이용 가능한 클라우드 API에 의존하는 대신 이 접근 방식을 선택해야 할까요?

Ollama를 통한 비교할 수 없는 개인 정보 보호 및 보안: 사용자 기기에서 Ollama를 사용하여 LLM을 실행하면 프롬프트, 제공하는 문서, 모델이 생성한 텍스트 등 모든 데이터가 로컬 시스템 내에 완전히 유지됩니다. 하드웨어 밖으로 나가지 않습니다. 이는 민감한 개인 정보, 기업 기밀 데이터 또는 독점 연구를 다룰 때 중요한 요소인 최고 수준의 개인 정보 보호 및 데이터 제어를 보장합니다.
Ollama를 통한 상당한 비용 절감: 클라우드 기반 LLM API는 종종 사용량 기반 모델로 운영되거나 지속적인 구독료가 필요합니다. 이러한 비용은 특히 사용량이 많을 경우 빠르게 누적될 수 있습니다. Ollama는 이러한 반복 비용을 제거합니다. 적절한 하드웨어에 대한 초기 투자(이미 보유하고 있을 수 있음) 외에 로컬에서 모델을 실행하는 것은 사실상 무료이며, API 청구서 걱정 없이 무제한 실험과 생성이 가능합니다.
Ollama를 통한 진정한 오프라인 기능: Ollama 모델을 로컬 저장소에 다운로드하면 언제 어디서나 인터넷 연결 없이 완전히 독립적으로 사용할 수 있습니다. 이 오프라인 액세스는 연결이 제한된 환경에서 작업하는 개발자, 현장 연구원 또는 이동 중에 안정적인 AI 액세스가 필요한 모든 사람에게 매우 중요합니다.
Ollama Modelfile을 통한 심층적인 사용자 지정 및 실험: Ollama는 강력한 Modelfile 시스템으로 차별화됩니다. 이를 통해 사용자는 매개변수(예: 창의성 수준 또는 출력 길이)를 조정하고, 사용자 지정 시스템 프롬프트를 정의하여 AI의 페르소나를 형성하고, 특수 미세 조정 어댑터(LoRA)를 통합하여 모델 동작을 쉽게 수정할 수 있습니다. GGUF 또는 Safetensors와 같은 표준 형식에서 모델 가중치를 직접 가져올 수도 있습니다. 이러한 세분화된 제어 및 유연성 수준은 폐쇄 소스 클라우드 API 제공 업체에서는 거의 제공되지 않습니다.
Ollama를 통한 잠재적인 성능 이점: 로컬 하드웨어 구성, 특히 고성능 그래픽 처리 장치(GPU)의 존재 여부에 따라 Ollama는 네트워크 대기 시간, 속도 제한 또는 공유 리소스의 가변 부하에 영향을 받을 수 있는 클라우드 서비스에 비해 훨씬 빠른 응답 시간(추론 속도)을 제공할 수 있습니다. 전용 하드웨어를 활용하면 훨씬 더 부드럽고 상호 작용적인 경험을 얻을 수 있습니다.
활기찬 Ollama 오픈 소스 생태계 참여: Ollama 자체는 오픈 소스 프로젝트로서 투명성과 커뮤니티 기여를 촉진합니다. 또한, 이는 주로 빠르게 확장되는 방대한 오픈 액세스 가능 LLM 라이브러리로 가는 관문 역할을 합니다. Ollama를 사용하면 이 역동적인 생태계의 일부가 되어 공유된 지식, 커뮤니티 지원 및 개방형 협업에 의해 주도되는 지속적인 혁신의 혜택을 누릴 수 있습니다.

Ollama의 주요 성과는 이러한 정교한 AI 모델을 실행하는 데 필요한 소프트웨어 환경 설정, 종속성 관리 및 복잡한 설정 구성과 관련된 내재적 복잡성을 숨기는 데 있습니다. 유명한 llama.cpp 라이브러리를 비롯한 고도로 최적화된 백엔드 추론 엔진을 능숙하게 활용하여 표준 소비자 하드웨어에서 효율적인 실행을 보장하고 CPU 및 GPU 가속을 모두 지원합니다.

Ollama 대 Llama.cpp 이해하기

Ollama와 llama.cpp는 밀접하게 관련되어 있지만 서로 다른 목적을 수행하므로 그 관계를 명확히 하는 것이 유용합니다.

llama.cpp: 이것은 LLM 추론의 핵심 작업을 담당하는 기반이 되는 고성능 C/C++ 라이브러리입니다. 모델 가중치 로딩, 입력 토큰 처리 및 출력 토큰의 효율적인 생성을 처리하며, 다양한 하드웨어 아키텍처(AVX와 같은 CPU 명령 세트, CUDA, Metal, ROCm을 통한 GPU 가속)에 최적화되어 있습니다. 계산의 힘든 작업을 수행하는 강력한 엔진입니다.
Ollama: 이것은 llama.cpp(및 잠재적인 미래의 다른 백엔드)를 중심으로 구축된 포괄적인 애플리케이션입니다. Ollama는 그 위에 사용자 친화적인 계층을 제공하며 다음을 제공합니다.
간단한 상호 작용을 위한 간단한 명령줄 인터페이스(CLI)(ollama run, ollama pull 등).
프로그래밍 방식 통합을 위한 내장 REST API 서버.
간소화된 모델 관리(라이브러리에서 다운로드, 로컬 저장소, 업데이트).
사용자 지정 및 모델 변형 생성을 위한 Modelfile 시스템.
크로스 플랫폼 설치 프로그램(macOS, Windows, Linux) 및 Docker 이미지.
자동 하드웨어 감지 및 구성(CPU/GPU).

본질적으로, 기술적으로 llama.cpp를 직접 컴파일하고 명령줄 도구를 실행하여 사용할 수 있지만, 이는 설정, 모델 변환 및 매개변수 관리와 관련하여 훨씬 더 많은 기술적 노력이 필요합니다. Ollama는 이 힘을 접근하기 쉽고 사용하기 쉬운 애플리케이션으로 패키징하여, 특히 초보자에게 로컬 LLM을 훨씬 더 광범위한 사용자에게 실용적으로 만듭니다. llama.cpp를 고성능 엔진 부품으로, Ollama를 운전 준비가 된 완전히 조립된 사용자 친화적인 차량으로 생각하십시오.

시스템에 Ollama 설치하기

Ollama는 접근성을 위해 설계되었으며 macOS, Windows, Linux 및 Docker 환경에 대한 간단한 설치 절차를 제공합니다.

Ollama의 일반적인 시스템 요구 사항:

RAM(메모리): 이것은 종종 가장 중요한 요소입니다.
최소 8GB: 소형 모델(예: 1B, 3B, 7B 매개변수)에는 충분하지만 성능이 느릴 수 있습니다.
권장 16GB: 7B 및 13B 모델을 편안하게 실행하기 위한 좋은 출발점입니다.
이상적 32GB 이상: 대형 모델(30B, 40B, 70B 이상)에 필요하며 더 큰 컨텍스트 창을 허용합니다. 일반적으로 RAM이 많을수록 성능이 향상되고 더 크고 성능이 좋은 모델을 실행할 수 있습니다.
디스크 공간: Ollama 애플리케이션 자체는 비교적 작습니다(수백 MB). 그러나 다운로드하는 LLM은 상당한 공간이 필요합니다. 모델 크기는 매우 다양합니다.
소형 양자화 모델(예: ~3B Q4): ~2GB
중형 양자화 모델(예: 7B/8B Q4): 4~5GB
대형 양자화 모델(예: 70B Q4): ~40GB
초대형 모델(예: 405B): 200GB 이상!
Ollama가 모델을 저장하는 드라이브에 충분한 여유 공간이 있는지 확인하십시오(아래 섹션 참조).
운영 체제:
macOS: 버전 11 Big Sur 이상. GPU 가속을 위해 Apple Silicon(M1/M2/M3/M4)이 권장됩니다.
Windows: Windows 10 버전 22H2 이상 또는 Windows 11. Home 및 Pro 에디션 모두 지원됩니다.
Linux: 최신 배포판(예: Ubuntu 20.04+, Fedora 38+, Debian 11+). 특히 AMD GPU 지원을 위해 커널 요구 사항이 적용될 수 있습니다.

macOS에 Ollama 설치하기

다운로드: 공식 Ollama 웹사이트에서 Ollama macOS 애플리케이션 DMG 파일을 직접 받습니다.
마운트: 다운로드한 .dmg 파일을 더블 클릭하여 엽니다.
설치: Ollama.app 아이콘을 응용 프로그램 폴더로 드래그합니다.
실행: 응용 프로그램 폴더에서 Ollama 애플리케이션을 실행합니다. 처음 실행할 때 실행 권한을 부여해야 할 수 있습니다.
백그라운드 서비스: Ollama는 백그라운드 서비스로 실행되기 시작하며 메뉴 막대에 아이콘으로 표시됩니다. 이 아이콘을 클릭하면 애플리케이션 종료 또는 로그 보기와 같은 옵션이 제공됩니다.

애플리케이션을 실행하면 Ollama 서버 프로세스가 자동으로 시작되고 ollama 명령줄 도구가 시스템 PATH에 추가되어 터미널 애플리케이션(Terminal.app, iTerm2 등)에서 즉시 사용할 수 있게 됩니다. Apple Silicon(M1, M2, M3, M4 칩)이 장착된 Mac에서는 Ollama가 수동 구성 없이 Apple의 Metal 그래픽 API를 통해 내장 GPU를 원활하게 활용합니다.

Windows에 Ollama 설치하기

다운로드: Ollama 웹사이트에서 OllamaSetup.exe 설치 관리자 파일을 받습니다.
설치 관리자 실행: 다운로드한 .exe 파일을 더블 클릭하여 설정 마법사를 시작합니다. 최소 Windows 버전 요구 사항(10 22H2+ 또는 11)을 충족하는지 확인합니다.
프롬프트 따르기: 설치 단계를 진행하고 라이선스 계약에 동의하며 필요한 경우 설치 위치를 선택합니다(일반적으로 기본값이 괜찮습니다).

설치 관리자는 시스템 시작 시 Ollama가 백그라운드 서비스로 자동 실행되도록 구성합니다. 또한 ollama.exe 실행 파일을 시스템 PATH에 추가하여 명령 프롬프트(cmd.exe), PowerShell 또는 최신 Windows 터미널과 같은 표준 Windows 터미널에서 ollama 명령을 사용할 수 있도록 합니다. Ollama API 서버는 자동으로 시작되고 http://localhost:11434에서 수신 대기합니다.

Ollama를 위한 Windows GPU 가속:

NVIDIA: NVIDIA 웹사이트에서 최신 GeForce Game Ready 또는 NVIDIA Studio 드라이버를 설치합니다. 드라이버 버전 452.39 이상이 필요합니다. Ollama는 호환되는 GPU를 자동으로 감지하고 활용해야 합니다.
AMD: AMD 지원 웹사이트에서 최신 AMD Software: Adrenalin Edition 드라이버를 설치합니다. 호환되는 Radeon GPU(일반적으로 RX 6000 시리즈 이상)가 자동으로 사용됩니다.

Linux에 Ollama 설치하기

대부분의 Linux 배포판에 가장 편리한 방법은 공식 설치 스크립트를 사용하는 것입니다.

curl -fsSL https://ollama.com/install.sh | sh

이 명령은 스크립트를 다운로드하고 sh를 사용하여 실행합니다. 스크립트는 다음 작업을 수행합니다.

시스템 아키텍처(x86_64, ARM64)를 감지합니다.
적절한 Ollama 바이너리를 다운로드합니다.
바이너리를 /usr/local/bin/ollama에 설치합니다.
필요한 GPU 드라이버(NVIDIA CUDA, AMD ROCm)를 확인하고 가능하면 종속성을 설치합니다(이 부분은 배포판에 따라 다를 수 있음).
전용 ollama 시스템 사용자와 그룹을 생성합니다.
Ollama 서버 프로세스를 관리하기 위한 systemd 서비스 파일(/etc/systemd/system/ollama.service)을 설정합니다.
ollama 서비스를 활성화하고 시작하여 부팅 시 및 백그라운드에서 자동으로 실행되도록 합니다.

Ollama를 위한 수동 Linux 설치 및 Systemd 구성:
스크립트가 실패하거나 수동 제어를 선호하는 경우(예: 다른 위치에 설치, 사용자를 다르게 관리, 특정 ROCm 버전 보장), Ollama GitHub 리포지토리의 자세한 Linux 설치 가이드를 참조하십시오. 일반적인 단계는 다음과 같습니다.

아키텍처에 맞는 바이너리를 다운로드합니다.
바이너리를 실행 가능하게 만들고(chmod +x ollama) PATH에 있는 위치(예: /usr/local/bin)로 이동합니다.
(권장) 시스템 사용자/그룹을 생성합니다: sudo useradd -r -s /bin/false -m -d /usr/share/ollama ollama 및 sudo groupadd ollama, 그런 다음 sudo usermod -a -G ollama ollama. 자신의 사용자를 그룹에 추가합니다: sudo usermod -a -G ollama $USER.
적절한 설정(사용자, 그룹, 실행 파일 경로, 필요한 경우 환경 변수)으로 systemd 서비스 파일(/etc/systemd/system/ollama.service)을 생성합니다. 일반적으로 문서에 샘플 스니펫이 제공됩니다.
systemd 데몬을 다시 로드합니다: sudo systemctl daemon-reload.
부팅 시 서비스가 시작되도록 활성화합니다: sudo systemctl enable ollama.
서비스를 즉시 시작합니다: sudo systemctl start ollama. sudo systemctl status ollama로 상태를 확인할 수 있습니다.

Ollama를 위한 필수 Linux GPU 드라이버:
최적의 성능을 위해서는 GPU 드라이버 설치를 강력히 권장합니다.

NVIDIA: 배포판용 공식 독점 NVIDIA 드라이버를 설치합니다(예: apt 또는 dnf와 같은 패키지 관리자를 통해 또는 NVIDIA 웹사이트에서 다운로드). nvidia-smi 명령을 사용하여 설치를 확인합니다.
AMD (ROCm): ROCm 툴킷을 설치합니다. AMD는 지원되는 배포판(Ubuntu, RHEL/CentOS, SLES 등)에 대한 공식 리포지토리 및 설치 가이드를 제공합니다. 커널 버전이 호환되는지 확인하십시오. Ollama 설치 스크립트는 일부 ROCm 종속성을 처리할 수 있지만 수동 설치를 통해 올바른 설정이 보장됩니다. rocminfo로 확인합니다.

공식 Ollama Docker 이미지 사용하기

Docker는 플랫폼에 구애받지 않고 Ollama를 격리된 컨테이너에서 실행하는 방법을 제공하며, 특히 복잡한 GPU 설정의 경우 종속성 관리를 단순화합니다.

CPU 전용 Ollama 컨테이너:

docker run -d \
  -v ollama_data:/root/.ollama \
  -p 127.0.0.1:11434:11434 \
  --name my_ollama \
  ollama/ollama

-d: 컨테이너를 분리 모드(백그라운드)로 실행합니다.
-v ollama_data:/root/.ollama: 호스트 시스템에 ollama_data라는 Docker 명명된 볼륨을 생성하고 컨테이너 내부의 /root/.ollama 디렉토리에 매핑합니다. 이것은 다운로드한 모델을 영구 저장하는 데 중요합니다. 이를 생략하면 컨테이너가 제거될 때 모델이 손실됩니다. 볼륨에는 원하는 이름을 선택할 수 있습니다.
-p 127.0.0.1:11434:11434: 호스트 머신의 루프백 인터페이스(127.0.0.1)의 포트 11434를 컨테이너 내부의 포트 11434에 매핑합니다. 네트워크의 다른 머신에서 Ollama 컨테이너에 액세스해야 하는 경우 0.0.0.0:11434:11434를 사용하십시오.
--name my_ollama: 실행 중인 컨테이너에 사용자 정의된 기억하기 쉬운 이름을 할당합니다.
ollama/ollama: Docker Hub의 공식 Ollama 이미지를 지정합니다.

NVIDIA GPU Ollama 컨테이너:

먼저 NVIDIA 컨테이너 툴킷이 호스트 머신에 올바르게 설치되어 있고 Docker가 NVIDIA 런타임을 사용하도록 구성되어 있는지 확인합니다.
--gpus=all 플래그를 추가하여 컨테이너를 실행합니다.

docker run -d \
  --gpus=all \
  -v ollama_data:/root/.ollama \
  -p 127.0.0.1:11434:11434 \
  --name my_ollama_gpu \
  ollama/ollama

이 플래그는 툴킷에서 감지한 모든 호환되는 NVIDIA GPU에 대한 액세스 권한을 컨테이너에 부여합니다. 필요한 경우 특정 GPU를 지정할 수 있습니다(예: --gpus '"device=0,1"').

AMD GPU (ROCm) Ollama 컨테이너:

ROCm 관련 이미지 태그를 사용합니다: ollama/ollama:rocm.
필요한 ROCm 장치 노드를 호스트에서 컨테이너로 매핑합니다.

docker run -d \
  --device /dev/kfd \
  --device /dev/dri \
  -v ollama_data:/root/.ollama \
  -p 127.0.0.1:11434:11434 \
  --name my_ollama_rocm \
  ollama/ollama:rocm

/dev/kfd: 커널 퓨전 드라이버 인터페이스.
/dev/dri: 직접 렌더링 인프라 장치(종종 /dev/dri/renderD128과 같은 렌더 노드 포함).
호스트에서 docker 명령을 실행하는 사용자가 이러한 장치 파일에 액세스할 수 있는 적절한 권한이 있는지 확인합니다(render 및 video와 같은 그룹의 멤버십이 필요할 수 있음).

Ollama 컨테이너가 실행되면 docker exec 명령을 사용하여 컨테이너 내부에서 ollama CLI 명령을 실행하여 상호 작용할 수 있습니다.

docker exec -it my_ollama ollama list
docker exec -it my_ollama ollama pull llama3.2
docker exec -it my_ollama ollama run llama3.2

또는 포트를 매핑한 경우(-p), 호스트 머신 또는 http://localhost:11434(또는 매핑한 IP/포트)를 가리키는 다른 애플리케이션에서 직접 Ollama API와 상호 작용할 수 있습니다.

Ollama는 모델을 어디에 저장하나요? Ollama 저장 위치 이해하기

Ollama가 다운로드한 모델을 어디에 보관하는지 아는 것은 디스크 공간 관리 및 백업에 필수적입니다. 기본 위치는 운영 체제 및 설치 방법에 따라 다릅니다.

macOS의 Ollama: 모델은 사용자 홈 디렉토리 내의 ~/.ollama/models에 있습니다. ~는 /Users/<사용자 이름>을 나타냅니다.
Windows의 Ollama: 모델은 사용자 프로필 디렉토리의 C:\Users\<사용자 이름>\.ollama\models에 저장됩니다.
Linux의 Ollama(사용자 설치/수동): macOS와 유사하게 모델은 일반적으로 ~/.ollama/models에 저장됩니다.
Linux의 Ollama(Systemd 서비스 설치): 스크립트를 통해 설치되었거나 ollama 사용자로 실행되는 시스템 전체 서비스로 구성된 경우, 모델은 종종 /usr/share/ollama/.ollama/models에 저장됩니다. 비표준 설정을 사용한 경우 서비스 구성 또는 문서를 확인하십시오.
Docker를 통한 Ollama: 컨테이너 내부의 경로는 /root/.ollama/models입니다. 그러나 Docker 볼륨을 마운트하기 위해 -v 플래그를 올바르게 사용한 경우(예: -v ollama_data:/root/.ollama), 실제 모델 파일은 호스트 머신의 Docker 관리 볼륨 영역 내에 저장됩니다. Docker 볼륨의 정확한 위치는 Docker 설정에 따라 다르지만 컨테이너와 독립적으로 영구 저장되도록 설계되었습니다.

모델 저장 위치는 구성 섹션에서 설명하는 OLLAMA_MODELS 환경 변수를 사용하여 리디렉션할 수 있습니다. 기본 드라이브의 공간이 부족하거나 대규모 모델을 전용 SSD 또는 더 큰 드라이브에 구성하려는 경우 유용합니다.

Ollama 첫걸음: LLM 실행하기

이제 Ollama가 설치되었고 서버가 활성 상태(데스크톱 앱, systemd 서비스 또는 Docker 컨테이너를 통해 실행 중)이므로 터미ナル에서 간단한 ollama 명령을 사용하여 LLM과 상호 작용을 시작할 수 있습니다.

Ollama 모델 다운로드: `pull` 명령어

특정 LLM을 실행하기 전에 먼저 가중치 및 구성 파일을 다운로드해야 합니다. Ollama는 인기 있는 공개 모델의 선별된 라이브러리를 제공하며 ollama pull 명령을 통해 쉽게 액세스할 수 있습니다. 사용 가능한 모델은 Ollama 웹사이트의 라이브러리 페이지에서 찾아볼 수 있습니다.

# 예제 1: 최신 Llama 3.2 8B Instruct 모델 가져오기
# 종종 'latest' 또는 단순히 기본 이름으로 태그 지정됨
ollama pull llama3.2

# 예제 2: Mistral의 특정 버전 가져오기 (70억 매개변수, 기본 모델)
ollama pull mistral:7b

# 예제 3: Google의 Gemma 3 4B 모델 가져오기
ollama pull gemma3

# 예제 4: Microsoft의 더 작은 Phi-4 Mini 모델 가져오기 (효율적)
ollama pull phi4-mini

# 예제 5: Vision 모델 가져오기 (이미지 처리 가능)
ollama pull llava

Ollama 모델 태그 이해하기:
Ollama 라이브러리의 모델은 모델_패밀리_이름:태그 명명 규칙을 사용합니다. 태그는 다음과 같은 변형을 지정합니다.

크기: 1b, 3b, 7b, 8b, 13b, 34b, 70b, 405b (수십억 개의 매개변수 표시). 일반적으로 더 큰 모델은 더 많은 지식을 가지고 있지만 더 많은 리소스가 필요합니다.
양자화: q2_K, q3_K_S, q4_0, q4_K_M, q5_1, q5_K_M, q6_K, q8_0, f16 (float16), f32 (float32). 양자화는 모델 크기와 계산 요구 사항을 줄이며 종종 정밀도에서 약간의 절충이 있습니다. 더 작은 숫자(예: q4)는 더 많은 압축을 의미합니다. K 변형(_K_S, _K_M, _K_L)은 일반적으로 크기와 품질의 균형이 잘 맞는 것으로 간주됩니다. f16/f32는 양자화되지 않았거나 최소한으로 압축되어 최고의 충실도를 제공하지만 가장 많은 리소스가 필요합니다.
변형: instruct (지침을 따르도록 조정됨), chat (대화용으로 조정됨), code (프로그래ミング 작업에 최적화됨), vision (멀티모달, 이미지 처리), uncensored (안전 필터링이 적음, 책임감 있게 사용).
latest: 태그를 생략하면(예: ollama pull llama3.2), Ollama는 일반적으로 latest 태그를 기본값으로 사용하며, 이는 일반적으로 널리 사용되는 균형 잡힌 버전(종종 중간 크기, 양자화됨, 지침 조정 모델)을 가리킵니다.

pull 명령은 필요한 파일(수 기가바이트가 될 수 있음)을 지정된 Ollama 모델 디렉토리에 다운로드합니다. 특정 모델:태그 조합을 한 번만 가져오면 됩니다. Ollama는 모델을 업데이트할 수도 있습니다. 기존 모델에서 pull을 다시 실행하면 변경된 계층(차이점)만 다운로드되므로 업데이트가 효율적입니다.

Ollama 모델과 대화형 채팅: `run` 명령어

다운로드한 모델과 대화하는 가장 직접적인 방법은 ollama run 명령을 사용하는 것입니다.

ollama run llama3.2

지정된 모델(llama3.2:latest의 경우)이 아직 다운로드되지 않은 경우 ollama run은 편리하게 먼저 ollama pull을 트리거합니다. 모델이 준비되고 메모리에 로드되면(특히 대규모 모델의 경우 몇 초가 걸릴 수 있음) 대화형 프롬프트가 표시됩니다.

>>> 메시지를 보내세요 (도움말은 /?)

이제 질문이나 지침을 입력하고 Enter 키를 누른 다음 AI가 응답을 생성할 때까지 기다리면 됩니다. 출력은 일반적으로 토큰 단위로 스트리밍되어 응답성이 좋은 느낌을 줍니다.

>>> 양자 얽힘 개념을 간단한 용어로 설명해 주세요.
네, 마법처럼 서로 연결된 두 개의 특별한 동전이 있다고 상상해 보세요. 동전 A와 동전 B라고 부르겠습니다. 보기 전에는 어느 동전도 앞면이나 뒷면이 아닙니다. 두 가능성이 모호하게 섞인 상태입니다.

이제 동전 A를 친구에게 주고 동전 B를 가지고 수 광년 떨어진 곳으로 여행합니다. 자신의 동전 B를 보고 예를 들어 앞면이라는 것을 알게 된 순간, 친구의 동전 A가 뒷면이라는 것을 *확실히* 알게 됩니다. 그리고 뒷면을 보았다면 친구의 것이 앞면이라는 것을 알게 될 것입니다.

이것이 양자 얽힘과 비슷합니다! 두 입자(우리 동전처럼)가 연결되고 그 속성(앞면/뒷면처럼)은 아무리 멀리 떨어져 있어도 상관관계를 유지합니다. 하나를 측정하면 다른 하나의 속성에 즉시 영향을 미치며, 빛이 그 사이를 이동하는 것보다 빠릅니다. 양자 물리학의 가장 이상하고 멋진 부분 중 하나입니다!

>>> 메시지를 보내세요 (도움말은 /?)

Ollama 대화 모드 내 유용한 명령어:
ollama run을 통해 모델과 상호 작용하는 동안 /로 시작하는 특수 명령을 사용할 수 있습니다.

/?: 사용 가능한 모든 슬래시 명령어 목록이 포함된 유용한 메뉴를 표시합니다.
/set parameter <매개변수_이름> <값>: 현재 채팅 세션에 대한 모델의 런타임 매개변수를 일시적으로 변경합니다. 예를 들어 /set parameter temperature 0.9는 창의성을 높이고 /set parameter num_ctx 8192는 이 세션의 컨텍스트 창을 늘립니다.
/show info: 현재 로드된 모델에 대한 자세한 정보(매개변수, 템플릿 구조, 라이선스 등)를 표시합니다.
/show modelfile: 현재 실행 중인 모델을 만드는 데 사용된 Modelfile의 내용을 표시합니다. 기본 모델, 매개변수 및 프롬프트 템플릿을 이해하는 데 유용합니다.
/save <세션_이름>: 현재 채팅 기록을 명명된 세션 파일에 저장합니다.
/load <세션_이름>: 이전에 저장한 채팅 세션을 로드하여 대화 기록을 복원합니다.
/bye 또는 /exit: 대화형 채팅 세션을 정상적으로 종료하고 모델을 메모리에서 언로드합니다(다른 세션에서 사용하지 않는 경우). 일반적으로 Ctrl+D를 사용하여 종료할 수도 있습니다.

로컬 Ollama 모델 관리하기

모델을 다운로드하고 생성함에 따라 관리 방법이 필요합니다.

다운로드한 Ollama 모델 목록 보기: 현재 로컬에 저장된 모든 모델을 보려면 다음을 사용합니다.

ollama list

이 명령은 모델 이름(NAME), 고유 ID, 디스크 크기(SIZE) 및 수정 시간(MODIFIED)을 보여주는 테이블을 출력합니다.

상세 Ollama 모델 정보 보기: 특정 모델의 세부 정보(매개변수, 시스템 프롬프트, 템플릿 등)를 검사하려면 다음을 사용합니다.

ollama show llama3.2:8b-instruct-q5_K_M

그러면 해당 특정 모델 태그와 관련된 Modelfile 내용, 매개변수 설정, 템플릿 세부 정보 및 기타 메타데이터가 출력됩니다.

Ollama 모델 제거하기: 모델이 더 이상 필요 없고 디스크 공간을 확보하려면 다음을 사용합니다.

ollama rm mistral:7b

이렇게 하면 지정된 모델:태그 조합이 스토리지에서 영구적으로 삭제됩니다. 주의해서 사용하십시오!

Ollama 모델 복사/이름 바꾸기: 기존 모델의 복사본을 만들거나 사용자 지정을 위한 시작점으로 사용하거나 단순히 다른 이름을 지정하려면 다음을 사용합니다.

ollama cp llama3.2 my-custom-llama3.2-setup

이렇게 하면 원래 llama3.2를 기반으로 my-custom-llama3.2-setup이라는 새 모델 항목이 생성됩니다.

현재 로드된 Ollama 모델 확인하기: RAM 또는 VRAM에 현재 로드되어 즉시 추론할 준비가 된 모델을 확인하려면 다음을 사용합니다.

ollama ps

이 명령은 모델 이름, ID, 크기, 사용된 프로세서(CPU/GPU) 및 마지막으로 액세스한 시점을 보여줍니다. 모델은 일반적으로 사용 후 짧은 시간(예: 5분) 동안 로드된 상태를 유지하여 후속 요청 속도를 높인 다음 리소스를 확보하기 위해 자동으로 언로드됩니다.

최적의 Ollama 모델은 무엇인가요? 올바른 LLM 선택하기

이것은 자주 묻는 중요한 질문이지만 답은 미묘합니다. 모든 사람이나 모든 작업에 대해 단일 "최고" Ollama 모델은 없습니다. 최적의 선택은 여러 요인에 따라 달라집니다.

특정 작업: AI에게 주로 무엇을 하기를 원하십니까?
일반 채팅/지원: llama3.2, llama3.1, mistral, gemma3, qwq가 강력한 경쟁자입니다.
코딩/프로그래밍: codellama, phi4, phi4-mini, starcoder2, deepseek-coder는 코드 생성, 설명 및 디버깅을 위해 특별히 조정되었습니다.
창의적 글쓰기: 기본 온도가 높거나 매개변수 수가 많은 모델(예: 70B 모델)은 더 상상력이 풍부한 결과를 낳을 수 있습니다. 실험이 중요합니다.
요약/분석: 지침 조정 모델(:instruct 태그)이 종종 여기서 뛰어납니다.
멀티모달(이미지 입력): llava, moondream, llama3.2-vision.
하드웨어 리소스(RAM 및 VRAM): 이것이 주요 제약 조건입니다.
낮은 리소스(8GB RAM, GPU 없음/약함): 작은 모델(1B-3B 매개변수) 또는 7B 모델의 고도로 양자화된 버전(예: q2_K, q3_K_S)을 고수하십시오. 성능이 느려집니다. 예: gemma3:1b, llama3.2:1b, phi4-mini:q4_0.
중급 리소스(16GB RAM, 기본 GPU): 7B/8B 모델(예: llama3.2, mistral, gemma3)을 양호한 양자화(q4_K_M, q5_K_M)로 편안하게 실행할 수 있습니다. 13B 모델(q4_0)을 천천히 실행할 수 있습니다.
고급 리소스(32GB 이상 RAM, 12GB 이상 VRAM이 있는 강력한 GPU): 13B, 30B 또는 70B(q4_K_M 또는 q5_K_M, q6_K와 같은 더 나은 양자화)와 같은 더 큰 모델을 실행할 수 있습니다. 이들은 훨씬 더 나은 추론 및 지식을 제공합니다. 예: llama3.3, llama3.1:405b(막대한 리소스 필요), gemma3:27b, deepseek-r1:671b(극단적인 요구 사항).
원하는 품질 대 속도 절충:
고품질: 매개변수 수가 많거나 덜 공격적인 양자화(예: q6_K, q8_0, f16)는 일반적으로 더 나은 결과를 제공하지만 느리고 더 많은 리소스가 필요합니다.
더 빠른 속도/낮은 리소스 사용: 매개변수 수가 적거나 더 공격적인 양자화(예: q4_0, q4_K_M, q3_K_M)는 더 빠르고 가볍지만 일관성이나 정확성이 약간 저하될 수 있습니다. K 양자화(_K_M, _K_S)는 종종 최상의 균형을 제공합니다.
모델 튜닝 및 정렬: 일부 모델은 기본 모델이고 다른 모델은 지침 조정(instruct) 또는 채팅 조정(chat)됩니다. Instruct/chat 모델은 일반적으로 지침을 따르고 대화에 참여하는 데 더 능숙합니다. Uncensored 모델은 안전 가드레일이 적습니다.

초보자를 위한 권장 사항(2024년 후반):

우수한 만능 모델(중급 하드웨어): llama3.2:8b-instruct-q5_K_M 또는 mistral:7b-instruct-v0.2-q5_K_M. 이들은 기능, 속도 및 리소스 사용량의 훌륭한 균형을 제공합니다.
효율적인 옵션(저사양 하드웨어): phi4-mini:q4_K_M 또는 gemma3:1b. 크기에 비해 놀라울 정도로 유능합니다.
코딩 초점: codellama:7b-instruct-q5_K_M.
비전 요구 사항: llava:13b(리소스가 허용하는 경우) 또는 moondream.

가장 좋은 접근 방식은 경험적입니다: Ollama 라이브러리에서 모델 설명을 읽고 하드웨어를 고려하여 ollama pull을 사용하여 몇 가지 유력한 후보를 다운로드하고 ollama run을 사용하여 일반적인 프롬프트로 테스트한 다음 자신에게 가장 적합한 성능을 보이는 것을 확인하십시오. 공간을 절약하기 위해 필요에 맞지 않는 모델을 ollama rm하는 것을 주저하지 마십시오.

Ollama 모델 개념 이해하기

Ollama를 효과적으로 사용하고 사용자 지정하려면 몇 가지 핵심 LLM 개념을 이해하는 것이 도움이 됩니다.

Ollama 모델 매개변수 설명

LLM에는 출력을 제어하기 위해 조정할 수 있는 다양한 내부 설정 또는 매개변수가 있습니다. Ollama를 사용하면 이들 중 많은 것을 제어할 수 있습니다.

temperature: (기본값: ~0.7-0.8) 출력의 무작위성 또는 "창의성"을 제어합니다.
낮은 값(예: 0.2): 출력을 더 결정론적이고 집중적이며 예측 가능하게 만듭니다. 사실적인 답변이나 코드 생성에 적합합니다.
높은 값(예: 1.0, 1.2): 무작위성을 높여 출력을 더 다양하고 창의적으로 만들지만 일관성이 떨어질 수 있습니다. 브레인스토밍이나 스토리 작성에 적합합니다.
top_p (Nucleus Sampling): (기본값: ~0.9) 확률 임계값을 설정합니다. 모델은 누적 확률 질량이 top_p를 초과하는 가장 가능성 높은 다음 토큰만 고려합니다. top_p를 낮추면(예: 0.5) 선택이 더 가능성 높은 단어로 제한되어 일관성이 높아지지만 참신함이 줄어들 수 있습니다. 높은 값은 더 다양한 선택을 허용합니다.
top_k: (기본값: ~40) 모델의 선택을 가장 가능성 높은 k개의 다음 토큰으로 제한합니다. 낮은 top_k(예: 10)는 출력을 더 집중시키고 높은 top_k는 더 많은 다양성을 허용합니다. top_p는 종종 top_k보다 더 효과적인 것으로 간주됩니다. 일반적으로 둘 다 낮게 설정하지 않고 하나 또는 다른 하나를 설정합니다.
num_predict: (기본값: ~128, 무한대의 경우 -1) 모델이 단일 응답으로 생성할 토큰(대략 단어/하위 단어)의 최대 수입니다. 중지 조건이 충족될 때까지 무제한 생성을 위해 -1로 설정합니다.
stop: 특정 텍스트 시퀀스 목록입니다. 모델이 이러한 시퀀스 중 하나를 생성하면 즉시 추가 출력 생성을 중지합니다. 계속되는 문장을 방지하거나 모델이 답변 후 중지되도록 하는 데 유용합니다. 예: ["\n", "User:", "<|eot_id|>"].
num_ctx: 모델의 컨텍스트 창 크기를 정의합니다. 아래의 자세한 설명을 참조하십시오.
기타 매개변수: Ollama는 llama.cpp에서 상속된 다른 많은 매개변수(예: repeat_penalty, seed, mirostat, GPU 계층 num_gpu 등)를 노출하여 세분화된 제어를 제공합니다. 자세한 내용은 Ollama 및 llama.cpp 설명서를 참조하십시오.

이들은 ollama run에서 /set parameter를 사용하여 일시적으로, Modelfile에서 PARAMETER 지침을 사용하여 영구적으로 또는 Ollama API의 options 개체를 통해 요청별로 설정할 수 있습니다.

Ollama 컨텍스트 길이: `num_ctx` 매개변수

컨텍스트 길이는 종종 컨텍스트 창 또는 Ollama 및 llama.cpp 설정의 num_ctx라고 하며 LLM의 가장 중요한 아키텍처 제한 중 하나입니다.

나타내는 것: num_ctx는 모델이 동시에 "볼" 수 있거나 처리할 수 있는 최대 토큰 수를 정의합니다. 여기에는 초기 시스템 프롬프트, 현재 채팅 기록의 모든 이전 사용자 메시지 및 보조 응답, 사용자의 최신 입력 프롬프트가 모두 포함됩니다.
중요한 이유: 관련성 있고 일관성 있으며 문맥적으로 적절한 응답을 생성하는 모델의 능력은 컨텍스트 창에 크게 좌우됩니다.
긴 대화: 더 큰 컨텍스트 창을 사용하면 모델이 대화 초기의 정보를 "기억"하여 길을 잃거나 반복하는 것을 방지할 수 있습니다.
문서 분석: 대규모 문서를 처리할 때(예: 요약 또는 질의 응답) 컨텍스트 창은 모델이 한 번에 고려할 수 있는 문서의 양을 결정합니다.
복잡한 지침: 프롬프트 훨씬 이전에 제공된 세부 정보에 의존하는 지침은 올바르게 이해되기 위해 충분한 컨텍스트 창이 필요합니다.
고유 모델 제한: 모든 LLM은 특정 최대 컨텍스트 길이(예: 2048, 4096, 8192, 32k, 128k 또는 최첨단 연구 모델의 경우 수백만 개 이상)로 사전 훈련됩니다. Ollama에서 num_ctx를 설정할 수 있지만 모델의 원래 훈련 제한보다 높게 설정하면 예측할 수 없는 동작, 성능 저하(모델이 훈련된 창 외부의 내용을 "잊어버릴" 수 있음) 또는 오류가 발생할 수 있습니다. 낮게 설정하는 것은 항상 안전하지만 모델의 기능을 제한합니다.
리소스 소비: 더 큰 컨텍스트 창을 처리하려면 훨씬 더 많은 RAM 및 VRAM(GPU 메모리)이 필요하고 계산 시간이 더 오래 걸립니다. 원하는 컨텍스트 기능과 하드웨어 제한 사이의 균형을 맞춰야 합니다.
Ollama 모델의 기본 num_ctx 찾기: ollama show <모델 이름:태그> 명령을 사용하고 표시된 Modelfile 섹션에서 PARAMETER num_ctx 줄을 찾습니다. Ollama 모델은 일반적으로 합리적인 기본값(예: 4096 또는 8192)으로 제공됩니다.
Ollama의 num_ctx 변경:
일시적 (ollama run 중): 슬래시 명령을 사용합니다: /set parameter num_ctx 8192
API 요청별: options JSON 개체에 포함합니다: curl ... -d '{ "model": "...", "prompt": "...", "options": { "num_ctx": 8192 } }'
영구적 (사용자 지정 Ollama 모델): Modelfile을 생성하거나 수정하고 PARAMETER num_ctx <값> 줄을 추가하거나 변경한 다음 ollama create를 사용하여 모델을 빌드합니다. 이렇게 하면 해당 사용자 지정 모델의 기본 컨텍스트 크기가 설정됩니다.

일반적인 작업에 맞는 num_ctx 값을 선택하십시오. 간단한 Q&A의 경우 더 작은 창(예: 4096)으로 충분할 수 있습니다. 긴 채팅이나 대규모 문서 요약의 경우 하드웨어와 모델이 합리적으로 지원할 수 있는 가장 큰 컨텍스트 창(예: 8192, 16384 또는 사용 가능한 경우 그 이상)의 이점을 누릴 수 있습니다.

고급 Ollama: API 및 사용자 지정 활용

ollama CLI는 쉬운 직접 상호 작용을 제공하지만, Ollama를 워크플로 및 애플리케이션에 통합하기 위한 진정한 잠재력은 내장된 REST API 및 Modelfile 사용자 지정 시스템에 있습니다.

Ollama API와 프로그래밍 방식으로 상호 작용하기

기본적으로 Ollama 서버 프로세스(데스크톱 앱, systemd 또는 Docker를 통해 실행 중이든)는 로컬 머신의 포트 11434(http://localhost:11434 또는 http://127.0.0.1:11434)에서 들어오는 HTTP 요청을 수신합니다. 이 API를 사용하면 동일한 머신(또는 구성된 경우 네트워크의 다른 머신)에서 실행 중인 다른 프로그램, 스크립트 또는 웹 인터페이스가 Ollama 모델과 프로그래밍 방식으로 상호 작용할 수 있습니다.

주요 Ollama API 엔드포인트:

POST /api/generate: 단일 비대화형 프롬프트를 기반으로 텍스트 완성을 생성하는 데 사용됩니다. 텍스트 확장, 간단한 번역 또는 간단한 코드 스니펫과 같은 작업에 적합합니다. model 및 prompt가 포함된 JSON 본문이 필요합니다.
POST /api/chat: 대화형 상호 작용을 위해 설계되었습니다. 각각 role(system, user 또는 assistant) 및 content가 있는 메시지 목록을 허용합니다. 이를 통해 모델은 여러 턴에 걸쳐 컨텍스트를 유지할 수 있습니다. model 및 messages가 포함된 JSON 본문이 필요합니다.
POST /api/embeddings: 입력 텍스트에 대한 숫자 벡터 표현(임베딩)을 생성합니다. 이러한 벡터는 의미적 의미를 포착하며 검색 증강 생성(RAG), 의미 검색, 텍스트 분류 및 클러스터링과 같은 작업의 기본입니다. model 및 prompt가 포함된 JSON 본문이 필요합니다.
GET /api/tags: 현재 로컬 Ollama 스토리지에서 사용 가능한 모든 모델 목록을 검색합니다(ollama list와 동일). 모델 개체의 JSON 배열을 반환합니다.
POST /api/show: 특정 로컬 모델에 대한 자세한 정보(매개변수, 템플릿, 라이선스 등)를 가져옵니다(ollama show와 동일). name(모델:태그)이 포함된 JSON 본문이 필요합니다.
DELETE /api/delete: 지정된 모델을 로컬 스토리지에서 제거합니다(ollama rm와 동일). name(모델:태그)이 포함된 JSON 본문이 필요합니다.
POST /api/pull: Ollama 라이브러리에서 모델 다운로드를 시작합니다(ollama pull와 동일). name(모델:태그)이 포함된 JSON 본문이 필요합니다. 진행률 정보를 스트리밍할 수도 있습니다.
POST /api/create: 제공된 Modelfile 콘텐츠를 기반으로 새 사용자 지정 모델을 만듭니다(ollama create -f와 동일). name(새 모델 이름) 및 modelfile(Modelfile 콘텐츠를 문자열로)이 포함된 JSON 본문이 필요합니다.
POST /api/copy: 기존 로컬 모델을 새 이름으로 복제합니다(ollama cp와 동일). source 및 destination 이름이 포함된 JSON 본문이 필요합니다.
POST /api/push: 사용자 지정 로컬 모델을 Ollama.com 계정에 업로드합니다(사전 로그인/설정 필요). name(네임스페이스가 지정된 모델 이름)이 포함된 JSON 본문이 필요합니다.

API 요청/응답 형식:
대부분의 POST 및 DELETE 요청은 요청 본문에 JSON 페이로드를 예상합니다. 응답은 일반적으로 JSON 개체로 반환됩니다. generate 및 chat 엔드포인트의 경우 응답 형식을 제어할 수 있습니다.

"stream": false (기본값): API는 전체 응답이 생성될 때까지 기다렸다가 전체 텍스트, 완성 세부 정보 및 성능 통계가 포함된 단일 JSON 개체로 반환합니다.
"stream": true: API는 생성된 각 토큰(또는 작은 토큰 청크)에 대해 하나씩 JSON 개체 스트림을 반환합니다. 이를 통해 애플리케이션은 응답을 점진적으로 표시하여 보다 상호 작용적인 사용자 경험을 제공할 수 있습니다. 스트림의 마지막 JSON 개체에는 전체 통계가 포함됩니다.

curl을 사용한 API 상호 작용 예:

1. 간단한 생성 요청 (비스트리밍):

curl http://localhost:11434/api/generate -d '{
  "model": "phi4-mini",
  "prompt": "팩토리얼을 계산하는 짧은 Python 함수를 작성하세요:",
  "stream": false,
  "options": {
    "temperature": 0.3,
    "num_predict": 80
  }
}'

2. 대화형 채팅 요청 (스트리밍):

# 참고: 스트리밍 출력은 여러 JSON 줄로 표시됩니다.
curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2:8b-instruct-q5_K_M",
  "messages": [
    { "role": "system", "content": "당신은 지식이 풍부한 역사학자입니다." },
    { "role": "user", "content": "제1차 세계 대전의 주요 원인은 무엇이었습니까?" }
  ],
  "stream": true,
  "options": {
    "num_ctx": 4096
  }
}'

3. 임베딩 생성 요청:

curl http://localhost:11434/api/embeddings -d '{
  "model": "mxbai-embed-large",  # 또는 다른 적절한 임베딩 모델
  "prompt": "Ollama는 로컬에서 LLM을 쉽게 실행할 수 있게 합니다."
}'

이 다재다능한 API는 웹 UI, 개발 도구, 백엔드 서비스, 자동화 스크립트 등 로컬 Ollama 인스턴스를 기반으로 하는 수많은 커뮤니티 통합의 중추를 형성합니다.

Ollama OpenAI 호환성 API 활용하기

OpenAI의 API 표준이 널리 채택되고 있음을 인식하여 Ollama는 사려 깊게 실험적인 호환성 계층을 포함합니다. 이를 통해 OpenAI 서비스용으로 설계된 많은 도구, 라이브러리 및 애플리케이션이 최소한의, 종종 사소한 수정만으로 로컬 Ollama 인스턴스와 작동할 수 있습니다.

작동 방식:
Ollama 서버는 /v1/ 경로(예: http://localhost:11434/v1/) 아래에 엔드포인트를 노출하며, 이는 주요 OpenAI API 엔드포인트의 구조와 예상되는 요청/응답 형식을 미러링합니다.

주요 호환 엔드포인트:

/v1/chat/completions: OpenAI의 채팅 완성 엔드포인트를 미러링합니다.
/v1/embeddings: OpenAI의 임베딩 엔드포인트를 미러링합니다.
/v1/models: OpenAI의 모델 목록 엔드포인트를 미러링합니다(로컬 Ollama 모델을 반환합니다).

Ollama와 함께 OpenAI 클라이언트 라이브러리 사용하기:
주요 이점은 클라이언트를 초기화할 때 두 개의 구성 매개변수만 변경하여 표준 OpenAI 클라이언트 라이브러리(openai-python, openai-node 등)를 사용할 수 있다는 것입니다.

base_url (또는 api_base): 로컬 Ollama v1 엔드포인트로 설정합니다: http://localhost:11434/v1/.
api_key: 비어 있지 않은 문자열을 제공합니다. Ollama의 /v1/ 엔드포인트는 실제로 인증을 수행하지 않으며 키 값을 무시하지만 대부분의 OpenAI 클라이언트 라이브러리에는 매개변수가 있어야 합니다. 일반적인 관행은 문자열 "ollama" 또는 "nokey"를 사용하는 것입니다.

openai-python을 사용한 Python 예제:

# openai 라이브러리가 설치되어 있는지 확인하십시오: pip install openai
from openai import OpenAI
import os

# Ollama 엔드포인트 및 더미 API 키 정의
OLLAMA_BASE_URL = "http://localhost:11434/v1"
OLLAMA_API_KEY = "ollama" # 자리 표시자, Ollama에서 값 무시됨

# 사용하려는 로컬 Ollama 모델 지정
OLLAMA_MODEL = "llama3.2"

try:
    # OpenAI 클라이언트를 초기화하고 Ollama 서버를 가리키도록 함
    client = OpenAI(
        base_url=OLLAMA_BASE_URL,
        api_key=OLLAMA_API_KEY,
    )

    print(f"Ollama 모델에 요청 보내는 중: {OLLAMA_MODEL} (OpenAI 호환성 계층 경유)...")

    # 표준 채팅 완성 요청 생성
    chat_completion = client.chat.completions.create(
        model=OLLAMA_MODEL, # 로컬 Ollama 모델 이름 사용
        messages=[
            {"role": "system", "content": "당신은 도움이 되는 어시스턴트입니다."},
            {"role": "user", "content": "Ollama와 llama.cpp의 차이점을 설명해주세요."}
        ],
        temperature=0.7,
        max_tokens=250, # 참고: 'max_tokens'는 Ollama의 'num_predict'와 대략 일치
        stream=False # 스트리밍 응답의 경우 True로 설정
    )

    # 응답 처리
    if chat_completion.choices:
        response_content = chat_completion.choices[0].message.content
        print("\nOllama 응답:")
        print(response_content)
        print("\n사용 통계:")
        print(f"  프롬프트 토큰: {chat_completion.usage.prompt_tokens}")
        print(f"  완성 토큰: {chat_completion.usage.completion_tokens}")
        print(f"  총 토큰: {chat_completion.usage.total_tokens}")
    else:
        print("Ollama로부터 응답 선택지를 받지 못했습니다.")

except Exception as e:
    print(f"\n오류가 발생했습니다:")
    print(f"  오류 유형: {type(e).__name__}")
    print(f"  오류 세부 정보: {e}")
    print(f"\nOllama 서버가 실행 중이고 {OLLAMA_BASE_URL}에서 액세스할 수 있는지 확인하십시오.")
    print(f"또한 모델 '{OLLAMA_MODEL}'이 로컬에서 사용 가능한지('ollama list') 확인하십시오.")

이 호환성은 기존 OpenAI 기반 프로젝트를 Ollama를 통해 로컬 모델을 사용하도록 마이그레이션하거나 클라우드와 로컬 백엔드 간에 유연하게 전환할 수 있는 새 애플리케이션을 구축하는 것을 크게 단순화합니다. 모든 모호한 OpenAI 기능이 완벽하게 미러링되지는 않을 수 있지만 핵심 채팅, 임베딩 및 모델 목록 기능은 잘 지원됩니다.

Modelfile을 이용한 심층적인 Ollama 사용자 지정

Modelfile은 Ollama 사용자 지정 기능의 초석입니다. 이는 Ollama 모델이 어떻게 구성되거나 수정되어야 하는지를 정확하게 정의하는 청사진 또는 레시피 역할을 합니다. 이러한 간단한 텍스트 파일을 생성하고 편집함으로써 모델 동작, 매개변수 및 구조를 세밀하게 제어할 수 있습니다.

핵심 Ollama Modelfile 지침:

FROM <기본_모델_참조>: (필수 첫 번째 지침) 새 모델이 구축되는 기반을 지정합니다. 참조는 다음을 가리킬 수 있습니다.
로컬 Ollama 라이브러리 또는 공식 레지스트리의 기존 모델 (예: FROM llama3.2:8b-instruct-q5_K_M).
Safetensors 형식의 압축 해제된 모델 가중치와 필요한 구성 파일(config.json, tokenizer.json 등)을 포함하는 로컬 디렉토리에 대한 상대 또는 절대 경로. 예: FROM /mnt/models/my_downloaded_llama/. Ollama는 지원되는 아키텍처(Llama, Mistral, Phi, Gemma 등) 로드를 시도합니다.
인기 있는 GGUF 형식(가중치와 메타데이터 패키징)의 단일 모델 파일에 대한 상대 또는 절대 경로. 예: FROM ./models/mistral-7b-instruct-v0.2.Q5_K_M.gguf.
PARAMETER <매개변수_이름> <값>: 생성되는 모델의 기본 런타임 매개변수 값을 설정합니다. 이러한 기본값은 ollama run 중(/set parameter 통해), API 호출 옵션 또는 동일한 Modelfile의 후속 PARAMETER 지침에 의해 재정의되지 않는 한 사용됩니다.
PARAMETER temperature 0.6
PARAMETER num_ctx 8192 (기본 컨텍스트 창 설정)
PARAMETER stop "<|user|>"
PARAMETER stop "<|end_of_turn|>" (여러 개의 중지 매개변수를 가질 수 있음)
PARAMETER repeat_penalty 1.15
TEMPLATE "<프롬프트_템플릿_문자열>": Ollama가 기본 LLM에 입력하기 전에 입력 프롬프트를 구조화하는 데 사용해야 하는 특정 형식을 정의합니다. 이는 채팅 및 지침 준수 모델에 매우 중요합니다. 시스템 메시지, 사용자 턴 및 보조 턴을 구분하는 특수 토큰이나 마커를 예상하도록 훈련되었기 때문입니다. 템플릿은 Go의 text/template 구문을 사용합니다. 템플릿 문자열 내에서 사용할 수 있는 주요 변수는 다음과 같습니다.
{{ .System }}: 시스템 메시지의 자리 표시자.
{{ .Prompt }}: 사용자의 현재 입력 자리 표시자 (/api/generate에서 사용).
{{ .Response }}: 모델의 생성된 출력이 추가될 위치의 자리 표시자 (종종 내부적으로 또는 특정 템플릿 구조에 사용됨).
{{ range .Messages }} ... {{ .Role }} ... {{ .Content }} ... {{ end }}: 채팅 템플릿(/api/chat)에서 전체 메시지 기록(시스템, 사용자, 보조 턴)을 반복하고 올바르게 형식을 지정하는 데 사용됩니다.
{{ .First }}: 현재 메시지가 맨 처음 메시지인지 여부를 나타내는 부울 값 (특수 시퀀스 시작 토큰 추가에 유용함).
예 (간단한 ChatML 템플릿):

TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>{{ end }}{{ range .Messages }}
<|im_start|>{{ .Role }}
{{ .Content }}<|im_end|>{{ end }}
<|im_start|>assistant
"""

템플릿을 올바르게 설정하는 것은 모델이 지침을 따르거나 자연스럽게 대화하도록 만드는 데 필수적입니다. 모델의 기본 템플릿은 ollama show --modelfile <모델_이름>을 사용하여 볼 수 있습니다.

SYSTEM "<기본_시스템_메시지>": API 또는 CLI를 통해 다른 시스템 메시지가 제공되지 않는 경우 사용될 기본 시스템 프롬프트를 제공합니다. 모델에 일관된 페르소나 또는 지침 세트를 설정하는 데 유용합니다.
SYSTEM "당신은 간결한 답변을 제공하는 데 중점을 둔 도움이 되는 AI 어시스턴트입니다."
ADAPTER </경로/어댑터_가중치>: FROM 지침에 지정된 기본 모델에 LoRA(Low-Rank Adaptation) 또는 QLoRA 어댑터를 적용합니다. 어댑터는 전체 대규모 모델을 재훈련하지 않고 특정 작업, 스타일 또는 지식 영역에 대해 사전 훈련된 LLM을 수정하거나 특수화하기 위해 훈련된 작은 가중치 세트입니다. 경로는 다음을 가리킬 수 있습니다.
어댑터를 포함하는 단일 .gguf 파일.
Safetensors 형식의 어댑터 가중치(adapter_model.safetensors, adapter_config.json)를 포함하는 디렉토리.
중요: 어댑터가 올바르게 작동하려면 기본 모델(FROM)이 어댑터가 원래 훈련된 모델과 동일해야 합니다.
LICENSE "<라이선스_세부정보>": 모델의 메타데이터 내에 라이선스 정보를 포함합니다. 짧은 식별자("MIT" 등) 또는 긴 텍스트 블록이 될 수 있습니다.
MESSAGE user "<예시_사용자_메시지>" / MESSAGE assistant "<예시_어시스턴트_응답>": 예시 대화 턴을 정의합니다. 이는 특히 소수 샷 프롬프팅 시나리오에서 모델의 톤, 스타일 또는 예상 출력 형식을 안내하는 데 도움이 될 수 있지만 그 효과는 모델마다 다릅니다.

Modelfile에서 Ollama 모델 빌드하기:
Modelfile을 생성한 후(예: MyCustomModel.modelfile로 저장), ollama create 명령을 사용하여 해당 Ollama 모델을 빌드합니다.

ollama create my-new-model-name -f MyCustomModel.modelfile

Ollama는 지침을 처리하고 잠재적으로 레이어를 결합하고 어댑터를 적용하고 매개변수를 설정하고 새 모델(my-new-model-name)을 로컬 라이브러리에 등록합니다. 그런 다음 다른 모델처럼 실행할 수 있습니다: ollama run my-new-model-name.

외부 모델을 Ollama로 가져오기 (GGUF, Safetensors)

Ollama의 Modelfile 시스템은 다른 소스(Hugging Face, 독립 연구원 등)에서 얻은 표준 형식으로 배포된 모델을 원활하게 사용하는 방법을 제공합니다.

GGUF 모델을 Ollama로 가져오기: GGUF는 llama.cpp 및 유사한 추론 엔진을 위해 특별히 설계된 인기 있는 형식입니다. 모델 가중치(종종 사전 양자화됨), 토크나이저 정보 및 메타데이터를 단일 파일로 패키징합니다. 이것은 종종 가져오기가 가장 쉬운 형식입니다.

.gguf 파일을 다운로드합니다 (예: zephyr-7b-beta.Q5_K_M.gguf).
최소한의 Modelfile을 생성합니다 (예: ZephyrImport.modelfile):

# ZephyrImport.modelfile
FROM ./zephyr-7b-beta.Q5_K_M.gguf

# 중요: 이 모델에 필요한 올바른 프롬프트 템플릿을 추가하십시오!
# (모델에 필요한 템플릿 형식을 찾아보십시오)
TEMPLATE """<|system|>
{{ .System }}</s>
<|user|>
{{ .Prompt }}</s>
<|assistant|>
{{ .Response }}</s>
"""
PARAMETER num_ctx 4096 # 합리적인 기본 컨텍스트 설정
SYSTEM "당신은 친절한 챗봇입니다." # 선택적 기본 시스템 프롬프트

Ollama 모델을 빌드합니다: ollama create my-zephyr-gguf -f ZephyrImport.modelfile.

Safetensors 모델 (전체 가중치)을 Ollama로 가져오기: Safetensors는 모델 텐서를 저장하기 위한 안전하고 빠른 형식입니다. 이 형식으로 모델의 완전한 가중치 및 구성 파일 세트가 있는 경우:

필요한 모든 파일 (*.safetensors 가중치 파일, config.json, tokenizer.json, special_tokens_map.json, tokenizer_config.json 등)이 단일 디렉토리 내에 있는지 확인합니다 (예: /data/models/Mistral-7B-v0.1-full/).
이 디렉토리를 참조하는 Modelfile을 생성합니다:

# MistralImport.modelfile
FROM /data/models/Mistral-7B-v0.1-full/

# 필요한 TEMPLATE, PARAMETER, SYSTEM 지침 추가
TEMPLATE """[INST] {{ if .System }}{{ .System }} \n{{ end }}{{ .Prompt }} [/INST]
{{ .Response }}"""
PARAMETER num_ctx 4096
PARAMETER temperature 0.7

모델을 빌드합니다: ollama create my-mistral-safetensors -f MistralImport.modelfile. Ollama는 호환되는 아키텍처 로드를 시도합니다. 모델이 양자화되지 않은 경우(예: FP16), 선택적으로 생성 중에 양자화할 수 있습니다 (아래 참조).

Ollama Modelfile을 통해 Safetensors LoRA 어댑터 적용하기:

먼저 LoRA 어댑터가 훈련된 정확한 기본 Ollama 모델이 있는지 확인합니다. 필요한 경우 가져옵니다 (예: ollama pull llama3.2:8b).
LoRA 어댑터 파일 (예: adapter_model.safetensors, adapter_config.json)을 자체 디렉토리에 배치합니다 (예: /data/adapters/my_llama3_lora/).
기본과 어댑터를 모두 지정하는 Modelfile을 생성합니다:

# ApplyLora.modelfile
FROM llama3.2:8b # 어댑터의 기본과 일치해야 함!

ADAPTER /data/adapters/my_llama3_lora/

# LoRA가 필요한 경우 매개변수 또는 템플릿 조정
PARAMETER temperature 0.5
SYSTEM "이제 LoRA가 가르쳐 준 스타일로 응답합니다."

적용된 모델을 빌드합니다: ollama create llama3-with-my-lora -f ApplyLora.modelfile.

Ollama로 모델 양자화하기

양자화는 모델 가중치의 수치 정밀도를 줄이는 프로세스입니다 (예: 16비트 부동 소수점 숫자를 4비트 정수로 변환). 이렇게 하면 모델의 파일 크기와 메모리 사용량(RAM/VRAM 사용량)이 크게 줄어들고 추론 속도가 빨라져 더 크고 성능이 좋은 모델을 소비자 하드웨어에서 실행할 수 있습니다. 절충안은 일반적으로 작고 종종 감지할 수 없는 출력 품질 저하입니다.

Modelfile의 FROM 지침이 양자화되지 않았거나 더 높은 정밀도의 모델 가중치(일반적으로 FP16 또는 FP32 Safetensors)를 가리키는 경우 Ollama는 모델 생성 프로세스 중에 양자화를 수행할 수 있습니다.

ollama create를 사용하여 양자화하는 방법:

양자화되지 않은 모델 가중치가 포함된 디렉토리를 가리키는 Modelfile을 생성합니다.

# QuantizeMe.modelfile
FROM /path/to/my/unquantized_fp16_model/
# 필요에 따라 TEMPLATE, PARAMETER, SYSTEM 추가

-q(또는 --quantize) 플래그 다음에 원하는 양자화 수준 식별자를 붙여 ollama create 명령을 실행합니다.

# Q4_K_M으로 양자화 (크기/품질의 인기 있는 균형)
ollama create my-quantized-model-q4km -f QuantizeMe.modelfile -q q4_K_M

# Q5_K_M으로 양자화 (약간 더 크고 잠재적으로 더 나은 품질)
ollama create my-quantized-model-q5km -f QuantizeMe.modelfile -q q5_K_M

# Q8_0으로 양자화 (양자화 중 가장 큰 일반적인 크기, 양자화 중 최고 품질)
ollama create my-quantized-model-q8 -f QuantizeMe.modelfile -q q8_0

# Q3_K_S로 양자화 (매우 작고 품질 손실이 더 큼)
ollama create my-quantized-model-q3ks -f QuantizeMe.modelfile -q q3_K_S

Ollama는 llama.cpp의 양자화 루틴을 사용하여 변환을 수행하고 새로 양자화된 모델을 지정된 이름으로 저장합니다.

일반적인 양자화 수준:

q4_0, q4_1: 기본 4비트 양자화.
q5_0, q5_1: 기본 5비트 양자화.
q8_0: 8비트 양자화 (파일 크기가 더 크고 원본 품질에 더 가까움).
q3_K_S, q3_K_M, q3_K_L: 더 진보된 3비트 "K-Quant" 방법 (작은/중간/큰 내부 변형). 매우 작고 눈에 띄는 품질 절충.
q4_K_S, q4_K_M: 진보된 4비트 K-Quant. q4_K_M은 종종 권장되는 최적 지점입니다.
q5_K_S, q5_K_M: 진보된 5비트 K-Quant. 좋은 균형, Q4_K보다 약간 큼.
q6_K: 진보된 6비트 K-Quant. 크기가 더 크고 Q8 품질에 가까움.

올바른 양자화 수준을 선택하는 것은 하드웨어 제약 조건과 잠재적인 품질 저하에 대한 허용 범위에 따라 다릅니다. 종종 q4_K_M 또는 q5_K_M을 먼저 시도해 볼 가치가 있습니다.

사용자 지정 Ollama 모델 공유하기

Modelfile을 사용하여 고유한 모델 변형을 만든 경우(예: 특정 LoRA 적용, 창의적인 시스템 프롬프트 및 템플릿 설정 또는 매개변수 미세 조정) 공식 Ollama 모델 레지스트리 웹사이트를 통해 더 넓은 Ollama 커뮤니티와 창작물을 공유할 수 있습니다.

Ollama 모델 공유 단계:

Ollama 계정 만들기: Ollama 웹사이트(ollama.com)에서 무료 계정에 가입합니다. 선택한 사용자 이름이 공유 모델의 네임스페이스가 됩니다.
로컬 Ollama 연결: 로컬 Ollama 설치를 온라인 계정과 연결해야 합니다. 여기에는 로컬 머신의 Ollama 공개 키를 웹사이트의 계정 설정에 추가하는 작업이 포함됩니다. 웹사이트에서는 운영 체제에 따라 로컬 공개 키 파일(id_ed25519.pub)을 찾는 방법에 대한 구체적인 지침을 제공합니다.
모델 이름 올바르게 지정: 공유 모델은 Ollama 사용자 이름으로 네임스페이스를 지정해야 하며 사용자 이름/모델 이름 형식을 따라야 합니다. 로컬 사용자 지정 모델의 이름이 다른 경우(예: mario), 먼저 ollama cp를 사용하여 올바른 네임스페이스 이름으로 복사해야 합니다.

# 사용자 이름이 'luigi'이고 로컬 모델이 'mario'라고 가정
ollama cp mario luigi/mario

레지스트리에 모델 푸시: 모델이 로컬에서 올바르게 명명되고 키가 연결되면 ollama push 명령을 사용합니다.

ollama push luigi/mario

Ollama는 필요한 모델 레이어와 메타데이터를 레지스트리에 업로드합니다.

푸시가 완료되면 전 세계 다른 Ollama 사용자는 네임스페이스 이름을 사용하여 공유 모델을 쉽게 다운로드하고 실행할 수 있습니다.

ollama run luigi/mario

이 공유 메커니즘은 협업을 촉진하고 커뮤니티가 특수하거나 창의적으로 사용자 지정된 모델로부터 혜택을 받을 수 있도록 합니다.

GPU 가속으로 Ollama 성능 최적화하기

Ollama는 모델을 순전히 컴퓨터의 CPU에서 실행할 수 있지만, 호환되는 그래픽 처리 장치(GPU)를 활용하면 모델이 텍스트를 생성하는 속도(추론 속도)가 크게 향상됩니다. Ollama는 가능한 경우 지원되는 GPU를 자동으로 감지하고 활용하도록 설계되었습니다.

NVIDIA GPU를 사용하는 Ollama: Ollama는 NVIDIA GPU에 대한 뛰어난 지원을 제공하며 다음이 필요합니다.

CUDA 컴퓨팅 기능 5.0 이상을 갖춘 GPU(대부분의 GeForce GTX 900 시리즈/Quadro M 시리즈 이상 카드). 호환성은 NVIDIA의 CUDA GPU 목록을 확인하십시오.
호스트 시스템(Linux 또는 Windows)에 올바르게 설치된 공식 독점 NVIDIA 드라이버.
Docker를 사용하는 Linux에서는 NVIDIA 컨테이너 툴킷이 설치 및 구성되어 있어야 합니다.
Ollama는 호환되는 하드웨어 및 드라이버를 자동으로 감지하고 계산을 GPU로 오프로드해야 합니다.

AMD Radeon GPU를 사용하는 Ollama: 최신 AMD GPU 지원은 Windows 및 Linux 모두에서 사용할 수 있습니다.

Windows에서는 최신 AMD Radeon 소프트웨어(Adrenalin Edition) 드라이버가 필요합니다.
Linux에서는 ROCm(Radeon Open Compute 플랫폼) 소프트웨어 스택이 설치되어 있어야 합니다(버전 5 또는 6+ 권장). Ollama Linux 설치 프로그램 또는 :rocm Docker 이미지는 종종 종속성 해결에 도움이 되지만 특정 배포판에서는 완전한 호환성을 위해 수동 ROCm 설치가 필요할 수 있습니다.
지원되는 GPU에는 일반적으로 RX 6000 시리즈, RX 7000 시리즈, PRO W6000/W7000 시리즈 및 일부 Instinct 가속기가 포함됩니다. 자세한 목록은 공식 Ollama GPU 설명서를 확인하십시오.

Apple Silicon을 사용하는 Ollama (macOS): M1, M2, M3 또는 M4 시리즈 칩이 장착된 Mac에서는 Ollama가 Apple의 Metal 그래픽 API를 통해 내장 GPU 기능을 자동으로 활용합니다. 일반적으로 추가 드라이버 설치나 구성이 필요하지 않습니다. GPU 가속은 즉시 작동합니다.

Ollama GPU 사용 확인하기:
Ollama가 실제로 GPU를 사용하고 있는지 확인하는 가장 쉬운 방법은 모델이 로드된 상태에서 ollama ps 명령을 실행하는 것입니다(예: 다른 터미널에서 ollama run <모델>을 시작한 직후 또는 API 요청이 처리되는 동안). 출력에서 PROCESSOR 열을 확인합니다.

gpu: 모델 계층이 주로 GPU에 로드되었음을 나타냅니다.
cpu: 모델이 CPU에서만 실행되고 있음을 나타냅니다. 이는 호환되는 GPU가 감지되지 않았거나, 드라이버가 없거나 잘못되었거나, GPU 지원 초기화 중에 문제가 발생했음을 의미할 수 있습니다. 오류는 Ollama 서버 로그를 확인하십시오.

다중 GPU Ollama 설정에서 특정 GPU 선택하기:
시스템에 여러 개의 호환되는 GPU가 있는 경우, Ollama 서버 프로세스를 시작하기 전에 환경 변수를 설정하여 Ollama(및 기본 llama.cpp)에 사용할 특정 장치를 지시할 수 있습니다.

NVIDIA (CUDA_VISIBLE_DEVICES): 이 변수를 GPU 인덱스(0부터 시작) 또는 가급적 GPU UUID의 쉼표로 구분된 목록으로 설정합니다.
export CUDA_VISIBLE_DEVICES=0 (NVIDIA에서 감지한 첫 번째 GPU만 사용).
export CUDA_VISIBLE_DEVICES=1 (두 번째 GPU만 사용).
export CUDA_VISIBLE_DEVICES=GPU-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,GPU-yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy (nvidia-smi -L을 사용하여 찾을 수 있는 특정 UUID로 식별된 GPU 사용).
AMD (ROCR_VISIBLE_DEVICES): 이 변수를 rocminfo 명령에서 보고하는 GPU 인덱스(일반적으로 0부터 시작)의 쉼표로 구분된 목록으로 설정합니다.
export ROCR_VISIBLE_DEVICES=0 (감지된 첫 번째 AMD GPU 사용).
export ROCR_VISIBLE_DEVICES=1,2 (감지된 두 번째 및 세 번째 AMD GPU 사용).

잘못된 장치 ID(예: export CUDA_VISIBLE_DEVICES=-1)를 설정하는 것은 의도적으로 Ollama가 CPU만 사용하도록 강제하는 방법으로 종종 사용되며 디버깅에 유용할 수 있습니다. 이러한 환경 변수를 설정한 후 변경 사항을 적용하려면 Ollama 서버/앱을 다시 시작해야 합니다.

Ollama 환경 구성하기

기본 설정 외에도 Ollama의 동작은 다양한 환경 변수를 사용하여 미세 조정할 수 있습니다. 이를 통해 네트워크 설정, 저장 위치, 로깅 수준 등을 사용자 지정할 수 있습니다.

구성을 위한 주요 Ollama 환경 변수

OLLAMA_HOST: Ollama API 서버가 수신 대기하는 네트워크 인터페이스 및 포트를 제어합니다.
기본값: 127.0.0.1:11434 (루프백 인터페이스에서만 수신 대기하며 동일한 시스템에서만 액세스 가능).
예: 0.0.0.0:11434 (사용 가능한 모든 네트워크 인터페이스에서 수신 대기하여 로컬 네트워크의 다른 장치에서 Ollama에 액세스할 수 있도록 함. 경고: Ollama를 외부에 노출하는 경우 적절한 방화벽 규칙이 설정되어 있는지 확인하십시오).
예: 192.168.1.100:11500 (특정 로컬 IP 주소 및 사용자 지정 포트에서만 수신 대기).
OLLAMA_MODELS: 중요하게도 이 변수를 사용하면 Ollama가 다운로드한 모델을 저장하고 찾을 사용자 지정 디렉터리 경로를 지정할 수 있습니다. 기본 드라이브(~/.ollama 또는 C:\Users\<User>\.ollama가 있는 위치)의 공간이 부족하거나 모델을 전용 SSD 또는 더 큰 드라이브에 구성하려는 경우 매우 유용합니다.
예 (Linux/macOS): export OLLAMA_MODELS=/mnt/large_drive/my_ollama_models
예 (Windows): 시스템 속성을 통해 OLLAMA_MODELS를 D:\OllamaData로 설정합니다.
중요: 디렉터리가 존재하고 Ollama 서버 프로세스를 실행하는 사용자 계정에 이 사용자 지정 경로에 대한 전체 읽기 및 쓰기 권한이 있는지 확인하십시오.
OLLAMA_ORIGINS: Ollama API에 대한 교차 출처 리소스 공유(CORS)를 관리합니다. 기본적으로 웹 브라우저는 웹 페이지가 제공된 도메인(출처)과 다른 도메인에 API 요청을 하는 것을 제한합니다. 다른 출처(예: http://localhost:3000)에서 제공되는 별도의 웹 UI(예: Open WebUI, Lobe Chat)를 실행 중이고 해당 UI가 Ollama API(http://localhost:11434)를 호출해야 하는 경우 UI의 출처를 이 변수에 추가해야 합니다.
예: export OLLAMA_ORIGINS=http://localhost:3000,http://192.168.1.50:8080 (이 두 특정 출처에서의 요청 허용).
예: export OLLAMA_ORIGINS='*' (모든 출처에서의 요청 허용. 주의해서 사용하십시오. 특히 OLLAMA_HOST가 127.0.0.1이 아닌 경우 API가 광범위하게 노출될 수 있으므로). chrome-extension://*와 같은 프로토콜을 포함할 수 있습니다.
OLLAMA_DEBUG: 상세 디버그 로깅을 활성화하려면 1로 설정합니다. 이렇게 하면 GPU 감지 단계, 모델 로드 세부 정보 및 잠재적 오류를 포함하여 Ollama의 내부 작업에 대한 훨씬 자세한 정보가 제공되므로 문제 해결에 매우 유용합니다.
예: export OLLAMA_DEBUG=1
OLLAMA_KEEP_ALIVE: Ollama가 마지막 요청 후 모델을 메모리에 로드된 상태로 유지하는 시간을 제어합니다. 기본적으로 약 5분(5m)일 수 있습니다. 0으로 설정하면 사용 직후 모델이 언로드됩니다(RAM/VRAM 절약하지만 다음 요청의 로드 시간 증가). 더 긴 시간(예: 30m) 또는 -1(서버가 중지될 때까지 무기한 로드됨)로 설정하면 동일한 모델에 대한 빈번한 요청 속도를 높일 수 있지만 리소스를 지속적으로 소비합니다.
예: export OLLAMA_KEEP_ALIVE=15m
HTTPS_PROXY / HTTP_PROXY / NO_PROXY: Ollama가 외부 인터넷 요청(예: ollama.com에서 모델을 다운로드하기 위해 ollama pull 실행 시)을 프록시 서버를 통해 라우팅해야 하는 경우 사용되는 표준 네트워킹 환경 변수. 기업 환경에서 일반적입니다.
예: export HTTPS_PROXY=http://proxy.mycompany.com:8080

Ollama 환경 변수 설정 방법

이러한 변수를 설정하는 올바른 방법은 Ollama를 설치하고 실행한 방식에 따라 다릅니다.

macOS의 Ollama (앱 사용): macOS의 GUI 애플리케이션 환경 변수는 launchctl을 사용하여 설정하는 것이 가장 좋습니다. 터미널을 열고 다음을 사용합니다.

launchctl setenv OLLAMA_MODELS "/Volumes/ExternalSSD/OllamaStorage"
launchctl setenv OLLAMA_HOST "0.0.0.0:11434"
# 다른 변수에 대해 반복

변수를 설정한 후 변경 사항을 적용하려면 메뉴 모음 아이콘에서 Ollama 애플리케이션을 종료하고 다시 시작해야 합니다.

Linux의 Ollama (Systemd 서비스 사용): 권장되는 방법은 서비스에 대한 재정의 파일을 만드는 것입니다.

sudo systemctl edit ollama.service를 실행합니다. 빈 텍스트 편집기가 열립니다.
필요에 따라 변수와 값을 수정하여 다음 줄을 추가합니다.

[Service]
Environment="OLLAMA_MODELS=/path/to/custom/model/dir"
Environment="OLLAMA_HOST=0.0.0.0:11434"
Environment="OLLAMA_DEBUG=1"

편집기를 저장하고 닫습니다.
변경 사항을 적용합니다: sudo systemctl daemon-reload
Ollama 서비스를 다시 시작합니다: sudo systemctl restart ollama

Windows의 Ollama: 내장된 환경 변수 편집기를 사용합니다.

시작 메뉴에서 "시스템 환경 변수 편집"을 검색하여 엽니다.
"환경 변수..." 버튼을 클릭합니다.
특정 사용자("사용자 변수") 또는 모든 사용자("시스템 변수")에 대해 변수를 설정할 수 있습니다. 시스템 변수는 일반적으로 관리자 권한이 필요합니다.
원하는 섹션 아래에서 "새로 만들기..."를 클릭합니다.
변수 이름(예: OLLAMA_MODELS)과 변수 값(예: D:\OllamaData)을 입력합니다.
열려 있는 모든 대화 상자에서 확인을 클릭합니다.
중요하게도 Ollama 백그라운드 프로세스를 다시 시작해야 합니다. 작업 관리자(Ctrl+Shift+Esc)를 열고 "서비스" 탭으로 이동하여 "Ollama"를 찾고 마우스 오른쪽 버튼을 클릭한 다음 "다시 시작"을 선택합니다. 또는 컴퓨터를 재부팅합니다.

Docker를 통한 Ollama: 각 변수에 대해 -e 플래그를 사용하여 docker run 명령에서 직접 환경 변수를 전달합니다.

docker run -d \
  --gpus=all \
  -v ollama_data:/root/.ollama \
  -p 127.0.0.1:11434:11434 \
  -e OLLAMA_HOST="0.0.0.0:11434" \
  -e OLLAMA_DEBUG="1" \
  -e OLLAMA_KEEP_ALIVE="10m" \
  --name my_ollama_configured \
  ollama/ollama

터미널에서 수동 ollama serve를 통한 Ollama: 명령 앞에 동일한 줄에 변수 할당을 접두사로 붙입니다.

OLLAMA_DEBUG=1 OLLAMA_HOST=0.0.0.0:11434 OLLAMA_MODELS=/data/ollama ollama serve

이러한 변수는 해당 특정 서버 인스턴스에만 적용됩니다.

설정에 적합한 방법을 선택하고 변경 사항을 적용한 후 Ollama 서버 프로세스를 다시 시작해야 합니다.

일반적인 Ollama 문제 해결하기

Ollama는 단순성에 중점을 두지만 가끔 문제가 발생할 수 있습니다. 다음은 자주 발생하는 문제를 진단하고 해결하는 방법입니다.

Ollama 로그 확인하기

주요 진단 도구는 Ollama 서버 로그 파일입니다. 시작 정보, 모델 로드 시도, GPU 감지 결과, API 요청 및 가장 중요한 상세 오류 메시지가 기록됩니다.

기본 로그 파일 위치:

macOS의 Ollama: ~/.ollama/logs/server.log
Linux의 Ollama (Systemd): 저널 제어 명령을 사용합니다: journalctl -u ollama. 실시간으로 로그를 추적하려면 -f를 추가합니다(journalctl -u ollama -f). 마지막 100줄을 보려면 -n 100을 사용합니다(journalctl -u ollama -n 100).
Windows의 Ollama: 로그 파일은 %LOCALAPPDATA%\Ollama 내에 있는 server.log입니다. 파일 탐색기 주소 표시줄이나 실행 대화 상자(Win+R)에 %LOCALAPPDATA%\Ollama를 붙여넣어 이 폴더를 쉽게 열 수 있습니다.
Docker를 통한 Ollama: Docker 로그 명령을 사용합니다: docker logs my_ollama (my_ollama를 컨테이너 이름으로 바꿉니다). 추적하려면 -f를 추가합니다(docker logs -f my_ollama).
수동 ollama serve를 통한 Ollama: 로그는 명령을 실행한 터미널 창에 직접 인쇄됩니다.

팁: 더 자세한 문제 해결을 위해 Ollama 서버를 시작하기 전에 항상 OLLAMA_DEBUG=1 환경 변수를 설정하여 디버그 로깅을 활성화한 다음 로그를 다시 확인하십시오.

Ollama 오류 수정: `listen tcp 127.0.0.1:11434: bind: address already in use`

이 특정 오류 메시지는 신규 사용자가 접하는 가장 일반적인 문제 중 하나입니다. Ollama가 필요로 하는 네트워크 포트(기본값 11434)를 다른 프로세스가 이미 점유하고 있어 Ollama가 API 서버를 시작할 수 없음을 의미합니다.

가능성 있는 원인:
Ollama 서버의 다른 인스턴스가 이미 백그라운드에서 실행 중입니다(아마도 깔끔하게 종료되지 않은 이전 세션에서).
시스템의 완전히 다른 애플리케이션이 우연히 포트 11434를 사용하고 있습니다.
해결책 1: 충돌하는 프로세스 식별 및 중지: 포트를 사용 중인 프로세스를 찾아 중지해야 합니다(안전하게 수행할 수 있는 경우).
Linux / macOS: 터미널을 열고 sudo lsof -i :11434 또는 sudo netstat -tulnp | grep 11434를 실행합니다. 이 명령은 포트를 사용 중인 프로그램의 프로세스 ID(PID)를 표시해야 합니다. 그런 다음 정상적으로 중지하거나 sudo kill <PID>를 사용할 수 있습니다. 오래된 Ollama 프로세스인 경우 강제 종료하면 충돌이 해결됩니다.
Windows: 관리자 권한으로 명령 프롬프트를 열고 netstat -ano | findstr "11434"를 실행합니다. 마지막 열에서 PID를 확인합니다. 작업 관리자(Ctrl+Shift+Esc)를 열고 "세부 정보" 탭(또는 "프로세스" 탭에서 PID 열 추가)으로 이동하여 해당 PID를 가진 프로세스를 찾아 적절한 경우 종료합니다.
해결책 2: Ollama의 수신 포트 변경: 충돌하는 프로세스를 중지할 수 없거나 의도적으로 Ollama를 다른 포트에서 실행하려는 경우 Ollama가 대체 포트를 사용하도록 구성할 수 있습니다. Ollama를 시작하기 전에 OLLAMA_HOST 환경 변수를 설정하여 원하는 포트를 포함시킵니다.
예: OLLAMA_HOST를 127.0.0.1:11435로 설정합니다(구성 섹션에서 설명한 방법 사용).
이 변경 후 API 클라이언트 구성, 웹 UI 또는 스크립트를 새 포트(예: http://localhost:11435)를 가리키도록 조정해야 합니다.

Ollama GPU 감지 및 사용 문제 해결하기

ollama ps가 gpu 대신 cpu를 표시하거나 로그에 특정 GPU 관련 오류(예: CUDA error, ROCm error)가 발생하는 경우 다음 단계를 따르십시오.

GPU 호환성 확인: 특정 GPU 모델이 GitHub의 공식 Ollama GPU 문서에서 지원되는 것으로 나열되어 있는지 다시 확인합니다.
드라이버 업데이트: NVIDIA 또는 AMD 웹사이트에서 직접 설치한 최신 안정 공식 드라이버가 있는지 확인합니다. OS에 포함된 일반 드라이버는 종종 불충분합니다. 드라이버 설치 후 전체 시스템 재부팅을 강력히 권장합니다.
Ollama 로그 확인 (디버그 모드): OLLAMA_DEBUG=1을 설정하고 Ollama 서버를 다시 시작한 다음 시작 로그를 주의 깊게 검토합니다. GPU 감지, 라이브러리 로딩(CUDA, ROCm) 및 특정 오류 코드와 관련된 메시지를 찾습니다.
NVIDIA 관련 (Linux):
nvidia-smi 명령이 작동하고 GPU 및 드라이버 버전이 표시되는지 확인합니다.
Docker를 사용하는 경우 NVIDIA 컨테이너 툴킷이 설치되어 작동하는지 확인합니다 (docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi).
필요한 커널 모듈이 로드되었는지 확인합니다 (lsmod | grep nvidia). 때때로 다시 로드하면 (sudo rmmod nvidia_uvm nvidia && sudo modprobe nvidia_uvm nvidia) 도움이 될 수 있습니다.
하드웨어 또는 드라이버 오류는 시스템 로그(dmesg | grep -iE 'nvidia|nvrm')를 확인합니다.
AMD 관련 (Linux):
rocminfo 명령이 작동하고 GPU가 표시되는지 확인합니다.
Ollama(또는 Docker 컨테이너)를 실행하는 사용자에게 /dev/kfd 및 /dev/dri/renderD* 장치에 대한 올바른 권한이 있는지 확인합니다(종종 render 및 video 그룹의 멤버십이 필요함). groups $USER 또는 groups ollama로 그룹 멤버십을 확인합니다. Docker 명령에 --group-add render --group-add video가 필요할 수 있습니다.
오류는 시스템 로그(dmesg | grep -iE 'amdgpu|kfd')를 확인합니다.
CPU 강제 (테스트용): 임시 진단 단계로 CUDA_VISIBLE_DEVICES=-1 또는 ROCR_VISIBLE_DEVICES=-1을 설정하여 CPU 사용을 강제해 봅니다. Ollama가 CPU에서 올바르게 실행되면 문제가 GPU 설정과 관련 있음을 확인합니다.

기타 일반적인 Ollama 문제 해결하기

권한 오류 (모델 디렉토리): 특히 Systemd 서비스를 사용하는 Linux에서 Ollama가 모델을 가져오거나 생성하지 못하는 경우 모델 저장 디렉토리(OLLAMA_MODELS 또는 기본값)에 대한 쓰기 권한이 없을 수 있습니다. 디렉토리가 존재하고 ollama 사용자/그룹이 소유하거나 쓰기 가능한지 확인합니다 (sudo chown -R ollama:ollama /path/to/models 및 sudo chmod -R 775 /path/to/models).
느린 모델 다운로드 (ollama pull):
기본 인터넷 연결 속도를 확인합니다.
프록시 뒤에 있는 경우 HTTPS_PROXY가 올바르게 구성되었는지 확인합니다.
ollama.com에 대한 연결을 차단하거나 제한할 수 있는 방화벽 규칙을 확인합니다.
WSL2를 사용하는 Windows에서는 알려진 LSO(Large Send Offload) 문제가 때때로 WSL 내 네트워크 성능에 영향을 줄 수 있습니다. Windows 네트워크 어댑터 설정에서 WSL 가상 네트워크 어댑터에 대해 LSOv2를 비활성화하면 도움이 될 수 있지만 지금은 덜 일반적입니다.
문자 깨짐 터미널 출력 (이전 Windows의 ollama run): 이전 Windows 10 버전의 cmd.exe 또는 PowerShell에서 ←[?25h...와 같은 이상한 문자가 표시되면 ANSI 이스케이프 코드 지원 부족 때문일 가능성이 높습니다. 가장 좋은 해결책은 다음과 같습니다.
Windows 10을 버전 22H2 이상으로 업그레이드합니다.
Windows 11을 사용합니다.
뛰어난 ANSI 지원을 제공하는 최신 Windows 터미널 애플리케이션을 사용합니다.

이러한 문제 해결 단계를 모두 시도하고 디버그 로그를 확인했지만 성공하지 못한 경우 Ollama 커뮤니티는 훌륭한 리소스입니다. 문제에 대한 명확한 설명, OS, Ollama 버전, 하드웨어(CPU/GPU/RAM), 사용 중인 특정 모델, 실행한 명령 및 중요하게는 디버그 로그의 관련 섹션을 포함하여 준비합니다. Ollama Discord에 질문을 게시하거나 Ollama GitHub 리포지토리에 잘 문서화된 문제를 제출하십시오.

Ollama를 완전히 제거하는 방법

시스템에서 Ollama를 제거해야 하는 경우 프로세스는 초기 설치 방법에 따라 다릅니다. 일반적으로 애플리케이션/바이너리, 백그라운드 서비스(해당되는 경우) 및 저장된 모델/구성 파일을 제거하는 작업이 포함됩니다.

macOS에서 Ollama 제거하기 (.app 통해 설치):

Ollama 종료: Ollama 메뉴 모음 아이콘을 클릭하고 "Ollama 종료"를 선택합니다.
애플리케이션 제거: /Applications 폴더에서 Ollama.app을 휴지통/Bin으로 드래그합니다.
데이터 및 구성 제거: 터미널을 열고 rm -rf ~/.ollama를 실행합니다. 경고: 다운로드한 모든 모델과 구성이 영구적으로 삭제됩니다. 실행하기 전에 명령을 다시 확인하십시오.
(선택 사항) 환경 변수 설정 해제: launchctl setenv를 사용하여 수동으로 변수를 설정한 경우 설정 해제할 수 있습니다: launchctl unsetenv OLLAMA_HOST, launchctl unsetenv OLLAMA_MODELS 등.

Windows에서 Ollama 제거하기 (.exe 통해 설치):

Windows 제거 프로그램 사용: "설정" > "앱" > "설치된 앱"으로 이동합니다. 목록에서 "Ollama"를 찾아 옆에 있는 세 개의 점(...)을 클릭하고 "제거"를 선택합니다. 제거 프롬프트를 따릅니다.
데이터 및 구성 제거: 제거 프로그램이 완료된 후 Ollama 데이터 디렉토리를 수동으로 삭제합니다. 파일 탐색기를 열고 주소 표시줄에 %USERPROFILE%\.ollama를 입력하고 Enter 키를 누른 다음 .ollama 폴더 전체를 삭제합니다. 경고: 모든 모델이 삭제됩니다.
(선택 사항) 환경 변수 제거: 시스템 속성을 통해 수동으로 OLLAMA_HOST, OLLAMA_MODELS 등을 추가한 경우 해당 위치("시스템 환경 변수 편집")로 돌아가서 삭제합니다.

Linux에서 Ollama 제거하기 (스크립트 또는 수동 바이너리 통해 설치):

서비스 중지: sudo systemctl stop ollama
서비스 비활성화: sudo systemctl disable ollama
바이너리 제거: sudo rm /usr/local/bin/ollama (또는 설치한 경로).
서비스 파일 제거: sudo rm /etc/systemd/system/ollama.service
Systemd 다시 로드: sudo systemctl daemon-reload
(선택 사항) 사용자/그룹 제거: ollama 사용자/그룹이 생성된 경우: sudo userdel ollama, sudo groupdel ollama.
데이터 및 구성 제거: 모델 저장 디렉토리를 삭제합니다. 저장 위치에 따라 다릅니다.

사용자로 실행한 경우: rm -rf ~/.ollama
시스템 서비스(ollama 사용자)로 실행한 경우: sudo rm -rf /usr/share/ollama/.ollama (또는 서비스 파일의 OLLAMA_MODELS로 지정된 경로).
경고: sudo rm -rf는 극도의 주의를 기울여 사용하십시오. 실행하기 전에 경로가 올바른지 확인하십시오.

Docker를 통한 Ollama 제거:

컨테이너 중지: docker stop my_ollama (컨테이너 이름 사용).
컨테이너 제거: docker rm my_ollama.
이미지 제거: docker rmi ollama/ollama (사용한 경우 ollama/ollama:rocm도 제거).
(선택 사항, 파괴적) 볼륨 제거: Docker 볼륨에 저장된 다운로드한 모든 모델을 삭제하려면 docker volume rm ollama_data를 실행합니다 (생성한 볼륨 이름 사용). 경고: 되돌릴 수 없습니다.

결론: Ollama와 함께 로컬 AI의 힘을 받아들이기

Ollama는 현대 대규모 언어 모델의 막대한 힘에 대한 접근을 민주화하는 데 중추적인 도구로 서 있습니다. 설정, 구성 및 실행의 복잡성을 우아하게 추상화함으로써 숙련된 개발자 및 연구원에서 호기심 많은 애호가에 이르기까지 다양한 사용자가 자신의 하드웨어에서 직접 정교한 AI를 실행할 수 있도록 지원합니다. 이점은 분명합니다. 비교할 수 없는 개인 정보 보호, 반복되는 API 비용으로부터의 자유, 안정적인 오프라인 작동, 직관적인 Modelfile 시스템과 강력한 API를 사용하여 모델을 심층적으로 사용자 지정하고 실험할 수 있는 자유로운 능력입니다.

목표가 차세대 AI 기반 애플리케이션을 구축하는 것이든, 데이터 주권을 유지하면서 최첨단 연구를 수행하는 것이든, 또는 단순히 외부 종속성 없이 언어 생성의 매혹적인 기능을 탐색하는 것이든, Ollama는 안정적이고 효율적이며 사용자 친화적인 기반을 제공합니다. llama.cpp와 같은 추론 엔진의 원시적인 힘과 사용자의 실제 요구 사항 사이의 격차를 성공적으로 메우고 활기찬 오픈 소스 AI 환경 내에서 혁신을 촉진합니다.

로컬 LLM의 세계로의 여정은 Ollama 덕분에 접근 가능하고 매우 보람 있습니다. 애플리케이션을 다운로드하고 ollama pull을 사용하여 첫 번째 모델을 가져오고 ollama run으로 대화를 시작하여 바로 자신의 기계에서 인공 지능의 방대한 잠재력을 발휘하기 시작하십시오.

💡

버튼