AI 게이트웨이에서 채널 관리

「채널(Channel)」은 AI 게이트웨이에서 하나의 공급자 접속 지점에 대한 설정입니다. 즉, 특정 공급자의 주소, 실제 API Key, 사용 가능한 모델, 가격 책정 및 할당량 등의 정보를 저장합니다. 게이트웨이는 바로 이 채널들을 기반으로 애플리케이션에서 들어온 요청을 해당 공급자로 라우팅합니다. 이 문서에서는 채널을 추가, 설정, 테스트 및 관리하는 방법을 소개합니다.

사전 요구 사항

• ServBay가 설치되어 실행 중이어야 하며, ServBay 계정에 로그인되어 있어야 합니다(채널 추가 전 로그인 필요).
• 대상 공급자의 실제 API Key를 준비해야 합니다(Ollama / LM Studio와 같은 로컬 공급자는 입력하지 않아도 됩니다).
• AI 게이트웨이의 전체 아키텍처를 아직 파악하지 못했다면, 먼저 AI 게이트웨이 소개를 읽어보시기 바랍니다.

채널 추가

AI 게이트웨이 → 채널(Channels) 페이지로 이동하여 추가(Add) 를 클릭하면 마법사가 열립니다. 마법사는 세 단계로 구성됩니다.

1단계: 공급자 선택

공급자는 카테고리별로 그룹화되어 표시되며, 카드를 클릭하여 선택할 수 있습니다:

• 주류(Mainstream): OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, OpenRouter.
• 중국(China): DeepSeek, Qwen(통이치엔원), Zhipu GLM(즈푸 GLM), Kimi, Doubao·Volcano(더우바오·화산), ERNIE(원신이옌), Hunyuan(훈위안), MiniMax, 01.AI(링이완우), StepFun(제위에싱천).
• 로컬(Local): Ollama, LM Studio.
• 사용자 정의(Custom): OpenAI Compatible, Custom.

공급자를 선택하면 게이트웨이가 해당 공급자의 기본 Base URL을 자동으로 입력합니다.

이중 리전 전환

Qwen, Zhipu GLM, Kimi, Doubao·Volcano, Hunyuan, MiniMax, StepFun 등 중국 공급자는 중국 내와 글로벌 두 가지 엔드포인트를 동시에 제공합니다. 이러한 공급자를 선택하면 마법사에 「리전」 선택기(🇨🇳 중국 내 / 🌐 글로벌)가 나타나며, 전환하면 Base URL이 해당 리전 주소로 자동 업데이트됩니다.

2단계: 설정 입력

• 채널 이름(필수) — 목록에서 해당 채널을 식별하는 데 사용되며, 사용자 정의할 수 있습니다.
• Base URL(필수) — 공급자 API 주소. 대부분의 공급자는 자동으로 입력되어 있으며, Azure OpenAI와 Custom은 직접 입력해야 합니다.
• API Key(선택) — 공급자의 실제 키입니다. 비워두면 엔드포인트 도달 가능 여부만 테스트할 수 있고 키 유효성은 검증할 수 없습니다. 로컬 공급자(Ollama / LM Studio)는 일반적으로 입력하지 않아도 됩니다.
• 모델 — 두 가지 방식 중 하나를 선택합니다:
  • 자동 검색: 검색을 클릭하면 게이트웨이가 공급자의 모델 목록 API를 호출하여 사용 가능한 모델을 가져오며, 태그(chip) 방식으로 여러 개를 선택할 수 있습니다.
  • 수동 입력: 모델 이름을 직접 입력합니다. Azure 채널은 모델 이름이 아닌 **배포 이름(Deployment name)**을 입력해야 합니다.
• 우선순위 / 가중치 — 여러 채널이 동일한 모델을 서비스할 수 있을 때, 게이트웨이가 이를 기반으로 라우팅과 부하 분배를 결정합니다.

Azure OpenAI 주의

Azure 채널의 「모델」 필드에는 기본 모델 이름이 아닌 Azure 포털에서 생성한 **배포 이름(Deployment name)**을 입력해야 합니다. Base URL에도 Azure 리소스 엔드포인트를 입력해야 합니다.

3단계: 확인 및 제출

설정 요약을 확인한 후 제출합니다. 제출에 성공하면 새 채널이 채널 목록에 나타나며 실시간 상태가 표시됩니다.

