GPT, Claude, Gemini를 위한 하나의 base_url: 세 개의 SDK를 하나로 통합하기

코드베이스에 두 번째 LLM 제공업체를 추가할 때는 관리할 만하다고 느껴집니다. 하지만 세 번째가 되면 세 개의 SDK, 세 개의 인증 방식 (auth schemes), 세 가지의 약간씩 다른 messages 형태, 세 가지의 재시도 정책 (retry policies), 그리고 모델 지원 종료 (deprecation)가 발생했을 때 시스템을 망가뜨릴 수 있는 세 곳의 지점을 마주하게 됩니다. "각 작업에 가장 적합한 모델을 사용하라"는 조언은 옳지만, 통합 비용 (integration tax)은 실제로 존재하며 시간이 갈수록 복리로 쌓입니다.

제가 계속해서 되풀이하는 패턴은 다음과 같습니다: 모든 것을 하나의 OpenAI 호환 엔드포인트 (OpenAI-compatible endpoint) 뒤에 두고 세 개의 클라이언트를 유지 관리하는 일을 중단하십시오.

다중 SDK 접착제(glue)의 실제 비용

문제가 되는 것은 순탄한 경로가 아니라, 그 주변의 모든 것입니다:

• 인증 드리프트 (Auth drift). OpenAI는 Bearer 키를 원하고, Anthropic은 x-api-key와 버전 헤더를 원하며, Google은 자체적인 방식을 원합니다. 세 개의 비밀 키, 세 개의 교체 (rotation) 일정이 필요합니다.
• 응답 형태의 분산 (Response-shape divergence). choices[0].message.content 대 content 블록 배열 대 candidates[].content.parts[]. 응답을 읽는 모든 호출 지점(call site)에 제공업체별 분기 처리가 필요합니다.
• 스트리밍 차이 (Streaming differences). SSE 프레이밍과 이벤트 이름이 충분히 다르기 때문에 스트림 파서 (stream parser)에 switch 문이 늘어납니다.
• 실패 모드의 확산 (Failure-mode sprawl). 속도 제한 (Rate-limit) 코드, 타임아웃 동작, 에러 본문이 모두 다릅니다. 재시도/백오프 (retry/backoff) 로직이 제공업체마다 갈라집니다.

이 중 어려운 것은 하나도 없습니다. 하지만 이 모든 것이 _유지 관리 (maintenance)_이며, 이는 소규모 팀의 속도를 조용히 늦추는 종류의 작업입니다.

OpenAI 호환 심 (OpenAI-compatible shim)

대부분의 제공업체는 이미 생태계가 OpenAI 방식으로 표준화되어 있기 때문에, OpenAI Chat Completions 규약으로 정규화할 수 있습니다. 따라서 공식 OpenAI SDK의 base_url을 다른 곳으로 지정하기만 하면 됩니다:

from openai import OpenAI

client = OpenAI(
...

동일한 호출 지점, 동일한 응답 형태, 하나의 키. 기반 모델을 바꾸려면 문자열 하나만 변경하면 됩니다. 재시도 로직, 스트리밍 파서, 로깅 등 모든 것이 하나의 규약을 대상으로 단 한 번만 작성하면 됩니다.

실제로 얻는 이점

• 하나의 인증(auth)과 하나의 비밀키(secret)만 교체하면 됩니다. 세 개를 관리할 필요가 없습니다.
• 모든 호출 지점에서 **동일한 응답 형태 (response shape)**를 가집니다. 제공자(provider)별로 분기 처리를 할 필요가 없습니다.
• 종속(lock-in)이 없습니다. OpenAI 규약(사실상의 오픈 표준)을 기준으로 코드를 작성하기 때문에, 특정 제공자를 바꾸거나 게이트웨이 자체를 바꾸는 것은 재작성이 아닌 base_url 변경만으로 가능합니다. 이는 양방향으로 적용되며, 이것이 핵심입니다.

포기해야 하는 것 (솔직한 부분)

정규화 계층(normalization layer)은 공짜 점심이 될 수 없습니다:

• 제공자별 특화 기능이 평탄화(flattened)됩니다. Anthropic의 프롬프트 캐싱(prompt caching), Google의 그라운딩(grounding), OpenAI의 구조화된 출력(structured-output) 모드 등 공통 규약에 깔끔하게 매핑되지 않는 기능은 사용할 수 없거나, 어차피 별도로 처리해야 하는 비표준 필드를 통해 노출됩니다.
• 홉(hop)이 추가됩니다. 네트워크 세그먼트가 하나 더 늘어나고, 장애가 발생할 수 있는 요소가 하나 더 추가됩니다. 지연 시간(latency)에 민감한 경로라면 이를 측정하십시오.
• 심(shim)의 커버리지 공백을 상속받게 됩니다. 게이트웨이가 필요한 파라미터를 매핑하지 않았다면, 매핑될 때까지 작업이 차단됩니다. 매핑 방식이 투명하고 문서화되어 있는 것을 선택하십시오.

트레이드오프(trade-off)는 다음과 같습니다: 제공자별 특화 기능(long tail)에 대한 접근 권한을 잃는 대신, 통합 표면(integration surface)을 극적으로 줄이는 것입니다. 제공자 기능의 약 5% 정도만 사용하는 대부분의 앱 팀에게는 좋은 거래입니다. 하지만 특정 제공자의 독점 기능에 크게 의존하는 팀에게는 그렇지 않습니다.

요약 (Takeaway)

코드베이스의 모든 LLM 호출 지점에 제공자별 분기 로직이 늘어나고 있다면, 하나의 OpenAI 호환 base_url로 통합함으로써 제공자별 특화 기능이라는 비용을 지불하는 대신 유지보수의 한 카테고리를 통째로 제거할 수 있습니다. 저는 이를 Modelis(GPT/Claude/Gemini를 위한 하나의 키, 선택적 auto 라우팅, 무료 티어 제공)라는 작은 게이트웨이로 modelishub.com에서 구축해 두었지만, 이 심(shim) 패턴은 OpenAI와 호환되는 무엇이든 작동합니다. 여러분이 절대 포기할 수 없는 제공자별 기능이 무엇인지 궁금합니다. 그것이 보통 결정적인 요인이 될 것입니다.