ollama/ollama-python

Ollama Python 라이브러리 – 빠른 개요

설명 – Ollama REST API를 감싸는 가벼운 Python 래퍼입니다. 몇 줄의 코드만으로 모든 Python 3.8+ 프로젝트에서 로컬 실행 또는 클라우드 호스팅 LLM을 호출할 수 있습니다.

중요성 – Ollama는 다양한 오픈 소스 LLM(예: Gemma, DeepSeek, Qwen)을 실행할 수 있는 자체 호스팅 모델 서버(및 클라우드 계층)를 제공합니다. 이 Python 패키지는 HTTP 요청의 번거로움을 제거하고 스트리밍, 비동기 호출 및 모델 관리를 대신 처리해 줍니다.

핵심 기능 (README 설명 기준)

기능	제공 내용
간편한 채팅 API	`ollama.chat(model, messages)`는 모델의 응답이 포함된 `ChatResponse` 객체를 반환합니다.
스트리밍 출력	`stream=True`를 전달하여 토큰이 도착하는 대로 동기(반복 가능) 또는 비동기(비동기 생성기) 방식으로 부분 응답을 받을 수 있습니다.
비동기 클라이언트	`AsyncClient`는 동기식 `Client`와 동일한 기능을 제공하며, `await`/`asyncio`를 사용하여 비차단 프로그램을 구현할 수 있습니다.
전체 모델 수명 주기	`list`, `show`, `create`, `copy`, `delete`, `pull`, `push` 및 `ps` (프로세스 상태)를 위한 도우미 함수를 제공합니다.
임베딩 지원	`ollama.embed`는 단일 문자열 또는 문자열 목록에 대한 벡터 임베딩을 반환합니다.
System One	의사결정 스타일 프롬프트(선택, 점수, 불리언)를 위한 구조화된 Q&A 엔드포인트 (`systemone`)를 지원합니다.
사용자 정의 HTTP 클라이언트	사용자 정의 `host`, `headers` 또는 모든 `httpx.Client` 옵션을 사용하여 `Client` 또는 `AsyncClient`를 인스턴스화할 수 있습니다.
클라우드 모델 액세스	호스트를 `https://ollama.com`으로 설정하고 API 키를 제공하면 Ollama의 호스팅 모델(예: `gpt-oss:120b-cloud`)에 대해 동일한 함수를 호출할 수 있습니다.

일반적인 사용 사례

LLM 기반 기능 프로토타이핑 – 스크립트, 웹 서비스 또는 노트북에 채팅, 생성 또는 임베딩 호출을 빠르게 추가합니다.
로컬/클라우드 하이브리드 워크플로우 – 로컬에서 소형 모델을 실행하여 빠르게 반복하고, 필요할 때 클라우드 호스팅 대형 모델로 전환합니다.
비동기 파이프라인 – AsyncClient를 사용하여 이벤트 루프를 차단하지 않고 비동기 웹 프레임워크(FastAPI, Starlette)에 LLM 호출을 통합합니다.
구조화된 의사결정 지원 – systemone 엔드포인트를 활용하여 간단한 분류, 점수 매기기 또는 객관식 작업을 수행합니다.
모델 관리 – Python 코드 내에서 모델을 자동으로 가져오기(pull), 푸시(push) 또는 삭제합니다.

시작하기 (README 기준)

# 패키지 설치
pip install ollama

# 동기식 채팅 예제
from ollama import chat

response = chat(
    model='gemma4',
    messages=[{'role': 'user', 'content': 'Why is the sky blue?'}]
)
print(response.message.content)   # → 모델의 답변

스트리밍 예제

stream = chat(model='gemma4', messages=[{'role': 'user', 'content': 'Why is the sky blue?'}], stream=True)
for chunk in stream:
    print(chunk.message.content, end='', flush=True)

비동기 사용

import asyncio
from ollama import AsyncClient

async def ask():
    resp = await AsyncClient().chat(model='gemma4', messages=[{'role': 'user', 'content': 'Why?'}])
    print(resp.message.content)

asyncio.run(ask())

클라우드 모델 액세스

ollama.com에서 API 키를 생성하고 내보냅니다:

export OLLAMA_API_KEY=your_api_key

클라이언트를 클라우드 호스트로 지정합니다:

from ollama import Client
client = Client(host='https://ollama.com', headers={'Authorization': f'Bearer {os.getenv("OLLAMA_API_KEY")}'})
for part in client.chat('gpt-oss:120b-cloud', messages=[{'role': 'user', 'content': 'Explain quantum entanglement.'}], stream=True):
    print(part.message.content, end='')

오류 처리

모든 요청 수준의 오류는 ollama.ResponseError를 발생시킵니다. 예외 객체는 다음을 노출합니다:

e.error – 서버에서 보낸 사람이 읽을 수 있는 메시지.
e.status_code – HTTP 상태 코드 (예: 모델이 없는 경우 404).

일반적인 패턴:

try:
    ollama.chat('nonexistent')
except ollama.ResponseError as e:
    print('Error:', e.error)
    if e.status_code == 404:
        ollama.pull('nonexistent')

추가 정보

API 참조 – 이 라이브러리는 공식 Ollama REST API(docs/api.md)를 그대로 반영합니다.
타입 정의 – 응답 객체의 정확한 구조는 ollama/_types.py를 참조하세요.
예제 – 저장소에는 구조화된 Q&A 엔드포인트를 보여주는 examples/systemone.py 스크립트가 포함되어 있습니다.

결론 – Ollama Python 라이브러리는 개발자가 관용적인 Python을 사용하여 로컬 및 클라우드 Ollama LLM과 상호 작용할 수 있도록 설계된 경량 클라이언트이며, 스트리밍, 비동기 처리, 임베딩 및 구조화된 프롬프트와 같은 고급 작업을 지원합니다.