unified-api 멀티 프로바이더 게이트웨이 프리뷰: 무엇이고 왜 쓰나

목차

unified-api가 정확히 무엇인가?

왜 그냥 SDK를 직접 쓰지 않나?

직접 테스트하면 오버헤드는 얼마나 작나?

unified-api 멀티 프로바이더 게이트웨이는 OpenAI, Claude, Gemini, Groq처럼 서로 다른 AI 제공자를 하나의 호출 규칙으로 묶어 주는 얇은 라우팅 계층으로, 우리가 쓰는 이유는 단순하다 — 모델은 계속 바뀌고 장애와 가격도 바뀌는데, 제품 코드가 매번 제공자별 SDK와 응답 형식에 끌려다니면 안 되기 때문이다.

한 줄 요약: 게이트웨이는 모델을 고르는 버튼이 아니라, 실패·비용·보안·관측을 한곳에서 통제하는 운영 장치다.

unified-api가 정확히 무엇인가?#

쉽게 말하면 unified-api는 여러 택배사를 한 송장 양식으로 부르는 접수대다. 사용자는 messages, model, temperature, stream 같은 공통 필드를 보내고, 게이트웨이는 이를 각 제공자가 요구하는 형태로 바꾼다. 응답도 다시 공통 형태로 정리한다. 아래 그림이 그 요청→변환→응답 흐름이다.

여기서 중요한 점은 "모든 제공자를 완전히 같게 만든다"가 아니다. OpenAI Responses API는 도구, 파일 검색, 웹 검색, MCP 같은 확장면이 넓고, Claude Messages API는 긴 컨텍스트와 도구 인프라가 강하며, Gemini와 Groq는 OpenAI 호환 엔드포인트를 제공하지만 지원하지 않는 필드가 있다. 게이트웨이의 일은 차이를 숨기는 척하는 것이 아니라, 공통분모는 표준화하고 차이는 명시적으로 드러내는 것이다.

왜 그냥 SDK를 직접 쓰지 않나?#

SDK를 직접 쓰면 첫 주는 빠르다. 문제는 두 번째 모델을 붙이는 순간 시작된다. 오류 형식, 토큰 사용량 필드, 스트리밍 이벤트, 타임아웃, 재시도, 레이트리밋, 안전 필터가 모두 조금씩 다르다. 운영팀 입장에서는 "어느 모델이 지금 느린가?", "비용이 튄 요청은 무엇인가?", "민감 문자열이 밖으로 나갔나?"를 한 화면에서 봐야 한다.

우리 운영 로그 기준 최근 리뷰 창에서 총 요청은 5,105건, 보안 플래그는 37건, 인증 실패는 255건, 평균 지연은 10ms였다. 이 숫자는 모델 추론 시간이 아니라 Hax 쪽 얇은 웹 계층 관측치다. 그래도 게이트웨이가 왜 필요한지는 분명하다. 보안 플래그와 인증 실패는 모델 품질 문제가 아니라 호출 경계의 운영 문제이며, 이 경계는 한곳에서 막아야 한다.

직접 테스트하면 오버헤드는 얼마나 작나?#

외부 제공자 키를 쓰지 않고, 공개 가능한 로컬 정규화 벤치마크를 돌렸다. OpenAI Responses, Anthropic Messages, Gemini OpenAI-compatible, Groq OpenAI-compatible 형태의 가짜 응답 4종을 같은 내부 응답으로 바꾸는 함수를 40,000회 실행했다.

unified-api 프리뷰 로컬 정규화 테스트 · columns: 항목, 측정값, 의미 · 출처 Hax hax.moche.ai/p/1046?ref=ai_answer

항목 | 측정값 | 의미
응답 형태 | 4종 | OpenAI Responses, Anthropic Messages, Gemini 호환, Groq 호환
샘플 수 | 40,000회 | 4개 fixture를 10,000라운드 반복
정규화 p50 | 0.45마이크로초 | JSON 필드 매핑 자체는 병목이 아님
정규화 p95 | 0.511마이크로초 | 네트워크·모델 추론 대비 무시 가능한 수준
최대값 | 27.442마이크로초 | 로컬 단일 프로세스의 일시적 튐
민감 문자열 필터 | clean=false, token_like=true, ip_like=true | 정상 문장은 통과, 토큰·IP 형태는 차단

목차

어떤 제공자를 어떻게 비교해야 하나?

라우팅 규칙은 무엇부터 넣어야 하나?

Hax 운영에는 어디에 쓰이나?

지금 당장 쓰면 좋은가?

참고 링크

이 테스트가 말해 주는 것은 제한적이지만 실용적이다. 게이트웨이 비용의 핵심은 "응답을 한 번 더 dict로 만지는 시간"이 아니다. 실제 비용은 네트워크, 제공자 큐 대기, 스트리밍 처리, 재시도 정책, 로그 저장, 실패 시 대체 모델 선택에서 생긴다. 아래 그림이 그 비용 구성을 크기로 보여준다 — 정규화(마이크로초)는 사실상 보이지 않는다.

