Python에서 로컬 LLM: Ollama와 LiteLLM으로 빠른 시작

# Python에서 로컬 LLM: Ollama와 LiteLLM으로 빠른 시작하기

대형 언어 모델(LLM) 세계에 첫발을 내디디는 개발자들은 종종 장애물에 부딪힙니다: 클라우드 서비스 등록, API 키 관리, 지속적인 토큰 비용. 기능적으로는 괜찮지만 초기 실험이나 로컬 개발에는 이상적이지 않습니다. 이 글에서는 효과적인 대안을 소개합니다: 컴퓨터에 LLM을 직접 배포하고 통합하는 방법. Ollama로 모델을 실행하고 LiteLLM으로 Python 애플리케이션에 통합하는 환경을 단계별로 안내하며, 외부 서비스 없이 첫 의미 있는 응답을 받는 방법을 보여드리겠습니다.

로컬 LLM 개발의 장점

로컬 LLM 배포는 학습과 프로토타이핑에 확실한 이점을 제공합니다. 첫째, API 키와 비용이 완전히 사라져 무제한 실험이 가능합니다. 둘째, 요청마다 인터넷 연결이 필요 없어 오프라인 개발이나 네트워크가 불안정한 환경에서 필수적입니다. 셋째, LLM 상호작용 과정이 투명해집니다: Python 코드가 LiteLLM과 통신하고, LiteLLM이 Ollama로 요청을 전달하며, 로컬 모델로 이어지는 과정을 직접 관찰할 수 있습니다. 이는 'AI 마법'이 아니라 추적 가능한 소프트웨어 로직으로, 디버깅과 아키텍처 이해를 크게 단순화합니다. LLM 통합 메커니즘을 깊이 이해하려는 개발자에게 로컬 접근은 최고의 출발점입니다.

Ollama와 LiteLLM: 핵심 아키텍처 구성 요소

설치에 들어가기 전에 사용할 두 주요 도구의 역할을 구분하는 게 중요합니다: Ollama와 LiteLLM.

Ollama는 대형 언어 모델을 로컬에서 실행하는 강력한 도구입니다. 컴퓨터에서 LLM 다운로드, 저장, 실행을 관리하는 서버 역할을 하며, 통합 API를 제공합니다. 본질적으로 로컬 LLM 런타임으로 Llama, Mistral, Qwen 등 다양한 모델을 쉽게 다루게 합니다.
LiteLLM은 다양한 LLM 제공자에 대한 API 요청을 통합하는 경량 Python 라이브러리입니다. 핵심은 OpenAI, Anthropic, Google Gemini 같은 클라우드 서비스와 Ollama 같은 로컬 솔루션에 단일 인터페이스를 제공하는 점입니다. LiteLLM을 통해 로컬 모델용 코드를 최소 변경으로 클라우드 제공자에 쉽게 적용할 수 있습니다.

요약하자면, Ollama가 로컬 모델을 실행하고, LiteLLM이 Python에서 표준화된 상호작용 방식을 제공하며, 여러분의 코드가 이를 중심으로 완전한 애플리케이션을 구축합니다.

Ollama 설치와 로컬 모델 다운로드

로컬 LLM 작업을 시작하려면 몇 가지 순차적 단계를 따르세요.

Ollama 설치

먼저 운영 체제(Windows, macOS, Linux)에 맞게 공식 사이트(ollama.com)에서 Ollama를 다운로드해 설치하세요. 설치 후 터미널에서 다음 명령어로 확인하세요:

ollama --version

버전 번호가 출력되면 Ollama가 사용 준비 완료입니다. Windows에서는 시스템 트레이에 Ollama 아이콘(🦙)이 있어야 백그라운드 서비스가 활성 상태임을 나타냅니다.

로컬 LLM 다운로드

Ollama 자체는 모델이 아니라 이를 실행하는 플랫폼입니다. 이제 특정 대형 언어 모델을 다운로드하세요. qwen2.5:3b가 훌륭한 선택입니다 — 대부분 노트북에서 잘 작동하는 컴팩트하면서도 강력한 모델로 한국어도 지원합니다. 터미널에서 다운로드를 시작하세요:

ollama run qwen2.5:3b

첫 실행 시 모델이 다운로드되어 로컬에 저장됩니다. 완료되면 Ollama 대화 모드로 들어갑니다. 예를 들어 안녕! Python이 뭔지 두 문장으로 설명해줘.라고 물어보며 테스트하세요. 응답이 오면 주요 관문 통과입니다. 대화 종료는 /bye입니다.

참고: 하드웨어 성능이 qwen2.5:3b에 부족하면 더 가벼운 ollama run qwen2.5:1.5b를 시도하세요. Python 코드 로직은 동일합니다.

Python 환경 준비

프로젝트 의존성을 격리하기 위해 가상 환경을 사용하는 게 좋습니다.

프로젝트 폴더 생성 후 이동:

```bash

mkdir llm-chat

cd llm-chat

```

가상 환경 초기화:

