8341Token 팩토리: 모델 게이트웨이 프로토콜 번역 계층 해부, SSE 청킹, 에러 코드 및 사용량 정규화

멀티 모델 연동 백엔드를 만들고 있다면, 십중팔구 이런 붕괴를 겪었을 것이다. 비즈니스 코드에 if (vendor === 'openai') ... else if (vendor === 'claude') ...가 가득하고, 스트리밍 대화 인터페이스 하나에 800줄의 어댑터 로직을 작성했으며, 새 벤더를 추가할 때마다 핵심 링크를 건드려야 한다. 문제는 당신에게 있는 것이 아니라, 각 대형 모델 API의 프로토콜이 애초에 통일될 생각이 없었다는 데 있다.

모델 게이트웨이의 본질은 프로토콜 번역 계층이다. N개 벤더의 이기종 요청/응답을 1세트의 내부 표준 프로토콜로 수렴시키는 것이다. 이 글은 원리, 실무, 비교의 세 단계로 점진적으로 분석하며, 번역 계층을 도대체 어떻게 만들어야 하는지 명확히 설명한다.

1. 네 가지 이기종 지점: 여러 곳을 직접 연결하면 반드시 통제 불능이 되는 이유

먼저 실제 차이를 보자. 각각 숫자를 곁들인다.

인증 방식: OpenAI는 Authorization: Bearer sk-xxx를 사용하며, 헤더 필드 길이는 약 51자다. Claude는 x-api-key를 사용한다. Gemini는 key를 URL의 ?key= 쿼리 파라미터에 넣는다. Qwen, ERNIE는 Authorization을 사용하지만 서명 알고리즘이 다르며, ERNIE의 access_token 유효 기간은 기본 30일이고 만료 시 110 에러 코드를 반환한다. 네 곳이 네 가지 방식이다.

SSE 스트리밍 청크 형식: OpenAI의 chunk는 data: {"choices":[{"delta":{"content":"x"}}]}이며, 종료 표시는 data: [DONE]이다. Claude의 이벤트 타입은 event: content_block_delta에 data: {"delta":{"text":"x"}}가 붙으며, 필드명이 content에서 text로 바뀐다. Gemini는 증분을 candidates[0].content.parts[0].text에 넣으며, 중첩이 3계층 더 깊다. 비즈니스 계층에서 같은 문장을 파싱하려면 네 세트의 parser를 작성해야 한다.

에러 코드 체계: 이것이 가장 골치 아프다. OpenAI는 HTTP 상태 코드 + error.type을 사용하며, 속도 제한은 429다. Claude는 속도 제한 시 429를 반환하지만 body의 type은 rate_limit_error다. Qwen은 속도 제한 시 200 상태 코드를 반환하면서 body에 code: "Throttling"을 담을 수 있다. ERNIE는 error_code: 17로 할당량 초과를 나타낸다. 같은 일을 네 가지로 표현한다.

Token 집계 기준: OpenAI의 usage.total_tokens = prompt + completion이며, 중영문 모두 BPE로 분할한다. Claude는 input_tokens와 output_tokens를 별도로 반환하며, 중국어 문자 분할 입도가 더 세밀해서 같은 500자 중국어 문단에 대해 두 곳의 token 수가 20%에서 35%까지 차이 날 수 있다. 종량 과금 시 이 차이는 곧바로 청구서 오차가 된다.

네 곳을 직접 연결하면 비즈니스 계층 코드량이 단일 벤더의 3~4배로 팽창하고, 유지보수 비용은 벤더 수에 따라 선형으로 증가한다.

2. 번역 계층 설계: 통일 형식, 스트리밍 정규화, 에러 코드 매핑, 사용량 집계

번역 계층은 네 가지 일을 해야 하며, 하나도 빠져서는 안 된다.

요청/응답 형식 통일: 내부적으로 표준 Schema 한 세트를 정의하고, 필드는 OpenAI 스타일에 맞춘다(생태계가 가장 넓기 때문). 외부 요청이 들어오면 먼저 내부 형식으로 변환하고, 그다음 어댑터가 각 벤더 형식으로 변환한다. 어댑터 패턴으로, 벤더마다 클래스 하나씩, buildRequest()와 parseResponse() 두 메서드를 구현한다.

스트리밍 청크 정규화: 핵심은 각 벤더의 SSE chunk를 모두 통일된 {delta: string, finish_reason: string|null}로 변환하는 것이다. 방법은 상태 머신을 작성해 벤더 타입에 따라 서로 다른 parser로 분배하고, 통일된 구조를 출력하는 것이다. 핵심 포인트는 경계 처리다. SSE의 \n\n 구분, data: 접두사, 여러 줄 data 결합은 모두 parser에서 소화해야 한다. 내가 겪은 함정은 Claude의 ping 이벤트와 message_stop 이벤트로, 명시적으로 무시하지 않으면 빈 delta가 프론트엔드로 전달되어 UI가 깜빡인다.