기능 탐지 및 라우팅 전략

채널을 추가하면 게이트웨이는 해당 채널에 대해 **기능 탐지(capability probing)**를 수행합니다. 이는 AI 게이트웨이의 가장 핵심적인 지능형 라우팅 메커니즘입니다. 탐지 결과에 따라 Claude Code 등의 도구를 바로 사용할 수 있는지, 모델 매핑을 만들어야 하는지, 그리고 대상 모델을 어떻게 선택할지가 결정됩니다.

탐지의 두 가지 핵심 지표

게이트웨이는 각 채널에 대해 두 가지 핵심 사실을 탐지합니다(모두 삼상태: true / false / 미탐지):

탐지 항목	의미	true	false	미탐지
Claude 모델명 인식(accepts_claude_names)	채널이 claude-opus-* / claude-sonnet-* / claude-haiku-* 모델명을 원래대로 인식하는지 여부	직접 연결 가능, 매핑 불필요	인식하지 못함, claude-* 이름을 업스트림 실제 모델명으로 변환하는 매핑 필수	탐지가 실행되지 않았거나 실패, 결론을 내릴 수 없음
티어 구분(tier_aware)	업스트림이 opus / sonnet / haiku 티어별로 서로 다른 모델을 자체적으로 반환하는지 여부	업스트림이 이미 티어를 구분하므로 업스트림에 위임	티어 구분 없음(모든 티어에 동일한 모델 반환), 게이트웨이 매핑 필요	탐지할 수 없거나 탐지한 적 없음

왜 추측하지 않고 탐지하는가

공급자마다 동작 방식이 크게 다릅니다. OpenAI는 claude-* 모델명을 원래 인식하지 못하며, 일부 중계 공급자는 포워딩을 통해 인식합니다. 반면 코딩 요금제형 공급자(예: Claude Pro/Max 구독)는 구독에 바인딩된 특정 모델명만 인식할 수 있습니다. 게이트웨이는 채널 유형으로 추측하지 않고, 실제 탐지를 수행한 후 라우팅 전략을 결정합니다.

라우팅 판정: 다섯 가지 상태

AI Gateway → 접속 관리 → 클라이언트 페이지에서 Claude Code에 대해 「원클릭 인계」를 수행하면, 게이트웨이가 모든 후보 채널의 탐지 결과를 집계하여 하나의 라우팅 판정을 도출합니다:

후보 채널 상태	판정	의미
사용 가능한 후보 채널 없음(채널 없음 / 모두 비정상 / 가상 키 범위 내 채널 없음)	후보 채널 없음	채널을 먼저 추가하거나 복구해야 함
임의의 후보 채널의 탐지 값이 미탐지	미검사	먼저 탐지를 한 번 실행해야 하며, 검증되지 않은 상태에서 매핑을 만들 수 없음
모든 후보 채널이 claude 모델명을 인식	직접 연결	매핑을 만들지 않고 요청을 그대로 전달
모든 후보 채널이 claude 모델명을 인식하지 못함	매핑 필수	게이트웨이가 3개 티어 매핑을 만들어 claude-* 를 업스트림 실제 모델명으로 변환
후보 중 인식하는 것과 인식하지 못하는 것이 혼재	혼합	수동 결정 필요(인식하는 것은 직접, 인식하지 못하는 것은 매핑)

모델 매핑: claude-* 를 업스트림 실제 모델로 변환

판정이 「매핑 필수」일 때, 게이트웨이는 Claude Code를 위해 세 가지 티어를 각각 커버하는 세 개의 모델 매핑 규칙을 생성합니다:

Claude Code가 보내는 모델명	매핑 규칙(와일드카드)	매핑 대상
claude-opus-*	모든 opus 티어 요청 매칭	후보 채널의 플래그십 모델
claude-sonnet-*	모든 sonnet 티어 요청 매칭	후보 채널의 플래그십 모델 또는 표준 모델
claude-haiku-*	모든 haiku 티어 요청 매칭	후보 채널의 경량 모델

대상 모델 선택 규칙(우선순위에 따른 폴백):