```bash

python -m venv venv

```

활성화.

* Windows: venv\Scripts\activate

* macOS / Linux: source venv/bin/activate

활성화 성공 시 명령줄에 (venv) 접두사가 나타납니다.

LiteLLM 라이브러리 설치:

```bash

pip install litellm

```

이제 코딩 준비 완료입니다.

Python에서 LLM 통합: 첫 번째 요청

프로젝트 루트에 main.py 파일을 만들고 다음 코드를 추가하세요:

from litellm import completion
 
MODEL = "ollama_chat/qwen2.5:3b"
API_BASE = "http://localhost:11434"
 
 
def ask(question: str) -> str:
    response = completion(
        model=MODEL,
        messages=[
            {"role": "user", "content": question}
        ],
        api_base=API_BASE,
        request_timeout=120,
    )
    return response.choices[0].message.content
 
 
answer = ask("안녕! Python에 대해 한 문장으로 설명해줘.")
print(answer)

활성화된 가상 환경에서 스크립트를 실행하세요:

python main.py

콘솔에 모델의 의미 있는 응답이 나오면 Python 코드에 로컬 LLM 통합 성공입니다. 추상 모델이 애플리케이션의 기능적 구성 요소로 변신한 결정적 순간입니다.

`main.py` 코드 분석

이 최소주의적이지만 기능적인 스크립트의 주요 요소를 살펴보죠:

from litellm import completion: LiteLLM 라이브러리의 핵심 completion 함수를 가져옵니다. LLM에 요청을 보내기 위해 설계됐습니다.
MODEL = "ollama_chat/qwen2.5:3b": 사용할 모델을 정의합니다. ollama_chat/ 접두사는 LiteLLM에 로컬 Ollama 서비스로 요청을 안내합니다. 다운로드한 모델 이름(예: qwen2.5:1.5b)을 지정하세요.
API_BASE = "http://localhost:11434": 로컬 Ollama API 서버 주소를 지정합니다. 기본 포트는 11434입니다.
messages=[{"role": "user", "content": question}]: 대부분의 현대 LLM API 상호작용 기본 구조입니다. 메시지 목록으로 요청을 전달하며, 각 메시지는 role(예: "user", "assistant", "system")과 content(메시지 텍스트)를 가집니다. 단일 질문에도 이 구조를 사용해 대화 이력과 컨텍스트 작업의 기반을 마련합니다.
request_timeout=120: 모델 응답 대기 최대 시간을 초 단위로 설정합니다. 로컬 모델은 초기 시작이나 복잡한 요청 처리에 더 많은 시간이 필요할 수 있습니다.
response.choices[0].message.content: 모델이 반환한 전체 응답 객체에서 생성된 텍스트를 추출합니다. response 객체에는 후속 탐구할 수 있는 다른 유용한 정보가 많습니다.

일반적인 시작 문제 해결

설치 과정에서 다양한 어려움을 겪을 수 있습니다. 가장 흔한 문제와 해결법입니다:

문제 1: Connection refused 또는 Failed to connect

* 원인: Ollama 서비스가 실행 중이지 않거나 접근 불가.

* 해결: Ollama 활성 확인. 시스템 트레이의 🦙 아이콘(Windows/macOS) 확인하거나 터미널에서 ollama list 실행. 응답이 오면 서비스 정상입니다.

문제 2: Model not found

* 원인: 코드에 지정한 모델이 다운로드되지 않았거나 이름 불일치.

* 해결: ollama list로 로컬 모델 목록 확인 후 main.py의 MODEL 변수 수정.

문제 3: 응답 느리거나 성능 저하

* 원인: 모델 첫 실행 시 메모리 로딩으로 느리거나 하드웨어 부하 과다.

* 해결: 더 기다리세요. 리소스 집약적 앱 종료. qwen2.5:1.5b 같은 가벼운 버전 시도.

문제 4: ModuleNotFoundError: No module named 'litellm'

* 원인: LiteLLM이 설치된 활성화된 가상 환경 밖에서 스크립트 실행.

* 해결: 터미널에 (venv) 접두사가 있는지 확인 후 스크립트 실행.

문제 5: PowerShell 인코딩 문제(글자 깨짐)

* 원인: 터미널 인코딩 불일치.

* 해결: PowerShell에서 $OutputEncoding = [System.Text.Encoding]::UTF8 실행 후 스크립트.

주요 요약

Ollama와 LiteLLM으로 로컬 LLM 배포 시 API 비용과 인터넷 의존성을 피하고 프로세스 완전 제어.
Ollama는 로컬 모델 런타임, LiteLLM은 Python에서 API 통합.
첫 단계는 Ollama 설치와 qwen2.5:3b 같은 적합한 모델 다운로드.
Python 스크립트는 litellm.completion으로 요청 전송, MODEL은 ollama_chat/로 로컬 모델 지정, API_BASE로 Ollama 주소.
LLM 요청은 role과 content을 가진 메시지 목록으로 전달되어 대화 시스템 기반 형성.