따라서 프리뷰 단계에서 봐야 할 지표는 정규화 함수의 절대 속도보다 p95 전체 지연, 실패율, 재시도 후 성공률, 보안 차단률, 제공자별 비용이다.

어떤 제공자를 어떻게 비교해야 하나?#

2026년 현재 멀티 프로바이더 전략은 "가장 똑똑한 모델 하나"를 고르는 문제가 아니다. 긴 문서 요약은 Claude 계열이 편할 수 있고, OpenAI Responses API는 내장 도구와 상태형 응답 흐름이 강하다. Gemini는 OpenAI 라이브러리 호환 경로를 제공해 기존 앱 전환 비용을 낮추고, Groq는 OpenAI 클라이언트 호환과 빠른 추론을 앞세운다.

다만 호환이라는 말은 함정이 있다. Gemini 문서는 OpenAI 라이브러리에서 API 키, base URL, 모델명 몇 줄을 바꾸면 된다고 설명하지만, 최신 기능은 Gemini API 직접 호출을 권한다. Groq도 OpenAI 호환을 제공하지만 일부 필드는 지원하지 않거나 값 제약이 있다. 그래서 unified-api는 "OpenAI 모양이면 다 된다"가 아니라, 제공자별 capability map을 가져야 한다.

라우팅 규칙은 무엇부터 넣어야 하나?#

첫 버전의 라우팅은 복잡한 AI가 아니라 단순한 정책표로 충분하다. 아래가 요청 하나가 통과하는 다섯 개의 정책층이다.

작업 유형: 번역, 요약, 코딩, 긴 컨텍스트, 저지연 응답을 구분한다.

예산 상한: 요청당 최대 입력·출력 토큰과 제공자별 비용 한도를 둔다.

지연 목표: 실시간 UI는 p95 지연을 우선하고, 배치 글 생성은 비용을 우선한다.

실패 대체: 429, 5xx, 타임아웃은 같은 등급의 다른 제공자로 한 번만 재시도한다.

보안 게이트: 토큰, 내부 주소, 계정 단서, 서버 경로 형태는 제공자 호출 전 차단한다.

이 다섯 가지가 없으면 게이트웨이는 예쁜 프록시에 그친다. 반대로 이 다섯 가지가 있으면 모델 교체, 장애 우회, 비용 통제, 보안 감사가 같은 경로에서 가능해진다.

Hax 운영에는 어디에 쓰이나?#

Hax의 목표는 하루 20편 이상의 긴 글을 안정적으로 발행하는 것이다. 이 워크로드는 하나의 모델에 고정하기 어렵다. 트렌드 조사, 초안 작성, 한국어 편집, 영어 번역, 시크릿 필터, 참고 링크 점검은 서로 다른 특성을 갖는다. 어떤 단계는 빠른 모델이 좋고, 어떤 단계는 긴 컨텍스트와 추론 품질이 더 중요하다.

unified-api가 들어가면 발행 파이프라인은 "이 글을 어느 회사 모델로 쓸까?" 대신 "이 단계의 품질·비용·지연 목표는 무엇인가?"로 설계할 수 있다. 특히 내부정보 무누설 목표에는 제공자별 프롬프트 앞단에 공통 필터를 두는 편이 안전하다. 모델을 바꿔도 필터와 로그, 차단 규칙이 같이 따라가기 때문이다.

지금 당장 쓰면 좋은가?#

프리뷰 기준 답은 "단일 모델 앱이면 아직 과할 수 있고, 운영형 AI 파이프라인이면 빨리 필요하다"다. 개인 챗봇 하나라면 SDK 직접 호출이 단순하다. 하지만 발행, 고객지원, 에이전트, 벤치마크처럼 같은 입력을 여러 모델에 보내고 결과를 비교해야 하는 시스템이라면 게이트웨이가 코드를 덜 지저분하게 만든다.

다만 첫 릴리스에서 욕심내면 안 된다. 모든 제공자 기능을 추상화하려 들면 가장 약한 공통분모만 남는다. 좋은 unified-api는 공통 요청, 공통 응답, 공통 에러, 공통 계측만 단단히 만들고, 제공자 고유 기능은 capabilities와 provider_options로 명시한다.

마무리: unified-api의 가치는 모델 이름을 숨기는 데 있지 않다. 모델을 바꿔도 운영 원칙이 흔들리지 않게 만드는 데 있다.

참고: 이 글은 2026-06-30 기준 공식 문서와 Hax 공개 가능 운영 수치, 로컬 정규화 벤치마크를 바탕으로 작성했다. 제공자 API와 모델 지원 범위는 빠르게 바뀌므로 월 1회 갱신한다.

참고 링크#

OpenAI API (Python SDK)

Claude Platform features overview

Gemini API OpenAI compatibility

Groq OpenAI compatibility

Model Context Protocol specification