ollama-advisor

컴퓨터 사양(RAM, GPU VRAM)과 용도(코딩/추론/비전/임베딩/오디오/일반)를 기반으로, 현재 환경에서 실행 가능한 Ollama 모델을 추천하고 다운로드·실행·중지까지 지원하는 Python 라이브러리입니다.

Mac, Windows, Linux, Google Colab에서 동작합니다.

설치

pip install ollama-advisor

개발(로컬) 설치:

git clone https://github.com/evanjung/ollama-advisor.git
cd ollama-advisor
pip install -e ".[dev]"

Quick Start

import ollama_advisor as oa

oa.recommend()                       # 전체 추천 (DataFrame 반환)
oa.recommend(purpose="coding")       # 코딩용만 필터링
oa.pull_model("qwen2.5-coder:7b")    # 모델 다운로드
oa.run_model("qwen2.5-coder:7b", prompt="hello")  # 비대화식 실행
oa.stop_model("qwen2.5-coder:7b")    # 실행 중지
oa.list_installed()                  # 로컬에 설치된 모델 목록

CLI:

ollama-advisor recommend --purpose coding
ollama-advisor pull qwen2.5-coder:7b
ollama-advisor run qwen2.5-coder:7b --prompt "hello"
ollama-advisor stop qwen2.5-coder:7b
ollama-advisor list
ollama-advisor ps
ollama-advisor specs

전제 조건: Ollama 설치

recommend()와 get_system_specs()는 Ollama 없이도 동작합니다.
pull_model, run_model, stop_model, list_installed 등은 로컬 Ollama 서버가 필요합니다.

• 다운로드: https://ollama.com/download
• macOS: brew install ollama 후 ollama serve (또는 앱 실행)
• Windows: 설치 프로그램 실행 후 트레이 앱 기동
• Linux: curl -fsSL https://ollama.com/install.sh | sh

Ollama가 꺼져 있으면 한국어 안내 메시지와 함께 OllamaError가 발생합니다.

Google Colab 제약

Colab에서는 Ollama가 공식적으로 백그라운드 서비스 지속 실행을 지원하지 않습니다. 임시로 아래처럼 실행할 수 있지만, 런타임 종료 시 모델과 서버 상태가 초기화됩니다.

!curl -fsSL https://ollama.ai/install.sh | sh
!nohup ollama serve > ollama.log 2>&1 &

노트북/Colab에서는 recommend() 호출 시 스크롤 가능한 HTML 테이블이 자동으로 표시됩니다.

동작 방식

메모리 추정식(4bit 양자화 근사): required_gb = billions × 0.6 + 1.0

개발 & 테스트

pip install -e ".[dev]"
pytest tests/ -v

CI(test.yml)는 Ubuntu / Windows / macOS × Python 3.9 / 3.11에서 실행되며, 네트워크 크롤링은 mock 처리합니다.

PyPI 배포 (메인테이너용)

1. PyPI 프로젝트 등록

1. pypi.org 계정 생성
2. 프로젝트 이름 ollama-advisor 사용 가능 여부 확인 (이미 사용 중이면 ollama-model-advisor 등 대체)
3. 빈 프로젝트를 웹에서 미리 생성하거나, 첫 Trusted Publisher 배포 시 자동 생성될 수 있음

2. Trusted Publisher (OIDC) 연결

1. PyPI → Account settings → Publishing → Add a new pending publisher
2. 설정:
   • PyPI project name: ollama-advisor
   • Owner: GitHub 사용자/조직
   • Repository name: ollama-advisor
   • Workflow name: publish.yml
   • Environment name: pypi (GitHub repo Settings → Environments에서 pypi 환경 생성 권장)
3. GitHub 저장소 Settings → Environments → pypi → Deployment protection rules 설정(선택)

API 토큰 없이 .github/workflows/publish.yml의 pypa/gh-action-pypi-publish가 OIDC로 배포합니다.

3. 릴리스 발행

git tag v0.1.0
git push origin v0.1.0

GitHub Releases에서 태그 v0.1.0으로 Release를 Publish하면:

1. publish.yml이 pytest 게이트 실행
2. 통과 시 PyPI에 wheel/sdist 업로드

로컬 수동 배포(비권장, 디버깅용):

python -m build
twine upload dist/*

라이선스

MIT — LICENSE