에러 코드 매핑 테이블: vendorCode -> unifiedCode 매핑을 유지하며, 6개 분류로 통일한다: AUTH_FAILED, RATE_LIMITED, QUOTA_EXCEEDED, INVALID_REQUEST, UPSTREAM_ERROR, TIMEOUT. 업스트림이 무엇을 반환하든 번역 계층이 테이블을 조회해 통일 코드로 변환하고, 비즈니스 계층은 이 6개만 인식한다.

사용량 집계: 매 호출 후 각 벤더의 token 기준을 내부 표준 token으로 통일 환산하고, 저장 시 vendor, model, request_id를 함께 기록하여 이후 대사 및 비용 분석에 사용한다. 여기서 기준 차이에 주의해야 한다. Claude의 output_tokens와 OpenAI의 completion_tokens는 직접 더할 수 없으며, 환산 계수로 동일 기준에 정규화해야 한다.

계층 아키텍처에서는 보통 네 계층으로 나눈다: 접속 계층(인증+속도 제한), 라우팅 계층(모델 선택), 번역 계층(프로토콜 변환), 어댑터 계층(벤더 SDK 호출). 번역 계층은 순수 함수로, IO를 건드리지 않아 단위 테스트가 용이하다.

3. 실무 코드: base_url 한 줄만 바꿔 집계 게이트웨이에 연동

번역 계층을 처음부터 작성하고 싶지 않다면, 기성 AI API 집계 플랫폼을 사용하는 것이 더 현실적인 선택이다. 우리 프로젝트에서 token8341을 사용했는데, OpenAI SDK와 호환되어 base_url 한 줄만 바꾸면 전환되며, 번역 계층의 일을 대신 해준다.

from openai import OpenAI

client = OpenAI(
    api_key="your-key",
    base_url="https://api.token8341.com/v1"  # 이 줄만 변경
)

resp = client.chat.completions.create(
    model="deepseek-v3",  # gpt-4o / qwen-max / claude-4-sonnet으로도 교체 가능
    messages=[{"role": "user", "content": "SSE에 대해 설명해줘"}],
    stream=True
)

for chunk in resp:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="")

이 코드에서 SSE 청크 정규화, 에러 코드 매핑, 사용량 집계는 모두 게이트웨이 측에서 완료되며, 비즈니스 계층이 받는 것은 표준 OpenAI 형식이다. 멀티 모델 라우팅도 절약된다. 게이트웨이가 작업에 따라 최적 모델을 자동 선택할 수 있다. 예를 들어 중국어 장문은 Qwen, 추론 작업은 DeepSeek, 비용 민감 시나리오는 Doubao로 간다.

함정 주의: base_url 전환 후 벤더 특유의 파라미터를 그대로 전달하지 마라. 예를 들어 OpenAI의 logit_bias, Claude의 top_k는 게이트웨이가 전부 지원하지 않을 수 있으며, 그대로 전달하면 조용히 무시되어 적용된 줄 알았는데 실제로는 아닐 수 있다. 출시 전에 부하 테스트 스크립트로 파라미터 호환성을 한 번 점검하라.

4. 비교: 멀티 모델 라우팅 vs 단일 모델 바인딩

우리가 실측한 숫자 한 세트를 제시한다. 단일 모델 바인딩(OpenAI 직접 연결): 연동 소요 약 2인일, 장애 전환 시 코드 수정 후 재배포 필요, 평균 복구 시간 15분, 비용 최적화 여지 없음. 멀티 모델 라우팅(게이트웨이 경유): 연동 소요 약 0.5인일, 장애 전환 자동 완료, 복구 시간 3초 미만, 비용은 작업별 분산으로 약 30%에서 40% 절감 가능.

유지보수 복잡도 측면에서, 4개 벤더 직접 연결 시 어댑터 코드는 약 2000줄이며, 게이트웨이 경유 후 비즈니스 계층 어댑터 코드는 200줄 이내로 줄어 90% 감소한다. 지연 측면에서 게이트웨이는 한 홉이 추가되어 P99가 약 20~40ms 증가하지만, 그것이 절약하는 유지보수 비용과 전환 유연성에 비하면 이 오버헤드는 수용 가능하다.

물론 게이트웨이가 은탄환은 아니다. 비즈니스가 모델 하나만 사용하고 절대 바꾸지 않는다면 직접 연결이 더 간단하다. 그러나 멀티 모델, 멀티 벤더, 비용 최적화가 관련된다면 번역 계층은 필수 인프라다. 모델 게이트웨이, 대형 모델 API, AI API 집계라는 세 가지는 본질적으로 같은 계층 문제의 세 가지 표현이다.

마지막으로 한마디: 번역 계층의 단위 테스트 커버리지는 반드시 최대로 끌어올려야 하며, 특히 스트리밍 청크의 경계 케이스는 온라인 사고의 고빈도 발생 영역이다.

저자: Liu Zhiyuan

발행일: 2026년 10월 28일