llama-swap 딥다이브
— 단일 바이너리 로컬 AI 모델 스위칭 프록시

Go로 리버스 프록시 만들기

internal/process/process_command.go에서 httputil.ReverseProxy를 직접 구현하지 않고 Go 표준 HTTP 클라이언트로 요청을 포워딩하는 방식을 볼 수 있습니다. SSE(스트리밍) 응답을 어떻게 그대로 흘려보내는지도 배울 수 있습니다. 실무에서 가장 많이 쓰이는 프록시 패턴 중 하나입니다.

핵심 파일: internal/server/server.go, internal/process/process.go

외부 프로세스 수명주기 관리 (Process Lifecycle)

Go에서 외부 프로그램을 os/exec로 실행하고, 상태 머신(Stopped → Starting → Ready → Stopping → Shutdown)으로 관리하는 패턴을 배울 수 있습니다. SIGTERM 처리, 타임아웃 종료, 프로세스 트리 정리(Windows 포함)까지 실전 수준의 구현이 담겨 있습니다.

핵심 파일: internal/process/process_command.go, internal/process/runtime_unix.go

헬스체크 폴링 패턴

새 모델 서버를 시작한 뒤 준비될 때까지 /health를 주기적으로 GET 요청해서 확인하는 패턴입니다. 쿠버네티스의 readinessProbe와 같은 개념을 직접 구현한 것입니다. 타임아웃(기본 120초)과 폴링 간격 조절 로직도 함께 배울 수 있습니다.

매크로 치환 시스템 + DSL 설계

internal/config/macros.go에서 YAML 값 안의 ${PORT}, ${MODEL_ID}, ${env.HOME} 같은 플레이스홀더를 재귀적으로 치환하는 간단한 매크로 엔진을 볼 수 있습니다. Matrix 라우터의 sets 표현식 파서(internal/config/matrix_dsl.go)는 간단한 파서 구현의 좋은 예시입니다.

SSE(Server-Sent Events) 스트리밍 처리

LLM 응답은 토큰 단위로 스트리밍됩니다. internal/event/와 internal/server/log.go에서 Go의 http.Flusher 인터페이스를 활용해 SSE를 구현하는 방법을 배울 수 있습니다. nginx 설정에서 proxy_buffering off가 왜 필요한지도 이해하게 됩니다.

Homebrew로 설치하고 최소 설정 실행 난이도 ★☆☆ 입문

macOS 또는 Linux에서 Homebrew로 설치 후, 이미 설치된 llama-server를 하나 등록하는 최소 config.yaml을 작성해봅니다.

# 최소 config.yaml
models:
  my-llama:
    cmd: llama-server --port ${PORT} --model ~/models/llama-3.2-1B.gguf

이후 curl http://localhost:8080/v1/models로 모델 목록이 반환되는지, /health가 OK를 돌려주는지 확인합니다.

두 모델 교대 확인 — 실제 스왑 체험 난이도 ★☆☆ 입문

config.yaml에 모델 2개를 등록하고 curl로 각각 요청을 보내며 /running 엔드포인트와 로그를 봅니다.

# curl로 모델 A 요청 후 상태 확인
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"model-a","messages":[{"role":"user","content":"안녕"}]}'

# 실행 중 모델 목록 확인
curl http://localhost:8080/running

model-a 요청 → model-b 요청 → 다시 model-a 요청할 때 로그에서 "stopping" → "starting" 메시지가 번갈아 나타나는 것을 관찰합니다.

TTL 설정으로 자동 언로드 확인 난이도 ★★☆ 중급

config.yaml에 ttl: 30을 추가하고, 요청 후 30초 기다리면 모델이 자동으로 내려가는지 /running으로 확인합니다. globalTTL과 모델별 ttl의 우선순위도 실험해봅니다.

models:
  my-llama:
    cmd: llama-server --port ${PORT} --model ~/models/llama.gguf
    ttl: 30  # 30초 후 자동 종료

aliases로 GPT-4 이름 흉내내기 난이도 ★★☆ 중급

기존 ChatGPT 클라이언트 앱은 model: "gpt-4"로 고정 요청을 보냅니다. aliases를 활용하면 이 요청을 로컬 모델로 받아칠 수 있습니다.

models:
  local-llama:
    cmd: llama-server --port ${PORT} --model ~/models/llama.gguf
    aliases:
      - "gpt-4"
      - "gpt-4o"

설정 후 클라이언트 앱의 base URL만 http://localhost:8080으로 바꾸면 gpt-4 요청이 로컬 모델로 흐릅니다.

OpenRouter를 peer로 등록해 하이브리드 라우팅 난이도 ★★★ 고급

로컬 모델과 클라우드 모델을 같은 엔드포인트로 운용합니다. peers 섹션에 OpenRouter를 추가하고, 로컬에 없는 모델 ID를 요청하면 자동으로 클라우드로 넘어가는 것을 확인합니다. 요청 필터(setParams)로 클라우드 요청에 데이터 수집 거부 헤더를 자동 삽입하는 설정도 시도해봅니다.