Gemini · OpenAI 호환 API

로컬 LM Studio · Gemini · OpenAI · Anthropic — 전부 OpenAI 호환 인터페이스로 통일하면 단일 코드로 스위치.

1. OpenAI 호환 endpoint 란

POST /v1/chat/completions 요청/응답 스키마가 사실상 표준. LM Studio · Ollama · Gemini · Groq · Together 대부분 지원.

2. 단일 클라이언트 추상화

from openai import OpenAI

def make_client(provider: str):
    if provider == "lmstudio":
        return OpenAI(base_url="http://localhost:1234/v1", api_key="lm-studio")
    if provider == "gemini":
        return OpenAI(
            base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
            api_key=os.environ["GEMINI_API_KEY"],
        )
    if provider == "openai":
        return OpenAI(api_key=os.environ["OPENAI_API_KEY"])
    raise ValueError(provider)

client = make_client(os.environ.get("LLM_PROVIDER", "lmstudio"))

LLM_PROVIDER 환경변수로 배포 환경별 스위치.

3. 모델 이름 매핑

각 provider 의 model id 가 다릅니다.

provider	model (chat)	model (embedding)
LM Studio	`gemma-2-9b-it`	미지원 (별도 모델)
Gemini	`gemini-1.5-flash` · `gemini-2.0-flash-exp`	`models/text-embedding-004`
OpenAI	`gpt-4o-mini` · `gpt-4o`	`text-embedding-3-small`
Groq	`llama-3.1-70b-versatile`	미지원

MODEL_MAP = {
    "lmstudio": {"chat": "gemma-2-9b-it"},
    "gemini":   {"chat": "gemini-1.5-flash"},
    "openai":   {"chat": "gpt-4o-mini"},
}
model = MODEL_MAP[provider]["chat"]

4. 비용 · latency 비교 (2026 기준 대략치)

provider	입력 1M tok	출력 1M tok	p50 latency
Gemini 1.5 flash	$0.075	$0.30	500ms
GPT-4o mini	$0.15	$0.60	600ms
Claude Haiku	$0.25	$1.25	700ms
로컬 Gemma 9B (GPU)	$0	$0	100~300ms

로컬은 GPU 전기세 외 무료. 클라우드는 요청당 비용.

5. 스트리밍

stream = client.chat.completions.create(
    model=model, messages=[...], stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta: yield delta

FastAPI 의 StreamingResponse 와 조합해 실시간 UI.

6. 장애 대응 · fallback

async def chat_with_fallback(messages):
    for provider in ["lmstudio", "gemini", "openai"]:
        try:
            client = make_client(provider)
            return client.chat.completions.create(model=MODEL_MAP[provider]["chat"], messages=messages)
        except Exception as e:
            logger.warning(f"{provider} failed: {e}")
    raise RuntimeError("all providers failed")

1 차 로컬 → 2 차 Gemini (무료 quota) → 3 차 OpenAI (유료).

7. 자주 걸리는 자리

model 이름 오타 — 각 provider 스크립트에서 client.models.list() 로 확인
토큰 제한 초과 — provider 별 max_tokens 다름 (LM Studio 는 로드 시점 설정)
비동기 · 동기 혼용 — openai 패키지는 AsyncOpenAI 별도
API 키 누수 — 환경변수만, 코드 · 로그 노출 금지

하고픈 말

OpenAI 호환 인터페이스는 벤더 락인을 크게 줄입니다. LLM_PROVIDER 환경변수 하나로 로컬 개발 · 무료 quota · 유료 프로덕션을 자유롭게 전환.

06-prompt-design