llmgate: YAML 설정 기반의 초경량 멀티 LLM 커넥터

섹션별 상세

llmgate는 LiteLLM과 같은 기존 도구의 무거운 의존성(약 200MB 이상)을 지양하고, 2MB 미만의 설치 크기와 최소한의 의존성으로 작동하도록 설계되었다. httpx와 pyyaml만을 사용하여 직접 HTTP 호출을 수행하므로 프록시 서버나 데이터베이스 로깅으로 인한 지연 시간이 거의 발생하지 않는다.

YAML 파일을 통해 smart, fast, cheap 등 다양한 프로필을 정의하고, 런타임에서 gate.switch() 메서드를 사용하여 즉시 프로바이더를 교체할 수 있는 유연성을 제공한다. 이를 통해 개발 환경에서는 로컬 모델을 사용하고 운영 환경에서는 고성능 클라우드 모델로 전환하는 작업이 간소화된다.

yaml

provider: anthropic
model: claude-sonnet-4-20250514
api_key: ${ANTHROPIC_API_KEY}
temperature: 0.7
max_tokens: 1024

llmgate.yaml 설정 파일 작성 예시

OpenAI, Anthropic, Gemini 등 21개의 주요 클라우드 프로바이더뿐만 아니라 Ollama, LM Studio와 같은 로컬 LLM 환경도 지원하며, 대부분의 프로바이더에서 스트리밍 출력이 가능하다. 스트리밍을 지원하지 않는 일부 프로바이더의 경우 전체 응답을 단일 청크로 반환하여 인터페이스 일관성을 유지한다.

python

from llmgate import LLMGate

gate = LLMGate()
response = gate.chat("Explain transformers in one sentence")
print(response.text)
print(response.tokens_used)

llmgate를 사용한 기본적인 채팅 호출 코드

환경 변수 보간(Interpolation) 기능을 지원하여 YAML 파일 내에서 ${ENV_VAR} 구문을 통해 API 키나 엔드포인트를 안전하게 관리할 수 있다. python-dotenv와 연동하여 .env 파일로부터 설정을 로드하는 방식도 지원하여 보안성을 높였다.

yaml

active_profile: smart
profiles:
  smart:
    provider: anthropic
    model: claude-sonnet-4-20250514
  fast:
    provider: groq
    model: llama-3.1-8b-instant

멀티 프로필 기능을 활용한 YAML 설정 구조

확장 가능한 구조를 채택하여 새로운 프로바이더 추가 시 BaseProvider를 상속받아 구현할 수 있으며, OpenAI 호환 API의 경우 기본 클래스를 재사용하여 최소한의 코드 수정으로 통합이 가능하다. 현재 v0.1 버전은 동기 방식만 지원하며 v0.2에서 Async 지원이 예정되어 있다.

용어 해설

야멜(YAML): — 데이터 직렬화에 사용되는 사람이 읽기 쉬운 텍스트 기반 형식이다. llmgate에서는 프로바이더 설정, 모델명, API 키 등을 구조화하여 관리하는 설정 파일 형식으로 사용된다.
보간법(Interpolation): — 문자열 내에 변수나 표현식을 삽입하여 실행 시점에 실제 값으로 치환하는 기법이다. YAML 설정 내에서 ${ENV_VAR} 구문을 통해 시스템 환경 변수를 안전하게 주입하는 데 활용된다.
OpenAI 호환성(OpenAI-compatible): — OpenAI의 API 규격과 동일한 엔드포인트 구조와 데이터 형식을 따르는 인터페이스이다. Groq, DeepSeek 등 많은 프로바이더가 이 규격을 채택하여 기존 OpenAI 클라이언트로도 호출이 가능하다.
의존성(Dependency): — 소프트웨어가 정상적으로 작동하기 위해 필요한 외부 라이브러리나 모듈이다. 의존성이 많아지면 설치 크기가 커지고 라이브러리 간 버전 충돌 가능성이 높아지는 '의존성 지옥' 문제가 발생할 수 있다.

기술

Python
httpx
PyYAML
OpenAI API
Anthropic API
Google Vertex AI
AWS Bedrock

활용 사례

경량 LLM 챗봇 개발
멀티 모델 벤치마킹 툴
로컬 및 클라우드 LLM 하이브리드 운영
의존성 제약이 엄격한 프로덕션 환경

언급된 리소스

GitHubllmgate GitHub Repository