Shimmy - 경량 로컬 AI 추론 서버

프로젝트 개요

Shimmy는 GGUF 모델에 OpenAI API 호환 엔드포인트를 제공하는 5.1MB 단일 바이너리 로컬 추론 서버입니다. 이는 "보이지 않는 인프라"로 설계되어 로컬 AI 개발을 마찰 없이 가능하게 합니다.

핵심 기능

🚀 초경량

• 바이너리 크기: 단 5.1MB (Ollama의 680MB 대비)
• 시작 시간: <100ms (Ollama의 5-10초 대비)
• 메모리 오버헤드: <50MB (Ollama의 200MB+ 대비)

🔧 제로 구성 실행

• 자동 포트 할당: 포트 충돌 방지
• 모델 자동 검색: 다양한 모델 소스 지원
  • Hugging Face 캐시: ~/.cache/huggingface/hub/
  • Ollama 모델: ~/.ollama/models/
  • 로컬 디렉토리: ./models/
  • 환경 변수: SHIMMY_BASE_GGUF=path/to/model.gguf

🎯 완벽한 호환성

• 100% OpenAI API 호환: 기존 도구 직접 교체 가능
• 즉시 사용 가능: VSCode, Cursor, Continue.dev 등 도구 수정 불필요
• 크로스 플랫폼 지원: Linux, macOS, Windows

기술 아키텍처

핵심 기술 스택

• 언어: Rust + Tokio (메모리 안전성, 비동기 성능)
• 추론 엔진: llama.cpp 백엔드 (산업 표준 GGUF 추론)
• API 설계: OpenAI 호환 (플러그 앤 플레이 교체)

지원 모델 형식

• GGUF 모델: 주요 지원 형식
• SafeTensors: 네이티브 지원, 로딩 속도 2배 향상
• LoRA 어댑터: 최고 수준 지원, 학습부터 프로덕션 API까지 단 30초

설치 및 사용

빠른 설치

방법 1: Cargo를 통한 설치

cargo install shimmy

방법 2: 사전 빌드된 바이너리 파일 다운로드 (Windows)

curl -L https://github.com/Michael-A-Kuykendall/shimmy/releases/latest/download/shimmy.exe

방법 3: macOS 설치

# 의존성 설치
brew install cmake rust
# shimmy 설치
cargo install shimmy

기본 사용

1. 모델 다운로드

# 호환 모델 다운로드
huggingface-cli download microsoft/Phi-3-mini-4k-instruct-gguf --local-dir ./models/
huggingface-cli download bartowski/Llama-3.2-1B-Instruct-GGUF --local-dir ./models/

2. 서버 시작

# 자동 포트 할당
shimmy serve

# 수동 포트 지정
shimmy serve --bind 127.0.0.1:11435

3. AI 도구 구성

VSCode 구성:

{
  "github.copilot.advanced": {
    "serverUrl": "http://localhost:11435"
  }
}

Continue.dev 구성:

{
  "models": [{
    "title": "Local Shimmy",
    "provider": "openai", 
    "model": "your-model-name",
    "apiBase": "http://localhost:11435/v1"
  }]
}

명령줄 도구

기본 명령

shimmy serve                        # 서버 시작 (자동 포트 할당)
shimmy serve --bind 127.0.0.1:8080 # 수동 포트 바인딩
shimmy list                         # 사용 가능한 모델 표시
shimmy discover                     # 모델 검색 새로 고침
shimmy generate --name X --prompt "Hi" # 생성 테스트
shimmy probe model-name             # 모델 로딩 검증

API 엔드포인트

핵심 엔드포인트

• GET /health - 상태 확인
• POST /v1/chat/completions - OpenAI 호환 채팅
• GET /v1/models - 사용 가능한 모델 나열
• POST /api/generate - Shimmy 네이티브 API
• GET /ws/generate - WebSocket 스트리밍

사용 예시

# API 테스트
curl -X POST http://localhost:11435/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

성능 비교

지표	Shimmy	Ollama	llama.cpp
바이너리 크기	5.1MB 🏆	680MB	89MB
시작 시간	<100ms 🏆	5-10s	1-2s
메모리 사용	50MB 🏆	200MB+	100MB
OpenAI API	100% 🏆	부분 지원	없음

장점

🔒 개인 정보 보호 우선

• 코드는 로컬 머신에 보관
• 데이터 유출 위험 없음
• 완전 오프라인 실행

💰 비용 효율성

• 토큰당 요금 없음
• 무제한 쿼리 횟수
• 한 번 설치로 영구 사용

⚡ 뛰어난 성능

• 로컬 추론, 1초 미만 응답
• 낮은 메모리 점유율
• 빠른 시작

🔄 유연한 배포

• 단일 바이너리 파일
• 외부 종속성 없음
• 크로스 플랫폼 호환

확장 기능

LoRA 어댑터 지원

Shimmy는 학습된 모델을 프로덕션 API에 빠르게 배포할 수 있는 최고 수준의 LoRA 어댑터 지원을 제공합니다.

# LoRA 어댑터 로드
shimmy serve --lora-adapter path/to/adapter

핫 모델 전환

서버 재시작 없이 런타임에 모델을 동적으로 전환하는 것을 지원합니다.

GPU 가속

• macOS: 자동 Metal GPU 가속
• 크로스 플랫폼: 다양한 GPU 백엔드 지원

커뮤니티 및 지원

커뮤니티 리소스

• 버그 보고: GitHub Issues
• 토론: GitHub Discussions
• 문서: docs/
• 후원: GitHub Sponsors

요약

Shimmy는 "적을수록 좋다"는 것을 증명하는 혁신적인 로컬 AI 추론 솔루션입니다. 극도로 가벼운 설계와 제로 구성 철학을 통해 Shimmy는 개발자에게 진정으로 "즉시 사용 가능한" 로컬 AI 인프라를 제공하며, 동시에 엔터프라이즈급 성능과 호환성을 유지합니다. AI 애플리케이션 개발자, 연구원 또는 개인 정보 보호에 민감한 사용자 등 누구에게나 Shimmy는 고려할 가치가 있는 훌륭한 선택입니다.