프로젝트 소개

llama-swap은 하나의 머신에서 여러 생성형 AI 모델을 실행하고 필요에 따라 전환하기 위한 프록시입니다. OpenAI 또는 Anthropic API 호환 추론 서버 앞에 위치하여 각 수신 요청에서 `model` 필드를 읽고, 해당 모델을 제공하는 데 필요한 업스트림 서버를 시작하거나 교체합니다. 이 프로젝트는 Go로 작성되었으며 하나의 바이너리와 하나의 구성 파일로 제공되고 외부 의존성이 없다고 명시되어 있습니다. 지원되는 업스트림에는 llama.cpp 및 그 포크, vllm, stable-diffusion.cpp, whisper.cpp, audio.cpp, ComfyUI가 포함됩니다. 프록시가 특정 엔진에 종속되지 않고 프로토콜 수준에서 작동하므로 README에서는 추론 서버를 독립적으로 업그레이드할 수 있다고 언급합니다. API 표면 - OpenAI 스타일 엔드포인트: `v1/completions`, `v1/chat/completions`, `v1/responses`, `v1/embeddings`, `v1/models`, `v1/audio/speech`, `v1/audio/transcriptions`, `v1/audio/voices`, `v1/images/generations`, `v1/images/edits`. - Anthropic 스타일 엔드포인트: `v1/messages`, `v1/messages/count_tokens`. - llama-server 추가 기능: `v1/rerank`, `v1/reranking`, `/rerank`, `/infill`, `/completion`, `/models`, `/props`. - stable-diffusion.cpp 서버의 SDAPI 엔드포인트, audio.cpp 작업 엔드포인트, `/comfyui/` 사용자 지정 엔드포인트. - 관리 엔드포인트: `/ui`, `/upstream/:model_id`, `/running`, `POST /api/models/unload`(모든 모델), `POST /api/models/unload/:model_id`, `/api/profiles`를 통한 프로필 나열 및 활성화, `/health`, Prometheus 시스템 및 GPU 메트릭용 `/metrics`. - 로그 엔드포인트: 버퍼링된 일반 텍스트 로그용 `/logs`, 실시간 스트리밍용 `/logs/stream`, 그리고 `/logs/stream/proxy`, `/logs/stream/upstream`, `/logs/stream/{model_id}` 변형이 있으며 `?no-history`는 새 줄만 스트리밍합니다. 구성 및 기능 최소 구성은 `models` 맵을 선언하며 각 항목에는 ID와 `cmd`가 있고 `${PORT}`는 자동으로 할당된 포트로 대체됩니다. 선택적 설정에는 비활성 후 자동 언로드를 위한 `ttl`, `unloadTimeout`, 익숙한 모델 이름을 위한 `aliases`, `env` 변수, 우아한 Docker/Podman 종료를 위한 `cmdStop`, `useModelName`, 요청 `filters`(`stripParams`, `setParams`, `setParamsByID`), 시작 시 사전 로드를 위한 `hooks`, `macros`, 사용자 지정 스왑 로직으로 동시 모델을 실행하기 위한 `matrix` DSL이 포함됩니다. API 키를 정의하여 엔드포인트 접근을 제한할 수 있으며, 프로필을 사용하면 런타임에 모델 ID 라우팅을 전환할 수 있습니다. 번들 웹 UI는 플레이그라운드, 토큰 메트릭, 요청/응답 검사, 수동 모델 로드 및 언로드, 실시간 로그 스트리밍을 제공합니다. Help 페이지는 로컬 도구 지원 모델을 llama-swap 자체 문서에 대해 실행하며, 동일한 도구가 `/api/mcp`에서 MCP 엔드포인트로 노출됩니다. 설치 나열된 옵션은 Docker, Homebrew, MacPorts, WinGet, 릴리스 바이너리(Linux, macOS, Windows, FreeBSD), Go와 Node.js를 사용한 소스 빌드입니다. Nightly Docker 이미지는 두 가지 계열로 제공됩니다. llama-server, ik-llama-server, stable-diffusion.cpp, whisper.cpp, audio.cpp, llama-swap을 번들로 포함하는 통합 이미지(CUDA 12, CUDA 13, Vulkan 변형, 권장)와 llama.cpp 자체 `llama-server` 컨테이너를 기반으로 하는 레거시 이미지입니다. 통합 이미지는 명령줄 플래그에 매핑되는 `LLAMA_SWAP_*` 환경 변수를 통해 구성할 수 있습니다. 운영 참고 사항 README에서는 nginx 뒤에 llama-swap을 배치할 때 응답 버퍼링을 비활성화할 것을 권장합니다. 버퍼링은 SSE와 스트리밍 채팅 완성을 깨뜨리기 때문입니다. llama-swap은 SSE 응답에 `X-Accel-Buffering: no`도 설정합니다. vllm 또는 tabbyAPI와 같은 Python 기반 서버의 경우 환경 격리와 올바른 `SIGTERM` 처리를 위해 Podman 또는 Docker에서 실행하는 것이 권장됩니다.