같은 기능인데 프런트엔드에서 네 개의 모델을 호출해야 합니다. GPT-4o는 폴백을 담당하고, DeepSeek는 주력 추론을 돌리고, Qwen은 중국어 장문을 처리하고, Doubao는 고객센터 화법을 맡습니다. 네 개의 SDK, 네 가지 인증 방식, 네 벌의 문서. 출시 첫 주에 이 차이점들을 맞추는 데만 이틀 치 인력이 소모됐습니다.
과장이 아닙니다. 저희가 집계해 보니, 네 개 모델을 연동한 뒤 비즈니스 코드에서 모델 호출과 관련된 부분이 거의 세 배로 불어났습니다. 모델을 바꿀 때마다 호출 방식, 파싱 로직, 오류 처리를 다시 고쳐야 했습니다. 더 골치 아픈 건, 벤더가 SDK를 업그레이드할 때마다 다시 테스트해야 한다는 점입니다. 이 글은 저희가 겪은 시행착오와 최종적으로 정착시킨 게이트웨이 방안을 정리한 것으로, 여러 모델 사이에서 고민하는 팀에 도움이 되길 바랍니다.
1. 인증: 네 가지 체계, 네 가지 방식
가장 먼저 부딪힌 건 인증입니다. OpenAI 계열은 Bearer Token을 쓰므로 요청 헤더에 Authorization: Bearer sk-xxx만 넣으면 됩니다. Qwen은 AccessKey 서명이 필요해서 매 요청마다 AK/SK로 HMAC을 계산하고 타임스탬프와 랜덤 문자열을 붙여야 합니다. Doubao는 AK/SK에 타임스탬프를 더하지만 서명 알고리즘이 Qwen과 또 다릅니다. DeepSeek는 OpenAI 형식을 호환하지만 자체 base_url과 모델명 매핑이 있고, 초기화 방식도 공식 SDK와 완전히 일치하지는 않습니다.
결과적으로 코드 곳곳에 if-else가 넘칩니다. 벤더마다 client 인스턴스 하나, 인스턴스마다 설정 한 벌. 키 관리가 더 골치입니다. 네 벤더의 Key가 네 곳에 저장되어 있고, 교체할 때 네 곳을 고쳐야 하며, 하나만 빠뜨려도 운영 사고가 납니다.
그래서 저희는 연동 계층에서 통일했습니다. 외부에는 API Key 하나만 노출하고, 내부에서 프로토콜 변환을 합니다. 구체적으로는 연동 계층이 벤더 라우팅 테이블을 유지하고, 각 벤더에 대응하는 인증 어댑터를 둡니다. 비즈니스 측은 Key 하나만 받아 요청을 연동 계층으로 보내고, 연동 계층은 모델명으로 해당 벤더를 찾아 어댑터로 서명과 포워딩을 완료합니다.
저희는 나중에 base_url을 token8341로 통일해서 시험해 봤는데, Key 하나로 GPT-4o, Claude, Gemini, DeepSeek, Qwen, ERNIE, Doubao를 호출할 수 있고, OpenAI SDK와 호환되어 base_url 한 줄만 바꾸면 전환됩니다. 인증의 번거로운 작업은 연동 계층 밖으로 차단되어 비즈니스 코드가 상당히 깔끔해졌습니다. 키 교체도 한 곳에서의 작업이 되어 운영 비용이 한 자릿수 수준으로 줄었습니다.
2. SSE 스트리밍 청크: 네 가지 형식, 하나의 렌더링
SSE 스트리밍 청크는 두 번째 함정이며, 인증보다 더 은밀합니다. GPT-4o의 chunk에서 delta.content는 null일 수 있는데, 특히 첫 chunk와 마지막 chunk에서 그렇습니다. 프런트엔드가 null 검사 없이 바로 렌더링하면 undefined가 깜빡입니다. DeepSeek는 마지막 chunk에 usage를 포함하는데, 그 usage 필드 구조가 OpenAI와 완전히 같지는 않습니다. Qwen은 event 타입이 더 세분화되어 add, finish, error 등 여러 이벤트 타입이 있고, 각 이벤트의 payload 구조가 다릅니다. Doubao의 종료 마커는 또 달라서, 특수한 finish_reason 필드로 스트림 종료를 표시합니다.
프런트엔드가 네 가지 형식을 받으니 렌더링 로직이 그대로 깨졌습니다. 처음에는 프런트엔드에서 어댑팅하는 방안으로 파서 함수 네 개를 작성했는데, 결국 새 모델을 추가할 때마다 프런트엔드를 고쳐야 했습니다. 그래서 게이트웨이 계층에서 정규화하도록 바꿨습니다. OpenAI의 chunk 구조로 통일하고, 빈 delta는 바로 필터링하고, usage는 따로 추출해 누적합니다. 구체적인 규칙은 이렇습니다. 모든 벤더의 스트리밍 응답을 data: {"choices":[{"delta":{"content":"..."}}]} 형식으로 변환하고, 종료는 data: [DONE]으로 통일하며, usage는 마지막 chunk에 OpenAI 형식으로 반환합니다.
프런트엔드는 한 가지 형식만 인식하면 되고, 백엔드가 누구와 연결되는지 신경 쓸 필요가 없습니다. 이 변경으로 프런트엔드의 모델 관련 코드가 400여 줄에서 80줄 정도로 줄었고, 새 모델을 추가할 때 프런트엔드는 전혀 손댈 필요가 없습니다.
3. 오류 코드: HTTP 200 안에 숨은 오류
오류 코드의 혼란스러움은 예상을 뛰어넘습니다. 같은 속도 제한인데도 OpenAI는 429와 rate_limit_exceeded를 반환하고, Qwen은 code 필드가 있는 비즈니스 오류를 반환하며, Doubao는 오류를 아예 HTTP 200의 body에 넣어 버립니다. 상태 코드는 200인데 body에 error 필드가 있는 식입니다. DeepSeek는 대부분 OpenAI와 일치하지만 가끔 사용자 정의 오류 구조를 반환합니다.
모니터링 알림을 통일할 방법이 없습니다. "429면 알림"이라는 규칙을 쓸 수 없습니다. 어떤 벤더는 속도 제한 시 429를 반환하지 않기 때문입니다. HTTP 상태 코드만 볼 수도 없습니다. Doubao의 200이 오류일 수 있기 때문입니다.
저희는 연동 계층에 매핑 테이블을 만들어 각 벤더의 오류 코드를 내부 오류 체계로 수렴했습니다. 속도 제한, 타임아웃, 인증 실패, 콘텐츠 검수, 서비스 불가입니다. 구체적인 매핑 로직은 먼저 HTTP 상태 코드를 보고, 그다음 body의 error code를 보며, 둘을 결합해 판단합니다. 예를 들어 Doubao가 200을 반환했지만 body에 error가 있으면 error code로 매핑하고, Qwen이 400과 비즈니스 code를 반환하면 code로 매핑합니다. 알림 규칙은 한 벌만 작성하고, 조사할 때만 원본 오류 코드를 봅니다.
이 매핑 테이블은 60여 개 규칙을 유지하며 네 벤더의 흔한 오류 시나리오를 커버합니다. 출시 후 알림 정확도가 기존 60% 정도에서 95% 이상으로 올라갔고, 오탐은 거의 사라졌습니다.
4. 사용량 통계: 네 숫자가 맞지 않는다
사용량 통계는 기준이 달라 가장 놓치기 쉬우면서도, 재무 대사 때 반드시 드러납니다. GPT-4o의 token 집계는 system prompt를 포함하고, DeepSeek는 캐시 적중 token을 별도로 가격 책정하며, Qwen은 입력과 출력을 따로 계산하고, Doubao는 과금 단위가 또 다릅니다. 재무 대사 때 네 숫자가 맞지 않으면 각 모델의 실제 비용을 도저히 계산할 수 없습니다.
귀집 방안은 게이트웨이 계층에서 매 요청의 model, input_tokens, output_tokens, cache_hit를 기록하고, token 과금 기준으로 통일해 저장하는 것입니다. 구체적으로는 게이트웨이가 요청을 포워딩할 때 시작과 종료 시각을 기록하고, 응답에서 각 벤더의 usage 필드를 추출해 표준 형식으로 통일 변환합니다. 과금 단위가 다른 벤더는 게이트웨이 계층에서 한 번 환산해 전부 per-token 비용으로 환산합니다.
이렇게 하면 하위에서 누구와 연결되든 비용을 같은 테이블에서 비교할 수 있습니다. 저희는 나중에 이 테이블을 기반으로 비용 대시보드도 만들어, 모델별, 비즈니스 라인별, 일별 차원으로 나눠 볼 수 있게 했습니다. 한번은 특정 비즈니스 라인의 비용이 갑자기 40% 올라서 확인해 보니, 라우팅 정책이 대량의 요청을 GPT-4o로 보내고 있었고, 라우팅을 조정하자 비용이 즉시 내려갔습니다. 통일된 사용량 귀집이 없었다면 이런 문제는 발견할 수 없었을 것입니다.
5. 모델 게이트웨이의 4계층 아키텍처
모델 게이트웨이는 어느 계층을 담당해야 할까요? 제 구분은 네 계층입니다.
첫째 계층은 프로토콜 변환입니다. 각 벤더의 요청/응답 형식을 OpenAI 호환 인터페이스로 통일합니다. 이 계층은 비즈니스 코드가 유일하게 직접 접촉하는 계층으로, 표준 OpenAI 형식의 요청을 각 벤더 형식으로 변환하고 응답을 다시 변환합니다.
둘째 계층은 라우팅입니다. 작업 유형에 따라 모델을 고릅니다. 예를 들어 중국어 장문은 Qwen, 코드는 DeepSeek, 폴백은 GPT-4o입니다. 라우팅 정책은 설정화할 수 있어 작업 유형, 우선순위, 비용 등 여러 차원을 지원합니다. 저희는 폴백 로직도 추가했습니다. 주 모델이 타임아웃되거나 속도 제한되면 자동으로 폴백 모델로 전환합니다.
셋째 계층은 사용량 귀집입니다. 과금과 할당량을 통일합니다. 매 요청의 token 소모, 캐시 적중, 응답 시간을 이 계층에 기록하고, 외부에 통일된 사용량 조회 인터페이스를 제공합니다.
넷째 계층은 관측성입니다. 로그, 분산 추적, 오류 코드 수렴입니다. 모든 요청에 trace_id가 있어 입구에서 출구까지 전 구간을 추적할 수 있습니다. 오류 코드는 이 계층에서 통일 매핑하고, 알림 규칙도 이 계층에서만 설정합니다.
비즈니스 코드는 첫째 계층의 인터페이스만 호출하고, 뒤의 세 계층은 그것에 투명합니다. 이렇게 하면 모델을 바꿔도 비즈니스 코드를 고칠 필요가 없고, 모델을 추가해도, 라우팅 정책을 조정해도 비즈니스 코드를 고칠 필요가 없습니다. 비즈니스 팀은 "모델 하나를 호출하겠다"는 것만 신경 쓰면 되고, 나머지는 게이트웨이에 맡기면 됩니다.
6. 함정 회피 조언
비즈니스 코드에서 각 벤더의 SDK를 직접 import하지 마세요. 벤더가 인터페이스를 업그레이드하거나 모델을 바꾸면 변경 범위가 매우 커집니다. 어떤 팀은 비즈니스 코드에서 SDK를 직접 호출했다가, 나중에 모델을 바꿀 때 30여 개 파일을 고치고 일주일을 테스트한 뒤에야 출시한 사례를 봤습니다.
연동 계층에 이틀을 더 쓰면 나중에 2주를 아낍니다. 이 투자 대비 효과는 저희 쪽에서 실증된 것입니다. 게이트웨이 출시 후 새 모델을 추가할 때는 게이트웨이 계층에 어댑터 하나만 추가하면 되고, 비즈니스 코드는 전혀 손댈 필요 없이 반나절이면 연동과 테스트를 마칠 수 있습니다.
두 가지 작은 조언을 덧붙입니다. 첫째, 사용량 귀집을 최대한 일찍 하세요. 재무 대사 때 가서야 계산이 안 된다는 걸 발견하지 마세요. 둘째, 오류 코드 매핑 테이블을 지속적으로 유지하세요. 새 벤더를 연동할 때 가장 먼저 할 일은 오류 코드 매핑을 채우는 것입니다.
저자: 쑨하오란
발행일: 2026년 11월 9일