1. 패밀리 프리셋: 후보 모델에 알려진 패밀리 키워드(예: glm)가 나타나면, 해당 패밀리의 플래그십 모델(예: glm-5.2)을 opus/sonnet 티어 대상으로, 해당 패밀리의 경량 모델(예: glm-4.7-flash)을 haiku 티어 대상으로 바로 선택합니다.
2. 키워드 매칭: 패밀리 프리셋이 없을 때 opus/sonnet은 후보 목록의 첫 번째 모델을, haiku는 후보 중 경량 키워드(flash / mini / lite / air / small / turbo / haiku)에 매칭되는 첫 번째 모델을 선택합니다.
3. 폴백: 여전히 매칭되지 않으면 세 티어 모두 후보 목록의 첫 번째 모델을 선택합니다.

haiku 티어 오설정은 대가가 가장 큽니다

Claude Code의 haiku 티어는 호출량이 가장 많습니다(매 대화의 경량 호출에 사용됨). 만약 플래그십 모델을 실수로 haiku 티어에 입력하면 청구서가 몇 배로 늘어날 수 있습니다. 게이트웨이의 키워드 매칭 표는 7가지 경량 접미사(flash / mini / lite / air / small / turbo / haiku)를 포함하여, 무거운 모델이 haiku 티어에 입력되지 않도록 보장합니다.

매핑 저장 메커니즘

인계를 확인한 후, 게이트웨이는 /admin/model-mappings API를 통해 매핑 레코드를 저장합니다. 각 매핑 레코드에는 다음이 포함됩니다:

• 소스 프로토콜(source_protocol): anthropic(Claude Code가 보내는 요청은 Anthropic 형식)
• 소스 모델 매칭(source_model_pattern): 와일드카드, 예: claude-opus-*
• 대상 프로토콜(target_protocol): openai(모두 OpenAI 형식으로 변환하여 업스트림에 전송)
• 대상 모델(target_model): 탐지로 선택된 구체적인 모델명

저장은 멱등합니다. 즉, 인계를 반복해도 중복 매핑이 생성되지 않으며, 저장 전에 기존 매핑 목록을 가져와 비교합니다.

런타임 라우팅 규칙: failover 와 다운그레이드

인계 단계에서 저장되는 정적 매핑 외에도, 게이트웨이는 **런타임 라우팅 규칙(routing rules)**을 지원하여 요청이 게이트웨이를 통과할 때 동적으로 결정합니다:

규칙 필드	역할
트리거 조건(condition_type)	언제 다운그레이드를 트리거할지, 예: 채널 할당량 소진(quota_exhausted)
비용 임계값(cost_threshold_usd)	선택 사항: 해당 채널의 누적 비용이 임계값을 초과할 때 트리거
동작(action_type)	트리거 후 수행할 작업, 예: 지정된 대체 채널로 전환(switch_to)
대상 채널(target_channel_id)	다운그레이드할 대체 채널
대상 모델(target_model)	선택 사항: 대체 채널로 다운그레이드할 때 동시에 모델 전환

여러 라우팅 규칙을 조합하면, 채널 A의 구독 할당량이 소진되었을 때 채널 B의 종량제 엔드포인트로 자동 전환하거나, 특정 채널의 24시간 비용이 한도를 초과할 때 더 저렴한 모델로 다운그레이드하는 등의 구성을 구현할 수 있습니다.

로드 밸런싱 및 우선순위

여러 정상 채널이 동일한 모델을 서비스할 수 있을 때, 게이트웨이는 다음 전략에 따라 선택합니다:

• 우선순위 모드(기본값): 우선순위가 가장 높은 채널만 선택하며, 동일 우선순위 채널에서는 게이트웨이가 내부 가중치에 따라 분배합니다.
• 라운드 로빈 모드(round_robin): 모든 정상 후보 채널 간에 요청을 번갈아 분배합니다.

우선순위는 채널 설정에서 지정하며(숫자가 클수록 우선순위가 높음), 가상 키의 allowed_channels는 선택 가능한 채널 범위를 제한합니다.

연결 테스트

채널 목록에서 개별 채널에 대해 연결 테스트를 실행할 수 있습니다. 테스트는 두 가지 차원으로 나뉩니다:

• 엔드포인트 도달 가능성(reachable) — Base URL에 연결할 수 있는지(네트워크와 주소가 올바른지) 확인합니다.
• 키 유효성(authenticated) — 실제로 공급자 API를 호출하여 API Key가 유효한지 검증합니다. API Key를 입력한 경우에만 검증됩니다.

테스트 결과에는 왕복 지연 시간(밀리초), 상태 배지, 오류 메시지가 표시됩니다.

TIP

추가 마법사에서 엔드포인트에 도달할 수 없으면 다음 단계로 진행할 수 없습니다. 하지만 엔드포인트에 도달할 수 있으나 키가 유효하지 않은 경우에는 경고만 표시되며 계속 진행할 수 있습니다(예: 나중에 키를 보완할 계획인 경우).

고급 설정

채널을 추가하거나 편집할 때 고급 설정을 펼칠 수 있으며, 비용 산정 및 할당량 제어에 사용됩니다:

• 가격 배율(Rate Multiplier) — 공급자의 공식 가격에 배율을 곱하여 실제 비용이나 재판매 가격 기준으로 산정할 수 있습니다. 기본값은 1.0입니다.
• 과금 구조 — 해당 채널의 과금 방식을 설명합니다. 예: 종량제(pay as you go), 구독(subscription), 패키지(package).
• 잔액 — 잔액 출처는 고정값, OSS 청구서 또는 수동 유지 중에서 선택할 수 있으며, OSS 청구서 선택 시 청구서 유형도 지정할 수 있습니다. 잔액과 업데이트 시간은 채널 상세 정보에서 읽기 전용으로 표시됩니다.
• 구독 만료 시간 — 구독 / 패키지형 채널은 만료 시간을 기록할 수 있습니다.
• 할당량 제한 — Token 수, 요청 수 또는 금액 기준으로 상한을 설정하고 주기(일간 / 주간 / 월간 / 사용자 지정)를 선택할 수 있습니다. 할당량이 소진되면 해당 채널은 자동으로 라우팅 대상에서 제외되며, 예상치 못한 초과 지출을 방지하는 안전장치입니다.

채널 편집 및 삭제

• 편집 — 채널 목록에서 채널을 열면 이름, Base URL, API Key, 모델 및 고급 설정을 수정할 수 있습니다.
• 삭제 — 채널을 삭제하면 해당 채널에 의존하는 가상 키가 더 이상 라우팅할 수 없으므로 신중하게 작업하시기 바랍니다.

상태

채널 목록과 개요 페이지는 각 채널의 상태(정상 / 성능 저하 / 사용 불가)를 실시간으로 표시하여, 무효화된 공급자 설정을 빠르게 발견하는 데 도움이 됩니다.

자주 묻는 질문(FAQ)

• Q: 채널 추가 시 로그인이 필요하다는 메시지가 표시되나요?
  • A: AI 게이트웨이는 ServBay의 부가 기능으로, 채널 / 키를 추가하기 전에 ServBay 계정에 로그인해야 합니다. 화면 안내에 따라 로그인하면 됩니다.
• Q: 채널 수가 한도에 도달했다는 메시지가 표시되나요?
  • A: 생성 가능한 채널 수는 계정 요금제와 관련이 있으며, 한도에 도달하면 사용하지 않는 채널을 삭제하거나 요금제를 업그레이드할 수 있습니다.
• Q: 모델 자동 검색이 목록을 가져오지 못하나요?
  • A: 먼저 Base URL이 올바른지, API Key가 유효한지(연결 테스트의 「키 유효성」으로 검증 가능) 확인하시기 바랍니다. 일부 공급자는 유효한 키가 있어야 모델 목록을 반환하며, 대신 모델 이름을 수동으로 입력할 수도 있습니다.
• Q: 로컬 Ollama / LM Studio를 연동하려면 Key를 입력해야 하나요?
  • A: 일반적으로 필요하지 않습니다. 해당 로컬 서비스가 시작되어 기본 포트(Ollama 11434, LM Studio 1234)를 수신하고 있는지만 확인하면 됩니다.

요약

채널은 AI 게이트웨이가 요청을 라우팅하는 기반입니다. 3단계 마법사를 통해 약 20개 공급자를 빠르게 연동할 수 있으며, 이중 리전 전환, 모델 자동 검색, 2차원 연결 테스트로 설정이 올바른지 확인한 후, 가격 책정과 할당량 등 고급 설정을 통해 비용을 세밀하게 관리할 수 있습니다. 채널을 설정한 후에는 가상 키를 생성하여 애플리케이션과 도구에서 사용할 수 있습니다.